@weasel-js/labkit 1.4.4 → 1.5.1

package/dist/config/index.d.ts

@@ -0,0 +1,276 @@
+import { $ as Auto, K as Instrument } from '../_dts/frac-B4okC2lX.js';
+export { aw as auto, aC as isAuto } from '../_dts/frac-B4okC2lX.js';
+import { R as ResolvedConfig, l as ConfigNode, A as Annotations, N as NodeOptions, v as SectionOption, d as ControlRenderer, n as ConfigOption, p as ConfigShape, h as ConfigBranch, B as BranchAnnotations, e as BranchOptions, b as ConfigSchema, I as InferConfig, i as ConfigEntry, a as ConfigField, c as ConfigRule, L as LeafPatch, o as ConfigRuleContext } from '../_dts/types-DzoNY1pO.js';
+export { m as ConfigOf, C as ConfigPath, E as EntryValue, q as NodeValue, S as SectionSpec, V as ValueAtPath } from '../_dts/types-DzoNY1pO.js';
+import { ToolPrefNumberFormat, ToolPrefNumberUnit, ToolPrefLeaf, ToolPrefGroup } from '@weasel-js/core';
+import 'react';
+import '../_dts/types-DJ79Tg5J.js';
+import '../_dts/PrefsForm.d-DPy9I8It.js';
+
+/** The dotted paths a schema declares as starting auto — every leaf that said
+ *  `.initial(auto)`. This is what seeds a new trial's unpinned set. */
+declare function autoPathsOf(resolved: ResolvedConfig): string[];
+/**
+ * The config an instrument reads: the stored one, with every unpinned path
+ * either computed by its resolver or removed.
+ *
+ * Resolution is demand-driven — a resolver reading another unpinned path
+ * forces that one first, whatever order the schema declared them in — so a
+ * cycle is a real cycle and not an ordering accident.
+ */
+declare function resolveAutoConfig<TC>(resolved: ResolvedConfig, config: TC, autoPaths: ReadonlySet<string>): TC;
+
+/** Whether a schema entry is a branch rather than a leaf. */
+declare 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. */
+declare abstract class BaseNode<T> implements ConfigNode<T> {
+    readonly annotations: Readonly<Annotations>;
+    readonly options: Readonly<NodeOptions>;
+    abstract readonly kind: string | null;
+    readonly default: T;
+    constructor(defaultValue: T, annotations?: Readonly<Annotations>, options?: Readonly<NodeOptions>);
+    /** Clone into the same subclass. Subclasses with extra constructor
+     *  arguments override this. */
+    protected with(annotations: Annotations, options: NodeOptions): this;
+    protected ann(patch: Annotations): this;
+    protected opt(patch: NodeOptions): this;
+    /** Human-readable label. Defaults to the key, title-cased. */
+    label(name: string): this;
+    /** Longer help text, surfaced as a tooltip on the row label. */
+    describe(description: string): this;
+    /** Omit from the panel unless it is asked to show hidden leaves. */
+    hidden(): this;
+    /** Pair with a sibling sharing this id, side-by-side on one row. */
+    pair(pair: string): this;
+    /** Render under a named section heading. `collapsed` opens the section
+     *  folded, and `layout` and `pack` lay out its rows — say each on any one of
+     *  the section's leaves. */
+    section(label: string, opts?: Omit<SectionOption, 'label'>): this;
+    /** 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;
+    /** Draw this one row yourself, keeping the kind, default and validation. */
+    render(renderer: ControlRenderer): this;
+    /**
+     * Compute this leaf's value while it is auto, instead of leaving it
+     * `undefined`. The resolver is given the config with every other auto path
+     * already resolved.
+     */
+    auto(resolve: (config: Record<string, unknown>) => T): this;
+    /**
+     * Start this leaf auto rather than pinned at its default. Takes `auto` and
+     * nothing else — the constructor argument already declares the value, and a
+     * second way to say it would fight with the first.
+     */
+    initial(value: Auto): this;
+    /** Never auto. The row takes no pin dot and ignores the gesture. */
+    manual(): this;
+}
+declare 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;
+    step(step: number): this;
+    /** A display suffix for the value — `'px'`, `'ms'`, `'°'`. Presentation only:
+     *  it is never parsed, and the stored value stays a plain number. */
+    suffix(suffix: string): this;
+    /** 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: ToolPrefNumberFormat): this;
+    /**
+     * Store the value in one unit and edit it in another — radians stored,
+     * degrees typed. `min`, `max` and `step` are declared in the stored unit
+     * alongside the value, and convert with it. `prefUnit` builds one from a
+     * `UnitSystem`.
+     */
+    unit(unit: ToolPrefNumberUnit): this;
+    /** Force a slider even without both bounds. */
+    slider(): this;
+    /** Force a typed input even when both bounds are set. */
+    input(): this;
+}
+declare class BooleanNode extends BaseNode<boolean> {
+    readonly kind = "boolean";
+    /** Ask for a switch rather than a checkbox. */
+    toggle(): this;
+}
+declare class StringNode extends BaseNode<string> {
+    readonly kind = "string";
+    placeholder(placeholder: string): this;
+    maxLength(maxLength: number): this;
+    /** Milliseconds to debounce live writes. 0 commits every keystroke. */
+    debounce(debounceMs: number): this;
+}
+declare class ColorNode extends BaseNode<string> {
+    readonly kind = "color";
+    /** The value carries alpha as `#rrggbbaa`, and the row gets an opacity
+     *  track beside the swatch. */
+    alpha(): this;
+}
+declare class EnumNode<T extends string> extends BaseNode<T> {
+    readonly kind = "enum";
+    /** Render as a segmented control rather than a select. */
+    radio(): this;
+    /** Relabel the choices. Named `labels` rather than `options` because
+     *  `options` is the node's own extras bag. */
+    labels(options: readonly ConfigOption[]): this;
+}
+/** A leaf whose kind the rule chain decides. */
+declare class ValueNode<T> extends BaseNode<T> {
+    readonly kind: null;
+}
+/** A leaf of a kind labkit does not ship a row for. */
+declare class CustomNode<T> extends BaseNode<T> {
+    readonly kind: string;
+    constructor(kind: string, defaultValue: T, annotations?: Readonly<Annotations>, options?: Readonly<NodeOptions>);
+    protected with(annotations: Annotations, options: NodeOptions): this;
+}
+/**
+ * A branch of the schema: its children nest under its key, so a leaf inside
+ * one is read and written at a dotted path. Distinct from `.section()`, which
+ * puts a heading over sibling leaves and leaves their paths alone.
+ */
+declare class GroupNode<S extends ConfigShape> implements ConfigBranch<S> {
+    readonly children: S;
+    readonly annotations: Readonly<BranchAnnotations>;
+    readonly options: Readonly<BranchOptions>;
+    constructor(children: S, annotations?: Readonly<BranchAnnotations>, options?: Readonly<BranchOptions>);
+    private with;
+    /** Heading for the group's rows. Defaults to the key, title-cased. */
+    label(name: string): GroupNode<S>;
+    /** Longer help text. Carried on the resolved `PrefGroup`, where weasel-ui's
+     *  `PrefsForm` draws it under the heading; `ControlPanel` has no place for
+     *  it yet and shows the heading alone. */
+    describe(description: string): GroupNode<S>;
+    /** Render this whole group under a named section heading. */
+    section(label: string, opts?: Omit<SectionOption, 'label'>): GroupNode<S>;
+    /** Show this group only while the predicate holds. Presentational — every
+     *  value beneath it stays in config and the instrument still reads it. */
+    showIf(predicate: (config: Record<string, unknown>) => boolean): GroupNode<S>;
+}
+/**
+ * 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'),
+ *   // Nested: read and written at `grid.color`.
+ *   grid: f.group({ color: f.color('#ffffff') }),
+ * })
+ * ```
+ */
+declare const f: {
+    number: (def: number) => NumberNode;
+    boolean: (def: boolean) => BooleanNode;
+    string: (def: string) => StringNode;
+    color: (def: string) => ColorNode;
+    /** 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>;
+    /** 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>;
+    /** A branch: its children nest under this key, so `grid: f.group({ size })`
+     *  puts the value at `config.grid.size` and addresses it as `'grid.size'`.
+     *  Groups nest as deeply as the schema wants. */
+    group: <const S extends ConfigShape>(children: S) => GroupNode<S>;
+    /** A leaf of a kind a lab supplies the control for, through `controls`. */
+    custom: <T>(kind: string, def: T, validate?: (leaf: ToolPrefLeaf, config: Record<string, unknown>) => string[]) => CustomNode<T>;
+    /** Collect leaves and groups into an instrument's config. */
+    schema<S extends ConfigShape>(nodes: S): ConfigSchema<InferConfig<S>>;
+};
+
+/**
+ * Adapt a legacy `configSchema(): ConfigField[]` into the resolved shape, so
+ * both instrument paths reach one renderer.
+ *
+ * Rules do not run here: a hand-written `ConfigField` already states its label
+ * and control, which is everything the rule chain would have inferred.
+ */
+declare function fromConfigFields(fields: readonly ConfigField[]): ResolvedConfig;
+
+/** The value at a dotted path. `undefined` when a segment is missing or the
+ *  walk hits something that is not a record. */
+declare function valueAtPath(config: unknown, path: string): unknown;
+/** Whether a dotted path is actually present, which a `undefined` value is
+ *  not enough to tell you. */
+declare function hasConfigPath(config: unknown, path: string): boolean;
+/** A copy of `config` with `value` written at a dotted path. Every record on
+ *  the way down is copied and the input is left alone; a missing — or
+ *  non-record — intermediate is replaced with the branch the path implies. */
+declare function withValueAtPath<T>(config: T, path: string, value: unknown): T;
+/**
+ * `stored` with every gap filled from `defaults`, down the whole tree.
+ *
+ * This is how a config written before its schema grew a branch still loads:
+ * the branch arrives at its defaults instead of `undefined`, and a key the
+ * defaults no longer mention is kept rather than dropped, so nothing is lost
+ * to a schema change the author has not finished making.
+ */
+declare function fillConfigDefaults<T>(stored: unknown, defaults: T): T;
+/** A node in a resolved schema tree, by dotted path. Structural rather than
+ *  `isPrefLeaf` so this stays free of a runtime import. */
+declare function schemaNodeAtPath(group: ToolPrefGroup, path: string): ToolPrefLeaf | ToolPrefGroup | undefined;
+
+/**
+ * Resolve a schema into the vocabulary weasel-ui renders, running each leaf
+ * through the consumer's rules and then labkit's own.
+ *
+ * The group mirrors the schema's own nesting: an `f.group` becomes a nested
+ * `PrefGroup`, so a leaf's dotted path within the tree is the path its value
+ * is written at, and both `ControlPanel` and `PrefsForm` address it
+ * identically.
+ */
+declare function resolveConfigSchema<TC>(schema: ConfigSchema<TC>, rules?: readonly ConfigRule[]): ResolvedConfig;
+
+/** `cellSize` -> `Cell size`. Splits camelCase without shattering acronyms. */
+declare function titleCase(key: string): string;
+/**
+ * labkit's own inference, expressed in the same vocabulary a consumer
+ * extends. Runs after the consumer's rules, so a lab always wins.
+ *
+ * If one of these ever needs something a `ConfigRule` cannot express, the
+ * seam is too weak — that is the point of writing them this way.
+ */
+declare const builtinRules: readonly ConfigRule[];
+/**
+ * Fold a rule chain into one leaf patch. Gap-filling: a property already
+ * settled is never overwritten, so the accumulator seeded with the author's
+ * annotations beats every rule, and earlier rules beat later ones.
+ */
+declare function applyRules(seed: LeafPatch, ctx: Omit<ConfigRuleContext, 'leaf'>, rules: readonly ConfigRule[]): LeafPatch;
+
+/**
+ * An instrument's controls, resolved against the surrounding lab's rules.
+ *
+ * Resolution cannot happen in `defineInstrument` — rules are lab-scoped and
+ * that runs at module load — so it happens here, at render. Both instrument
+ * paths land in the same shape, so callers never branch on which was used.
+ */
+declare function useConfigSchema(instrument: Instrument<any, any, any>): ResolvedConfig;
+
+/**
+ * The config an instrument reads: the stored one with every unpinned path
+ * resolved. The single place resolution happens, so `Trial` and
+ * `useTrialState` cannot disagree about what an instrument is looking at.
+ */
+declare function useResolvedConfig<TC>(schema: ResolvedConfig | undefined, config: TC, autoPaths: readonly string[] | undefined): {
+    config: TC;
+    auto: ReadonlySet<string>;
+};
+
+/**
+ * Whether the row at a dotted path should be drawn right now. A group answers
+ * for its whole subtree — hiding one hides everything under it.
+ *
+ * `hidden` is the node's own static flag; `showIf` is the schema's predicate
+ * over the live config. Both are presentational — a hidden leaf keeps its
+ * value and the instrument still reads it.
+ */
+declare function isLeafVisible(resolved: ResolvedConfig, path: string, config: Record<string, unknown>, showHidden?: boolean): boolean;
+
+export { Annotations, Auto, BaseNode, BooleanNode, BranchAnnotations, BranchOptions, ColorNode, ConfigBranch, ConfigEntry, ConfigNode, ConfigOption, ConfigRule, ConfigRuleContext, ConfigSchema, ConfigShape, ControlRenderer, CustomNode, EnumNode, GroupNode, InferConfig, LeafPatch, NodeOptions, NumberNode, ResolvedConfig, StringNode, ValueNode, applyRules, autoPathsOf, builtinRules, f, fillConfigDefaults, fromConfigFields, hasConfigPath, isConfigBranch, isLeafVisible, resolveAutoConfig, resolveConfigSchema, schemaNodeAtPath, titleCase, useConfigSchema, useResolvedConfig, valueAtPath, withValueAtPath };

