@schlessera/brain-ui-react 0.35.0 → 0.36.0

package/src/components/graph/graph-node-rail.tsx

@@ -0,0 +1,147 @@
+import { useMemo } from "react";
+import type { GraphNodePayload } from "@schlessera/brain-ui-sdk/protocol";
+import {
+  ContactCard,
+  Label,
+  RelatedFiles,
+  type ContactAction,
+  type ContactFact,
+  type ContactKind,
+  type ContactTone,
+} from "@schlessera/brain-ui-kit";
+
+import { useGraphStore } from "../../stores/graph-store.js";
+import { hopsLabel, useNodeActions } from "./use-node-actions.js";
+
+/**
+ * D6's 340px right rail, from `wide:` only: `Label "Selected node"` + the
+ * node as a kit `ContactCard` ("a graph node and a chat entity are the same
+ * object"), then `Label "Edges"` + the node's neighbours in the scene as a
+ * `RelatedFiles` list. Below `wide:` the floating `NodePopover` draws the
+ * node instead.
+ *
+ * The neighbours come from `subgraph.edges` — the scene's edges, not the
+ * corpus's — so the count is "edges drawn", and a truncated scene may hold
+ * fewer than the node's degree. The card's facts carry the true degrees.
+ */
+export function GraphNodeRail() {
+  const subgraph = useGraphStore((s) => s.subgraph);
+  const selectedId = useGraphStore((s) => s.selectedId);
+
+  const node = useMemo(
+    () =>
+      selectedId === null || !subgraph
+        ? null
+        : (subgraph.nodes.find((n) => n.id === selectedId) ?? null),
+    [selectedId, subgraph]
+  );
+
+  return (
+    <aside
+      aria-label="Selected node"
+      className="flex w-[340px] shrink-0 flex-col gap-4 overflow-y-auto border-l border-border bg-surface px-4 py-4"
+    >
+      <Label text="Selected node" icon="capability" />
+      {node ? (
+        <SelectedNode node={node} />
+      ) : (
+        <p className="font-mono text-[10px] text-muted-foreground">
+          click a node on the canvas
+        </p>
+      )}
+    </aside>
+  );
+}
+
+function SelectedNode({ node }: { node: GraphNodePayload }) {
+  const subgraph = useGraphStore((s) => s.subgraph)!;
+  const meta = useGraphStore((s) => s.meta);
+  const select = useGraphStore((s) => s.select);
+  const actions = useNodeActions(node);
+
+  const isVirtual = node.virtual === true;
+  const kindLabel = isVirtual ? "root" : node.type;
+  const topic =
+    node.community !== undefined
+      ? (meta?.communities.find((c) => c.community === node.community)?.label ?? null)
+      : null;
+
+  const facts: ContactFact[] = [
+    { k: "in-degree", v: String(node.inDegree) },
+    { k: "out-degree", v: String(node.outDegree) },
+  ];
+  const hops = hopsLabel(node.distance);
+  if (hops) facts.push({ k: "hops", v: hops });
+  if (topic) facts.push({ k: "topic", v: topic, tone: "purple" });
+
+  const cardActions: ContactAction[] = [];
+  if (actions.canOpen)
+    cardActions.push({ label: "Open note", icon: "file", tone: "primary", onClick: actions.open });
+  if (actions.canFocus)
+    cardActions.push({ label: "Focus here", icon: "graph", tone: "ghost", onClick: actions.focus });
+  if (actions.canExpand)
+    cardActions.push({ label: "Expand", icon: "expand", tone: "ghost", onClick: actions.expand });
+
+  const neighbours = useMemo(() => {
+    const byId = new Map(subgraph.nodes.map((n) => [n.id, n]));
+    const out: { node: GraphNodePayload; direction: "out" | "in" }[] = [];
+    const seen = new Set<number>();
+    for (const edge of subgraph.edges) {
+      const otherId =
+        edge.source === node.id ? edge.target : edge.target === node.id ? edge.source : null;
+      if (otherId === null || seen.has(otherId)) continue;
+      const other = byId.get(otherId);
+      if (!other) continue;
+      seen.add(otherId);
+      out.push({ node: other, direction: edge.source === node.id ? "out" : "in" });
+    }
+    return out;
+  }, [subgraph, node.id]);
+
+  const entity = entityShape(node.type);
+
+  return (
+    <>
+      <ContactCard
+        label={node.title || node.path}
+        role={`${kindLabel} · ${node.path}`}
+        kind={entity.kind}
+        tone={entity.tone}
+        facts={facts}
+        actions={cardActions}
+        keyWidth={72}
+      />
+      {neighbours.length > 0 && (
+        <>
+          <Label text="Edges" icon="files" tone="teal" meta={`${neighbours.length} drawn`} />
+          <RelatedFiles
+            label=""
+            meta=""
+            items={neighbours.map(({ node: other, direction }) => ({
+              path: other.title || other.path,
+              reason: direction === "out" ? `links to · ${other.path}` : `linked from · ${other.path}`,
+              icon: other.virtual ? "graph" : "file",
+              tone: direction === "out" ? "teal" : "blue",
+              onClick: () => select(other.id),
+            }))}
+          />
+        </>
+      )}
+    </>
+  );
+}
+
+/**
+ * The card's avatar follows the entity language (teal person, blue company,
+ * purple project). A document type outside that vocabulary is drawn as a
+ * neutral rounded square — the kit has no "note" kind, and a circle would
+ * claim it is a person.
+ */
+function entityShape(type: string): { kind: ContactKind; tone: ContactTone } {
+  const t = type.toLowerCase();
+  if (t === "person" || t === "people" || t === "contact") return { kind: "person", tone: "teal" };
+  if (t === "company" || t === "organization" || t === "organisation" || t === "org")
+    return { kind: "company", tone: "blue" };
+  if (t === "project") return { kind: "project", tone: "purple" };
+  return { kind: "project", tone: "neutral" };
+}

