cursedbelt 5.58.0 → 5.59.0

package/src/componentCssReadsAreDeclared.spec.ts

@@ -0,0 +1,62 @@
+/**
+ * Every bare `var(--x)` a component's plain stylesheet reads must be a property the belt declares.
+ *
+ * ── The measurement this exists because of (2026-10-05, forge task desk-split-pane-tab-dragging) ─
+ * `pointerDrag.css` (5.59.0, first cut) read `z-index: var(--cb-dragghost-z)`, a name only
+ * `DragGhost`'s inline style set. The belt's gate was green, e2e included. desk's
+ * `test/build/belt-tokens.test.ts` went red on it after the belt had landed: an app's built
+ * stylesheet must define whatever it reads with nothing behind it, and a name set only from a
+ * `style` prop is defined nowhere a stylesheet can see. Every app that folds the belt's CSS and
+ * runs that check would meet it the same way, one app at a time.
+ *
+ * ── The rule ─────────────────────────────────────────────────────────────────────────────
+ * In `src/react/**\/*.css`, a `var()` WITHOUT a fallback must name a property some belt stylesheet
+ * declares (`theme.css`'s tokens, or the component's own rule). A value the component sets inline
+ * gets a fallback (`var(--cb-panesplit-share, 1)`) or a theme token (`var(--z-popover, 1100)`).
+ */
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { Glob } from 'bun';
+
+const ROOT = new URL('..', import.meta.url).pathname;
+
+const withoutComments = (css: string) => css.replace(/\/\*[\s\S]*?\*\//g, '');
+
+/** Every custom property a stylesheet declares. */
+function declaredIn(css: string): Set<string> {
+  return new Set([...withoutComments(css).matchAll(/(--[a-zA-Z0-9-]+)\s*:/g)].map((m) => m[1] as string));
+}
+
+/** The bare `var()` reads in `css` whose name `declared` does not hold. */
+function undeclaredBareReads(css: string, declared: Set<string>): string[] {
+  const names = [...withoutComments(css).matchAll(/var\(\s*(--[a-zA-Z0-9-]+)\s*\)/g)].map((m) => m[1] as string);
+  return [...new Set(names.filter((name) => !declared.has(name)))].sort();
+}
+
+describe('undeclaredBareReads', () => {
+  test('a bare read of a name only an inline style sets is caught — the 5.59.0 ghost', () => {
+    expect(undeclaredBareReads('.g { z-index: var(--cb-dragghost-z); }', new Set(['--z-popover']))).toEqual(['--cb-dragghost-z']);
+  });
+
+  test('a fallback, a declared token, or a commented-out read is not a dependency', () => {
+    const css = '/* var(--gone) */ .g { --own: 1; z-index: var(--z-popover); flex: var(--share, 1) 1 0; order: var(--own); }';
+    expect(undeclaredBareReads(css, new Set([...declaredIn(css), '--z-popover']))).toEqual([]);
+  });
+});
+
+describe("the belt's component stylesheets", () => {
+  const all = [...new Glob('src/**/*.css').scanSync(ROOT)];
+  const declared = new Set(all.flatMap((file) => [...declaredIn(readFileSync(`${ROOT}${file}`, 'utf8'))]));
+  const components = all.filter((file) => file.startsWith('src/react/'));
+
+  test('the sweep measured something', () => {
+    expect(components.length).toBeGreaterThan(10);
+    expect(declared.has('--z-popover')).toBe(true);
+  });
+
+  for (const file of components) {
+    test(`${file} reads nothing bare that no belt stylesheet declares`, () => {
+      expect(undeclaredBareReads(readFileSync(`${ROOT}${file}`, 'utf8'), declared)).toEqual([]);
+    });
+  }
+});

package/src/react/components/PaneSplit.spec.tsx

@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { PaneSplit, type PaneSplitNode } from './PaneSplit.js';
+
+afterEach(cleanup);
+
+// desk-split-pane-tab-dragging: desk's WorkspaceSplit, graduated. The drawn picture (square panes,
+// one hairline) is measured in desk's real browser; the tree and the seam arithmetic are here.
+const tree: PaneSplitNode<{ id: string }> = {
+  kind: 'split',
+  direction: 'column',
+  sizes: [0.5, 0.5],
+  children: [
+    {
+      kind: 'split',
+      direction: 'row',
+      sizes: [0.5, 0.5],
+      children: [
+        { kind: 'leaf', pane: { id: 'p1' } },
+        { kind: 'leaf', pane: { id: 'p2' } },
+      ],
+    },
+    { kind: 'leaf', pane: { id: 'p3' } },
+  ],
+};
+
+function draw(onResize = mock()) {
+  render(<PaneSplit node={tree} paneKey={(pane) => pane.id} renderPane={(pane) => <section aria-label={pane.id} />} onResize={onResize} />);
+  return onResize;
+}
+
+describe('PaneSplit', () => {
+  test('draws every leaf, with one seam between each pair of siblings', () => {
+    draw();
+    expect(['p1', 'p2', 'p3'].map((id) => screen.getByLabelText(id).tagName)).toEqual(['SECTION', 'SECTION', 'SECTION']);
+    const seams = screen.getAllByRole('separator');
+    expect(seams.map((seam) => seam.getAttribute('aria-orientation'))).toEqual(['vertical', 'horizontal']);
+  });
+
+  test('an arrow key moves only its own seam, and reports the split at its path', () => {
+    const onResize = draw();
+    const [inner] = screen.getAllByRole('separator');
+    fireEvent.keyDown(inner!, { key: 'ArrowRight' });
+    expect(onResize).toHaveBeenCalledTimes(1);
+    const [path, sizes] = onResize.mock.calls[0]!;
+    expect(path).toEqual([0]);
+    expect(sizes[0]).toBeCloseTo(0.52);
+    expect(sizes[1]).toBeCloseTo(0.48);
+  });
+
+  test('Home and End stop at the smallest share a pane may have', () => {
+    const onResize = draw();
+    const [, outer] = screen.getAllByRole('separator');
+    fireEvent.keyDown(outer!, { key: 'Home' });
+    expect(onResize.mock.calls[0]![0]).toEqual([]);
+    expect(onResize.mock.calls[0]![1][0]).toBeCloseTo(0.12);
+    fireEvent.keyDown(outer!, { key: 'End' });
+    expect(onResize.mock.calls[1]![1][0]).toBeCloseTo(0.88);
+  });
+});

package/src/react/components/PaneSplit.tsx

@@ -0,0 +1,206 @@
+/**
+ * `PaneSplit` — an editor's pane tree, drawn VS Code's way: panes that meet edge to edge, square,
+ * with one hairline between them.
+ *
+ * Graduated from desk's `WorkspaceSplit` on the owner's word: *"Panels and panes should be separated
+ * by sharp corners and thin border lines just like they are in vscode"* — and *"since these changes
+ * apply to layouts and cards they should be changed in cb and should impact desk through cb"*.
+ *
+ * The model is the app's — a tree of leaves and splits, each split carrying the fractions of its
+ * children. This component is only geometry: flex tracks, one seam between each pair of children,
+ * and the arithmetic that turns a pointer into a pair of fractions. Unlike `PanelGrid` it owns no
+ * sizes and persists nothing, which is what an app that stores its layout as a setting needs.
+ *
+ * 🔴 **The seam is keyboard-operable.** Arrow keys move it by 2%, Home/End take it to the bounds.
+ *
+ * 🔴 **The hit strip lives inside the seam's own track** — a real flex item, never a bar hung over
+ * the boundary. An invisible strip centred on the seam sits over the first pixels of the pane beside
+ * it and swallows clicks nobody aimed at it (desk's file `21`, where a 44px hit area ate a fill
+ * handle). So the track is a few pixels wide for the hand, painted the panes' own ground
+ * (`--cb-panesplit-ground`) with the hairline drawn down its middle: to the eye, two panes and one
+ * line, which is VS Code's picture; to the pointer, a target that touches no pane.
+ *
+ * Plain CSS (`paneSplit.css`), prefix `cb-panesplit`, so it draws in an app with no Tailwind pass.
+ */
+
+import type { CSSProperties, JSX, KeyboardEvent as ReactKeyboardEvent, PointerEvent as ReactPointerEvent } from 'react';
+import { useCallback, useRef } from 'react';
+import './paneSplit.css';
+
+export type PaneSplitDirection = 'row' | 'column';
+
+export type PaneSplitNode<P> =
+  | { kind: 'leaf'; pane: P }
+  | { kind: 'split'; direction: PaneSplitDirection; sizes: readonly number[]; children: readonly PaneSplitNode<P>[] };
+
+/** Where a node sits in the tree: the child index at each level, from the root. */
+export type PaneSplitPath = readonly number[];
+
+export interface PaneSplitProps<P> {
+  node: PaneSplitNode<P>;
+  /** A key unique across the whole tree — what keeps a pane's subtree when its siblings close. */
+  paneKey: (pane: P) => string;
+  renderPane: (pane: P) => JSX.Element;
+  /** A seam moved: the split at `path` now has these fractions. */
+  onResize: (path: PaneSplitPath, sizes: number[]) => void;
+  /** The smallest share of an axis a pane can be dragged down to. Default 0.12. */
+  minFraction?: number;
+  /** Where `node` sits — only for a tree drawn from below its root. */
+  path?: PaneSplitPath;
+}
+
+const DEFAULT_MIN_FRACTION = 0.12;
+
+/**
+ * A key for a child that follows its content rather than its position: closing a pane in the middle
+ * of a row shifts every later child's index, and `key={index}` would hand React the wrong subtree.
+ */
+function childKey<P>(node: PaneSplitNode<P>, paneKey: (pane: P) => string): string {
+  if (node.kind === 'leaf') return paneKey(node.pane);
+  return node.children.map((child) => childKey(child, paneKey)).join('|');
+}
+
+export function PaneSplit<P>(props: PaneSplitProps<P>): JSX.Element {
+  const { node } = props;
+  if (node.kind === 'leaf') return props.renderPane(node.pane);
+  return <SplitNode {...props} node={node} path={props.path ?? []} />;
+}
+
+function SplitNode<P>({
+  node,
+  path,
+  paneKey,
+  renderPane,
+  onResize,
+  minFraction = DEFAULT_MIN_FRACTION,
+}: PaneSplitProps<P> & { node: Extract<PaneSplitNode<P>, { kind: 'split' }>; path: PaneSplitPath }): JSX.Element {
+  const frame = useRef<HTMLDivElement>(null);
+  const dragging = useRef<number | null>(null);
+
+  /** Set the share of the pair either side of seam `index`; only those two panes move. */
+  const setShare = useCallback(
+    (index: number, share: number) => {
+      const pair = (node.sizes[index] ?? 0) + (node.sizes[index + 1] ?? 0);
+      if (pair <= 0) return;
+      const bounded = Math.min(Math.max(share, minFraction), 1 - minFraction);
+      const sizes = [...node.sizes];
+      sizes[index] = pair * bounded;
+      sizes[index + 1] = pair * (1 - bounded);
+      onResize(path, sizes);
+    },
+    [node.sizes, minFraction, onResize, path],
+  );
+
+  const moveSeam = (index: number, position: number) => {
+    const box = frame.current?.getBoundingClientRect();
+    if (!box) return;
+    const total = node.direction === 'row' ? box.width : box.height;
+    if (total <= 0) return;
+    const offset = (node.direction === 'row' ? position - box.left : position - box.top) / total;
+    const before = node.sizes.slice(0, index).reduce((sum, size) => sum + size, 0);
+    const pair = (node.sizes[index] ?? 0) + (node.sizes[index + 1] ?? 0);
+    if (pair <= 0) return;
+    setShare(index, (offset - before) / pair);
+  };
+
+  const nudgeSeam = (index: number, delta: number) => {
+    const pair = (node.sizes[index] ?? 0) + (node.sizes[index + 1] ?? 0);
+    if (pair <= 0) return;
+    setShare(index, (node.sizes[index] ?? 0) / pair + delta);
+  };
+
+  const onKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>, index: number) => {
+    const back = node.direction === 'row' ? 'ArrowLeft' : 'ArrowUp';
+    const forward = node.direction === 'row' ? 'ArrowRight' : 'ArrowDown';
+    if (event.key === back) nudgeSeam(index, -0.02);
+    else if (event.key === forward) nudgeSeam(index, 0.02);
+    else if (event.key === 'Home') nudgeSeam(index, -1);
+    else if (event.key === 'End') nudgeSeam(index, 1);
+    else return;
+    event.preventDefault();
+  };
+
+  const onPointerDown = (event: ReactPointerEvent<HTMLDivElement>, index: number) => {
+    if (event.button !== 0) return;
+    dragging.current = index;
+    event.currentTarget.setPointerCapture(event.pointerId);
+    event.preventDefault();
+  };
+
+  const onPointerMove = (event: ReactPointerEvent<HTMLDivElement>) => {
+    if (dragging.current === null) return;
+    moveSeam(dragging.current, node.direction === 'row' ? event.clientX : event.clientY);
+  };
+
+  const endDrag = (event: ReactPointerEvent<HTMLDivElement>) => {
+    if (dragging.current === null) return;
+    dragging.current = null;
+    if (event.currentTarget.hasPointerCapture?.(event.pointerId)) event.currentTarget.releasePointerCapture(event.pointerId);
+  };
+
+  const minPercent = Math.round(minFraction * 100);
+  return (
+    <div className="cb-panesplit" data-direction={node.direction} ref={frame}>
+      {node.children.map((child, index) => (
+        <ChildAndSeam
+          key={childKey(child, paneKey)}
+          last={index === node.children.length - 1}
+          size={node.sizes[index] ?? 1 / node.children.length}
+          seam={{
+            direction: node.direction,
+            percent: Math.round((node.sizes[index] ?? 0) * 100),
+            min: minPercent,
+            max: 100 - minPercent,
+            onKeyDown: (event) => onKeyDown(event, index),
+            onPointerDown: (event) => onPointerDown(event, index),
+            onPointerMove,
+            endDrag,
+          }}
+        >
+          <PaneSplit node={child} path={[...path, index]} paneKey={paneKey} renderPane={renderPane} onResize={onResize} minFraction={minFraction} />
+        </ChildAndSeam>
+      ))}
+    </div>
+  );
+}
+
+interface SeamProps {
+  direction: PaneSplitDirection;
+  percent: number;
+  min: number;
+  max: number;
+  onKeyDown: (event: ReactKeyboardEvent<HTMLDivElement>) => void;
+  onPointerDown: (event: ReactPointerEvent<HTMLDivElement>) => void;
+  onPointerMove: (event: ReactPointerEvent<HTMLDivElement>) => void;
+  endDrag: (event: ReactPointerEvent<HTMLDivElement>) => void;
+}
+
+function ChildAndSeam({ last, size, seam, children }: { last: boolean; size: number; seam: SeamProps; children: JSX.Element }): JSX.Element {
+  return (
+    <>
+      <div className="cb-panesplit__cell" style={{ '--cb-panesplit-share': size } as CSSProperties}>
+        {children}
+      </div>
+      {!last && (
+        // A draggable, keyboard-adjustable divider — an <hr> is a static, non-focusable thematic
+        // break and cannot carry the pointer and keyboard handlers or the aria-valuenow it needs.
+        // biome-ignore lint/a11y/useSemanticElements: see the comment above
+        <div
+          className="cb-panesplit__seam"
+          role="separator"
+          tabIndex={0}
+          aria-orientation={seam.direction === 'row' ? 'vertical' : 'horizontal'}
+          aria-label={seam.direction === 'row' ? 'Width of the pane on the left' : 'Height of the pane above'}
+          aria-valuenow={seam.percent}
+          aria-valuemin={seam.min}
+          aria-valuemax={seam.max}
+          onKeyDown={seam.onKeyDown}
+          onPointerDown={seam.onPointerDown}
+          onPointerMove={seam.onPointerMove}
+          onPointerUp={seam.endDrag}
+          onPointerCancel={seam.endDrag}
+        />
+      )}
+    </>
+  );
+}

