pi-weave 0.1.7 → 0.1.8

package/src/web/client/search/search.ts

@@ -0,0 +1,107 @@
+/**
+ * The palette's effects: a timer, a fetch, and nothing else
+ * (weave-workspace §10, P4).
+ *
+ * `search.model.ts` decides *when* to issue a request and *whether* a
+ * response may be applied; it cannot arm a timer or call `fetch` without
+ * ceasing to be pure. This module is the other half — a controller that owns
+ * exactly two capabilities, both injected:
+ *
+ *  - a **clock** (`now`) and a **scheduler** (`delay`), so the 140 ms debounce
+ *    is exercised by a fake in microseconds rather than waited out;
+ *  - a **`FetchLike`**, the same port `api.ts` takes, so no DOM is involved.
+ *
+ * The result is that the palette's entire asynchronous behaviour — debounce,
+ * re-arm, stale-response rejection, failure — is covered by ordinary unit
+ * tests, and `SearchPalette.tsx` is a `useState`, an effect and three
+ * handlers. That is §10's split applied to the one part of the workspace that
+ * is genuinely concurrent.
+ *
+ * ## Why the controller and not the component owns the sequence number
+ *
+ * A component could hold `seq` in a ref and compare on arrival. It would also
+ * be re-created by every hot reload, remounted by every breakpoint change,
+ * and untestable. Keeping the counter inside {@link SearchState}, where the
+ * reducer can reason about it, means "an older response must not overwrite a
+ * newer one" is a property with a test rather than a comment.
+ */
+
+import type { FetchLike } from "../api";
+import { fetchSearch } from "../api";
+import type { SearchEvent, SearchState, SearchTransition } from "./search.model";
+import { initialSearchState, reduceSearch } from "./search.model";
+
+/**
+ * Arms a one-shot timer and returns nothing.
+ *
+ * Deliberately *not* returning a cancel handle: the debounce in
+ * `reduceSearch` is a re-arming chain precisely so that nothing ever needs
+ * cancelling, and a cancel handle here would invite a second, competing
+ * mechanism. `(fn, ms) => void setTimeout(fn, ms)` at the call site; a queue
+ * a test drains by hand in a test.
+ */
+export type Scheduler = (run: () => void, ms: number) => void;
+
+/** What {@link createSearch} needs. Every capability injected. */
+export interface SearchOptions {
+  fetch: FetchLike;
+  /** Epoch ms. `Date.now` in the browser. */
+  now: () => number;
+  delay: Scheduler;
+  /** Called after every state change, so the component can re-render. */
+  onChange: (state: SearchState) => void;
+}
+
+/** A running palette controller. */
+export interface SearchHandle {
+  /** Current state. Read at render. */
+  state(): SearchState;
+  /** The text changed. */
+  setQuery(query: string): void;
+  /** Move the cursor — pointer hover, or a key the model resolved to an index. */
+  setCursor(cursor: number): void;
+  /** The palette closed: disarm the debounce. */
+  dismiss(): void;
+}
+
+/**
+ * Build the controller.
+ *
+ * One function, one loop: every event goes through {@link dispatch}, which
+ * reduces, publishes, and then performs whichever of the two effects the
+ * transition asked for. There is no other path that mutates state, which is
+ * what makes "a stale response cannot win" enforceable — the check lives in
+ * the reducer and every response arrives through here.
+ */
+export function createSearch(opts: SearchOptions): SearchHandle {
+  let state = initialSearchState();
+
+  const dispatch = (event: SearchEvent): void => {
+    const next: SearchTransition = reduceSearch(state, event);
+    state = next.state;
+    opts.onChange(state);
+
+    if (next.schedule !== null) opts.delay(() => dispatch({ type: "tick", now: opts.now() }), next.schedule);
+
+    const request = next.request;
+    if (request === null) return;
+    // Fire and forget: `api.ts` returns failures as values, so there is
+    // nothing to reject and nothing to catch. `void` documents the floating
+    // promise rather than hiding it — the same shape `workspace.ts` uses.
+    void (async () => {
+      const result = await fetchSearch(opts.fetch, request.query);
+      dispatch(
+        result.ok
+          ? { type: "response", seq: request.seq, query: request.query, hits: result.data.hits }
+          : { type: "failed", seq: request.seq },
+      );
+    })();
+  };
+
+  return {
+    state: () => state,
+    setQuery: (query) => dispatch({ type: "query", query, now: opts.now() }),
+    setCursor: (cursor) => dispatch({ type: "cursor", cursor }),
+    dismiss: () => dispatch({ type: "dismiss" }),
+  };
+}

