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

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

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