@anchrd/intel 0.59.0

package/ui/src/node-editor/node-editor.tsx

@@ -0,0 +1,304 @@
+import { filterSuggestionItems } from "@blocknote/core";
+import { SuggestionMenuController, useCreateBlockNote } from "@blocknote/react";
+import {
+  BlockNoteDocument,
+  BlockNoteMediaType,
+  DocumentLinkInlineType,
+  type Node,
+  type NodeDocument,
+} from "@contract/node.ts";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { Link2 } from "lucide-react";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { ActionSlot } from "@/app/action-slot/action-slot.tsx";
+import { BlockNoteView, defaultSlashMenuItems } from "@/blocknote-view/blocknote-view.tsx";
+import type { IntelDataProvider } from "@/data/intel-data-provider/intel-data-provider.types.ts";
+import { DocumentLinkProvider, documentLinkIds } from "@/document-link/document-link.tsx";
+import { blocksToMarkdown, markdownToBlocks } from "@/document-markdown/document-markdown.ts";
+import {
+  type IntelEditor,
+  type IntelEditorPartialBlock,
+  intelEditorSchema,
+} from "@/editor-schema/editor-schema.ts";
+import { FrontmatterProvider } from "@/frontmatter/frontmatter.tsx";
+import type { I18n } from "@/i18n/i18n.types.ts";
+import { Modal } from "@/modal/modal.tsx";
+import { saveErrorKey } from "@/node-save-error.ts";
+import { SaveButton, UnsavedChangesGuard } from "@/save-button/save-button.tsx";
+import { TitleRowScrollArea } from "@/title-row/title-row.tsx";
+import { VerbatimProvider } from "@/verbatim/verbatim.tsx";
+
+function storedBlocks(content: string | null): IntelEditorPartialBlock[] | undefined {
+  if (!content) return undefined;
+  try {
+    const parsed = BlockNoteDocument.safeParse(JSON.parse(content));
+    return parsed.success ? (parsed.data.blocks as IntelEditorPartialBlock[]) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * What the editor holds, in a form two states can be compared by.
+ *
+ * ⚠️ This is what "unsaved" is answered with, and it deliberately is not "`onChange` fired". The
+ * editor changes for reasons that are not edits — loading the content is one (`replaceBlocks`
+ * below), and BlockNote normalizing a freshly mounted document is another. Neither is anything a
+ * reader did, and a warning that appears on every open is a warning nobody reads on the one day it
+ * is true. The canvas next door draws the same line with `editsNodes`/`editsEdges`.
+ *
+ * `id`s are part of it on purpose: BlockNote keeps them stable across edits within a session, and
+ * dropping them would call two different paragraphs equal whenever their text happens to match.
+ *
+ * ⚠️ It runs on every keystroke, and it walks the whole document to do so. That is affordable
+ * because `documentLinkIds` beside it already does, and because it is what buys the case a one-way
+ * flag cannot have: typing something and taking it back leaves nothing to save. There is no early
+ * exit — checking "already dirty, skip" is exactly what would lose that case. If documents ever
+ * grow far enough for this to be felt, the answer is to compare less often, not less carefully.
+ */
+function editorSnapshot(blocks: unknown): string {
+  return JSON.stringify(blocks);
+}
+
+export function NodeEditor({
+  data,
+  document,
+  i18n,
+  onSaved,
+}: {
+  data: IntelDataProvider;
+  document: NodeDocument;
+  i18n: I18n;
+  onSaved(document: NodeDocument): void;
+}) {
+  const initialBlocks = useMemo(() => storedBlocks(document.content), [document.content]);
+  // ⚠️ `initialContent` is always passed, never spread in conditionally: a conditional spread makes
+  // the options a union type, and BlockNote then infers the default schema instead of Intel's —
+  // which typechecks and then refuses to insert a document link at run time. One empty paragraph is
+  // what the editor would have started with anyway.
+  const editor = useCreateBlockNote({
+    schema: intelEditorSchema,
+    initialContent: initialBlocks?.length ? initialBlocks : [{ type: "paragraph" }],
+    // ⚠️ The one cast, in the one place. `useCreateBlockNote` decides its return type with a
+    // conditional that this repo's `exactOptionalPropertyTypes` defeats, so it hands back the
+    // default-schema editor even though it built Intel's. Same upstream seam as `BlockNoteView`.
+  }) as unknown as IntelEditor;
+  // The content as it stands on the server, in comparable form. Every question of "is there
+  // anything to save" is answered against this, and saving moves it forward.
+  //
+  // ⚠️ A ref, not state: it is read inside `onChange` on every keystroke and must be the current
+  // value there, not the one captured when that handler was created. Nothing renders from it — what
+  // renders is `dirty` — so there is nothing to re-render when it moves.
+  const savedSnapshot = useRef(editorSnapshot(editor.document));
+  const [dirty, setDirty] = useState(false);
+  const [picking, setPicking] = useState(false);
+  // Which documents the text links to right now. It is recomputed from the editor rather than from
+  // the saved content, so a link resolves the moment it is inserted instead of after a save.
+  const [linkedIds, setLinkedIds] = useState<string[]>(() => documentLinkIds(initialBlocks ?? []));
+  const resolved = useQuery({
+    // The key is the set of targets: two documents linking to the same thing share one answer, and
+    // adding a link asks only because the set changed.
+    queryKey: ["node-link-titles", [...linkedIds].sort()],
+    queryFn: () => data.resolveNodeLinks({ nodeIds: linkedIds }),
+    enabled: linkedIds.length > 0,
+  });
+  // One place decides whether there is anything to save, so the answer cannot differ between the
+  // button, the guard and the save itself.
+  function settle(): void {
+    setDirty(editorSnapshot(editor.document) !== savedSnapshot.current);
+  }
+
+  const save = useMutation({
+    mutationFn: async () => {
+      const blocks = editor.document;
+      const payload = BlockNoteDocument.parse({
+        format: "blocknote",
+        schemaVersion: 1,
+        blocks,
+        markdown: blocksToMarkdown(editor, blocks),
+      });
+      const node = await data.saveNode({
+        nodeId: document.node.id,
+        baseVersionId: document.version?.id ?? null,
+        content: JSON.stringify(payload),
+        mediaType: BlockNoteMediaType,
+        idempotencyKey: crypto.randomUUID(),
+      });
+      // ⚠️ An answer that carries no version did not save anything (#432). Letting it through would
+      // move `savedSnapshot` forward, drop the unsaved warning and leave the reader free to close
+      // the tab — over a document the server still reports as empty. It belongs on the error path,
+      // which is the one place the screen already says that the writing failed.
+      if (!node.version) throw new Error("save_without_version");
+      // ⚠️ The snapshot of what was SENT, not of what stands in the editor when the answer comes
+      // back. Saving crosses the network, and typing during it is normal — taking the state at
+      // arrival would call that typing saved and lose it at the next navigation.
+      return { node, snapshot: editorSnapshot(blocks) };
+    },
+    onSuccess: ({ node, snapshot }) => {
+      savedSnapshot.current = snapshot;
+      settle();
+      onSaved(node);
+    },
+  });
+
+  useEffect(() => {
+    if (!document.content || initialBlocks) return;
+    const blocks = markdownToBlocks(editor, document.content);
+    editor.replaceBlocks(editor.document, blocks);
+    // ⚠️ Loading the content IS a change to the editor, and `onChange` reports it as one. This is
+    // the line that keeps a document nobody has touched from asking to be saved: what was just
+    // loaded is by definition what is stored.
+    savedSnapshot.current = editorSnapshot(editor.document);
+    setDirty(false);
+  }, [document.content, editor, initialBlocks]);
+
+  function insertLink(nodeId: string): void {
+    editor.insertInlineContent([
+      { type: DocumentLinkInlineType, props: { nodeId } },
+      // A trailing space, or the caret stays inside an element that takes no text and the next
+      // keystroke has nowhere to go.
+      " ",
+    ]);
+    setPicking(false);
+    settle();
+    setLinkedIds(documentLinkIds(editor.document));
+  }
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      {/* ⚠️ Up into the title line, not a strip of its own (#24). The button used to cost a whole
+          screen row and a rule under it to say nothing most of the time. It is rendered from here
+          because this is where `dirty` lives — moving the state up to the screen would mean the
+          screen tracking every keystroke in an editor it does not own. */}
+      <ActionSlot name="title-actions">
+        <SaveButton dirty={dirty} saving={save.isPending} onSave={() => save.mutate()} />
+      </ActionSlot>
+      <UnsavedChangesGuard dirty={dirty} />
+      {save.isError && (
+        <p role="alert" className="mx-6 mt-4 text-sm text-destructive">
+          {i18n.t(saveErrorKey(save.error))}
+        </p>
+      )}
+      <TitleRowScrollArea className="min-h-0 flex-1 overflow-y-auto py-6">
+        <DocumentLinkProvider
+          value={{
+            titles: new Map((resolved.data?.items ?? []).map((item) => [item.nodeId, item.title])),
+            pending: linkedIds.length > 0 && resolved.isPending,
+            unresolvedLabel: i18n.t("node.link.unresolved"),
+          }}
+        >
+          <FrontmatterProvider
+            value={{
+              summary: i18n.t("node.frontmatter.summary"),
+              expand: i18n.t("node.frontmatter.toggle"),
+            }}
+          >
+            <VerbatimProvider value={i18n.t("node.verbatim.label")}>
+              <BlockNoteView
+                editor={editor}
+                onChange={() => {
+                  settle();
+                  setLinkedIds(documentLinkIds(editor.document));
+                }}
+              >
+                {/* The `/` line BlockNote already has, with one item added. A second way to reach the
+                same thing would be the second way #41 exists to remove. */}
+                <SuggestionMenuController
+                  triggerCharacter="/"
+                  getItems={async (query) =>
+                    filterSuggestionItems(
+                      [
+                        ...defaultSlashMenuItems(editor),
+                        {
+                          title: i18n.t("node.link.insert"),
+                          group: i18n.t("node.link.group"),
+                          icon: <Link2 aria-hidden="true" className="size-4" />,
+                          onItemClick: () => setPicking(true),
+                        },
+                      ],
+                      query,
+                    )
+                  }
+                />
+              </BlockNoteView>
+            </VerbatimProvider>
+          </FrontmatterProvider>
+        </DocumentLinkProvider>
+      </TitleRowScrollArea>
+      {picking ? (
+        <DocumentPicker
+          data={data}
+          i18n={i18n}
+          exclude={document.node.id}
+          close={() => setPicking(false)}
+          choose={insertLink}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * The documents the author may link to.
+ *
+ * ⚠️ The candidate list is the authorized graph — the same one the server would answer with — so
+ * the picker cannot offer a document the author may not see. The reader's side filters again, on
+ * its own account: the author seeing a title is not the reader seeing it (#41).
+ */
+function DocumentPicker({
+  data,
+  i18n,
+  exclude,
+  close,
+  choose,
+}: {
+  data: IntelDataProvider;
+  i18n: I18n;
+  exclude: string;
+  close(): void;
+  choose(nodeId: string): void;
+}) {
+  const [query, setQuery] = useState("");
+  const graph = useQuery({
+    queryKey: ["node-graph"],
+    queryFn: () => data.getNodeGraph(),
+  });
+  const candidates = (graph.data?.nodes ?? [])
+    .filter((node: Node) => node.id !== exclude && node.kind !== "folder")
+    .filter((node: Node) => node.title.toLowerCase().includes(query.trim().toLowerCase()))
+    .slice(0, 50);
+
+  return (
+    <Modal title={i18n.t("node.link.insert")} close={close}>
+      <label className="block text-sm font-medium">
+        {i18n.t("node.link.search")}
+        <input
+          // biome-ignore lint/a11y/noAutofocus: the dialog opens from a keystroke to take this term
+          autoFocus
+          value={query}
+          onChange={(event) => setQuery(event.target.value)}
+          className="mt-2 w-full rounded-md border bg-background px-3 py-2 outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        />
+      </label>
+      <ul className="mt-4 max-h-64 space-y-1 overflow-y-auto">
+        {graph.isPending ? (
+          <li className="text-sm text-muted-foreground">{i18n.t("common.loading")}</li>
+        ) : null}
+        {candidates.map((node: Node) => (
+          <li key={node.id}>
+            <button
+              type="button"
+              onClick={() => choose(node.id)}
+              className="w-full rounded-md px-3 py-2 text-left text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              {node.title}
+            </button>
+          </li>
+        ))}
+        {!graph.isPending && candidates.length === 0 ? (
+          <li className="text-sm text-muted-foreground">{i18n.t("node.link.noMatches")}</li>
+        ) : null}
+      </ul>
+    </Modal>
+  );
+}

package/ui/src/node-graph/graph-notice.tsx

@@ -0,0 +1,21 @@
+import type { RelationGraph } from "@contract/flow.ts";
+import type { I18n } from "@/i18n/i18n.types.ts";
+
+/**
+ * The one line above a graph, and it appears only when there is something to say (#88).
+ *
+ * ⚠️ It counted what was drawn directly below it — "3 nodes and 0 relationships you are allowed to
+ * see" — permanently, above every graph. Three nodes are three nodes; the reader sees them. What
+ * they cannot see is what the view stopped short of, and that is what stayed.
+ *
+ * Its own file so a case about this one line does not have to render the whole radial tree beside
+ * it — the two are meant to change for different reasons (#825).
+ */
+export function GraphNotice({ data, i18n }: { data: RelationGraph; i18n: I18n }) {
+  if (data.omitted === 0) return null;
+  return (
+    <p className="border-b px-6 py-3 text-sm text-muted-foreground">
+      {i18n.t("view.graphTruncated", { omitted: data.omitted, limit: data.limit })}
+    </p>
+  );
+}

package/ui/src/node-graph/node-graph.ts

@@ -0,0 +1,214 @@
+import type { RelationEdge, RelationGraph, RelationNode } from "@contract/flow.ts";
+
+// The radial tree's own geometry (#825), the same four rings the calculated draft used: they get
+// closer together further out because the circumference at that radius keeps growing, so the same
+// angular slice buys more room to draw in.
+const RING_RADIUS = [0, 130, 235, 320] as const;
+
+/**
+ * The last ring drawn as individual circles ("drei Ringe offen", #825): depth 0 to 2 are always
+ * their own node, icon and label. A node AT this depth is drawn too, but as a bundle once it has
+ * descendants — everything past it is rolled into that one marker rather than drawn at all.
+ */
+export const BUNDLE_DEPTH = 3;
+
+// One ring further out than the bundle ring, so a user's line always starts outside every node it
+// can point at, tree member or bundle alike.
+const USER_RADIUS = 448;
+// How far outside its own ring a node reached only by `reads`/`calls` sits (#825): far enough to
+// read as attached rather than filed, never mistaken for a member of the ring it borrows depth from.
+const SATELLITE_OFFSET = 46;
+
+const OUTERMOST_RING_RADIUS = RING_RADIUS[RING_RADIUS.length - 1] ?? 0;
+
+function radiusFor(depth: number): number {
+  return RING_RADIUS[Math.min(depth, RING_RADIUS.length - 1)] ?? OUTERMOST_RING_RADIUS;
+}
+
+export function polarPoint(radius: number, angle: number): { x: number; y: number } {
+  return { x: radius * Math.cos(angle), y: radius * Math.sin(angle) };
+}
+
+/**
+ * The one line the whole picture hangs on (#825's own ⚠️): a straight line from centre to centre
+ * turns 53 nodes into a starburst and the tree is gone. This draws the arc on the PARENT's own
+ * radius from the parent's angle to the child's, then a straight radial piece out to the child —
+ * so a fork in the tree reads as a fork, not as two lines that happen to start near each other.
+ */
+export function elbowPath(
+  parentRadius: number,
+  parentAngle: number,
+  childRadius: number,
+  childAngle: number,
+): string {
+  const arcStart = polarPoint(parentRadius, parentAngle);
+  const arcEnd = polarPoint(parentRadius, childAngle);
+  const lineEnd = polarPoint(childRadius, childAngle);
+  if (parentRadius === 0) {
+    // The centre has no arc to draw — every child starts at the same point, so the elbow is only
+    // ever the radial half.
+    return `M${arcStart.x},${arcStart.y} L${lineEnd.x},${lineEnd.y}`;
+  }
+  const delta = (((childAngle - parentAngle) % (Math.PI * 2)) + Math.PI * 2) % (Math.PI * 2);
+  const sweep = delta < Math.PI ? 1 : 0;
+  return (
+    `M${arcStart.x},${arcStart.y} ` +
+    `A${parentRadius},${parentRadius} 0 0,${sweep} ${arcEnd.x},${arcEnd.y} ` +
+    `L${lineEnd.x},${lineEnd.y}`
+  );
+}
+
+export interface PositionedNode {
+  node: RelationNode;
+  angle: number;
+  radius: number;
+  x: number;
+  y: number;
+  parent: PositionedNode | null;
+  /** Nodes rolled up into this one because they sit past the bundled ring (#825). Named, not hidden. */
+  bundled: number;
+}
+
+export interface PositionedUser {
+  id: string;
+  angle: number;
+  x: number;
+  y: number;
+}
+
+export interface RadialLayout {
+  /** Every node actually drawn as its own circle — a tree member up to the bundled ring, or a
+   * satellite reached only by `reads`/`calls`. A bundled descendant past `BUNDLE_DEPTH` is not here;
+   * it is counted on its ancestor's `bundled` instead. */
+  nodes: PositionedNode[];
+  users: PositionedUser[];
+  byId: Map<string, PositionedNode>;
+}
+
+// A stable order for children of one parent, so the same graph always draws the same picture
+// (#825: "dieselbe Eingabe, dasselbe Bild") regardless of what order the server happened to answer
+// its rows in.
+function byId(a: RelationNode, b: RelationNode): number {
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+
+/**
+ * The sunburst angle inheritance (#825): a node's sector is split among its children in proportion
+ * to how much each one carries — measured in nodes, not leaves, so a subfolder with one huge
+ * document and one with fifty small ones do not fight for the same sliver.
+ */
+function subtreeSize(id: string, childrenOf: Map<string, RelationNode[]>): number {
+  const children = childrenOf.get(id) ?? [];
+  return children.reduce((sum, child) => sum + 1 + subtreeSize(child.id, childrenOf), 0);
+}
+
+/**
+ * Turns the flat answer `flow_graph` gives into a picture: every tree member's ring and angle, every
+ * satellite's borrowed position, and the outer ring of users (#825).
+ *
+ * ⚠️ Only `inScope` members feed the sunburst split. A node reached solely through a `reads`/`calls`
+ * edge carries no coherent parent in this drawing (`node-graph.ts` on the API side sets `parentId`
+ * to `null` for exactly that reason) — it is positioned next to whichever flow reached it instead,
+ * so a dashed line still shows what connects it without inventing a membership arc for it.
+ */
+export function buildRadialLayout(data: RelationGraph): RadialLayout {
+  const treeMembers = data.nodes.filter((node) => node.inScope);
+  const satellites = data.nodes.filter((node) => !node.inScope);
+  const treeById = new Map(treeMembers.map((node) => [node.id, node]));
+
+  const childrenOf = new Map<string, RelationNode[]>();
+  const roots: RelationNode[] = [];
+  for (const node of treeMembers) {
+    if (node.parentId !== null && treeById.has(node.parentId)) {
+      const list = childrenOf.get(node.parentId) ?? [];
+      list.push(node);
+      childrenOf.set(node.parentId, list);
+    } else {
+      // No parent drawn alongside it: the real centre (depth 0), a top-level item when the whole
+      // tree is being shown, or — the one edge case — a tree member whose own folder was cut by the
+      // size limit. All three start a fresh sector rather than vanish.
+      roots.push(node);
+    }
+  }
+  for (const list of childrenOf.values()) list.sort(byId);
+  roots.sort(byId);
+
+  const positioned = new Map<string, PositionedNode>();
+
+  function place(node: RelationNode, angle: number, parent: PositionedNode | null): PositionedNode {
+    const radius = radiusFor(Math.min(node.depth, BUNDLE_DEPTH));
+    const { x, y } = polarPoint(radius, angle);
+    const entry: PositionedNode = { node, angle, radius, x, y, parent, bundled: 0 };
+    positioned.set(node.id, entry);
+    return entry;
+  }
+
+  function walk(node: RelationNode, a0: number, a1: number, parent: PositionedNode | null): void {
+    const mid = (a0 + a1) / 2;
+    const entry = place(node, mid, parent);
+    if (node.depth >= BUNDLE_DEPTH) {
+      // Past the open rings: everything beneath is counted on this node rather than drawn (#825).
+      entry.bundled = subtreeSize(node.id, childrenOf);
+      return;
+    }
+    const children = childrenOf.get(node.id) ?? [];
+    if (children.length === 0) return;
+    const total = children.reduce((sum, child) => sum + 1 + subtreeSize(child.id, childrenOf), 0);
+    let cursor = a0;
+    for (const child of children) {
+      const weight = (1 + subtreeSize(child.id, childrenOf)) / total;
+      const span = (a1 - a0) * weight;
+      walk(child, cursor, cursor + span, entry);
+      cursor += span;
+    }
+  }
+
+  // A real centre (a named folder or the flow being inspected) takes the whole circle for itself,
+  // exactly like the reference draft. Without one — the whole tree, `folderId: null` — the top-level
+  // items split the circle between themselves instead, as if a root stood there unseen (#825).
+  const singleRoot = roots.length === 1 && roots[0]?.depth === 0 ? roots[0] : null;
+  if (singleRoot) {
+    walk(singleRoot, -Math.PI / 2, (Math.PI * 3) / 2, null);
+  } else {
+    const total = roots.reduce((sum, root) => sum + 1 + subtreeSize(root.id, childrenOf), 0) || 1;
+    let cursor = -Math.PI / 2;
+    for (const root of roots) {
+      const weight = (1 + subtreeSize(root.id, childrenOf)) / total;
+      const span = Math.PI * 2 * weight;
+      walk(root, cursor, cursor + span, null);
+      cursor += span;
+    }
+  }
+
+  // Satellites borrow their referrer's angle. More than one from the same flow fan out a little so
+  // they do not sit on top of one another, in the stable order above.
+  const byReferrer = new Map<string, RelationNode[]>();
+  for (const edge of data.edges as RelationEdge[]) {
+    const target = satellites.find((node) => node.id === edge.target);
+    if (!target) continue;
+    const list = byReferrer.get(edge.source) ?? [];
+    if (!list.some((node) => node.id === target.id)) list.push(target);
+    byReferrer.set(edge.source, list);
+  }
+  for (const [referrerId, targets] of byReferrer) {
+    const referrer = positioned.get(referrerId);
+    if (!referrer) continue;
+    targets.sort(byId);
+    const spread = 0.16;
+    targets.forEach((node, index) => {
+      const offset = targets.length === 1 ? 0 : (index / (targets.length - 1) - 0.5) * spread;
+      const angle = referrer.angle + offset;
+      const radius = referrer.radius + SATELLITE_OFFSET;
+      const { x, y } = polarPoint(radius, angle);
+      positioned.set(node.id, { node, angle, radius, x, y, parent: null, bundled: 0 });
+    });
+  }
+
+  const users: PositionedUser[] = data.users.map((user, index) => {
+    const angle = -Math.PI / 2 + (index / Math.max(1, data.users.length)) * Math.PI * 2;
+    const { x, y } = polarPoint(USER_RADIUS, angle);
+    return { id: user.id, angle, x, y };
+  });
+
+  return { nodes: [...positioned.values()], users, byId: positioned };
+}