@ambientcss/components 2.1.0 → 3.0.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { PropsWithChildren, CSSProperties, HTMLAttributes, ButtonHTMLAttributes } from 'react';
+import * as react from 'react';
+import { PropsWithChildren, CSSProperties, HTMLAttributes, ReactNode, PointerEvent, ButtonHTMLAttributes, KeyboardEvent } from 'react';
 
 type AmbientTheme = {
     lightX?: number;
@@ -18,9 +19,30 @@ type AmbientProviderProps = PropsWithChildren<{
 }>;
 declare function AmbientProvider({ children, className, style, theme }: AmbientProviderProps): react_jsx_runtime.JSX.Element;
 
+/** The grounded surface finishes from @ambientcss/css.
+ *
+ *  Lives on parts and presets, never on a mechanism: which element a
+ *  material belongs on is a fact about a particular control's construction,
+ *  and a mechanism cannot know that once the parts are yours.
+ *
+ *  `brushed`, `brushed-round` and `blasted` are micro-relief materials: they
+ *  paint their grain into BOTH of the host's pseudo-elements, so a part that
+ *  already spends one of its own has to give them an inner layer rather than
+ *  wear them directly. `ButtonCap` is the only part in this package that does.
+ *
+ *  `brushed-round` is the same aluminium as `brushed` with the grain spun
+ *  round the element's centre, so it belongs on round faces — a knob cap, a
+ *  round button — where the centre it turns about is a real feature. */
+type AmbientMaterial = "matte" | "shiny" | "glass" | "brushed" | "brushed-round" | "blasted";
+
 interface AmbientPanelProps extends HTMLAttributes<HTMLDivElement> {
-    material?: "matte" | "shiny" | "glass";
+    material?: AmbientMaterial;
 }
+/** A panel is a plain surface, so it can wear any finish directly: it spends
+ *  neither pseudo-element of its own, which is what the two micro-relief
+ *  materials need. Their grain paints below the panel's children, and their
+ *  `overflow: hidden` clips whatever hangs outside it — a control's drop
+ *  shadow at the very edge included. */
 declare function AmbientPanel({ className, material, ...props }: AmbientPanelProps): react_jsx_runtime.JSX.Element;
 
 type AmbientRackGap = "tight" | "normal" | "loose";
@@ -33,66 +55,741 @@ interface AmbientRackProps extends HTMLAttributes<HTMLDivElement> {
 }
 declare function AmbientRack({ className, gap, direction, ...props }: AmbientRackProps): react_jsx_runtime.JSX.Element;
 
+/** The four frames every control renders, in paint order.
+ *
+ *  - `panel`    static, behind the control, allowed to overflow its box
+ *  - `base`     static, the control's own footprint
+ *  - `actuator` the moving part: the frame the control transforms
+ *  - `fixture`  static, above the actuator
+ *
+ *  A part dropped into a frame is ordinary markup. The control moves the
+ *  frame; the part only has to look like something. */
+type ControlParts = {
+    panel?: ReactNode | undefined;
+    base?: ReactNode | undefined;
+    actuator?: ReactNode | undefined;
+    fixture?: ReactNode | undefined;
+};
+type FrameName = keyof ControlParts;
+/** `"sm" | "md" | "lg"` picks a size from the family's table; any other
+ *  string is used as a CSS length for `--ambx-size`. */
+type ControlSize = "sm" | "md" | "lg" | (string & {});
+/** How the actuator moves to a new position.
+ *
+ *  - `follow` 1:1 with the pointer, no transition — right while dragging
+ *  - `ease`   transitions, right for keyboard and click-to-set
+ *  - `snap`   instant, for a detented control that should read as clicking
+ *
+ *  The default is contextual: follow while `data-dragging` is on the root,
+ *  ease otherwise. That needs no JS — see `.ambx-control` in styles.css. */
+type ControlAnimate = "auto" | "follow" | "ease" | "snap";
+/** What a part can read, via `useControlState()`. The same values are on
+ *  the control root as custom properties, which are canonical; this is a
+ *  typed view of them for parts that genuinely need JS. */
+type ControlState = {
+    /** The raw value. Booleans arrive as 0/1, selections as the index. */
+    value: number;
+    min: number;
+    max: number;
+    /** Normalised position, 0-1. */
+    percent: number;
+    /** Degrees clockwise from 12 o'clock. 0 for non-rotary controls. */
+    angle: number;
+    /** Sweep origin and extent in degrees. 0 for non-rotary controls. */
+    travelStart: number;
+    travelSweep: number;
+    /** Rest positions along the travel; 0 means continuous. */
+    detents: number;
+    dragging: boolean;
+    disabled: boolean;
+    atMin: boolean;
+    atMax: boolean;
+};
+
+/** A transport key, a latching mute and an auto-repeating nudge button are
+ *  the same object with three state machines and identical paint. */
+type PressMode = "momentary" | "toggle" | "repeat";
+type UsePressOptions = {
+    mode?: PressMode | undefined;
+    /** `toggle` mode only: the pressed-in state. */
+    value?: boolean | undefined;
+    defaultValue?: boolean | undefined;
+    onChange?: ((next: boolean) => void) | undefined;
+    /** Fires once per activation, and repeatedly in `repeat` mode. */
+    onPress?: (() => void) | undefined;
+    /** `repeat` mode: delay before repeating starts, then its interval. */
+    repeatDelay?: number | undefined;
+    repeatInterval?: number | undefined;
+    disabled?: boolean | undefined;
+};
+declare function usePress(options: UsePressOptions): {
+    state: ControlState;
+    rootProps: {
+        onPointerDown: (event: PointerEvent<HTMLButtonElement>) => void;
+        onPointerUp: () => void;
+        onPointerCancel: () => void;
+        onPointerLeave: () => void;
+        onClick: () => void;
+        type: "button";
+        disabled: boolean;
+        "aria-pressed": boolean | undefined;
+        style: CSSProperties;
+        "data-pressed": string | undefined;
+        "data-mode": PressMode;
+    };
+    pressed: boolean;
+    on: boolean;
+    setOn: (next: boolean) => void;
+};
+
+type AmbientPressProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "value" | "defaultValue" | "type"> & UsePressOptions & {
+    parts?: ControlParts | undefined;
+    size?: ControlSize | undefined;
+};
+/** A key that sinks under a finger, with no appearance of its own.
+ *
+ *  Its frames are `display: contents` markers rather than boxes, because a
+ *  button is sized by its cap: the width is `min-width` plus the legend.
+ *  Wrapping the cap in a positioned frame would collapse the control. */
+declare function AmbientPress({ parts, size, className, mode, value, defaultValue, onChange, onPress, repeatDelay, repeatInterval, disabled, children, ...rest }: AmbientPressProps): react_jsx_runtime.JSX.Element;
+
+/** How pointer movement becomes value.
+ *
+ *  These are three different mappings, not one with a parameter, and the
+ *  library was ambiguous about which it implemented: the code did `angle`
+ *  while knob.md documented `drag`. Naming it makes that drift impossible.
+ *
+ *  - `drag`  pointer DISTANCE -> value delta. The v3 default: it is what the
+ *            docs always described, what most audio software does, and the
+ *            only one that behaves on touch, where a finger covers the knob.
+ *  - `angle` pointer POSITION -> absolute angle -> value. Needs a dead zone,
+ *            and needs a sweep under a full turn to be unambiguous.
+ *  - `delta` accumulated angular change. The endless-encoder mapping: no
+ *            ends, no dead zone, and the value may wrap independently of
+ *            where the pointer happens to be. */
+type RotaryInput = "drag" | "angle" | "delta";
+/** The pot's travel in degrees clockwise from 12 o'clock. A bare number is
+ *  a sweep centred on 12 o'clock, so `270` is the default 8-to-4 pot. */
+type RotaryTravel = number | {
+    start: number;
+    sweep: number;
+};
+type UseRotaryOptions = {
+    value?: number | undefined;
+    defaultValue?: number | undefined;
+    min?: number | undefined;
+    max?: number | undefined;
+    /** Quantises the VALUE. `0` leaves it continuous. */
+    step?: number | undefined;
+    /** Quantises the TRAVEL: rest positions along the arc. Defaults to the
+     *  step grid, but the two are independent — an endless encoder can have
+     *  24 detents per turn while its value stays continuous. */
+    detents?: number | undefined;
+    travel?: RotaryTravel | undefined;
+    input?: RotaryInput | undefined;
+    /** Pixels of drag for one full range, in `drag` mode. */
+    dragDistance?: number | undefined;
+    /** `delta` mode only: run past the ends and come round again. */
+    wrap?: boolean | undefined;
+    disabled?: boolean | undefined;
+    onChange?: ((next: number) => void) | undefined;
+};
+declare function useRotary(options: UseRotaryOptions): {
+    state: ControlState;
+    rootProps: {
+        onPointerDown: (event: PointerEvent<HTMLDivElement>) => void;
+        onPointerMove: (event: PointerEvent<HTMLDivElement>) => void;
+        onPointerUp: () => void;
+        onPointerCancel: () => void;
+        onKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
+        ref: react.RefObject<HTMLDivElement | null>;
+        role: "slider";
+        "aria-valuemin": number;
+        "aria-valuemax": number;
+        "aria-valuenow": number;
+        "aria-orientation": "vertical";
+        "aria-disabled": true | undefined;
+        tabIndex: number;
+        style: CSSProperties;
+    };
+    setValue: (next: number) => void;
+};
+
+/** The five control families a kit can dress. */
+type ControlFamily = "rotary" | "travel" | "press" | "latch" | "bank";
+/** What a preset hands its kit: the look options the caller asked for.
+ *
+ *  Deliberately loose. Look props are *kit vocabulary* — `knurling` and
+ *  `markers` are words the grounded kit made up — so a kit reads the keys it
+ *  understands and ignores the rest, exactly as a stylesheet that never
+ *  implemented a class simply does not react to it. See `looks` below for
+ *  how that stays honest rather than silent. */
+type KitLook = Record<string, unknown>;
+/** A dressed control: what goes in the frames, and what the root wears.
+ *
+ *  The class comes from the kit rather than the preset because it is part of
+ *  the look — `.amb-knob` carries the grounded knob's own token table, and a
+ *  kit that replaces the parts has no use for it. */
+type KitDress = {
+    parts: ControlParts;
+    className?: string | undefined;
+};
+/** Presentation defaults a visual identity may legitimately set.
+ *
+ *  Narrow on purpose: a kit says how its controls should *feel* to turn, not
+ *  what they are worth. Anything touching value, range or handlers stays with
+ *  the caller. */
+type KitDefaults = {
+    rotary?: {
+        travel?: RotaryTravel;
+        input?: RotaryInput;
+        animate?: ControlAnimate;
+    } | undefined;
+    travel?: {
+        animate?: ControlAnimate;
+    } | undefined;
+    latch?: {
+        animate?: ControlAnimate;
+    } | undefined;
+};
+type ControlKit = {
+    name: string;
+    rotary?: ((look: KitLook) => KitDress) | undefined;
+    travel?: ((look: KitLook) => KitDress) | undefined;
+    press?: ((look: KitLook) => KitDress) | undefined;
+    latch?: ((look: KitLook) => KitDress) | undefined;
+    bank?: ((look: KitLook) => KitDress) | undefined;
+    defaults?: KitDefaults | undefined;
+    /** Look keys each family honours. Used only to warn in development when a
+     *  caller passes a prop the active kit is going to drop on the floor —
+     *  the one real cost of letting look props pass through untyped. */
+    looks?: Partial<Record<ControlFamily, readonly string[]>> | undefined;
+};
+/** Dress every control below this point in `kit`.
+ *
+ *  A kit is a plain object, so shipping one is shipping a module: no
+ *  registry, no lifecycle, nothing to initialise. A kit that leaves a family
+ *  undefined falls through to the default, which is what a real third-party
+ *  kit will do for most of them. */
+declare function AmbientKitProvider({ kit, children }: PropsWithChildren<{
+    kit: ControlKit;
+}>): react_jsx_runtime.JSX.Element;
+declare function useKit(): ControlKit | null;
+/** Resolve a family's dressing: the active kit if it dresses this family,
+ *  otherwise the fallback the preset was built around. */
+declare function useDress<F extends ControlFamily>(family: F, look: KitLook, fallback: (look: KitLook) => KitDress): {
+    dress: KitDress;
+    defaults: F extends keyof KitDefaults ? KitDefaults[F] : undefined;
+};
+
 type AmbientButtonShape = "pill" | "round" | "square";
 type AmbientButtonSize = "sm" | "md" | "lg";
-interface AmbientButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-    material?: "matte" | "shiny" | "glass";
-    shape?: AmbientButtonShape;
-    size?: AmbientButtonSize;
-}
-declare function AmbientButton({ className, children, material, shape, size, ...props }: AmbientButtonProps): react_jsx_runtime.JSX.Element;
+type AmbientButtonProps = Omit<AmbientPressProps, "parts" | "size"> & {
+    material?: AmbientMaterial | undefined;
+    shape?: AmbientButtonShape | undefined;
+    size?: AmbientButtonSize | undefined;
+    /** Look options in the active kit's vocabulary. */
+    look?: KitLook | undefined;
+};
+/** A key cap seated in a clearance well. */
+declare function AmbientButton({ className, children, look, material, shape, size, ...rest }: AmbientButtonProps): react_jsx_runtime.JSX.Element;
+
+type UseLatchOptions = {
+    value?: boolean | undefined;
+    defaultValue?: boolean | undefined;
+    onChange?: ((next: boolean) => void) | undefined;
+    disabled?: boolean | undefined;
+};
+/** A two-position travel. Kept distinct from Press because its actuator
+ *  genuinely slides rather than sinking, and because its ARIA is
+ *  `role="switch"` — a switch is a state, not an action. */
+declare function useLatch(options: UseLatchOptions): {
+    state: ControlState;
+    rootProps: {
+        onClick: () => void;
+        type: "button";
+        role: "switch";
+        "aria-checked": boolean;
+        disabled: boolean;
+        style: CSSProperties;
+    };
+    on: boolean;
+    setOn: (next: boolean) => void;
+};
+
+type AmbientLatchProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "value" | "defaultValue" | "type"> & UseLatchOptions & {
+    parts?: ControlParts | undefined;
+    size?: ControlSize | undefined;
+    animate?: ControlAnimate | undefined;
+    label?: ReactNode | undefined;
+};
+/** A two-position slide, with no appearance of its own. The control IS the
+ *  track: its actuator is a pill-sized frame that travels across it, which
+ *  is why anything sitting beside a switch — a lamp, a legend — belongs to
+ *  whatever composes it rather than to the switch. */
+declare function AmbientLatch({ parts, size, animate, label, className, value, defaultValue, onChange, disabled, children, ...rest }: AmbientLatchProps): react_jsx_runtime.JSX.Element;
 
 type AmbientSwitchSize = "sm" | "md" | "lg";
