@weasel-js/labkit 1.4.3 → 1.5.0

package/src/chrome/regions/StatusRegion.tsx

@@ -1,14 +1,20 @@
 import { StatusBar } from '../../primitives/StatusBar';
-import type { TrialChromeContext, TrialContribution } from '../types';
+import type { RegionContribution, StatusReadout, TrialChromeContext } from '../types';
 
 /** Props for `<StatusRegion>`. */
-export interface StatusRegionProps {
-  contributions: readonly TrialContribution[];
-  ctx: TrialChromeContext;
+export interface StatusRegionProps<TCtx = TrialChromeContext> {
+  contributions: readonly RegionContribution<NoInfer<TCtx>>[];
+  ctx: TCtx;
+  /** Which region's readouts to lay out; the lab's footer is `footer`. */
+  region?: string;
 }
 
-/** Lays a trial's `status` contributions out as readouts. */
-export function StatusRegion({ contributions, ctx }: StatusRegionProps) {
+/** Lays a bar's readouts out. */
+export function StatusRegion<TCtx = TrialChromeContext>({
+  contributions,
+  ctx,
+  region = 'status',
+}: StatusRegionProps<TCtx>) {
   if (contributions.length === 0) return null;
   return (
     <StatusBar>
@@ -19,10 +25,11 @@ export function StatusRegion({ contributions, ctx }: StatusRegionProps) {
               {c.render(ctx)}
             </StatusBar.Section>
           );
-        if (c.region !== 'status' || !c.item) return null;
+        if (c.region !== region || !c.item) return null;
+        const item = c.item as StatusReadout;
         return (
           <StatusBar.Section key={c.id} end={c.end}>
-            <span title={c.item.title}>{c.item.text}</span>
+            <span title={item.title}>{item.text}</span>
           </StatusBar.Section>
         );
       })}

package/src/chrome/regions/ToolbarRegion.tsx

@@ -1,24 +1,28 @@
 import type { ReactNode } from 'react';
 import { Toolbar } from '../../primitives/Toolbar';
-import type { TrialChromeContext, TrialContribution } from '../types';
+import type { RegionContribution, ToolbarItem, TrialChromeContext } from '../types';
 
 /** Props for `<ToolbarRegion>`. */
-export interface ToolbarRegionProps {
-  contributions: readonly TrialContribution[];
-  ctx: TrialChromeContext;
+export interface ToolbarRegionProps<TCtx = TrialChromeContext> {
+  contributions: readonly RegionContribution<NoInfer<TCtx>>[];
+  ctx: TCtx;
+  /** Which region's items to lay out; the lab's action bar is `header`. */
+  region?: string;
+  /** The bar's accessible name. */
+  label?: string;
 }
 
-interface Group {
+interface Group<TCtx> {
   key: string;
   end: boolean;
-  entries: TrialContribution[];
+  entries: RegionContribution<TCtx>[];
 }
 
 /** 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>();
+function groupsOf<TCtx>(contributions: readonly RegionContribution<TCtx>[]): Group<TCtx>[] {
+  const groups: Group<TCtx>[] = [];
+  const byKey = new Map<string, Group<TCtx>>();
   for (const c of contributions) {
     if (c.group == null) {
       groups.push({ key: c.id, end: c.end ?? false, entries: [c] });
@@ -35,10 +39,15 @@ function groupsOf(contributions: readonly TrialContribution[]): Group[] {
   return groups;
 }
 
-function renderEntry(c: TrialContribution, ctx: TrialChromeContext): ReactNode {
+function renderEntry<TCtx>(
+  c: RegionContribution<TCtx>,
+  ctx: TCtx,
+  region: string,
+): 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, pressed, onActivate } = c.item;
+  if (c.region !== region || !c.item) return null;
+  const { icon: Icon, label, shortcut, disabled, danger, showLabel, pressed, onActivate } =
+    c.item as ToolbarItem<TCtx>;
   return (
     <Toolbar.Button
       key={c.id}
@@ -56,15 +65,20 @@ function renderEntry(c: TrialContribution, ctx: TrialChromeContext): ReactNode {
   );
 }
 
-/** Lays a trial's `toolbar` contributions out, grouped by their `group`. */
-export function ToolbarRegion({ contributions, ctx }: ToolbarRegionProps) {
+/** Lays a bar's contributions out, grouped by their `group`. */
+export function ToolbarRegion<TCtx = TrialChromeContext>({
+  contributions,
+  ctx,
+  region = 'toolbar',
+  label = 'Trial actions',
+}: ToolbarRegionProps<TCtx>) {
   if (contributions.length === 0) return null;
   const groups = groupsOf(contributions);
   return (
-    <Toolbar aria-label="Trial actions">
+    <Toolbar aria-label={label}>
       {groups.map((g) => (
         <Toolbar.Group key={g.key} end={g.end} aria-label={g.key}>
-          {g.entries.map((c) => renderEntry(c, ctx))}
+          {g.entries.map((c) => renderEntry(c, ctx, region))}
         </Toolbar.Group>
       ))}
     </Toolbar>

package/src/chrome/types.ts

@@ -4,14 +4,15 @@ 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. */
+ *  the instrument. The lab's own boxes are named in `LabRegion`. */
 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 {
+/** A button in a toolbar. `TCtx` is the chrome context its `onActivate` is
+ *  handed — a trial's, or the lab's for a lab-level bar. */
+export interface ToolbarItem<TCtx = TrialChromeContext> {
   icon: IconComponent;
   label: string;
   /** Shown in the tooltip. Not bound here — the trial owns its keymap. */
@@ -24,10 +25,10 @@ export interface ToolbarItem {
   pressed?: boolean;
   /** Render the label beside the glyph rather than only in the tooltip. */
   showLabel?: boolean;
-  /** Handed the trial's chrome context, so a contribution declared from the
-   *  lab can reach `ctx.saveSnapshot()` and the rest without the `render`
-   *  escape. A zero-argument handler stays valid. */
-  onActivate: (ctx: TrialChromeContext) => void;
+  /** Handed the chrome context it was declared against, so a contribution can
+   *  reach `ctx.saveSnapshot()` and the rest without the `render` escape. A
+   *  zero-argument handler stays valid. */
+  onActivate: (ctx: TCtx) => void;
 }
 
 /** A selectable tool in the palette region. */
@@ -52,12 +53,12 @@ export interface SidebarSection {
 }
 
 /** A control acting on the view of the trial, not on the trial. */
-export interface ViewportControl {
+export interface ViewportControl<TCtx = TrialChromeContext> {
   icon: IconComponent;
   label: string;
   disabled?: boolean;
   /** Handed the trial's chrome context, as `ToolbarItem.onActivate` is. */
-  onActivate: (ctx: TrialChromeContext) => void;
+  onActivate: (ctx: TCtx) => void;
 }
 
 /** A readout in the status bar. */
@@ -68,8 +69,8 @@ export interface StatusReadout {
   title?: string;
 }
 
-/** What every contribution shares. */
-interface ContributionBase {
+/** What every contribution shares, whichever chrome it is declared against. */
+export 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. */
@@ -96,18 +97,49 @@ export type TrialContribution =
       render: (ctx: TrialChromeContext) => ReactNode;
     });
 
+/**
+ * A tool slot a region can reflect and write. Both chrome contexts carry one:
+ * a trial's resolves to the lab's when its instrument declares no tools.
+ */
+export interface ToolSlotContext {
+  activeToolId: string | null;
+  setActiveTool: (id: string) => void;
+}
+
+/** What a sidebar region reflects and writes: which sections are folded, and —
+ *  where the chrome can tear a section out — where it goes. A trial supplies
+ *  all four; a lab supplies the fold state only. */
+export interface SidebarSlotContext {
+  collapsedSections: Readonly<Record<string, boolean>>;
+  setSectionCollapsed: (key: string, collapsed: boolean) => void;
+  undockedPanels?: readonly string[];
+  undockPanel?: (sectionId: string, as?: 'tile' | 'floating') => void;
+}
+
+/**
+ * A contribution as a region renderer sees it. A renderer checks the region
+ * name against its own and narrows `item` itself, which is what lets one
+ * renderer serve both chromes — the trial's and the lab's — without knowing
+ * which context it was handed.
+ */
+export interface RegionContribution<TCtx> extends ContributionBase {
+  region: string;
+  item?: unknown;
+  render?: (ctx: TCtx) => 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 {
+export interface TrialChromeContext extends ToolSlotContext, SidebarSlotContext {
   trialId: string;
   instrumentName: string;
-  /** What the title bar reads, which is the instrument's name until something
-   *  calls `setTitle`. */
+  /** What the title bar reads, which is the instrument's title (or, lacking
+   *  one, its name) until something calls `setTitle`. */
   title: string;
-  /** Retitle this trial; `null` restores the instrument name. Persisted with
+  /** Retitle this trial; `null` restores the instrument's title. Persisted with
    *  the trial, so a title survives a reload. */
   setTitle: (title: string | null) => void;
   isLastTrial: boolean;
@@ -157,9 +189,4 @@ export interface TrialChromeContext {
   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

@@ -35,6 +35,10 @@ describe('builder', () => {
     expect(n.annotations.suffix).toBe('px');
   });
 
+  it('annotates a number with a display format', () => {
+    expect(f.number(0).format('compact').annotations.format).toBe('compact');
+  });
+
   it('keeps a custom node kind across a chain', () => {
     const n = f.custom('vector2', { x: 0 }).label('Offset');
     expect(n.kind).toBe('vector2');

package/src/config/builder.ts

@@ -1,4 +1,4 @@
-import type { PrefLeaf } from '@weasel-js/ui';
+import type { PrefLeaf, PrefNumberFormat } from '@weasel-js/ui';
 import type {
   Annotations,
   BranchAnnotations,
@@ -21,7 +21,7 @@ export function isConfigBranch(entry: ConfigEntry): entry is ConfigBranch {
 
 /** 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> {
+export 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
@@ -89,7 +89,7 @@ abstract class BaseNode<T> implements ConfigNode<T> {
   }
 }
 
-class NumberNode extends BaseNode<number> {
+export class NumberNode extends BaseNode<number> {
   readonly kind = 'number';
 
   /** Bound the value. A number with both bounds renders as a slider. */
@@ -107,6 +107,12 @@ class NumberNode extends BaseNode<number> {
     return this.ann({ suffix });
   }
 
+  /** Show the value in a named format — `'compact'` reads `2.0M`. Presentation
+   *  only: the stored value stays a plain number, and a typed `2.5m` reads back. */
+  format(format: PrefNumberFormat): this {
+    return this.ann({ format });
+  }
+
   /** Force a slider even without both bounds. */
   slider(): this {
     return this.ann({ control: 'slider' });
@@ -118,7 +124,7 @@ class NumberNode extends BaseNode<number> {
   }
 }
 
-class BooleanNode extends BaseNode<boolean> {
+export class BooleanNode extends BaseNode<boolean> {
   readonly kind = 'boolean';
 
   /** Ask for a switch. `ControlPanel` still draws a checkbox; weasel-ui's
@@ -128,7 +134,7 @@ class BooleanNode extends BaseNode<boolean> {
   }
 }
 
-class StringNode extends BaseNode<string> {
+export class StringNode extends BaseNode<string> {
   readonly kind = 'string';
 
   placeholder(placeholder: string): this {
@@ -145,11 +151,11 @@ class StringNode extends BaseNode<string> {
   }
 }
 
-class ColorNode extends BaseNode<string> {
+export class ColorNode extends BaseNode<string> {
   readonly kind = 'color';
 }
 
-class EnumNode<T extends string> extends BaseNode<T> {
+export class EnumNode<T extends string> extends BaseNode<T> {
   readonly kind = 'enum';
 
   /** Render as a segmented control rather than a select. */
@@ -165,12 +171,12 @@ class EnumNode<T extends string> extends BaseNode<T> {
 }
 
 /** A leaf whose kind the rule chain decides. */
-class ValueNode<T> extends BaseNode<T> {
+export 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> {
+export class CustomNode<T> extends BaseNode<T> {
   constructor(
     readonly kind: string,
     defaultValue: T,
@@ -190,7 +196,7 @@ class CustomNode<T> extends BaseNode<T> {
  * one is read and written at a dotted path. Distinct from `.section()`, which
  * puts a heading over sibling leaves and leaves their paths alone.
  */
-class GroupNode<S extends ConfigShape> implements ConfigBranch<S> {
+export class GroupNode<S extends ConfigShape> implements ConfigBranch<S> {
   constructor(
     readonly children: S,
     readonly annotations: Readonly<BranchAnnotations> = {},

package/src/config/declarationEmit.fixture.ts

@@ -0,0 +1,11 @@
+import { f } from './builder';
+
+export const flat = f.schema({ n: f.number(1).range(0, 4), s: f.string('x').label('S') });
+
+export const grouped = f.schema({
+  g: f.group({ on: f.boolean(true).toggle(), e: f.enum('a', ['a', 'b']).radio() }).label('G'),
+});
+
+export const node = f.number(1).slider();
+
+export const group = f.group({ c: f.color('#fff'), v: f.value(1), k: f.custom('k', 'x') });

package/src/config/declarationEmit.test.ts

@@ -0,0 +1,51 @@
+import { resolve } from 'node:path';
+import ts from 'typescript';
+import { describe, expect, it } from 'vitest';
+
+const root = resolve(__dirname, '../../../..');
+const fixture = resolve(__dirname, 'declarationEmit.fixture.ts');
+
+/** Emits declarations for one file under the root tsconfig and returns every diagnostic, formatted. */
+function declarationDiagnostics(file: string): string[] {
+  const parsed = ts.getParsedCommandLineOfConfigFile(
+    resolve(root, 'tsconfig.json'),
+    {},
+    {
+      ...ts.sys,
+      onUnRecoverableConfigFileDiagnostic: (d) => {
+        throw new Error(ts.flattenDiagnosticMessageText(d.messageText, '\n'));
+      },
+    },
+  );
+  if (!parsed) throw new Error('could not read the root tsconfig');
+  const options: ts.CompilerOptions = {
+    ...parsed.options,
+    noEmit: false,
+    declaration: true,
+    emitDeclarationOnly: true,
+    declarationMap: false,
+    sourceMap: false,
+    incremental: false,
+    tsBuildInfoFile: undefined,
+    types: [],
+  };
+  const program = ts.createProgram({ rootNames: [file], options });
+  const source = program.getSourceFile(file);
+  if (!source) throw new Error(`${file} is not in the program`);
+  const emitted = program.emit(source, () => {}, undefined, true);
+  const diagnostics = [
+    ...program.getSyntacticDiagnostics(source),
+    ...program.getSemanticDiagnostics(source),
+    ...emitted.diagnostics,
+  ];
+  return diagnostics.map((d) => {
+    const text = ts.flattenDiagnosticMessageText(d.messageText, '\n');
+    return d.file ? `${d.file.fileName}: TS${d.code} ${text}` : `TS${d.code} ${text}`;
+  });
+}
+
+describe('config schema declarations', () => {
+  it('emit for exported schemas, groups and nodes', () => {
+    expect(declarationDiagnostics(fixture)).toEqual([]);
+  }, 60_000);
+});

package/src/config/entry.test.ts

@@ -0,0 +1,46 @@
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const IMPORT =
+  /^\s*(?:import|export)\s+(?!type\b)[^'"]*from\s+['"]([^'"]+)['"]|^\s*import\s+['"]([^'"]+)['"]|import\(\s*['"]([^'"]+)['"]\s*\)/gm;
+
+const isFile = (path: string) => statSync(path, { throwIfNoEntry: false })?.isFile() ?? false;
+
+function walk(file: string, seen = new Set<string>()): Set<string> {
+  if (seen.has(file)) return seen;
+  seen.add(file);
+  const source = readFileSync(file, 'utf8');
+  for (const match of source.matchAll(IMPORT)) {
+    const spec = match[1] ?? match[2] ?? match[3];
+    if (!spec?.startsWith('.')) continue;
+    const base = resolve(dirname(file), spec.replace(/\.js$/, ''));
+    const candidates = [
+      resolve(dirname(file), spec),
+      `${base}.ts`,
+      `${base}.tsx`,
+      resolve(base, 'index.ts'),
+      resolve(base, 'index.tsx'),
+    ];
+    const hit = candidates.find(isFile);
+    // An import the walk cannot follow would let a stylesheet behind it pass unseen.
+    if (!hit) throw new Error(`${file}: cannot resolve ${spec}`);
+    walk(hit, seen);
+  }
+  return seen;
+}
+
+describe('@weasel-js/labkit/config', () => {
+  it('reaches no stylesheet', () => {
+    const files = [...walk(resolve(__dirname, 'index.ts'))];
+    expect(files.filter((f) => /\.(less|css)$/.test(f))).toEqual([]);
+  });
+
+  it('is published as an entry', async () => {
+    const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf8'));
+    expect(pkg.exports['./config']).toEqual({
+      types: './dist/config/index.d.ts',
+      import: './dist/config/index.js',
+    });
+  });
+});

package/src/config/index.ts

@@ -1,4 +1,16 @@
-export { f, isConfigBranch } from './builder';
+export {
+  BaseNode,
+  BooleanNode,
+  ColorNode,
+  CustomNode,
+  EnumNode,
+  f,
+  GroupNode,
+  isConfigBranch,
+  NumberNode,
+  StringNode,
+  ValueNode,
+} from './builder';
 export { fromConfigFields } from './fromConfigField';
 export {
   fillConfigDefaults,

package/src/config/nodeClasses.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { f, GroupNode, NumberNode } from './index';
+
+describe('config node classes', () => {
+  it('are exported as values', () => {
+    expect(typeof NumberNode).toBe('function');
+    expect(typeof GroupNode).toBe('function');
+    expect(f.number(1)).toBeInstanceOf(NumberNode);
+    expect(f.group({ n: f.number(1) })).toBeInstanceOf(GroupNode);
+  });
+
+  it('can be extended', () => {
+    class Mine extends NumberNode {}
+    const node = new Mine(2);
+    expect(node).toBeInstanceOf(NumberNode);
+    expect(node.default).toBe(2);
+  });
+});

package/src/config/types.ts

@@ -1,4 +1,4 @@
-import type { PrefGroup, PrefLeaf, PrefRenderer } from '@weasel-js/ui';
+import type { PrefGroup, PrefLeaf, PrefNumberFormat, PrefRenderer } from '@weasel-js/ui';
 
 /**
  * Renders the control cell for one config leaf. Identical to weasel-ui's
@@ -25,6 +25,8 @@ export interface Annotations {
   max?: number;
   step?: number;
   suffix?: string;
+  /** How a number's value is shown. `compact` abbreviates from a thousand up. */
+  format?: PrefNumberFormat;
   control?: string;
   options?: readonly ConfigOption[];
   placeholder?: string;

package/src/controls/ControlPanel.test.tsx

@@ -444,6 +444,22 @@ describe('<ControlPanel> suffix', () => {
   });
 });
 
+describe('<ControlPanel> format', () => {
+  it('shows a slider readout in the format the leaf declares', () => {
+    render(
+      <ControlPanel
+        schema={resolveConfigSchema(
+          f.schema({ glyphs: f.number(0).range(0, 2_000_000).format('compact') }),
+          [],
+        )}
+        config={{ glyphs: 2_000_000 }}
+        setConfig={vi.fn()}
+      />,
+    );
+    expect(screen.getByDisplayValue('2.0M')).toBeInTheDocument();
+  });
+});
+
 describe('<ControlPanel> collapsible sections', () => {
   const schema = resolveConfigSchema(
     f.schema({ showGrid: f.boolean(true), seed: f.number(0).section('Advanced') }),

package/src/controls/ControlPanel.tsx

@@ -6,6 +6,7 @@ import {
   NumberRow,
   type PrefGroup,
   type PrefLeaf,
+  type PrefNumberFormat,
   type PropertyAlign,
   type PropertyDensity,
   PropertyGroup,
@@ -26,12 +27,12 @@ import { isLeafVisible } from '../config/visible';
 import type { ConfigField } from './types';
 
 /** How a panel packs its rows into the two-column property grid.
- *   - `'auto'`: narrow controls (numbers, checkboxes, dropdowns, colours) sit
+ *   - `'auto'`: narrow controls (numbers, checkboxes, dropdowns, colors) sit
  *     two per row; the ones that need the width — text, sliders, segmented
  *     toggles — span it.
  *   - `'pairs'`: every row pairs. A control that needs the full width says so
  *     itself, with `<PropertyRow span>`.
- *   - `'one-up'`: one control per row, colours excepted.
+ *   - `'one-up'`: one control per row, colors excepted.
  */
 export type ControlPack = 'auto' | 'pairs' | 'one-up';
 
@@ -247,6 +248,7 @@ function ControlRow<TC extends Record<string, unknown>>({
       const max = extra<number>(leaf, 'max');
       const step = extra<number>(leaf, 'step');
       const suffix = extra<string>(leaf, 'suffix');
+      const notation = extra<PrefNumberFormat>(leaf, 'format');
       if (extra<string>(leaf, 'control') === 'slider' && min !== undefined && max !== undefined) {
         return (
           <SliderRow
@@ -255,6 +257,7 @@ function ControlRow<TC extends Record<string, unknown>>({
             min={min}
             max={max}
             step={step}
+            notation={notation}
             unit={suffix}
             onChange={write}
             layout={layout}

package/src/fake-indexeddb-auto.d.ts

@@ -0,0 +1,5 @@
+// fake-indexeddb's `./auto` export declares no `types` condition, so under
+// `moduleResolution: Bundler` tsc finds no declaration for it — the ambient one
+// the package ships at its root is never part of the compilation. The subpath
+// is side-effect-only, so a bare declaration is the whole of it.
+declare module 'fake-indexeddb/auto';

package/src/index.test.ts

@@ -51,6 +51,13 @@ describe('public export surface', () => {
   });
 });
 
+describe('ui re-exports', () => {
+  it('carries ToggleBar and Button from the package root', () => {
+    expect(labkit).toHaveProperty('ToggleBar');
+    expect(labkit).toHaveProperty('Button');
+  });
+});
+
 describe('surface, job and orbit entry points', () => {
   it('are reachable from the package root', async () => {
     const kit = await import('./index');