@smartmemory/wiki-components 0.5.0 → 0.6.0

package/README.md

@@ -26,7 +26,7 @@ npm install @smartmemory/wiki-components react react-dom date-fns lucide-react
 
 ## Contract
 
-`src/data-client.d.ts` is the contract: nine calls (`identity`, `featureHub`, `decisions`, `decisionsPage`, `sourcesPage`, `docsByArea`, `ledger`, `upcomingCalls`, `search`), the endpoint and
+`src/data-client.d.ts` is the contract: twelve calls (`identity`, `featureHub`, `decisions`, `decisionsPage`, `sourcesPage`, `docsByArea`, `ledger`, `upcomingCalls`, `search`, `graphAll`, `graphPage`, `note`), the endpoint and
 request body each maps to on the wiki API, and the result types (from `wiki/contracts/query.schema.json`). The same list is
 runtime data in `DATA_CLIENT_CALLS`; `ui/test/wiki-components.test.jsx` pins the typed file, the table and the app's client
 to each other. `<WikiDataProvider>` refuses a client missing a method.
@@ -35,6 +35,7 @@ to each other. `<WikiDataProvider>` refuses a client missing a method.
 
 ```jsx
 import { WikiDataProvider, FeatureHub, Search, Decisions, Sources, AreaDocs, Ledger, wikiPath } from "@smartmemory/wiki-components";
+import { GraphHost, GraphPage } from "@smartmemory/wiki-components/graph";
 
 <WikiDataProvider client={myClient}>
   <FeatureHub featureId="CORE-1" workspace="wiki-eng" />
@@ -45,6 +46,7 @@ import { WikiDataProvider, FeatureHub, Search, Decisions, Sources, AreaDocs, Led
   <Sources workspace="wiki-eng" />
   <AreaDocs area="search" workspace="wiki-eng" onNavigate={go} hrefFor={href} />
   <Ledger workspace="wiki-eng" />
+  <GraphHost value={{ workspace: "wiki-eng", useSearchParams, Link, useColorMode, aspectHint }}><GraphPage /></GraphHost>
 </WikiDataProvider>
 ```
 