-type AmbientSwitchProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChange"> & {
-    checked?: boolean;
-    defaultChecked?: boolean;
-    onCheckedChange?: (checked: boolean) => void;
-    size?: AmbientSwitchSize;
-    label?: string;
-    /** Show a small LED indicator that lights up when the switch is on. Pass `true` for default green or a CSS color string. */
-    led?: boolean | string;
-};
-declare function AmbientSwitch({ className, checked, defaultChecked, onCheckedChange, onClick, size, label, led, children, ...props }: AmbientSwitchProps): react_jsx_runtime.JSX.Element;
-
-type AmbientKnobVariant = "dot" | "line" | "flute" | "cap" | "wheel";
+type AmbientSwitchProps = Omit<AmbientLatchProps, "parts" | "size"> & {
+    size?: AmbientSwitchSize | undefined;
+    /** A lamp above the switch. `true` for the scene's own colour, or any
+     *  CSS colour string. */
+    led?: boolean | string | undefined;
+    /** Look options in the active kit's vocabulary. */
+    look?: KitLook | undefined;
+};
+/** A pill sliding in a dark stadium recess, with an optional lamp above.
+ *
+ *  The lamp is mounted beside the switch rather than inside it: the latch
+ *  control IS the track, so anything that is neither track nor pill belongs
+ *  to whatever composes them. That means the preset has to hold the state —
+ *  the lamp and the pill read the same boolean, and only their common
+ *  parent can see both.
+ */
+declare function AmbientSwitch({ size, led, label, look, value, defaultValue, onChange, animate, className, ...rest }: AmbientSwitchProps): react_jsx_runtime.JSX.Element;
+
+type BankOption = {
+    value: string;
+    /** Key legend — a numeral in the referent, but any node works. */
+    label?: ReactNode | undefined;
+    /** Accessible name, and the hover title. Needed whenever the legend is a
+     *  glyph or an icon: a key reading "*" has no name otherwise. */
+    ariaLabel?: string | undefined;
+    /** Overrides the bank's lamp colour for this key only. */
+    color?: string | undefined;
+    disabled?: boolean | undefined;
+};
+type BankOrientation = "vertical" | "horizontal";
+type UseBankOptions = {
+    options: BankOption[];
+    value?: string | string[] | undefined;
+    defaultValue?: string | string[] | undefined;
+    onChange?: ((value: string | string[]) => void) | undefined;
+    /** Let more than one lamp be lit at a time. */
+    multiple?: boolean | undefined;
+    orientation?: BankOrientation | undefined;
+    disabled?: boolean | undefined;
+};
+/** N presses sharing a selection model.
+ *
+ *  The roving tabindex, the radiogroup-versus-checkbox-group keyboard
+ *  difference and the selection-follows-focus rule are the reason this
+ *  mechanism exists: they are the part nobody should have to re-derive in
+ *  order to change what a key looks like. */
+declare function useBank(options: UseBankOptions): {
+    selected: string[];
+    select: (option: BankOption | undefined) => void;
+    rootProps: {
+        role: "group" | "radiogroup";
+        "aria-orientation": BankOrientation | undefined;
+        "aria-disabled": true | undefined;
+        "data-orientation": BankOrientation;
+        "data-disabled": string | undefined;
+    };
+    keyProps: (option: BankOption, index: number) => {
+        key: string;
+        type: "button";
+        ref: (node: HTMLButtonElement | null) => void;
+        role: "checkbox" | "radio";
+        "aria-checked": boolean;
+        "aria-label": string | undefined;
+        title: string | undefined;
+        disabled: boolean;
+        tabIndex: number;
+        "data-on": string | undefined;
+        onClick: () => void;
+        onKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => void;
+    };
+};
+
+type AmbientBankProps = Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> & UseBankOptions & {
+    /** Parts applied to every key. The bank's own frames go in `parts`. */
+    keyParts?: ControlParts | undefined;
+    parts?: ControlParts | undefined;
+    size?: ControlSize | undefined;
+    /** Lamp colour. Defaults to the scene's `--amb-highlight-color`. */
+    color?: string | undefined;
+    label?: ReactNode | undefined;
+    /** Per-key override, for a bank whose keys are not interchangeable. */
+    renderKey?: ((option: BankOption, on: boolean) => ReactNode) | undefined;
+};
+/** N keys sharing a selection model, with no appearance of its own.
+ *
+ *  Parts apply per key rather than once, because that is what a bank is.
+ *  The focusable element is the key `<button>`, which this mechanism
+ *  renders — your parts go inside it, which is why the presentational-parts
+ *  rule still holds here. */
+declare function AmbientBank({ options, keyParts, parts, size, color, label, renderKey, className, style, value, defaultValue, onChange, multiple, orientation, disabled, ...rest }: AmbientBankProps): react_jsx_runtime.JSX.Element;
+
+type AmbientSelectOption = BankOption;
+type AmbientSelectOrientation = BankOrientation;
+type AmbientSelectSize = "sm" | "md" | "lg";
+type AmbientSelectProps = Omit<AmbientBankProps, "keyParts" | "parts" | "size"> & {
+    size?: AmbientSelectSize | undefined;
+    /** Look options in the active kit's vocabulary. */
+    look?: KitLook | undefined;
+};
+/**
+ * A bank of lamp-lit keys in a shared rail — the hardware idiom for a
+ * mode selector, where the state is a lamp rather than a mark.
+ *
+ * Three physical layers per key, and the ORDER is the whole trick: the key
+ * itself is the pocket floor, the lens is a disc lying on it, and the cap
+ * is a translucent diffuser over both. The cap is `.amb-mat-glass`, so its
+ * backdrop-filter blurs the lens behind it — which is why the lens goes in
+ * the `base` frame and the cap in `actuator`, and why swapping them would
+ * put out every lamp.
+ */
+declare function AmbientSelect({ size, look, className, ...rest }: AmbientSelectProps): react_jsx_runtime.JSX.Element;
+
+type AmbientRotaryProps = Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> & UseRotaryOptions & {
+    parts?: ControlParts | undefined;
+    size?: ControlSize | undefined;
+    animate?: ControlAnimate | undefined;
+    label?: ReactNode | undefined;
+};
+/** A rotary mechanism with no appearance of its own.
+ *
+ *  It owns the value, the three pointer mappings, the sweep, the keyboard
+ *  contract and the ARIA; what it looks like is entirely the `parts` you
+ *  give it. There is deliberately no `material` prop: which element a
+ *  material belongs on is a fact about a particular knob's construction —
+ *  on the clipped face when it is knurled, on the body when it is not —
+ *  and a mechanism cannot know that once the body is yours. Presets carry
+ *  `material`, because a preset knows its own parts. */
+declare function AmbientRotary({ parts, size, animate, label, className, value, defaultValue, min, max, step, detents, travel, input, dragDistance, wrap, disabled, onChange, ...rest }: AmbientRotaryProps): react_jsx_runtime.JSX.Element;
+
+/** Printed scale dots on the panel around the knob: the arc's two ends, the
+ *  full graduated ring, or nothing. */
+type AmbientKnobMarkers = "none" | "ends" | "full";
+/** The pointer riding the rotating face: a radial bar or an offset dot. */
+type AmbientKnobIndicator = "rectangle" | "circle";
 type AmbientKnobSize = "sm" | "md" | "lg";
