@weasel-js/labkit 1.0.2 → 1.0.4

package/dist/undo/index.d.ts

@@ -1,29 +1,44 @@
-export { U as UndoCapability } from '../_dts/index-C6Yze7sQ.js';
+export { U as UndoCapability } from '../_dts/index-CFlDPeZh.js';
 import 'react';
-import '../_dts/types-Si4Fw-1F.js';
+import '../_dts/types-x92Kfeme.js';
 
+/** A subscriber to a named event. */
 type EventListener = () => void;
+/** Named-event pub/sub, the channel an instrument's `emit` writes to and undo
+ *  snapshotting listens on. */
 interface EventBus {
     on(event: string, listener: EventListener): () => void;
     emit(event: string): void;
     clear(): void;
 }
+/** Build an empty event bus. */
 declare function createEventBus(): EventBus;
 
+/** Undo history as two stacks of state snapshots: what has been done, and
+ *  what has been undone. The present state is held elsewhere, not here. */
 interface UndoStack {
     past: unknown[];
     future: unknown[];
 }
+/** A fresh, empty history. */
 declare function emptyStack(): UndoStack;
+/** Record a new snapshot, discarding the redo branch and the oldest entry
+ *  once `maxDepth` is reached. */
 declare function pushSnapshot(stack: UndoStack, snapshot: unknown, maxDepth: number): UndoStack;
+/** Step back one snapshot, returning the new history and the state to restore.
+ *  `null` when there is nothing to undo. The caller supplies `current` so it
+ *  can be redone. */
 declare function undo(stack: UndoStack, current: unknown): {
     stack: UndoStack;
     snapshot: unknown;
 } | null;
+/** Step forward one snapshot, returning the new history and the state to
+ *  restore. `null` when there is nothing to redo. */
 declare function redo(stack: UndoStack, current: unknown): {
     stack: UndoStack;
     snapshot: unknown;
 } | null;
+/** Discard the whole history. */
 declare function clearUndo(_stack: UndoStack): UndoStack;
 
 export { clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo };

package/dist/undo/index.js

@@ -1,3 +1,3 @@
-export { clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo } from '../chunk-7BKDG73Z.js';
+export { clearUndo, createEventBus, emptyStack, pushSnapshot, redo, undo } from '../chunk-RL2LOLNI.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/labkit",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "React widgets for building self-contained interactive lab pages",
   "license": "MIT",
   "author": "orochi235",
@@ -97,6 +97,7 @@
     "earcut": "2.2.4",
     "polygon-clipping": "^0.15.7",
     "react-aria-components": "^1.5.0",
