@weasel-js/labkit 1.1.0 → 1.3.0-pre.0

package/src/chrome/ChromeRegions.stories.tsx

@@ -0,0 +1,106 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { CrosshairIcon, HandIcon, PencilIcon } from '@weasel-js/ui';
+import type { ConfigField } from '../controls/types';
+import type { Instrument } from '../instrument/types';
+import { Lab } from '../lab/Lab';
+
+interface DemoConfig extends Record<string, unknown> {
+  radius: number;
+  filled: boolean;
+}
+
+interface DemoState extends Record<string, unknown> {
+  spokes: number;
+}
+
+const fields: ConfigField[] = [
+  { key: 'radius', label: 'Radius', type: 'slider', default: 60, min: 10, max: 120, step: 1 },
+  { key: 'filled', label: 'Filled', type: 'checkbox', default: true },
+];
+
+/** Declares every capability that contributes chrome, so all five trial
+ *  regions render at once. */
+const FullInstrument: Instrument<DemoState, DemoConfig> = {
+  name: 'Every Region',
+  defaultConfig: () => ({ radius: 60, filled: true }),
+  initialState: () => ({ spokes: 7 }),
+  configSchema: () => fields,
+  undo: {},
+  layers: { ids: ['wheel'] },
+  tools: {
+    tools: [
+      { id: 'draw', label: 'Draw', icon: PencilIcon, shortcut: 'D' },
+      { id: 'pan', label: 'Pan', icon: HandIcon, shortcut: 'H' },
+      { id: 'measure', label: 'Measure', icon: CrosshairIcon, shortcut: 'M' },
+    ],
+  },
+  canvas: {
+    layers: [
+      {
+        id: 'wheel',
+        draw: (ctx, { state, config }) => {
+          ctx.strokeStyle = '#8ab';
+          ctx.fillStyle = 'rgba(136, 170, 187, 0.25)';
+          ctx.lineWidth = 1.5;
+          ctx.beginPath();
+          ctx.arc(160, 120, config.radius, 0, Math.PI * 2);
+          if (config.filled) ctx.fill();
+          ctx.stroke();
+          for (let i = 0; i < state.spokes; i++) {
+            const a = (i / state.spokes) * Math.PI * 2;
+            ctx.beginPath();
+            ctx.moveTo(160, 120);
+            ctx.lineTo(160 + Math.cos(a) * config.radius, 120 + Math.sin(a) * config.radius);
+            ctx.stroke();
+          }
+        },
+      },
+    ],
+  },
+  render: ({ trial }) => (
+    <div className="lk-region-demo-readout">tool: {trial.activeToolId ?? 'none'}</div>
+  ),
+};
+
+const meta: Meta<typeof Lab> = {
+  title: 'labkit/Chrome/Regions',
+  component: Lab,
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Lab>;
+
+export const EveryRegion: Story = {
+  args: {
+    instruments: [FullInstrument],
+    defaultInstrument: 'Every Region',
+    title: 'Chrome Regions',
+    storage: null,
+  },
+};
+
+/** A consumer dropping a built-in and adding its own in its place. */
+export const SuppressedAndReplaced: Story = {
+  args: {
+    instruments: [FullInstrument],
+    defaultInstrument: 'Every Region',
+    title: 'Suppress + Replace',
+    storage: null,
+    suppress: ['snapshot'],
+    chrome: [
+      {
+        id: 'export',
+        region: 'toolbar',
+        group: 'trial',
+        end: true,
+        item: {
+          icon: CrosshairIcon,
+          label: 'Export',
+          showLabel: true,
+          onActivate: () => {},
+        },
+      },
+    ],
+  },
+};

package/src/chrome/builtins.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest';
+import { f } from '../config/builder';
+import { fromConfigFields } from '../config/fromConfigField';
+import { resolveConfigSchema } from '../config/resolve';
+import type { Instrument } from '../instrument/types';
+import { builtinContributions } from './builtins';
+import type { TrialChromeContext } from './types';
+
+const ctx: TrialChromeContext = {
+  trialId: 't1',
+  instrumentName: 'Stub',
+  isLastTrial: false,
+  zoom: 1,
+  setZoom: () => {},
+  canUndo: true,
+  canRedo: false,
+  undo: () => {},
+  redo: () => {},
+  configFields: [],
+  configSchema: fromConfigFields([]),
+  config: {},
+  setConfig: () => {},
+  savedSnapshots: [],
+  saveSnapshot: () => {},
+  loadSnapshot: () => {},
+  clone: () => {},
+  reset: () => {},
+  close: () => {},
+  activeToolId: null,
+  setActiveTool: () => {},
+};
+
+const bare: Instrument = {
+  name: 'Stub',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => null,
+};
+
+const withCanvas: Instrument = { ...bare, canvas: { layers: [] } };
+
+const ctxWithZoom = (zoom: number | null): TrialChromeContext => ({ ...ctx, zoom });
+
+function ids(instrument: Instrument, c: TrialChromeContext = ctx): string[] {
+  return builtinContributions(instrument, c).map((x) => x.id);
+}
+
+describe('builtinContributions', () => {
+  it('always contributes the trial actions', () => {
+    expect(ids(bare)).toEqual(['snapshot', 'clone', 'reset', 'close']);
+  });
+
+  it('contributes undo and redo only when the instrument declares undo', () => {
+    expect(ids(bare)).not.toContain('undo');
+    expect(ids({ ...bare, undo: {} })).toContain('undo');
+    expect(ids({ ...bare, undo: {} })).toContain('redo');
+  });
+
+  it('puts zoom controls in the viewport region, not the toolbar', () => {
+    const zoomIn = builtinContributions(withCanvas, ctx).find((c) => c.id === 'zoom-in');
+    expect(zoomIn?.region).toBe('viewport');
+  });
+
+  it('contributes no viewport controls when the view is not 2D', () => {
+    expect(ids(withCanvas, ctxWithZoom(null))).not.toContain('zoom-in');
+  });
+
+  it('contributes a settings section only when the schema has fields', () => {
+    expect(ids(bare)).not.toContain('settings');
+    const withFields = {
+      ...ctx,
+      configSchema: fromConfigFields([
+        { key: 'n', label: 'N', type: 'number' as const, default: 1 },
+      ]),
+    };
+    expect(ids(bare, withFields)).toContain('settings');
+  });
+
+  it('contributes a settings section for a builder schema too', () => {
+    const withSchema = {
+      ...ctx,
+      configSchema: resolveConfigSchema(f.schema({ showGrid: f.boolean(true) }), []),
+    };
+    expect(ids(bare, withSchema)).toContain('settings');
+  });
+
+  it('reflects undo availability in the item, not by omitting it', () => {
+    const withUndo: Instrument = { ...bare, undo: {} };
+    const list = builtinContributions(withUndo, { ...ctx, canUndo: false });
+    const undo = list.find((c) => c.id === 'undo');
+    expect(undo?.item).toMatchObject({ disabled: true });
+  });
+
+  it('marks close as danger and disables it on the last trial', () => {
+    const list = builtinContributions(bare, { ...ctx, isLastTrial: true });
+    expect(list.find((c) => c.id === 'close')?.item).toMatchObject({
+      danger: true,
+      disabled: true,
+    });
+  });
+
+  it('offers the snapshot loader only once a snapshot has been taken', () => {
+    expect(ids(bare)).not.toContain('snapshot-load');
+    const withSaves = {
+      ...ctx,
+      savedSnapshots: [
+        {
+          id: 's1',
+          name: 'First',
+          trialId: 't1',
+          instrumentName: 'Stub',
+          config: {},
+          state: {},
+          savedAt: 1,
+        },
+      ],
+    };
+    expect(ids(bare, withSaves)).toContain('snapshot-load');
+  });
+
+  it('produces no duplicate ids for a fully-declared instrument', () => {
+    const full: Instrument = {
+      ...bare,
+      undo: {},
+      canvas: { layers: [] },
+      layers: { ids: ['a'] },
+    };
+    const list = builtinContributions(full, ctx);
+    expect(new Set(list.map((c) => c.id)).size).toBe(list.length);
+  });
+});
+
+describe('view readouts', () => {
+  it('contributes fps and scale to the status bar when the trial has a canvas', () => {
+    const out = builtinContributions(withCanvas, ctxWithZoom(1));
+    const status = out.filter((c) => c.region === 'status').map((c) => c.id);
+    expect(status).toContain('fps');
+    expect(status).toContain('scale');
+  });
+
+  it('contributes the zoom control to the viewport, replacing the readout', () => {
+    const out = builtinContributions(withCanvas, ctxWithZoom(1));
+    const viewport = out.filter((c) => c.region === 'viewport').map((c) => c.id);
+    expect(viewport).toContain('zoom-control');
+    expect(out.map((c) => c.id)).not.toContain('zoom-readout');
+  });
+
+  it('contributes none of them to a trial with no canvas', () => {
+    const out = builtinContributions(bare, ctxWithZoom(null));
+    expect(out.map((c) => c.id)).not.toContain('fps');
+    expect(out.map((c) => c.id)).not.toContain('zoom-control');
+  });
+});

package/src/chrome/builtins.tsx

@@ -0,0 +1,205 @@
+import {
+  CloneIcon,
+  CloseIcon,
+  FitIcon,
+  RedoIcon,
+  ResetIcon,
+  SnapshotIcon,
+  UndoIcon,
+  ZoomInIcon,
+  ZoomOutIcon,
+} from '@weasel-js/ui';
+import type { ControlRenderer } from '../config/types';
+import { ControlPanel } from '../controls/ControlPanel';
+import type { Instrument } from '../instrument/types';
+import { Select } from '../passthrough/weasel-ui';
+import { FpsMeter } from '../primitives/FpsMeter';
+import { ScaleIndicator } from '../primitives/ScaleIndicator';
+import { ZoomControl } from '../primitives/ZoomControl';
+import type { TrialChromeContext, TrialContribution } from './types';
+
+const ZOOM_STEP = 1.25;
+
+/**
+ * The contributions a trial gets from what its instrument declared. This is
+ * the whole "declaring a capability provides the chrome" rule — it replaces
+ * the presence checks that used to be spread across the runtime.
+ */
+export function builtinContributions(
+  instrument: Instrument,
+  ctx: TrialChromeContext,
+  controls?: Record<string, ControlRenderer>,
+): TrialContribution[] {
+  const out: TrialContribution[] = [];
+  const zoom = ctx.zoom;
+
+  if (instrument.undo != null) {
+    out.push({
+      id: 'undo',
+      region: 'toolbar',
+      group: 'history',
+      item: {
+        icon: UndoIcon,
+        label: 'Undo',
+        shortcut: 'Mod+Z',
+        disabled: !ctx.canUndo,
+        onActivate: ctx.undo,
+      },
+    });
+    out.push({
+      id: 'redo',
+      region: 'toolbar',
+      group: 'history',
+      item: {
+        icon: RedoIcon,
+        label: 'Redo',
+        shortcut: 'Mod+Shift+Z',
+        disabled: !ctx.canRedo,
+        onActivate: ctx.redo,
+      },
+    });
+  }
+
+  // A tool id shares the contribution namespace, so a tool called `close`
+  // collides with the built-in close button and throws. Both are contributions
+  // to one trial's chrome.
+  for (const t of instrument.tools?.tools ?? []) {
+    out.push({
+      id: t.id,
+      region: 'palette',
+      group: t.group,
+      item: { icon: t.icon, label: t.label, shortcut: t.shortcut },
+    });
+  }
+
+  // Zoom acts on the view of the trial, so it is a viewport control. A trial
+  // holding a non-2D view reports zoom as null and gets none of this.
+  if (instrument.canvas != null && zoom !== null) {
+    out.push({
+      id: 'zoom-out',
+      region: 'viewport',
+      group: 'zoom',
+      item: {
+        icon: ZoomOutIcon,
+        label: 'Zoom out',
+        onActivate: () => ctx.setZoom(zoom / ZOOM_STEP),
+      },
+    });
+    out.push({
+      id: 'zoom-in',
+      region: 'viewport',
+      group: 'zoom',
+      item: {
+        icon: ZoomInIcon,
+        label: 'Zoom in',
+        onActivate: () => ctx.setZoom(zoom * ZOOM_STEP),
+      },
+    });
+    out.push({
+      id: 'actual-size',
+      region: 'viewport',
+      group: 'zoom',
+      item: { icon: FitIcon, label: 'Actual size', onActivate: () => ctx.setZoom(1) },
+    });
+    out.push({
+      id: 'zoom-control',
+      region: 'viewport',
+      group: 'zoom',
+      render: (c) => <ZoomControl zoom={c.zoom ?? 1} onZoomChange={c.setZoom} />,
+    });
+    out.push({
+      id: 'scale',
+      region: 'status',
+      group: 'view',
+      render: () => <ScaleIndicator />,
+    });
+    out.push({
+      id: 'fps',
+      region: 'status',
+      group: 'view',
+      end: true,
+      render: () => <FpsMeter />,
+    });
+  }
+
+  if (Object.keys(ctx.configSchema.group.children).length > 0) {
+    out.push({
+      id: 'settings',
+      region: 'sidebar',
+      item: {
+        title: 'Settings',
+        body: (
+          <ControlPanel
+            schema={ctx.configSchema}
+            config={ctx.config as Record<string, unknown>}
+            setConfig={(key, value) => ctx.setConfig(String(key), value)}
+            renderers={controls}
+          />
+        ),
+      },
+    });
+  }
+
+  out.push({
+    id: 'snapshot',
+    region: 'toolbar',
+    group: 'history',
+    item: {
+      icon: SnapshotIcon,
+      label: 'Save snapshot',
+      shortcut: 'Mod+S',
+      onActivate: () => ctx.saveSnapshot(),
+    },
+  });
+  if (ctx.savedSnapshots.length > 0) {
+    // A picker is not an icon button, so it takes the render escape. Held at
+    // `selectedKey={null}` so it stays a "load one" action rather than
+    // drifting into a display of what was loaded last.
+    out.push({
+      id: 'snapshot-load',
+      region: 'toolbar',
+      group: 'trial',
+      end: true,
+      render: (c) => (
+        <Select
+          className="lk-toolbar__load-select"
+          aria-label="Load snapshot"
+          placeholder="Load…"
+          selectedKey={null}
+          options={c.savedSnapshots.map((sn) => ({ value: sn.id, label: sn.name }))}
+          onSelectionChange={(id) => {
+            if (id != null) c.loadSnapshot(String(id));
+          }}
+        />
+      ),
+    });
+  }
+  out.push({
+    id: 'clone',
+    region: 'toolbar',
+    group: 'trial',
+    end: true,
+    item: { icon: CloneIcon, label: 'Clone trial', onActivate: ctx.clone },
+  });
+  out.push({
+    id: 'reset',
+    region: 'toolbar',
+    group: 'trial',
+    end: true,
+    item: { icon: ResetIcon, label: 'Reset trial', onActivate: ctx.reset },
+  });
+  out.push({
+    id: 'close',
+    region: 'titlebar',
+    end: true,
+    item: {
+      icon: CloseIcon,
+      label: ctx.isLastTrial ? 'Cannot close the last trial' : 'Close trial',
+      danger: true,
+      disabled: ctx.isLastTrial,
+      onActivate: ctx.close,
+    },
+  });
+
+  return out;
+}

package/src/chrome/index.ts

@@ -0,0 +1,25 @@
+export { builtinContributions } from './builtins';
+export { mergeContributions, suppressContributions } from './merge';
+export type { PaletteRegionProps } from './regions/PaletteRegion';
+export { PaletteRegion } from './regions/PaletteRegion';
+export type { SidebarRegionProps } from './regions/SidebarRegion';
+export { SidebarRegion } from './regions/SidebarRegion';
+export type { StatusRegionProps } from './regions/StatusRegion';
+export { StatusRegion } from './regions/StatusRegion';
+export type { TitleBarRegionProps } from './regions/TitleBarRegion';
+export { TitleBarRegion } from './regions/TitleBarRegion';
+export type { ToolbarRegionProps } from './regions/ToolbarRegion';
+export { ToolbarRegion } from './regions/ToolbarRegion';
+export type { ViewportRegionProps } from './regions/ViewportRegion';
+export { ViewportRegion } from './regions/ViewportRegion';
+export type {
+  IconComponent,
+  SidebarSection,
+  StatusReadout,
+  ToolbarItem,
+  ToolItem,
+  TrialChromeContext,
+  TrialContribution,
+  TrialRegion,
+  ViewportControl,
+} from './types';

package/src/chrome/merge.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { mergeContributions, suppressContributions } from './merge';
+import type { TrialContribution } from './types';
+
+const Glyph = () => null;
+
+function toolbarItem(id: string): TrialContribution {
+  return {
+    id,
+    region: 'toolbar',
+    item: { icon: Glyph, label: id, onActivate: () => {} },
+  };
+}
+
+describe('mergeContributions', () => {
+  it('concatenates bundles in order', () => {
+    const out = mergeContributions([toolbarItem('a')], [toolbarItem('b'), toolbarItem('c')]);
+    expect(out.map((c) => c.id)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('throws on a duplicate id, naming it', () => {
+    expect(() => mergeContributions([toolbarItem('undo')], [toolbarItem('undo')])).toThrow(
+      /duplicate contribution id "undo"/,
+    );
+  });
+
+  it('accepts no bundles', () => {
+    expect(mergeContributions()).toEqual([]);
+  });
+});
+
+describe('suppressContributions', () => {
+  it('removes the named ids', () => {
+    const out = suppressContributions(
+      [toolbarItem('a'), toolbarItem('b'), toolbarItem('c')],
+      ['b'],
+    );
+    expect(out.map((c) => c.id)).toEqual(['a', 'c']);
+  });
+
+  it('throws on an id that is not there', () => {
+    expect(() => suppressContributions([toolbarItem('a')], ['snapshto'])).toThrow(
+      /cannot suppress "snapshto"/,
+    );
+  });
+
+  it('is a no-op for an empty suppress list', () => {
+    const bundle = [toolbarItem('a')];
+    expect(suppressContributions(bundle, [])).toEqual(bundle);
+  });
+});

package/src/chrome/merge.ts

@@ -0,0 +1,52 @@
+import type { TrialContribution } from './types';
+
+/**
+ * Concatenate contribution bundles into one list, preserving order — order
+ * decides how a region lays its contributions out, so it is part of the
+ * result, not an accident of it.
+ *
+ * Throws on a duplicate id rather than dropping one: a contribution silently
+ * losing to a later bundle is the failure a registry exists to prevent.
+ */
+export function mergeContributions(
+  ...bundles: readonly TrialContribution[][]
+): TrialContribution[] {
+  const out: TrialContribution[] = [];
+  const seen = new Set<string>();
+  for (const bundle of bundles) {
+    for (const entry of bundle) {
+      if (seen.has(entry.id)) {
+        throw new Error(
+          `[labkit] mergeContributions: duplicate contribution id "${entry.id}". ` +
+            'Two bundles registered the same id; rename one, or suppress the ' +
+            'built-in before adding yours.',
+        );
+      }
+      seen.add(entry.id);
+      out.push(entry);
+    }
+  }
+  return out;
+}
+
+/**
+ * Drop contributions by id. Throws when an id is not present: a typo that
+ * silently suppresses nothing is the same class of bug as a duplicate id
+ * silently winning.
+ */
+export function suppressContributions(
+  bundle: readonly TrialContribution[],
+  ids: readonly string[],
+): TrialContribution[] {
+  const present = new Set(bundle.map((c) => c.id));
+  for (const id of ids) {
+    if (!present.has(id)) {
+      throw new Error(
+        `[labkit] cannot suppress "${id}": no contribution with that id. ` +
+          `Present ids: ${[...present].join(', ')}`,
+      );
+    }
+  }
+  const drop = new Set(ids);
+  return bundle.filter((c) => !drop.has(c.id));
+}

package/src/chrome/regions/PaletteRegion.less

@@ -0,0 +1,14 @@
+.lk-palette-region {
+  display: flex;
+  flex-direction: column;
+  padding: var(--wzl-space-xs);
+  border-right: var(--wzl-border-w) solid var(--wzl-line-subtle);
+  background: var(--wzl-surface-sunken);
+
+  // labkit's `:where(button)` default sets an explicit height, and because
+  // :where() carries no specificity it also wins over ToolButton, which sizes
+  // itself from padding.
+  button {
+    height: auto;
+  }
+}

package/src/chrome/regions/PaletteRegion.test.tsx

@@ -0,0 +1,36 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { TrialChromeContext, TrialContribution } from '../types';
+import { PaletteRegion } from './PaletteRegion';
+
+const Glyph = () => <svg />;
+
+function ctxWith(activeToolId: string | null, setActiveTool = vi.fn()) {
+  return { trialId: 't1', activeToolId, setActiveTool } as unknown as TrialChromeContext;
+}
+
+function tool(id: string): TrialContribution {
+  return { id, region: 'palette', item: { icon: Glyph, label: id } };
+}
+
+describe('PaletteRegion', () => {
+  it('renders nothing when empty', () => {
+    const { container } = render(<PaletteRegion contributions={[]} ctx={ctxWith(null)} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('marks the resolved tool as current', () => {
+    render(
+      <PaletteRegion contributions={[tool('brush'), tool('eraser')]} ctx={ctxWith('brush')} />,
+    );
+    expect(screen.getByRole('button', { name: 'brush' })).toHaveAttribute('aria-current', 'true');
+    expect(screen.getByRole('button', { name: 'eraser' })).not.toHaveAttribute('aria-current');
+  });
+
+  it('sets the tool on click', () => {
+    const setActiveTool = vi.fn();
+    render(<PaletteRegion contributions={[tool('brush')]} ctx={ctxWith(null, setActiveTool)} />);
+    screen.getByRole('button', { name: 'brush' }).click();
+    expect(setActiveTool).toHaveBeenCalledWith('brush');
+  });
+});

package/src/chrome/regions/PaletteRegion.tsx

@@ -0,0 +1,41 @@
+import { ToolButton, ToolGroup } from '../../passthrough/weasel-ui';
+import type { TrialChromeContext, TrialContribution } from '../types';
+
+/** Props for `<PaletteRegion>`. */
+export interface PaletteRegionProps {
+  contributions: readonly TrialContribution[];
+  ctx: TrialChromeContext;
+}
+
+/** A trial's tool strip. Selection lives in the trial's or the lab's tool
+ *  slot; this region only reflects it. */
+export function PaletteRegion({ contributions, ctx }: PaletteRegionProps) {
+  if (contributions.length === 0) return null;
+  return (
+    <div
+      className="lk-palette-region"
+      role="toolbar"
+      aria-label="Tools"
+      aria-orientation="vertical"
+    >
+      <ToolGroup orientation="vertical">
+        {contributions.map((c) => {
+          if (c.render) return <span key={c.id}>{c.render(ctx)}</span>;
+          if (c.region !== 'palette' || !c.item) return null;
+          const { icon: Icon, label, shortcut, disabled } = c.item;
+          return (
+            <ToolButton
+              key={c.id}
+              icon={<Icon size={16} />}
+              label={label}
+              shortcut={shortcut}
+              active={ctx.activeToolId === c.id}
+              disabled={disabled}
+              onClick={() => ctx.setActiveTool(c.id)}
+            />
+          );
+        })}
+      </ToolGroup>
+    </div>
+  );
+}