@weasel-js/labkit 1.4.4 → 1.5.1

package/dist/_dts/{index-Blv9uQzu.d.ts → index-BNdz-tNd.d.ts}

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
-import { R as ResolvedConfig, c as ControlRenderer } from './types-B9_zrHmb.js';
-import { C as ConfigField } from './types-x92Kfeme.js';
+import { ToolPrefNumberFormat } from '@weasel-js/core';
+import { R as ResolvedConfig, a as ConfigField, d as ControlRenderer } from './types-DzoNY1pO.js';
 
 /**
  * How much room a container gives its rows — gaps, padding, and field height,
@@ -100,11 +100,25 @@ interface PropertyRowProps extends PropertyMetricProps {
     span?: boolean;
     children: ReactNode;
     htmlFor?: string;
+    /** The control is a group of several (a segmented toggle), not one element.
+     *  The row then renders as a `<div>`: a `<label>` hands a click on its text to
+     *  its first control, which in a group means selecting the first option. Each
+     *  member has to carry its own name. */
+    group?: boolean;
     className?: string;
+    /** The row is auto: its value is not pinned and the owner computes it. Draws
+     *  the control ghosted and colorless. */
+    auto?: boolean;
+    /** Given, the row carries a pin dot that toggles `auto`. Omitted, the row can
+     *  show an auto state but not change it. */
+    onAutoChange?: (next: boolean) => void;
+    /** Marks the row's element for a panel-level gesture handler. `PropertyRow`
+     *  does not spread unknown props, so this is declared rather than inherited. */
+    'data-auto-path'?: string;
 }
 /** The label-plus-control frame every typed row below is built from. Use it
  *  directly for a control this module does not cover. */
