@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.1

package/color-wheel/behaviour.jsx

@@ -0,0 +1,301 @@
+// Ported from react-aria `useColorWheel` (packages/react-aria/src/color/useColorWheel.ts), Apache-2.0, © Adobe.
+// Rivet:
+// - `useColorWheel(props, state, inputRef)` → `colorWheelProps(props, state)` (RA's `{trackProps, thumbProps,
+//   inputProps}`), built from attribute functions (`colorWheelTrackStyle`, `colorWheelThumbStyle`,
+//   `colorWheelInputValueText`, `colorWheelInputLabels`, …) and the hook's handlers as free functions
+//   (`colorWheelTrackPointerDown`, `colorWheelThumbPointerDown`, `colorWheelThumbKeyDown`,
+//   `colorWheelInputChange`, `colorWheelInputFocus`). Components wire the handlers from inline arrows (resumable).
+// - `inputRef` is a `ref()` element ref in `props.inputRef`; the hook's refs live in `props.interaction`
+//   (`createColorWheelInteraction()`, JSON); `locale` is resolved at render and passed in.
+// - `useGlobalListeners` → window `pointerup` listener added / removed by the handlers; `useFormReset` installs
+//   on the first focus of the input.
+import { untrack } from "@rivetjs/reactivity";
+import { focusWithoutScrolling, useFormReset, useLabels } from "@rivetjs/cdk/utils";
+import { keyboardKeyDown } from "../interactions/keyboard.jsx";
+import { getOwnerWindow, read } from "../interactions/utils.js";
+import { moveKeyDown, movePointerDown } from "../interactions/move.jsx";
+import { decrement, getDefaultValue, getThumbPosition, getValue, increment, isDragging, setDragging, setHue, setHueFromPoint, setValue, } from "@rivetjs/cdk/color";
+import { colorAreaInputStyle } from "../color-area/behaviour.jsx";
+const newMove = () => ({ didMove: false, lastPosition: null, id: null });
+/** Rivet: the hook-local state of one color wheel. */
+export function createColorWheelInteraction() {
+    return { refs: { position: null, pointer: { active: false, id: null }, onTrack: false, moveThumb: newMove(), moveTrack: newMove(), formReset: false } };
+}
+const thumbRadius = (props) => (props.innerRadius + props.outerRadius) / 2;
+function focusInput(props) {
+    const input = props.inputRef();
+    if (input)
+        focusWithoutScrolling(input);
+}
+// moveHandler
+function moveStart(props, state) {
+    props.interaction.refs.position = null;
+    setDragging(state, true);
+}
+function moveMove(props, state, { deltaX, deltaY, pointerType, shiftKey }) {
+    const refs = props.interaction.refs;
+    const radius = thumbRadius(props);
+    if (refs.position == null) {
+        refs.position = untrack(() => getThumbPosition(state, radius));
+    }
+    refs.position.x += deltaX;
+    refs.position.y += deltaY;
+    if (pointerType === "keyboard") {
+        if (deltaX > 0 || deltaY < 0) {
+            increment(state, shiftKey ? state.pageStep : state.step);
+        }
+        else if (deltaX < 0 || deltaY > 0) {
+            decrement(state, shiftKey ? state.pageStep : state.step);
+        }
+    }
+    else {
+        setHueFromPoint(state, refs.position.x, refs.position.y, radius);
+    }
+}
+function moveEnd(props, state) {
+    props.interaction.refs.onTrack = false;
+    setDragging(state, false);
+    focusInput(props);
+}
+function thumbMove(props, state) {
+    return {
+        props: { onMoveStart: () => moveStart(props, state), onMove: (e) => moveMove(props, state, e), onMoveEnd: () => moveEnd(props, state) },
+        state: props.interaction.refs.moveThumb,
+    };
+}
+function trackMove(props, state) {
+    const refs = props.interaction.refs;
+    return {
+        props: {
+            onMoveStart: () => {
+                if (refs.onTrack)
+                    moveStart(props, state);
+            },
+            onMove: (e) => {
+                if (refs.onTrack)
+                    moveMove(props, state, e);
+            },
+            onMoveEnd: () => {
+                if (refs.onTrack)
+                    moveEnd(props, state);
+            },
+        },
+        state: refs.moveTrack,
+    };
+}
+// Global `pointerup` listener (useGlobalListeners), one per wheel.
+const upListeners = new WeakMap();
+function addUp(props, state, kind) {
+    const listener = (e) => (kind === "thumb" ? onThumbUp(props, state, e) : onTrackUp(props, state, e));
+    // The element's window (no bare `window`: this module is resume-compiled, server-checked).
+    const win = getOwnerWindow(props.inputRef());
+    upListeners.set(props.interaction, { listener, win });
+    win.addEventListener("pointerup", listener, false);
+}
+function removeUp(props) {
+    const entry = upListeners.get(props.interaction);
+    if (entry)
+        entry.win.removeEventListener("pointerup", entry.listener, false);
+    upListeners.delete(props.interaction);
+}
+function onThumbDown(props, state, id) {
+    if (!untrack(() => isDragging(state))) {
+        props.interaction.refs.pointer = { active: true, id };
+        focusInput(props);
+        setDragging(state, true);
+        addUp(props, state, "thumb");
+    }
+}
+function onThumbUp(props, state, e) {
+    const refs = props.interaction.refs;
+    if (refs.pointer.active && e.pointerId === refs.pointer.id) {
+        focusInput(props);
+        setDragging(state, false);
+        refs.pointer = { active: false, id: null };
+        refs.onTrack = false;
+        removeUp(props);
+    }
+}
+function onTrackDown(props, state, track, id, pageX, pageY) {
+    const refs = props.interaction.refs;
+    const rect = track.getBoundingClientRect();
+    const x = pageX - rect.x - rect.width / 2;
+    const y = pageY - rect.y - rect.height / 2;
+    const radius = Math.sqrt(x * x + y * y);
+    if (props.innerRadius < radius && radius < props.outerRadius && !untrack(() => isDragging(state)) && !refs.pointer.active) {
+        refs.onTrack = true;
+        refs.pointer = { active: true, id };
+        setHueFromPoint(state, x, y, radius);
+        focusInput(props);
+        setDragging(state, true);
+        addUp(props, state, "track");
+    }
+}
+function onTrackUp(props, state, e) {
+    const refs = props.interaction.refs;
+    if (refs.onTrack && refs.pointer.active && e.pointerId === refs.pointer.id) {
+        refs.onTrack = false;
+        refs.pointer = { active: false, id: null };
+        setDragging(state, false);
+        focusInput(props);
+        removeUp(props);
+    }
+}
+const ignoredButton = (e) => e.pointerType === "mouse" && (e.button !== 0 || e.altKey || e.ctrlKey || e.metaKey);
+/** Track `pointerdown` (RA trackInteractions: track down + track useMove). No-op when disabled. */
+export function colorWheelTrackPointerDown(e, props, state) {
+    if (read(props.isDisabled))
+        return;
+    if (!ignoredButton(e))
+        onTrackDown(props, state, e.currentTarget, e.pointerId, e.clientX, e.clientY);
+    movePointerDown(trackMove(props, state), e);
+}
+/** Thumb `pointerdown` (RA thumbInteractions: thumb down + thumb useMove). No-op when disabled. */
+export function colorWheelThumbPointerDown(e, props, state) {
+    if (read(props.isDisabled))
+        return;
+    if (!ignoredButton(e))
+        onThumbDown(props, state, e.pointerId);
+    movePointerDown(thumbMove(props, state), e);
+}
+/** Thumb `keydown` (RA useKeyboard shortcuts PageUp / PageDown + useMove arrow keys). */
+export function colorWheelThumbKeyDown(e, props, state) {
+    if (read(props.isDisabled))
+        return;
+    keyboardKeyDown({
+        shortcuts: {
+            PageUp: () => {
+                setDragging(state, true);
+                increment(state, state.pageStep);
+                setDragging(state, false);
+            },
+            PageDown: () => {
+                setDragging(state, true);
+                decrement(state, state.pageStep);
+                setDragging(state, false);
+            },
+        },
+        allowRepeats: true,
+    }, e);
+    moveKeyDown(thumbMove(props, state), e);
+}
+/** Input `change`. */
+export function colorWheelInputChange(e, _props, state) {
+    setHue(state, parseFloat(e.target.value));
+}
+/** Rivet: input `focus` installs `useFormReset` once. */
+export function colorWheelInputFocus(_e, props, state) {
+    if (props.interaction.refs.formReset)
+        return;
+    props.interaction.refs.formReset = true;
+    const defaultValue = untrack(() => getDefaultValue(state));
+    useFormReset(props.inputRef(), defaultValue, (value) => setValue(state, value));
+}
+// Creates an SVG path string for a circle.
+function circlePath(cx, cy, r) {
+    return `M ${cx}, ${cy} m ${-r}, 0 a ${r}, ${r}, 0, 1, 0, ${r * 2}, 0 a ${r}, ${r}, 0, 1, 0 ${-r * 2}, 0`;
+}
+/** Track style: size, conic hue gradient, ring clip path. */
+export function colorWheelTrackStyle(props) {
+    const { outerRadius, innerRadius } = props;
+    return {
+        position: "relative",
+        touchAction: "none",
+        width: `${outerRadius * 2}px`,
+        height: `${outerRadius * 2}px`,
+        background: `
+          conic-gradient(
+            from 90deg,
+            hsl(0, 100%, 50%),
+            hsl(30, 100%, 50%),
+            hsl(60, 100%, 50%),
+            hsl(90, 100%, 50%),
+            hsl(120, 100%, 50%),
+            hsl(150, 100%, 50%),
+            hsl(180, 100%, 50%),
+            hsl(210, 100%, 50%),
+            hsl(240, 100%, 50%),
+            hsl(270, 100%, 50%),
+            hsl(300, 100%, 50%),
+            hsl(330, 100%, 50%),
+            hsl(360, 100%, 50%)
+          )
+        `,
+        clipPath: `path(evenodd, "${circlePath(outerRadius, outerRadius, outerRadius)} ${circlePath(outerRadius, outerRadius, innerRadius)}")`,
+        forcedColorAdjust: "none",
+    };
+}
+/** Thumb style: absolute position on the ring (reads the state). */
+export function colorWheelThumbStyle(props, state) {
+    const { x, y } = getThumbPosition(state, thumbRadius(props));
+    return {
+        position: "absolute",
+        left: (props.outerRadius + x).toFixed(3) + "px",
+        top: (props.outerRadius + y).toFixed(3) + "px",
+        transform: "translate(-50%, -50%)",
+        touchAction: "none",
+        forcedColorAdjust: "none",
+    };
+}
+/** Input labelling (`useLabels`; default `aria-label` = the localized hue channel name). */
+export function colorWheelInputLabels(props, state) {
+    let ariaLabel = props["aria-label"];
+    if (ariaLabel == null && props["aria-labelledby"] == null) {
+        ariaLabel = untrack(() => getValue(state)).getChannelName("hue", props.locale);
+    }
+    return useLabels({ id: props.id, "aria-label": ariaLabel, "aria-labelledby": props["aria-labelledby"] });
+}
+/** Input range attributes (strings, as upstream). */
+export function colorWheelInputRange(state) {
+    const { minValue, maxValue, step } = getValue(state).getChannelRange("hue");
+    return { min: String(minValue), max: String(maxValue), step: String(step) };
+}
+/** Input `aria-valuetext` ("<hue>°, <hue name>"). */
+export function colorWheelInputValueText(props, state) {
+    const value = getValue(state);
+    return `${value.formatChannelValue("hue", props.locale)}, ${value.getHueName(props.locale)}`;
+}
+/** Input value. */
+export const colorWheelInputValue = (state) => `${getValue(state).getChannelValue("hue")}`;
+/** The visually hidden input style (same as the color area inputs). */
+export const colorWheelInputStyle = colorAreaInputStyle;
+/**
+ * react-aria `useColorWheel`: the three attribute bags (values read now; handler closures not resumable —
+ * components wire the exported handler functions from inline arrows instead).
+ */
+export function colorWheelProps(props, state) {
+    // Values read now; a live `isDisabled` (accessor) keeps the handlers (they check the current value).
+    const isDisabled = typeof props.isDisabled !== "function" && !!props.isDisabled;
+    const disabledNow = read(props.isDisabled);
+    return {
+        trackProps: {
+            ...(isDisabled ? {} : { onPointerDown: (e) => colorWheelTrackPointerDown(e, props, state) }),
+            style: colorWheelTrackStyle(props),
+        },
+        thumbProps: {
+            ...(isDisabled
+                ? {}
+                : {
+                    onPointerDown: (e) => colorWheelThumbPointerDown(e, props, state),
+                    onKeyDown: (e) => colorWheelThumbKeyDown(e, props, state),
+                }),
+            style: colorWheelThumbStyle(props, state),
+        },
+        inputProps: {
+            ...colorWheelInputLabels(props, state),
+            type: "range",
+            ...colorWheelInputRange(state),
+            "aria-valuetext": colorWheelInputValueText(props, state),
+            disabled: disabledNow,
+            value: colorWheelInputValue(state),
+            name: props.name,
+            form: props.form,
+            onChange: (e) => colorWheelInputChange(e, props, state),
+            onFocus: (e) => colorWheelInputFocus(e, props, state),
+            style: colorWheelInputStyle,
+            "aria-errormessage": props["aria-errormessage"],
+            "aria-describedby": props["aria-describedby"],
+            "aria-details": props["aria-details"],
+        },
+    };
+}

