pi-weave 0.1.7 → 0.1.8

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

@@ -0,0 +1,193 @@
+/**
+ * The workspace shell (weave-workspace §1.2).
+ *
+ * Header, three resizable columns, context rail, status bar. This component
+ * holds the wiring and nothing else — every value it renders comes from a
+ * pure function in `shell.model.ts`, `layout.model.ts` or `drag.model.ts`,
+ * and the fetch/SSE loop is `workspace.ts`. What is left here is hooks:
+ * signals in, callbacks out.
+ *
+ * The three effects, all one-liners over injected units:
+ *
+ *  1. **mount** — `startWorkspace` fetches the graph and opens the stream;
+ *     the returned `stop` is the cleanup, so a hot reload cannot leak a
+ *     socket.
+ *  2. **resize** — `watchViewport` keeps `width` current, because the width
+ *     picks the breakpoint, which decides how many columns exist.
+ *  3. **keys** — `watchKeys` attaches the one global `keydown` listener
+ *     (§11 P4). Its context is read through `live`, because a listener
+ *     registered at mount outlives every render and a captured overlay flag
+ *     would let `⌘K` stack a palette on top of itself.
+ *
+ * Layout persistence is not an effect: `dividerHandlers` writes to
+ * `localStorage` on release and on a keyboard nudge, never per frame.
+ */
+
+import { useEffect, useMemo, useRef, useState } from "preact/hooks";
+import { fetchJson } from "../api.dom";
+import { createSigmaRenderer } from "../graph/renderer.dom";
+import { domEventSource } from "../live";
+import { createEditor, watchUnload, type EditorHandle } from "../note/editor.controller";
+import { editorPrompt, editorToolbar, initialEditorState, shouldBlockUnload } from "../note/editor.model";
+import { SearchPalette } from "../search/SearchPalette";
+import { connection, graph, noteBody, selectedId } from "../state";
+import type { WorkspaceHandle } from "../workspace";
+import { observeNotes, select, startWorkspace } from "../workspace";
+import { Columns } from "./Columns";
+import { dividerHandlers } from "./drag.model";
+import { Header } from "./Header";
+import { HelpOverlay } from "./HelpOverlay";
+import { watchKeys } from "./keys";
+import { focusSelector, runShellAction } from "./keys.model";
+import type { LayoutState } from "./layout.model";
+import { breakpointFor, loadLayout, resolveColumns, saveLayout } from "./layout.model";
+import { StatusBar } from "./StatusBar";
+import type { OverlayId } from "./shell.model";
+import { connectionView, looksApple, searchShortcut, statusBarModel, summarize } from "./shell.model";
+import { watchViewport } from "./viewport";
+
+export interface ShellProps {
+  /** From the page bootstrap. Shown in the status bar. */
+  cwd: string;
+  /** `window.innerWidth` at mount. Injected so the first render is testable. */
+  initialWidth: number;
+  /** `navigator.platform`, for the `⌘K` vs `Ctrl K` hint. */
+  platform: string;
+}
+
+export function Shell(props: ShellProps) {
+  const [width, setWidth] = useState(props.initialWidth);
+  const [overlay, setOverlay] = useState<OverlayId>(null);
+  const [layout, setLayout] = useState<LayoutState>(() => loadLayout(localStorage, props.initialWidth));
+  const [editorState, setEditorState] = useState(initialEditorState);
+  const workspace = useRef<WorkspaceHandle | null>(null);
+  // Filled by the graph column at mount, cleared on unmount. The global `g`
+  // key's only route to the renderer — see `Graph.tsx`'s `fit` prop.
+  const fit = useRef<(() => void) | null>(null);
+  // The gesture and the global key listener read through these so a handler
+  // built on an early render still sees current state — see `DragHost`.
+  const live = useRef({ layout, width, overlay });
+  live.current = { layout, width, overlay };
+
+  // Built once and owned by the shell, not by the note column. The column is
+  // unmounted by a resize below 800 px, and an editor whose lifetime was the
+  // column's would lose an unsaved draft to a window drag.
+  const editor: EditorHandle = useMemo(
+    () => createEditor({ fetch: fetchJson, select: (id) => void select(fetchJson, id), onChange: setEditorState }),
+    [],
+  );
+
+  useEffect(() => {
+    const handle = startWorkspace({ fetch: fetchJson, open: domEventSource });
+    workspace.current = handle;
+    return () => handle.stop();
+  }, []);
+
+  // Every note that arrives, from any of the three directions it can arrive
+  // from (mount, selection, SSE refetch), so the editor can decide whether it
+  // is news or an interruption — see `editor.model.ts`'s header.
+  useEffect(() => observeNotes((payload) => editor.send({ type: "loaded", payload })), []);
+
+  // Read through a thunk, not captured: a listener registered at mount
+  // outlives every render, so a captured state would always look clean and
+  // the guard would be installed but inert.
+  useEffect(() => watchUnload(window, () => shouldBlockUnload(editor.state())), []);
+
+  useEffect(() => watchViewport(window, setWidth), []);
+
+  useEffect(
+    () =>
+      watchKeys(document, {
+        context: () => ({ overlay: live.current.overlay, hasSelection: selectedId.value !== null }),
+        run: (action) =>
+          runShellAction(action, {
+            setOverlay,
+            focusSelector: (selector) => focusSelector(document, selector),
+            fitGraph: () => fit.current?.(),
+            // Through the editor, not straight to `select`: clearing the
+            // selection while a draft is dirty must be refused like any
+            // other navigation, and `Esc` is the easiest way to do it by
+            // accident.
+            clearSelection: () => editor.send({ type: "navigate", id: null }),
+            toggleEdit: () => editor.send({ type: "toggle" }),
+            saveNote: () => editor.send({ type: "save" }),
+          }),
+      }),
+    [],
+  );
+
+  const resolved = useMemo(() => resolveColumns(layout, width, breakpointFor(width)), [layout, width]);
+
+  // Built once: the handlers read state through `live`, so they never go
+  // stale and never need to be rebuilt.
+  const drag = useMemo(
+    () =>
+      dividerHandlers({
+        layout: () => live.current.layout,
+        width: () => live.current.width,
+        setLayout,
+        persist: (next) => void saveLayout(localStorage, next),
+      }),
+    [],
+  );
+
+  return (
+    <>
+      <Header
+        summary={summarize(graph.value)}
+        connection={connectionView(connection.value)}
+        shortcut={searchShortcut(looksApple(props.platform))}
+        onRefresh={() => workspace.current?.refresh()}
+        onSearch={() => setOverlay("search")}
+      />
+      <Columns
+        resolved={resolved}
+        onDown={drag.onDown}
+        onMove={drag.onMove}
+        onUp={drag.onUp}
+        onKey={drag.onKey}
+        graph={graph.value}
+        note={noteBody.value}
+        selectedId={selectedId.value}
+        // Through the editor: a selection made while a draft is dirty is
+        // parked rather than performed, and the column then asks. Every
+        // column's `onSelect` routes here, so there is one guarded door
+        // rather than three that each had to remember.
+        onSelect={(id) => editor.send({ type: "navigate", id })}
+        now={Date.now()}
+        toolbar={editorToolbar(editorState)}
+        prompt={editorPrompt(editorState)}
+        draft={editorState.draft}
+        send={editor.send}
+        // The graph column's three ports (§7.5, §10). Supplied here, at the
+        // one place that is already allowed to name browser globals, so
+        // `Graph.tsx` and everything under it takes its world as parameters.
+        renderer={createSigmaRenderer}
+        storage={localStorage}
+        host={window}
+        fit={fit}
+      />
+      {/*
+        `model.generatedAt`, not `stamp`. The two used to be the same string;
+        since §15.6 `stamp` is a content digest (a hex validator for the ETag
+        and the SSE dedupe) and would render as `a3f9c2…` under a label that
+        says "data as of". `generatedAt` kept the data-as-of job, which is
+        exactly what this bar wants.
+      */}
+      <StatusBar
+        model={statusBarModel(props.cwd, selectedId.value, connection.value, graph.value?.model.generatedAt ?? null)}
+      />
+      {overlay === "search" ? (
+        <SearchPalette
+          graph={graph.value}
+          onSelect={(id) => void select(fetchJson, id)}
+          onClose={() => setOverlay(null)}
+          ports={{ fetch: fetchJson, now: Date.now, delay: (run, ms) => void setTimeout(run, ms) }}
+        />
+      ) : null}
+      {overlay === "help" ? (
+        <HelpOverlay shortcut={searchShortcut(looksApple(props.platform))} onClose={() => setOverlay(null)} />
+      ) : null}
+    </>
+  );
+}

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

