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

package/src/lab/LabFullChrome.stories.tsx

@@ -0,0 +1,308 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useEffect, useRef } from 'react';
+import type { ConfigField } from '../controls/types';
+import { defineInstrument } from '../instrument/defineInstrument';
+import type { Instrument, RenderContext } from '../instrument/types';
+import type { JobEvent } from '../job/types';
+import { Lab } from './Lab';
+import { useLabContext } from './LabContext';
+
+interface ScanConfig {
+  gain: number;
+  integrationMs: number;
+  source: string;
+  channel: string;
+  traceColor: string;
+  autoBaseline: boolean;
+}
+
+interface ScanState {
+  samples: number[];
+  marks: number[];
+}
+
+const PLOT = { w: 240, h: 120 };
+
+function scanSchema(traceColor: string): ConfigField[] {
+  return [
+    { key: 'gain', label: 'Gain', type: 'slider', default: 1.4, min: 0.1, max: 4, step: 0.1 },
+    {
+      key: 'integrationMs',
+      label: 'Integration (ms)',
+      type: 'number',
+      default: 250,
+      min: 10,
+      max: 2000,
+      step: 10,
+    },
+    {
+      key: 'source',
+      label: 'Source',
+      type: 'select',
+      default: 'deuterium',
+      options: [
+        { value: 'deuterium', label: 'Deuterium' },
+        { value: 'tungsten', label: 'Tungsten' },
+        { value: 'xenon', label: 'Xenon flash' },
+      ],
+    },
+    { key: 'channel', label: 'Channel', type: 'text', default: 'CH-1', maxLength: 12 },
+    { key: 'traceColor', label: 'Trace', type: 'color', default: traceColor },
+    { key: 'autoBaseline', label: 'Auto baseline', type: 'checkbox', default: true },
+  ];
+}
+
+function wait(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}
+
+interface SweepSpec {
+  count: number;
+  everyMs: number;
+  /** Frame indices that report a `failed` event instead of a sample. */
+  dropped?: number[];
+  /** Frame index at which the whole run throws, and what it throws. */
+  faultAt?: number;
+  fault?: string;
+}
+
+async function* sweep(spec: SweepSpec, signal: AbortSignal): AsyncGenerator<JobEvent<number>> {
+  yield { kind: 'total', total: spec.count };
+  for (let i = 0; i < spec.count; i++) {
+    await wait(spec.everyMs, signal);
+    if (signal.aborted) return;
+    if (i === spec.faultAt) throw new Error(spec.fault ?? 'Sweep failed');
+    if (spec.dropped?.includes(i)) {
+      yield { kind: 'failed', index: i, error: `Frame ${i}: detector saturated` };
+      continue;
+    }
+    yield { kind: 'item', item: Math.sin(i * 0.55) * 42 + 58 };
+  }
+}
+
+// Rendered for its effect alone: a mark seeded on mount gives every trial one
+// undoable edit, so Undo reads live instead of starting greyed out.
+function SeedMarks({ ctx }: { ctx: RenderContext<ScanState, ScanConfig> }) {
+  const seeded = useRef(false);
+  useEffect(() => {
+    if (seeded.current) return;
+    seeded.current = true;
+    ctx.setState((prev) => ({ ...prev, marks: [...prev.marks, 64, 152] }));
+  }, [ctx]);
+  return null;
+}
+
+function scanInstrument(
+  name: string,
+  traceColor: string,
+  spec: SweepSpec,
+): Instrument<ScanState, ScanConfig, number> {
+  return defineInstrument<ScanState, ScanConfig, number>({
+    name,
+    defaultConfig: () => ({
+      gain: 1.4,
+      integrationMs: 250,
+      source: 'deuterium',
+      channel: 'CH-1',
+      traceColor,
+      autoBaseline: true,
+    }),
+    initialState: () => ({ samples: [], marks: [] }),
+    configSchema: () => scanSchema(traceColor),
+    render: (ctx) => <SeedMarks ctx={ctx} />,
+    canvas: {
+      initialView: { zoom: 1, pan: { x: 24, y: 24 } },
+      layers: [
+        {
+          id: 'grid',
+          draw: (c, { zoom }) => {
+            c.strokeStyle = '#8894a8';
+            c.globalAlpha = 0.3;
+            c.lineWidth = 1 / zoom;
+            for (let x = 0; x <= PLOT.w; x += 20) {
+              c.beginPath();
+              c.moveTo(x, 0);
+              c.lineTo(x, PLOT.h);
+              c.stroke();
+            }
+            for (let y = 0; y <= PLOT.h; y += 20) {
+              c.beginPath();
+              c.moveTo(0, y);
+              c.lineTo(PLOT.w, y);
+              c.stroke();
+            }
+            c.globalAlpha = 1;
+          },
+        },
+        {
+          id: 'trace',
+          draw: (c, { state, config, zoom }) => {
+            if (state.samples.length === 0) return;
+            c.strokeStyle = config.traceColor;
+            c.lineWidth = 2 / zoom;
+            c.beginPath();
+            state.samples.forEach((sample, i) => {
+              const x = i * 10;
+              const y = PLOT.h - Math.min(PLOT.h, sample * config.gain * 0.7);
+              if (i === 0) c.moveTo(x, y);
+              else c.lineTo(x, y);
+            });
+            c.stroke();
+          },
+        },
+        {
+          id: 'marks',
+          draw: (c, { state, zoom }) => {
+            c.strokeStyle = '#f08c00';
+            c.lineWidth = 1 / zoom;
+            for (const x of state.marks) {
+              c.beginPath();
+              c.moveTo(x, 0);
+              c.lineTo(x, PLOT.h);
+              c.stroke();
+            }
+          },
+        },
+      ],
+    },
+    layers: {
+      ids: [
+        { id: 'grid', label: 'Grid', alwaysOn: true },
+        { id: 'trace', label: 'Trace' },
+        { id: 'marks', label: 'Marks' },
+      ],
+    },
+    dragDrop: {
+      palette: [
+        { id: 'peak', label: 'Peak marker' },
+        { id: 'baseline', label: 'Baseline point' },
+        { id: 'window', label: 'Integration window' },
+      ],
+      onDrop: (worldPos, _item, state) => ({ ...state, marks: [...state.marks, worldPos.x] }),
+    },
+    undo: { snapshotOn: ['state.change', 'canvas.itemAdded'], maxDepth: 20 },
+    job: {
+      auto: true,
+      run: ({ signal }) => sweep(spec, signal),
+      onItem: (item, state) => ({ ...state, samples: [...state.samples, item] }),
+    },
+  });
+}
+
+const spectrometer = scanInstrument('Spectrometer', '#5ad1ff', { count: 24, everyMs: 1200 });
+const beamProfile = scanInstrument('Beam profile', '#ffd166', {
+  count: 12,
+  everyMs: 900,
+  dropped: [4, 9],
+});
+const thermalDrift = scanInstrument('Thermal drift', '#ff8fa3', {
+  count: 8,
+  everyMs: 800,
+  faultAt: 3,
+  fault: 'Sensor bus timeout on channel 2',
+});
+
+/** Opens the other two trials and saves one snapshot per trial, so every
+ *  toolbar shows its Load control and the header's Select has somewhere to
+ *  add to. */
+function SeedTrials() {
+  const lab = useLabContext();
+  const opened = useRef(false);
+  const saved = useRef(false);
+  useEffect(() => {
+    if (!opened.current) {
+      opened.current = true;
+      lab.addTrial('Beam profile');
+      lab.addTrial('Thermal drift');
+      return;
+    }
+    if (!saved.current && lab.trials.length === 3) {
+      saved.current = true;
+      for (const trial of lab.trials) lab.saveSnapshot(trial.id, 'Baseline');
+    }
+  }, [lab]);
+  return null;
+}
+
+const runLog = defineInstrument<{ lines: string[] }, Record<string, never>>({
+  name: 'Run log',
+  defaultConfig: () => ({}),
+  initialState: () => ({
+    lines: ['09:04 lamp warm', '09:06 slit 50 µm', '09:12 calibrated', '09:14 sweep armed'],
+  }),
+  render: ({ state }) => (
+    <div className="lk-run-log">
+      {state.lines.map((line) => (
+        <div key={line}>{line}</div>
+      ))}
+    </div>
+  ),
+});
+
+const meta: Meta<typeof Lab> = {
+  title: 'labkit/Lab/FullChrome',
+  component: Lab,
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Lab>;
+
+/** Every chrome surface a lab renders, on screen at once: three instruments so
+ *  the header offers its Select, three trials each carrying a title bar, the
+ *  full toolbar, a control panel with one of every field type, the palette and
+ *  layer list, and a status bar with a running job. Starts in dark, where the
+ *  `nebula` backdrop paints. */
+export const AllChrome: Story = {
+  args: {
+    instruments: [spectrometer, beamProfile, thermalDrift],
+    defaultInstrument: 'Spectrometer',
+    title: 'Optics bench',
+    storage: null,
+    mode: 'dark',
+    nebula: ['#3b5bdb', '#7048e8', '#0ca678'],
+    children: (
+      <>
+        <SeedTrials />
+        <span className="lk-run-tag">Run 42 · bench 3</span>
+      </>
+    ),
+  },
+};
+
+/** The chrome the other story cannot show at the same time: one instrument, so
+ *  the header is an Add trial button; one trial, so Close is disabled; no
+ *  config schema, canvas, undo or job, so the sidebar falls back to its
+ *  placeholder and the toolbar keeps only what is left. */
+export const SingleInstrument: Story = {
+  args: {
+    instruments: [runLog],
+    defaultInstrument: 'Run log',
+    title: 'Run log',
+    storage: null,
+  },
+};
+
+/** The shell footer, which `<Lab>` had no prop for — reaching it used to mean
+ *  building `<LabShell>` yourself. Trial chrome is contributions now; see
+ *  `labkit/Chrome/Regions` for those. */
+export const WithFooter: Story = {
+  args: {
+    instruments: [spectrometer, beamProfile],
+    defaultInstrument: 'Spectrometer',
+    title: 'With footer',
+    storage: null,
+    mode: 'dark',
+    footer: <span className="lk-run-tag">Footer — reached through LabProps.footer</span>,
+  },
+};

package/src/lab/LabHeader.test.tsx

@@ -0,0 +1,42 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import type { Instrument } from '../instrument/types';
+import { Lab } from './Lab';
+
+const Stub: Instrument = {
+  name: 'Stub',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => <div>stub</div>,
+};
+const Other: Instrument = { ...Stub, name: 'Other' };
+
+describe('<LabHeader>', () => {
+  it('offers an add-trial button when the lab has one instrument', () => {
+    render(<Lab instruments={[Stub]} defaultInstrument="Stub" storage={null} />);
+    expect(screen.getByRole('button', { name: /add trial/i })).toBeInTheDocument();
+  });
+
+  it('offers a picker instead when the lab has several', () => {
+    render(<Lab instruments={[Stub, Other]} defaultInstrument="Stub" storage={null} />);
+    // A picker, not a button — which instrument to add is now a choice.
+    expect(screen.queryByRole('button', { name: /^add trial$/i })).toBeNull();
+    expect(screen.getByLabelText(/add trial/i)).toBeInTheDocument();
+  });
+
+  it('adds a trial when the button is used', async () => {
+    const { default: userEvent } = await import('@testing-library/user-event');
+    const user = userEvent.setup();
+    render(<Lab instruments={[Stub]} defaultInstrument="Stub" storage={null} />);
+    expect(screen.getAllByLabelText(/^Trial Stub$/)).toHaveLength(1);
+    await user.click(screen.getByRole('button', { name: /add trial/i }));
+    expect(screen.getAllByLabelText(/^Trial Stub$/)).toHaveLength(2);
+  });
+
+  it('exposes the color mode as a three-way choice', () => {
+    render(<Lab instruments={[Stub]} defaultInstrument="Stub" storage={null} />);
+    for (const label of ['Auto', 'Light', 'Dark']) {
+      expect(screen.getByRole('radio', { name: label })).toBeInTheDocument();
+    }
+  });
+});

package/src/lab/LabHeader.tsx

@@ -0,0 +1,57 @@
+import { AddIcon } from '@weasel-js/ui';
+import { Select, ToggleBar } from '../passthrough/weasel-ui';
+import type { LabMode } from '../state/types';
+import { useLabContext } from './LabContext';
+
+const MODES: { value: LabMode; label: string }[] = [
+  { value: 'auto', label: 'Auto' },
+  { value: 'light', label: 'Light' },
+  { value: 'dark', label: 'Dark' },
+];
+
+/** The controls `<Lab>` puts in its header: add a trial, and choose the color
+ *  mode. Both drive `LabContext`, which carried them with no UI at all — so
+ *  every consumer rebuilt these two. Rendered before a consumer's own header
+ *  content, which still lands beside them. */
+export function LabHeader() {
+  const lab = useLabContext();
+  const only = lab.instruments.length === 1 ? lab.instruments[0] : null;
+
+  return (
+    <>
+      {only ? (
+        <button
+          type="button"
+          className="lk-lab-header__add"
+          onClick={() => lab.addTrial(only.name)}
+        >
+          <AddIcon size={16} />
+          <span>Add trial</span>
+        </button>
+      ) : (
+        // Held at null so the control stays an "add one" action rather than
+        // reading as the current instrument.
+        <Select
+          className="lk-lab-header__add-select"
+          aria-label="Add trial"
+          placeholder="Add trial…"
+          selectedKey={null}
+          options={lab.instruments.map((i) => ({ value: i.name, label: i.name }))}
+          onSelectionChange={(name) => {
+            if (name != null) lab.addTrial(String(name));
+          }}
+        />
+      )}
+
+      <ToggleBar
+        className="lk-lab-header__mode"
+        ariaLabel="Color mode"
+        items={MODES}
+        value={lab.mode}
+        onChange={(next) => {
+          if (next) lab.setMode(next);
+        }}
+      />
+    </>
+  );
+}

package/src/lab/LabPalette.test.tsx

@@ -0,0 +1,35 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import type { Instrument } from '../instrument/types';
+import { Lab } from './Lab';
+
+const Glyph = () => <svg />;
+const bare: Instrument = {
+  name: 'Bare',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => null,
+};
+const tools = [
+  { id: 'pick', label: 'Pick', icon: Glyph },
+  { id: 'pan', label: 'Pan', icon: Glyph },
+];
+
+describe('the lab palette', () => {
+  it('does not render when the lab declares no tools', () => {
+    render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" />);
+    expect(screen.queryByRole('toolbar', { name: 'Tools' })).toBeNull();
+  });
+
+  it('renders one button per declared tool', () => {
+    render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" tools={tools} />);
+    expect(screen.getByRole('button', { name: 'Pick' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Pan' })).toBeInTheDocument();
+  });
+
+  it('marks the chosen tool current after a click', () => {
+    render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" tools={tools} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Pan' }));
+    expect(screen.getByRole('button', { name: 'Pan' })).toHaveAttribute('aria-current', 'true');
+  });
+});

package/src/lab/LabPalette.tsx

@@ -0,0 +1,34 @@
+import { useContext } from 'react';
+import { useStore } from 'zustand/react';
+import { PaletteRegion } from '../chrome/regions/PaletteRegion';
+import type { TrialChromeContext, TrialContribution } from '../chrome/types';
+import { LabStoreContext } from '../state/context';
+import type { TrialTool } from '../tools/types';
+
+/** Props for `<LabPalette>`. */
+export interface LabPaletteProps {
+  tools: readonly TrialTool[];
+}
+
+/** The lab's tool strip. Writes the lab's tool slot, which every trial whose
+ *  instrument declares no tools of its own resolves to. */
+export function LabPalette({ tools }: LabPaletteProps) {
+  const storeCtx = useContext(LabStoreContext);
+  if (!storeCtx) throw new Error('[labkit] LabPalette requires <LabStoreProvider>');
+  const activeToolId = useStore(storeCtx.store, (s) => s.activeToolId);
+  const setLabTool = useStore(storeCtx.store, (s) => s.setLabTool);
+
+  const contributions: TrialContribution[] = tools.map((t) => ({
+    id: t.id,
+    region: 'palette',
+    group: t.group,
+    item: { icon: t.icon, label: t.label, shortcut: t.shortcut },
+  }));
+
+  const ctx = {
+    activeToolId,
+    setActiveTool: setLabTool,
+  } as unknown as TrialChromeContext;
+
+  return <PaletteRegion contributions={contributions} ctx={ctx} />;
+}

package/src/lab/LabShell.less

@@ -6,6 +6,12 @@
   background: var(--wzl-surface);
 }
 
+// Standalone, the shell owns its surface. Inside `<Lab>` that surface is the
+// one thing between the viewer and `.lk-lab`'s nebula, so it steps aside.
+.lk-lab > .lk-shell {
+  background: transparent;
+}
+
 .lk-shell-header {
   display: flex;
   align-items: center;
@@ -18,8 +24,8 @@
 
 .lk-shell-title {
   margin: 0;
-  font-size: 16px;
-  font-weight: 600;
+  font-size: var(--wzl-font-size-xl);
+  font-weight: var(--wzl-font-weight-bold);
   color: var(--wzl-fg);
 }
 
@@ -33,7 +39,19 @@
   flex: 1;
   min-height: 0;
   overflow: auto;
-  padding: var(--wzl-space-md);
+  padding: var(--lk-workspace-pad);
+}
+
+// `.lk-shell-body` is a block container, so `flex: 1` here resolves to nothing
+// and the workspace's `height: 100%` collapses to zero.
+.lk-lab__body {
+  display: flex;
+  height: 100%;
+  min-height: 0;
+
+  > .lk-workspace {
+    min-width: 0;
+  }
 }
 
 .lk-shell-footer {
@@ -43,3 +61,32 @@
   color: var(--wzl-fg-muted);
   font-size: var(--wzl-font-size-sm);
 }
+
+.lk-lab-header__add {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--wzl-space-xs);
+}
+
+// `Select` is a form field and defaults to `width: 100%`. Left to resolve that
+// against a shrink-to-fit header row it swallows the slack, which pushed the
+// consumer's own header content down to min-content and wrapped the row to
+// three lines. See the `.lk-root` prefix convention in theme/base.less.
+.lk-root .lk-lab-header__add-select {
+  width: 160px;
+}
+
+// The mode toggle is a preference, not a primary action: it sits quiet until
+// the pointer is on it.
+.lk-lab-header__mode {
+  opacity: 0.75;
+  // A consumer's own header content shares this row and does not shrink, so
+  // without this the segments compress past their labels and the pill track
+  // disappears entirely.
+  flex-shrink: 0;
+
+  &:hover,
+  &:focus-within {
+    opacity: 1;
+  }
+}

package/src/lab/Workspace.less

@@ -5,36 +5,7 @@
   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-trial-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;
-  }
+  min-height: 0;
 }

