@weasel-js/labkit 1.0.3 → 1.1.0

package/src/lab/Workspace.test.tsx

@@ -0,0 +1,114 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, test, vi } from 'vitest';
+import { Workspace } from './Workspace';
+
+const VIEWPORT = { w: 800, h: 600 };
+
+describe('Workspace', () => {
+  test('renders all children', () => {
+    render(
+      <Workspace viewport={VIEWPORT}>
+        <div>one</div>
+        <div>two</div>
+        <div>three</div>
+      </Workspace>,
+    );
+    expect(screen.getByText('one')).toBeInTheDocument();
+    expect(screen.getByText('two')).toBeInTheDocument();
+    expect(screen.getByText('three')).toBeInTheDocument();
+  });
+
+  test('keeps a child with the tile its id names when an earlier one closes', () => {
+    const ids = ['a', 'b', 'c'];
+    const { rerender, container } = render(
+      <Workspace ids={ids} viewport={VIEWPORT}>
+        <div>a</div>
+        <div>b</div>
+        <div>c</div>
+      </Workspace>,
+    );
+    expect(container.querySelector('[data-node="c"]')).toHaveTextContent('c');
+
+    rerender(
+      <Workspace ids={['b', 'c']} viewport={VIEWPORT}>
+        <div>b</div>
+        <div>c</div>
+      </Workspace>,
+    );
+    expect(container.querySelector('[data-node="c"]')).toHaveTextContent('c');
+    expect(container.querySelector('[data-node="a"]')).toBeNull();
+  });
+
+  test('uses lk-workspace class', () => {
+    const { container } = render(
+      <Workspace viewport={VIEWPORT}>
+        <div />
+      </Workspace>,
+    );
+    expect((container.firstChild as HTMLElement).className).toContain('lk-workspace');
+  });
+
+  test('renders resize affordances only when resizable', () => {
+    const { container, rerender } = render(
+      <Workspace ids={['a', 'b']} viewport={VIEWPORT}>
+        <div>a</div>
+        <div>b</div>
+      </Workspace>,
+    );
+    expect(container.querySelectorAll('[role="separator"]')).toHaveLength(0);
+
+    rerender(
+      <Workspace ids={['a', 'b']} resizable viewport={VIEWPORT}>
+        <div>a</div>
+        <div>b</div>
+      </Workspace>,
+    );
+    expect(container.querySelectorAll('[role="separator"]').length).toBeGreaterThan(0);
+  });
+
+  test('applies a saved extent to a tile as it registers', () => {
+    const { container } = render(
+      <Workspace
+        ids={['a', 'b']}
+        resizable
+        viewport={VIEWPORT}
+        layout={{ a: { span: { cols: 2 } } }}
+      >
+        <div>a</div>
+        <div>b</div>
+      </Workspace>,
+    );
+    const a = container.querySelector('[data-node="a"]') as HTMLElement;
+    const b = container.querySelector('[data-node="b"]') as HTMLElement;
+    // `a` holds two columns, so it is wider than the single-column `b`.
+    expect(Number.parseFloat(a.style.width)).toBeGreaterThan(Number.parseFloat(b.style.width));
+  });
+
+  test('reports the order a drop would produce instead of applying it', () => {
+    const onReorder = vi.fn();
+    const { container } = render(
+      <Workspace ids={['a', 'b']} reorderable onReorder={onReorder} viewport={VIEWPORT}>
+        <div>a</div>
+        <div>b</div>
+      </Workspace>,
+    );
+    // The grid is controlled: it renders a handle per tile and commits nothing
+    // itself. Order still comes from `ids`.
+    expect(container.querySelectorAll('.lk-trial-tile__grip')).toHaveLength(2);
+    expect(onReorder).not.toHaveBeenCalled();
+    const nodes = [...container.querySelectorAll('[data-node]')].map((el) =>
+      el.getAttribute('data-node'),
+    );
+    expect(nodes).toEqual(['a', 'b']);
+  });
+
+  test('renders no drag handles unless reorderable', () => {
+    const { container } = render(
+      <Workspace ids={['a', 'b']} viewport={VIEWPORT}>
+        <div>a</div>
+        <div>b</div>
+      </Workspace>,
+    );
+    expect(container.querySelectorAll('.lk-trial-tile__grip')).toHaveLength(0);
+  });
+});

package/src/lab/Workspace.tsx

