@anchrd/intel-ui 0.4.0 → 0.5.0

package/src/knowledge-editor/knowledge-editor.tsx

@@ -1,22 +1,34 @@
 import {
   BlockNoteDocument,
   BlockNoteMediaType,
+  DocumentLinkInlineType,
   type KnowledgeDocument,
+  type KnowledgeNode,
 } from "@anchrd/intel-contract";
-import type { PartialBlock } from "@blocknote/core";
-import { useCreateBlockNote } from "@blocknote/react";
-import { useMutation } from "@tanstack/react-query";
-import { Save } from "lucide-react";
+import { filterSuggestionItems } from "@blocknote/core";
+import { SuggestionMenuController, useCreateBlockNote } from "@blocknote/react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { Link2 } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
-import { BlockNoteView } from "@/blocknote-view/blocknote-view.tsx";
+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,
+  type IntelEditor,
+  type IntelEditorPartialBlock,
+  intelEditorSchema,
+} from "@/document-link/document-link.tsx";
 import type { I18n } from "@/i18n/i18n.types.ts";
+import { Modal } from "@/modal/modal.tsx";
+import { SaveButton, UnsavedChangesGuard } from "@/save-button/save-button.tsx";
 
-function storedBlocks(content: string | null): PartialBlock[] | undefined {
+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 PartialBlock[]) : undefined;
+    return parsed.success ? (parsed.data.blocks as IntelEditorPartialBlock[]) : undefined;
   } catch {
     return undefined;
   }