package/dist/config/index.js

@@ -0,0 +1,8 @@
+export { useConfigSchema } from '../chunk-PJ7WEQBJ.js';
+import '../chunk-Z76KEZAX.js';
+export { BaseNode, BooleanNode, ColorNode, CustomNode, EnumNode, GroupNode, NumberNode, StringNode, ValueNode, applyRules, builtinRules, f, isConfigBranch, resolveConfigSchema, titleCase, useResolvedConfig } from '../chunk-ZDHY47EV.js';
+export { fromConfigFields, isLeafVisible } from '../chunk-PHK4W562.js';
+export { auto, autoPathsOf, fillConfigDefaults, hasConfigPath, isAuto, resolveAutoConfig, schemaNodeAtPath, valueAtPath, withValueAtPath } from '../chunk-7PFH3CNM.js';
+import '../chunk-T3EC2DXD.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/controls/index.d.ts

@@ -1,7 +1,6 @@
-export { e as ControlPanel } from '../_dts/index-Blv9uQzu.js';
-export { a as CheckboxField, b as ColorField, C as ConfigField, d as ConfigFieldType, N as NumberField, S as SelectField, e as SelectOption, f as SliderField, T as TextField } from '../_dts/types-x92Kfeme.js';
+export { e as ControlPanel } from '../_dts/index-BNdz-tNd.js';
+export { f as CheckboxField, g as ColorField, a as ConfigField, k as ConfigFieldType, r as NumberField, s as SelectField, t as SelectOption, u as SliderField, T as TextField } from '../_dts/types-DzoNY1pO.js';
 import 'react/jsx-runtime';
 import 'react';
