pi-weave 0.1.12 → 0.1.13

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

@@ -1,107 +0,0 @@
-/**
- * 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/Divider.tsx

@@ -1,44 +0,0 @@
-/**
- * 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/cssvars.ts

@@ -1,70 +0,0 @@
-/**
- * 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

@@ -1,170 +0,0 @@
-/**
- * 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);
-    },
-  };
-}