@@ -34,10 +46,29 @@ export function KnowledgeEditor({
   onSaved(document: KnowledgeDocument): 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({
-    ...(initialBlocks?.length ? { initialContent: initialBlocks } : {}),
-  });
+    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;
   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: ["knowledge-link-titles", [...linkedIds].sort()],
+    queryFn: () => data.resolveKnowledgeLinks({ nodeIds: linkedIds }),
+    enabled: linkedIds.length > 0,
+  });
   const save = useMutation({
     mutationFn: async () => {
       const payload = BlockNoteDocument.parse({
@@ -66,27 +97,144 @@ export function KnowledgeEditor({
     editor.replaceBlocks(editor.document, blocks);
   }, [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);
+    setDirty(true);
+    setLinkedIds(documentLinkIds(editor.document));
+  }
+
   return (
     <div className="flex min-h-0 flex-1 flex-col">
-      <div className="flex items-center justify-end border-b px-4 py-2">
-        <button
-          type="button"
-          disabled={!dirty || save.isPending}
-          onClick={() => save.mutate()}
-          className="inline-flex items-center gap-2 rounded-md bg-primary px-3 py-2 text-sm font-medium text-primary-foreground outline-none hover:bg-primary/90 focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50"
-        >
-          <Save aria-hidden="true" className="size-4" />
-          {save.isPending ? i18n.t("common.saving") : i18n.t("common.save")}
-        </button>
-      </div>
+      {/* ⚠️ 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("knowledge.saveError")}
         </p>
       )}
       <div className="min-h-0 flex-1 overflow-y-auto py-6">
-        <BlockNoteView editor={editor} onChange={() => setDirty(true)} />
+        <DocumentLinkProvider
+          value={{
+            titles: new Map((resolved.data?.items ?? []).map((item) => [item.nodeId, item.title])),
+            pending: linkedIds.length > 0 && resolved.isPending,
+            unresolvedLabel: i18n.t("knowledge.link.unresolved"),
+          }}
+        >
+          <BlockNoteView
+            editor={editor}
+            onChange={() => {
+              setDirty(true);
+              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("knowledge.link.insert"),
+                      group: i18n.t("knowledge.link.group"),
+                      icon: <Link2 aria-hidden="true" className="size-4" />,
+                      onItemClick: () => setPicking(true),
+                    },
+                  ],
+                  query,
+                )
+              }
+            />
+          </BlockNoteView>
+        </DocumentLinkProvider>
       </div>
+      {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: ["knowledge-graph"],
+    queryFn: () => data.getKnowledgeGraph(),
+  });
+  const candidates = (graph.data?.nodes ?? [])
+    .filter((node: KnowledgeNode) => node.id !== exclude && node.kind !== "folder")
+    .filter((node: KnowledgeNode) => node.title.toLowerCase().includes(query.trim().toLowerCase()))
+    .slice(0, 50);
+
+  return (
+    <Modal title={i18n.t("knowledge.link.insert")} close={close}>
+      <label className="block text-sm font-medium">
+        {i18n.t("knowledge.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: KnowledgeNode) => (
+          <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("knowledge.link.noMatches")}</li>
+        ) : null}
+      </ul>
+    </Modal>
+  );
+}

package/src/knowledge-graph/knowledge-graph.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeGraph as KnowledgeGraphData } from "@anchrd/intel-contract";
+import type { RelationGraph } from "@anchrd/intel-contract";
 import Color from "colorjs.io";
 import { MultiDirectedGraph } from "graphology";
 
@@ -19,12 +19,21 @@ export function resolveGraphColor(...tokens: string[]): string | undefined {
   return undefined;
 }
 
-export function createKnowledgeGraph(data: KnowledgeGraphData): MultiDirectedGraph {
+/**
+ * What accesses what, as Sigma draws it (#19).
+ *
+ * ⚠️ This builds only what it is given, and it is given only what the server let through. An edge
+ * whose endpoint is missing is dropped rather than drawn to an invented node: a placeholder for
+ * something the user may not see would give away that it exists, which is the one thing the graph
+ * must never do. The check is here as well as on the server because this is the last place before
+ * the pixels.
+ */
+export function createRelationGraph(data: RelationGraph): MultiDirectedGraph {
   const graph = new MultiDirectedGraph();
-  const primary = resolveGraphColor("--primary", "--foreground");
-  const secondary = resolveGraphColor("--secondary-foreground", "--foreground");
-  const muted = resolveGraphColor("--muted-foreground", "--foreground");
-  const edge = resolveGraphColor("--border", "--muted-foreground");
+  const flowColor = resolveGraphColor("--primary", "--foreground");
+  const documentColor = resolveGraphColor("--secondary-foreground", "--foreground");
+  const outsideColor = resolveGraphColor("--muted-foreground", "--foreground");
+  const edgeColor = resolveGraphColor("--border", "--muted-foreground");
   const count = Math.max(1, data.nodes.length);
   for (const [index, node] of data.nodes.entries()) {
     const angle = index * Math.PI * (3 - Math.sqrt(5));
@@ -33,26 +42,19 @@ export function createKnowledgeGraph(data: KnowledgeGraphData): MultiDirectedGra
       label: node.title,
       x: Math.cos(angle) * radius,
       y: Math.sin(angle) * radius,
-      size: node.kind === "folder" ? 11 : node.kind === "attachment" ? 6 : 8,
-      color: node.kind === "folder" ? secondary : node.kind === "attachment" ? muted : primary,
+      size: node.kind === "flow" ? 10 : node.kind === "folder" ? 8 : 7,
+      // What is filed in this level and what it merely reaches into are told apart by colour, so a
+      // document pulled in from another folder does not read as part of it.
+      color: !node.inScope ? outsideColor : node.kind === "flow" ? flowColor : documentColor,
     });
   }
-  for (const node of data.nodes) {
-    if (node.parentId && graph.hasNode(node.parentId)) {
-      graph.addDirectedEdgeWithKey(`tree:${node.id}`, node.parentId, node.id, {
-        size: 0.6,
-        color: edge,
-      });
-    }
-  }
-  for (const link of data.links) {
-    if (graph.hasNode(link.sourceNodeId) && graph.hasNode(link.targetNodeId)) {
-      graph.addDirectedEdgeWithKey(link.id, link.sourceNodeId, link.targetNodeId, {
-        label: link.label ?? link.relation.replaceAll("_", " "),
-        size: 2,
-        color: primary,
-      });
-    }
+  for (const edge of data.edges) {
+    if (!graph.hasNode(edge.source) || !graph.hasNode(edge.target)) continue;
+    graph.addDirectedEdgeWithKey(edge.id, edge.source, edge.target, {
+      label: edge.relation,
+      size: edge.relation === "calls" ? 2.5 : 1.5,
+      color: edge.relation === "calls" ? flowColor : edgeColor,
+    });
   }
   return graph;
 }

package/src/knowledge-graph/knowledge-graph.tsx

@@ -1,10 +1,9 @@
-import type { KnowledgeGraph as KnowledgeGraphData } from "@anchrd/intel-contract";
+import type { RelationGraph } from "@anchrd/intel-contract";
 import { ControlsContainer, SigmaContainer, useCamera, useRegisterEvents } from "@react-sigma/core";
 import { LocateFixed, Minus, Plus } from "lucide-react";
 import { useEffect, useMemo } from "react";
 import type { I18n } from "@/i18n/i18n.types.ts";
-import { Modal } from "@/modal/modal.tsx";
-import { createKnowledgeGraph, resolveGraphColor } from "./knowledge-graph.ts";
+import { createRelationGraph, resolveGraphColor } from "./knowledge-graph.ts";
 
 function labelColors() {
   const label = resolveGraphColor("--foreground");
@@ -59,34 +58,39 @@ function GraphControls({ i18n }: { i18n: I18n }) {
   );
 }
 
-export function KnowledgeGraphView({
+/**
+ * The graph half of the editor ↔ graph switch (#19): one level of the shared tree, its documents and
+ * flows side by side, and the edges between them.
+ *
+ * Clicking a node navigates to it — the graph is a way through the product, not a picture of it.
+ */
+export function RelationGraphView({
   data,
   i18n,
-  close,
   select,
 }: {
-  data: KnowledgeGraphData;
+  data: RelationGraph;
   i18n: I18n;
-  close(): void;
-  select(nodeId: string): void;
+  select(node: RelationGraph["nodes"][number]): void;
 }) {
-  const graph = useMemo(() => createKnowledgeGraph(data), [data]);
+  const graph = useMemo(() => createRelationGraph(data), [data]);
+  const byId = useMemo(() => new Map(data.nodes.map((node) => [node.id, node])), [data.nodes]);
   return (
-    <Modal
-      title={i18n.t("knowledge.graph")}
-      close={close}
-      className="h-[calc(100vh-2rem)] max-w-none"
-    >
-      <p className="mb-4 text-sm text-muted-foreground">
-        {i18n.t("knowledge.graphDescription", {
-          nodes: data.nodes.length,
-          links: data.links.length,
-        })}
+    <section aria-label={i18n.t("view.graph")} className="flex min-h-0 flex-1 flex-col">
+      <p className="border-b px-6 py-3 text-sm text-muted-foreground">
+        {i18n.t("view.graphDescription", { nodes: data.nodes.length, edges: data.edges.length })}
+        {/* ⚠️ The cut-off is said out loud. A graph that quietly stopped drawing would read as "this
+            folder holds nothing else", which is worse than a graph that admits it is partial. */}
+        {data.omitted > 0 ? (
+          <span className="ml-2 rounded-md border px-2 py-0.5 text-xs">
+            {i18n.t("view.graphTruncated", { omitted: data.omitted, limit: data.limit })}
+          </span>
+        ) : null}
       </p>
-      <div className="min-h-0 flex-1 overflow-hidden rounded-lg border bg-muted/20">
+      <div className="min-h-0 flex-1 bg-muted/20">
         {data.nodes.length === 0 ? (
-          <div className="grid h-full place-items-center text-sm text-muted-foreground">
-            {i18n.t("knowledge.empty")}
+          <div className="grid h-full place-items-center p-8 text-sm text-muted-foreground">
+            {i18n.t("view.graphEmpty")}
           </div>
         ) : (
           <SigmaContainer
@@ -101,11 +105,16 @@ export function KnowledgeGraphView({
               ...labelColors(),
             }}
           >
-            <GraphEvents select={select} />
+            <GraphEvents
+              select={(nodeId) => {
+                const node = byId.get(nodeId);
+                if (node) select(node);
+              }}
+            />
             <GraphControls i18n={i18n} />
           </SigmaContainer>
         )}
       </div>
-    </Modal>
+    </section>
   );
 }

package/src/knowledge-table/knowledge-table.tsx

@@ -0,0 +1,129 @@
+import type { KnowledgeNode } from "@anchrd/intel-contract";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { Download } from "lucide-react";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+
+/**
+ * A table as a grid (#40).
+ *
+ * Reading is the whole of the first cut: there is no cell editor, and rows arrive through
+ * `knowledge_table_append` — the point of the kind is that an agent fills it without a person
+ * retyping anything.
+ *
+ * ⚠️ The rows are the server's answer, parsed by the server's one CSV reader. A second reader here
+ * would eventually disagree with it about a quoted comma, and the grid would then show something
+ * the export does not contain.
+ */
+export function KnowledgeTablePanel({ node }: { node: KnowledgeNode }) {
+  const { data, i18n } = useIntelRouterContext();
+  const table = useQuery({
+    queryKey: ["knowledge-table", node.id],
+    queryFn: () => data.getKnowledgeTable(node.id),
+  });
+  // CSV is the export. The canonical body is already CSV, so downloading is handing over the bytes
+  // that are stored rather than rendering a second format that could drift from them.
+  const download = useMutation({
+    mutationFn: async () => {
+      const document_ = await data.getKnowledge(node.id);
+      return new Blob([document_.content ?? ""], { type: "text/csv;charset=utf-8" });
+    },
+    onSuccess: (blob) => {
+      const url = URL.createObjectURL(blob);
+      const anchor = document.createElement("a");
+      anchor.href = url;
+      anchor.download = node.title.toLowerCase().endsWith(".csv")
+        ? node.title
+        : `${node.title}.csv`;
+      document.body.append(anchor);
+      anchor.click();
+      anchor.remove();
+      setTimeout(() => URL.revokeObjectURL(url), 0);
+    },
+  });
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      <div className="flex items-center justify-between gap-4 border-b px-4 py-2">
+        <p className="text-sm text-muted-foreground">
+          {table.data
+            ? i18n.t("knowledge.table.summary", {
+                rows: table.data.rows.length,
+                columns: table.data.columns.length,
+              })
+            : ""}
+        </p>
+        <button
+          type="button"
+          onClick={() => download.mutate()}
+          disabled={download.isPending || !table.data?.columns.length}
+          className="inline-flex items-center gap-2 rounded-md border px-3 py-2 text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+        >
+          <Download aria-hidden="true" className="size-4" />
+          {i18n.t("knowledge.table.download")}
+        </button>
+      </div>
+      {download.isError ? (
+        <p role="alert" className="mx-6 mt-4 text-sm text-destructive">
+          {i18n.t("knowledge.downloadFailed")}
+        </p>
+      ) : null}
+      {table.isPending ? (
+        <p className="p-6 text-sm text-muted-foreground">{i18n.t("common.loading")}</p>
+      ) : table.isError ? (
+        <div role="alert" className="space-y-3 p-6 text-sm">
+          <p className="text-destructive">{i18n.t("knowledge.loadFailed")}</p>
+          <button
+            type="button"
+            onClick={() => void table.refetch()}
+            className="rounded-md border px-3 py-2 text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            {i18n.t("common.retry")}
+          </button>
+        </div>
+      ) : table.data.columns.length === 0 ? (
+        <p className="grid flex-1 place-items-center p-8 text-center text-sm text-muted-foreground">
+          {i18n.t("knowledge.table.undefined")}
+        </p>
+      ) : (
+        <div className="min-h-0 flex-1 overflow-auto">
+          <table className="w-full border-collapse text-sm">
+            <caption className="sr-only">{node.title}</caption>
+            <thead className="sticky top-0 bg-card">
+              <tr>
+                {table.data.columns.map((column) => (
+                  // Column names are distinct by contract (`DefineKnowledgeTableInput`), so the
+                  // name is the key and nothing has to fall back to a position.
+                  <th
+                    key={column}
+                    scope="col"
+                    className="border-b border-r px-3 py-2 text-left font-medium whitespace-nowrap"
+                  >
+                    {column}
+                  </th>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {table.data.rows.map((row, rowIndex) => (
+                // ⚠️ Rows carry no identity of their own. A table is an append-only list of text
+                // and its position is the only thing that names a row — there is no id to key on,
+                // and inventing one would be inventing data.
+                // biome-ignore lint/suspicious/noArrayIndexKey: an appended row has no other key
+                <tr key={rowIndex} className="even:bg-muted/40">
+                  {table.data.columns.map((column, cellIndex) => (
+                    <td key={column} className="border-b border-r px-3 py-2 align-top">
+                      {row[cellIndex] ?? ""}
+                    </td>
+                  ))}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+          {table.data.rows.length === 0 ? (
+            <p className="p-6 text-sm text-muted-foreground">{i18n.t("knowledge.table.empty")}</p>
+          ) : null}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/main.tsx

@@ -5,11 +5,11 @@ import { createRoot } from "react-dom/client";
 import { createIntelDataProvider } from "@/data/intel-data-provider/intel-data-provider.ts";
 import { createI18n } from "@/i18n/i18n.ts";
 import { createIntelRouter } from "@/router/router.tsx";
-import { watchSystemTheme } from "@/theme/theme.ts";
+import { SystemThemeQuery, watchSystemTheme } from "@/theme/theme.ts";
 import "./styles.css";
 import "./theme/custom.css";
 
-watchSystemTheme(document.documentElement, window.matchMedia("(prefers-color-scheme: dark)"));
+watchSystemTheme(document.documentElement, window.matchMedia(SystemThemeQuery));
 
 const root = document.getElementById("root");
 if (!root) throw new Error("Missing #root element");