+    "windease": "^1.2.1",
     "zustand": "^5.0.12"
   },
   "devDependencies": {

package/src/canvas/CanvasStack.tsx

@@ -5,6 +5,7 @@ import { screenToWorld } from './canvasCoords';
 import { type CanvasLayerDescriptor, useLayerScheduler } from './useLayerScheduler';
 import { usePanZoom } from './usePanZoom';
 
+/** Props for `<CanvasStack>`. */
 export interface CanvasStackProps {
   layers: CanvasLayerDescriptor[];
   view: ViewTransform;
@@ -16,6 +17,9 @@ export interface CanvasStackProps {
   children?: ReactNode;
 }
 
+/** Stacks one `<canvas>` per layer and drives them from a shared view, so a
+ *  layer that changes rarely is not redrawn with one that changes every frame.
+ *  Handles sizing, device pixel ratio, and pan/zoom. */
 export function CanvasStack({
   layers,
   view,

package/src/canvas/CanvasStackContext.ts

@@ -1,8 +1,11 @@
 import { createContext } from 'react';
 import type { ViewTransform } from '../instrument/types';
 
+/** What a canvas stack publishes to its children — currently the view, so
+ *  DOM overlays can position themselves in the same coordinates. */
 export interface CanvasStackContextValue {
   view: ViewTransform;
 }
 
+/** Context carrying the surrounding canvas stack's view. */
 export const CanvasStackContext = createContext<CanvasStackContextValue | null>(null);

package/src/canvas/canvasCoords.ts

@@ -1,5 +1,6 @@
 import type { Point, ViewTransform } from '../instrument/types';
 
+/** Project a world point into screen coordinates under a view. */
 export function worldToScreen(world: Point, view: ViewTransform): Point {
   return {
     x: world.x * view.zoom + view.pan.x,
@@ -7,6 +8,7 @@ export function worldToScreen(world: Point, view: ViewTransform): Point {
   };
 }
 
+/** Unproject a screen point back to world coordinates under a view. */
 export function screenToWorld(screen: Point, view: ViewTransform): Point {
   return {
     x: (screen.x - view.pan.x) / view.zoom,

package/src/canvas/useLayerScheduler.ts

@@ -1,6 +1,8 @@
 import { type RefObject, useEffect, useRef } from 'react';
 import type { ViewTransform } from '../instrument/types';
 
+/** One layer of a canvas stack: its id, whether it is currently shown, and how
+ *  it paints itself. */
 export interface CanvasLayerDescriptor {
   id: string;
   visible: boolean;

package/src/controls/ControlPanel.tsx

@@ -16,6 +16,8 @@ export interface ControlPanelProps<TC extends Record<string, unknown>> {
   className?: string;
 }
 
+/** Render an instrument's config schema as a stack of controls, each writing
+ *  back through `setConfig`. */
 export function ControlPanel<TC extends Record<string, unknown>>({
   fields,
   config,

package/src/controls/types.ts

@@ -1,11 +1,15 @@
+/** Which control a config field is edited with. */
 export type ConfigFieldType = 'slider' | 'checkbox' | 'select' | 'number' | 'text' | 'color';
 
+/** What every config field carries: the config key it writes, the label shown
+ *  beside it, and which control renders it. */
 export interface ConfigFieldBase {
   key: string;
   label: string;
   type: ConfigFieldType;
 }
 
+/** A bounded number edited by dragging. */
 export interface SliderField extends ConfigFieldBase {
   type: 'slider';
   default: number;
@@ -14,22 +18,27 @@ export interface SliderField extends ConfigFieldBase {
   step?: number;
 }
 
+/** A boolean. */
 export interface CheckboxField extends ConfigFieldBase {
   type: 'checkbox';
   default: boolean;
 }
 
+/** One choice in a select field. */
 export interface SelectOption {
   value: string;
   label: string;
 }
 
+/** A fixed set of labeled choices. */
 export interface SelectField extends ConfigFieldBase {
   type: 'select';
   default: string;
   options: SelectOption[];
 }
 
+/** A number typed directly, optionally bounded. Use a slider field instead
+ *  when the range matters more than the exact value. */
 export interface NumberField extends ConfigFieldBase {
   type: 'number';
   default: number;
@@ -38,6 +47,8 @@ export interface NumberField extends ConfigFieldBase {
   step?: number;
 }
 
+/** A free-text string. Writes are debounced so typing does not re-run the
+ *  instrument on every keystroke. */
 export interface TextField extends ConfigFieldBase {
   type: 'text';
   default: string;
@@ -47,11 +58,14 @@ export interface TextField extends ConfigFieldBase {
   debounceMs?: number;
 }
 
+/** A color, as a CSS color string. */
 export interface ColorField extends ConfigFieldBase {
   type: 'color';
   default: string;
 }
 
+/** One field of an instrument's config schema. The schema is what the control
+ *  panel renders, and what `validateConfigSchema` checks. */
 export type ConfigField =
   | SliderField
   | CheckboxField

package/src/instrument/capabilityDetector.ts

@@ -1,5 +1,7 @@
 import type { Instrument } from './types';
 
+/** Which optional capabilities an instrument declared — what the workspace
+ *  consults to decide which chrome to show. */
 export interface CapabilityFlags {
   hasCanvas: boolean;
   hasLayers: boolean;
@@ -7,6 +9,7 @@ export interface CapabilityFlags {
   hasUndo: boolean;
 }
 
+/** Read an instrument's declared capabilities off its definition. */
 export function detectCapabilities(instrument: Instrument<unknown, unknown>): CapabilityFlags {
   return {
     hasCanvas: instrument.canvas != null,

package/src/instrument/defineInstrument.ts

@@ -1,5 +1,7 @@
 import type { Instrument } from './types';
 
+/** Identity at runtime; exists so an instrument's state and config types are
+ *  inferred from the spec rather than having to be written out. */
 export function defineInstrument<TS, TC>(spec: Instrument<TS, TC>): Instrument<TS, TC> {
   return spec;
 }

package/src/instrument/types.ts

@@ -1,6 +1,8 @@
 import type { ReactNode } from 'react';
 import type { ConfigField } from '../controls/types';
 
+/** What an instrument's `render` is handed: its state and config, the setters
+ *  for both, the workspace it is mounted in, and a way to emit named events. */
 export interface RenderContext<TS = unknown, TC = unknown> {
   state: TS;
   config: TC;
@@ -14,20 +16,28 @@ export interface RenderContext<TS = unknown, TC = unknown> {
   emit: (event: string) => void;
 }
 
+/** One 2D canvas layer of an instrument, drawn in declaration order. */
 export interface CanvasLayer<TS = unknown, TC = unknown> {
   id: string;
   draw: (ctx: CanvasRenderingContext2D, args: { state: TS; config: TC; zoom: number }) => void;
 }
 
+/** Declares that an instrument draws to a canvas: its layers, and where the
+ *  view starts. */
 export interface CanvasCapability<TS = unknown, TC = unknown> {
   layers: CanvasLayer<TS, TC>[];
   initialView?: { zoom: number; pan: { x: number; y: number } };
 }
 
+/** Declares which of an instrument's layers the workspace should offer
+ *  show/hide controls for. */
 export interface LayerCapability {
   ids: string[];
 }
 
+/** Declares that an instrument accepts items dragged from a palette: what the
+ *  palette offers, what a drop does to the state, and — optionally — live
+ *  feedback during the drag and the ability to drag existing items back out. */
 export interface DragDropCapability<TS = unknown, TC = unknown> {
   palette: PaletteItem[] | ((state: TS, config: TC) => PaletteItem[]);
   onDrop: (worldPos: Point, item: PaletteItem, state: TS, config: TC) => TS;
@@ -35,20 +45,39 @@ export interface DragDropCapability<TS = unknown, TC = unknown> {
   pickUp?: (hit: HitResult, state: TS, config: TC) => { item: PaletteItem; state: TS } | null;
 }
 
+/** Declares that an instrument's state is undoable: which emitted events
+ *  snapshot it, and how many snapshots to keep. */
 export interface UndoCapability {
   snapshotOn?: string[];
   maxDepth?: number;
 }
 
+/** The name of an event an instrument emits through `RenderContext.emit`. */
 export type SystemEvent = string;
 
+/** A point in world coordinates. */
 export type Point = { x: number; y: number };
+/** What a hit-test found, and where. */
 export type HitResult = { hit: boolean; layerId?: string; pointId?: string };
+/** A workspace's camera. */
 export type ViewTransform = { zoom: number; pan: Point };
+/** A layer as the layer list shows it. `alwaysOn` layers cannot be hidden. */
 export type LayerDescriptor = { id: string; label: string; alwaysOn?: boolean };
+/** One draggable entry in an instrument's palette. */
 export type PaletteItem = { id: string; label: string; data?: unknown };
+/** Whether a drop would be accepted at the current position, and why not if
+ *  it would not. */
 export type DragFeedback = { ok: boolean; reason?: string };
 
+/**
+ * An instrument: one self-contained interactive experiment a lab can host.
+ *
+ * It owns two pieces of data — `config`, the settings the control panel edits,
+ * and `state`, what the experiment is currently doing — and renders from both.
+ * The optional capability fields declare what else it wants from the runtime:
+ * a canvas, a layer list, palette drag-and-drop, undo. Declaring a capability
+ * is what makes the workspace provide the corresponding chrome.
+ */
 export interface Instrument<TS = unknown, TC = unknown> {
   name: string;
   defaultConfig: () => TC;

package/src/instrument/validateConfigSchema.ts

@@ -1,5 +1,7 @@
 import type { ConfigField, ConfigFieldType } from '../controls/types';
 
+/** Whether a config schema is usable, and every problem found rather than
+ *  just the first. */
 export interface ValidationResult {
   valid: boolean;
   errors: string[];
@@ -7,6 +9,9 @@ export interface ValidationResult {
 
 const KNOWN_TYPES: ConfigFieldType[] = ['slider', 'checkbox', 'select', 'number', 'text', 'color'];
 
+/** Check a config schema for the mistakes that would otherwise surface as a
+ *  silently broken control: empty or duplicate keys, unknown field types, and
+ *  fields whose own constraints do not hold. */
 export function validateConfigSchema(fields: ConfigField[]): ValidationResult {
   const errors: string[] = [];
   const seenKeys = new Set<string>();

package/src/lab/Lab.tsx

@@ -12,13 +12,15 @@ import {
   addWorkspace as addWorkspaceOp,
   cloneWorkspace as cloneWorkspaceOp,
   closeWorkspace as closeWorkspaceOp,
+  reorderWorkspaces as reorderWorkspacesOp,
   resetWorkspace as resetWorkspaceOp,
 } from '../workspace/workspaceOps';
 import { LabContext, type LabContextValue } from './LabContext';
 import { LabShell } from './LabShell';
 import { useResolvedMode } from './useSystemMode';
-import { WorkspaceGrid } from './WorkspaceGrid';
+import { WorkspaceGrid, type WorkspaceLayout } from './WorkspaceGrid';
 
+/** Props for `<Lab>`. */
 export interface LabProps {
   instruments: Instrument[];
   defaultInstrument: string;
@@ -76,6 +78,8 @@ function buildNebula(colors: readonly string[]): string {
   return blobs.join(', ');
 }
 
+/** The lab runtime: creates the store, provides it, and renders one workspace
+ *  per record in a grid. Each workspace runs one of `instruments`. */
 export function Lab({
   instruments,
   defaultInstrument,
@@ -105,6 +109,7 @@ export function Lab({
   const workspaces = useStore(store, (s) => s.workspaces);
   const savedSnapshots = useStore(store, (s) => s.savedSnapshots);
   const modeValue = useStore(store, (s) => s.mode);
+  const layout = useStore(store, (s) => s.layout);
   const resolvedMode = useResolvedMode(modeValue);
 
   useEffect(() => {
@@ -137,6 +142,9 @@ export function Lab({
         const next = closeWorkspaceOp(store.getState().workspaces, id);
         replaceWorkspaces(next);
       },
+      reorderWorkspaces: (ids) => {
+        replaceWorkspaces(reorderWorkspacesOp(store.getState().workspaces, ids));
+      },
       resetWorkspace: (id) => {
         const next = resetWorkspaceOp(store.getState().workspaces, id, instruments);
         const record = next.find((w) => w.id === id);
@@ -184,7 +192,14 @@ export function Lab({
           style={backdropStyle}
         >
           <LabShell title={title ?? 'Labkit'} mode={modeValue} header={children}>
-            <WorkspaceGrid>
+            <WorkspaceGrid
+              ids={workspaces.map((w) => w.id)}
+              resizable
+              reorderable
+              onReorder={(ids) => contextValue.reorderWorkspaces(ids)}
+              layout={layout as WorkspaceLayout}
+              onLayoutChange={(next) => store.getState().setLayout(next)}
+            >
               {workspaces.map((w) => (
                 <Workspace key={w.id} id={w.id} />
               ))}

package/src/lab/LabContext.ts

@@ -2,6 +2,9 @@ import { createContext, useContext } from 'react';
 import type { Instrument } from '../instrument/types';
 import type { LabMode, SavedSnapshot, WorkspaceRecord } from '../state/types';
 
+/** Lab-wide state and commands: the available instruments, the open
+ *  workspaces and the operations over them, saved snapshots, and the color
+ *  mode. */
 export interface LabContextValue {
   instruments: Instrument[];
   workspaces: WorkspaceRecord[];
@@ -9,6 +12,7 @@ export interface LabContextValue {
   cloneWorkspace: (id: string) => void;
   closeWorkspace: (id: string) => void;
   resetWorkspace: (id: string) => void;
+  reorderWorkspaces: (ids: readonly string[]) => void;
   savedSnapshots: SavedSnapshot[];
   saveSnapshot: (workspaceId: string, name?: string) => void;
   loadSnapshot: (workspaceId: string, snapshotId: string) => void;
@@ -17,8 +21,10 @@ export interface LabContextValue {
   setMode: (m: LabMode) => void;
 }
 
+/** Context carrying the surrounding lab. Prefer `useLabContext`. */
 export const LabContext = createContext<LabContextValue | null>(null);
 
+/** The surrounding lab. Throws outside a `<Lab>`. */
 export function useLabContext(): LabContextValue {
   const ctx = useContext(LabContext);
   if (ctx === null) {

package/src/lab/LabShell.tsx

@@ -4,6 +4,7 @@ import type { LabMode } from '../state/types';
 import { interstellarTheme } from '../theme/interstellar';
 import { useResolvedMode } from './useSystemMode';
 
+/** Props for `<LabShell>`. */
 export interface LabShellProps {
   title: string;
   children: ReactNode;
@@ -15,6 +16,9 @@ export interface LabShellProps {
   mode?: LabMode;
 }
 
+/** Page frame for a lab: a titled header, a body, and an optional footer,
+ *  themed for the resolved color mode. Presentational only — use `<Lab>` when
+ *  the workspace runtime is wanted too. */
 export function LabShell({ title, children, header, footer, mode = 'auto' }: LabShellProps) {
   const resolved = useResolvedMode(mode);
   const outer = useThemeOptional();

package/src/lab/WorkspaceGrid.less

@@ -1,8 +1,40 @@
+// Tiles are positioned by windease at strategy-computed rects; `.windease-zone`
+// (from windease/styles.css) supplies the containing block and the 100% box.
+// This class exists for consumers to target.
 .lk-workspace-grid {
-  display: grid;
-  grid-template-columns: repeat(var(--lk-grid-cols, 1), 1fr);
-  grid-template-rows: repeat(var(--lk-grid-rows, 1), 1fr);
-  gap: var(--wzl-space-md);
-  width: 100%;
+  min-height: 0;
+}
+
+// Only rendered when `reorderable` — a tile is full of controls, so the drag
+// target has to be its own strip rather than the whole pane.
+.lk-workspace-tile {
+  display: flex;
+  flex-direction: column;
   height: 100%;
+
+  &__grip {
+    flex: 0 0 auto;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 14px;
+    cursor: grab;
+    border-radius: var(--wzl-radius-sm) var(--wzl-radius-sm) 0 0;
+    background: var(--wzl-surface-sunken);
+
+    &:active { cursor: grabbing; }
+  }
+
+  &__grip-dots {
+    width: 28px;
+    height: 3px;
+    border-radius: 999px;
+    background: var(--wzl-fg-muted);
+    opacity: 0.5;
+  }
+
+  &__body {
+    flex: 1;
+    min-height: 0;
+  }
 }

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