package/src/react/components/PointerDrag.spec.tsx

@@ -0,0 +1,108 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { DragGhost, type PointerDragState, type UsePointerDragOptions, usePointerDrag } from './PointerDrag.js';
+
+afterEach(cleanup);
+
+// desk-split-pane-tab-dragging: the gesture's decisions are proved here; that the ghost really
+// follows the pointer across panes is proved in desk's real browser (test/browser/workspace.test.ts).
+function Harness(props: Omit<UsePointerDragOptions<string>, 'onDrop'> & { onDrop?: (state: PointerDragState<string>) => void }) {
+  const { drag, bind } = usePointerDrag<string>({ ...props, onDrop: props.onDrop ?? (() => {}) });
+  return (
+    <div>
+      <button
+        // guardrails-ignore no-raw-action-button: a bare element, so what is under test is the
+        // hook's bindings and nothing a Button adds.
+        type="button"
+        {...bind('tab-a')}
+      >
+        A
+      </button>
+      <DragGhost drag={drag}>ghost of {drag?.item}</DragGhost>
+    </div>
+  );
+}
+
+const press = (pointerType: string, x: number, y: number) => ({ pointerId: 1, pointerType, button: 0, clientX: x, clientY: y });
+
+describe('usePointerDrag', () => {
+  test('a mouse press that never travels past the slop is a tap, and draws no ghost', () => {
+    const onTap = mock();
+    const onDrop = mock();
+    render(<Harness onTap={onTap} onDrop={onDrop} />);
+    const tab = screen.getByRole('button', { name: 'A' });
+    fireEvent.pointerDown(tab, press('mouse', 10, 10));
+    fireEvent.pointerMove(tab, press('mouse', 12, 11));
+    expect(screen.queryByTestId('drag-ghost')).toBeNull();
+    fireEvent.pointerUp(tab, press('mouse', 12, 11));
+    expect(onTap).toHaveBeenCalledWith('tab-a');
+    expect(onDrop).not.toHaveBeenCalled();
+  });
+
+  test('past the slop the ghost follows the pointer, and the release is a drop', () => {
+    const onTap = mock();
+    const onDrop = mock();
+    const onMove = mock();
+    render(<Harness onTap={onTap} onDrop={onDrop} onMove={onMove} />);
+    const tab = screen.getByRole('button', { name: 'A' });
+    fireEvent.pointerDown(tab, press('mouse', 10, 10));
+    fireEvent.pointerMove(tab, press('mouse', 40, 30));
+    fireEvent.pointerMove(tab, press('mouse', 90, 60));
+    const ghost = screen.getByTestId('drag-ghost');
+    expect(ghost.textContent).toBe('ghost of tab-a');
+    // Grabbed at (10,10) of a box at (0,0): the ghost's corner sits that far up-left of the pointer.
+    const grab = (onMove.mock.calls[0]![0] as PointerDragState<string>).grab;
+    expect([ghost.style.getPropertyValue('--cb-dragghost-x'), ghost.style.getPropertyValue('--cb-dragghost-y')]).toEqual([`${90 - grab.x}px`, `${60 - grab.y}px`]);
+    fireEvent.pointerUp(tab, press('mouse', 90, 60));
+    expect(onDrop).toHaveBeenCalledTimes(1);
+    expect((onDrop.mock.calls[0]![0] as PointerDragState<string>).at).toEqual({ x: 90, y: 60 });
+    expect(onTap).not.toHaveBeenCalled();
+    expect(screen.queryByTestId('drag-ghost')).toBeNull();
+  });
+
+  test('a finger that moves before the hold is a scroll — no drag, no tap', () => {
+    const onTap = mock();
+    const onDrop = mock();
+    render(<Harness onTap={onTap} onDrop={onDrop} holdMs={1000} />);
+    const tab = screen.getByRole('button', { name: 'A' });
+    fireEvent.pointerDown(tab, press('touch', 10, 10));
+    fireEvent.pointerMove(tab, press('touch', 60, 10));
+    fireEvent.pointerUp(tab, press('touch', 60, 10));
+    expect(screen.queryByTestId('drag-ghost')).toBeNull();
+    expect(onTap).not.toHaveBeenCalled();
+    expect(onDrop).not.toHaveBeenCalled();
+  });
+
+  test('a finger that rests through the hold drags, and holds the page still while it does', async () => {
+    const onDrop = mock();
+    render(<Harness onDrop={onDrop} holdMs={5} />);
+    const tab = screen.getByRole('button', { name: 'A' });
+    fireEvent.pointerDown(tab, press('touch', 10, 10));
+    await act(() => new Promise((resolve) => setTimeout(resolve, 30)));
+    expect(screen.getByTestId('drag-ghost')).toBeTruthy();
+    const scroll = new Event('touchmove', { cancelable: true });
+    window.dispatchEvent(scroll);
+    expect(scroll.defaultPrevented).toBe(true);
+    fireEvent.pointerMove(tab, press('touch', 80, 40));
+    fireEvent.pointerUp(tab, press('touch', 80, 40));
+    expect(onDrop).toHaveBeenCalledTimes(1);
+    // Released: the page scrolls again.
+    const after = new Event('touchmove', { cancelable: true });
+    window.dispatchEvent(after);
+    expect(after.defaultPrevented).toBe(false);
+  });
+
+  test('Escape abandons a drag — cancelled, never dropped', () => {
+    const onDrop = mock();
+    const onCancel = mock();
+    render(<Harness onDrop={onDrop} onCancel={onCancel} />);
+    const tab = screen.getByRole('button', { name: 'A' });
+    fireEvent.pointerDown(tab, press('mouse', 10, 10));
+    fireEvent.pointerMove(tab, press('mouse', 60, 10));
+    fireEvent.keyDown(window, { key: 'Escape' });
+    expect(onCancel).toHaveBeenCalledTimes(1);
+    expect(screen.queryByTestId('drag-ghost')).toBeNull();
+    fireEvent.pointerUp(tab, press('mouse', 60, 10));
+    expect(onDrop).not.toHaveBeenCalled();
+  });
+});