-declare function PropertyRow({ label, readout, description, variant, layout, span, children, htmlFor, className, density, align, }: PropertyRowProps): react_jsx_runtime.JSX.Element;
+declare function PropertyRow({ label, readout, description, variant, layout, span, children, htmlFor, group, className, density, align, auto, onAutoChange, 'data-auto-path': autoPath, }: PropertyRowProps): react_jsx_runtime.JSX.Element;
 /** Props for `<SliderRow>`. */
 interface SliderRowProps extends PropertyMetricProps {
     label: ReactNode;
@@ -126,6 +140,14 @@ interface SliderRowProps extends PropertyMetricProps {
     onInput?: (next: number) => void;
     /** Override how the value is rendered next to the label. Defaults to `value.toString()`. */
     format?: (value: number) => ReactNode;
+    /**
+     * Static text in place of the editable readout. Use it when the row is not
+     * showing a number a caller could type back — an auto row's `auto · 18`, say,
+     * which an editable field would seed a draft with and then fail to parse.
+     */
+    readout?: ReactNode;
+    /** A named display for the value: `compact` reads `2.0M`. `format` wins when both are given. */
+    notation?: ToolPrefNumberFormat;
     /**
      * Optional suffix rendered next to the readout. A string becomes a
      * baseline-aligned dim "word" unit (e.g. "px"); pass JSX like `<sup>°</sup>`
@@ -136,10 +158,16 @@ interface SliderRowProps extends PropertyMetricProps {
     description?: string;
     /** Take the full width of the enclosing grid — see `<PropertyRow span>`. */
     span?: boolean;
+    /** The row is auto — see `<PropertyRow auto>`. */
+    auto?: boolean;
+    /** Toggles `auto` from a pin dot — see `<PropertyRow onAutoChange>`. */
+    onAutoChange?: (next: boolean) => void;
+    /** Marks the row for a panel-level gesture handler — see `<PropertyRow data-auto-path>`. */
+    'data-auto-path'?: string;
 }
 /** A bounded number edited by dragging, with a live readout whose precision
  *  follows `step`. */
-declare function SliderRow({ label, value, min, max, step, onChange, onInput, format, unit, layout, description, span, density, align, }: SliderRowProps): react_jsx_runtime.JSX.Element;
+declare function SliderRow({ label, value, min, max, step, onChange, onInput, format, readout, notation, unit, layout, description, span, density, align, auto, onAutoChange, 'data-auto-path': autoPath, }: SliderRowProps): react_jsx_runtime.JSX.Element;
 /** Props for `<ColorRow>`. */
 interface ColorRowProps extends PropertyMetricProps {
     label: ReactNode;
@@ -170,42 +198,69 @@ interface ColorRowProps extends PropertyMetricProps {
     /** Label beside the swatch (default) or above it. */
     layout?: PropertyRowLayout;
     description?: string;
+    /** Right-aligned readout shown next to the label — see `<PropertyRow readout>`. */
+    readout?: ReactNode;
     /** Take the full width of the enclosing grid — see `<PropertyRow span>`. */
     span?: boolean;
+    /** The row is auto — see `<PropertyRow auto>`. */
+    auto?: boolean;
+    /** Toggles `auto` from a pin dot — see `<PropertyRow onAutoChange>`. */
+    onAutoChange?: (next: boolean) => void;
+    /** Marks the row for a panel-level gesture handler — see `<PropertyRow data-auto-path>`. */
+    'data-auto-path'?: string;
 }
 /** A color swatch, optionally with an alpha slider beneath it. */
-declare function ColorRow({ label, value, onChange, onInput, alpha, onAlphaChange, onAlphaInput, alphaDisabled, layout, description, span, density, align, }: ColorRowProps): react_jsx_runtime.JSX.Element;
+declare function ColorRow({ label, readout, value, onChange, onInput, alpha, onAlphaChange, onAlphaInput, alphaDisabled, layout, description, span, density, align, auto, onAutoChange, 'data-auto-path': autoPath, }: ColorRowProps): react_jsx_runtime.JSX.Element;
 /** Props for `<CheckboxRow>`. */
 interface CheckboxRowProps extends PropertyMetricProps {
     label: ReactNode;
-    value: boolean;
+    /** Absent reads as unchecked. */
+    value: boolean | undefined;
     onChange: (next: boolean) => void;
     /** Label beside the box (default) or above it. */
     layout?: PropertyRowLayout;
     description?: string;
+    /** Right-aligned readout shown next to the label — see `<PropertyRow readout>`. */
+    readout?: ReactNode;
     /** Take the full width of the enclosing grid — see `<PropertyRow span>`. */
     span?: boolean;
+    /** The row is auto — see `<PropertyRow auto>`. */
+    auto?: boolean;
+    /** Toggles `auto` from a pin dot — see `<PropertyRow onAutoChange>`. */
+    onAutoChange?: (next: boolean) => void;
+    /** Marks the row for a panel-level gesture handler — see `<PropertyRow data-auto-path>`. */
+    'data-auto-path'?: string;
 }
 /** A boolean checkbox. */
-declare function CheckboxRow({ label, value, onChange, layout, span, description, density, align, }: CheckboxRowProps): react_jsx_runtime.JSX.Element;
+declare function CheckboxRow({ label, readout, value, onChange, layout, span, description, density, align, auto, onAutoChange, 'data-auto-path': autoPath, }: CheckboxRowProps): react_jsx_runtime.JSX.Element;
 /** Props for `<TextRow>`. */
 interface TextRowProps extends PropertyMetricProps {
     label: ReactNode;
-    value: string;
+    /** Absent reads as an empty field. */
+    value: string | null | undefined;
     onChange: (next: string) => void;
     placeholder?: string;
     maxLength?: number;
     layout?: PropertyRowLayout;
     description?: string;
+    /** Right-aligned readout shown next to the label — see `<PropertyRow readout>`. */
+    readout?: ReactNode;
     /** Take the full width of the enclosing grid — see `<PropertyRow span>`. */
     span?: boolean;
+    /** The row is auto — see `<PropertyRow auto>`. */
+    auto?: boolean;
+    /** Toggles `auto` from a pin dot — see `<PropertyRow onAutoChange>`. */
+    onAutoChange?: (next: boolean) => void;
+    /** Marks the row for a panel-level gesture handler — see `<PropertyRow data-auto-path>`. */
+    'data-auto-path'?: string;
 }
 /** A single-line text input. */
-declare function TextRow({ label, value, onChange, placeholder, maxLength, layout, description, span, density, align, }: TextRowProps): react_jsx_runtime.JSX.Element;
+declare function TextRow({ label, readout, value, onChange, placeholder, maxLength, layout, description, span, density, align, auto, onAutoChange, 'data-auto-path': autoPath, }: TextRowProps): react_jsx_runtime.JSX.Element;
 /** Props for `<NumberRow>`. */
 interface NumberRowProps extends PropertyMetricProps {
     label: ReactNode;
-    value: number;
+    /** Absent reads as an empty field. */
+    value: number | null | undefined;
     /**
      * The committed value. Given `onInput` as well, it fires on blur or Enter;
      * on its own it fires on every keystroke, which is what a row with one
@@ -230,12 +285,20 @@ interface NumberRowProps extends PropertyMetricProps {
     unit?: ReactNode;
     layout?: PropertyRowLayout;
     description?: string;
+    /** Right-aligned readout shown next to the label — see `<PropertyRow readout>`. */
+    readout?: ReactNode;
     /** Take the full width of the enclosing grid — see `<PropertyRow span>`. */
     span?: boolean;
+    /** The row is auto — see `<PropertyRow auto>`. */
+    auto?: boolean;
+    /** Toggles `auto` from a pin dot — see `<PropertyRow onAutoChange>`. */
+    onAutoChange?: (next: boolean) => void;
+    /** Marks the row for a panel-level gesture handler — see `<PropertyRow data-auto-path>`. */
+    'data-auto-path'?: string;
 }
 /** A number typed directly. Reach for `<SliderRow>` when the range matters
  *  more than the exact value. */
-declare function NumberRow({ label, value, onChange, onInput, min, max, step, placeholder, unit, layout, description, span, density, align, }: NumberRowProps): react_jsx_runtime.JSX.Element;
+declare function NumberRow({ label, readout, value, onChange, onInput, min, max, step, placeholder, unit, layout, description, span, density, align, auto, onAutoChange, 'data-auto-path': autoPath, }: NumberRowProps): react_jsx_runtime.JSX.Element;
 interface PropertyOption<T extends string> {
     value: T;
     label: ReactNode;
@@ -243,17 +306,28 @@ interface PropertyOption<T extends string> {
 /** Props for `<SelectRow>`. */
 interface SelectRowProps<T extends string> extends PropertyMetricProps {
     label: ReactNode;
-    value: T;
+    /** Absent, or not one of `options`, shows a placeholder rather than the first option. */
+    value: T | undefined;
     options: ReadonlyArray<PropertyOption<T>>;
     onChange: (next: T) => void;
+    /** Shown while no option is chosen. Defaults to "Choose option…". */
+    placeholder?: string;
     layout?: PropertyRowLayout;
     description?: string;
+    /** Right-aligned readout shown next to the label — see `<PropertyRow readout>`. */
+    readout?: ReactNode;
     /** Take the full width of the enclosing grid — see `<PropertyRow span>`. */
     span?: boolean;
+    /** The row is auto — see `<PropertyRow auto>`. */
+    auto?: boolean;
+    /** Toggles `auto` from a pin dot — see `<PropertyRow onAutoChange>`. */
+    onAutoChange?: (next: boolean) => void;
+    /** Marks the row for a panel-level gesture handler — see `<PropertyRow data-auto-path>`. */
+    'data-auto-path'?: string;
 }
 /** A dropdown over a fixed set of choices. Prefer `<ToggleRow>` when there
  *  are only two or three and they should all stay visible. */
-declare function SelectRow<T extends string>({ label, value, options, onChange, layout, description, span, density, align, }: SelectRowProps<T>): react_jsx_runtime.JSX.Element;
+declare function SelectRow<T extends string>({ label, readout, value, options, onChange, placeholder, layout, description, span, density, align, auto, onAutoChange, 'data-auto-path': autoPath, }: SelectRowProps<T>): react_jsx_runtime.JSX.Element;
 /** Props for `<ToggleRow>`. */
 interface ToggleRowProps<T extends string> extends PropertyMetricProps {
     label: ReactNode;
@@ -262,20 +336,28 @@ interface ToggleRowProps<T extends string> extends PropertyMetricProps {
     onChange: (next: T) => void;
     layout?: PropertyRowLayout;
     description?: string;
+    /** Right-aligned readout shown next to the label — see `<PropertyRow readout>`. */
+    readout?: ReactNode;
     /** Take the full width of the enclosing grid — see `<PropertyRow span>`. */
     span?: boolean;
+    /** The row is auto — see `<PropertyRow auto>`. */
+    auto?: boolean;
+    /** Toggles `auto` from a pin dot — see `<PropertyRow onAutoChange>`. */
+    onAutoChange?: (next: boolean) => void;
+    /** Marks the row for a panel-level gesture handler — see `<PropertyRow data-auto-path>`. */
+    'data-auto-path'?: string;
 }
 /** A segmented control: the same choice as a select, with every option
  *  visible at once. */
-declare function ToggleRow<T extends string>({ label, value, options, onChange, layout, description, span, density, align, }: ToggleRowProps<T>): react_jsx_runtime.JSX.Element;
+declare function ToggleRow<T extends string>({ label, readout, value, options, onChange, layout, description, span, density, align, auto, onAutoChange, 'data-auto-path': autoPath, }: ToggleRowProps<T>): react_jsx_runtime.JSX.Element;
 
 /** 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.
  */
 type ControlPack = 'auto' | 'pairs' | 'one-up';
 interface ControlPanelProps<TC extends Record<string, unknown>> {
@@ -322,6 +404,12 @@ interface ControlPanelProps<TC extends Record<string, unknown>> {
     /** A fold moved. The key is a section's label — prefixed by its group's
      *  dotted path when the section sits inside one — or a group's own path. */
     onCollapse?: (key: string, collapsed: boolean) => void;
+    /** Dotted paths currently unpinned. A row in this set draws ghosted and its
+     *  dot reads as auto, and the dot writes the sentinel back through
+     *  `setConfig`. Omitted, the panel keeps the set itself: the dots still work
+     *  and the sentinel never reaches `setConfig`, which would otherwise store it
+     *  as the row's value. */
+    auto?: ReadonlySet<string>;
     /** Draw leaves marked `hidden`. */
     showHidden?: boolean;
     className?: string;
@@ -329,7 +417,7 @@ interface ControlPanelProps<TC extends Record<string, unknown>> {
 /** Render an instrument's config schema as a stack of controls, each writing
  *  back through `setConfig`. Built on the property rows, so a lab's controls
  *  are the same aligned, themed rows the rest of the kit uses. */
-declare function ControlPanel<TC extends Record<string, unknown>>({ schema, fields, config, setConfig, renderers, pack, layout, density, align, collapse, collapsed, onCollapse, showHidden, className, }: ControlPanelProps<TC>): react_jsx_runtime.JSX.Element;
+declare function ControlPanel<TC extends Record<string, unknown>>({ schema, fields, config, setConfig, renderers, pack, layout, density, align, collapse, collapsed, onCollapse, auto: given, showHidden, className, }: ControlPanelProps<TC>): react_jsx_runtime.JSX.Element;
 
 export { CheckboxRow as C, NumberRow as N, SelectRow as S, TextRow as T, ColorRow as c, ControlPanel as e, PropertyList as g, PropertyPanel as j, PropertyRow as l, PropertySpan as p, SliderRow as s, ToggleRow as v };
 export type { PropertyMetricProps as P, PropertyListPack as a, CheckboxRowProps as b, ColorRowProps as d, NumberRowProps as f, PropertyListProps as h, PropertyOption as i, PropertyPanelProps as k, PropertyRowLayout as m, PropertyRowProps as n, PropertyRowVariant as o, PropertySpanProps as q, SelectRowProps as r, SliderRowProps as t, TextRowProps as u, ToggleRowProps as w };

package/dist/_dts/index-CSJoj4LC.d.ts

@@ -0,0 +1,248 @@
+import { d as ControlRenderer, c as ConfigRule } from './types-DzoNY1pO.js';
+import { K as Instrument, ar as TrialChromeContext, N as TrialContribution, T as TrialRecord, q as InstrumentList, e as SavedSnapshot, o as LabMode, ap as ToolSlotContext, a3 as ContributionBase, aq as ToolbarItem, ao as ToolItem, ai as SidebarSection, al as StatusReadout, H as TrialTool, ae as RegionContribution, aj as SidebarSlotContext } from './frac-B4okC2lX.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * 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.
+ */
+declare function builtinContributions(instrument: Instrument, ctx: TrialChromeContext, controls?: Record<string, ControlRenderer>): TrialContribution[];
+
+/** What a trial opens on beyond its instrument's own defaults. */
+interface AddTrialOptions<TC = Record<string, unknown>> {
+    /** Overlaid on `defaultConfig()` before `initialState` reads it, so a trial
+     *  opened on a subject is running that subject from its first frame. Keys
+     *  whose value is `undefined` are left to the default. */
+    config?: Partial<TC>;
+}
+/** Append a new trial running `instrumentName`, at that instrument's default
+ *  config — with `options.config` written over it — and the initial state
+ *  that config produces. */
+declare function addTrial(trials: TrialRecord[], instruments: InstrumentList, instrumentName: string, options?: AddTrialOptions): TrialRecord[];
+/** Insert a deep copy of a trial directly after it. The copy starts with
+ *  an empty undo history — the original's is not shared. */
+declare function cloneTrial(trials: TrialRecord[], id: string): TrialRecord[];
+/** Remove a trial, unless it is the last one — a lab always has at least
+ *  one. */
+declare function closeTrial(trials: TrialRecord[], id: string): TrialRecord[];
+/** Return a trial to what it opened on — its instrument's defaults under the
+ *  seed `addTrial` was given — keeping its id and its place in the list. */
+declare function resetTrial(trials: TrialRecord[], id: string, instruments: InstrumentList): TrialRecord[];
+/**
+ * Reorder to match `ids`. Ids the list doesn't mention keep their relative
+ * order at the end, and ids it names that no longer exist are dropped — a
+ * reorder that raced a close should not resurrect the closed trial.
+ */
+declare function reorderTrials(trials: TrialRecord[], ids: readonly string[]): TrialRecord[];
+
+/** Lab-wide state and commands: the available instruments, the open
+ *  trials and the operations over them, saved snapshots, and the color
+ *  mode. */
+interface LabContextValue {
+    instruments: InstrumentList;
+    trials: TrialRecord[];
+    /** Open a trial running `instrumentName`. `options.config` is written over
+     *  that instrument's defaults, which is where a trial opened on a subject
+     *  says which subject. */
+    addTrial: (instrumentName: string, options?: AddTrialOptions) => void;
+    cloneTrial: (id: string) => void;
+    closeTrial: (id: string) => void;
+    resetTrial: (id: string) => void;
+    reorderTrials: (ids: readonly string[]) => void;
+    /** Put a fresh trial running `instrumentName` in trial `id`'s place, at its
+     *  size. The replacement has a new id, and takes the focus if `id` had it. */
+    swapTrial: (id: string, instrumentName: string, options?: AddTrialOptions) => void;
+    /** The trial last pointed at or focused, counting focus that moved into a
+     *  frame inside it. A trial `addTrial` or `cloneTrial` opens takes it. Falls
+     *  back to the first trial; null only when there are none. */
+    focusedTrialId: string | null;
+    focusTrial: (id: string) => void;
+    savedSnapshots: SavedSnapshot[];
+    saveSnapshot: (trialId: string, name?: string) => void;
+    loadSnapshot: (trialId: string, snapshotId: string) => void;
+    deleteSnapshot: (snapshotId: string) => void;
+    mode: LabMode;
+    setMode: (m: LabMode) => void;
+    /** Lab-wide rules run over every instrument's config leaves, before
+     *  labkit's own inference. */
+    configRules?: readonly ConfigRule[];
+    /** Lab-wide control overrides, keyed by config path or by leaf kind. */
+    controls?: Record<string, ControlRenderer>;
+}
+/** Context carrying the surrounding lab. Prefer `useLabContext`. */
+declare const LabContext: react.Context<LabContextValue | null>;
+/** The surrounding lab. Throws outside a `<Lab>`. */
+declare function useLabContext(): LabContextValue;
+
+/**
+ * A named position in the lab's own chrome — a box the shell owns, outside any
+ * one trial. `header` and `footer` are the shell's two bars, named as
+ * `<LabShell>` names them; `palette` is the tool rail down the side of the
+ * workspace; `sidebar` is a column of sections left of the tool rail.
+ */
+type LabRegion = 'header' | 'palette' | 'sidebar' | 'aside' | 'footer';
+/**
+ * Everything a lab-level contribution can read and command: the lab's own
+ * state and operations, plus the lab's tool slot — which every trial whose
+ * instrument declares no tools of its own reflects and writes.
+ */
+interface LabChromeContext extends LabContextValue, ToolSlotContext {
+}
+/**
+ * A contribution to the lab's chrome. Shaped as `TrialContribution` is, and
+ * merged and suppressed by the same rules, but keyed to the lab's regions and
+ * rendered with the lab's context. Supplying `render` instead of `item` opts
+ * out of the region's layout.
+ *
+ * `TCtx` is what the chrome hands a handler. It defaults to `LabChromeContext`,
+ * which is what `<Lab>` renders its regions with; a consumer mounting the
+ * regions under a bare `<LabShell>` names whatever it passes as `ctx` instead.
+ */
+type LabContribution<TCtx = LabChromeContext> = (ContributionBase & {
+    region: 'header';
+    item: ToolbarItem<TCtx>;
+    render?: never;
+}) | (ContributionBase & {
+    region: 'palette';
+    item: ToolItem;
+    render?: never;
+}) | (ContributionBase & {
+    region: 'sidebar' | 'aside';
+    item: SidebarSection;
+    render?: never;
+}) | (ContributionBase & {
+    region: 'footer';
+    item: StatusReadout;
+    render?: never;
+}) | (ContributionBase & {
+    region: LabRegion;
+    item?: never;
+    render: (ctx: TCtx) => ReactNode;
+});
+
+/** The lab's chrome context: the lab itself, plus the lab's tool slot. Throws
+ *  outside a `<Lab>`. */
+declare function useLabChromeContext(): LabChromeContext;
+/** The lab's contributions for one region, in declaration order. */
+declare function contributionsIn<TCtx = LabChromeContext>(contributions: readonly LabContribution<TCtx>[], region: LabRegion): LabContribution<TCtx>[];
+/** The palette contributions a lab's `tools` stand for. Declaring a tool is
+ *  shorthand for contributing a palette item that writes the lab's tool
+ *  slot. */
+declare function toolContributions(tools: readonly TrialTool[]): LabContribution[];
+/** Everything the lab's chrome renders, from both of the ways a lab declares
+ *  it. Tools and contributions share one id namespace, so a tool colliding
+ *  with a contribution throws here rather than one of them silently losing. */
+declare function labContributions(tools: readonly TrialTool[] | undefined, chrome: readonly LabContribution[] | undefined): LabContribution[];
+/** Props shared by the lab's region mounts. Each takes the lab's whole
+ *  contribution list and lays out the part addressed to it. */
+interface LabRegionProps {
+    contributions: readonly LabContribution[];
+}
+/** The lab's action bar, in the shell header beside the title. */
+declare function LabHeaderRegion({ contributions }: LabRegionProps): react_jsx_runtime.JSX.Element;
+/** The lab's sidebar sections. Fold state is a lab-scoped persisted value, so it
+ *  survives a reload in a stored lab and lasts the session in an unstored one. */
+declare function LabSidebarRegion({ contributions }: LabRegionProps): react_jsx_runtime.JSX.Element;
+/** The lab's aside sections, on the far side of the workspace from the sidebar.
+ *  Fold state persists the way the sidebar's does. */
+declare function LabAsideRegion({ contributions }: LabRegionProps): react_jsx_runtime.JSX.Element;
+/** The lab's readouts, in the shell footer below the workspace. */
+declare function LabFooterRegion({ contributions }: LabRegionProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * 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.
+ */
+declare function mergeContributions<T extends {
+    id: string;
+}>(...bundles: readonly (readonly T[])[]): T[];
+/**
+ * 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.
+ */
+declare function suppressContributions<T extends {
+    id: string;
+}>(bundle: readonly T[], ids: readonly string[]): T[];
+
+/** Props for `<PaletteRegion>`. */
+interface PaletteRegionProps<TCtx extends ToolSlotContext = TrialChromeContext> {
+    contributions: readonly RegionContribution<NoInfer<TCtx>>[];
+    ctx: TCtx;
+    /** Which region's items to lay out. The lab's rail names the same box
+     *  `palette` too, so this only moves for a chrome that does not. */
+    region?: string;
+}
+/** A tool strip: a trial's, or the lab's. Selection lives in whichever tool
+ *  slot the context carries; this region only reflects it. */
+declare function PaletteRegion<TCtx extends ToolSlotContext = TrialChromeContext>({ contributions, ctx, region, }: PaletteRegionProps<TCtx>): react_jsx_runtime.JSX.Element | null;
+
+/** Props for `<SidebarRegion>`. */
+interface SidebarRegionProps<TCtx extends SidebarSlotContext = TrialChromeContext> {
+    contributions: readonly RegionContribution<NoInfer<TCtx>>[];
+    ctx: TCtx;
+    /** Which region's items to lay out. */
+    region?: string;
+}
+/** Lays `sidebar` contributions out as titled, collapsible sections — a
+ *  trial's, or the lab's. A section the trial has torn out is not rendered
+ *  here — `Trial` portals its body into the workspace instead. A context with
+ *  no `undockPanel` offers no tear-out. */
+declare function SidebarRegion<TCtx extends SidebarSlotContext = TrialChromeContext>({ contributions, ctx, region, }: SidebarRegionProps<TCtx>): react_jsx_runtime.JSX.Element | null;
+
+/** Props for `<StatusRegion>`. */
+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 bar's readouts out. */
+declare function StatusRegion<TCtx = TrialChromeContext>({ contributions, ctx, region, }: StatusRegionProps<TCtx>): react_jsx_runtime.JSX.Element | null;
+
+/** Which end of the title bar a `<TitleBarRegion>` lays out: `'lead'` renders
+ *  the contributions that leave `end` unset, before the title; `'actions'`
+ *  renders the ones that set it, after everything else. */
+type TitleBarPlacement = 'lead' | 'actions';
+/** Props for `<TitleBarRegion>`. */
+interface TitleBarRegionProps {
+    contributions: readonly TrialContribution[];
+    ctx: TrialChromeContext;
+    /** Defaults to `'actions'`, where the built-ins live. */
+    placement?: TitleBarPlacement;
+}
+/** Lays a trial's `titlebar` contributions out at one end of the bar. */
+declare function TitleBarRegion({ contributions, ctx, placement }: TitleBarRegionProps): react_jsx_runtime.JSX.Element | null;
+
+/** Props for `<ToolbarRegion>`. */
+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;
+}
+/** Lays a bar's contributions out, grouped by their `group`. */
+declare function ToolbarRegion<TCtx = TrialChromeContext>({ contributions, ctx, region, label, }: ToolbarRegionProps<TCtx>): react_jsx_runtime.JSX.Element | null;
+
+/** Props for `<ViewportRegion>`. */
+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.
+ */
+declare function ViewportRegion({ contributions, ctx }: ViewportRegionProps): react_jsx_runtime.JSX.Element | null;
+
+export { resetTrial as B, suppressContributions as C, toolContributions as D, useLabChromeContext as E, useLabContext as F, PaletteRegion as P, SidebarRegion as S, ViewportRegion as V, LabAsideRegion as a, LabContext as c, LabFooterRegion as e, LabHeaderRegion as f, LabSidebarRegion as i, StatusRegion as l, TitleBarRegion as n, ToolbarRegion as p, addTrial as s, builtinContributions as t, cloneTrial as u, closeTrial as v, contributionsIn as w, labContributions as x, mergeContributions as y, reorderTrials as z };
+export type { AddTrialOptions as A, LabContribution as L, TitleBarPlacement as T, LabChromeContext as b, LabContextValue as d, LabRegion as g, LabRegionProps as h, PaletteRegionProps as j, SidebarRegionProps as k, StatusRegionProps as m, TitleBarRegionProps as o, ToolbarRegionProps as q, ViewportRegionProps as r };

package/dist/_dts/{types-B9_zrHmb.d.ts → types-DzoNY1pO.d.ts}

@@ -1,5 +1,5 @@
-import { ToolPrefLeaf, ToolPrefGroup } from '@weasel-js/core';
-import { P as PrefRenderer } from './PrefsForm.d-DDHFANkc.js';
+import { ToolPrefNumberFormat, ToolPrefNumberUnit, ToolPrefLeaf, ToolPrefGroup } from '@weasel-js/core';
+import { P as PrefRenderer } from './PrefsForm.d-DPy9I8It.js';
 
 /**
  * Renders the control cell for one config leaf. Identical to weasel-ui's
@@ -24,6 +24,13 @@ interface Annotations {
     max?: number;
     step?: number;
     suffix?: string;
+    /** How a number's value is shown. `compact` abbreviates from a thousand up. */
+    format?: ToolPrefNumberFormat;
+    /** Display-unit conversion for a number stored in a canonical unit — the
+     *  value, its bounds and its step all convert at the control's edge. */
+    unit?: ToolPrefNumberUnit;
+    /** A color leaf's value carries alpha (`#rrggbbaa`) and its row edits it. */
+    alpha?: boolean;
     control?: string;
     options?: readonly ConfigOption[];
     placeholder?: string;
@@ -71,6 +78,10 @@ interface SectionSpec {
      *  whether or not it was given a panel-wide `collapse`; a fold the reader
      *  has since toggled outranks it. */
     collapsed?: boolean;
+    /** Where the section's rows put their labels, over the panel's `layout`. */
+    layout?: 'block' | 'inline';
+    /** How the section packs its rows, over the panel's `pack`. */
+    pack?: 'auto' | 'pairs' | 'one-up';
 }
 /** A schema resolved against a set of rules: the vocabulary weasel-ui renders,
  *  plus the three things labkit keeps on the side because `PrefLeaf` has no
@@ -90,11 +101,26 @@ interface ResolvedConfig {
 interface SectionOption {
     label: string;
     collapsed?: boolean;
+    /** Where the section's rows put their labels, over the panel's `layout`. */
+    layout?: 'block' | 'inline';
+    /** How the section packs its rows, over the panel's `pack`. */
+    pack?: 'auto' | 'pairs' | 'one-up';
 }
 /** Per-node extras that do not belong on a `PrefLeaf`. */
 interface NodeOptions extends BranchOptions {
     render?: ControlRenderer;
-    validate?: (leaf: ToolPrefLeaf) => string[];
+    /** Errors for this leaf under `config`, the instrument's whole config. */
+    validate?: (leaf: ToolPrefLeaf, config: Record<string, unknown>) => string[];
+    /** Computes this leaf's value while it is auto. Attaching one is what lets
+     *  the ghosted control draw a real value and keeps the instrument off
+     *  `?? compute()`. */
+    autoResolve?: (config: Record<string, unknown>) => unknown;
+    /** The leaf starts auto rather than pinned at its default. Set by
+     *  `.initial(auto)`. */
+    unpinned?: boolean;
+    /** The leaf can never be auto: the row takes no pin dot and ignores the
+     *  gesture. For a value the instrument cannot receive as `undefined`. */
+    manual?: boolean;
 }
 /** What a branch can say about itself, beyond its children. */
 interface BranchOptions {
@@ -163,4 +189,65 @@ interface ConfigSchema<TC> {
 /** The config type behind a schema: `ConfigOf<typeof sceneConfig>`. */
 type ConfigOf<S> = S extends ConfigSchema<infer TC> ? TC : never;
 
-export type { Annotations as A, BranchAnnotations as B, ConfigPath as C, EntryValue as E, InferConfig as I, LeafPatch as L, NodeOptions as N, ResolvedConfig as R, SectionSpec as S, ValueAtPath as V, ConfigSchema as a, ConfigNode as b, ControlRenderer as c, ConfigOption as d, ConfigShape as e, ConfigBranch as f, BranchOptions as g, ConfigEntry as h, ConfigRule as i, ConfigRuleContext as j, ConfigOf as k, NodeValue as l };
+/** Which control a config field is edited with. */
+type ConfigFieldType = 'slider' | 'checkbox' | 'select' | 'number' | 'text' | 'color';
+/** What every config field carries: the config key it writes, the label shown
+ *  beside it, and which control renders it. */
+interface ConfigFieldBase {
+    key: string;
+    label: string;
+    type: ConfigFieldType;
+}
+/** A bounded number edited by dragging. */
+interface SliderField extends ConfigFieldBase {
+    type: 'slider';
+    default: number;
+    min: number;
+    max: number;
+    step?: number;
+}
+/** A boolean. */
+interface CheckboxField extends ConfigFieldBase {
+    type: 'checkbox';
+    default: boolean;
+}
+/** One choice in a select field. */
+interface SelectOption {
+    value: string;
+    label: string;
+}
+/** A fixed set of labeled choices. */
+interface SelectField extends ConfigFieldBase {
+    type: 'select';
+    default: string;
+    options: SelectOption[];
+}
+/** A number typed directly, optionally bounded. Use a slider field instead
+ *  when the range matters more than the exact value. */
+interface NumberField extends ConfigFieldBase {
+    type: 'number';
+    default: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/** A free-text string. Writes are debounced so typing does not re-run the
+ *  instrument on every keystroke. */
+interface TextField extends ConfigFieldBase {
+    type: 'text';
+    default: string;
+    placeholder?: string;
+    maxLength?: number;
+    /** Milliseconds to debounce live setConfig calls. Default 150 ms. Set to 0 to disable. */
+    debounceMs?: number;
+}
+/** A color, as a CSS color string. */
+interface ColorField extends ConfigFieldBase {
+    type: 'color';
+    default: string;
+}
+/** One field of an instrument's config schema. The schema is what the control
+ *  panel renders, and what `validateConfigSchema` checks. */
+type ConfigField = SliderField | CheckboxField | SelectField | NumberField | TextField | ColorField;
+
+export type { Annotations as A, BranchAnnotations as B, ConfigPath as C, EntryValue as E, InferConfig as I, LeafPatch as L, NodeOptions as N, ResolvedConfig as R, SectionSpec as S, TextField as T, ValueAtPath as V, ConfigField as a, ConfigSchema as b, ConfigRule as c, ControlRenderer as d, BranchOptions as e, CheckboxField as f, ColorField as g, ConfigBranch as h, ConfigEntry as i, ConfigFieldBase as j, ConfigFieldType as k, ConfigNode as l, ConfigOf as m, ConfigOption as n, ConfigRuleContext as o, ConfigShape as p, NodeValue as q, NumberField as r, SelectField as s, SelectOption as t, SliderField as u, SectionOption as v };