package/src/web/client/shell/Columns.tsx

@@ -0,0 +1,161 @@
+/**
+ * The three-column grid, its dividers and the context rail
+ * (weave-workspace §1.2).
+ *
+ * The one interesting line is the `useLayoutEffect`: column widths reach the
+ * DOM as **custom properties**, written through `applyVars` →
+ * `style.setProperty`. That is the CSSOM path, which `style-src 'nonce-…'`
+ * does not govern — see `cssvars.ts` for the verified reasoning — and it
+ * leaves the actual `grid-template-columns` rule in the nonce'd stylesheet
+ * where it can be read.
+ *
+ * `useLayoutEffect` rather than `useEffect` so the widths land before paint;
+ * with `useEffect` the first frame renders at whatever the CSS fallback says
+ * and then jumps.
+ *
+ * The column/divider pairing is {@link columnSlots}, not an index check here:
+ * it is breakpoint-sensitive and therefore worth a test.
+ *
+ * All three columns are built as of P3, so {@link Column} dispatches on the
+ * column id. That ternary chain is the one piece of branching in the file and
+ * it is a *routing* decision, not a product one: each arm is a bare element,
+ * and everything those components then decide lives in their own `.model.ts`.
+ */
+
+import { Fragment } from "preact";
+import { useLayoutEffect, useRef } from "preact/hooks";
+import { Graph } from "../graph/Graph";
+import type { PositionStorage } from "../graph/positions";
+import type { RendererFactory } from "../graph/renderer";
+import type { SchemeHost } from "../graph/scheme";
+import type { EditorEvent, EditorPrompt, EditorToolbar } from "../note/editor.model";
+import { Note } from "../note/Note";
+import { Tree } from "../tree/Tree";
+import type { GraphPayload, NotePayload } from "../../shared/wire";
+import { applyVars } from "./cssvars";
+import type { ColumnId, DividerId, ResolvedColumn } from "./layout.model";
+import { columnVars } from "./layout.model";
+import { ContextRail } from "./ContextRail";
+import { Divider } from "./Divider";
+import type { ColumnSlot } from "./shell.model";
+import { columnSlots, emptyStateFor } from "./shell.model";
+
+export interface ColumnsProps {
+  resolved: readonly ResolvedColumn[];
+  onDown: (divider: DividerId, clientX: number, pointerId: number) => void;
+  onMove: (clientX: number) => void;
+  onUp: () => void;
+  onKey: (divider: DividerId, key: string) => void;
+  /** The §1.3 context bus, as the columns see it. */
+  graph: GraphPayload | null;
+  note: NotePayload | null;
+  selectedId: string | null;
+  /**
+   * The §1.3 context bus.
+   *
+   * Takes `string | null` because the graph can *clear* the selection — a
+   * click on empty stage — and no other column can. `workspace.ts`'s `select`
+   * has always accepted `null`; this prop was merely narrower than the thing
+   * behind it. The tree, the note column and the rail pass a `string`, which
+   * a handler accepting the wider type takes without a cast.
+   */
+  onSelect: (id: string | null) => void;
+  /** Epoch ms for relative times, read once per render by the shell. */
+  now: number;
+  /**
+   * The graph column's three injected ports (§7.5, §10).
+   *
+   * Threaded through rather than imported by `Graph.tsx` for the reason
+   * `api.dom.ts` exists: `createSigmaRenderer` imports sigma, which is a
+   * `ReferenceError` outside a browser, so the module that names it must stay
+   * reachable only from a `.tsx` entry point.
+   */
+  renderer: RendererFactory;
+  storage: PositionStorage;
+  host: SchemeHost;
+  /** Slot the graph column fills with its `fit`, for the global `g` key. */
+  fit: { current: (() => void) | null };
+  /**
+   * The note editor's view model (§11 P5).
+   *
+   * Derived by the shell from the one `EditorHandle`, because the editor's
+   * state outlives the note column's mount: below 800 px the column can be
+   * unmounted by a resize, and an editor owned by the component would lose
+   * an unsaved draft to a window drag.
+   */
+  toolbar: EditorToolbar | null;
+  prompt: EditorPrompt | null;
+  draft: string;
+  send: (event: EditorEvent) => void;
+}
+
+/** One column: a titled region and whichever surface fills it. */
+function Column({ id, props }: { id: ColumnId; props: ColumnsProps }) {
+  const copy = emptyStateFor(id);
+  return (
+    <section class={`weave-col weave-col-${id}`} aria-label={copy.title}>
+      <h2 class="weave-col-title">{copy.title}</h2>
+      {id === "tree" ? <Tree graph={props.graph} selectedId={props.selectedId} onSelect={props.onSelect} now={props.now} /> : null}
+      {id === "note" ? (
+        <Note
+          note={props.note}
+          graph={props.graph}
+          selectedId={props.selectedId}
+          onSelect={props.onSelect}
+          now={props.now}
+          toolbar={props.toolbar}
+          prompt={props.prompt}
+          draft={props.draft}
+          send={props.send}
+        />
+      ) : null}
+      {id === "graph" ? (
+        <Graph
+          graph={props.graph}
+          selectedId={props.selectedId}
+          onSelect={props.onSelect}
+          renderer={props.renderer}
+          storage={props.storage}
+          host={props.host}
+          fit={props.fit}
+        />
+      ) : null}
+      {id === "graph" ? <ContextRail graph={props.graph} selectedId={props.selectedId} onSelect={props.onSelect} /> : null}
+    </section>
+  );
+}
+
+/** A column and, where one follows it, its divider. */
+function Slot({ slot, props }: { slot: ColumnSlot; props: ColumnsProps }) {
+  const divider = slot.divider;
+  return (
+    <Fragment>
+      <Column id={slot.column.id} props={props} />
+      {divider === null ? null : (
+        <Divider
+          id={divider}
+          label={`Resize ${slot.column.id} column`}
+          onDown={(x, pointerId) => props.onDown(divider, x, pointerId)}
+          onMove={props.onMove}
+          onUp={props.onUp}
+          onKey={(key) => props.onKey(divider, key)}
+        />
+      )}
+    </Fragment>
+  );
+}
+
+export function Columns(props: ColumnsProps) {
+  const grid = useRef<HTMLDivElement | null>(null);
+  useLayoutEffect(() => {
+    applyVars(grid.current, columnVars(props.resolved));
+  }, [props.resolved]);
+
+  return (
+    <div class="weave-grid" ref={grid} data-columns={props.resolved.length}>
+      {columnSlots(props.resolved).map((slot) => (
+        <Slot key={slot.column.id} slot={slot} props={props} />
+      ))}
+    </div>
+  );
+}

