Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,10 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
side panel has **Merge**, a find box where Enter merges the entity picked into it, and **Maybe the same**, its likely
doubles with **Merge** and **Not the same**. Renaming an entity to another's name offers to merge them. Merges, type
changes and hiding say what happened with **Undo** ([Entities](docs/processing.md#entities-and-the-graph-explorer)).
- **Edit and merge from the graph.** In the graph explorer, an entity's or topic's panel has **Edit**, which opens the
same editor as its own page, and an entity's has **Merge** and **Maybe the same**. The node menu has **Edit…** and
**Merge into another…**, which merges the node into the one clicked next (entities and speakers of one namespace;
entities of two namespaces are linked as the same thing), each with **Undo** ([The graph](docs/graph.md)).

## 0.9.0 <small>October 15, 2026</small> {id="0.9.0"}

Expand Down
31 changes: 31 additions & 0 deletions ci/clicks/journeys.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -661,6 +661,37 @@ export const JOURNEYS = [
await page.getByText("Merge undone").first().waitFor();
},
},
{
id: "graph-merge",
ns: "interviews",
module: "Graph",
feature: "Merge an entity into another from the graph, then undo it",
note: "Find the node, Merge in its panel, type the other's name and Enter; the notice has Undo, so nothing asks to confirm.",
from: "/",
async run(ctx) {
const { page, meter } = ctx;
await go(ctx, "Graph");
const find = page.getByRole("combobox", { name: "Find in graph" });
await page.getByRole("region", { name: "Graph" }).waitFor();
await page.waitForTimeout(1000);
// On a phone the filters, the find box among them, sit behind a button
if (!(await find.isVisible())) await meter.click(page.getByRole("button", { name: "Filters" }), "Filters");
await meter.type(find, "rasp", "part of the name");
await page.getByRole("option", { name: /Raspberry Pi/ }).first().waitFor();
await meter.press("Enter", "Enter to pick it");
const filters = page.getByRole("dialog", { name: "Graph filters" });
if (await filters.isVisible().catch(() => false))
await meter.click(filters.getByRole("button", { name: "Close" }), "close the filters (they stay open over the node)");
await page.getByRole("heading", { name: "Raspberry Pi" }).first().waitFor();
await meter.click(page.getByRole("button", { name: "Merge", exact: true }).first(), "Merge in its panel");
await meter.type(page.getByRole("combobox", { name: "Entity to merge into Raspberry Pi" }), "lens", "the other's name");
await page.getByRole("option", { name: /^Lens/ }).first().waitFor();
await meter.press("Enter", "Enter to merge it");
await page.getByText("Merged Lens into Raspberry Pi").first().waitFor();
await meter.click(page.getByRole("button", { name: "Undo" }), "Undo on the notice");
await page.getByText("Merge undone").first().waitFor();
},
},
{
// Last: it points Lens at a cloud model, which the stand-in model behind the journeys above isn't
id: "cloud-model",
Expand Down
8 changes: 8 additions & 0 deletions docs/graph.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,14 @@ to itself and has one. On a computer the Find in graph box has the focus, so typ
- **Node menu**: right-click a node (long-press on touch, or select it and press M) for its parents, children, all
ancestors, all descendants and neighbours, paths to another node (pick it next), a BFS, DFS or radial layout from
it, adding it to a route, its details and its page, or hiding it. What is found joins the canvas and lights up.
- **Edit and merge** (editors of the node's namespace): an entity's or topic's panel has **Edit**, which opens the
same editor as its own page (name, type, description, other names; a topic's labels, definition, broader and related
topics), and an entity's has **Merge**, a find box where Enter merges the entity picked into it, and **Maybe the
same**, its likely doubles. From the node menu, **Edit…** does the same and **Merge into another…** merges the node
into the one you pick next: entities of one namespace are merged, entities of two namespaces are linked as the same
thing, and speakers of one namespace are merged. Each happens at once with **Undo** on its notice. A node that joins
entities of several namespaces (all shared) offers **Edit in** each namespace. Looking at an earlier version, the
graph is read-only.
- **Route**: add stops from the node menu; the route follows the shortest path between each pair of stops, laid out
left to right.
- **Ask**: the bar at the bottom takes a question in plain words or Cypher (anything starting with `MATCH`). The
Expand Down
20 changes: 20 additions & 0 deletions nextjs-frontend/__tests__/entities-curate.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,26 @@ describe("merging into an entity", () => {
expect(m(Entities.undoEntityMerge).mock.calls[0][0].path).toEqual({ mid: 44 });
});

it("waits for the list of what was typed when Enter comes first", async () => {
const all = [
{ id: 2, name: "Matterbridge", type_label: "Term", mentions: 5 },
{ id: 3, name: "Lens", type_label: "Term", mentions: 2 },
];
m(Entities.listEntities).mockImplementation(({ query }: { query: { q?: string } }) =>
ok({ total: 2, items: query.q ? all.filter((e) => e.name.toLowerCase().includes(query.q!)) : all }),
);
m(Entities.mergeEntities).mockReturnValue(ok({ ok: true, merge: 45 }));
show(<MergeInto keep={{ id: 1, name: "Raspberry Pi" }} ns="pods" open onOpenChange={() => undefined} />);
const box = screen.getByRole("combobox", { name: "Entity to merge into Raspberry Pi" });
await waitFor(() => expect(screen.getAllByRole("option")).toHaveLength(2));
// typed and Enter at once: the unfiltered list (Matterbridge first) is still showing
fireEvent.change(box, { target: { value: "lens" } });
fireEvent.keyDown(box, { key: "Enter" });
await waitFor(() => expect(Entities.mergeEntities).toHaveBeenCalled());
expect(m(Entities.mergeEntities).mock.calls[0][0].body).toEqual({ keep: 1, others: [3] });
expect(Entities.mergeEntities).toHaveBeenCalledTimes(1);
});

it("offers the ones that may be the same, to merge or set apart", async () => {
m(Entities.listEntitySuggestions).mockReturnValue(
ok([
Expand Down
60 changes: 60 additions & 0 deletions nextjs-frontend/__tests__/graph-curate.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
import { joinKind, joinPlan } from "@/components/graph/join";
import type { GraphNode } from "@/components/graph/model";
import { editTarget } from "@/components/graph/panel";

jest.mock("@/app/openapi-client", () => ({ Entities: {}, Search: {}, Speakers: {}, Topics: {} }));
jest.mock("next-auth/react", () => ({ useSession: () => ({ data: { accessToken: "t" } }) }));

const node = (id: string, kind: GraphNode["kind"], refs: number[], ns: string[]): GraphNode => ({
id,
kind,
label: id,
ns,
weight: 1,
refs,
x: 0,
y: 0,
});

const acme = node("e1", "entity", [1], ["pods"]);
const acmeInc = node("e2", "entity", [2], ["pods"]);
const acmeCalls = node("e9", "entity", [9], ["calls"]);
const joined = node("e:acme", "entity", [1, 9], ["calls", "pods"]);
const alice = node("s3", "speaker", [3], ["pods"]);
const al = node("s4", "speaker", [4], ["pods"]);
const topic = node("t5", "topic", [5], ["pods"]);

describe("editing from the graph", () => {
const editorOf = (only: string) => (_role: "editor", ns: string) => ns === only;

it("opens an entity or topic of one namespace you edit", () => {
expect(editTarget(acme, editorOf("pods"))).toEqual({ kind: "entity", id: 1, ns: "pods" });
expect(editTarget(topic, editorOf("pods"))).toEqual({ kind: "topic", id: 5, ns: "pods" });
expect(editTarget(acmeCalls, editorOf("pods"))).toBeNull(); // a viewer there
expect(editTarget(joined, editorOf("pods"))).toBeNull(); // several namespaces: each opens on its own
expect(editTarget(alice, editorOf("pods"))).toBeNull(); // speakers have their own page
});
});

describe("merging on the canvas", () => {
it("joins entities and speakers of one namespace, nothing that spans several", () => {
expect([joinKind(acme), joinKind(alice), joinKind(joined), joinKind(topic), joinKind(null)]).toEqual([
"entity",
"speaker",
null,
null,
null,
]);
});

it("merges in a namespace, links across namespaces, and says why when it can't", () => {
expect(joinPlan(acmeInc, acme)).toBe("merge");
expect(joinPlan(acmeCalls, acme)).toBe("link");
expect(joinPlan(al, alice)).toBe("merge-speaker");
expect(joinPlan(acme, acme)).toBe("Pick another node to merge into.");
expect(joinPlan(acme, alice)).toBe("An entity merges into another entity.");
expect(joinPlan(alice, topic)).toBe("A speaker merges into another speaker.");
expect(joinPlan(alice, node("s8", "speaker", [8], ["calls"]))).toBe("Speakers are merged within one namespace.");
expect(joinPlan(acme, joined)).toBe("An entity merges into another entity.");
});
});
50 changes: 49 additions & 1 deletion nextjs-frontend/components/entities/curate.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,42 @@ export function useMergeEntities() {
return { merge, pending };
}

/** Say entities of two namespaces are the same thing (they stay two; the graph joins them), with Undo on the toast. */
export function useLinkEntities() {
const client = useApiClient();
const toast = useToast();
const refresh = useEntityRefresh();
return useCallback(
async (a: EntityPick, b: EntityPick): Promise<boolean> => {
try {
await data(Entities.linkEntity({ client, path: { eid: a.id }, body: { with: b.id } }));
refresh();
toast({
title: `Linked ${a.name} and ${b.name}`,
body: "They’re in different namespaces, so they stay two entities that the graph shows as the same thing.",
tone: "green",
duration: 10000,
action: {
label: "Undo",
onClick: () =>
void data(Entities.unlinkEntity({ client, path: { eid: a.id, other: b.id } }))
.then(() => {
refresh();
toast({ title: "Link undone", tone: "green" });
})
.catch((err) => toast({ title: "Couldn’t undo the link", body: why(err), tone: "red" })),
},
});
return true;
} catch (err) {
toast({ title: "Couldn’t link them", body: why(err), tone: "red" });
return false;
}
},
[client, refresh, toast],
);
}

type Found = { id: number; name: string; type_label?: string; mentions?: number; builtin?: string | null };

/** Find an entity of a namespace by typing: the most mentioned first, arrow keys move, Enter picks, Escape leaves. */
Expand Down Expand Up @@ -164,6 +200,14 @@ export function EntityFind({
onPick({ id: e.id, name: e.name });
setQ("");
};
// Enter before the list caught up with what was typed picks from the list for that text, not the one still showing
const [want, setWant] = useState(false);
const waiting = found.isFetching || debounced !== q.trim();
useEffect(() => {
if (!want || waiting) return;
setWant(false);
pick(items[active]);
});
return (
<div className="flex flex-col gap-1">
<div className="relative">
Expand All @@ -188,7 +232,11 @@ export function EntityFind({
setActive((a) => Math.max(0, a - 1));
} else if (e.key === "Enter") {
e.preventDefault();
pick(items[active]);
if (!waiting) pick(items[active]);
else {
setDebounced(q.trim());
setWant(true);
}
} else if (e.key === "Escape" && onCancel) {
e.preventDefault();
e.stopPropagation();
Expand Down
31 changes: 30 additions & 1 deletion nextjs-frontend/components/graph/explorer-ui.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,10 @@ import {
ArrowUpToLine,
EyeOff,
GitFork,
GitMerge,
Loader2,
Network,
Pencil,
Route,
RotateCcw,
Share2,
Expand All @@ -31,21 +33,28 @@ const ICONS: Record<Relation, typeof Network> = {
neighbours: Share2,
};

/** A node's menu (right-click, long press, or M on the keyboard), opened at a point on the canvas. */
/** A node's menu (right-click, long press, or M on the keyboard), opened at a point on the canvas. Editors also edit
* an entity or topic from it, and start merging an entity into another one picked next. */
export function NodeMenu({
node,
at,
ex,
byId,
onClose,
onSelect,
onEdit,
onMerge,
}: {
node: GraphNode | null;
at: { x: number; y: number } | null;
ex: Explorer;
byId: Map<string, GraphNode>;
onClose: () => void;
onSelect: (id: string) => void;
/** Open this node in its editor; absent when it can't be edited here. */
onEdit?: () => void;
/** Merge this node into the one picked next; absent when it can't be merged. */
onMerge?: () => void;
}) {
const start = ex.pathStart ? byId.get(ex.pathStart) : null;
const href = node ? nodeHref(node) : null;
Expand Down Expand Up @@ -98,6 +107,16 @@ export function NodeMenu({
Rings around this
</MenuItem>
<MenuSeparator />
{onEdit && (
<MenuItem icon={<Pencil />} onSelect={onEdit}>
Edit…
</MenuItem>
)}
{onMerge && (
<MenuItem icon={<GitMerge />} onSelect={onMerge}>
Merge into another…
</MenuItem>
)}
<MenuItem onSelect={() => onSelect(node.id)}>Show details</MenuItem>
{href && (
<MenuItem asChild>
Expand All @@ -122,6 +141,8 @@ export function ExplorerBar({
version,
asOf,
onNow,
mergeFrom,
onMergeCancel,
}: {
ex: Explorer;
byId: Map<string, GraphNode>;
Expand All @@ -130,6 +151,9 @@ export function ExplorerBar({
/** the version shown, when it isn't now */
asOf?: string | null;
onNow?: () => void;
/** the node being merged into the one picked next */
mergeFrom?: string | null;
onMergeCancel?: () => void;
}) {
const options = LAYOUTS.filter((l) => l.key !== "route" || ex.route.length > 1);
const label = (id: string) => byId.get(id)?.label ?? id;
Expand Down Expand Up @@ -191,6 +215,11 @@ export function ExplorerBar({
Paths from {label(ex.pathStart)}: now pick where to
</Chip>
)}
{mergeFrom && onMergeCancel && (
<Chip onClear={onMergeCancel} label="Cancel the merge">
Merge {label(mergeFrom)} into: now pick the one to keep
</Chip>
)}
{ex.route.length > 0 && (
<div className="pointer-events-auto flex max-w-full flex-wrap items-center gap-1.5 rounded-[10px] border border-blue-border bg-blue-surface px-2.5 py-1.5 text-[12.5px] text-fg">
<Route className="size-3.5 text-blue" aria-hidden />
Expand Down
Loading
Loading