@@ -0,0 +1,28 @@
+/**
+ * The status bar (weave-workspace §1.2).
+ *
+ * Working directory, current selection, data-as-of stamp, connection. The
+ * model is built by `statusBarModel`; this renders it.
+ */
+
+import type { StatusBarModel } from "./shell.model";
+import { shortStamp } from "./shell.model";
+
+export function StatusBar({ model }: { model: StatusBarModel }) {
+  return (
+    <footer class="weave-status">
+      <span class="weave-status-cwd" title={model.cwd}>
+        {model.cwd}
+      </span>
+      <span class="weave-status-sel" title="the §1.3 context bus — one signal, every column">
+        {model.selection}
+      </span>
+      <span class="weave-status-stamp" title="data as of">
+        {shortStamp(model.stamp)}
+      </span>
+      <span class={`weave-conn weave-conn-${model.connection.tone}`} title={model.connection.hint}>
+        {model.connection.label}
+      </span>
+    </footer>
+  );
+}

package/src/web/client/shell/cssvars.ts

@@ -0,0 +1,70 @@
+/**
+ * Applying computed layout widths to an element, under a strict CSP
+ * (weave-workspace §5.2).
+ *
+ * ## The constraint, stated precisely
+ *
+ * `page.ts` serves `style-src 'nonce-{N}'` with **no `'unsafe-inline'`**. In
+ * CSP terms that blocks a literal `style="…"` *attribute in the markup the
+ * parser sees*. It does **not** block mutation of an element's
+ * `CSSStyleDeclaration` from script: `el.style.setProperty(...)`,
+ * `el.style.width = …` and `el.style.cssText = …` are CSSOM writes, and CSP
+ * has no hook on them. This is why a strict-CSP app can still have dynamic
+ * layout at all.
+ *
+ * Preact reaches the same place: `setProperty` in `preact/src/diff/props.js`
+ * handles a `style` prop by assigning `dom.style.cssText` for a string, or by
+ * `style.setProperty` / `style[key] = …` for an object. It never calls
+ * `setAttribute("style", …)`. So a `style={{…}}` prop in a component would in
+ * fact survive the CSP — verified in the installed source, not assumed.
+ *
+ * We still do not use one. The widths are written as **custom properties** by
+ * this module, and the nonce'd stylesheet owns the `grid-template-columns`
+ * rule that consumes them. The reason is not CSP but ownership: a `style`
+ * prop would put a second layout implementation in the bundle, competing with
+ * the one in CSS, and the browser's devtools would show a computed width with
+ * no rule to trace it back to. One number per column in, one rule in CSS —
+ * that is the whole contribution.
+ *
+ * ## Why the element is a parameter and the API is one function
+ *
+ * There is no DOM test environment (§10). Everything *decidable* about the
+ * widths already lives in `layout.model.ts` as pure functions returning
+ * `[name, value]` pairs; what remains here is a loop that hands those pairs
+ * to a `setProperty` this module does not own. The port below is that method
+ * and nothing else, so the untestable surface is one line long and a fake is
+ * an object literal.
+ */
+
+/**
+ * The slice of `CSSStyleDeclaration` used to apply a layout.
+ *
+ * A real `HTMLElement.style` satisfies it structurally. Declared here rather
+ * than imported from the DOM lib because this module is compiled by the root
+ * `tsconfig.json` when a test imports it, and that project has no `DOM` lib.
+ */
+export interface StyleTarget {
+  setProperty(property: string, value: string): void;
+}
+
+/** An element with a `style`. `HTMLElement` satisfies it. */
+export interface StyledElement {
+  readonly style: StyleTarget;
+}
+
+/**
+ * Write custom properties onto an element.
+ *
+ * Tolerates a `null` element so the caller — a `useLayoutEffect` holding a
+ * ref — does not need a guard of its own. A ref is `null` on the render
+ * before the element exists and on the one after it is removed, and both are
+ * ordinary rather than exceptional.
+ *
+ * Returns the number of properties written, which is what makes the function
+ * observable in a test without a DOM: `0` for a null element, `n` otherwise.
+ */
+export function applyVars(element: StyledElement | null, vars: readonly (readonly [string, string])[]): number {
+  if (element === null) return 0;
+  for (const [name, value] of vars) element.style.setProperty(name, value);
+  return vars.length;
+}