package/src/web/client/shell/ContextRail.tsx

@@ -0,0 +1,87 @@
+/**
+ * The context rail beneath the graph column (weave-workspace §1.1, §1.2, P2.5).
+ *
+ * LINKS, BACKLINKS, TAGS and MENTIONS for whatever is selected — §1.1's
+ * "bring related information into the current view", with every entry
+ * clickable and nothing requiring a navigation to see.
+ *
+ * Props in, JSX out. `context.model.ts` decides which groups exist, which
+ * rows they hold, what each row is labelled and what it selects; this renders
+ * the result.
+ */
+
+import type { ContextGroup, ContextRow, TagGroupRow } from "../context/context.model";
+import { contextModel } from "../context/context.model";
+import type { GraphPayload } from "../../shared/wire";
+import { CONTEXT_EMPTY } from "./shell.model";
+
+export interface ContextRailProps {
+  graph: GraphPayload | null;
+  selectedId: string | null;
+  onSelect: (id: string) => void;
+}
+
+function Row({ row, onSelect }: { row: ContextRow; onSelect: () => void }) {
+  return (
+    <li class={`weave-ctx-row${row.selected ? " weave-row-on" : ""}`}>
+      <button type="button" class="weave-ctx-link" onClick={onSelect}>
+        <span class="weave-kind" aria-hidden="true">
+          {row.kindGlyph}
+        </span>
+        <span class={`weave-prov weave-prov-${row.provenance ?? "none"}`} title={row.provenanceTitle}>
+          {row.provenanceGlyph}
+        </span>
+        <span class="weave-label">{row.label}</span>
+      </button>
+    </li>
+  );
+}
+
+function Group({ group, onSelect }: { group: ContextGroup; onSelect: (id: string) => void }) {
+  return (
+    <section class="weave-ctx-group">
+      <h4 class="weave-ctx-heading">{group.heading}</h4>
+      <ul class="weave-ctx-rows">
+        {group.rows.map((row) => (
+          <Row key={row.id} row={row} onSelect={() => onSelect(row.target)} />
+        ))}
+      </ul>
+    </section>
+  );
+}
+
+function Tag({ tag, onSelect }: { tag: TagGroupRow; onSelect: (id: string) => void }) {
+  return (
+    <li class="weave-ctx-tag">
+      <span class="weave-tag">#{tag.tag}</span>
+      <ul class="weave-ctx-rows">
+        {tag.siblings.map((row) => (
+          <Row key={row.id} row={row} onSelect={() => onSelect(row.target)} />
+        ))}
+      </ul>
+    </li>
+  );
+}
+
+export function ContextRail(props: ContextRailProps) {
+  const model = contextModel(props.graph, props.selectedId);
+  return (
+    <div class="weave-rail" aria-label={CONTEXT_EMPTY.title}>
+      <h2 class="weave-col-title">{CONTEXT_EMPTY.title}</h2>
+      {model.empty === null ? null : <p class="weave-ctx-empty">{model.empty}</p>}
+      {model.groups.map((group) => (
+        <Group key={group.heading} group={group} onSelect={props.onSelect} />
+      ))}
+      {model.tags.length === 0 ? null : (
+        <section class="weave-ctx-group">
+          <h4 class="weave-ctx-heading">TAGS</h4>
+          <ul class="weave-ctx-tags">
+            {model.tags.map((tag) => (
+              <Tag key={tag.tag} tag={tag} onSelect={props.onSelect} />
+            ))}
+          </ul>
+        </section>
+      )}
+    </div>
+  );
+}

