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

package/src/chrome/regions/SidebarRegion.tsx

@@ -0,0 +1,56 @@
+import type { ReactNode } from 'react';
+import { useState } from 'react';
+import type { TrialChromeContext, TrialContribution } from '../types';
+
+/** Props for `<SidebarRegion>`. */
+export interface SidebarRegionProps {
+  contributions: readonly TrialContribution[];
+  ctx: TrialChromeContext;
+}
+
+function Section({
+  title,
+  defaultCollapsed,
+  children,
+}: {
+  title: string;
+  defaultCollapsed: boolean;
+  children: ReactNode;
+}) {
+  const [collapsed, setCollapsed] = useState(defaultCollapsed);
+  return (
+    <section className="lk-sidebar-section">
+      <button
+        type="button"
+        className="lk-sidebar-section__head"
+        aria-expanded={!collapsed}
+        onClick={() => setCollapsed((c) => !c)}
+      >
+        {title}
+      </button>
+      {collapsed ? null : <div className="lk-sidebar-section__body">{children}</div>}
+    </section>
+  );
+}
+
+/** Lays a trial's `sidebar` contributions out as titled, collapsible sections. */
+export function SidebarRegion({ contributions, ctx }: SidebarRegionProps) {
+  if (contributions.length === 0) return null;
+  return (
+    <>
+      {contributions.map((c) => {
+        if (c.render) return <div key={c.id}>{c.render(ctx)}</div>;
+        if (c.region !== 'sidebar' || !c.item) return null;
+        return (
+          <Section
+            key={c.id}
+            title={c.item.title}
+            defaultCollapsed={c.item.defaultCollapsed ?? false}
+          >
+            {c.item.body}
+          </Section>
+        );
+      })}
+    </>
+  );
+}

package/src/chrome/regions/StatusRegion.tsx

@@ -0,0 +1,31 @@
+import { StatusBar } from '../../primitives/StatusBar';
+import type { TrialChromeContext, TrialContribution } from '../types';
+
+/** Props for `<StatusRegion>`. */
+export interface StatusRegionProps {
+  contributions: readonly TrialContribution[];
+  ctx: TrialChromeContext;
+}
+
+/** Lays a trial's `status` contributions out as readouts. */
+export function StatusRegion({ contributions, ctx }: StatusRegionProps) {
+  if (contributions.length === 0) return null;
+  return (
+    <StatusBar>
+      {contributions.map((c) => {
+        if (c.render)
+          return (
+            <StatusBar.Section key={c.id} end={c.end}>
+              {c.render(ctx)}
+            </StatusBar.Section>
+          );
+        if (c.region !== 'status' || !c.item) return null;
+        return (
+          <StatusBar.Section key={c.id} end={c.end}>
+            <span title={c.item.title}>{c.item.text}</span>
+          </StatusBar.Section>
+        );
+      })}
+    </StatusBar>
+  );
+}

package/src/chrome/regions/TitleBarRegion.tsx

@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react';
+import type { TrialChromeContext, TrialContribution } from '../types';
+
+/** Props for `<TitleBarRegion>`. */
+export interface TitleBarRegionProps {
+  contributions: readonly TrialContribution[];
+  ctx: TrialChromeContext;
+}
+
+function renderEntry(c: TrialContribution, ctx: TrialChromeContext): ReactNode {
+  if (c.render) return <span key={c.id}>{c.render(ctx)}</span>;
+  if (c.region !== 'titlebar' || !c.item) return null;
+  const { icon: Icon, label, shortcut, disabled, danger } = c.item;
+  return (
+    <button
+      key={c.id}
+      type="button"
+      className={`lk-titlebar-button${danger ? ' lk-titlebar-button--danger' : ''}`}
+      disabled={disabled}
+      aria-label={label}
+      title={shortcut ? `${label} (${shortcut})` : label}
+      onClick={c.item.onActivate}
+      // The bar behind these buttons is the window drag surface, so a press
+      // that lands here must not also start a drag.
+      onPointerDown={(e) => e.stopPropagation()}
+      onMouseDown={(e) => e.stopPropagation()}
+    >
+      <Icon size={14} />
+    </button>
+  );
+}
+
+/** Lays a trial's `titlebar` contributions out, at the far end of the bar. */
+export function TitleBarRegion({ contributions, ctx }: TitleBarRegionProps) {
+  if (contributions.length === 0) return null;
+  return (
+    <span className="lk-trial__titlebar-actions">
+      {contributions.map((c) => renderEntry(c, ctx))}
+    </span>
+  );
+}

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