package/src/web/client/shell/drag.model.ts

@@ -0,0 +1,170 @@
+/**
+ * Divider dragging, as pure state (weave-workspace §1.2).
+ *
+ * `layout.model.ts` already owns the arithmetic — {@link resizeAt} converts a
+ * pixel delta into clamped, normalised fractions. What it does not own is the
+ * *gesture*: where the pointer went down, how far it has travelled since, and
+ * when the result should be persisted. That is this file, and it is separate
+ * for the usual reason — a gesture living inside `Divider.tsx` would be
+ * untestable without a DOM (§10), and a drag that mis-clamps is exactly the
+ * bug a unit test catches and a glance at the screen does not.
+ *
+ * ## Deltas are measured from the gesture's origin, never frame to frame
+ *
+ * A `pointermove` handler that applied `event.movementX` to the current
+ * layout would accumulate error: `resizeAt` clamps, so any movement the clamp
+ * swallowed is lost, and the divider then trails the pointer by however much
+ * was discarded. Storing the layout as it was at `pointerdown` and applying
+ * the *total* offset each time makes the divider track the pointer exactly,
+ * and makes dragging into a wall and back out again return to where it
+ * started rather than to wherever the drift left it.
+ */
+
+import type { DividerId, LayoutState } from "./layout.model";
+import { resizeAt } from "./layout.model";
+
+/**
+ * A gesture in progress.
+ *
+ * `origin` is the pointer x at `pointerdown`; `base` is the layout as it was
+ * at that instant. Both are needed to satisfy the total-offset rule above.
+ */
+export interface DragState {
+  readonly divider: DividerId;
+  readonly origin: number;
+  readonly base: LayoutState;
+  /** `setPointerCapture` id, so the shell can release exactly this pointer. */
+  readonly pointerId: number;
+}
+
+/** Begin a drag. */
+export function beginDrag(divider: DividerId, clientX: number, layout: LayoutState, pointerId: number): DragState {
+  return { divider, origin: clientX, base: layout, pointerId };
+}
+
+/**
+ * The layout for a pointer position during a drag.
+ *
+ * Always derived from `base`, never from the previous frame — see the module
+ * header. `resizeAt` returns its input identically when nothing moved, so a
+ * pointer jittering by a subpixel at a clamped edge produces the same object
+ * and wakes no signal subscribers.
+ */
+export function dragTo(drag: DragState, clientX: number, available: number): LayoutState {
+  return resizeAt(drag.base, drag.divider, clientX - drag.origin, available);
+}
+
+/**
+ * Whether a completed drag actually changed anything.
+ *
+ * The persistence trigger. A click on a divider with no movement is a
+ * `pointerdown`/`pointerup` pair that should not write to `localStorage`, and
+ * a drag that was entirely absorbed by the clamp should not either. Compares
+ * the three fractions rather than object identity, because `resizeAt`
+ * normalises and can return an equal-but-distinct object.
+ */
+export function dragChanged(drag: DragState, final: LayoutState): boolean {
+  const a = drag.base.fractions;
+  const b = final.fractions;
+  return a.tree !== b.tree || a.note !== b.note || a.graph !== b.graph;
+}
+
+/**
+ * The keyboard nudge, in pixels.
+ *
+ * A divider is a `separator` with `tabindex`, so it must be operable from the
+ * keyboard — §11's P4 makes the whole workspace keyboard-drivable, and a
+ * control that can only be dragged is one that has to be retrofitted then. 24
+ * px is a visible step without being a jump.
+ */
+export const NUDGE_PX = 24;
+
+/**
+ * Map an arrow key to a signed nudge, or `0` for any other key.
+ *
+ * Returning `0` rather than `null` lets the caller feed the result straight
+ * into `resizeAt`, which already treats a zero delta as "return the state
+ * unchanged" — one branch instead of two, and the one that exists is already
+ * covered.
+ */
+export function nudgeFor(key: string): number {
+  if (key === "ArrowLeft") return -NUDGE_PX;
+  if (key === "ArrowRight") return NUDGE_PX;
+  return 0;
+}
+
+// --- the gesture, as a unit -----------------------------------------------------
+
+/**
+ * What {@link dividerHandlers} needs from the component around it.
+ *
+ * Accessors rather than values, because a handler installed on one render
+ * must see the layout as it is when the pointer moves, not as it was when the
+ * closure was built. A stale `layout` here is the classic React/Preact
+ * gesture bug: the drag applies to a snapshot and the divider jumps back on
+ * the next render.
+ */
+export interface DragHost {
+  layout(): LayoutState;
+  /** Container width in CSS pixels. */
+  width(): number;
+  /** Publish a new layout (a `setState`). */
+  setLayout(next: LayoutState): void;
+  /** Persist a layout. Called on release and on a keyboard nudge, never per frame. */
+  persist(layout: LayoutState): void;
+}
+
+/** The four callbacks a {@link Divider} needs. */
+export interface DividerHandlers {
+  onDown(divider: DividerId, clientX: number, pointerId: number): void;
+  onMove(clientX: number): void;
+  onUp(): void;
+  onKey(divider: DividerId, key: string): void;
+}
+
+/**
+ * Build the divider gesture handlers over a host.
+ *
+ * This lives here rather than as four `useCallback`s in `Shell.tsx` for the
+ * reason §10 gives: the ordering rules they encode are real logic — persist
+ * on release but not per frame, ignore a move with no gesture in progress,
+ * persist a keyboard nudge immediately because there is no release to wait
+ * for — and logic inside a `.tsx` is logic no test can reach. The component
+ * is left holding a ref and a `setState`.
+ *
+ * The mutable gesture is kept in the closure rather than in component state
+ * on purpose: a `pointermove` at 120 Hz writing to `useState` would rerender
+ * the whole shell on every frame to store a value nothing renders.
+ */
+export function dividerHandlers(host: DragHost): DividerHandlers {
+  let active: DragState | null = null;
+
+  return {
+    onDown(divider, clientX, pointerId) {
+      active = beginDrag(divider, clientX, host.layout(), pointerId);
+    },
+
+    onMove(clientX) {
+      // No gesture in progress: a plain hover over the divider, which fires
+      // `pointermove` just as a drag does.
+      if (active !== null) host.setLayout(dragTo(active, clientX, host.width()));
+    },
+
+    onUp() {
+      const finished = active;
+      active = null;
+      // Persisted only if something actually moved — a click on a divider,
+      // and a drag entirely absorbed by the clamp, both write nothing.
+      if (finished !== null && dragChanged(finished, host.layout())) host.persist(host.layout());
+    },
+
+    onKey(divider, key) {
+      const next = resizeAt(host.layout(), divider, nudgeFor(key), host.width());
+      // `resizeAt` returns its input identically for an unhandled key, so a
+      // `Tab` or an `Enter` on a focused divider costs nothing.
+      if (next === host.layout()) return;
+      host.setLayout(next);
+      host.persist(next);
+    },
+  };
+}

