@weasel-js/labkit 1.0.3 → 1.0.4

package/src/lab/WorkspaceGrid.stories.tsx

@@ -59,3 +59,19 @@ export const SevenTiles: Story = {
     </div>
   ),
 };
+
+/** Draggable seams. Drag a tile edge, or Tab to a seam and press an arrow —
+ *  a grid moves extents a whole cell at a time. */
+export const Resizable: Story = {
+  render: () => (
+    <div style={{ height: 500 }}>
+      <WorkspaceGrid ids={['a', 'b', 'c', 'd', 'e']} resizable>
+        <Tile>1</Tile>
+        <Tile>2</Tile>
+        <Tile>3</Tile>
+        <Tile>4</Tile>
+        <Tile>5</Tile>
+      </WorkspaceGrid>
+    </div>
+  ),
+};

package/src/lab/WorkspaceGrid.test.tsx

@@ -1,11 +1,13 @@
 import { render, screen } from '@testing-library/react';
-import { describe, expect, test } from 'vitest';
+import { describe, expect, test, vi } from 'vitest';
 import { WorkspaceGrid } from './WorkspaceGrid';
 
+const VIEWPORT = { w: 800, h: 600 };
+
 describe('WorkspaceGrid', () => {
   test('renders all children', () => {
     render(
-      <WorkspaceGrid>
+      <WorkspaceGrid viewport={VIEWPORT}>
         <div>one</div>
         <div>two</div>
         <div>three</div>
@@ -16,25 +18,97 @@ describe('WorkspaceGrid', () => {
     expect(screen.getByText('three')).toBeInTheDocument();
   });
 
-  test('sets CSS custom properties for grid dimensions based on child count', () => {
-    const { container } = render(
-      <WorkspaceGrid>
+  test('keeps a child with the tile its id names when an earlier one closes', () => {
+    const ids = ['a', 'b', 'c'];
+    const { rerender, container } = render(
+      <WorkspaceGrid ids={ids} viewport={VIEWPORT}>
         <div>a</div>
         <div>b</div>
         <div>c</div>
       </WorkspaceGrid>,
     );
-    const grid = container.firstChild as HTMLElement;
-    expect(grid.style.getPropertyValue('--lk-grid-cols')).toBe('2');
-    expect(grid.style.getPropertyValue('--lk-grid-rows')).toBe('2');
+    expect(container.querySelector('[data-node="c"]')).toHaveTextContent('c');
+
+    rerender(
+      <WorkspaceGrid ids={['b', 'c']} viewport={VIEWPORT}>
+        <div>b</div>
+        <div>c</div>
+      </WorkspaceGrid>,
+    );
+    expect(container.querySelector('[data-node="c"]')).toHaveTextContent('c');
+    expect(container.querySelector('[data-node="a"]')).toBeNull();
   });
 
   test('uses lk-workspace-grid class', () => {
     const { container } = render(
-      <WorkspaceGrid>
+      <WorkspaceGrid viewport={VIEWPORT}>
         <div />
       </WorkspaceGrid>,
     );
-    expect((container.firstChild as HTMLElement).className).toBe('lk-workspace-grid');
+    expect((container.firstChild as HTMLElement).className).toContain('lk-workspace-grid');
+  });
+
+  test('renders resize affordances only when resizable', () => {
+    const { container, rerender } = render(
+      <WorkspaceGrid ids={['a', 'b']} viewport={VIEWPORT}>
+        <div>a</div>
+        <div>b</div>
+      </WorkspaceGrid>,
+    );
+    expect(container.querySelectorAll('[role="separator"]')).toHaveLength(0);
+
+    rerender(
+      <WorkspaceGrid ids={['a', 'b']} resizable viewport={VIEWPORT}>
+        <div>a</div>
+        <div>b</div>
+      </WorkspaceGrid>,
+    );
+    expect(container.querySelectorAll('[role="separator"]').length).toBeGreaterThan(0);
+  });
+
+  test('applies a saved extent to a tile as it registers', () => {
+    const { container } = render(
+      <WorkspaceGrid
+        ids={['a', 'b']}
+        resizable
+        viewport={VIEWPORT}
+        layout={{ a: { span: { cols: 2 } } }}
+      >
+        <div>a</div>
+        <div>b</div>
+      </WorkspaceGrid>,
+    );
+    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(
+      <WorkspaceGrid ids={['a', 'b']} reorderable onReorder={onReorder} viewport={VIEWPORT}>
+        <div>a</div>
+        <div>b</div>
+      </WorkspaceGrid>,
+    );
+    // The grid is controlled: it renders a handle per tile and commits nothing
+    // itself. Order still comes from `ids`.
+    expect(container.querySelectorAll('.lk-workspace-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(
+      <WorkspaceGrid ids={['a', 'b']} viewport={VIEWPORT}>
+        <div>a</div>
+        <div>b</div>
+      </WorkspaceGrid>,
+    );
+    expect(container.querySelectorAll('.lk-workspace-tile__grip')).toHaveLength(0);
   });
 });

package/src/lab/WorkspaceGrid.tsx

@@ -1,22 +1,196 @@
-import { Children, type CSSProperties, type ReactNode } from 'react';
-import { gridDims } from './gridDims';
+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-workspaces');
+const STRATEGIES = { grid: gridStrategy as never };
+const KIND = 'workspace';
+
+/** 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 WorkspaceLayout = Record<
+  string,
+  { size?: { w?: number; h?: number }; span?: { cols?: number; rows?: number } }
+>;
 
-/** Props for `<WorkspaceGrid>`. */
 export interface WorkspaceGridProps {
   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?: WorkspaceLayout;
+  /** Fires when a tile's extent changes. Persist it and hand it back as
+   *  `layout` to make a resize survive a reload. */
+  onLayoutChange?: (layout: WorkspaceLayout) => 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): WorkspaceLayout[string] | null {
+  const p = store.getNode(id)?.membership?.placement as WorkspaceLayout[string] | undefined;
+  if (!p) return null;
+  const out: WorkspaceLayout[string] = {};
+  if (p.size) out.size = p.size;
+  if (p.span) out.span = p.span;
+  return Object.keys(out).length > 0 ? out : null;
 }
 
-/** Lays its children out in the most nearly square grid that fits them. */
-export function WorkspaceGrid({ children }: WorkspaceGridProps) {
-  const count = Children.count(children);
-  const { cols, rows } = gridDims(count);
-  const style = {
-    '--lk-grid-cols': String(cols),
-    '--lk-grid-rows': String(rows),
-  } as CSSProperties;
+/**
+ * Auto-balanced tiling of workspaces, `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 WorkspaceGrid({
+  children,
+  ids,
+  resizable = false,
+  reorderable = false,
+  onReorder,
+  layout,
+  onLayoutChange,
+  gap = 12,
+  padding = 0,
+  viewport,
+}: WorkspaceGridProps) {
+  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: WorkspaceLayout = {};
+      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-workspace-tile">
+            <DragHandle nodeId={node.id} className="lk-workspace-tile__grip">
+              <span className="lk-workspace-tile__grip-dots" aria-hidden="true" />
+            </DragHandle>
+            <div className="lk-workspace-tile__body">{content}</div>
+          </div>
+        );
+      },
+    };
+  }, [nodeIds, items, reorderable]);
+
+  const grid = (
+    <Container
+      parentId={ZONE_ID}
+      chrome={chrome}
+      className="lk-workspace-grid windease-zone"
+      affordances={resizable}
+      viewport={viewport}
+      onChildOrderChange={reorderable ? commitOrder : undefined}
+    />
+  );
+
   return (
-    <div className="lk-workspace-grid" style={style}>
-      {children}
-    </div>
+    <Provider store={store}>
+      <StrategyRegistryProvider strategies={STRATEGIES}>
+        {reorderable ? <DragProvider>{grid}</DragProvider> : grid}
+      </StrategyRegistryProvider>
+    </Provider>
   );
 }

package/src/lab/index.ts

@@ -1,5 +1,3 @@
-export type { GridDims } from './gridDims';
-export { gridDims } from './gridDims';
 export type { LabProps } from './Lab';
 export { Lab } from './Lab';
 export type { LabContextValue } from './LabContext';

package/src/state/helpers.ts

@@ -1,10 +1,10 @@
 import type { InstrumentSerializers, UndoStack, WorkspaceRecord } from './types';
 
-/** The storage key a lab writes one of its three buckets under. Namespaced by
+/** The storage key a lab writes one of its buckets under. Namespaced by
  *  `storageKey` so two labs sharing an origin do not collide. */
 export function labStorageKey(
   storageKey: string,
-  bucket: 'workspaces' | 'saves' | 'theme',
+  bucket: 'workspaces' | 'saves' | 'theme' | 'layout',
 ): string {
   return `lk:${storageKey}:${bucket}`;
 }

package/src/state/store.test.ts

@@ -245,7 +245,8 @@ describe('persistence — debounced writes', () => {
     vi.advanceTimersByTime(400);
     const writesAfter = writeSpy.mock.calls.length;
 
-    expect(writesAfter - writesBefore).toBe(3);
+    // One flush, one write per storage key: workspaces, saves, theme, layout.
+    expect(writesAfter - writesBefore).toBe(4);
     vi.useRealTimers();
   });
 });

package/src/state/store.ts

@@ -34,6 +34,7 @@ export interface LabStoreActions {
   deleteSnapshot: (snapshotId: string) => void;
   listSnapshots: (workspaceId?: string) => SavedSnapshot[];
   setMode: (mode: LabMode) => void;
+  setLayout: (layout: Record<string, unknown>) => void;
 }
 
 /** A lab's store: its state and actions, plus the hook instruments use to
@@ -65,6 +66,17 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
     }
   }
 
+  const layoutRaw = options.storage.read(labStorageKey(options.storageKey, 'layout'));
+  let hydratedLayout: Record<string, unknown> = {};
+  if (layoutRaw) {
+    try {
+      hydratedLayout = JSON.parse(layoutRaw) as Record<string, unknown>;
+    } catch {
+      console.warn('[labkit] failed to parse saved layout, starting empty');
+      hydratedLayout = {};
+    }
+  }
+
   const modeRaw = options.storage.read(labStorageKey(options.storageKey, 'theme'));
   // `interstellar` was the dark mode's name back when it was a theme.
   const stored = modeRaw === 'interstellar' ? 'dark' : modeRaw;
@@ -79,6 +91,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
     workspaces: hydratedWorkspaces,
     savedSnapshots: hydratedSnapshots,
     mode: hydratedMode,
+    layout: hydratedLayout,
 
     addWorkspace: (record) => {
       set((s) => ({
@@ -207,6 +220,11 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
       set({ mode });
       scheduleFlush();
     },
+
+    setLayout: (layout) => {
+      set({ layout });
+      scheduleFlush();
+    },
   }));
 
   function scheduleFlush(): void {
@@ -222,6 +240,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
         JSON.stringify(s.savedSnapshots),
       );
       options.storage.write(labStorageKey(options.storageKey, 'theme'), s.mode);
+      options.storage.write(labStorageKey(options.storageKey, 'layout'), JSON.stringify(s.layout));
       flushTimer = null;
     }, 300);
   }

package/src/state/types.ts

@@ -37,6 +37,9 @@ export interface LabStoreState {
   workspaces: WorkspaceRecord[];
   savedSnapshots: SavedSnapshot[];
   mode: LabMode;
+  /** Per-workspace tile extents, keyed by workspace id. Opaque here — the
+   *  shape belongs to whatever lays the workspaces out. */
+  layout: Record<string, unknown>;
 }
 
 /** Where a lab persists itself. Implementations are keyed string storage and

package/src/test-setup.ts

@@ -12,6 +12,25 @@ if (jsdomWin && typeof globalThis.localStorage === 'undefined') {
   Object.defineProperty(globalThis, 'sessionStorage', { value: jsdomWin.sessionStorage });
 }
 
+// windease's ContainerHost calls `new ResizeObserver` unguarded, and jsdom
+// ships none. The stub must report a non-zero box: a windease container
+// renders no children at all until something measures it, and jsdom's own
+// geometry is always 0, so every tiled tile would vanish from the DOM.
+if (typeof globalThis.ResizeObserver === 'undefined') {
+  globalThis.ResizeObserver = class {
+    #cb: ResizeObserverCallback;
+    constructor(cb: ResizeObserverCallback) {
+      this.#cb = cb;
+    }
+    observe(target: Element) {
+      const contentRect = { width: 1024, height: 768, x: 0, y: 0, top: 0, left: 0 };
+      this.#cb([{ target, contentRect } as ResizeObserverEntry], this);
+    }
+    unobserve() {}
+    disconnect() {}
+  } as unknown as typeof ResizeObserver;
+}
+
 afterEach(() => {
   cleanup();
 });

package/src/workspace/Workspace.stories.tsx

@@ -34,6 +34,7 @@ function Harness() {
     cloneWorkspace: noop,
     closeWorkspace: noop,
     resetWorkspace: noop,
+    reorderWorkspaces: noop,
     savedSnapshots: [],
     saveSnapshot: noop,
     loadSnapshot: noop,

package/src/workspace/Workspace.test.tsx

@@ -126,6 +126,7 @@ function ChromeHarness({
     cloneWorkspace: vi.fn(),
     closeWorkspace: vi.fn(),
     resetWorkspace: vi.fn(),
+    reorderWorkspaces: vi.fn(),
     savedSnapshots: [],
     saveSnapshot: vi.fn(),
     loadSnapshot: vi.fn(),

package/src/workspace/index.ts

@@ -20,5 +20,6 @@ export {
   addWorkspace,
   cloneWorkspace,
   closeWorkspace,
+  reorderWorkspaces,
   resetWorkspace,
 } from './workspaceOps';

package/src/workspace/workspaceOps.test.ts

@@ -1,7 +1,13 @@
 import { describe, expect, it } from 'vitest';
 import type { Instrument } from '../instrument/types';
 import type { WorkspaceRecord } from '../state/types';
-import { addWorkspace, cloneWorkspace, closeWorkspace, resetWorkspace } from './workspaceOps';
+import {
+  addWorkspace,
+  cloneWorkspace,
+  closeWorkspace,
+  reorderWorkspaces,
+  resetWorkspace,
+} from './workspaceOps';
 
 interface CounterState {
   count: number;
@@ -140,3 +146,30 @@ describe('resetWorkspace', () => {
     expect((arr[0]?.config as CounterConfig).step).toBe(99);
   });
 });
+
+describe('reorderWorkspaces', () => {
+  const ws = (id: string) =>
+    ({
+      id,
+      instrumentName: 'T',
+      config: {},
+      state: {},
+      view: { zoom: 1, pan: { x: 0, y: 0 } },
+      undoStack: { past: [], future: [] },
+    }) as never;
+
+  it('reorders to match the given ids', () => {
+    const next = reorderWorkspaces([ws('a'), ws('b'), ws('c')], ['c', 'a', 'b']);
+    expect(next.map((w) => w.id)).toEqual(['c', 'a', 'b']);
+  });
+
+  it('drops ids that no longer exist rather than resurrecting them', () => {
+    const next = reorderWorkspaces([ws('a'), ws('b')], ['gone', 'b', 'a']);
+    expect(next.map((w) => w.id)).toEqual(['b', 'a']);
+  });
+
+  it('keeps unmentioned workspaces, after the named ones', () => {
+    const next = reorderWorkspaces([ws('a'), ws('b'), ws('c')], ['c']);
+    expect(next.map((w) => w.id)).toEqual(['c', 'a', 'b']);
+  });
+});

package/src/workspace/workspaceOps.ts

@@ -84,3 +84,19 @@ export function resetWorkspace(
   };
   return [...workspaces.slice(0, idx), reset, ...workspaces.slice(idx + 1)];
 }
+
+/**
+ * Reorder to match `ids`. Ids the list doesn't mention keep their relative
+ * order at the end, and ids it names that no longer exist are dropped — a
+ * reorder that raced a close should not resurrect the closed workspace.
+ */
+export function reorderWorkspaces(
+  workspaces: WorkspaceRecord[],
+  ids: readonly string[],
+): WorkspaceRecord[] {
+  const byId = new Map(workspaces.map((w) => [w.id, w]));
+  const named = ids.map((id) => byId.get(id)).filter((w): w is WorkspaceRecord => w !== undefined);
+  const seen = new Set(named.map((w) => w.id));
+  const rest = workspaces.filter((w) => !seen.has(w.id));
+  return [...named, ...rest];
+}