@@ -69,6 +71,16 @@ import { WikiDataProvider, FeatureHub, Search, Decisions, Sources, AreaDocs, Led
   (`GET /feeds/upcoming_calls`), which resolves `{items, errors}`, or `null` when the host does not serve the feed (the
   section is then left out; an empty feed still shows "No upcoming calls."). The window is 30 days back to one day ahead of
   `now`, an optional prop (ms since the epoch) for tests, else the first render's time. Also exported: `LedgerTimeline`.
+- `Graph` (its own entry, `@smartmemory/wiki-components/graph`, so a host that never draws it does not load it) is the wiki's
+  Graph screen as it ran in the `/ui/` app, moved with its bodies unchanged (COMPOSE-WIKI-GRAPH-1a): 2D, the WebGL 2D base and the
+  lazy 3D view, filters, paths, saved views and the doc pane. It takes everything the app used to give it through
+  `<GraphHost value={{ workspace, useSearchParams, Link, useColorMode, requestTreeSync?, aspectHint }}>`: the view state lives in
+  the URL, so the host supplies `useSearchParams` (react-router's, or any hook returning `[URLSearchParams, setter]`), a `Link`
+  taking `to`, the design system's `useColorMode`, and the words for the greyed aspect options. Its data is
+  `client.graphAll({workspace})` (`POST /query/graph`, `page: {all: true}`; a host without the mode rejects with `code`
+  `"invalid_request"` and the screen pages with `client.graphPage({workspace, cursor?, size?})`) and, for the doc pane,
+  `client.note({workspace, id})` (`GET /note?workspace=&id=`). Exports: `GraphPage`, `GraphHost`, `GRAPH_ASPECTS`, `wholeGraph`,
+  `resetWebGL2Probe`. The package root also exports `MD` and `MD_PLUGINS` (note text rendering) and `INPUT`.
 - `workspace` / `workspaces` are optional: without them a screen calls `client.identity()` and uses the caller's grants
   (FeatureHub the first one).
 - `onNavigate(target)` receives a plain left click on a link and the search box's submit. `hrefFor(target)` is each link's
@@ -76,7 +88,7 @@ import { WikiDataProvider, FeatureHub, Search, Decisions, Sources, AreaDocs, Led
 
 ## Host requirements
 
-- **Peers:** `react` and `react-dom` `>=18 <20`, `date-fns` 3, `lucide-react`. The package ships JSX source (no build step);
+- **Peers:** `react` and `react-dom` `>=18 <20`, `date-fns` 3, `lucide-react`; for the Graph entry also `d3-force` 3, `d3-quadtree` 3, `react-markdown` 9 or 10 and `remark-gfm` 4 (the root entry needs `remark-gfm` for `MD_PLUGINS`), and the optional `pixi.js` 8 (WebGL 2D), `three` and `d3-force-3d` (3D). The package ships JSX source (no build step);
   a Vite host transforms it (installed from npm or linked). Consumed as `file:` dependency, its bare imports resolve from its real path, so a host outside
   this repo must list `react`, `react-dom` (and `lucide-react`, `date-fns`) in `resolve.dedupe` or it loads the wiki's
   React 18 copy next to its own.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smartmemory/wiki-components",
-  "version": "0.5.0",
-  "description": "The wiki's feature hub and search screens as router-free React components fed by an injected DataClient (WIKI-UI-COMPONENTS-1). Ships JSX source for a bundler host (Vite).",
+  "version": "0.6.0",
+  "description": "The wiki's screens (feature hub, search, decisions, sources, docs, ledger, graph) as router-free React components fed by an injected DataClient (WIKI-UI-COMPONENTS-1). Ships JSX source for a bundler host (Vite).",
   "license": "BUSL-1.1",
   "author": "Regression Analytics LLC",
   "repository": {
@@ -20,6 +20,10 @@
       "types": "./src/index.d.ts",
       "default": "./src/index.js"
     },
+    "./graph": {
+      "types": "./src/graph/index.d.ts",
+      "default": "./src/graph/index.js"
+    },
     "./data-client": {
       "types": "./src/data-client.d.ts"
     },
@@ -34,7 +38,25 @@
     "react": ">=18 <20",
     "react-dom": ">=18 <20",
     "date-fns": "^3.6.0",
-    "lucide-react": ">=0.475.0"
+    "lucide-react": ">=0.475.0",
+    "d3-force": "^3.0.0",
+    "d3-quadtree": "^3.0.1",
+    "react-markdown": ">=9 <11",
+    "remark-gfm": "^4.0.1",
+    "pixi.js": "^8.22.0",
+    "three": "0.186.1",
+    "d3-force-3d": "3.0.6"
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "peerDependenciesMeta": {
+    "pixi.js": {
+      "optional": true
+    },
+    "three": {
+      "optional": true
+    },
+    "d3-force-3d": {
+      "optional": true
+    }
+  }
 }

package/src/data-client.d.ts

@@ -1,4 +1,4 @@
-// WIKI-UI-COMPONENTS-1: the DataClient contract. Every call the FeatureHub, Search, Decisions, Sources, AreaDocs and Ledger screens make, and nothing else.
+// WIKI-UI-COMPONENTS-1: the DataClient contract. Every call the FeatureHub, Search, Decisions, Sources, AreaDocs, Ledger and Graph screens make, and nothing else.
 // A host (the wiki's /ui/ app, Compose's wiki tab) passes one object with these async methods to <WikiDataProvider>.
 // The components never fetch: each call below is the whole of their I/O.
 //
@@ -15,6 +15,9 @@
 //   ledger       POST /query/ledger           {query: "ledger",      workspace, filters: {from, to}, page: {size: 50, cursor?}}  (sort is the host's: ts, newest first)
 //   upcomingCalls GET /feeds/upcoming_calls?workspace=  (none) -> data_envelope; an absent feed (the wiki answers 404 not_found) resolves to null
 //   search       POST /query/search           {query: "search",      workspace, filters: {q},          page: {}}
+//   graphAll     POST /query/graph            {query: "graph",      workspace, filters: {},           page: {all: true}}  (one-shot; a host without it rejects with code invalid_request)
+//   graphPage    POST /query/graph            {query: "graph",      workspace, filters: {},           page: {size, cursor?}}  (the paged fallback)
+//   note         GET  /note?workspace=&id=    (none) -> {workspace, note, generated_at}  (the Graph's doc pane)
 //
 // The same table is runtime data in data-client.jsx (DATA_CLIENT_CALLS); a test pins the two to each other.
 // A rejected call should reject with an Error carrying `code` (the query_error code) so the screens can show it.
@@ -118,6 +121,23 @@ export interface FeatureHubResult extends QueryResult<DocItem> {
   feature: FeatureItem | null;
 }
 
+/** The graph query result: every doc of the workspace (`items`) and the links between them (`edges`). `revision`/`layout` come on the one-shot answer, `next_cursor` on a page. */
+export interface GraphResult {
+  items: Record<string, unknown>[];
+  edges?: Record<string, unknown>[];
+  total?: number;
+  revision?: string;
+  layout?: unknown;
+  next_cursor?: string | null;
+}
+
+/** GET /note: one note with its text. */
+export interface NoteResult {
+  workspace: Workspace;
+  note: { title?: string; type?: string; text?: string; [field: string]: unknown };
+  generated_at: string;
+}
+
 /** x-named-queries.search.result (a grouped_result). */
 export interface SearchResult {
   groups: { label: string; items: SearchHit[]; total: number; next_cursor: string | null }[];
@@ -147,6 +167,12 @@ export interface DataClient {
   upcomingCalls(args: { workspace: Workspace }): Promise<UpcomingCalls | null>;
   /** POST /query/search, filters {q} (1 to 256 characters), page {}. One call per workspace searched. */
   search(args: { workspace: Workspace; q: string }): Promise<SearchResult>;
+  /** POST /query/graph, filters {}, page {all: true}: the whole workspace graph in one request. A host without the mode rejects with an Error whose `code` is "invalid_request" (the screen then pages with graphPage). */
+  graphAll(args: { workspace: Workspace }): Promise<GraphResult>;
+  /** POST /query/graph, filters {}, page {size, cursor?}: one page of the graph. `cursor` is the previous page's `next_cursor`, opaque. */
+  graphPage(args: { workspace: Workspace; cursor?: string; size?: number }): Promise<GraphResult>;
+  /** GET /note?workspace=&id=: one note with its text (the Graph's doc pane). */
+  note(args: { workspace: Workspace; id: string }): Promise<NoteResult>;
 }
 
 /** Where a screen asks the host to go (Search only; FeatureHub has no links). The host maps it to its own route

package/src/data-client.jsx

@@ -12,6 +12,9 @@ export const DATA_CLIENT_CALLS = [
   { method: "ledger", endpoint: "POST /query/ledger", query: "ledger", page: { size: 50 } },
   { method: "upcomingCalls", endpoint: "GET /feeds/upcoming_calls" },
   { method: "search", endpoint: "POST /query/search", query: "search", page: {} },
+  { method: "graphAll", endpoint: "POST /query/graph", query: "graph", page: { all: true } },
+  { method: "graphPage", endpoint: "POST /query/graph", query: "graph", page: { size: 200 } },
+  { method: "note", endpoint: "GET /note" },
 ];
 
 const Ctx = createContext(null);

package/src/graph/components/wiki/DocCard.jsx

@@ -0,0 +1,46 @@
+import React, { useEffect, useRef } from "react";
+import { Link } from "../../host";
+import { docCardAt } from "../../lib/docCard";
+
+/** The focused doc's card, drawn at its node in the 3D view (WIKI-GRAPH-EXPLORE-1b-SHELL B1). Each frame it asks the canvas for the
+ *  node's `screenPositions` entry and moves itself with a style write (no React render per frame); it hides while the node is off-screen
+ *  or behind the camera. Pin is left out as filed. `anchor` is the drawn id the card follows (docCard cardAnchor: the doc, or the collapsed folder drawn for it; null = hidden), `canvas` is the GraphCanvas3D ref, `to` the Open note link, `onPathTo(doc)` the Path to… action (round 3: starts the path lens from this doc).
+ *  `shown` false fades it out (no fade under reduced motion) and makes it inert; `onHold` / `onRelease` fire as the pointer enters / leaves it and `onFocusIn` / `onFocusOut` as keyboard focus does (the auto-hide waits). */
+export default function DocCard({ canvas, focus, anchor = focus?.id ?? null, to, onPathTo, shown = true, reduced = false, onHold, onRelease, onFocusIn, onFocusOut }) {
+  const box = useRef(null);
+  const id = anchor;
+  useEffect(() => {
+    const el = box.current;
+    if (!el) return undefined;
+    // Every imperative style the RAF writes is reset here first, so a same-mount change of anchor (including to null) never leaves the
+    // previous anchor's visibility or position on the element (React sees the same declarative style and would not reset it).
+    el.style.visibility = "hidden"; el.style.left = ""; el.style.top = "";
+    if (!id) return undefined;
+    let raf = 0, last = "";
+    const tick = () => {
+      raf = requestAnimationFrame(tick);
+      const parent = el.offsetParent || el.parentElement;
+      const w = parent?.clientWidth || 0, h = parent?.clientHeight || 0;
+      const p = canvas.current?.screenPositions?.([id])?.[0];
+      const at = docCardAt(p, el.offsetWidth, el.offsetHeight, w, h);
+      const key = at ? `${Math.round(at.left)},${Math.round(at.top)}` : "";
+      if (key === last) return;
+      last = key;
+      el.style.visibility = at ? "visible" : "hidden";
+      if (at) { el.style.left = `${at.left}px`; el.style.top = `${at.top}px`; }
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [canvas, id]);
+  if (!focus) return null;
+  return (
+    <div ref={box} data-testid="graph-doc-card" data-shown={shown ? "true" : "false"} style={{ visibility: "hidden", opacity: shown ? 1 : 0, transition: reduced ? "none" : "opacity 300ms" }}
+      inert={shown ? undefined : ""} onPointerEnter={onHold} onPointerLeave={onRelease} onFocus={onFocusIn} onBlur={onFocusOut}
+      className={`${shown ? "pointer-events-auto" : "pointer-events-none"} absolute left-0 top-0 z-10 w-64 max-w-[70%] rounded-lg border border-neutral-200/70 bg-ground/90 p-3 shadow-sm backdrop-blur`}>
+      <h2 className="text-base font-semibold text-ink">{focus.title}</h2>
+      <p className="mt-1 break-all font-mono text-xs text-neutral-500">{focus.folder || "(root)"}</p>
+      {focus.area && <p className="mt-1 text-xs text-ink2">area {focus.area}</p>}
+      <div className="mt-2 text-[13px]"><Link to={to} className="text-blue-600 hover:underline">Open note</Link>{onPathTo && <button type="button" onClick={() => onPathTo(focus)} className="ml-3 text-blue-600 hover:underline">Path to…</button>}</div>
+    </div>
+  );
+}

package/src/graph/components/wiki/GraphBreadcrumb.jsx

@@ -0,0 +1,23 @@
+import React from "react";
+
+/** WIKI-GRAPH-LEVELS-1 c2: where the level view is. `crumbs` are the open folders, top-level first (`breadcrumb()` of the
+ *  deepest one); "All" is always first. `onSelect(path)` collapses to that folder, `onSelect(null)` back to level 0. The
+ *  current (last) entry is text, not a button. `all={false}` (the page has an auto-expanded base,
+ *  WIKI-GRAPH-LEVELS-AUTOEXPAND-1) drops "All": the trail starts at the base, and `onSelect` is told the clicked path. A separate component so the later command palette can absorb it. */
+export default function GraphBreadcrumb({ crumbs, onSelect, all = true }) {
+  const last = crumbs.length - 1;
+  const BTN = "rounded px-1 text-[13px] text-blue-600 hover:underline";
+  return (
+    <nav aria-label="Graph level" className="flex min-w-0 flex-wrap items-center gap-1 text-[13px] text-ink2">
+      {all && (last < 0 ? <span aria-current="location" className="px-1 text-ink">All</span> : <button type="button" onClick={() => onSelect(null)} className={BTN}>All</button>)}
+      {crumbs.map((c, i) => (
+        <React.Fragment key={c.path}>
+          {(all || i > 0) && <span aria-hidden="true" className="text-neutral-400">/</span>}
+          {i === last
+            ? <span aria-current="location" className="px-1 text-ink">{c.label}</span>
+            : <button type="button" onClick={() => onSelect(c.path)} className={BTN}>{c.label}</button>}
+        </React.Fragment>
+      ))}
+    </nav>
+  );
+}