@weasel-js/labkit 1.5.1 → 1.6.0

package/README.md

@@ -30,9 +30,6 @@ the `@weasel-js/ui` components it passes through:
 import '@weasel-js/labkit/styles.css';
 ```
 
-Annotations are on the `pre` tag until the next stable release:
-`npm i @weasel-js/labkit@pre`.
-
 ## A lab
 
 ```tsx
@@ -250,8 +247,8 @@ it. `SidebarSection.undockable` and `undockAs` control the offer;
 
 ## Theming
 
-labkit ships one theme, `interstellar` — a cosmic dark and a warm parchment
-light — as a value, not a stylesheet. `<Lab>` and `<LabShell>` apply it for you;
+labkit ships one theme, `interstellar` — a cosmic dark over weasel's own light
+mode — as a value, not a stylesheet. `<Lab>` and `<LabShell>` apply it for you;
 `mode` is `"auto"` (follow the OS), `"light"` or `"dark"`. Only `styles.css`
 needs importing, and the token values arrive through the provider:
 
@@ -316,14 +313,13 @@ directly. Several expose more than the root does, `/state` most of all.
 | `/chrome` | Regions, contribution types, built-in contributions |
 | `/controls` | `<ControlPanel>` and the config field types |
 | `/canvas` | `<CanvasStack>`, coordinate helpers, `usePanZoom`, `useOrbit` |
-| `/layers` | `<LayerList>` |
+| `/layers` | `<LayerList>` from `@weasel-js/ui`, and the layers capability types |
 | `/loupe` | Magnifier components and `useLoupe` |
 | `/surface` | Tiled surface hooks for your own renderer |
 | `/job` | `useJob` and the job capability types |
 | `/state` | The lab store, storage adapters, `useTrialState`, serialization helpers |
 | `/undo` | Undo stack and event bus |
 | `/dragdrop` | `<Palette>`, `<DragGhost>`, `useDragDrop` |
-| `/ui/layers` | `<LayerStack>`, the expandable layer-card list |
 | `/weasel-ui`, `/weasel-canvas` | Passthroughs to `@weasel-js/ui` and `@weasel-js/core` |
 
 ## Development

package/dist/_dts/{CanvasStackContext-CJNMS6mz.d.ts → CanvasStackContext-DQgcH1ny.d.ts}

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { RefObject } from 'react';
-import { k as ViewTransform, W as WorldFrame } from './frac-B4okC2lX.js';
+import { m as ViewTransform, W as WorldFrame } from './frac-DTRq7Xpb.js';
 
 /** One layer of a canvas stack: its id, whether it is currently shown, and how
  *  it paints itself. */

package/dist/_dts/LayerList.d-2c9yup5Y.d.ts

@@ -0,0 +1,83 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { S as StanceProps } from './PrefsRow.d-DFpPIeIC.js';
+
+/** One layer. With a body (see `renderBody`) it draws as a card that folds its
+ *  body away; without one, as a one-line row. Either can hold child layers. */
+interface LayerListItem {
+    id: string;
+    /** The layer's name. Also what its controls are labeled by. */
+    label: string;
+    /** Shown in the header in place of `label` — a select that switches the
+     *  layer's kind, say. */
+    title?: ReactNode;
+    /** Fixed-size content before the label: a color swatch, a kind icon. */
+    leading?: ReactNode;
+    /** Drawn in the drag handle in place of the grip — an ordinal. */
+    badge?: ReactNode;
+    /** Which of its list this layer is: an index into the theme's tone list, or
+     *  a color. A card draws its edge and handle in it and recolors its controls. */
+    tone?: StanceProps['tone'];
+    /** Cannot be dragged, hidden or removed, walls off drops on either side, and
+     *  selects alone rather than joining a multi-selection. */
+    locked?: boolean;
+    /** Shown or not, when the list has `onVisibilityChange`. Default true. */
+    visible?: boolean;
+    children?: LayerListItem[];
+    /** Folds the body and children away until the user opens them.
+     *  `collapsedIds` overrides it. */
+    defaultCollapsed?: boolean;
+}
+/**
+ * A reorder: `ids`, siblings under `parentId` (`null` at the top level), now
+ * sit as one block in list order starting at `index` of the parent's children.
+ * A drag never moves a layer to another parent.
+ */
+interface LayerMove {
+    ids: string[];
+    parentId: string | null;
+    index: number;
+}
+/** Props for `<LayerList>`. */
+interface LayerListProps {
+    items: LayerListItem[];
+    /** Omit for a list the user cannot reorder. */
+    onReorder?: (move: LayerMove) => void;
+    /** Giving both makes rows selectable: a click selects one, shift-click adds
+     *  or removes one, and dragging a selected row drags its selected siblings. */
+    selectedIds?: readonly string[];
+    onSelect?: (ids: string[]) => void;
+    /** Adds a visibility checkbox to every unlocked layer. */
+    onVisibilityChange?: (id: string, visible: boolean) => void;
+    /** Adds a ✕ to every unlocked layer. */
+    onRemove?: (id: string) => void;
+    /** A layer's controls. Returning `null` leaves that layer a one-line row. */
+    renderBody?: (item: LayerListItem) => ReactNode;
+    /** Ids whose body and children are folded away. Giving it makes folding
+     *  controlled; `onCollapsedChange` fires either way. */
+    collapsedIds?: readonly string[];
+    onCollapsedChange?: (ids: string[]) => void;
+    /** Heading above the list. */
+    title?: string;
+    /** Names the list for assistive tech when it has no `title`. */
+    label?: string;
+    /** Kinds the user can add, as buttons beside the title. Shown only with `onAdd`. */
+    addKinds?: string[];
+    onAdd?: (kind: string) => void;
+    /** Shown in place of the list when `items` is empty. */
+    empty?: ReactNode;
+    /** Appended to the root's class list — the module's own names are hashed. */
+    className?: string;
+}
+/** Returns `items` with `move` applied, for a consumer that holds the tree as state. */
+declare function moveLayers(items: LayerListItem[], move: LayerMove): LayerListItem[];
+/**
+ * An ordered, drag-reorderable list of layers — a document's objects, a lab's
+ * canvases, a fill's effects. Each layer is a one-line row or, with a body, a
+ * card whose controls fold away; either can nest child layers. Selection,
+ * visibility, removal and an add palette are each on when their handler is given.
+ */
+declare function LayerList(props: LayerListProps): react_jsx_runtime.JSX.Element;
+
+export { LayerList as L, moveLayers as m };
+export type { LayerListItem as a, LayerListProps as b, LayerMove as c };