-import '../_dts/types-B9_zrHmb.js';
 import '@weasel-js/core';
-import '../_dts/PrefsForm.d-DDHFANkc.js';
+import '../_dts/PrefsForm.d-DPy9I8It.js';

package/dist/controls/index.js

@@ -1,5 +1,6 @@
-export { ControlPanel } from '../chunk-U3IYHIAE.js';
-import '../chunk-E44SU6XS.js';
-import '../chunk-W3ECWC2K.js';
+export { ControlPanel } from '../chunk-EH7UEQV7.js';
+import '../chunk-PHK4W562.js';
+import '../chunk-7PFH3CNM.js';
+import '../chunk-T3EC2DXD.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/dragdrop/index.d.ts

@@ -1,11 +1,9 @@
-import { P as PaletteItem, a as Point, D as DragFeedback, b as DragDropCapability, V as ViewTransform, c as WorldSpec } from '../_dts/frac-z7ker2Vx.js';
+import { P as PaletteItem, l as Point, m as DragFeedback, n as DragDropCapability, k as ViewTransform, a as WorldSpec } from '../_dts/frac-B4okC2lX.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { RefObject, PointerEvent, ReactPortal } from 'react';
-import '../_dts/types-B9_zrHmb.js';
+import '../_dts/types-DzoNY1pO.js';
 import '@weasel-js/core';
-import '../_dts/PrefsForm.d-DDHFANkc.js';
-import '../_dts/types-x92Kfeme.js';
-import '../_dts/types-BP2OCcpg.js';
+import '../_dts/PrefsForm.d-DPy9I8It.js';
 import '../_dts/types-DJ79Tg5J.js';
 
 interface DragState {