@weasel-js/labkit 1.4.4 → 1.5.0

package/src/lab/fitCheck.ts

@@ -0,0 +1,125 @@
+import { useEffect } from 'react';
+
+/** An element's edges, in the same coordinate space as the bound it is tested against. */
+export interface Edges {
+  top: number;
+  left: number;
+  bottom: number;
+  right: number;
+}
+
+export interface Overshoot<T> {
+  item: T;
+  /** How far past the bound the item reaches, in px, on whichever axis is worse. */
+  by: number;
+  axis: 'x' | 'y';
+}
+
+/** The item reaching furthest past the bottom or right of `bound`. On a tie the
+ *  first item wins, so given document order it names the outermost box. */
+export function findOvershoot<T>(
+  bound: Edges,
+  items: Iterable<{ item: T; edges: Edges }>,
+  tolerance = 1,
+): Overshoot<T> | null {
+  let worst: Overshoot<T> | null = null;
+  for (const { item, edges } of items) {
+    const y = edges.bottom - bound.bottom;
+    const x = edges.right - bound.right;
+    const by = Math.max(x, y);
+    if (by <= tolerance) continue;
+    if (!worst || by > worst.by) worst = { item, by, axis: y >= x ? 'y' : 'x' };
+  }
+  return worst;
+}
+
+function tagAndClasses(el: Element): string {
+  return el.tagName.toLowerCase() + [...el.classList].map((c) => `.${c}`).join('');
+}
+
+/** `div.lk-shell-body` — the tag and classes, which is what a reader greps for.
+ *  A classless element is placed by its nearest classed ancestor. */
+export function describeElement(el: Element): string {
+  if (el.classList.length > 0) return tagAndClasses(el);
+  let up = el.parentElement;
+  while (up && up.classList.length === 0) up = up.parentElement;
+  return up ? `${tagAndClasses(el)} in ${tagAndClasses(up)}` : tagAndClasses(el);
+}
+
+function edgesOf(el: Element): Edges {
+  const r = el.getBoundingClientRect();
+  return { top: r.top, left: r.left, bottom: r.bottom, right: r.right };
+}
+
+function* candidates(root: Element): Iterable<{ item: Element; edges: Edges }> {
+  yield { item: root, edges: edgesOf(root) };
+  for (const el of root.querySelectorAll('*')) yield { item: el, edges: edgesOf(el) };
+}
+
+function overflows(el: Element): boolean {
+  return el.scrollHeight > el.clientHeight + 1 || el.scrollWidth > el.clientWidth + 1;
+}
+
+/** Why a mounted lab scrolls, or null when it fits. The document only counts
+ *  when the lab is what reaches past the viewport, so a lab embedded in a long
+ *  page does not report the page's own scroll. */
+export function explainLabScroll(lab: Element, shellBody: Element): string | null {
+  if (overflows(shellBody)) {
+    const r = shellBody.getBoundingClientRect();
+    const bound = {
+      top: r.top,
+      left: r.left,
+      bottom: r.top + shellBody.clientHeight,
+      right: r.left + shellBody.clientWidth,
+    };
+    const hit = findOvershoot(bound, candidates(shellBody));
+    return hit
+      ? `.lk-shell-body scrolls: ${describeElement(hit.item)} reaches ${Math.round(hit.by)}px past it (${hit.axis})`
+      : '.lk-shell-body scrolls';
+  }
+
+  const doc = document.scrollingElement ?? document.documentElement;
+  if (!overflows(doc)) return null;
+  const r = lab.getBoundingClientRect();
+  const bound = {
+    top: r.top,
+    left: r.left,
+    bottom: r.top + Math.min(r.height, doc.clientHeight),
+    right: r.left + Math.min(r.width, doc.clientWidth),
+  };
+  const hit = findOvershoot(bound, candidates(lab));
+  return hit
+    ? `the page scrolls: ${describeElement(hit.item)} reaches ${Math.round(hit.by)}px past the lab's box (${hit.axis})`
+    : null;
+}
+
+const SETTLE_MS = 300;
+
+/** Dev only: warns once, naming the culprit, when a mounted lab scrolls. */
+export function useLabFitWarning(labBody: Element | null): void {
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'production') return;
+    if (!labBody || typeof ResizeObserver === 'undefined') return;
+    const lab = labBody.closest('.lk-lab');
+    const shellBody = labBody.closest('.lk-shell-body');
+    if (!lab || !shellBody) return;
+
+    // A shrinking window overflows for a frame or two before the workspace
+    // re-lays out, so only overflow that outlasts the resize is reported.
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const observer = new ResizeObserver(() => {
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        const why = explainLabScroll(lab, shellBody);
+        if (!why) return;
+        observer.disconnect();
+        console.warn(`[labkit] <Lab> should fit its container without scrolling, but ${why}.`);
+      }, SETTLE_MS);
+    });
+    for (const el of [document.documentElement, lab, shellBody, labBody]) observer.observe(el);
+    return () => {
+      clearTimeout(timer);
+      observer.disconnect();
+    };
+  }, [labBody]);
+}