package/src/components/graph/graph-page.tsx

@@ -1,28 +1,32 @@
 import { useEffect } from "react";
 import { TriangleAlert } from "lucide-react";
+import { EmptyState, ScreenHeader } from "@schlessera/brain-ui-kit";
 
-import { useGraphStore, type GraphMode } from "../../stores/graph-store.js";
+import { useGraphStore, type DiscoveryColorBy, type GraphMode } from "../../stores/graph-store.js";
 import { useUIStore } from "../../stores/ui-store.js";
+import { useMediaQuery } from "../../hooks/use-media-query.js";
 import { FilePanel } from "../files/file-panel.js";
 import { SettingsPanel } from "../settings/settings-panel.js";
-import { GraphControls } from "./graph-controls.js";
+import { GraphControls, LAPTOP_QUERY, WIDE_QUERY } from "./graph-controls.js";
+import { GraphControlsColumn, MODES } from "./graph-controls-column.js";
 import { GraphEmptyState, Mono } from "./graph-empty-state.js";
 import { MaintenanceBody } from "./graph-maintenance.js";
+import { GraphNodeRail } from "./graph-node-rail.js";
 import { DiscoveryStart, SceneBody } from "./graph-scene.js";
 import { CenteredSpinner } from "./graph-spinner.js";
 import { cn } from "../../lib/utils.js";
 