@@ -0,0 +1,196 @@
+import {
+  Children,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from 'react';
+import { asNodeId, createNode, gridStrategy, type NodeId, Store } from 'windease';
+import {
+  type ChromeMap,
+  Container,
+  DragHandle,
+  DragProvider,
+  Provider,
+  StrategyRegistryProvider,
+} from 'windease/react';
+
+const ZONE_ID = asNodeId('lk-workspace');
+const STRATEGIES = { grid: gridStrategy as never };
+const KIND = 'trial';
+
+/** A tile's persisted extent, keyed by the id its caller gave it. Grid resizes
+ *  write `span`; `size` is here because a strategy swap would write that. */
+export type TrialLayout = Record<
+  string,
+  { size?: { w?: number; h?: number }; span?: { cols?: number; rows?: number } }
+>;
+
+export interface WorkspaceProps {
+  children: ReactNode;
+  /**
+   * Stable id per child, positionally matched. Supply these whenever a tile
+   * can be closed from the middle: without them a tile is identified by its
+   * position, so closing one shifts every id after it and the panes inherit
+   * each other's dragged extents. `layout` and `reorderable` both key off
+   * these, so neither means much without them.
+   */
+  ids?: readonly string[];
+  /** Draggable seams between tiles. Off by default — an even tiling is the
+   *  behavior every existing caller has. */
+  resizable?: boolean;
+  /** Let a tile be dragged to a new position. Off by default. The grid never
+   *  reorders `children` itself: it reports the order a drop would produce and
+   *  the caller commits it. */
+  reorderable?: boolean;
+  /** The full id list a drop would produce, in its new order. */
+  onReorder?: (ids: string[]) => void;
+  /** Extents from a previous session, applied to tiles as they register. */
+  layout?: TrialLayout;
+  /** Fires when a tile's extent changes. Persist it and hand it back as
+   *  `layout` to make a resize survive a reload. */
+  onLayoutChange?: (layout: TrialLayout) => void;
+  gap?: number;
+  padding?: number;
+  /**
+   * Fixed tiling extent. Omit in an app — the grid measures its own box. Supply
+   * it where nothing measures, notably jsdom: at a zero measurement the grid
+   * renders no tiles at all.
+   */
+  viewport?: { w: number; h: number };
+}
+
+function extentOf(store: Store, id: NodeId): TrialLayout[string] | null {
+  const p = store.getNode(id)?.membership?.placement as TrialLayout[string] | undefined;
+  if (!p) return null;
+  const out: TrialLayout[string] = {};
+  if (p.size) out.size = p.size;
+  if (p.span) out.span = p.span;
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+/**
+ * Auto-balanced tiling of trials, `ceil(sqrt(n))` columns wide.
+ *
+ * Tiles are absolutely positioned at the rects `gridStrategy` computes, not
+ * laid out by CSS — `windease/styles.css` (folded into
+ * `@weasel-js/labkit/styles.css`) carries the rules that positioning depends on.
+ */
+export function Workspace({
+  children,
+  ids,
+  resizable = false,
+  reorderable = false,
+  onReorder,
+  layout,
+  onLayoutChange,
+  gap = 12,
+  padding = 0,
+  viewport,
+}: WorkspaceProps) {
+  const items = Children.toArray(children);
+  const idKey = ids ? ids.join(',') : `#${items.length}`;
+  // biome-ignore lint/correctness/useExhaustiveDependencies: idKey is the stable projection of items/ids; depending on those directly rebuilds every render and re-runs the sync effect forever
+  const nodeIds = useMemo(() => items.map((_, i) => asNodeId(ids?.[i] ?? `lk-ws-${i}`)), [idKey]);
+
+  // Held in refs rather than depended on: a fresh object each render would
+  // re-run the sync effect, and only a newly registered tile reads `layout`.
+  const layoutRef = useRef(layout);
+  layoutRef.current = layout;
+  const onLayoutChangeRef = useRef(onLayoutChange);
+  onLayoutChangeRef.current = onLayoutChange;
+
+  // One store for the component's lifetime: a tile's dragged extent lives in
+  // its node, so rebuilding the store on every add or close would silently
+  // reset every pane.
+  const storeRef = useRef<Store | null>(null);
+  if (storeRef.current === null) {
+    const store = new Store();
+    store.registerNode(
+      createNode({
+        kind: 'zone',
+        id: ZONE_ID,
+        container: { strategyId: 'grid', config: { resizable, gap, padding } },
+      }),
+    );
+    storeRef.current = store;
+  }
+  const store = storeRef.current;
+
+  useLayoutEffect(() => {
+    store.updateContainerConfig(ZONE_ID, { resizable, gap, padding });
+  }, [store, resizable, gap, padding]);
+
+  useLayoutEffect(() => {
+    const present = new Set(store.getContainerView(ZONE_ID)?.childOrder ?? []);
+    const wanted = new Set(nodeIds);
+    for (const id of present) {
+      if (!wanted.has(id)) store.unregisterNode(id);
+    }
+    for (const id of nodeIds) {
+      if (present.has(id)) continue;
+      store.registerNode(createNode({ kind: KIND, id, parentId: ZONE_ID, focus: true }));
+      store.showNode(id);
+      const saved = layoutRef.current?.[id];
+      if (saved) store.patchPlacement(id, saved);
+    }
+    store.setChildOrder(ZONE_ID, [...nodeIds]);
+  }, [store, nodeIds]);
+
+  useEffect(() => {
+    if (!onLayoutChange) return;
+    return store.events.on('node.placementChanged', () => {
+      const next: TrialLayout = {};
+      for (const child of store.getChildren(ZONE_ID)) {
+        const extent = extentOf(store, child.id);
+        if (extent) next[child.id] = extent;
+      }
+      onLayoutChangeRef.current?.(next);
+    });
+  }, [store, onLayoutChange]);
+
+  const commitOrder = useCallback(
+    (nextIds: NodeId[]) => onReorder?.(nextIds.map(String)),
+    [onReorder],
+  );
+
+  const chrome = useMemo<ChromeMap>(() => {
+    const byId = new Map<string, ReactNode>(nodeIds.map((id, i) => [id, items[i]]));
+    return {
+      [KIND]: ({ node }) => {
+        const content = byId.get(node.id) ?? null;
+        if (!reorderable) return content;
+        // A tile is full of controls, so the whole thing can't be the handle.
+        return (
+          <div className="lk-trial-tile">
+            <DragHandle nodeId={node.id} className="lk-trial-tile__grip">
+              <span className="lk-trial-tile__grip-dots" aria-hidden="true" />
+            </DragHandle>
+            <div className="lk-trial-tile__body">{content}</div>
+          </div>
+        );
+      },
+    };
+  }, [nodeIds, items, reorderable]);
+
+  const grid = (
+    <Container
+      parentId={ZONE_ID}
+      chrome={chrome}
+      className="lk-workspace windease-zone"
+      affordances={resizable}
+      viewport={viewport}
+      onChildOrderChange={reorderable ? commitOrder : undefined}
+    />
+  );
+
+  return (
+    <Provider store={store}>
+      <StrategyRegistryProvider strategies={STRATEGIES}>
+        {reorderable ? <DragProvider>{grid}</DragProvider> : grid}
+      </StrategyRegistryProvider>
+    </Provider>
+  );
+}

package/src/lab/index.ts

@@ -1,10 +1,8 @@
-export type { GridDims } from './gridDims';
-export { gridDims } from './gridDims';
 export type { LabProps } from './Lab';
 export { Lab } from './Lab';
 export type { LabContextValue } from './LabContext';
 export { LabContext, useLabContext } from './LabContext';
 export type { LabShellProps } from './LabShell';
 export { LabShell } from './LabShell';
-export type { WorkspaceGridProps } from './WorkspaceGrid';
-export { WorkspaceGrid } from './WorkspaceGrid';
+export type { WorkspaceProps } from './Workspace';
+export { Workspace } from './Workspace';

package/src/layers/AGENTS.md

@@ -31,9 +31,9 @@ The instrument declares layer ids:
 layers: { ids: ['grid', 'plants'] }
 ```
 
-`Workspace.tsx` converts each id into a `LayerDescriptor` (with `label === id` by default) and tracks `visibility` and a derived `layerOrder` in local state. The order produced by `onReorder` is then applied to `instrument.canvas.layers` before they're passed to `<CanvasStack>`.
+`Trial.tsx` converts each id into a `LayerDescriptor` (with `label === id` by default) and tracks `visibility` and a derived `layerOrder` in local state. The order produced by `onReorder` is then applied to `instrument.canvas.layers` before they're passed to `<CanvasStack>`.
 
-There is no transitive coupling between `layers.ids` and `canvas.layers[].id` — the workspace assumes the ids match. If you declare a layer in `canvas` that isn't in `layers.ids`, it stays in default order and is always visible.
+There is no transitive coupling between `layers.ids` and `canvas.layers[].id` — the trial assumes the ids match. If you declare a layer in `canvas` that isn't in `layers.ids`, it stays in default order and is always visible.
 
 ## `alwaysOn` semantics
 
@@ -52,7 +52,7 @@ Pointer capture is acquired on `pointerdown` and released on `pointerup`, so dra
 
 ## Empty state
 
-If `layers.length === 0`, renders `.lk-layer-list__empty` with the text "No layers". Workspace already guards this case (`layerDescriptors.length > 0`) so the empty state is rare in practice.
+If `layers.length === 0`, renders `.lk-layer-list__empty` with the text "No layers". Trial already guards this case (`layerDescriptors.length > 0`) so the empty state is rare in practice.
 
 ## When to fork
 

package/src/primitives/Toolbar.stories.tsx

@@ -12,7 +12,7 @@ type Story = StoryObj<typeof Toolbar>;
 export const Default: Story = {
   render: () => (
     <Toolbar>
-      <Toolbar.Title>My Workspace</Toolbar.Title>
+      <Toolbar.Title>My Trial</Toolbar.Title>
       <Toolbar.Button onClick={() => {}}>Undo</Toolbar.Button>
       <Toolbar.Button onClick={() => {}}>Redo</Toolbar.Button>
       <Toolbar.Spacer />
@@ -24,7 +24,7 @@ export const Default: Story = {
 export const WithDisabled: Story = {
   render: () => (
     <Toolbar>
-      <Toolbar.Title>Empty workspace</Toolbar.Title>
+      <Toolbar.Title>Empty trial</Toolbar.Title>
       <Toolbar.Button onClick={() => {}} disabled>
         Undo
       </Toolbar.Button>

package/src/state/SingletonExperiment.test.tsx

@@ -1,8 +1,9 @@
 import { act, render, renderHook } from '@testing-library/react';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { createMemoryAdapter } from './adapters';
+import { labDocumentKey } from './document';
 import { SingletonExperimentProvider } from './SingletonExperiment';
-import { useExperimentState } from './useExperimentState';
+import { useTrialState } from './useTrialState';
 
 interface Config {
   width: number;
@@ -17,7 +18,7 @@ describe('SingletonExperimentProvider', () => {
     vi.useRealTimers();
   });
 
-  it('exposes config and state via useExperimentState', () => {
+  it('exposes config and state via useTrialState', () => {
     const wrapper = ({ children }: { children: React.ReactNode }) => (
       <SingletonExperimentProvider<State, Config>
         id="test"
@@ -29,7 +30,7 @@ describe('SingletonExperimentProvider', () => {
         {children}
       </SingletonExperimentProvider>
     );
-    const { result } = renderHook(() => useExperimentState<State, Config>(), { wrapper });
+    const { result } = renderHook(() => useTrialState<State, Config>(), { wrapper });
     expect(result.current.config).toEqual({ width: 100, bg: '#000' });
     expect(result.current.state).toEqual({ zoom: 1 });
   });
@@ -38,7 +39,7 @@ describe('SingletonExperimentProvider', () => {
     vi.useFakeTimers();
     const storage = createMemoryAdapter();
     const Probe = () => {
-      const h = useExperimentState<State, Config>();
+      const h = useTrialState<State, Config>();
       return (
         <button type="button" onClick={() => h.setConfig('width', 200)}>
           go
@@ -62,15 +63,14 @@ describe('SingletonExperimentProvider', () => {
     act(() => {
       vi.advanceTimersByTime(400);
     });
-    // createLabStore uses labStorageKey which prefixes with "lk:"
-    const raw = storage.read('lk:test:workspaces');
+    const raw = storage.read(labDocumentKey('test'));
     expect(raw).toBeTruthy();
     expect(raw).toContain('"width":200');
   });
 
   it('rehydrates from storage on mount', () => {
     const storage = createMemoryAdapter();
-    // createLabStore uses labStorageKey which prefixes with "lk:"
+    // A pre-document lab, which createLabStore folds forward on hydration.
     storage.write(
       'lk:test:workspaces',
       JSON.stringify([
@@ -94,7 +94,7 @@ describe('SingletonExperimentProvider', () => {
         {children}
       </SingletonExperimentProvider>
     );
-    const { result } = renderHook(() => useExperimentState<State, Config>(), { wrapper });
+    const { result } = renderHook(() => useTrialState<State, Config>(), { wrapper });
     expect(result.current.config).toEqual({ width: 999, bg: '#fff' });
     expect(result.current.state).toEqual({ zoom: 2 });
   });

package/src/state/SingletonExperiment.tsx

@@ -1,5 +1,5 @@
 import { type ReactNode, useRef } from 'react';
-import { LabStoreProvider, WorkspaceIdProvider } from './context';
+import { LabStoreProvider, TrialIdProvider } from './context';
 import { createLabStore, type LabStore } from './store';
 import type { StorageAdapter } from './types';
 
@@ -7,8 +7,8 @@ const SINGLETON_INSTRUMENT = '__singleton__';
 
 /** Props for `<SingletonExperimentProvider>`. */
 export interface SingletonExperimentProviderProps<TS, TC> {
-  /** Stable id for the synthetic workspace; also doubles as the
-   *  WorkspaceIdContext value. */
+  /** Stable id for the synthetic trial; also doubles as the
+   *  TrialIdContext value. */
   id: string;
   initialConfig: TC;
   initialState: TS;
@@ -18,9 +18,9 @@ export interface SingletonExperimentProviderProps<TS, TC> {
 }
 
 /**
- * One-workspace `<Lab>` substitute for single-screen experiments. Mounts
- * a `LabStoreProvider` + `WorkspaceIdProvider` with one synthetic
- * workspace, so `useExperimentState` works without going through the
+ * 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.
  */
 export function SingletonExperimentProvider<TS, TC>({
@@ -34,8 +34,8 @@ export function SingletonExperimentProvider<TS, TC>({
   const storeRef = useRef<LabStore | null>(null);
   if (storeRef.current === null) {
     const store = createLabStore({ storageKey, storage });
-    if (!store.getState().workspaces.some((w) => w.id === id)) {
-      store.getState().addWorkspace({
+    if (!store.getState().trials.some((w) => w.id === id)) {
+      store.getState().addTrial({
         id,
         instrumentName: SINGLETON_INSTRUMENT,
         config: initialConfig,
@@ -47,7 +47,7 @@ export function SingletonExperimentProvider<TS, TC>({
   }
   return (
     <LabStoreProvider store={storeRef.current}>
-      <WorkspaceIdProvider workspaceId={id}>{children}</WorkspaceIdProvider>
+      <TrialIdProvider trialId={id}>{children}</TrialIdProvider>
     </LabStoreProvider>
   );
 }

package/src/state/context.tsx

@@ -27,25 +27,25 @@ export function useLabStore(): LabStoreState & ReturnType<LabStore['getState']>
   return useStore(ctx.store);
 }
 
-/** Context carrying which workspace the subtree belongs to. */
-export const WorkspaceIdContext = createContext<string | null>(null);
+/** Context carrying which trial the subtree belongs to. */
+export const TrialIdContext = createContext<string | null>(null);
 
-/** Names the workspace its subtree belongs to, so an instrument's hooks can
+/** Names the trial its subtree belongs to, so an instrument's hooks can
  *  find their own record in the store without being passed an id. */
-export function WorkspaceIdProvider({
-  workspaceId,
+export function TrialIdProvider({
+  trialId,
   children,
 }: {
-  workspaceId: string;
+  trialId: string;
   children: ReactNode;
 }): ReactElement {
-  return <WorkspaceIdContext.Provider value={workspaceId}>{children}</WorkspaceIdContext.Provider>;
+  return <TrialIdContext.Provider value={trialId}>{children}</TrialIdContext.Provider>;
 }
 
-/** The id of the workspace this component is inside. Throws outside a
- *  `<WorkspaceIdProvider>`. */
-export function useWorkspaceId(): string {
-  const id = useContext(WorkspaceIdContext);
-  if (!id) throw new Error('[labkit] useWorkspaceId must be used inside <WorkspaceIdProvider>');
+/** The id of the trial this component is inside. Throws outside a
+ *  `<TrialIdProvider>`. */
+export function useTrialId(): string {
+  const id = useContext(TrialIdContext);
+  if (!id) throw new Error('[labkit] useTrialId must be used inside <TrialIdProvider>');
   return id;
 }