package/src/web/client/shell/Divider.tsx

@@ -0,0 +1,44 @@
+/**
+ * A drag handle between two columns (weave-workspace §1.2).
+ *
+ * All four handlers forward straight to callbacks the shell supplies; the
+ * arithmetic is in `drag.model.ts` and `layout.model.ts`. The ARIA role is
+ * `separator` with `tabindex={0}` so the divider is reachable and operable
+ * from the keyboard, which §11's P4 requires of the whole workspace and which
+ * is far cheaper to do now than to retrofit.
+ */
+
+import type { DividerId } from "./layout.model";
+
+export interface DividerProps {
+  id: DividerId;
+  label: string;
+  onDown: (clientX: number, pointerId: number) => void;
+  onMove: (clientX: number) => void;
+  onUp: () => void;
+  onKey: (key: string) => void;
+}
+
+export function Divider(props: DividerProps) {
+  return (
+    <div
+      class="weave-divider"
+      role="separator"
+      aria-orientation="vertical"
+      aria-label={props.label}
+      tabIndex={0}
+      onPointerDown={(event) => {
+        // Capture, so a fast drag that outruns the 1 px handle keeps
+        // delivering moves here instead of to whatever is under the pointer.
+        event.currentTarget.setPointerCapture(event.pointerId);
+        props.onDown(event.clientX, event.pointerId);
+      }}
+      onPointerMove={(event) => props.onMove(event.clientX)}
+      onPointerUp={(event) => {
+        event.currentTarget.releasePointerCapture(event.pointerId);
+        props.onUp();
+      }}
+      onKeyDown={(event) => props.onKey(event.key)}
+    />
+  );
+}