package/src/web/client/shell/focus.model.ts

@@ -0,0 +1,100 @@
+/**
+ * Focus management for the modal surfaces (weave-workspace P4).
+ *
+ * P4's exit criterion is "the whole workspace is drivable without a mouse",
+ * and a dialog that does not trap focus fails it in the most literal way
+ * available: Tab from the last control lands on the header behind the
+ * overlay, the user is now typing into a search box they cannot see, and
+ * `Esc` goes to whatever they landed on. So the palette and the help overlay
+ * both trap, and both restore.
+ *
+ * ## Why this is a model and not three lines in a `useEffect`
+ *
+ * Trapping is arithmetic — "which element is next, given the current one, a
+ * direction, and a wrap" — and arithmetic in a `.tsx` is arithmetic no test
+ * can reach (§10). {@link trapTarget} takes an array of focusables and an
+ * index and returns an index; the component supplies the array from a
+ * `querySelectorAll` and calls `.focus()` on the answer. Everything that can
+ * be wrong is on this side of that line.
+ *
+ * The DOM types are deliberately absent: {@link Focusable} is a one-method
+ * structural port that a real `HTMLElement` satisfies, so this file compiles
+ * under the root `tsconfig.json` (no `DOM` lib) and the tests that import it
+ * need no browser.
+ */
+
+/** The slice of an element this module uses. `HTMLElement` satisfies it. */
+export interface Focusable {
+  focus(): void;
+}
+
+/**
+ * The selector for "things a user can Tab to", inside a dialog.
+ *
+ * `:not([disabled])` matters — a disabled control is not in the tab order,
+ * and including one produces a trap with a dead stop in it. `tabindex="-1"`
+ * is excluded for the same reason: it means *programmatically* focusable,
+ * which is the opposite of what a Tab cycle wants.
+ *
+ * Kept here rather than in the component so the two overlays cannot drift
+ * into two different definitions of what is focusable.
+ */
+export const FOCUSABLE_SELECTOR = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])',
+].join(",");
+
+/**
+ * Where Tab should land next, or `null` to leave the event alone.
+ *
+ * Returns an **index** rather than an element so the whole thing is testable
+ * with an array of numbers if you like. `null` means "not our business":
+ * a trap over zero or one focusable elements has nothing to cycle, and
+ * calling `preventDefault` in that case would strand the user on a dialog
+ * that eats Tab and does nothing with it — strictly worse than an untrapped
+ * one they can at least escape.
+ *
+ * @param count how many focusables the dialog contains
+ * @param at the index of the currently focused one, or `-1` when focus is on
+ *   the dialog container itself (which is where it starts)
+ * @param backwards Shift+Tab
+ */
+export function trapTarget(count: number, at: number, backwards: boolean): number | null {
+  if (count <= 1) return null;
+  // Focus on the container itself: Tab enters at the top, Shift+Tab at the
+  // bottom. Without this the first Tab out of a freshly-opened dialog would
+  // compute from -1 and land on the second control, skipping the input.
+  if (at < 0) return backwards ? count - 1 : 0;
+  if (!backwards) return at === count - 1 ? 0 : at + 1;
+  return at === 0 ? count - 1 : at - 1;
+}
+
+/**
+ * Whether an event is the Tab a trap should act on.
+ *
+ * Modified Tab — ⌘Tab, Ctrl+Tab, Alt+Tab — belongs to the operating system or
+ * the browser's tab strip, and intercepting it is both futile and rude. Shift
+ * is the one modifier that is ours, because Shift+Tab *is* backwards Tab.
+ */
+export function isTrapTab(key: string, ctrl: boolean, meta: boolean, alt: boolean): boolean {
+  return key === "Tab" && !ctrl && !meta && !alt;
+}
+
+/**
+ * Restore focus to where it was before a dialog opened.
+ *
+ * A separate function for one reason: the null check. The previously-focused
+ * element is whatever `document.activeElement` was at open time, and that is
+ * legitimately `null` — a fresh page load where nothing has been clicked, or
+ * a body that was itself focused. Returning `false` rather than throwing lets
+ * the caller stay a one-liner, and the boolean is what the test asserts.
+ */
+export function restoreFocus(previous: Focusable | null): boolean {
+  if (previous === null) return false;
+  previous.focus();
+  return true;
+}