-type AmbientKnobProps = Omit<HTMLAttributes<HTMLDivElement>, "onChange"> & {
-    value: number;
-    min?: number;
-    max?: number;
-    step?: number;
-    label?: string;
-    material?: "matte" | "shiny" | "glass";
-    variant?: AmbientKnobVariant;
-    size?: AmbientKnobSize;
-    onChange?: (nextValue: number) => void;
+type AmbientKnobProps = Omit<AmbientRotaryProps, "parts" | "size"> & {
+    material?: AmbientMaterial | undefined;
+    /** Ribbed grip around the rotating body. Off gives a smooth turned body. */
+    knurling?: boolean | undefined;
+    /** The grip ring's own colour, for a two-tone knob — any CSS colour, read
+     *  as an albedo, so it still takes the scene's light rather than being
+     *  painted flat. Unset, the ring is the same material as the cap. */
+    knurlColor?: string | undefined;
+    markers?: AmbientKnobMarkers | undefined;
+    indicator?: AmbientKnobIndicator | undefined;
+    size?: AmbientKnobSize | undefined;
+    /** Look options in another kit's vocabulary.
+     *
+     *  The five props above are the *grounded* kit's words. A kit that dresses
+     *  knobs differently has its own, and they arrive here rather than as
+     *  loose props so the common path stays typed and a misspelt `knurling`
+     *  is still a compile error. Kits usually ship a preset of their own that
+     *  types this properly — see `ConsoleKnob`. */
+    look?: KitLook | undefined;
+};
+/**
+ * The rotary preset: `AmbientRotary` wearing whatever the active kit says a
+ * knob looks like, and the grounded hardware knob when no kit is set.
+ */
+declare function AmbientKnob({ material, knurling, knurlColor, markers, indicator, look, size, className, travel, input, animate, ...rest }: AmbientKnobProps): react_jsx_runtime.JSX.Element;
+
+type TravelOrientation = "horizontal" | "vertical";
+type UseTravelOptions = {
+    value?: number | undefined;
+    defaultValue?: number | undefined;
+    min?: number | undefined;
+    max?: number | undefined;
+    step?: number | undefined;
+    detents?: number | undefined;
+    orientation?: TravelOrientation | undefined;
+    /** Flip which end of the axis is `min`. */
+    invert?: boolean | undefined;
+    disabled?: boolean | undefined;
+    onChange?: ((next: number) => void) | undefined;
+};
+/** A value riding a straight track.
+ *
+ *  One mechanism behind both the slider and the fader, which before v3 were
+ *  the same file twice with X and Y swapped. The only real difference is
+ *  which axis the pointer reads — and which end is `min`, where the two
+ *  disagree for a physical reason rather than a stylistic one: a horizontal
+ *  track runs min-at-the-left, and an upright one runs min-at-the-bottom,
+ *  because that is how a fader is built. Both are the default here, so
+ *  neither preset has to ask. */
+declare function useTravel(options: UseTravelOptions): {
+    state: ControlState;
+    rootProps: {
+        onPointerDown: (event: PointerEvent<HTMLDivElement>) => void;
+        onPointerMove: (event: PointerEvent<HTMLDivElement>) => void;
+        onPointerUp: () => void;
+        onPointerCancel: () => void;
+        onKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
+        ref: react.RefObject<HTMLDivElement | null>;
+        role: "slider";
+        "aria-valuemin": number;
+        "aria-valuemax": number;
+        "aria-valuenow": number;
+        "aria-orientation": TravelOrientation;
+        "aria-disabled": true | undefined;
+        tabIndex: number;
+        style: CSSProperties;
+        "data-orientation": TravelOrientation;
+    };
+    setValue: (next: number) => void;
+};
+
+type AmbientTravelProps = Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> & UseTravelOptions & {
+    parts?: ControlParts | undefined;
+    size?: ControlSize | undefined;
+    animate?: ControlAnimate | undefined;
+    label?: ReactNode | undefined;
 };
-declare function AmbientKnob({ value, min, max, step, label, material, variant, size, onChange, className, ...props }: AmbientKnobProps): react_jsx_runtime.JSX.Element;
+/** A value on a straight track, with no appearance of its own. */
+declare function AmbientTravel({ parts, size, animate, label, className, value, defaultValue, min, max, step, detents, orientation, invert, disabled, onChange, ...rest }: AmbientTravelProps): react_jsx_runtime.JSX.Element;
 
 type AmbientFaderSize = "sm" | "md" | "lg";
-type AmbientFaderProps = Omit<HTMLAttributes<HTMLDivElement>, "onChange"> & {
-    value: number;
-    min?: number;
-    max?: number;
-    step?: number;
-    label?: string;
-    material?: "matte" | "shiny" | "glass";
-    size?: AmbientFaderSize;
-    onChange?: (nextValue: number) => void;
+type AmbientFaderProps = Omit<AmbientTravelProps, "parts" | "size" | "orientation"> & {
+    material?: AmbientMaterial | undefined;
+    size?: AmbientFaderSize | undefined;
+    /** Look options in the active kit's vocabulary. */
+    look?: KitLook | undefined;
 };
-declare function AmbientFader({ value, min, max, step, label, material, size, onChange, className, ...props }: AmbientFaderProps): react_jsx_runtime.JSX.Element;
+/** A pill cap on a stem, riding an upright slot. Min is at the bottom,
+ *  which `AmbientTravel` already does for a vertical track. */
+declare function AmbientFader({ material, look, size, animate, className, ...rest }: AmbientFaderProps): react_jsx_runtime.JSX.Element;
 
 type AmbientSliderSize = "sm" | "md" | "lg";
-type AmbientSliderProps = Omit<HTMLAttributes<HTMLDivElement>, "onChange"> & {
-    value: number;
-    min?: number;
-    max?: number;
-    step?: number;
-    label?: string;
-    material?: "matte" | "shiny" | "glass";
-    size?: AmbientSliderSize;
-    onChange?: (nextValue: number) => void;
+type AmbientSliderProps = Omit<AmbientTravelProps, "parts" | "size" | "orientation"> & {
+    material?: AmbientMaterial | undefined;
+    size?: AmbientSliderSize | undefined;
+    /** Look options in the active kit's vocabulary. */
+    look?: KitLook | undefined;
+};
+/** A domed disc gliding over a shallow concave channel. */
+declare function AmbientSlider({ material, look, size, animate, className, ...rest }: AmbientSliderProps): react_jsx_runtime.JSX.Element;
+
+/** The Blender-grounded hardware look: the default every preset falls back to. */
+declare const groundedKit: ControlKit;
+
+declare const consoleKit: ControlKit;
+type ConsoleKnobProps = Omit<AmbientKnobProps, "look" | "material" | "knurling" | "knurlColor" | "markers" | "indicator"> & {
+    /** The accent centre mark printed above the knob. */
+    mark?: boolean | undefined;
+    /** The −/+ legends at the ends of the travel. */
+    legend?: boolean | undefined;
+};
+declare function ConsoleKnob({ mark, legend, ...rest }: ConsoleKnobProps): react_jsx_runtime.JSX.Element;
+type ConsoleToggleProps = Omit<AmbientSwitchProps, "look">;
+declare function ConsoleToggle(props: ConsoleToggleProps): react_jsx_runtime.JSX.Element;
+
+/** The knob's base: a flat face housed in a circular groove.
+ *
+ *  Two elements, because they are two pieces of the panel: the groove is the
+ *  cut, and the face is the flat disc sitting in it, showing the ring of the
+ *  cut around itself. Neither carries `.ambient` — the face has no body, so
+ *  there is no edge to cut and nothing to cast, and every cue that reads as
+ *  depth here belongs either to the walls of the housing or to the bar
+ *  standing on the face.
+ *
+ *  It sits in the `base` frame, so it does not turn. A plain disc looks the
+ *  same at every angle, and leaving it still keeps the scene's light on it
+ *  untouched — only the bar has to do the work below. */
+declare function ConsoleWell({ className }: {
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+/** The actuator: a cuboid bar lying across the disc on its diameter.
+ *
+ *  Two spans, and the nesting is load-bearing. The bar rides the rotating
+ *  actuator frame, so a chamfer highlight painted from the inherited light
+ *  would turn with it and put the lit edge on the wrong side of the screen
+ *  at half the angles. The fix is to rotate the LIGHT the other way: the
+ *  outer span captures the scene's light vector, the inner one re-states it
+ *  in the frame's own turned coordinates, so the bright edge and the drop
+ *  shadow both stay put on screen while the bar sweeps under them.
+ *
+ *  It has to be two elements because a custom property cannot read itself —
+ *  `--amb-light-x: calc(var(--amb-light-x) ...)` is a cycle, which resolves
+ *  to invalid at computed-value time and takes the whole `box-shadow`
+ *  composite down with it, silently. */
+declare function ConsoleBar({ className }: {
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+/** Panel graphics around the knob: the accent centre mark above it, and the
+ *  −/+ legends at the ends of the travel. Both sit outside the knob's own
+ *  box, which is what the `panel` frame is for. */
+declare function ConsoleMarks({ mark, legend, className }: {
+    mark?: boolean | undefined;
+    legend?: boolean | undefined;
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+/** The toggle's track: a pill groove that fills with the accent as the
+ *  switch travels.
+ *
+ *  A pure-CSS part — it reads `--ambx-percent` off the control root and
+ *  mixes its own colour from it, so the mechanism does not know this element
+ *  exists and no React state reaches it. */
+declare function ToggleTrack({ className }: {
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+/** The travelling thumb: an accent disc inside a white ring.
+ *
+ *  Flat on top and deliberately so — no chamfer, no fillet — but still a
+ *  knob-scale body, so it casts. That pairing is why the classes are spelt
+ *  out rather than reached through `.amb-fillet-2`: the edge treatments set
+ *  a thickness of their own, and here the thickness is wanted without the
+ *  cut that usually comes with it. */
+declare function ToggleThumb({ className }: {
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+
+/** Read the enclosing control's state from inside a part.
+ *
+ *  This is the third outlet of the state channel, and the one to reach for
+ *  last: the custom properties on the control root are canonical, and a
+ *  part that can be styled from CSS should be. Use this when a part needs
+ *  the value as a JS number — a readout, a tick ring that has to emit N
+ *  children, an SVG whose path data depends on the value. */
+declare function useControlState(): ControlState;
+/** A bank key carries more than a number: its legend, its accessible name
+ *  and its own lamp colour all belong to the option, not to the state. So a
+ *  key's parts get this alongside `useControlState()`. */
+type BankKeyState = {
+    option: BankOption;
+    on: boolean;
+    index: number;
+};
+declare function useBankKey(): BankKeyState;
+
+/** The knob's cap: the smooth chamfered disc that is most of what you see,
+ *  and the element that carries the drop shadow.
+ *
+ *  `flush` takes the full width, which is what a smooth turned knob wants.
+ *  The default sits back by the knurl band so a `KnurledFace` can ring it —
+ *  the same cap either way, and the chamfer the referent cuts on every knob
+ *  (knob.py's `chamfer=0.35`, regardless of rib count) either way too. */
+declare function KnobBody({ material, flush, className }: {
+    material?: AmbientMaterial | undefined;
+    flush?: boolean | undefined;
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+/** The rotating knurl: a rim ring of ribs around the cap, clipped to the
+ *  toothed annulus so the ribs break the outline instead of being painted
+ *  inside a circle, and shaded per tooth — a lit flank climbing to each
+ *  ridge, a shaded one falling away — with a contact-occlusion band along
+ *  its inner edge where the cap overhangs it.
+ *
+ *  The clip is the part's own business — it generates the path, emits its
+ *  own `<defs>` and references it by a local id. A rotary mechanism has no
+ *  idea any of this is happening, which is exactly the point: if this part
+ *  needed help from the control to exist, the split would not be clean. */
+declare function KnurledFace({ material, color, className }: {
+    material?: AmbientMaterial | undefined;
+    /** The ribs' own colour, as an albedo. */
+    color?: string | undefined;
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+/** The grounded referent's offset indicator dot (knob() dot_frac 0.12,
+ *  dot_offset 0.68). Put it in the `actuator` frame and it sweeps; put it
+ *  in `base` and it stays put while everything else turns. */
+declare function IndicatorDot({ className }: {
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+/** A short radial bar out near the rim, running 0.50R to 0.84R. */
+declare function IndicatorBar({ className }: {
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+type ScaleRingProps = {
+    /** Dots to print. `2` is the pair the travel starts and stops at. */
+    count?: number | undefined;
+    className?: string | undefined;
+    children?: ReactNode | undefined;
 };
-declare function AmbientSlider({ value, min, max, step, label, material, size, onChange, className, ...props }: AmbientSliderProps): react_jsx_runtime.JSX.Element;
+/** Printed scale dots on the panel around a rotary, on the same arc the
+ *  value sweeps.
+ *
+ *  This is the part that has to read state as JS rather than CSS: the
+ *  angles come from the control's own travel, and there is no way to emit
+ *  N children from a stylesheet. It is also the proof that the context
+ *  outlet works — the dots land on the sweep whatever `travel` is set to,
+ *  without the ring being told. */
+declare function ScaleRing({ count, className, children }: ScaleRingProps): react_jsx_runtime.JSX.Element;
+
+/** The track a thumb rides in.
+ *
+ *  Both grounded referents are grooves with a lume interior — dark in
+ *  bright light, glowing in low light — but they are cut to different
+ *  depths: a fader runs in a through-slot, a slider in a shallow concave
+ *  channel (slider.py, 1mm deep = thickness 0.22). */
+declare function TravelTrack({ depth, className }: {
+    depth?: "slot" | "channel" | undefined;
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+/** Fader cap: the referent (fader.py) is a pill on a stem — 7mm tall
+ *  (thickness 1.5) riding 2.2mm above the plate (elevation 0.28) — with a
+ *  single grip line across the top. */
+declare function FaderCap({ material, className }: {
+    material?: AmbientMaterial | undefined;
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+/** Slider thumb: a domed disc gliding over the channel. */
+declare function SliderThumb({ material, className }: {
+    material?: AmbientMaterial | undefined;
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+
+/** The key cap: a chamfered, subtly dished top that sinks on `:active`.
+ *
+ *  The cap is what sizes a press control — its legend sets the width above
+ *  the well's `min-width` — which is why a press control's frames are
+ *  `display: contents` markers rather than boxes.
+ *
+ *  The cap spends its own `::after` on the dish, so the two micro-relief
+ *  materials cannot ride on it: their grain wants both pseudo-elements, and
+ *  the dish's `background` shorthand and the grain's tile would each silently
+ *  win half of the other's declarations. They get `.ambx-cap-face` instead —
+ *  an inner layer under the dish and under the legend, which is the inner
+ *  layer @ambientcss/css's own note prescribes. The cap itself stays a plain
+ *  `amb-surface` when relief is down there: the dish's overlay alphas are
+ *  derived from `--amb-shade` the ordinary way, and since the relief
+ *  materials carry no `--amb-albedo` of their own any more, that derivation
+ *  is already correct for them too — no per-material tone correction to
+ *  apply. */
+declare function ButtonCap({ material, className, children }: {
+    material?: AmbientMaterial | undefined;
+    className?: string | undefined;
+    children?: ReactNode | undefined;
+}): react_jsx_runtime.JSX.Element;
+
+/** The recess the pill slides in (switch.py: a 1.5mm well, thickness 0.33). */
+declare function SwitchTrack({ className }: {
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+/** The sliding pill, standing 2.6mm above the recess floor. */
+declare function SwitchPill({ className }: {
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+/** A pinprick indicator lamp. `color` is any CSS colour; unset it takes the
+ *  scene's own lamp colour, the same `--amb-led-color` a bank reads. */
+declare function Led({ on, color, className }: {
+    on?: boolean | undefined;
+    color?: string | undefined;
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+
+/** The lamp under a key: a big disc lying on the pocket floor.
+ *
+ *  It has to paint BEFORE the cap, because the cap's `backdrop-filter` is
+ *  what diffuses it — which is the whole trick, and the reason the lens
+ *  belongs in the `base` frame and the cap in `actuator`. */
+declare function KeyLens({ className }: {
+    className?: string | undefined;
+}): react_jsx_runtime.JSX.Element;
+/** The translucent diffuser over the lamp, carrying the key's legend.
+ *
+ *  With no children it prints the option's own label, which is why a bank
+ *  of numerals needs no `renderKey`: the part reads the option it belongs
+ *  to out of the key context. */
+declare function KeyCap({ className, children }: {
+    className?: string | undefined;
+    children?: ReactNode | undefined;
+}): react_jsx_runtime.JSX.Element;
 
-export { AmbientButton, type AmbientButtonProps, type AmbientButtonShape, type AmbientButtonSize, AmbientFader, type AmbientFaderProps, type AmbientFaderSize, AmbientKnob, type AmbientKnobProps, type AmbientKnobSize, type AmbientKnobVariant, AmbientPanel, type AmbientPanelProps, AmbientProvider, type AmbientProviderProps, AmbientRack, type AmbientRackGap, type AmbientRackProps, AmbientSlider, type AmbientSliderProps, type AmbientSliderSize, AmbientSwitch, type AmbientSwitchProps, type AmbientSwitchSize, type AmbientTheme };
+export { AmbientBank, type AmbientBankProps, AmbientButton, type AmbientButtonProps, type AmbientButtonShape, type AmbientButtonSize, AmbientFader, type AmbientFaderProps, type AmbientFaderSize, AmbientKitProvider, AmbientKnob, type AmbientKnobIndicator, type AmbientKnobMarkers, type AmbientKnobProps, type AmbientKnobSize, AmbientLatch, type AmbientLatchProps, type AmbientMaterial, AmbientPanel, type AmbientPanelProps, AmbientPress, type AmbientPressProps, AmbientProvider, type AmbientProviderProps, AmbientRack, type AmbientRackGap, type AmbientRackProps, AmbientRotary, type AmbientRotaryProps, AmbientSelect, type AmbientSelectOption, type AmbientSelectOrientation, type AmbientSelectProps, type AmbientSelectSize, AmbientSlider, type AmbientSliderProps, type AmbientSliderSize, AmbientSwitch, type AmbientSwitchProps, type AmbientSwitchSize, type AmbientTheme, AmbientTravel, type AmbientTravelProps, type BankKeyState, type BankOption, type BankOrientation, ButtonCap, ConsoleBar, ConsoleKnob, type ConsoleKnobProps, ConsoleMarks, ConsoleToggle, type ConsoleToggleProps, ConsoleWell, type ControlAnimate, type ControlFamily, type ControlKit, type ControlParts, type ControlSize, type ControlState, FaderCap, type FrameName, IndicatorBar, IndicatorDot, KeyCap, KeyLens, type KitDefaults, type KitDress, type KitLook, KnobBody, KnurledFace, Led, type PressMode, type RotaryInput, type RotaryTravel, ScaleRing, type ScaleRingProps, SliderThumb, SwitchPill, SwitchTrack, ToggleThumb, ToggleTrack, type TravelOrientation, TravelTrack, type UseBankOptions, type UseLatchOptions, type UsePressOptions, type UseRotaryOptions, type UseTravelOptions, consoleKit, groundedKit, useBank, useBankKey, useControlState, useDress, useKit, useLatch, usePress, useRotary, useTravel };