package/src/web/client/shell/FocusTrap.tsx

@@ -0,0 +1,56 @@
+/**
+ * The DOM half of the focus trap (weave-workspace P4, §10).
+ *
+ * `focus.model.ts` decides *which* index Tab should land on; this hook does
+ * the three things that require a real document and cannot be decided:
+ * remember what was focused, focus the dialog, and put focus back on unmount.
+ * There is no branch here that `trapTarget` and `restoreFocus` do not already
+ * own — the `?? null`s are DOM nullability, not decisions.
+ *
+ * Isolated in a `.tsx` for `renderer.dom.ts`'s reason: it names
+ * `document.activeElement` and `HTMLElement`, which do not exist in the root
+ * `tsconfig.json` project, so anything importing it can only be compiled by
+ * `tsconfig.web.json`.
+ */
+
+import { useEffect, useRef } from "preact/hooks";
+import { FOCUSABLE_SELECTOR, isTrapTab, restoreFocus, trapTarget } from "./focus.model";
+
+/** What {@link useFocusTrap} hands back to the dialog. */
+export interface FocusTrapHandle {
+  /** Put on the dialog element. */
+  readonly ref: { current: HTMLElement | null };
+  /** Call from the dialog's `onKeyDown`. Returns whether it consumed the key. */
+  onKeyDown(event: KeyboardEvent): boolean;
+}
+
+/**
+ * Trap focus inside an element while it is mounted, and restore it after.
+ *
+ * The dialog itself is focused on mount rather than its first control,
+ * deliberately: a screen reader announces the dialog's `aria-label` and role
+ * on arrival, which a jump straight to the input would skip. `trapTarget`
+ * handles the resulting `at === -1` explicitly for exactly this case.
+ */
+export function useFocusTrap(): FocusTrapHandle {
+  const ref = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    const previous = document.activeElement;
+    ref.current?.focus();
+    return () => void restoreFocus(previous instanceof HTMLElement ? previous : null);
+  }, []);
+
+  return {
+    ref,
+    onKeyDown(event) {
+      if (!isTrapTab(event.key, event.ctrlKey, event.metaKey, event.altKey)) return false;
+      const items = [...(ref.current?.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR) ?? [])];
+      const target = trapTarget(items.length, items.indexOf(document.activeElement as HTMLElement), event.shiftKey);
+      if (target === null) return false;
+      event.preventDefault();
+      items[target]?.focus();
+      return true;
+    },
+  };
+}

package/src/web/client/shell/Header.tsx

