@weasel-js/labkit 1.4.3 → 1.5.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);
+  });
+});

package/src/primitives/Split.tsx

@@ -0,0 +1,159 @@
+import { type ReactNode, useEffect, useMemo, useRef } from 'react';
+import { asNodeId, createNode, Store, stripStrategy } from 'windease';
+import { type ChromeMap, Container, Provider, StrategyRegistryProvider } from 'windease/react';
+
+const ZONE_ID = asNodeId('lk-split');
+const SIDEBAR_ID = asNodeId('lk-split-sidebar');
+const CONTENT_ID = asNodeId('lk-split-content');
+const STRATEGIES = { strip: stripStrategy as never };
+
+/** Props for `<Split>`. */
+export interface SplitProps {
+  /** The sidebar pane's contents. */
+  sidebar: ReactNode;
+  /** The content pane's contents. */
+  children: ReactNode;
+  /** Names the sidebar pane, and through it the seam. Default `'Sidebar'`. */
+  label?: string;
+  /** Extra classes on the strip, which always has `lk-split`. */
+  className?: string;
+  /** The class on the sidebar pane. */
+  sidebarClassName?: string;
+  /** The class on the content pane. */
+  contentClassName?: string;
+  /** The sidebar's current extent in pixels. Omit to leave it unpersisted: the
+   *  seam still works, its result just does not outlive the mount. */
+  width?: number;
+  /** Where the sidebar starts before anyone drags it. */
+  defaultWidth?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  /** How little the content pane may be squeezed to. Reported as the seam's
+   *  reachable maximum, so the drag stops there rather than clamping silently. */
+  contentMinWidth?: number;
+  /** Fires through the drag, not on release: the pane is already there. */
+  onWidthChange?: (width: number) => void;
+  /**
+   * Fixed extent. Omit in an app — the strip measures its own box. Supply it
+   * where nothing measures, notably jsdom, or both panes lay out at zero.
+   */
+  viewport?: { w: number; h: number };
+}
+
+/**
+ * A sidebar and a content pane as a two-pane strip with a draggable seam.
+ *
+ * The seam is `stripStrategy`'s own resize affordance, so it arrives as a
+ * `role="separator"` carrying the reachable range, operable by pointer and by
+ * arrows / Home / End, and clamped against the content pane's floor rather
+ * than against the sidebar's alone.
+ */
+export function Split({
+  sidebar,
+  children,
+  label = 'Sidebar',
+  className,
+  sidebarClassName,
+  contentClassName,
+  width,
+  defaultWidth = 320,
+  minWidth = 140,
+  maxWidth = 720,
+  contentMinWidth = 160,
+  onWidthChange,
+  viewport,
+}: SplitProps) {
+  // The cross-axis half of every size hint below is inert: a horizontal strip
+  // stretches its panes to the container's height and never reads `h`.
+  const storeRef = useRef<Store | null>(null);
+  if (storeRef.current === null) {
+    const store = new Store();
+    store.registerNode(
+      createNode({
+        kind: 'zone',
+        id: ZONE_ID,
+        container: { strategyId: 'strip', config: { axis: 'x', resizable: true } },
+      }),
+    );
+    store.registerNode(
+      createNode({
+        kind: 'sidebar',
+        id: SIDEBAR_ID,
+        parentId: ZONE_ID,
+        meta: { title: label },
+        placement: { size: { w: width ?? defaultWidth } },
+        hints: { minSize: { w: minWidth, h: 0 }, maxSize: { w: maxWidth, h: 0 } },
+      }),
+    );
+    store.registerNode(
+      createNode({
+        kind: 'content',
+        id: CONTENT_ID,
+        parentId: ZONE_ID,
+        meta: { title: 'Content' },
+        hints: { minSize: { w: contentMinWidth, h: 0 } },
+      }),
+    );
+    store.showNode(SIDEBAR_ID);
+    store.showNode(CONTENT_ID);
+    storeRef.current = store;
+  }
+  const store = storeRef.current;
+
+  // What the store last held, so the placement event can tell a drag from the
+  // echo of our own write and a controlled `width` does not fight the seam.
+  const widthRef = useRef(width ?? defaultWidth);
+
+  useEffect(() => {
+    store.setHints(SIDEBAR_ID, {
+      minSize: { w: minWidth, h: 0 },
+      maxSize: { w: maxWidth, h: 0 },
+    });
+    store.setHints(CONTENT_ID, { minSize: { w: contentMinWidth, h: 0 } });
+  }, [store, minWidth, maxWidth, contentMinWidth]);
+
+  useEffect(() => {
+    store.setMeta(SIDEBAR_ID, { title: label });
+  }, [store, label]);
+
+  useEffect(() => {
+    if (width === undefined || width === widthRef.current) return;
+    widthRef.current = width;
+    store.patchPlacement(SIDEBAR_ID, { size: { w: width } });
+  }, [store, width]);
+
+  const onWidthChangeRef = useRef(onWidthChange);
+  onWidthChangeRef.current = onWidthChange;
+  useEffect(
+    () =>
+      store.events.on('node.placementChanged', () => {
+        const next = (store.getPlacement(SIDEBAR_ID)?.size as { w?: number } | undefined)?.w;
+        if (typeof next !== 'number' || next === widthRef.current) return;
+        widthRef.current = next;
+        onWidthChangeRef.current?.(next);
+      }),
+    [store],
+  );
+
+  const chrome = useMemo<ChromeMap>(
+    () => ({
+      sidebar: () => <div className={sidebarClassName}>{sidebar}</div>,
+      content: () => <div className={contentClassName}>{children}</div>,
+    }),
+    [sidebar, children, sidebarClassName, contentClassName],
+  );
+
+  return (
+    <Provider store={store}>
+      <StrategyRegistryProvider strategies={STRATEGIES}>
+        <Container
+          parentId={ZONE_ID}
+          chrome={chrome}
+          className={className ? `lk-split windease-zone ${className}` : 'lk-split windease-zone'}
+          affordances
+          viewport={viewport}
+        />
+      </StrategyRegistryProvider>
+    </Provider>
+  );
+}