package/src/loupe/AGENTS.md

@@ -4,7 +4,7 @@
 on, painted by whichever painter suits the instrument's content.
 
 The magnifier itself is not here. `@weasel-js/loupe` holds the model — aim,
-factor, mode, colour, picking — over a `LoupeSurface` it asks five questions.
+factor, mode, color, picking — over a `LoupeSurface` it asks five questions.
 This directory binds that model to a labkit trial and draws it.
 
 ## Files

package/src/loupe/Loupe.less

@@ -7,7 +7,7 @@
   // Nothing under the lens stops working while it is up: the pan, the wheel and
   // any overlay of the instrument's own keep receiving the pointer.
   pointer-events: none;
-  border: var(--wzl-border-w) solid var(--wzl-border-raised);
+  border: var(--wzl-border-w) solid var(--wzl-border-strong);
   box-shadow: 0 2px 8px var(--wzl-shadow);
   // A painter's ground shows through wherever it draws nothing, and a vector
   // lens leaves the gaps between marks transparent. This is the trial's own

package/src/loupe/canvasLens.ts

@@ -61,7 +61,7 @@ export function lensSourceRect(
 }
 
 /**
- * The colour a stack presents at a point: the topmost visible layer with
+ * The color a stack presents at a point: the topmost visible layer with
  * anything opaque there, or `null` when every layer is transparent — which is
  * the honest answer for a point showing nothing but the workspace behind.
  */

package/src/loupe/types.ts

@@ -43,7 +43,7 @@ export interface LoupeCapability<TS = unknown, TC = unknown> {
   /** Held for a momentary peek while the loupe is off. Default `'Alt'`; `null`
    *  turns hold-to-peek off. Matched against `KeyboardEvent.key`. */
   peekKey?: string | null;
-  /** Called with the colour under the aim, wherever the surface can say. The
+  /** Called with the color under the aim, wherever the surface can say. The
    *  canvas painter reads it back; a DOM loupe has no pixels to sample. */
   onColorChange?: (hex: string) => void;
 }

package/src/loupe/useLoupe.test.tsx

@@ -148,7 +148,7 @@ describe('useLoupe', () => {
     expect(wheel.defaultPrevented).toBe(true);
   });
 
