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

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

package/src/config/builder.ts

@@ -0,0 +1,224 @@
+import type { PrefLeaf } from '@weasel-js/ui';
+import type {
+  Annotations,
+  ConfigNode,
+  ConfigOption,
+  ConfigSchema,
+  ControlRenderer,
+  InferConfig,
+  NodeOptions,
+} from './types';
+
+/** Shared chaining surface. Every method clones, so a node can be reused as a
+ *  base for several leaves without one bleeding into the next. */
+abstract class BaseNode<T> implements ConfigNode<T> {
+  abstract readonly kind: string | null;
+
+  // `default` is a reserved word in a parameter position, so the field is
+  // declared rather than taken as a parameter property.
+  readonly default: T;
+
+  constructor(
+    defaultValue: T,
+    readonly annotations: Readonly<Annotations> = {},
+    readonly options: Readonly<NodeOptions> = {},
+  ) {
+    this.default = defaultValue;
+  }
+
+  /** Clone into the same subclass. Subclasses with extra constructor
+   *  arguments override this. */
+  protected with(annotations: Annotations, options: NodeOptions): this {
+    const Ctor = this.constructor as new (
+      d: T,
+      a: Annotations,
+      o: NodeOptions,
+    ) => this;
+    return new Ctor(this.default, annotations, options);
+  }
+
+  protected ann(patch: Annotations): this {
+    return this.with({ ...this.annotations, ...patch }, this.options);
+  }
+
+  protected opt(patch: NodeOptions): this {
+    return this.with(this.annotations, { ...this.options, ...patch });
+  }
+
+  /** Human-readable label. Defaults to the key, title-cased. */
+  label(name: string): this {
+    return this.ann({ name });
+  }
+
+  /** Longer help text, surfaced as a tooltip on the row label. */
+  describe(description: string): this {
+    return this.ann({ description });
+  }
+
+  /** Omit from the panel unless it is asked to show hidden leaves. */
+  hidden(): this {
+    return this.ann({ hidden: true });
+  }
+
+  /** Pair with a sibling sharing this id, side-by-side on one row. */
+  pair(pair: string): this {
+    return this.ann({ pair });
+  }
+
+  /** Render under a named section heading. */
+  section(section: string): this {
+    return this.opt({ section });
+  }
+
+  /** Show this row only while the predicate holds. Presentational — the value
+   *  stays in config and the instrument still reads it. */
+  showIf(predicate: (config: Record<string, unknown>) => boolean): this {
+    return this.opt({ showIf: predicate });
+  }
+
+  /** Draw this one row yourself, keeping the kind, default and validation. */
+  render(renderer: ControlRenderer): this {
+    return this.opt({ render: renderer });
+  }
+}
+
+class NumberNode extends BaseNode<number> {
+  readonly kind = 'number';
+
+  /** Bound the value. A number with both bounds renders as a slider. */
+  range(min: number, max: number): this {
+    return this.ann({ min, max });
+  }
+
+  step(step: number): this {
+    return this.ann({ step });
+  }
+
+  /** Force a slider even without both bounds. */
+  slider(): this {
+    return this.ann({ control: 'slider' });
+  }
+
+  /** Force a typed input even when both bounds are set. */
+  input(): this {
+    return this.ann({ control: 'input' });
+  }
+}
+
+class BooleanNode extends BaseNode<boolean> {
+  readonly kind = 'boolean';
+
+  /** Ask for a switch. `ControlPanel` still draws a checkbox; weasel-ui's
+   *  `PrefsForm` honors the distinction. */
+  toggle(): this {
+    return this.ann({ control: 'switch' });
+  }
+}
+
+class StringNode extends BaseNode<string> {
+  readonly kind = 'string';
+
+  placeholder(placeholder: string): this {
+    return this.ann({ placeholder });
+  }
+
+  maxLength(maxLength: number): this {
+    return this.ann({ maxLength });
+  }
+
+  /** Milliseconds to debounce live writes. 0 commits every keystroke. */
+  debounce(debounceMs: number): this {
+    return this.ann({ debounceMs });
+  }
+}
+
+class ColorNode extends BaseNode<string> {
+  readonly kind = 'color';
+}
+
+class EnumNode<T extends string> extends BaseNode<T> {
+  readonly kind = 'enum';
+
+  /** Render as a segmented control rather than a select. */
+  radio(): this {
+    return this.ann({ control: 'radio' });
+  }
+
+  /** Relabel the choices. Named `labels` rather than `options` because
+   *  `options` is the node's own extras bag. */
+  labels(options: readonly ConfigOption[]): this {
+    return this.ann({ options });
+  }
+}
+
+/** A leaf whose kind the rule chain decides. */
+class ValueNode<T> extends BaseNode<T> {
+  readonly kind = null;
+}
+
+/** A leaf of a kind labkit does not ship a row for. */
+class CustomNode<T> extends BaseNode<T> {
+  constructor(
+    readonly kind: string,
+    defaultValue: T,
+    annotations: Readonly<Annotations> = {},
+    options: Readonly<NodeOptions> = {},
+  ) {
+    super(defaultValue, annotations, options);
+  }
+
+  protected override with(annotations: Annotations, options: NodeOptions): this {
+    return new CustomNode(this.kind, this.default, annotations, options) as this;
+  }
+}
+
+const expand = <T extends string>(
+  options: readonly T[] | readonly ConfigOption[],
+): readonly ConfigOption[] =>
+  options.map((o) => (typeof o === 'string' ? { value: o, label: o } : o));
+
+/**
+ * Builds an instrument's config: the values, their types, and how each is
+ * edited, in one declaration.
+ *
+ * ```ts
+ * const config = f.schema({
+ *   showGrid: f.boolean(true),
+ *   cellSize: f.number(20).range(5, 80).step(5).label('Grid spacing'),
+ * })
+ * ```
+ */
+export const f = {
+  number: (def: number): NumberNode => new NumberNode(def),
+  boolean: (def: boolean): BooleanNode => new BooleanNode(def),
+  string: (def: string): StringNode => new StringNode(def),
+  color: (def: string): ColorNode => new ColorNode(def),
+
+  /** A fixed set of choices. The default's literal type flows into the config
+   *  type, so `f.enum('fast', ['fast', 'accurate'])` gives
+   *  `'fast' | 'accurate'` with no `as const`. */
+  enum: <const T extends string>(
+    def: T,
+    options: readonly T[] | readonly ConfigOption[],
+  ): EnumNode<T> => new EnumNode<T>(def, { options: expand(options) }),
+
+  /** A leaf with no declared kind: the rule chain decides, which is how a lab
+   *  states a convention like "every `*Color` key is a color picker". */
+  value: <T>(def: T): ValueNode<T> => new ValueNode(def),
+
+  /** A leaf of a kind a lab supplies the control for, through `controls`. */
+  custom: <T>(kind: string, def: T, validate?: (leaf: PrefLeaf) => string[]): CustomNode<T> =>
+    new CustomNode(kind, def, {}, validate ? { validate } : {}),
+
+  /** Collect leaves into an instrument's config. */
+  schema<S extends Record<string, ConfigNode>>(nodes: S): ConfigSchema<InferConfig<S>> {
+    return {
+      nodes,
+      defaults: () => {
+        const out: Record<string, unknown> = {};
+        for (const [key, node] of Object.entries(nodes)) out[key] = node.default;
+        return out as InferConfig<S>;
+      },
+    };
+  },
+};