@weasel-js/labkit 1.4.4 → 1.5.0

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 });
   });
 });

package/src/state/SingletonExperiment.tsx

@@ -1,7 +1,10 @@
-import { type ReactNode, useRef } from 'react';
+import type { ReactNode } from 'react';
+import { defaultStorage } from './adapters';
 import { LabStoreProvider, TrialIdProvider } from './context';
-import { createLabStore, type LabStore } from './store';
+import { openLabStore } from './openLabStore';
+import { PersistenceContext } from './Persistence';
 import type { StorageAdapter } from './types';
+import { useOpenOnce, useWarnIgnoredChange } from './useOpenOnce';
 
 const SINGLETON_INSTRUMENT = '__singleton__';
 
@@ -12,8 +15,11 @@ export interface SingletonExperimentProviderProps<TS, TC> {
   id: string;
   initialConfig: TC;
   initialState: TS;
-  storage: StorageAdapter;
   storageKey: string;
+  /** Default: IndexedDB, or localStorage where IndexedDB will not open. */
+  storage?: StorageAdapter;
+  /** Rendered until the stored experiment has loaded. Default: nothing. */
+  fallback?: ReactNode;
   children: ReactNode;
 }
 
@@ -21,7 +27,8 @@ export interface SingletonExperimentProviderProps<TS, TC> {
  * One-trial `<Lab>` substitute for single-screen experiments. Mounts
  * a `LabStoreProvider` + `TrialIdProvider` with one synthetic
  * trial, so `useTrialState` works without going through the
- * full `<Lab instruments={...}>` runtime.
+ * full `<Lab instruments={...}>` runtime. `storageKey` and `storage` are read
+ * once, at mount.
  */
 export function SingletonExperimentProvider<TS, TC>({
   id,
@@ -29,13 +36,14 @@ export function SingletonExperimentProvider<TS, TC>({
   initialState,
   storage,
   storageKey,
+  fallback = null,
   children,
 }: SingletonExperimentProviderProps<TS, TC>) {
-  const storeRef = useRef<LabStore | null>(null);
-  if (storeRef.current === null) {
-    const store = createLabStore({ storageKey, storage });
-    if (!store.getState().trials.some((w) => w.id === id)) {
-      store.getState().addTrial({
+  useWarnIgnoredChange('<SingletonExperimentProvider>', { storageKey, storage });
+  const opened = useOpenOnce(async () => {
+    const lab = await openLabStore({ storageKey, storage: storage ?? (await defaultStorage()) });
+    if (!lab.store.getState().trials.some((w) => w.id === id)) {
+      lab.store.getState().addTrial({
         id,
         instrumentName: SINGLETON_INSTRUMENT,
         config: initialConfig,
@@ -43,11 +51,14 @@ export function SingletonExperimentProvider<TS, TC>({
         view: { zoom: 1, pan: { x: 0, y: 0 } },
       });
     }
-    storeRef.current = store;
-  }
+    return lab;
+  });
+  if (!opened) return <>{fallback}</>;
   return (
-    <LabStoreProvider store={storeRef.current}>
-      <TrialIdProvider trialId={id}>{children}</TrialIdProvider>
+    <LabStoreProvider store={opened.store}>
+      <PersistenceContext.Provider value={opened.records}>
+        <TrialIdProvider trialId={id}>{children}</TrialIdProvider>
+      </PersistenceContext.Provider>
     </LabStoreProvider>
   );
 }

package/src/state/adapterContract.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+import type { StorageAdapter, StorageChange } from './types';
+
+/** How the contract suite drives one adapter. */
+export interface AdapterHarness {
+  adapter: StorageAdapter;
+  /** Whether a `Uint8Array` survives the round trip unchanged. */
+  binary: boolean;
+  /** Make a change the way another writer would, or omit when the adapter
+   *  has no `subscribe`. */
+  foreign?: {
+    set(key: string, value: unknown): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+  };
+}
+
+async function until(check: () => boolean, ms = 1000): Promise<void> {
+  const end = Date.now() + ms;
+  while (!check()) {
+    if (Date.now() > end) throw new Error('timed out waiting for a change');
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+const settle = (): Promise<void> => new Promise((r) => setTimeout(r, 50));
+
+/** Every shipped adapter answers to these. `setup` runs once per test. */
+export function describeAdapterContract(name: string, setup: () => AdapterHarness): void {
+  describe(`${name} — the adapter contract`, () => {
+    it('reads back what it stored, as a copy', async () => {
+      const { adapter } = setup();
+      const value = { trial: 'a', nested: { n: 1, list: [1, 'two', null] } };
+      await adapter.set('lk:x:one', value);
+      value.nested.n = 99;
+      expect(await adapter.get('lk:x:one')).toEqual({
+        trial: 'a',
+        nested: { n: 1, list: [1, 'two', null] },
+      });
+    });
+
+    it('answers undefined for a key it never held', async () => {
+      const { adapter } = setup();
+      expect(await adapter.get('lk:x:absent')).toBeUndefined();
+    });
+
+    it('lists only the keys under a prefix', async () => {
+      const { adapter } = setup();
+      await adapter.set('lk:x:a', 1);
+      await adapter.set('lk:x:b', 2);
+      await adapter.set('lk:y:a', 3);
+      const listed = await adapter.list('lk:x:');
+      expect(new Map(listed)).toEqual(
+        new Map<string, unknown>([
+          ['lk:x:a', 1],
+          ['lk:x:b', 2],
+        ]),
+      );
+    });
+
+    it('deletes a key', async () => {
+      const { adapter } = setup();
+      await adapter.set('lk:x:gone', { a: 1 });
+      await adapter.delete('lk:x:gone');
+      expect(await adapter.get('lk:x:gone')).toBeUndefined();
+      expect(await adapter.list('lk:x:')).toEqual([]);
+    });
+
+    it('keeps binary values exactly when it says it can', async () => {
+      const { adapter, binary } = setup();
+      if (!binary) return;
+      await adapter.set('lk:x:bytes', new Uint8Array([1, 2, 255]));
+      const back = await adapter.get('lk:x:bytes');
+      // Not `toBeInstanceOf`: under jsdom, structuredClone hands back Node's
+      // Uint8Array, which is not the test realm's.
+      expect(Object.prototype.toString.call(back)).toBe('[object Uint8Array]');
+      expect([...(back as Uint8Array)]).toEqual([1, 2, 255]);
+    });
+
+    it("reports another writer's changes under its prefix, and nothing else", async () => {
+      const { adapter, foreign } = setup();
+      if (!foreign) {
+        expect(adapter.subscribe).toBeUndefined();
+        return;
+      }
+      if (!adapter.subscribe) throw new Error(`${name} has a foreign writer but no subscribe`);
+      const heard: StorageChange[] = [];
+      const off = adapter.subscribe('lk:x:', (changes) => heard.push(...changes));
+      try {
+        await adapter.set('lk:x:own', 'mine');
+        await foreign.set('lk:y:elsewhere', 'not this prefix');
+        await settle();
+        expect(heard).toEqual([]);
+
+        await foreign.set('lk:x:theirs', { from: 'peer' });
+        await until(() => heard.length > 0);
+        expect(heard).toEqual([['lk:x:theirs', { from: 'peer' }]]);
+
+        await foreign.delete('lk:x:theirs');
+        await until(() => heard.length > 1);
+        expect(heard[1]).toEqual(['lk:x:theirs', undefined]);
+      } finally {
+        off();
+      }
+    });
+
+    it('stops reporting once unsubscribed', async () => {
+      const { adapter, foreign } = setup();
+      if (!foreign || !adapter.subscribe) return;
+      const heard: StorageChange[] = [];
+      adapter.subscribe('lk:x:', (changes) => heard.push(...changes))();
+      await foreign.set('lk:x:late', 1);
+      await settle();
+      expect(heard).toEqual([]);
+    });
+  });
+}