package/dist/_dts/{PrefsForm.d-DPy9I8It.d.ts → PrefsRow.d-DFpPIeIC.d.ts}

@@ -1,6 +1,21 @@
+import { Stance } from '@weasel-js/theme';
 import { ReactNode } from 'react';
 import { ToolPrefLeaf } from '@weasel-js/core';
 
+/**
+ * What a surface holds, and which of its peers it is. Every surface that takes
+ * these takes both, and the theme decides how each looks.
+ */
+interface StanceProps {
+    /** The class of content the surface holds. Omitted, it draws as it always has. */
+    stance?: Stance;
+    /**
+     * Which of its peers this is: an index into the theme's tone list, wrapping,
+     * or a color given directly. Independent of `stance`, and allowed without one.
+     */
+    tone?: number | string;
+}
+
 /** What a {@link PrefRenderer} is given for the leaf it is rendering. */
 interface PrefRenderContext {
     /** Dotted path of the leaf within the schema root. */
@@ -21,4 +36,4 @@ interface PrefRenderContext {
  */
 type PrefRenderer = (ctx: PrefRenderContext) => ReactNode;
 
-export type { PrefRenderer as P, PrefRenderContext as a };
+export type { PrefRenderer as P, StanceProps as S, PrefRenderContext as a };

package/dist/_dts/{Select.d-Gwr8fLpK.d.ts → Select.d-BchGMC2Y.d.ts}

@@ -1,12 +1,13 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode, ButtonHTMLAttributes, ReactElement } from 'react';
+import { S as StanceProps } from './PrefsRow.d-DFpPIeIC.js';
 import { TextFieldProps, ValidationResult, SelectProps as SelectProps$1, ListBoxItemProps } from 'react-aria-components';
 
 declare const ICON_PATHS: {
     readonly clone: "<path d=\"M7 7.4V4.6A1.6 1.6 0 0 1 8.6 3h6.8A1.6 1.6 0 0 1 17 4.6v6.8a1.6 1.6 0 0 1-1.6 1.6H12.6\" stroke-linecap=\"butt\"/><rect x=\"3\" y=\"7\" width=\"10\" height=\"10\" rx=\"1.6\"/><path d=\"M5.7 10.8h4.6M5.7 13.4h3\" stroke-width=\"1\"/>";
     readonly reset: "<path d=\"M7.28 4.88A5.8 5.8 0 1 0 12.72 4.88\"/><path d=\"M13.81 7.57 12.72 4.88 15.56 4.28\"/>";
-    readonly close: "<path d=\"M5 5 15 15M15 5 5 15\" stroke-width=\"1.75\"/>";
+    readonly close: "<path d=\"M4.5 4.5 15.5 15.5M15.5 4.5 4.5 15.5\" stroke-width=\"1.75\"/>";
     readonly export: "<path d=\"M4 12.6v2.9A1.5 1.5 0 0 0 5.5 17h9a1.5 1.5 0 0 0 1.5-1.5v-2.9\"/><path d=\"M10 3.2v8.5\"/><path d=\"M11.7 9.35 10 11.7 8.3 9.35\"/><path d=\"M6.8 14.7h6.4\" stroke-width=\"1\"/>";
     readonly zoomIn: "<circle cx=\"9\" cy=\"9\" r=\"5.4\"/><path d=\"M12.82 12.82 16.9 16.9\"/><path d=\"M9 6.7v4.6M6.7 9h4.6\"/>";
     readonly zoomOut: "<circle cx=\"9\" cy=\"9\" r=\"5.4\"/><path d=\"M12.82 12.82 16.9 16.9\"/><path d=\"M6.7 9h4.6\"/>";
@@ -20,6 +21,14 @@ declare const ICON_PATHS: {
     readonly undo: "<path d=\"M4.4 8.4h6.8a3.6 3.6 0 0 1 0 7.2H8.6\"/><path d=\"M6.47 10.14 4.4 8.4 6.47 6.66\"/>";
     readonly redo: "<path d=\"M15.6 8.4H8.8a3.6 3.6 0 0 0 0 7.2H11.4\"/><path d=\"M13.53 6.66 15.6 8.4 13.53 10.14\"/>";
     readonly snapshot: "<path d=\"M3.8 8.3A1.4 1.4 0 0 1 5.2 6.9h1.9L8 5.1h4l.9 1.8h1.9A1.4 1.4 0 0 1 16.2 8.3v6A1.4 1.4 0 0 1 14.8 15.7H5.2A1.4 1.4 0 0 1 3.8 14.3z\"/><circle cx=\"10\" cy=\"11\" r=\"2.75\"/>";
+    readonly bold: "<path d=\"M6 3.5h4.6a3.1 3.1 0 0 1 0 6.2H6zM6 9.7h5.4a3.4 3.4 0 0 1 0 6.8H6z\" stroke-width=\"2.1\"/>";
+    readonly italic: "<path d=\"M9 3.5h6M5 16.5h6M12.5 3.5 7.5 16.5\"/>";
+    readonly underline: "<path d=\"M6 3.4v5.6a4 4 0 0 0 8 0V3.4\"/><path d=\"M4.6 17h10.8\"/>";
+    readonly strikethrough: "<path d=\"M14.4 5.8c-.9-1.6-2.4-2.4-4.4-2.4-2.5 0-4.2 1.3-4.2 3.1 0 .9.4 1.6 1.2 2.2\"/><path d=\"M5.6 14.2c.9 1.6 2.4 2.4 4.4 2.4 2.5 0 4.2-1.3 4.2-3.1 0-.9-.4-1.6-1.2-2.2\"/><path d=\"M3.4 10h13.2\"/>";
+    readonly overline: "<path d=\"M4.6 3h10.8\"/><ellipse cx=\"10\" cy=\"11.4\" rx=\"4.4\" ry=\"4.8\"/>";
+    readonly superscript: "<path d=\"M3.6 8.6 10.4 16.4M10.4 8.6 3.6 16.4\"/><path d=\"M11.9 5.3a2.2 2.2 0 1 1 4.3.8c0 1.4-4.3 2.2-4.3 3.5h4.5\"/>";
+    readonly subscript: "<path d=\"M3.6 3.6 10.4 11.4M10.4 3.6 3.6 11.4\"/><path d=\"M11.9 11.5a2.2 2.2 0 1 1 4.3.8c0 1.4-4.3 2.2-4.3 3.5h4.5\"/>";
+    readonly code: "<path d=\"M7 6.2 3.2 10 7 13.8M13 6.2 16.8 10 13 13.8\"/><path d=\"M11.2 4.8 8.8 15.2\"/>";
     readonly play: "<path d=\"M7.6 5.2 15.6 10 7.6 14.8Z\"/>";
     readonly pause: "<path d=\"M7.8 5.2v9.6M12.2 5.2v9.6\"/>";
     readonly stop: "<rect x=\"5.6\" y=\"5.6\" width=\"8.8\" height=\"8.8\" rx=\"1.4\"/>";
@@ -34,6 +43,7 @@ declare const ICON_PATHS: {
     readonly warning: "<path d=\"M10 3.4 17.4 16.2H2.6z\"/><path d=\"M10 8.4v3.4\"/><path d=\"M10 14h0\"/>";
     readonly error: "<circle cx=\"10\" cy=\"10\" r=\"7\"/><path d=\"M7.6 7.6 12.4 12.4M12.4 7.6 7.6 12.4\"/>";
     readonly busy: "<path d=\"M10 3.2A6.8 6.8 0 1 1 3.2 10\"/>";
+    readonly check: "<path d=\"M4.35 10.56 8.03 14.24 15.66 5.77\"/>";
     readonly modeLight: "<circle cx=\"10\" cy=\"10\" r=\"3.5\"/><path d=\"M15.3 10L17.7 10M13.75 6.25L15.44 4.56M10 4.7L10 2.3M6.25 6.25L4.56 4.56M4.7 10L2.3 10M6.25 13.75L4.56 15.44M10 15.3L10 17.7M13.75 13.75L15.44 15.44\"/>";
     readonly modeDark: "<path d=\"M8.19 3.55A6.7 6.7 0 1 0 16.45 11.81A5.9 5.9 0 0 1 8.19 3.55Z\"/>";
     readonly modeAuto: "<path d=\"M10 2.6Q10 10 17.4 10Q10 10 10 17.4Q10 10 2.6 10Q10 10 10 2.6Z\"/>";
@@ -43,6 +53,7 @@ declare const ICON_PATHS: {
     readonly search: "<circle cx=\"9\" cy=\"9\" r=\"5.4\"/><path d=\"M12.82 12.82 16.9 16.9\"/>";
     readonly loupe: "<circle cx=\"9\" cy=\"9\" r=\"5.6\"/><path d=\"M12.96 12.96 17 17\"/><rect x=\"6\" y=\"6\" width=\"6\" height=\"6\" stroke-width=\"1\"/><path d=\"M9 6v6M6 9h6\" stroke-width=\"1\"/>";
     readonly layers: "<path d=\"M10 2.8 17.2 6.6 10 10.4 2.8 6.6z\"/><path d=\"M2.8 10 10 13.8 17.2 10\" stroke-width=\"1\"/><path d=\"M2.8 13.4 10 17.2 17.2 13.4\" stroke-width=\"1\"/>";
+    readonly page: "<path d=\"M4.6 2.8H11.6L15.4 6.6V17.2H4.6z\"/><path d=\"M11.6 2.8V6.6H15.4\"/>";
     readonly link: "<path d=\"M8.6 11.4a3.4 3.4 0 0 1 0-4.8l2.2-2.2a3.4 3.4 0 0 1 4.8 4.8l-1.1 1.1\"/><path d=\"M11.4 8.6a3.4 3.4 0 0 1 0 4.8l-2.2 2.2a3.4 3.4 0 0 1-4.8-4.8l1.1-1.1\"/>";
     readonly collapse: "<path d=\"M14.16 4.05 10 7.8 5.84 4.05M5.84 15.95 10 12.2 14.16 15.95\"/>";
     readonly expand: "<path d=\"M5.84 8.15 10 4.4 14.16 8.15M14.16 11.85 10 15.6 5.84 11.85\"/>";
@@ -230,13 +241,31 @@ declare function Icon({ name, className, size, label, filled, fillOpacity, }: Ic
     name: IconName;
 }): react_jsx_runtime.JSX.Element;
 
-/** Visual weight of a button. Defaults to `secondary`. */
-type ButtonVariant = 'primary' | 'secondary' | 'ghost';
+/** The tooltip fields a segmented bar's item carries. */
+interface SegmentTooltipFields {
+    /** Tooltip content. Overrides the name-plus-`shortcut` default. */
+    tooltip?: ReactNode;
+    /** Shortcut hint shown in the tooltip as `Name (⌘Z)`, the way `ToolButton`
+     *  and `ActionBar` show theirs. The name is `ariaLabel`, else a string
+     *  `label`. */
+    shortcut?: string;
+}
+
+/** Visual weight of a button. Defaults to `secondary`. `link` drops the
+ *  control box entirely and reads as a hyperlink in running text -- for an
+ *  in-page navigation that is still a button, not an `<a href>`. */
+type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'link';
+/** Text color of a `link` button — the same set as `Code`'s statuses. */
+type ButtonStatus = 'neutral' | 'muted' | 'accent' | 'success' | 'warn' | 'danger';
 /** Button height and type scale. */
 type ButtonSize = 'sm' | 'md';
 type ButtonBase = {
     variant?: ButtonVariant;
     size?: ButtonSize;
+    /** Text color of the `link` variant, which is `accent` unless told
+     *  otherwise. The boxed variants carry their weight in their fill and
+     *  ignore it. A peer `tone`, or a stance's accent, paints over it. */
+    status?: ButtonStatus;
     /** A button that stays down: renders `aria-pressed` and holds the active
      *  treatment while it is on. For a control that reports a state rather than
      *  firing an action -- a panel toggle, a mode switch. Left off, the button
@@ -252,7 +281,7 @@ type ButtonBase = {
     style?: ButtonHTMLAttributes<HTMLButtonElement>['style'];
     children?: ReactNode;
     onClick?: ButtonHTMLAttributes<HTMLButtonElement>['onClick'];
-};
+} & StanceProps & SegmentTooltipFields;
 type ButtonRegular = ButtonBase & {
     iconOnly?: false;
     ariaLabel?: string;
@@ -271,6 +300,10 @@ type ButtonProps = ButtonRegular | ButtonIconOnly;
  * button `aria-busy`, and leaves the label in place; it does not disable the
  * button, so pass `disabled` too if the click should be blocked.
  *
+ * `shortcut` adds a kit tooltip reading `Name (⌘S)`, named by `ariaLabel` or
+ * string children, the way `ToolButton` and `ButtonBar` items show theirs;
+ * `tooltip` replaces that text with any content.
+ *
  * `ref` forwards to the underlying `<button>`.
  */
 declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
@@ -281,7 +314,7 @@ type ToggleBarItem<V extends string | number = string> = {
     label?: ReactNode;
     ariaLabel?: string;
     disabled?: boolean;
-};
+} & SegmentTooltipFields;
 /** Segment height and type scale for a {@link ToggleBar}. */
 type ToggleBarSize = 'sm' | 'md';
 /** Visual treatment of a {@link ToggleBar}. */
@@ -354,9 +387,48 @@ interface OverlayPortalProps {
 /** React Aria props minus the portal key a weasel overlay owns. */
 type WithoutPortalTarget<T> = Omit<T, 'UNSTABLE_portalContainer'>;
 
+/**
+ * Whether a {@link Field} stacks its label above the control or sits them
+ * side by side.
+ */
+type FieldOrientation = 'stacked' | 'row';
+/** Props for {@link Field}. */
+type FieldProps = {
+    orientation?: FieldOrientation;
+    className?: string;
+    children?: ReactNode;
+};
+/**
+ * Layout primitive that arranges a label, control, hint, and error in the
+ * canonical weasel-ui form-row shape. The control itself owns its semantics
+ * (RAC `TextField`, `Checkbox`, etc.); this just paints the layout.
+ *
+ * Most users will instead reach for `Input` / `Checkbox` / `Switch`, which
+ * compose Field internally. Use Field directly when you need a custom
+ * control to sit in the same visual rhythm.
+ */
+declare function Field({ orientation, className, children }: FieldProps): react_jsx_runtime.JSX.Element;
+/**
+ * The class names {@link Field} paints its slots with, so a control composing
+ * its own layout can match the same form-row rhythm.
+ */
+declare const fieldClasses: {
+    root: string;
+    row: string;
+    label: string;
+    hint: string;
+    error: string;
+};
+
 /** Props for {@link Input}, on top of React Aria's `TextField` props. */
 type InputProps = Omit<TextFieldProps, 'children' | 'className'> & {
     label?: ReactNode;
+    /**
+     * `'stacked'` (the default) puts the label above the field; `'row'` sets it
+     * beside the field at its own width, with any description or error on a
+     * line below. Same vocabulary as {@link Field}'s `orientation`.
+     */
+    orientation?: FieldOrientation;
     description?: ReactNode;
     errorMessage?: ReactNode | ((v: ValidationResult) => ReactNode);
     placeholder?: string;
@@ -373,6 +445,12 @@ type InputProps = Omit<TextFieldProps, 'children' | 'className'> & {
  */
 declare const Input: react.ForwardRefExoticComponent<Omit<TextFieldProps, "className" | "children"> & {
     label?: ReactNode;
+    /**
+     * `'stacked'` (the default) puts the label above the field; `'row'` sets it
+     * beside the field at its own width, with any description or error on a
+     * line below. Same vocabulary as {@link Field}'s `orientation`.
+     */
+    orientation?: FieldOrientation;
     description?: ReactNode;
     errorMessage?: ReactNode | ((v: ValidationResult) => ReactNode);
     placeholder?: string;
@@ -394,20 +472,40 @@ type SelectOption = {
      */
     textValue?: string;
 };
+/** A titled group of options in a {@link Select}'s `options` list. */
+type SelectOptionGroup<T extends Key = string> = {
+    title: ReactNode;
+    options: ReadonlyArray<SelectOption & {
+        value: T;
+    }>;
+};
 type Key = string | number;
+/** How a {@link Select} trigger signals that it opens a list. */
+type SelectIndicator = 'chevron' | 'underline' | 'none';
+/** Where a {@link Select}'s list opens relative to its trigger. */
+type SelectPopup = 'over' | 'below';
 /**
  * Props for {@link Select}, on top of React Aria's `Select` props, with the
  * selection key narrowed to the option value type.
  */
 type SelectProps<T extends Key = string> = Omit<SelectProps$1<object>, 'children' | 'className' | 'selectedKey' | 'defaultSelectedKey' | 'onSelectionChange'> & {
     label?: ReactNode;
+    /**
+     * `'stacked'` (the default) puts the label above the trigger; `'row'` sets it
+     * beside the trigger at its own width, with any description or error on a
+     * line below. Same vocabulary as {@link Field}'s `orientation`.
+     */
+    orientation?: FieldOrientation;
     description?: ReactNode;
     errorMessage?: ReactNode | ((v: ValidationResult) => ReactNode);
     placeholder?: string;
-    /** Either pass `options` for a quick render, or `children` for full control. */
-    options?: ReadonlyArray<SelectOption & {
+    /**
+     * Either pass `options` for a quick render, or `children` for full control.
+     * An entry with `title` and `options` of its own is a titled section.
+     */
+    options?: ReadonlyArray<(SelectOption & {
         value: T;
-    }>;
+    }) | SelectOptionGroup<T>>;
     children?: ReactNode;
     selectedKey?: T | null;
     defaultSelectedKey?: T;
@@ -420,6 +518,20 @@ type SelectProps<T extends Key = string> = Omit<SelectProps$1<object>, 'children
     width?: 'fill' | 'fit';
     /** `'bare'` drops the box, for a select set in a row of other chrome such as a property row. */
     variant?: 'field' | 'bare';
+    /**
+     * How the trigger says it opens a list. `'chevron'` draws the caret beside
+     * the value; `'underline'` marks the value itself, dotted at rest and solid
+     * while it is pointed at or open; `'none'` says nothing. Unset takes the
+     * variant's own: a boxed select shows the caret, a bare one — set in a row
+     * where 10px of caret is a tenth of the value's width — underlines.
+     */
+    indicator?: SelectIndicator;
+    /**
+     * Where the list opens. `'over'` (the default) puts the selected row on the
+     * trigger, its label in the trigger's own text column, so choosing what is
+     * already chosen moves nothing; `'below'` hangs it under the trigger.
+     */
+    popup?: SelectPopup;
     /**
      * Id for the trigger button. React Aria puts a plain `id` on the wrapper,
      * which is not labelable, so an outer `<label for>` needs this to reach a
@@ -427,14 +539,19 @@ type SelectProps<T extends Key = string> = Omit<SelectProps$1<object>, 'children
      */
     triggerId?: string;
     className?: string;
-} & OverlayPortalProps;
+} & SegmentTooltipFields & OverlayPortalProps;
 /**
  * Form select wrapping React Aria's Select. Pass either `options` for a
  * quick declarative render or `children` of `<SelectItem>` for control over
- * each row.
+ * each row; `<SelectSection>` (or an `options` entry with a `title`) groups
+ * rows under a heading.
  *
  * The selection key type is parameterized so consumers with a string-literal
  * union for `value` (e.g. `'r' | 'g' | 'b'`) get a typed `onSelectionChange`.
+ *
+ * `shortcut` puts a kit tooltip on the trigger reading `Name (⌘K)`, named by
+ * `aria-label` or a string `label`, as `Button` does; `tooltip` replaces that
+ * text.
  */
 declare function Select<T extends Key = string>(props: SelectProps<T>): react_jsx_runtime.JSX.Element;
 /** Props for {@link SelectItem}, on top of React Aria's `ListBoxItem` props. */
@@ -449,5 +566,5 @@ type SelectItemProps = Omit<ListBoxItemProps, 'className' | 'children'> & {
  */
 declare function SelectItem({ children, className, textValue, ...rest }: SelectItemProps): react_jsx_runtime.JSX.Element;
 
-export { Button as B, Select as S, ToggleBar as T, Icon as d, Input as e, ICON_PATHS as l, SelectItem as n };
-export type { IconProps as I, OverlayPortalProps as O, WithoutPortalTarget as W, ButtonProps as a, ButtonSize as b, ButtonVariant as c, InputProps as f, SelectProps as g, ToggleBarItem as h, ToggleBarProps as i, ToggleBarSize as j, ToggleBarVariant as k, IconName as m, SelectItemProps as o, SelectOption as p };
+export { Button as B, Select as S, ToggleBar as T, Icon as d, Input as e, Field as m, ICON_PATHS as o, SelectItem as q, fieldClasses as t };
+export type { FieldOrientation as F, IconProps as I, OverlayPortalProps as O, WithoutPortalTarget as W, ButtonProps as a, ButtonSize as b, ButtonVariant as c, InputProps as f, SelectProps as g, ToggleBarItem as h, ToggleBarProps as i, ToggleBarSize as j, ToggleBarVariant as k, SegmentTooltipFields as l, FieldProps as n, IconName as p, SelectItemProps as r, SelectOption as s };

package/dist/_dts/{frac-B4okC2lX.d.ts → frac-DTRq7Xpb.d.ts}

@@ -1,5 +1,7 @@
 import { ComponentType, ReactNode, RefObject } from 'react';
-import { R as ResolvedConfig, C as ConfigPath, V as ValueAtPath, a as ConfigField, b as ConfigSchema } from './types-DzoNY1pO.js';
+import { S as StanceProps } from './PrefsRow.d-DFpPIeIC.js';
+import { R as ResolvedConfig, a as ConfigPath, V as ValueAtPath, b as ConfigField, c as ConfigSchema } from './types-B7y8hX1D.js';
+import { ColorModePreference } from '@weasel-js/theme';
 import { J as JobHandle, a as JobCapability } from './types-DJ79Tg5J.js';
 import { Scene } from '@weasel-js/core';
 
@@ -129,7 +131,11 @@ interface SavedSnapshot {
     savedAt: number;
 }
 /** `auto` follows the OS; the other two are an explicit choice. */
-type LabMode = 'auto' | 'light' | 'dark';
+type LabMode = ColorModePreference;
+/** How much room the lab's own chrome takes — the theme's density axis, named
+ *  the way the theme names it. A lab's instruments are unaffected: this sizes
+ *  the shell around them. */
+type LabDensity = 'compact' | 'comfortable' | 'roomy';
 /** Everything a lab persists: its trials, its saved snapshots, and the
  *  chosen color mode. */
 interface LabStoreState {
@@ -173,7 +179,7 @@ interface TrialStateHandle<TS, TC> {
     setState: (next: TS | ((prev: TS) => TS)) => void;
     config: TC;
     /** The config as stored, before any auto path is resolved. What the control
-     *  panel renders, so a ghosted control sits at the value it pins back to. */
+     *  panel renders, so an auto row pins back to the value it was holding. */
     raw: TC;
     /** Dotted paths this trial has unpinned. */
     auto: ReadonlySet<string>;
@@ -265,15 +271,23 @@ interface ToolbarItem<TCtx = TrialChromeContext> {
      *  zero-argument handler stays valid. */
     onActivate: (ctx: TCtx) => void;
 }
-/** A selectable tool in the palette region. */
-interface ToolItem {
+/** A tool in the palette region: a mode by default, a command when it carries
+ *  an `onActivate`. `TCtx` is the chrome context that handler is handed — a
+ *  trial's, or the lab's for a lab-level rail. */
+interface ToolItem<TCtx = TrialChromeContext> {
     icon: IconComponent;
     label: string;
+    /** Shown in the tooltip. Not bound here — the trial owns its keymap. */
     shortcut?: string;
     disabled?: boolean;
+    /** Runs on press instead of selecting. An item with one is a command: it
+     *  never writes the tool slot, and never reads as the current tool. */
+    onActivate?: (ctx: TCtx) => void;
 }
-/** A titled block in the sidebar. */
-interface SidebarSection {
+/** A titled block in the sidebar. `stance` and `tone` work as on a
+ *  `<PropertyPanel>`: what kind of content the section holds, and which of its
+ *  peers it is. */
+interface SidebarSection extends StanceProps {
     title: string;
     /** Starts collapsed, until the trial remembers a fold of its own. */
     defaultCollapsed?: boolean;
@@ -589,7 +603,7 @@ interface CanvasCapability<TS = unknown, TC = unknown> {
 /** Declares that an instrument's DOM is content of a fixed size, which the
  *  trial pans and zooms the way it does a canvas's layers. Not combined with
  *  `canvas`: there the DOM is an unzoomed overlay, and `canvas` wins. */
-interface StageCapability {
+interface StageCapability<TS = unknown, TC = unknown> {
     /** The content's own size in CSS pixels, at zoom 1. */
     size: ViewportSize;
     /** Where the view starts. Omitted, the content opens centered and shrunk to
@@ -597,6 +611,9 @@ interface StageCapability {
     initialView?: ViewTransform | ((viewport: ViewportSize) => ViewTransform);
     minZoom?: number;
     maxZoom?: number;
+    /** Drawn over the content in viewport pixels, outside the camera — a legend,
+     *  a floating panel, anything that must not zoom with the picture. */
+    overlay?: (ctx: RenderContext<TS, TC>) => ReactNode;
 }
 /** Declares which of an instrument's layers the trial should offer
  *  show/hide controls for. */
@@ -696,7 +713,7 @@ interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
     serialize?: (state: TS) => unknown;
     deserialize?: (data: unknown, config: TC) => TS;
     canvas?: CanvasCapability<TS, TC>;
-    stage?: StageCapability;
+    stage?: StageCapability<TS, TC>;
     layers?: LayerCapability;
     dragDrop?: DragDropCapability<TS, TC>;
     undo?: UndoCapability;
@@ -785,8 +802,9 @@ interface FracRect {
     h: number;
 }
 /** What shape a mark is. The kinds map onto weasel's own tools; an arrow is a
- *  line carrying an end marker, not a separate geometry. */
-type AnnotationKind = 'stroke' | 'line' | 'arrow' | 'rect' | 'ellipse' | 'text';
+ *  line carrying an end marker, not a separate geometry. A point holds one
+ *  entry in `points` and zero-size bounds at that position. */
+type AnnotationKind = 'stroke' | 'line' | 'arrow' | 'rect' | 'ellipse' | 'text' | 'point';
 /** One selectable status in an instrument's meaning tier. */
 interface AnnotationStatus {
     id: string;
@@ -1018,5 +1036,5 @@ declare function fracContains(box: FracRect, pt: FracPoint, tol?: number): boole
  *  answers false for two rects that merely overlap. */
 declare function fracEncloses(outer: FracRect, inner: FracRect): boolean;
 
-export { DEFAULT_FRAME as D, LOUPE_DEFAULTS as a8, fracEncloses as aA, fracToWorld as aB, isAuto as aC, resolveLoupe as aD, roundFrac as aE, worldToFrac as aF, annotationsFromJSON as av, auto as aw, createAnnotationScene as ax, createAnnotationStore as ay, fracContains as az, applyCamera as b, dockPanel as j, panelKey as p, resolveFrame as r, undockPanel as u };
-export type { Auto as $, AnnotationData as A, AnnotationTarget as B, CreateLabStoreOptions as C, AnnotationsApi as E, AnnotationsCapability as F, TrialInfo as G, TrialTool as H, InstrumentSerializers as I, AnnotationKind as J, Instrument as K, LabDocument as L, Migration as M, TrialContribution as N, Annotation as O, PaletteItem as P, AnnotationInit as Q, AnnotationPatch as R, SerializedTrial as S, TrialRecord as T, UndoStack as U, ViewportSize as V, WorldFrame as W, AnnotationQuery as X, AnnotationStatus as Y, AnnotationStoreOptions as Z, AnnotationTargetInfo as _, WorldSpec as a, CanvasCapability as a0, CanvasLayer as a1, CaptureDeps as a2, ContributionBase as a3, FracPoint as a4, FracRect as a5, HitResult as a6, IconComponent as a7, LayerCapability as a9, LoupePoint as aG, LoupeMode as aH, LayerDescriptor as aa, LoupeCapability as ab, LoupeDeclaration as ac, LoupeRenderArgs as ad, RegionContribution as ae, RenderContext as af, ResolvedLoupe as ag, SerializedAnnotations as ah, SidebarSection as ai, SidebarSlotContext as aj, StageCapability as ak, StatusReadout as al, SystemEvent as am, ToolCapability as an, ToolItem as ao, ToolSlotContext as ap, ToolbarItem as aq, TrialChromeContext as ar, TrialRegion as as, UndoCapability as at, ViewportControl as au, StorageAdapter as c, LabStoreState as d, SavedSnapshot as e, StorageChange as f, TrialStateHandle as g, UndockedPanel as h, UndockedPanels as i, ViewTransform as k, Point as l, DragFeedback as m, DragDropCapability as n, LabMode as o, InstrumentList as q, InstrumentHooks as s, WorldRect as t, AnnotationMeaning as v, MarkScene as w, CaptureSource as x, CaptureOptions as y, CaptureResult as z };
+export { DEFAULT_FRAME as D, fracContains as aA, fracEncloses as aB, fracToWorld as aC, isAuto as aD, resolveLoupe as aE, roundFrac as aF, worldToFrac as aG, LOUPE_DEFAULTS as ab, annotationsFromJSON as aw, auto as ax, createAnnotationScene as ay, createAnnotationStore as az, applyCamera as c, dockPanel as l, panelKey as p, resolveFrame as r, undockPanel as u };
+export type { AnnotationStatus as $, AnnotationData as A, CaptureOptions as B, CreateLabStoreOptions as C, CaptureResult as E, AnnotationTarget as F, AnnotationsApi as G, AnnotationsCapability as H, InstrumentSerializers as I, TrialInfo as J, TrialTool as K, LayerCapability as L, Migration as M, AnnotationKind as N, Instrument as O, PaletteItem as P, LabDensity as Q, TrialContribution as R, SerializedTrial as S, TrialRecord as T, UndoStack as U, ViewportSize as V, WorldFrame as W, Annotation as X, AnnotationInit as Y, AnnotationPatch as Z, AnnotationQuery as _, LayerDescriptor as a, AnnotationStoreOptions as a0, AnnotationTargetInfo as a1, Auto as a2, CanvasCapability as a3, CanvasLayer as a4, CaptureDeps as a5, ContributionBase as a6, FracPoint as a7, FracRect as a8, HitResult as a9, LoupePoint as aH, LoupeMode as aI, IconComponent as aa, LoupeCapability as ac, LoupeDeclaration as ad, LoupeRenderArgs as ae, RegionContribution as af, RenderContext as ag, ResolvedLoupe as ah, SerializedAnnotations as ai, SidebarSection as aj, SidebarSlotContext as ak, StageCapability as al, StatusReadout as am, SystemEvent as an, ToolCapability as ao, ToolItem as ap, ToolSlotContext as aq, ToolbarItem as ar, TrialChromeContext as as, TrialRegion as at, UndoCapability as au, ViewportControl as av, WorldSpec as b, StorageAdapter as d, LabDocument as e, LabStoreState as f, SavedSnapshot as g, StorageChange as h, TrialStateHandle as i, UndockedPanel as j, UndockedPanels as k, ViewTransform as m, Point as n, DragFeedback as o, DragDropCapability as q, LabMode as s, InstrumentList as t, InstrumentHooks as v, WorldRect as w, AnnotationMeaning as x, MarkScene as y, CaptureSource as z };

package/dist/_dts/inDialog-D5ZKGjiD.d.ts

@@ -0,0 +1,23 @@
+import { ReactNode } from 'react';
+import { C as ControlRenderer } from './types-B7y8hX1D.js';
+
+/** Options for {@link inDialog}. */
+interface InDialogOptions {
+    /** What the row's button shows of the value. Defaults to a list joined with
+     *  commas, or the value itself. */
+    summary?: (value: unknown) => ReactNode;
+    /** The dialog's heading. Defaults to the row's label. */
+    title?: ReactNode;
+}
+/** The one-line summary a dialog row shows when it is given none. */
+declare function summarizeValue(value: unknown): string;
+/**
+ * Moves a control into a modal: the row becomes a button showing a summary of
+ * the value, and the button opens a dialog whose body is `body`, handed the
+ * same context a row renderer gets. For a leaf whose editor will never fit a
+ * sidebar row.
+ */
+declare function inDialog(body: ControlRenderer, opts?: InDialogOptions): ControlRenderer;
+
+export { inDialog as i, summarizeValue as s };
+export type { InDialogOptions as I };

package/dist/_dts/{index-CSJoj4LC.d.ts → index-B0--8PEM.d.ts}

@@ -1,5 +1,5 @@
-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 { C as ControlRenderer, d as ConfigRule } from './types-B7y8hX1D.js';
+import { O as Instrument, as as TrialChromeContext, R as TrialContribution, T as TrialRecord, t as InstrumentList, g as SavedSnapshot, s as LabMode, aq as ToolSlotContext, a6 as ContributionBase, ar as ToolbarItem, ap as ToolItem, aj as SidebarSection, am as StatusReadout, K as TrialTool, af as RegionContribution, ak as SidebarSlotContext } from './frac-DTRq7Xpb.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
@@ -107,7 +107,7 @@ type LabContribution<TCtx = LabChromeContext> = (ContributionBase & {
     render?: never;
 }) | (ContributionBase & {
     region: 'palette';
-    item: ToolItem;
+    item: ToolItem<TCtx>;
     render?: never;
 }) | (ContributionBase & {
     region: 'sidebar' | 'aside';
@@ -181,7 +181,8 @@ interface PaletteRegionProps<TCtx extends ToolSlotContext = TrialChromeContext>
     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. */
+ *  slot the context carries; this region only reflects it. An item carrying
+ *  `onActivate` is a command instead — it presses, and never latches. */
 declare function PaletteRegion<TCtx extends ToolSlotContext = TrialChromeContext>({ contributions, ctx, region, }: PaletteRegionProps<TCtx>): react_jsx_runtime.JSX.Element | null;
 
 /** Props for `<SidebarRegion>`. */