-const MODES: { value: GraphMode; label: string }[] = [
-  { value: "clusters", label: "Clusters" },
-  { value: "discovery", label: "Discovery" },
-  { value: "local", label: "Local" },
-  { value: "maintenance", label: "Maintenance" },
-];
-
 /**
  * Full-screen knowledge-graph view — a sibling of ChatPage inside the
  * AppShell. Mounts its own FilePanel/SettingsPanel copies because the chat
  * page (which normally hosts them) is hidden while this view is active.
+ *
+ * D6 (the fifth drop): from `laptop:` a 264px controls column on the left
+ * and the canvas under a kit `ScreenHeader nav`; from `wide:` a 340px right
+ * rail with the selected node. Below `laptop:` the mode tabs stay in the
+ * header, the options in the phone sheet, the selected node in the floating
+ * popover. The pane widths key on the same ladder the rail uses, read as a
+ * media query rather than a class so only one copy of the form is mounted.
  */
 export function GraphPage() {
   const mode = useGraphStore((s) => s.mode);
@@ -38,6 +42,8 @@ export function GraphPage() {
   const setFilePanelOpen = useUIStore((s) => s.setFilePanelOpen);
   const settingsPanelOpen = useUIStore((s) => s.settingsPanelOpen);
   const setSettingsPanelOpen = useUIStore((s) => s.setSettingsPanelOpen);
+  const laptop = useMediaQuery(LAPTOP_QUERY);
+  const wide = useMediaQuery(WIDE_QUERY);
 
   useEffect(() => {
     let active = true;
@@ -64,41 +70,43 @@ export function GraphPage() {
         onClose={() => setSettingsPanelOpen(false)}
       />
 
-      {/* Header: mode tabs */}
-      <header className="flex items-center gap-2 border-b border-border px-3 py-2 md:px-4">
-        <h1 className="hidden font-display text-base text-foreground md:block">
-          Graph
-        </h1>
-        <nav
-          aria-label="Graph modes"
-          className="flex flex-1 justify-center gap-1 md:justify-start md:pl-4"
-        >
-          {MODES.map((m) => (
-            <button
-              key={m.value}
-              onClick={() => setMode(m.value)}
-              aria-current={mode === m.value ? "page" : undefined}
-              className={cn(
-                "min-h-9 rounded-lg px-3 py-1.5 text-xs font-medium transition-colors",
-                mode === m.value
-                  ? "bg-surface-raised text-foreground"
-                  : "text-muted-foreground hover:text-foreground"
-              )}
-            >
-              {m.label}
-            </button>
-          ))}
-        </nav>
-        {subgraph?.truncated && (
-          <span
-            className="hidden shrink-0 items-center gap-1 rounded-full border border-border bg-surface-raised px-2 py-0.5 text-[10px] text-muted-foreground md:flex"
-            title="The server capped this scene; the lowest-ranked notes were dropped."
+      {/* Below laptop: the mode tabs in the header */}
+      {!laptop && (
+        <header className="flex items-center gap-2 border-b border-border px-3 py-2 md:px-4">
+          <h1 className="hidden font-display text-base text-foreground md:block">
+            Graph
+          </h1>
+          <nav
+            aria-label="Graph modes"
+            className="flex flex-1 justify-center gap-1 md:justify-start md:pl-4"
           >
-            <TriangleAlert className="h-3 w-3" />
-            truncated
-          </span>
-        )}
-      </header>
+            {MODES.map((m) => (
+              <button
+                key={m.value}
+                onClick={() => setMode(m.value)}
+                aria-current={mode === m.value ? "page" : undefined}
+                className={cn(
+                  "min-h-9 rounded-lg px-3 py-1.5 text-xs font-medium transition-colors",
+                  mode === m.value
+                    ? "bg-surface-raised text-foreground"
+                    : "text-muted-foreground hover:text-foreground"
+                )}
+              >
+                {m.label}
+              </button>
+            ))}
+          </nav>
+          {subgraph?.truncated && (
+            <span
+              className="hidden shrink-0 items-center gap-1 rounded-full border border-border bg-surface-raised px-2 py-0.5 text-[10px] text-muted-foreground md:flex"
+              title="The server capped this scene; the lowest-ranked notes were dropped."
+            >
+              <TriangleAlert className="h-3 w-3" />
+              truncated
+            </span>
+          )}
+        </header>
+      )}
 
       {/* Stale strip */}
       {stale && metaState === "done" && (
@@ -109,9 +117,132 @@ export function GraphPage() {
         </div>
       )}
 
-      {/* Body */}
-      <div className="relative flex-1 overflow-hidden bg-background">
-        <GraphBody modeState={{ mode, metaState, dataState }} />
+      {/* Body: D6's panes from laptop, the canvas alone below */}
+      <div className="flex min-h-0 flex-1">
+        {laptop && <GraphControlsColumn />}
+        <div className="flex min-w-0 flex-1 flex-col">
+          {laptop && <SceneHeader />}
+          <div className="relative flex-1 overflow-hidden bg-background">
+            <GraphBody modeState={{ mode, metaState, dataState }} />
+          </div>
+          {laptop && <CanvasCaption />}
+        </div>
+        {wide && <GraphNodeRail />}
+      </div>
+    </div>
+  );
+}
+
+const MODE_LABEL: Record<GraphMode, string> = {
+  clusters: "Clusters",
+  discovery: "Discovery",
+  local: "Local",
+  maintenance: "Maintenance",
+};
+
+/**
+ * The kit `ScreenHeader nav` above the canvas: the focus node when the scene
+ * has one (Local's centre, Discovery's root), else the mode; the subtitle is
+ * the counts the store holds and stays empty until a scene has landed.
+ */
+function SceneHeader() {
+  const mode = useGraphStore((s) => s.mode);
+  const subgraph = useGraphStore((s) => s.subgraph);
+  const findings = useGraphStore((s) => s.findings);
+  const local = useGraphStore((s) => s.local);
+  const discoveryRoot = useGraphStore((s) => s.discovery.root);
+  const staleDays = useGraphStore((s) => s.maintenance.staleDays);
+
+  const focus =
+    subgraph && (mode === "local" || mode === "discovery")
+      ? (subgraph.nodes.find((n) => n.distance === 0) ?? null)
+      : null;
+  const focusPath = mode === "local" ? local.center : mode === "discovery" ? discoveryRoot : null;
+  const focusTitle = focus ? focus.title || focus.path : focusPath;
+  const title = focusTitle ? `Around ${focusTitle}` : MODE_LABEL[mode];
+
+  let subtitle: string | undefined;
+  if (mode === "maintenance") {
+    if (findings) {
+      const count =
+        findings.orphans.length +
+        findings.unreachable.length +
+        findings.brokenLinks.length +
+        findings.stale.length;
+      subtitle = `${count.toLocaleString()} findings · stale after ${staleDays} days`;
+    }
+  } else if (subgraph) {
+    const parts: string[] = [];
+    if (focus) parts.push(focus.virtual ? "root" : focus.type);
+    parts.push(`${subgraph.nodes.length.toLocaleString()} nodes`);
+    parts.push(`${subgraph.edges.length.toLocaleString()} edges`);
+    if (mode === "local") parts.push(`${local.depth} hop${local.depth === 1 ? "" : "s"}`);
+    if (subgraph.truncated) parts.push("truncated");
+    subtitle = parts.join(" · ");
+  }
+
+  return (
+    <ScreenHeader
+      variant="nav"
+      title={title}
+      subtitle={subtitle}
+      subTone={subgraph?.truncated ? "red" : "neutral"}
+      back={false}
+    />
+  );
+}
+
+const RULE_LABEL: Record<DiscoveryColorBy, string> = {
+  topic: "topic",
+  distance: "distance",
+  folder: "folder",
+  entity: "entity type",
+};
+
+/**
+ * The mono line under the canvas names the ACTIVE colouring rule (sixth
+ * pass §7: "a caption bound to a constant while the control says otherwise
+ * is a lie in a legend"). Read from the same state the scene colours by —
+ * the Colour control in Discovery and Local, topic in Clusters (uniform
+ * when no topics were computed) — so the caption never claims a rule the
+ * scene does not follow.
+ */
+function CanvasCaption() {
+  const mode = useGraphStore((s) => s.mode);
+  const colorBy = useGraphStore((s) => s.discoveryColorBy);
+  const hasTopics = useGraphStore((s) => (s.meta?.communities.length ?? 0) > 0);
+  if (mode === "maintenance") return null;
+  const rule =
+    mode === "discovery" || mode === "local" ? RULE_LABEL[colorBy] : hasTopics ? "topic" : "uniform";
+  return (
+    <p className="border-t border-border px-4 py-2 font-mono text-[10px] text-muted-foreground">
+      canvas is app-drawn · colour = {rule} · click a node to load its card
+    </p>
+  );
+}
+
+/**
+ * An orphan note in Local mode: the centre has no edges in either direction
+ * at this depth. "Emptiness is a finding" — the kit `EmptyState no-results`
+ * with the design's copy and the store's own count, no reassurance.
+ */
+function OrphanEmptyState() {
+  const setActiveView = useUIStore((s) => s.setActiveView);
+  return (
+    <div className="flex h-full items-center justify-center p-6">
+      <div className="w-full max-w-[520px]">
+        <EmptyState
+          variant="no-results"
+          title="Nothing links to this yet"
+          body="This note has no edges in either direction. Ask a question that mentions it and the graph fills in as the answer cites things."
+          meta="0 edges"
+          primaryLabel="Ask about it"
+          primaryIcon="ask"
+          primaryTone="primary"
+          pad={22}
+          minHeight={0}
+          onPrimary={() => setActiveView("chat")}
+        />
       </div>
     </div>
   );
@@ -199,13 +330,22 @@ function GraphBody({
     return <CenteredSpinner />;
   }
 
+  // Local's centre with nothing around it is the orphan case, whether the
+  // server returned the lone centre or nothing at all.
+  if (mode === "local" && subgraph.edges.length === 0) {
+    return (
+      <>
+        <OrphanEmptyState />
+        <GraphControls />
+      </>
+    );
+  }
+
   if (subgraph.nodes.length === 0) {
     return (
       <>
         <GraphEmptyState title="Nothing to show">
-          {mode === "local"
-            ? "This note has no links in or out at this depth."
-            : "No notes matched this scene."}
+          No notes matched this scene.
         </GraphEmptyState>
         <GraphControls />
       </>