@@ -0,0 +1,82 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { TrialChromeContext, TrialContribution } from '../types';
+import { ToolbarRegion } from './ToolbarRegion';
+
+const Glyph = () => <svg data-testid="glyph" />;
+
+const ctx = { trialId: 't1' } as unknown as TrialChromeContext;
+
+function item(id: string, over: Partial<TrialContribution> = {}): TrialContribution {
+  return {
+    id,
+    region: 'toolbar',
+    item: { icon: Glyph, label: id, onActivate: () => {} },
+    ...over,
+  } as TrialContribution;
+}
+
+describe('ToolbarRegion', () => {
+  it('renders nothing when it has no contributions', () => {
+    const { container } = render(<ToolbarRegion contributions={[]} ctx={ctx} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('renders one button per contribution, labelled', () => {
+    render(<ToolbarRegion contributions={[item('undo'), item('redo')]} ctx={ctx} />);
+    expect(screen.getByRole('button', { name: 'undo' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'redo' })).toBeInTheDocument();
+  });
+
+  it('fires onActivate on click', () => {
+    const onActivate = vi.fn();
+    render(
+      <ToolbarRegion
+        contributions={[
+          { id: 'go', region: 'toolbar', item: { icon: Glyph, label: 'Go', onActivate } },
+        ]}
+        ctx={ctx}
+      />,
+    );
+    screen.getByRole('button', { name: 'Go' }).click();
+    expect(onActivate).toHaveBeenCalledOnce();
+  });
+
+  it('groups contributions sharing a group into one group element', () => {
+    render(
+      <ToolbarRegion
+        contributions={[
+          item('undo', { group: 'history' }),
+          item('redo', { group: 'history' }),
+          item('close', { group: 'trial' }),
+        ]}
+        ctx={ctx}
+      />,
+    );
+    expect(screen.getAllByRole('group')).toHaveLength(2);
+  });
+
+  it('renders a render-escape contribution verbatim', () => {
+    render(
+      <ToolbarRegion
+        contributions={[{ id: 'custom', region: 'toolbar', render: () => <b>custom</b> }]}
+        ctx={ctx}
+      />,
+    );
+    expect(screen.getByText('custom')).toBeInTheDocument();
+  });
+
+  it('disables a button whose item says so', () => {
+    render(
+      <ToolbarRegion
+        contributions={[
+          item('undo', {
+            item: { icon: Glyph, label: 'Undo', disabled: true, onActivate: () => {} },
+          }),
+        ]}
+        ctx={ctx}
+      />,
+    );
+    expect(screen.getByRole('button', { name: 'Undo' })).toBeDisabled();
+  });
+});

package/src/chrome/regions/ToolbarRegion.tsx

@@ -0,0 +1,71 @@
+import type { ReactNode } from 'react';
+import { Toolbar } from '../../primitives/Toolbar';
+import type { TrialChromeContext, TrialContribution } from '../types';
+
+/** Props for `<ToolbarRegion>`. */
+export interface ToolbarRegionProps {
+  contributions: readonly TrialContribution[];
+  ctx: TrialChromeContext;
+}
+
+interface Group {
+  key: string;
+  end: boolean;
+  entries: TrialContribution[];
+}
+
+/** Bucket by group, preserving first-appearance order. Ungrouped
+ *  contributions each become their own bucket so they stay in place. */
+function groupsOf(contributions: readonly TrialContribution[]): Group[] {
+  const groups: Group[] = [];
+  const byKey = new Map<string, Group>();
+  for (const c of contributions) {
+    if (c.group == null) {
+      groups.push({ key: c.id, end: c.end ?? false, entries: [c] });
+      continue;
+    }
+    let g = byKey.get(c.group);
+    if (!g) {
+      g = { key: c.group, end: c.end ?? false, entries: [] };
+      byKey.set(c.group, g);
+      groups.push(g);
+    }
+    g.entries.push(c);
+  }
+  return groups;
+}
+
+function renderEntry(c: TrialContribution, ctx: TrialChromeContext): ReactNode {
+  if (c.render) return <span key={c.id}>{c.render(ctx)}</span>;
+  if (c.region !== 'toolbar' || !c.item) return null;
+  const { icon: Icon, label, shortcut, disabled, danger, showLabel } = c.item;
+  return (
+    <Toolbar.Button
+      key={c.id}
+      iconOnly={!showLabel}
+      variant={danger ? 'danger' : 'default'}
+      disabled={disabled}
+      aria-label={label}
+      title={shortcut ? `${label} (${shortcut})` : label}
+      onClick={c.item.onActivate}
+    >
+      <Icon size={16} />
+      {showLabel ? <span>{label}</span> : null}
+    </Toolbar.Button>
+  );
+}
+
+/** Lays a trial's `toolbar` contributions out, grouped by their `group`. */
+export function ToolbarRegion({ contributions, ctx }: ToolbarRegionProps) {
+  if (contributions.length === 0) return null;
+  const groups = groupsOf(contributions);
+  return (
+    <Toolbar aria-label="Trial actions">
+      {groups.map((g) => (
+        <Toolbar.Group key={g.key} end={g.end} aria-label={g.key}>
+          {g.entries.map((c) => renderEntry(c, ctx))}
+        </Toolbar.Group>
+      ))}
+    </Toolbar>
+  );
+}

package/src/chrome/regions/ViewportRegion.less

@@ -0,0 +1,42 @@
+.lk-viewport-controls {
+  position: absolute;
+  right: var(--wzl-space-sm);
+  bottom: var(--wzl-space-sm);
+  z-index: var(--wzl-z-overlay);
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+  // Bounded by the well it floats in, so a wide control cluster wraps into the
+  // corner rather than running out under the sidebar.
+  max-width: calc(100% - 2 * var(--wzl-space-sm));
+  gap: var(--wzl-space-xs);
+  padding: var(--wzl-space-xs);
+  border: var(--wzl-border-w) solid var(--wzl-border);
+  border-radius: var(--wzl-radius-md);
+  background: var(--wzl-surface-raised);
+  backdrop-filter: blur(var(--wzl-glass-blur));
+}
+
+.lk-viewport-controls__button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--wzl-control-h);
+  height: var(--wzl-control-h);
+  padding: 0;
+  border: 0;
+  border-radius: var(--wzl-radius-sm);
+  background: transparent;
+  color: var(--wzl-fg-muted);
+  cursor: pointer;
+
+  &:hover:not(:disabled) {
+    background: var(--wzl-surface-hover);
+    color: var(--wzl-fg);
+  }
+
+  &:disabled {
+    opacity: 0.4;
+    cursor: default;
+  }
+}

package/src/chrome/regions/ViewportRegion.tsx

@@ -0,0 +1,37 @@
+import type { TrialChromeContext, TrialContribution } from '../types';
+
+/** Props for `<ViewportRegion>`. */
+export interface ViewportRegionProps {
+  contributions: readonly TrialContribution[];
+  ctx: TrialChromeContext;
+}
+
+/**
+ * Controls acting on the view of a trial. Anchored inside the content well
+ * rather than in the toolbar, which acts on the trial itself.
+ */
+export function ViewportRegion({ contributions, ctx }: ViewportRegionProps) {
+  if (contributions.length === 0) return null;
+  return (
+    <div className="lk-viewport-controls" role="toolbar" aria-label="View">
+      {contributions.map((c) => {
+        if (c.render) return <span key={c.id}>{c.render(ctx)}</span>;
+        if (c.region !== 'viewport' || !c.item) return null;
+        const { icon: Icon, label, disabled } = c.item;
+        return (
+          <button
+            key={c.id}
+            type="button"
+            className="lk-viewport-controls__button"
+            aria-label={label}
+            title={label}
+            disabled={disabled}
+            onClick={c.item.onActivate}
+          >
+            <Icon size={16} />
+          </button>
+        );
+      })}
+    </div>
+  );
+}

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

@@ -0,0 +1,81 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { TrialChromeContext, TrialContribution } from '../types';
+import { SidebarRegion } from './SidebarRegion';
+import { StatusRegion } from './StatusRegion';
+import { ViewportRegion } from './ViewportRegion';
+
+const Glyph = () => <svg />;
+const ctx = { trialId: 't1' } as unknown as TrialChromeContext;
+
+describe('SidebarRegion', () => {
+  it('renders nothing when empty', () => {
+    const { container } = render(<SidebarRegion contributions={[]} ctx={ctx} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('renders each section with its title and body', () => {
+    const contributions: TrialContribution[] = [
+      { id: 'settings', region: 'sidebar', item: { title: 'Settings', body: <p>fields</p> } },
+      { id: 'layers', region: 'sidebar', item: { title: 'Layers', body: <p>list</p> } },
+    ];
+    render(<SidebarRegion contributions={contributions} ctx={ctx} />);
+    expect(screen.getByText('Settings')).toBeInTheDocument();
+    expect(screen.getByText('fields')).toBeInTheDocument();
+    expect(screen.getByText('Layers')).toBeInTheDocument();
+  });
+
+  it('starts a section collapsed when it asks to', () => {
+    render(
+      <SidebarRegion
+        contributions={[
+          {
+            id: 's',
+            region: 'sidebar',
+            item: { title: 'S', defaultCollapsed: true, body: <p>hidden</p> },
+          },
+        ]}
+        ctx={ctx}
+      />,
+    );
+    expect(screen.queryByText('hidden')).not.toBeInTheDocument();
+  });
+});
+
+describe('StatusRegion', () => {
+  it('renders nothing when empty', () => {
+    const { container } = render(<StatusRegion contributions={[]} ctx={ctx} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('renders each readout as text', () => {
+    render(
+      <StatusRegion
+        contributions={[{ id: 'zoom', region: 'status', item: { text: '150%' } }]}
+        ctx={ctx}
+      />,
+    );
+    expect(screen.getByText('150%')).toBeInTheDocument();
+  });
+});
+
+describe('ViewportRegion', () => {
+  it('renders nothing when empty', () => {
+    const { container } = render(<ViewportRegion contributions={[]} ctx={ctx} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('fires a control on click', () => {
+    const onActivate = vi.fn();
+    render(
+      <ViewportRegion
+        contributions={[
+          { id: 'fit', region: 'viewport', item: { icon: Glyph, label: 'Fit', onActivate } },
+        ]}
+        ctx={ctx}
+      />,
+    );
+    screen.getByRole('button', { name: 'Fit' }).click();
+    expect(onActivate).toHaveBeenCalledOnce();
+  });
+});

package/src/chrome/types.ts

@@ -0,0 +1,127 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { ResolvedConfig } from '../config/types';
+import type { ConfigField } from '../controls/types';
+import type { SavedSnapshot } from '../state/types';
+
+/** A named position in a trial's chrome. Content is not a region — that is
+ *  the instrument. */
+export type TrialRegion = 'titlebar' | 'toolbar' | 'palette' | 'sidebar' | 'viewport' | 'status';
+
+/** An icon component taking a pixel size, as `@weasel-js/ui` glyphs do. */
+export type IconComponent = ComponentType<{ size?: number }>;
+
+/** A button in the trial toolbar. */
+export interface ToolbarItem {
+  icon: IconComponent;
+  label: string;
+  /** Shown in the tooltip. Not bound here — the trial owns its keymap. */
+  shortcut?: string;
+  disabled?: boolean;
+  /** Reddens on hover. For actions that discard work. */
+  danger?: boolean;
+  /** Render the label beside the glyph rather than only in the tooltip. */
+  showLabel?: boolean;
+  onActivate: () => void;
+}
+
+/** A selectable tool in the palette region. */
+export interface ToolItem {
+  icon: IconComponent;
+  label: string;
+  shortcut?: string;
+  disabled?: boolean;
+}
+
+/** A titled block in the sidebar. */
+export interface SidebarSection {
+  title: string;
+  /** Starts collapsed. The open/closed state itself is the region's. */
+  defaultCollapsed?: boolean;
+  body: ReactNode;
+}
+
+/** A control acting on the view of the trial, not on the trial. */
+export interface ViewportControl {
+  icon: IconComponent;
+  label: string;
+  disabled?: boolean;
+  onActivate: () => void;
+}
+
+/** A readout in the status bar. */
+export interface StatusReadout {
+  /** Short enough for a status bar. Rendered as text. */
+  text: string;
+  /** Tooltip. */
+  title?: string;
+}
+
+/** What every contribution shares. */
+interface ContributionBase {
+  id: string;
+  /** Groups sort by first appearance; items sort within a group by
+   *  declaration order. Contributions with no group sort after grouped ones. */
+  group?: string;
+  /** Pushes this contribution, and its group, to the far end of the region. */
+  end?: boolean;
+}
+
+/**
+ * A contribution is data the chrome renders, keyed to a region. Supplying
+ * `render` instead of `item` opts out of the chrome's layout — deliberate,
+ * and visible in the declaration.
+ */
+export type TrialContribution =
+  | (ContributionBase & { region: 'titlebar'; item: ToolbarItem; render?: never })
+  | (ContributionBase & { region: 'toolbar'; item: ToolbarItem; render?: never })
+  | (ContributionBase & { region: 'palette'; item: ToolItem; render?: never })
+  | (ContributionBase & { region: 'sidebar'; item: SidebarSection; render?: never })
+  | (ContributionBase & { region: 'viewport'; item: ViewportControl; render?: never })
+  | (ContributionBase & { region: 'status'; item: StatusReadout; render?: never })
+  | (ContributionBase & {
+      region: TrialRegion;
+      item?: never;
+      render: (ctx: TrialChromeContext) => ReactNode;
+    });
+
+/**
+ * Everything a contribution can read about the trial it is being rendered
+ * into. Replaces the three separate slot contexts, which each carried a
+ * hand-picked subset.
+ */
+export interface TrialChromeContext {
+  trialId: string;
+  instrumentName: string;
+  isLastTrial: boolean;
+
+  /** Null when the trial holds a view that is not the 2D one. */
+  zoom: number | null;
+  setZoom: (z: number) => void;
+
+  canUndo: boolean;
+  canRedo: boolean;
+  undo: () => void;
+  redo: () => void;
+
+  /** The instrument's controls, resolved against the lab's rules. Always
+   *  populated: a legacy `configSchema()` is adapted into the same shape. */
+  configSchema: ResolvedConfig;
+  /** @deprecated Read `configSchema`. Empty for an instrument declaring
+   *  `config`, since a builder schema has no `ConfigField[]` form. */
+  configFields: ConfigField[];
+  config: unknown;
+  setConfig: (key: string, value: unknown) => void;
+
+  savedSnapshots: SavedSnapshot[];
+  saveSnapshot: (name?: string) => void;
+  loadSnapshot: (snapshotId: string) => void;
+
+  clone: () => void;
+  reset: () => void;
+  close: () => void;
+
+  /** Resolved active tool: the trial's slot, or the lab's when the trial has
+   *  none. Null when neither holds one. */
+  activeToolId: string | null;
+  setActiveTool: (id: string) => void;
+}

package/src/config/builder.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+import { f } from './builder';
+
+describe('builder', () => {
+  it('carries kind and default', () => {
+    const n = f.number(20);
+    expect(n.kind).toBe('number');
+    expect(n.default).toBe(20);
+  });
+
+  it('chains annotations immutably', () => {
+    const base = f.number(20);
+    const a = base.label('A');
+    const b = base.label('B');
+    expect(a.annotations.name).toBe('A');
+    expect(b.annotations.name).toBe('B');
+    expect(base.annotations.name).toBeUndefined();
+  });
+
+  it('keeps the subclass across a chain, so kind-specific methods survive', () => {
+    const n = f.number(20).label('A').range(5, 80).describe('help').step(5);
+    expect(n.kind).toBe('number');
+    expect(n.annotations).toMatchObject({ name: 'A', description: 'help', min: 5, max: 80, step: 5 });
+  });
+
+  it('keeps a custom node kind across a chain', () => {
+    const n = f.custom('vector2', { x: 0 }).label('Offset');
+    expect(n.kind).toBe('vector2');
+    expect(n.annotations.name).toBe('Offset');
+  });
+
+  it('expands a bare enum option list', () => {
+    const n = f.enum('fast', ['fast', 'accurate']);
+    expect(n.annotations.options).toEqual([
+      { value: 'fast', label: 'fast' },
+      { value: 'accurate', label: 'accurate' },
+    ]);
+  });
+
+  it('takes labeled enum options as given', () => {
+    const n = f.enum('fast', [{ value: 'fast', label: 'Fast' }]);
+    expect(n.annotations.options).toEqual([{ value: 'fast', label: 'Fast' }]);
+  });
+
+  it('f.value carries no kind', () => {
+    expect(f.value(3).kind).toBeNull();
+  });
+
+  it('holds section, showIf and render off the annotation bag', () => {
+    const n = f
+      .number(1)
+      .section('Advanced')
+      .showIf((c) => c.showGrid === true)
+      .render(() => null);
+    expect(n.options.section).toBe('Advanced');
+    expect(n.options.showIf?.({ showGrid: true })).toBe(true);
+    expect(n.options.render).toBeTypeOf('function');
+    expect(n.annotations).toEqual({});
+  });
+
+  it('schema.defaults() collects every default', () => {
+    const s = f.schema({ showGrid: f.boolean(true), cellSize: f.number(20) });
+    expect(s.defaults()).toEqual({ showGrid: true, cellSize: 20 });
+  });
+});
+
+describe('builder / node option collisions', () => {
+  // `options` is the node's extras bag AND was briefly an EnumNode method, so
+  // section/showIf/render silently vanished on every enum leaf. tsc caught it;
+  // this keeps a runtime witness.
+  it('every node kind exposes options as the extras bag, not a method', () => {
+    const nodes = [
+      f.number(1),
+      f.boolean(true),
+      f.string(''),
+      f.color('#fff'),
+      f.enum('a', ['a', 'b']),
+      f.value(1),
+      f.custom('vector2', 0),
+    ];
+    for (const node of nodes) {
+      expect(typeof node.options).toBe('object');
+      expect(node.section('S').options.section).toBe('S');
+      expect(node.render(() => null).options.render).toBeTypeOf('function');
+    }
+  });
+});