@weasel-js/labkit 1.6.1 → 1.7.1

package/dist/_dts/PropertyField.d-D0ndfIIt.d.ts

@@ -1,404 +0,0 @@
-import * as react from 'react';
-import { ReactNode } from 'react';
-import { ToolPrefNumberFormat, FillStyle, PaintKind } from '@weasel-js/core';
-import { S as StanceProps } from './PrefsRow.d-DFpPIeIC.js';
-
-/**
- * Display-formatter for numbers. Use this anywhere a number is shown to
- * a user. The whole point: negative values get prefixed with the real
- * MINUS SIGN (U+2212) instead of the ASCII HYPHEN-MINUS (U+002D) that
- * `toLocaleString` and template literals produce by default.
- *
- * U+2212 is the same visual width as `+` and reads as a sign rather
- * than a hyphen — columns of signed numbers align cleanly and the
- * glyph doesn't get confused with a bullet or list dash.
- */
-declare const MINUS_SIGN = "\u2212";
-/**
- * Formats a number for display, substituting {@link MINUS_SIGN} for the ASCII
- * hyphen `toLocaleString` emits. Non-finite values stringify as-is.
- */
-declare function formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
-/** One unit's conversion into the shown unit: a bare factor, or a scale that
- *  also moves zero. Structurally the kit's `UnitEntry`, kept local so this
- *  formatting helper stays free of the scene vocabulary. */
-type UnitTableEntry = number | {
-    factor: number;
-    offset?: number;
-};
-/** Suffixes a person may type, each mapped to its conversion. */
-type UnitTable = Record<string, UnitTableEntry>;
-
-/**
- * How much room a container gives its rows — gaps, padding, and field height,
- * moved together. Set on any container in the family; it reaches every
- * descendant, so an inner group can differ from the panel around it.
- */
-type PropertyDensity = 'tight' | 'normal' | 'roomy';
-/** Where an inline row's label and control sit on the row's cross axis. Set on
- *  a container to line a whole column of them up. */
-type PropertyAlign = 'start' | 'center' | 'end' | 'baseline';
-/** Metric props every container in the family takes. Both reach descendants,
- *  so the nearest container that states one wins. */
-interface PropertyMetricProps {
-    /** Room the rows get. Unset inherits from an outer container, else `normal`. */
-    density?: PropertyDensity;
-    /**
-     * Cross-axis alignment of an inline row's label and control. `baseline` sits
-     * the control on the label's first-line baseline, which is what lines a
-     * column of swatches up against labels of different heights. Unset keeps each
-     * variant's own alignment — a color row centers its label and swatch and
-     * sinks the pair to the row's bottom edge, which keeps a paired alpha track
-     * level with its neighbour.
-     */
-    align?: PropertyAlign;
-}
-/** Props for `<PropertyPanel>`. */
-interface PropertyPanelProps extends PropertyMetricProps, StanceProps {
-    title?: ReactNode;
-    /** Controls on the trailing edge of the title row — a switch, a clear
-     *  button. They sit outside the heading, so they neither take its type nor
-     *  join its accessible name. */
-    actions?: ReactNode;
-    /**
-     * Lets text inside the panel be selected and copied. A panel is chrome by
-     * default, so a drag across it moves a slider rather than painting a
-     * selection; a `debug` panel defaults to selectable, since what it shows —
-     * ids, keys, traces — is there to be copied.
-     */
-    selectable?: boolean;
-    children: ReactNode;
-    className?: string;
-}
-/**
- * A titled panel holding property rows — the sidebar container the rest of
- * this module's components fill.
- *
- * `stance` says what kind of content it holds and `tone` which of its peers it
- * is; the theme's `--wzl-panel-*` and `--wzl-stance-*` slots decide how each looks. A stanced
- * panel's title takes the row-label recipe rather than the display title.
- */
-declare function PropertyPanel({ title, actions, selectable, children, className, density, align, stance, tone, }: PropertyPanelProps): react.JSX.Element;
-/** How a property list packs its rows into two columns. */
-type PropertyListPack = 'auto-color' | 'pairs' | 'one-up';
-/** Props for `<PropertyList>`. */
-interface PropertyListProps extends PropertyMetricProps {
-    children: ReactNode;
-    className?: string;
-    /**
-     * How rows pack into the 2-column grid.
-     *   - `'auto-color'` (default): only color rows pair side-by-side; everything
-     *     else spans the full width. Right for sparse top-level panels.
-     *   - `'pairs'`: every row auto-places into the 2-column grid two-per-row.
-     *     Headers and subpanels still span the full width; wrap any other
-     *     full-width child in `<PropertySpan>`. Right for dense effect bodies.
-     *   - `'one-up'`: every row spans the full width, color rows included. Right
-     *     for a palette — a column of swatches read as a group.
-     */
-    pack?: PropertyListPack;
-}
-/**
- * Grid container for PropertyRows. Use standalone for chrome-less layouts, or
- * nest inside <PropertyPanel/> for the standard glass card.
- */
-declare const PropertyList: react.ForwardRefExoticComponent<PropertyListProps & react.RefAttributes<HTMLDivElement>>;
-/** Props for `<PropertySpan>`. */
-interface PropertySpanProps {
-    children: ReactNode;
-    className?: string;
-}
-/**
- * Wrapper that makes an arbitrary child span both columns of a
- * `<PropertyList pack="pairs">`, a `<PropertyGroup pack="pairs">` body, or a
- * `<Subpanel>`. `<PropertyRow span>` covers the row case; this covers
- * everything else a consumer puts in the grid.
- */
-declare function PropertySpan({ children, className }: PropertySpanProps): react.JSX.Element;
-/** Which control shape a row holds, which decides its intrinsic layout. */
-type PropertyRowVariant = 'default' | 'color' | 'checkbox';
-/** Whether a row's label sits above its control or beside it. */
-type PropertyRowLayout = 'block' | 'inline';
-/** Props for `<PropertyRow>`. */
-interface PropertyRowProps extends PropertyMetricProps {
-    label: ReactNode;
-    /** Right-aligned readout shown next to the label (e.g. current value). */
-    readout?: ReactNode;
-    /**
-     * Help text for the row, shown in a tooltip off an ⓘ affordance beside the
-     * label. Empty or absent renders no affordance.
-     */
-    description?: string;
-    variant?: PropertyRowVariant;
-    /**
-     * Label position relative to the control. Unset takes the variant's own
-     * orientation: `block` — label above control — for the default variant, and
-     * `inline` for the color and checkbox variants, which read as a row.
-     */
-    layout?: PropertyRowLayout;
-    /**
-     * Take the full width of the enclosing grid. Only has an effect inside a
-     * `<PropertyList pack="pairs">` or a `<Subpanel>`; elsewhere rows are already
-     * full width.
-     */
-    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. The
-     *  control is hidden — its box kept, so the row does not resize — and the
-     *  row reads out the word instead. */
-    auto?: boolean;
-    /** Given, the row's label toggles `auto` when it is clicked. Omitted, the row
-     *  can show an auto state but not change it.
-     *
-     *  The label then names that toggle, so a control passed as `children` has to
-     *  carry its own accessible name — every `<PropertyField>` does. */
-    onAutoChange?: (next: boolean) => void;
-    /**
-     * What draws the row's control. `bare` (the default) is a native input the
-     * row's stylesheet dresses; `framed` is a kit field bringing its own frame,
-     * which the row then leaves alone — see {@link PropertyFieldChrome}.
-     */
-    chrome?: PropertyFieldChrome;
-}
-/** The label-plus-control frame `<PropertyField>` draws its rows in. Use it
- *  directly for a control no field kind covers. */
-declare function PropertyRow({ label, readout, description, variant, layout, span, children, htmlFor, group, className, density, align, auto, onAutoChange, chrome, }: PropertyRowProps): react.JSX.Element;
-
-/**
- * Which controls a field is drawn with.
- *
- *   - `'bare'` (the default): native inputs the property row's own stylesheet
- *     draws — the compact controls of an inspector sidebar or a lab panel.
- *   - `'framed'`: the kit's field components, each bringing its own frame —
- *     for a surface whose row does not style its controls (`SelectionPanel`,
- *     `ToolOptionsBar`), or that needs what only they do, such as reading a
- *     unit typed into a number (`accepts`).
- *
- * The two differ only where the kit still has two widgets for one job; a
- * slider, a switch, a font picker and a paint are the same in both.
- */
-type PropertyFieldChrome = 'bare' | 'framed';
-/** One choice of an enum field. */
-interface PropertyOption<T extends string> {
-    value: T;
-    /** The option's name. A string also names its segment for a screen reader. */
-    label: ReactNode;
-    /** What a segment shows in place of `label` when the full one would not fit
-     *  — a glyph or a letter. `label` stays the accessible name. */
-    glyph?: ReactNode;
-    /** Shown but not choosable: a value the control reports and cannot author. */
-    disabled?: boolean;
-}
-/** Props every kind of field shares. */
-interface FieldBase {
-    /** The control's accessible name. A `<PropertyField>` takes it from a string
-     *  `label` when this is omitted. */
-    name?: string;
-    /** The sources the field reads disagree — a multi-selection whose nodes
-     *  differ. The control shows no value, in whatever form it has for that. */
-    mixed?: boolean;
-    /**
-     * The sources agree on holding nothing: whatever is in effect comes from a
-     * fallback further down. The control shows no chosen value rather than
-     * inventing one, since the next edit would write the invention back.
-     */
-    unset?: boolean;
-    chrome?: PropertyFieldChrome;
-    /** Class on the control element itself. */
-    className?: string;
-    /** Id for the control element, for a `<label htmlFor>` outside it. */
-    id?: string;
-}
-/** A boolean field. */
-interface PropertyBooleanFieldProps extends FieldBase {
-    kind: 'boolean';
-    /** `checkbox` (default), `switch`, or `toggle` — a one-segment pressable bar. */
-    control?: 'checkbox' | 'switch' | 'toggle';
-    /** Absent reads as off. */
-    value: boolean | undefined;
-    onChange: (next: boolean) => void;
-    /** A `toggle`'s segment content. Defaults to the first letter of `name`. */
-    glyph?: ReactNode;
-}
-/** A number field. */
-interface PropertyNumberFieldProps extends FieldBase {
-    kind: 'number';
-    /** `input` (default) for a typed number; `slider` for a track with an
-     *  editable readout, where the range matters more than the exact value. */
-    control?: 'input' | 'slider';
-    /** Absent reads as an empty field. */
-    value: number | null | undefined;
-    /**
-     * The committed value. Given `onInput` as well, it fires once a drag ends,
-     * or on blur or Enter in a typed field; on its own it fires on every move
-     * and keystroke. A `framed` typed field commits only on blur or Enter,
-     * whichever callbacks it has.
-     */
-    onChange: (next: number) => void;
-    /** The live value, fired continuously. Pass it alongside `onChange` when the
-     *  write is expensive — cheap state here, the costly work there. */
-    onInput?: (next: number) => void;
-    /** A slider's track runs 0..100 where these are omitted. */
-    min?: number;
-    max?: number;
-    step?: number;
-    /**
-     * Suffix after the value. A string becomes a dim word unit (`px`); pass JSX
-     * like `<sup>°</sup>` for a symbol. Display only — the value stays a number.
-     */
-    unit?: ReactNode;
-    /** Units a person may type into a `framed` field, each mapped to the factor
-     *  that turns it into the unit shown: `{ mm: 0.1, cm: 1 }`. */
-    accepts?: Readonly<UnitTable>;
-    /** A slider readout's display. Defaults to the value at `step`'s precision. */
-    format?: (value: number) => ReactNode;
-    /** A named display for the value: `compact` reads `2.00M`. `format` wins. */
-    notation?: ToolPrefNumberFormat;
-    placeholder?: string;
-    /** A `framed` unitless field's stepper buttons. Default `true`. */
-    steppers?: boolean;
-}
-/** A text field. */
-interface PropertyStringFieldProps extends FieldBase {
-    kind: 'string';
-    control?: 'input' | 'textarea';
-    /** Absent reads as an empty field. */
-    value: string | null | undefined;
-    /**
-     * The committed text. On its own it fires on every keystroke. Given
-     * `onInput` as well, the field drafts: `onInput` gets each keystroke and
-     * this fires once, on blur or Enter, and only if the text changed.
-     */
-    onChange: (next: string) => void;
-    onInput?: (next: string) => void;
-    placeholder?: string;
-    maxLength?: number;
-}
-/** A choice among fixed options. */
-interface PropertyEnumFieldProps<T extends string = string> extends FieldBase {
-    kind: 'enum';
-    /**
-     * `select` (default) is a dropdown. `radio` and `toggle` show every option
-     * at once — a radio group chooses, and a toggle is a row of pressable
-     * segments. Drawn `bare`, both are segments.
-     */
-    control?: 'select' | 'radio' | 'toggle';
-    /** Absent, or not one of `options`, chooses nothing. */
-    value: T | undefined;
-    options: ReadonlyArray<PropertyOption<T>>;
-    onChange: (next: T) => void;
-    /** Shown while no option is chosen. Defaults to "Choose option…". */
-    placeholder?: string;
-}
-/** A single color. */
-interface PropertyColorFieldProps extends FieldBase {
-    kind: 'color';
-    /** `#rrggbb`, or `#rrggbbaa` when `alpha` is `true`. */
-    value: string | undefined;
-    /**
-     * The committed color. `bare`: given `onInput` as well, it fires once the
-     * picker closes; on its own it fires on every move. `framed`: it fires once
-     * per gesture, whichever callbacks it has.
-     */
-    onChange: (next: string) => void;
-    onInput?: (next: string) => void;
-    /**
-     * Offer an opacity track. `true` keeps the alpha in `value` as `#rrggbbaa`;
-     * a number is the 0..1 alpha held apart from it, reported through
-     * `onAlphaChange` / `onAlphaInput`.
-     */
-    alpha?: boolean | number;
-    onAlphaChange?: (next: number) => void;
-    onAlphaInput?: (next: number) => void;
-    /** Draw the opacity track inert, for a consumer that drops alpha. */
-    alphaDisabled?: boolean;
-}
-/** A whole paint: a solid, a gradient, a pattern, or none. */
-interface PropertyPaintFieldProps extends FieldBase {
-    kind: 'paint';
-    /** `swatch` (default) opens the editor in a popover, for a narrow slot;
-     *  `inline` draws the kind bar and its editor in place. */
-    control?: 'swatch' | 'inline';
-    /** `null` is an explicit "no paint"; `undefined` is nothing to show. */
-    value: FillStyle | null | undefined;
-    onChange: (next: FillStyle | null) => void;
-    onInput?: (next: FillStyle | null) => void;
-    /** Offer "None". Default `true`. */
-    allowNone?: boolean;
-    /** Restrict the kinds offered. Default: every registered kind. */
-    kinds?: readonly PaintKind[];
-}
-/** A font family, picked from the live font registry. */
-interface PropertyFontFamilyFieldProps extends FieldBase {
-    kind: 'font-family';
-    value: string | undefined;
-    onChange: (next: string) => void;
-    /** The weight and slant the family is drawn at, so the picker names the
-     *  variant that will actually paint. */
-    weight?: number;
-    fontStyle?: 'normal' | 'italic';
-}
-/**
- * One field for {@link PropertyControl} and {@link PropertyField}, keyed by
- * `kind`.
- */
-type PropertyControlProps<T extends string = string> = PropertyBooleanFieldProps | PropertyNumberFieldProps | PropertyStringFieldProps | PropertyEnumFieldProps<T> | PropertyColorFieldProps | PropertyPaintFieldProps | PropertyFontFamilyFieldProps;
-/** Row props {@link PropertyField} adds to the field it draws. */
-interface PropertyFieldRowProps extends PropertyMetricProps {
-    label: ReactNode;
-    /**
-     * Text beside the label. On a slider it replaces the editable readout —
-     * use it when the row is not showing a number a caller could type back,
-     * such as an auto row's `auto`.
-     */
-    readout?: ReactNode;
-    description?: string;
-    layout?: PropertyRowLayout;
-    /** 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 the row's label — see `<PropertyRow onAutoChange>`. */
-    onAutoChange?: (next: boolean) => void;
-    /** Class on the row. `controlClassName` reaches the control. */
-    rowClassName?: string;
-    controlClassName?: string;
-}
-/** Props for {@link PropertyField}: one field, and the row around it. */
-type PropertyFieldProps<T extends string = string> = PropertyFieldRowProps & DistributiveOmit<PropertyControlProps<T>, 'className' | 'id'>;
-type DistributiveOmit<U, K extends PropertyKey> = U extends unknown ? Omit<U, K> : never;
-/**
- * A labeled settings row for one field, its control chosen by `kind` (and
- * `control`): `<PropertyField kind="number" control="slider" label="Blur" …>`.
- *
- * The row is a {@link PropertyRow}; the control is the one
- * {@link PropertyControl} draws for the same props. Every schema-driven
- * settings surface in the kit — `ControlPanel`, `PrefsForm`, `SelectionPanel`
- * — draws its built-in kinds through that one mapping, so a kind's control
- * is decided once.
- *
- * Callbacks follow the field's shape: a discrete control (a box, a choice)
- * reports each pick; a continuous or typed one reports every change through
- * `onChange` alone, or splits them into live `onInput` and settled
- * `onChange` when given both. `mixed` and `unset` show a field whose sources
- * disagree, or agree on holding nothing.
- */
-declare function PropertyField<T extends string = string>(props: PropertyFieldProps<T>): react.JSX.Element;
-/**
- * The control for one field, with no row around it — for a cell that shares
- * a row with others, or a surface that draws its own row. Keyed by `kind`
- * (and `control`), the same mapping {@link PropertyField} draws.
- *
- * A slider brings its readout beside the track. Several elements come back
- * as siblings rather than wrapped, so the surrounding row lays them out.
- */
-declare function PropertyControl<T extends string = string>(typed: PropertyControlProps<T>): react.JSX.Element;
-
-export { MINUS_SIGN as M, PropertyControl as b, PropertyField as d, PropertyList as f, PropertyPanel as i, PropertyRow as k, PropertySpan as o, formatNumber as s };
-export type { PropertyMetricProps as P, PropertyListPack as a, PropertyControlProps as c, PropertyFieldProps as e, PropertyListProps as g, PropertyOption as h, PropertyPanelProps as j, PropertyRowLayout as l, PropertyRowProps as m, PropertyRowVariant as n, PropertySpanProps as p, PropertyAlign as q, PropertyDensity as r };