package/src/lab/Workspace.test.tsx

@@ -1,7 +1,15 @@
 import { render, screen } from '@testing-library/react';
 import { describe, expect, test, vi } from 'vitest';
+import { useTrialDrag } from '../trial/TrialDragContext';
 import { Workspace } from './Workspace';
 
+/** Reports whether its tile supplied a drag source — the title bar is the
+ *  drag surface now, so there is no grip element to assert on. */
+function DragProbe({ label }: { label: string }) {
+  const drag = useTrialDrag();
+  return <div data-testid={`drag-${label}`}>{drag ? 'draggable' : 'static'}</div>;
+}
+
 const VIEWPORT = { w: 800, h: 600 };
 
 describe('Workspace', () => {
@@ -88,13 +96,14 @@ describe('Workspace', () => {
     const onReorder = vi.fn();
     const { container } = render(
       <Workspace ids={['a', 'b']} reorderable onReorder={onReorder} viewport={VIEWPORT}>
-        <div>a</div>
-        <div>b</div>
+        <DragProbe label="a" />
+        <DragProbe label="b" />
       </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);
+    // The grid is controlled: each tile offers itself as a drag source and
+    // commits nothing itself. Order still comes from `ids`.
+    expect(screen.getByTestId('drag-a')).toHaveTextContent('draggable');
+    expect(screen.getByTestId('drag-b')).toHaveTextContent('draggable');
     expect(onReorder).not.toHaveBeenCalled();
     const nodes = [...container.querySelectorAll('[data-node]')].map((el) =>
       el.getAttribute('data-node'),
@@ -102,13 +111,14 @@ describe('Workspace', () => {
     expect(nodes).toEqual(['a', 'b']);
   });
 
-  test('renders no drag handles unless reorderable', () => {
-    const { container } = render(
+  test('offers no drag source unless reorderable', () => {
+    render(
       <Workspace ids={['a', 'b']} viewport={VIEWPORT}>
-        <div>a</div>
-        <div>b</div>
+        <DragProbe label="a" />
+        <DragProbe label="b" />
       </Workspace>,
     );
-    expect(container.querySelectorAll('.lk-trial-tile__grip')).toHaveLength(0);
+    expect(screen.getByTestId('drag-a')).toHaveTextContent('static');
+    expect(screen.getByTestId('drag-b')).toHaveTextContent('static');
   });
 });

package/src/lab/Workspace.tsx

@@ -11,13 +11,13 @@ import { asNodeId, createNode, gridStrategy, type NodeId, Store } from 'windease
 import {
   type ChromeMap,
   Container,
-  DragHandle,
   DragProvider,
   Provider,
   StrategyRegistryProvider,
 } from 'windease/react';
 
 import { useSurfaceOptional } from '../surface/useSurfaceTile';
+import { TrialDragContext } from '../trial/TrialDragContext';
 
 const ZONE_ID = asNodeId('lk-workspace');
 const STRATEGIES = { grid: gridStrategy as never };
@@ -175,14 +175,11 @@ export function Workspace({
       [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>
+          // No grip strip: the trial's own title bar is the drag surface.
+          <TrialDragContext.Provider value={{ nodeId: node.id }}>
+            <div className="lk-trial-tile">{content}</div>
+          </TrialDragContext.Provider>
         );
       },
     };