-  it('reports the colour under the aim', () => {
+  it('reports the color under the aim', () => {
     const onColorChange = vi.fn();
     render(
       <Harness sample={(p) => (p.x > 10 ? '#ff0000' : '#00ff00')} onColorChange={onColorChange} />,

package/src/loupe/useLoupe.ts

@@ -14,7 +14,7 @@ export interface UseLoupeOptions {
   hostRef: RefObject<HTMLElement | null>;
   /** Whether the loupe is turned on. Hold-to-peek shows it regardless. */
   enabled: boolean;
-  /** Hex colour at a host point. Omitted, the loupe reports no colour — which
+  /** Hex color at a host point. Omitted, the loupe reports no color — which
    *  is the honest answer for a surface with no pixels to read. */
   sample?: (p: LoupePoint) => string | null;
 }

package/src/passthrough/weasel-ui.ts

@@ -37,6 +37,8 @@ export {
   type ChromaCurve,
   type ChromaCurvePoint,
   ComboBox,
+  type ComboBoxCommit,
+  type ComboBoxFilter,
   ComboBoxItem,
   type ComboBoxItemProps,
   type ComboBoxOption,
@@ -100,6 +102,9 @@ export {
   type LayerStackProps,
   type LogicalMod,
   type LogicalModSpec,
+  MenuButton,
+  type MenuButtonItem,
+  type MenuButtonProps,
   MINUS_SIGN,
   NumberField,
   type NumberFieldProps,
@@ -188,6 +193,10 @@ export {
   type TrackCtx,
   type UseReorderDragListOptions,
   type UseRovingTabIndexOptions,
+  useAsyncOptions,
+  type AsyncOption,
+  type AsyncOptionsResult,
+  type UseAsyncOptionsProps,
   useReorderDragList,
   useRovingTabIndex,
   visiblePrefSubtree,

package/src/primitives/FloatingPanel.stories.tsx

@@ -1,4 +1,6 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import { localStorageAdapter } from '../state/adapters';
+import { Persistence } from '../state/Persistence';
 import { FloatingPanel } from './FloatingPanel';
 import { Legend } from './Legend';
 
@@ -43,4 +45,14 @@ export const HoldingALegend: Story = {
   },
 };
 
-export const Remembered: Story = { args: { storageKey: 'labkit.story.panel' } };
+// Remembered only under a provider; this one keeps it across story reloads.
+export const Remembered: Story = {
+  args: { persist: 'story-panel' },
+  decorators: [
+    (Story) => (
+      <Persistence storageKey="labkit-story" storage={localStorageAdapter}>
+        <Story />
+      </Persistence>
+    ),
+  ],
+};

package/src/primitives/FloatingPanel.test.tsx

@@ -1,5 +1,8 @@
-import { fireEvent, render, screen } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createMemoryAdapter } from '../state/adapters';
+import { labPrefix } from '../state/labRecords';
+import { Persistence } from '../state/Persistence';
 import { FloatingPanel } from './FloatingPanel';
 
 // The shared stub reports one size for every element, which makes the panel and
@@ -219,34 +222,62 @@ describe('FloatingPanel dragging', () => {
 });
 
 describe('FloatingPanel persistence', () => {
-  it('writes its placement under the given key once dragged', () => {
-    const { panel } = renderPanel(<FloatingPanel storageKey="k">x</FloatingPanel>);
+  const PLACE = `${labPrefix('fp')}value:lab:legend`;
+
+  function persisted(backing: Map<string, unknown>, ui: React.ReactElement) {
+    return render(
+      <Persistence storageKey="fp" storage={createMemoryAdapter(backing)}>
+        <div>{ui}</div>
+      </Persistence>,
+    );
+  }
+
+  it('writes its placement under its persist name once dragged', async () => {
+    const backing = new Map<string, unknown>();
+    const { container } = persisted(backing, <FloatingPanel persist="legend">x</FloatingPanel>);
+    await waitFor(() => expect(container.querySelector('.lk-floating-panel')).not.toBeNull());
+    const panel = container.querySelector('.lk-floating-panel') as HTMLElement;
     fireEvent.pointerDown(panel, { clientX: 100, clientY: 100 });
     fireEvent.pointerMove(panel, { clientX: 140, clientY: 160 });
     fireEvent.pointerUp(panel);
-    const stored = JSON.parse(localStorage.getItem('k') ?? 'null');
-    expect(stored).toMatchObject({ x: expect.any(Number), y: expect.any(Number) });
-    expect(stored).toHaveProperty('anchor');
+    await waitFor(() =>
+      expect(backing.get(PLACE)).toMatchObject({ x: expect.any(Number), y: expect.any(Number) }),
+    );
+    expect(backing.get(PLACE)).toHaveProperty('anchor');
   });
 
-  it('restores what it stored on a later mount', () => {
-    localStorage.setItem('k', JSON.stringify({ x: 140, y: 90, anchor: null }));
-    const { panel } = renderPanel(<FloatingPanel storageKey="k">x</FloatingPanel>);
-    expect(panel.style.left).toBe('140px');
+  it('restores what it stored on a later mount', async () => {
+    const backing = new Map<string, unknown>([[PLACE, { x: 140, y: 90, anchor: null }]]);
+    const { container } = persisted(backing, <FloatingPanel persist="legend">x</FloatingPanel>);
+    // Placed only once both boxes are measured, which can land a render later.
+    await waitFor(() =>
+      expect(
+        (container.querySelector('.lk-floating-panel') as HTMLElement | null)?.style.left,
+      ).toBe('140px'),
+    );
+    const panel = container.querySelector('.lk-floating-panel') as HTMLElement;
     expect(panel.style.top).toBe('90px');
   });
 
-  it('writes nothing when no key is given', () => {
-    const { panel } = renderPanel(<FloatingPanel>x</FloatingPanel>);
+  it('writes nothing without a persist name', async () => {
+    const backing = new Map<string, unknown>();
+    const { container, unmount } = persisted(backing, <FloatingPanel>x</FloatingPanel>);
+    await waitFor(() => expect(container.querySelector('.lk-floating-panel')).not.toBeNull());
+    const panel = container.querySelector('.lk-floating-panel') as HTMLElement;
     fireEvent.pointerDown(panel, { clientX: 100, clientY: 100 });
     fireEvent.pointerMove(panel, { clientX: 140, clientY: 160 });
     fireEvent.pointerUp(panel);
-    expect(localStorage.length).toBe(0);
+    unmount();
+    await new Promise((r) => setTimeout(r, 20));
+    expect(backing.size).toBe(0);
   });
 
-  it('survives a corrupt stored value rather than throwing', () => {
-    localStorage.setItem('k', '{{{');
-    expect(() => renderPanel(<FloatingPanel storageKey="k">x</FloatingPanel>)).not.toThrow();
+  it('forgets its placement with no provider above it', () => {
+    const { panel } = renderPanel(<FloatingPanel persist="legend">x</FloatingPanel>);
+    fireEvent.pointerDown(panel, { clientX: 100, clientY: 100 });
+    fireEvent.pointerMove(panel, { clientX: 140, clientY: 160 });
+    fireEvent.pointerUp(panel);
+    expect(localStorage.length).toBe(0);
   });
 });
 

package/src/primitives/FloatingPanel.tsx

@@ -9,6 +9,7 @@ import {
   type FloatingPlacement,
   floatingStrategy,
 } from 'windease';
+import { usePersistedState } from '../state/usePersistedState';
 
 /** The strategy holds a map keyed by item id; a panel is always a lone item. */
 const ITEM_ID = 'panel';
@@ -22,8 +23,10 @@ export interface FloatingPanelProps {
   snapCorners?: readonly Corner[];
   /** Pixels in from a corner when snapped. Default 12. */
   inset?: number;
-  /** localStorage key to remember its position under. Omit to forget on reload. */
-  storageKey?: string;
+  /** Name to remember its position under, through `usePersistedState` — so it
+   *  is remembered only inside a lab or a `<Persistence>`. Omit to forget on
+   *  reload. */
+  persist?: string;
   className?: string;
 }
 
@@ -47,16 +50,6 @@ function isInteractive(target: EventTarget | null): boolean {
   return target.closest('input, button, a, select, textarea, [data-no-drag]') !== null;
 }
 
-function readStored(key: string | undefined): FloatingPlacement | null {
-  if (!key) return null;
-  try {
-    const raw = localStorage.getItem(key);
-    return raw ? (JSON.parse(raw) as FloatingPlacement) : null;
-  } catch {
-    return null;
-  }
-}
-
 /**
  * A draggable box that floats over its offset parent and snaps to its corners.
  *
@@ -70,7 +63,7 @@ export function FloatingPanel({
   anchor = DEFAULT_ANCHOR,
   snapCorners,
   inset = DEFAULT_INSET,
-  storageKey,
+  persist,
   className,
 }: FloatingPanelProps) {
   const ref = useRef<HTMLDivElement>(null);
@@ -79,18 +72,11 @@ export function FloatingPanel({
 
   const [container, setContainer] = useState({ w: 0, h: 0 });
   const [size, setSize] = useState({ w: 0, h: 0 });
-  const [place, setPlace] = useState<FloatingPlacement>(
-    () => readStored(storageKey) ?? { x: 0, y: 0, anchor },
-  );
-
-  useEffect(() => {
-    if (!storageKey) return;
-    try {
-      localStorage.setItem(storageKey, JSON.stringify(place));
-    } catch {
-      // A full or disabled store is not worth failing a lab over.
-    }
-  }, [place, storageKey]);
+  const [place, setPlace] = usePersistedState<FloatingPlacement>(persist, () => ({
+    x: 0,
+    y: 0,
+    anchor,
+  }));
 
   const item = useMemo(
     () => ({

package/src/primitives/Split.less

@@ -0,0 +1,14 @@
+// The strip's own seam. windease positions and sizes it; this is only what it
+// looks like.
+.lk-split [data-affordance-kind='resize-x'] {
+  background: var(--wzl-border);
+}
+
+.lk-split .windease-affordance-hit:hover [data-affordance-kind='resize-x'],
+.lk-split .windease-affordance-hit:focus-visible [data-affordance-kind='resize-x'] {
+  background: var(--wzl-accent);
+}
+
+.lk-split .windease-affordance-hit:focus-visible {
+  outline: none;
+}

package/src/primitives/Split.test.tsx

@@ -0,0 +1,108 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { Split } from './Split';
+
+const VIEWPORT = { w: 800, h: 600 };
+
+function renderBody(props: Partial<Parameters<typeof Split>[0]> = {}) {
+  return render(
+    <Split viewport={VIEWPORT} sidebar={<p>sidebar body</p>} {...props}>
+      <p>instrument output</p>
+    </Split>,
+  );
+}
+
+describe('Split', () => {
+  it('renders both panes', () => {
+    renderBody();
+    expect(screen.getByText('sidebar body')).toBeInTheDocument();
+    expect(screen.getByText('instrument output')).toBeInTheDocument();
+  });
+
+  it('puts a labeled separator between the sidebar and the content', () => {
+    renderBody({ width: 320 });
+    const seam = screen.getByRole('separator');
+    expect(seam).toHaveAttribute('aria-orientation', 'horizontal');
+    expect(seam).toHaveAttribute('aria-valuenow', '320');
+    expect(seam).toHaveAccessibleName(/sidebar/i);
+  });
+
+  it('reports the width a drag lands on', () => {
+    const onWidthChange = vi.fn();
+    renderBody({ width: 320, onWidthChange });
+    const seam = screen.getByRole('separator');
+    fireEvent.pointerDown(seam, { clientX: 320, clientY: 100 });
+    fireEvent.pointerMove(seam, { clientX: 380, clientY: 100 });
+    fireEvent.pointerUp(seam, { clientX: 380, clientY: 100 });
+    expect(onWidthChange).toHaveBeenLastCalledWith(380);
+  });
+
+  it('resizes from the keyboard', () => {
+    const onWidthChange = vi.fn();
+    renderBody({ width: 320, onWidthChange });
+    const seam = screen.getByRole('separator');
+    fireEvent.keyDown(seam, { key: 'ArrowRight' });
+    expect(onWidthChange).toHaveBeenLastCalledWith(328);
+  });
+
+  it('refuses to drag the sidebar past its stated bounds', () => {
+    const onWidthChange = vi.fn();
+    renderBody({ width: 320, minWidth: 200, maxWidth: 400, onWidthChange });
+    const seam = screen.getByRole('separator');
+    expect(seam).toHaveAttribute('aria-valuemin', '200');
+    expect(seam).toHaveAttribute('aria-valuemax', '400');
+    fireEvent.pointerDown(seam, { clientX: 320, clientY: 100 });
+    fireEvent.pointerMove(seam, { clientX: 900, clientY: 100 });
+    expect(onWidthChange).toHaveBeenLastCalledWith(400);
+  });
+
+  it('leaves the content pane a floor the seam cannot cross', () => {
+    const onWidthChange = vi.fn();
+    renderBody({ width: 320, maxWidth: 10_000, contentMinWidth: 300, onWidthChange });
+    const seam = screen.getByRole('separator');
+    fireEvent.pointerDown(seam, { clientX: 320, clientY: 100 });
+    fireEvent.pointerMove(seam, { clientX: 5_000, clientY: 100 });
+    expect(onWidthChange).toHaveBeenLastCalledWith(VIEWPORT.w - 300);
+  });
+
+  it('puts the caller’s class names on its boxes', () => {
+    const { container } = render(
+      <Split
+        viewport={VIEWPORT}
+        className="lk-x__panes"
+        sidebarClassName="lk-x__side"
+        contentClassName="lk-x__main"
+        label="Stories"
+        sidebar={<p>side</p>}
+      >
+        <p>main</p>
+      </Split>,
+    );
+    expect(container.querySelector('.lk-x__panes.lk-split')).not.toBeNull();
+    expect(container.querySelector('.lk-x__side')?.textContent).toBe('side');
+    expect(container.querySelector('.lk-x__main')?.textContent).toBe('main');
+  });
+
+  it('names its seam after the sidebar label', () => {
+    render(
+      <Split viewport={VIEWPORT} label="Stories" sidebar={<p>side</p>}>
+        <p>main</p>
+      </Split>,
+    );
+    expect(screen.getByRole('separator')).toHaveAccessibleName(/stories/i);
+  });
+
+  it('renames its seam when the label changes', () => {
+    const { rerender } = render(
+      <Split viewport={VIEWPORT} label="Stories" sidebar={<p>side</p>}>
+        <p>main</p>
+      </Split>,
+    );
+    rerender(
+      <Split viewport={VIEWPORT} label="Outline" sidebar={<p>side</p>}>
+        <p>main</p>
+      </Split>,
+    );
+    expect(screen.getByRole('separator')).toHaveAccessibleName(/outline/i);
+  });
+});