@@ -0,0 +1,54 @@
+/**
+ * The header bar (weave-workspace §1.2).
+ *
+ * Title, the `⌘K` search button, the `vault:N · repo:… · N nodes` summary,
+ * the refresh button and the connection dot. Every string and every tone
+ * comes from `shell.model.ts`.
+ *
+ * The search control was `disabled` through P1–P3 because search was P4 and
+ * an affordance that looks live but is not would be the dishonest option. P4
+ * landed, so it is live — and it is a `<button>`, not an `<input>`: the
+ * palette owns the only text field in the workspace, and a header box you
+ * could type into whose contents were then thrown away when the overlay
+ * opened would be a worse lie than the disabled version it replaced.
+ */
+
+import type { ConnectionView, HeaderSummary } from "./shell.model";
+import { SEARCH_PLACEHOLDER, searchHint, summaryParts } from "./shell.model";
+
+export interface HeaderProps {
+  summary: HeaderSummary;
+  connection: ConnectionView;
+  shortcut: string;
+  onRefresh: () => void;
+  /** Opens the ⌘K palette. The same action the global key performs. */
+  onSearch: () => void;
+}
+
+export function Header(props: HeaderProps) {
+  return (
+    <header class="weave-header">
+      <span class="weave-brand">🧵 pi-weave</span>
+      <button type="button" class="weave-search" title={searchHint(props.shortcut)} onClick={props.onSearch}>
+        <span class="weave-search-text">{SEARCH_PLACEHOLDER}</span>
+        <kbd>{props.shortcut}</kbd>
+      </button>
+      <span class="weave-summary">
+        {summaryParts(props.summary).map((part) => (
+          <span key={part} class="weave-summary-part">
+            {part}
+          </span>
+        ))}
+      </span>
+      <button type="button" class="weave-refresh" onClick={props.onRefresh} title="Refetch everything">
+        ⟳
+      </button>
+      <span class={`weave-conn weave-conn-${props.connection.tone}`} title={props.connection.hint}>
+        <span class="weave-conn-dot" aria-hidden="true">
+          ●
+        </span>
+        {props.connection.label}
+      </span>
+    </header>
+  );
+}

package/src/web/client/shell/HelpOverlay.tsx

@@ -0,0 +1,70 @@
+/**
+ * The `?` keyboard-shortcut sheet (weave-workspace §11 P4).
+ *
+ * Props in, JSX out. The rows come from `keyHelp` in `keys.model.ts` — the
+ * same module the map itself is built from, so the sheet cannot document a
+ * key the code does not implement — and the trap is `useFocusTrap`. There is
+ * no branch in this file.
+ *
+ * `Escape` is not handled here: the global listener already answers it with
+ * `closeOverlay` whenever an overlay is open, and a second handler claiming
+ * the same key is how a dialog ends up closing twice.
+ */
+
+import { useFocusTrap } from "./FocusTrap";
+import type { KeyHelpGroup } from "./keys.model";
+import { HELP_HINT, HELP_TITLE, keyHelp } from "./keys.model";
+
+export interface HelpOverlayProps {
+  /** `⌘K` or `Ctrl K`, from `searchShortcut`. */
+  shortcut: string;
+  onClose: () => void;
+}
+
+function Group({ group }: { group: KeyHelpGroup }) {
+  return (
+    <div>
+      <p class="weave-key-group">{group.title}</p>
+      {group.entries.map((entry) => (
+        <div key={entry.combo} class="weave-key-row">
+          <kbd class="weave-key-combo">{entry.combo}</kbd>
+          <span class="weave-key-what">{entry.what}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export function HelpOverlay(props: HelpOverlayProps) {
+  const trap = useFocusTrap();
+  // `⌘K` reduced to `⌘` / `Ctrl `: the sheet composes its own combinations.
+  const cmd = props.shortcut.slice(0, -1);
+
+  return (
+    <div class="weave-scrim" onClick={props.onClose}>
+      <div
+        class="weave-help"
+        role="dialog"
+        aria-modal="true"
+        aria-label={HELP_TITLE}
+        tabIndex={-1}
+        ref={trap.ref as { current: HTMLDivElement | null }}
+        onClick={(event) => event.stopPropagation()}
+        onKeyDown={(event) => void trap.onKeyDown(event as unknown as KeyboardEvent)}
+      >
+        <h2 class="weave-help-title">{HELP_TITLE}</h2>
+        <div class="weave-keys">
+          {keyHelp(cmd).map((group) => (
+            <Group key={group.title} group={group} />
+          ))}
+        </div>
+        <p class="weave-help-foot">
+          <button type="button" class="weave-chip" onClick={props.onClose}>
+            close
+          </button>
+          <span class="weave-help-hint">{HELP_HINT}</span>
+        </p>
+      </div>
+    </div>
+  );
+}