package/color-wheel/index.d.ts

@@ -0,0 +1,50 @@
+import { type ColorWheelState } from "@rivetjs/cdk/color";
+import { type DOMRenderProps } from "../utils/render.js";
+import { type GlobalDOMAttributes } from "../utils/dom-props.js";
+import { type ContextValue, type RefValue, type RenderProps, type SlotProps, type StyleRenderProps } from "../slots/index.jsx";
+import { type AriaColorWheelOptions } from "./behaviour.jsx";
+export * from "./behaviour.jsx";
+export interface ColorWheelRenderProps {
+    /**
+     * Whether the color wheel is disabled.
+     *
+     * @selector [data-disabled]
+     */
+    isDisabled: () => boolean;
+    /** State of the color wheel. */
+    state: ColorWheelState;
+}
+export interface ColorWheelProps extends AriaColorWheelOptions, RenderProps<ColorWheelRenderProps>, DOMRenderProps<"div", ColorWheelRenderProps>, SlotProps, Omit<GlobalDOMAttributes<HTMLDivElement>, "style"> {
+    /**
+     * The CSS class for the element. A function may be provided to compute the class based on component state.
+     *
+     * @default 'rv-ColorWheel'
+     */
+    class?: RenderProps<ColorWheelRenderProps>["class"];
+    ref?: RefValue<HTMLDivElement>;
+}
+/** RAC `ColorWheelContext`. */
+export declare const ColorWheelContext: import("@rivetjs/reactivity").Context<ContextValue<Partial<ColorWheelProps>, HTMLDivElement>>;
+/** RAC `ColorWheelStateContext`. */
+export declare const ColorWheelStateContext: import("@rivetjs/reactivity").Context<ColorWheelState | null>;
+/**
+ * A color wheel allows users to adjust the hue of an HSL or HSB color value on a circular track.
+ */
+export declare function ColorWheel(props: ColorWheelProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+export interface ColorWheelTrackRenderProps extends ColorWheelRenderProps {
+}
+export interface ColorWheelTrackProps extends StyleRenderProps<ColorWheelTrackRenderProps>, DOMRenderProps<"div", ColorWheelTrackRenderProps>, Omit<GlobalDOMAttributes<HTMLDivElement>, "style">, SlotProps {
+    /**
+     * The CSS class for the element. A function may be provided to compute the class based on component state.
+     *
+     * @default 'rv-ColorWheelTrack'
+     */
+    class?: StyleRenderProps<ColorWheelTrackRenderProps>["class"];
+    ref?: RefValue<HTMLDivElement>;
+}
+/** RAC `ColorWheelTrackContext` (the wheel provides the track's handlers + style). */
+export declare const ColorWheelTrackContext: import("@rivetjs/reactivity").Context<ContextValue<Partial<ColorWheelTrackProps> & Record<string, unknown>, HTMLDivElement>>;
+/**
+ * A color wheel track is a circular track within a color wheel which displays the hue gradient.
+ */
+export declare function ColorWheelTrack(props: ColorWheelTrackProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;

package/color-wheel/index.jsx

@@ -0,0 +1,166 @@
+// Ported from react-aria-components `ColorWheel`, `ColorWheelTrack` (packages/react-aria-components/src/ColorWheel.tsx),
+// Apache-2.0, © Adobe.
+// A color wheel allows users to adjust the hue of an HSL or HSB color value on a circular track.
+// Children: `<ColorWheelTrack />` + `<ColorThumb />`.
+// Rivet:
+// - state = `createColorWheelState` (`@rivetjs/cdk/color`: plain signals + JSON); `value` = plain value or two-way
+//   Signal (string | Color); the hook-local state = `createColorWheelInteraction()`; the input ref = `ref()`.
+// - handlers are inline arrows over the `./behaviour.tsx` free functions (resumable); the conic gradient + ring
+//   clip path are inline styles from JS (`colorWheelTrackStyle`).
+// - render props are accessors (`isDisabled()`); `state` is the serializable state object.
+// `render` (RAC DOMRenderProps): given, the attributes object (reactive entries are accessors) goes to `render(attrs, renderProps)` instead of the default element.
+import { createContext, useContext, untrack } from "@rivetjs/reactivity";
+import { hasLive, liveAssign, liveOptions } from "../utils/live.jsx";
+import { read } from "../interactions/utils.js";
+import { isColorWheelDisabled } from "../color/wheel-state.js";
+import { liveRenderProps } from "../slots/index.jsx";
+import { ref as createRef } from "@rivetjs/runtime/dom";
+import { createColorWheelState, getDisplayColor, isDragging } from "@rivetjs/cdk/color";
+import { useLocale } from "@rivetjs/cdk/i18n";
+import {} from "../utils/render.js";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { Provider, contextProps, renderProps, renderPropsOf, resumableContext, } from "../slots/index.jsx";
+import { InternalColorThumbContext } from "../color-thumb/index.jsx";
+import { colorWheelInputChange, colorWheelInputFocus, colorWheelInputLabels, colorWheelInputRange, colorWheelInputStyle, colorWheelInputValue, colorWheelInputValueText, colorWheelThumbKeyDown, colorWheelThumbPointerDown, colorWheelThumbStyle, colorWheelTrackPointerDown, colorWheelTrackStyle, createColorWheelInteraction, } from "./behaviour.jsx";
+export * from "./behaviour.jsx";
+/** RAC `ColorWheelContext`. */
+export const ColorWheelContext = resumableContext(createContext(null, { id: "rv-color-wheel" }));
+/** RAC `ColorWheelStateContext`. */
+export const ColorWheelStateContext = resumableContext(createContext(null, { id: "rv-color-wheel-state" }));
+const OWNED = ["style", "id", "render"];
+/** `data-disabled` of a live `isDisabled` (a returned arrow: resumable symbol; goes into the spread bag). */
+function liveDisabledAttr(state) {
+    return () => (isColorWheelDisabled(state) ? "true" : undefined);
+}
+/**
+ * A color wheel allows users to adjust the hue of an HSL or HSB color value on a circular track.
+ */
+export function ColorWheel(props) {
+    const [ctxMerged, ref] = contextProps(props, props.ref, ColorWheelContext);
+    // Live props (P5): `isDisabled` and a controlled `value={c()}` become accessors (the state / handlers read them; the
+    // value is never written); the rest of the body is read once (untracked: a prop change never re-creates the wheel).
+    const merged = liveOptions(ctxMerged, ["isDisabled"], ["value"]);
+    return untrack(() => colorWheel(merged, ref));
+}
+function colorWheel(merged, ref) {
+    const state = createColorWheelState(merged);
+    const inputRef = createRef();
+    const { locale } = useLocale();
+    // A live `isDisabled` is an accessor: the handlers stay attached and check it at event time.
+    const isDisabled = merged.isDisabled;
+    const disabledFlag = state.disabled ? liveDisabledAttr(state) : undefined;
+    const dropHandlers = !disabledFlag && !!isDisabled;
+    const opts = {
+        isDisabled,
+        id: merged.id,
+        name: merged.name,
+        form: merged.form,
+        outerRadius: merged.outerRadius,
+        innerRadius: merged.innerRadius,
+        "aria-label": merged["aria-label"],
+        "aria-labelledby": merged["aria-labelledby"],
+        "aria-describedby": merged["aria-describedby"],
+        "aria-details": merged["aria-details"],
+        "aria-errormessage": merged["aria-errormessage"],
+        inputRef,
+        locale,
+        interaction: createColorWheelInteraction(),
+    };
+    const values = { state, isDisabled: () => isColorWheelDisabled(state) };
+    const rp = renderPropsOf(merged, { values, defaultClassName: "rv-ColorWheel", defaultStyle: { position: "relative" } });
+    const labels = colorWheelInputLabels(opts, state);
+    const describedBy = opts["aria-describedby"];
+    const details = opts["aria-details"];
+    const errorMessage = opts["aria-errormessage"];
+    const inputProps = () => ({
+        ...labels,
+        type: "range",
+        ...colorWheelInputRange(state),
+        "aria-valuetext": colorWheelInputValueText(opts, state),
+        disabled: read(isDisabled) || undefined,
+        value: colorWheelInputValue(state),
+        name: opts.name,
+        form: opts.form,
+        onChange: (e) => colorWheelInputChange(e, opts, state),
+        onFocus: (e) => colorWheelInputFocus(e, opts, state),
+        "aria-errormessage": errorMessage,
+        "aria-describedby": describedBy,
+        "aria-details": details,
+    });
+    const thumbProps = dropHandlers
+        ? {}
+        : {
+            onPointerDown: (e) => colorWheelThumbPointerDown(e, opts, state),
+            onKeyDown: (e) => colorWheelThumbKeyDown(e, opts, state),
+        };
+    const thumbContext = {
+        displayColor: () => getDisplayColor(state),
+        isDragging: () => isDragging(state),
+        thumbProps,
+        thumbStyle: () => colorWheelThumbStyle(opts, state),
+        inputXRef: inputRef,
+        inputStyle: colorWheelInputStyle,
+        xInputProps: inputProps,
+        isDisabled,
+    };
+    const trackContext = dropHandlers
+        ? { style: colorWheelTrackStyle(opts) }
+        : { style: colorWheelTrackStyle(opts), onPointerDown: (e) => colorWheelTrackPointerDown(e, opts, state) };
+    // `data-disabled` goes through the spread bag (a function attribute value outside a spread is not a server binding,
+    // and an explicit attribute after the spread would override the bag's key); none is added while enabled (static).
+    const disabledAttr = disabledFlag ?? (isDisabled ? "true" : undefined);
+    const dom = disabledAttr ? liveAssign(globalDOMProps(merged, OWNED), { "data-disabled": disabledAttr }) : globalDOMProps(merged, OWNED);
+    const slot = merged.slot || undefined;
+    const children = rp.children;
+    if (merged.render) {
+        const attrs = {
+            ...dom,
+            ref: ref,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            slot,
+            "data-disabled": disabledAttr,
+            children: () => (<Provider values={[
+                    [ColorWheelStateContext, state],
+                    [ColorWheelTrackContext, trackContext],
+                    [InternalColorThumbContext, thumbContext],
+                ]}>
+          {children()}
+        </Provider>),
+        };
+        return merged.render(attrs, values);
+    }
+    return (<div {...dom} ref={ref} class={rp.class()} style={rp.style()} slot={slot}>
+      <Provider values={[
+            [ColorWheelStateContext, state],
+            [ColorWheelTrackContext, trackContext],
+            [InternalColorThumbContext, thumbContext],
+        ]}>
+        {children()}
+      </Provider>
+    </div>);
+}
+/** RAC `ColorWheelTrackContext` (the wheel provides the track's handlers + style). */
+export const ColorWheelTrackContext = resumableContext(createContext(null, { id: "rv-color-wheel-track" }));
+/**
+ * A color wheel track is a circular track within a color wheel which displays the hue gradient.
+ */
+export function ColorWheelTrack(props) {
+    const [merged, ref] = contextProps(props, props.ref, ColorWheelTrackContext);
+    const state = useContext(ColorWheelStateContext);
+    const { class: className, style, slot, render, ...rest } = merged;
+    // Live props (P5): `data-disabled` goes through the spread bag (an accessor while the wheel's `isDisabled` is live,
+    // `state.disabled`); none is added while enabled.
+    const disabledAttr = state.disabled ? liveDisabledAttr(state) : state.isDisabled ? "true" : undefined;
+    const attrs = disabledAttr ? { ...rest, "data-disabled": disabledAttr } : rest;
+    const values = { isDisabled: () => isColorWheelDisabled(state), state };
+    // Live props (P5): a live class / style through one live view per key. No function in the initializer: the spread
+    // site captures `rp.class` / `rp.style`, not `rp`.
+    const rp = renderProps({ class: className, style, defaultClassName: "rv-ColorWheelTrack", values }, hasLive(merged) ? liveRenderProps(merged, ["class", "style"]) : undefined);
+    const s = slot ?? undefined;
+    if (render) {
+        const bag = { ...attrs, slot: s, ref: ref, class: () => rp.class(), style: () => rp.style(), "data-disabled": disabledAttr };
+        return render(bag, values);
+    }
+    return <div {...attrs} slot={s} ref={ref} class={rp.class()} style={rp.style()}/>;
+}

package/combobox/behaviour.d.ts

@@ -0,0 +1,120 @@
+import type { Ref } from "@rivetjs/runtime/jsx-runtime";
+import type { LayoutDelegate, KeyboardDelegate } from "../collections/types.js";
+import { type Router } from "../utils/links.jsx";
+import { type MaybeAccessor, type ValidationResult } from "../state/form-validation.js";
+import { type ComboBoxState, type SelectionMode } from "../state/combobox.js";
+import { type AriaTextFieldProps, type PropBag } from "../text-field/behaviour.jsx";
+import type { FieldIds } from "../label/behaviour.js";
+/** The element refs of a combobox (`ref()`s from `@rivetjs/runtime/dom`). */
+export interface ComboBoxRefs {
+    /** The input element. */
+    inputRef: Ref<HTMLInputElement>;
+    /** The list box popover. */
+    popoverRef: Ref<Element>;
+    /** The list box. */
+    listBoxRef: Ref<HTMLElement>;
+    /** The optional list box popup trigger button. */
+    buttonRef: Ref<Element>;
+}
+export interface AriaComboBoxProps extends Omit<AriaTextFieldProps, "value" | "defaultValue" | "onChange" | "type" | "inputElementType"> {
+    /** Whether keyboard navigation is circular. */
+    shouldFocusWrap?: boolean | undefined;
+    /** Whether the ComboBox allows a non-item matching input value to be set. */
+    allowsCustomValue?: boolean | undefined;
+    /** Whether single or multiple selection is enabled. */
+    selectionMode?: SelectionMode | undefined;
+}
+export interface AriaComboBoxOptions extends AriaComboBoxProps, ComboBoxRefs {
+    /**
+     * The HTML element used to render the label, e.g. 'label', or 'span'.
+     *
+     * @default 'label'
+     */
+    labelElementType?: "label" | "span";
+    /** An optional keyboard delegate implementation, to override the default. */
+    keyboardDelegate?: KeyboardDelegate;
+    /**
+     * A delegate object that provides layout information for items in the collection. By default this uses
+     * the DOM, but this can be overridden to implement things like virtualized scrolling.
+     */
+    layoutDelegate?: LayoutDelegate;
+    /** Rivet: locale of the announcements and labels (default "en-US"). */
+    locale?: string;
+    /** Rivet: the router of link items (RA `useRouter()`). */
+    router?: Router;
+    /** Rivet: the `ComboBoxValue` slot id (RA `useValueId`); read inside `aria-describedby`. */
+    valueId?: () => string | undefined;
+}
+export interface ComboBoxAria {
+    /** Props for the label element. */
+    labelProps: PropBag;
+    /** Props for the combo box input element. */
+    inputProps: PropBag;
+    /** Props for the list box (ListBoxContext). */
+    listBoxProps: PropBag;
+    /** Props for the optional trigger button (ButtonContext). */
+    buttonProps: PropBag;
+    /** Props for the element representing the selected value. */
+    valueProps: {
+        id: string | undefined;
+    };
+    /** Props for the combo box description element, if any. */
+    descriptionProps: PropBag;
+    /** Props for the combo box error message element, if any. */
+    errorMessageProps: PropBag;
+    /** Rivet: ids of the field parts. */
+    ids: FieldIds;
+    /** Rivet: id of the list box (`ListState.id`). */
+    listBoxId: string;
+    isInvalid: () => boolean;
+    validationErrors: () => string[];
+    validationDetails: () => ValidationResult["validationDetails"];
+}
+/** Handler props (plain data + the user's callbacks). */
+export interface ComboBoxHandlerProps {
+    /** A value, or an accessor that stays live (live props: read at event time). */
+    isDisabled?: MaybeAccessor<boolean | undefined>;
+    isReadOnly?: MaybeAccessor<boolean | undefined>;
+    allowsCustomValue?: boolean | undefined;
+    shouldFocusWrap?: boolean | undefined;
+    onFocus?: ((e: FocusEvent) => void) | undefined;
+    onBlur?: ((e: FocusEvent) => void) | undefined;
+    onKeyDown?: ((e: KeyboardEvent) => void) | undefined;
+    keyboardDelegate?: KeyboardDelegate | undefined;
+    layoutDelegate?: LayoutDelegate | undefined;
+    locale?: string | undefined;
+    router?: Router | undefined;
+}
+/** The input's keydown (upstream: `chain(state.isOpen && collectionProps.onKeyDown, keyboardProps.onKeyDown, repeatKeyboardProps.onKeyDown, props.onKeyDown)`). */
+export declare function comboBoxInputKeyDown(e: KeyboardEvent, props: ComboBoxHandlerProps, state: ComboBoxState, refs: ComboBoxRefs): void;
+/** The input's blur. */
+export declare function comboBoxInputBlur(e: FocusEvent, props: ComboBoxHandlerProps, state: ComboBoxState, refs: ComboBoxRefs): void;
+/** The input's focus. */
+export declare function comboBoxInputFocus(e: FocusEvent, props: ComboBoxHandlerProps, state: ComboBoxState, refs: ComboBoxRefs): void;
+/** Press handlers for the ComboBox button: `onPress` (touch). */
+export declare function comboBoxButtonPress(e: {
+    pointerType: string;
+}, props: ComboBoxHandlerProps, state: ComboBoxState, refs: ComboBoxRefs): void;
+/** Press handlers for the ComboBox button: `onPressStart` (mouse / keyboard / virtual). */
+export declare function comboBoxButtonPressStart(e: {
+    pointerType: string;
+}, props: ComboBoxHandlerProps, state: ComboBoxState, refs: ComboBoxRefs): void;
+/** The trigger button's keydown (useMenuTrigger `keyboardProps`, trigger "press"). */
+export declare function comboBoxButtonKeyDown(e: KeyboardEvent, props: ComboBoxHandlerProps, state: ComboBoxState): void;
+/** If a touch happens on direct center of ComboBox input, might be virtual click from iPad so open ComboBox menu. */
+export declare function comboBoxInputTouchEnd(e: TouchEvent, props: ComboBoxHandlerProps, state: ComboBoxState, refs: ComboBoxRefs): void;
+/** Focus the input in case the label is not a native <label> element. */
+export declare function comboBoxLabelClick(refs: Pick<ComboBoxRefs, "inputRef">): void;
+/**
+ * The per-render effects of useComboBox (announcements, `ariaHideOutside` while open, focus ring re-show,
+ * closing on a listbox item action): one reactive root, created on the first interaction, disposed once the
+ * combobox is neither focused nor open.
+ */
+export declare function comboBoxEffects(props: ComboBoxHandlerProps, state: ComboBoxState, refs: ComboBoxRefs): void;
+/** Disposes the interaction effects (`comboBoxEffects`): call when the combobox unmounts (React effect cleanup). */
+export declare function comboBoxDisposeEffects(state: Pick<ComboBoxState, "isOpen">): void;
+/**
+ * Provides the behavior and accessibility implementation for a combo box component. A combo box combines a
+ * text input with a listbox, allowing users to filter a list of options to items matching a query.
+ */
+export declare function comboBoxProps(props: AriaComboBoxOptions, state: ComboBoxState): ComboBoxAria;