package/src/primitives/ZoomControl.tsx

@@ -1,3 +1,4 @@
+import { normalizeZoom } from '@weasel-js/core';
 import { NumberField, Slider } from '../passthrough/weasel-ui';
 
 /** Props for `<ZoomControl>`. */
@@ -30,10 +31,12 @@ export function ZoomControl({
   zoom,
   onZoomChange,
   onZoomCommit,
-  min = 0.1,
-  max = 8,
+  min: minProp = 0.1,
+  max: maxProp = 8,
   className,
 }: ZoomControlProps) {
+  const min = normalizeZoom(minProp);
+  const max = normalizeZoom(maxProp);
   const commit = onZoomCommit ?? onZoomChange;
   const emit = (track: number, done: boolean): void => {
     const next = clamp(fromTrack(track), min, max);

package/src/primitives/index.ts

@@ -9,6 +9,8 @@ export type { ScaleIndicatorProps } from './ScaleIndicator';
 export { ScaleIndicator } from './ScaleIndicator';
 export type { SidebarProps } from './Sidebar';
 export { Sidebar } from './Sidebar';
+export type { SplitProps } from './Split';
+export { Split } from './Split';
 export type { StatusBarProps, StatusBarSectionProps } from './StatusBar';
 export { StatusBar } from './StatusBar';
 export type { ToolbarButtonProps, ToolbarGroupProps, ToolbarProps } from './Toolbar';

package/src/state/Persistence.stories.tsx

@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+import { createIndexedDbAdapter } from './adapters';
+import { Persistence } from './Persistence';
+import { usePersistedState } from './usePersistedState';
+
+// jsdom only has fake-indexeddb, an imitation. This round-trips a value through
+// the browser's own IndexedDB: write it, unmount the provider so it closes,
+// mount a fresh one, and read it back.
+
+function Tab() {
+  const [tab, setTab] = usePersistedState('tab', 'shape');
+  return (
+    <p>
+      <output aria-label="tab">{tab}</output>
+      <button type="button" onClick={() => setTab('color')}>
+        choose color
+      </button>
+    </p>
+  );
+}
+
+function Remountable({ database }: { database: string }) {
+  const [generation, setGeneration] = useState(0);
+  const [shown, setShown] = useState(true);
+  const storage = useState(() => createIndexedDbAdapter({ database }))[0];
+  return (
+    <div>
+      <button
+        type="button"
+        onClick={() => {
+          setShown(false);
+          // Past the provider's deferred close, which sends the queued write.
+          setTimeout(() => {
+            setGeneration((g) => g + 1);
+            setShown(true);
+          }, 100);
+        }}
+      >
+        remount
+      </button>
+      {shown ? (
+        <Persistence
+          key={generation}
+          storageKey="story"
+          storage={storage}
+          fallback={<p>loading</p>}
+        >
+          <Tab />
+        </Persistence>
+      ) : null}
+    </div>
+  );
+}
+
+const meta: Meta<typeof Remountable> = {
+  title: 'labkit/State/Persistence',
+  component: Remountable,
+};
+export default meta;
+
+export const SurvivesARemountInIndexedDb: StoryObj<typeof Remountable> = {
+  args: { database: `labkit-story-${Date.now()}` },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await waitFor(() => expect(canvas.getByLabelText('tab')).toHaveTextContent('shape'));
+    await userEvent.click(canvas.getByText('choose color'));
+    await userEvent.click(canvas.getByText('remount'));
+    await waitFor(() => expect(canvas.queryByLabelText('tab')).toBeNull());
+    await waitFor(() => expect(canvas.getByLabelText('tab')).toHaveTextContent('color'), {
+      timeout: 3000,
+    });
+  },
+};

package/src/state/Persistence.tsx

@@ -0,0 +1,33 @@
+import { createContext, type ReactNode } from 'react';
+import { defaultStorage } from './adapters';
+import { labPrefix } from './labRecords';
+import { openRecords, type RecordCache } from './records';
+import type { StorageAdapter } from './types';
+import { useOpenOnce, useWarnIgnoredChange } from './useOpenOnce';
+
+/** The records `usePersistedState` reads and writes. `<Lab>`,
+ *  `SingletonExperimentProvider` and `<Persistence>` provide one. */
+export const PersistenceContext = createContext<RecordCache | null>(null);
+
+/** Props for `<Persistence>`. */
+export interface PersistenceProps {
+  /** Names the records, as `<Lab storageKey>` does. A lab and a
+   *  `<Persistence>` given the same key share lab-scoped values. */
+  storageKey: string;
+  /** Default: IndexedDB, or localStorage where IndexedDB will not open. */
+  storage?: StorageAdapter;
+  /** Rendered until the records have loaded. Default: nothing. */
+  fallback?: ReactNode;
+  children: ReactNode;
+}
+
+/** Persisted values for a page with no lab: `usePersistedState` below it keeps
+ *  what it holds across a reload. Both props are read once, at mount. */
+export function Persistence({ storageKey, storage, fallback = null, children }: PersistenceProps) {
+  useWarnIgnoredChange('<Persistence>', { storageKey, storage });
+  const records = useOpenOnce(async () =>
+    openRecords({ storage: storage ?? (await defaultStorage()), prefix: labPrefix(storageKey) }),
+  );
+  if (!records) return <>{fallback}</>;
+  return <PersistenceContext.Provider value={records}>{children}</PersistenceContext.Provider>;
+}

package/src/state/SingletonExperiment.test.tsx

@@ -1,7 +1,7 @@
-import { act, render, renderHook } from '@testing-library/react';
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, render, renderHook, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
 import { createMemoryAdapter } from './adapters';
-import { labDocumentKey } from './document';
+import { labPrefix } from './labRecords';
 import { SingletonExperimentProvider } from './SingletonExperiment';
 import { useTrialState } from './useTrialState';
 
@@ -13,31 +13,41 @@ interface State {
   zoom: number;
 }
 
-describe('SingletonExperimentProvider', () => {
-  afterEach(() => {
-    vi.useRealTimers();
-  });
+function Provider({
+  backing,
+  children,
+}: {
+  backing: Map<string, unknown>;
+  children: React.ReactNode;
+}) {
+  return (
+    <SingletonExperimentProvider<State, Config>
+      id="test"
+      initialConfig={{ width: 100, bg: '#000' }}
+      initialState={{ zoom: 1 }}
+      storage={createMemoryAdapter(backing)}
+      storageKey="test"
+      fallback={<p>loading</p>}
+    >
+      {children}
+    </SingletonExperimentProvider>
+  );
+}
 
-  it('exposes config and state via useTrialState', () => {
+describe('SingletonExperimentProvider', () => {
+  it('shows its fallback, then exposes config and state via useTrialState', async () => {
+    const backing = new Map<string, unknown>();
     const wrapper = ({ children }: { children: React.ReactNode }) => (
-      <SingletonExperimentProvider<State, Config>
-        id="test"
-        initialConfig={{ width: 100, bg: '#000' }}
-        initialState={{ zoom: 1 }}
-        storage={createMemoryAdapter()}
-        storageKey="test"
-      >
-        {children}
-      </SingletonExperimentProvider>
+      <Provider backing={backing}>{children}</Provider>
     );
     const { result } = renderHook(() => useTrialState<State, Config>(), { wrapper });
-    expect(result.current.config).toEqual({ width: 100, bg: '#000' });
+    expect(screen.getByText('loading')).toBeInTheDocument();
+    await waitFor(() => expect(result.current?.config).toEqual({ width: 100, bg: '#000' }));
     expect(result.current.state).toEqual({ zoom: 1 });
   });
 
-  it('persists config changes to storage', () => {
-    vi.useFakeTimers();
-    const storage = createMemoryAdapter();
+  it('persists config changes to storage', async () => {
+    const backing = new Map<string, unknown>();
     const Probe = () => {
       const h = useTrialState<State, Config>();
       return (
@@ -46,32 +56,24 @@ describe('SingletonExperimentProvider', () => {
         </button>
       );
     };
-    const { getByText } = render(
-      <SingletonExperimentProvider<State, Config>
-        id="test"
-        initialConfig={{ width: 100, bg: '#000' }}
-        initialState={{ zoom: 1 }}
-        storage={storage}
-        storageKey="test"
-      >
+    render(
+      <Provider backing={backing}>
         <Probe />
-      </SingletonExperimentProvider>,
+      </Provider>,
+    );
+    const go = await screen.findByText('go');
+    act(() => go.click());
+    await waitFor(() =>
+      expect(backing.get(`${labPrefix('test')}trial:test`)).toMatchObject({
+        config: { width: 200 },
+      }),
     );
-    act(() => {
-      getByText('go').click();
-    });
-    act(() => {
-      vi.advanceTimersByTime(400);
-    });
-    const raw = storage.read(labDocumentKey('test'));
-    expect(raw).toBeTruthy();
-    expect(raw).toContain('"width":200');
   });
 
-  it('rehydrates from storage on mount', () => {
-    const storage = createMemoryAdapter();
-    // A pre-document lab, which createLabStore folds forward on hydration.
-    storage.write(
+  it('rehydrates from storage on mount', async () => {
+    const backing = new Map<string, unknown>();
+    // A pre-document lab, which opening folds forward.
+    backing.set(
       'lk:test:workspaces',
       JSON.stringify([
         {
@@ -84,18 +86,10 @@ describe('SingletonExperimentProvider', () => {
       ]),
     );
     const wrapper = ({ children }: { children: React.ReactNode }) => (
-      <SingletonExperimentProvider<State, Config>
-        id="test"
-        initialConfig={{ width: 100, bg: '#000' }}
-        initialState={{ zoom: 1 }}
-        storage={storage}
-        storageKey="test"
-      >
-        {children}
-      </SingletonExperimentProvider>
+      <Provider backing={backing}>{children}</Provider>
     );
     const { result } = renderHook(() => useTrialState<State, Config>(), { wrapper });
-    expect(result.current.config).toEqual({ width: 999, bg: '#fff' });
+    await waitFor(() => expect(result.current?.config).toEqual({ width: 999, bg: '#fff' }));
     expect(result.current.state).toEqual({ zoom: 2 });
   });
 });