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

package/color-area/index.jsx

@@ -0,0 +1,187 @@
+// Ported from react-aria-components `ColorArea` (packages/react-aria-components/src/ColorArea.tsx), Apache-2.0, © Adobe.
+// A color area allows users to adjust two channels of an RGB, HSL or HSB color value against a two-dimensional
+// gradient background. Children: `<ColorThumb />`.
+// Rivet:
+// - state = `createColorAreaState` (`@rivetjs/cdk/color`: plain signals + JSON); `value` = plain value or
+//   two-way Signal (string | Color); the hook-local state = `createColorAreaInteraction()`; refs = `ref()`.
+// - handlers are inline arrows over the `./behaviour.tsx` free functions (resumable: drag / keys work on a
+//   resumed page); the gradient background is an inline style from JS (`colorAreaStyle`).
+// - 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, untrack } from "@rivetjs/reactivity";
+import { ref as createRef } from "@rivetjs/runtime/dom";
+import { createColorAreaState, 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, mergeRefValues, resumableContext, contextProps, renderPropsOf, } from "../slots/index.jsx";
+import { InternalColorThumbContext } from "../color-thumb/index.jsx";
+import { colorAreaGroupLabels, colorAreaInputChange, colorAreaInputFocus, colorAreaInputHidden, colorAreaInputLabels, colorAreaInputRange, colorAreaInputStyle, colorAreaInputTabIndex, colorAreaInputValue, colorAreaInputValueText, colorAreaPointerDown, colorAreaRoleDescription, colorAreaStyle, colorAreaThumbFocusIn, colorAreaThumbFocusOut, colorAreaThumbKeyDown, colorAreaThumbPointerDown, colorAreaThumbStyle, createColorAreaInteraction, } from "./behaviour.jsx";
+import { liveAssign, liveOptions } from "../utils/live.jsx";
+import { read } from "../interactions/utils.js";
+import { isColorAreaDisabled } from "../color/area-state.js";
+export * from "./behaviour.jsx";
+/** RAC `ColorAreaContext`. */
+export const ColorAreaContext = resumableContext(createContext(null, { id: "rv-color-area" }));
+/** RAC `ColorAreaStateContext`. */
+export const ColorAreaStateContext = resumableContext(createContext(null, { id: "rv-color-area-state" }));
+const OWNED = ["style", "id", "onPointerDown", "render"];
+/** `data-disabled` of a live `isDisabled` (a returned arrow: resumable symbol; goes into the spread bag). */
+function liveDisabledAttr(state) {
+    return () => (isColorAreaDisabled(state) ? "true" : undefined);
+}
+/**
+ * A color area allows users to adjust two channels of an RGB, HSL or HSB color value against a
+ * two-dimensional gradient background.
+ */
+export function ColorArea(props) {
+    const [ctxMerged, forwarded] = contextProps(props, props.ref, ColorAreaContext);
+    // 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 area).
+    const merged = liveOptions(ctxMerged, ["isDisabled"], ["value"]);
+    return untrack(() => colorArea(merged, forwarded));
+}
+function colorArea(merged, forwarded) {
+    const inputXRef = createRef();
+    const inputYRef = createRef();
+    const containerRef = createRef();
+    const { locale, direction } = useLocale();
+    const state = createColorAreaState(merged);
+    // 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,
+        "aria-label": merged["aria-label"],
+        "aria-labelledby": merged["aria-labelledby"],
+        "aria-describedby": merged["aria-describedby"],
+        "aria-details": merged["aria-details"],
+        xName: merged.xName,
+        yName: merged.yName,
+        form: merged.form,
+        inputXRef,
+        inputYRef,
+        containerRef,
+        locale,
+        direction,
+        interaction: createColorAreaInteraction(),
+    };
+    const values = { state, isDisabled: () => isColorAreaDisabled(state) };
+    const rp = renderPropsOf(merged, { defaultClassName: "rv-ColorArea", values });
+    const ownStyle = merged.style;
+    const style = () => {
+        const defaultStyle = colorAreaStyle(opts, state);
+        const computed = typeof ownStyle === "function" ? ownStyle({ state, isDisabled: () => isColorAreaDisabled(state), defaultStyle }) : ownStyle;
+        return { ...defaultStyle, ...computed };
+    };
+    const roledescription = colorAreaRoleDescription(opts);
+    const xLabels = colorAreaInputLabels(opts);
+    const yLabels = colorAreaInputLabels(opts);
+    const describedBy = opts["aria-describedby"];
+    const details = opts["aria-details"];
+    const xInputProps = () => ({
+        ...xLabels,
+        onFocus: (e) => colorAreaInputFocus(e, opts, state, "x"),
+        type: "range",
+        ...colorAreaInputRange(opts, state, "x"),
+        "aria-roledescription": roledescription,
+        "aria-valuetext": colorAreaInputValueText(opts, state, "x"),
+        "aria-orientation": "horizontal",
+        "aria-describedby": describedBy,
+        "aria-details": details,
+        disabled: read(isDisabled) || undefined,
+        value: colorAreaInputValue(state, "x"),
+        name: opts.xName,
+        form: opts.form,
+        tabIndex: colorAreaInputTabIndex(opts, "x"),
+        "aria-hidden": colorAreaInputHidden(opts, "x"),
+        onChange: (e) => colorAreaInputChange(e, opts, state),
+    });
+    const yInputProps = () => ({
+        ...yLabels,
+        onFocus: (e) => colorAreaInputFocus(e, opts, state, "y"),
+        type: "range",
+        ...colorAreaInputRange(opts, state, "y"),
+        "aria-roledescription": roledescription,
+        "aria-valuetext": colorAreaInputValueText(opts, state, "y"),
+        "aria-orientation": "vertical",
+        "aria-describedby": describedBy,
+        "aria-details": details,
+        disabled: read(isDisabled) || undefined,
+        value: colorAreaInputValue(state, "y"),
+        name: opts.yName,
+        form: opts.form,
+        tabIndex: colorAreaInputTabIndex(opts, "y"),
+        "aria-hidden": colorAreaInputHidden(opts, "y"),
+        onChange: (e) => colorAreaInputChange(e, opts, state),
+    });
+    const thumbProps = dropHandlers
+        ? { role: "presentation" }
+        : {
+            role: "presentation",
+            onPointerDown: (e) => colorAreaThumbPointerDown(e, opts, state),
+            onKeyDown: (e) => colorAreaThumbKeyDown(e, opts, state),
+            onFocusIn: (e) => colorAreaThumbFocusIn(e, opts),
+            onFocusOut: (e) => colorAreaThumbFocusOut(e, opts),
+        };
+    const thumbContext = {
+        displayColor: () => getDisplayColor(state),
+        isDragging: () => isDragging(state),
+        thumbProps,
+        thumbStyle: () => colorAreaThumbStyle(opts, state),
+        inputXRef,
+        inputYRef,
+        inputStyle: colorAreaInputStyle,
+        xInputProps,
+        yInputProps,
+        isDisabled,
+    };
+    const groupLabels = colorAreaGroupLabels(opts);
+    // `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 { onPointerDown } = merged;
+    const slot = merged.slot || undefined;
+    // The container ref (RA `containerRef`) doubles as the forwarded ref.
+    const ref = mergeRefValues(containerRef, forwarded);
+    const children = rp.children;
+    if (merged.render) {
+        const attrs = {
+            ...dom,
+            ref: ref,
+            id: groupLabels.id,
+            "aria-label": groupLabels["aria-label"],
+            "aria-labelledby": groupLabels["aria-labelledby"],
+            role: "group",
+            class: () => rp.class(),
+            style,
+            slot,
+            "data-disabled": disabledAttr,
+            onPointerDown: (e) => {
+                colorAreaPointerDown(e, opts, state);
+                onPointerDown?.(e);
+            },
+            children: () => (<Provider values={[
+                    [ColorAreaStateContext, state],
+                    [InternalColorThumbContext, thumbContext],
+                ]}>
+          {children()}
+        </Provider>),
+        };
+        return merged.render(attrs, values);
+    }
+    return (<div {...dom} ref={ref} id={groupLabels.id} aria-label={groupLabels["aria-label"]} aria-labelledby={groupLabels["aria-labelledby"]} role="group" class={rp.class()} style={style()} slot={slot} onPointerDown={(e) => {
+            colorAreaPointerDown(e, opts, state);
+            onPointerDown?.(e);
+        }}>
+      <Provider values={[
+            [ColorAreaStateContext, state],
+            [InternalColorThumbContext, thumbContext],
+        ]}>
+        {children()}
+      </Provider>
+    </div>);
+}

package/color-field/behaviour.d.ts

@@ -0,0 +1,112 @@
+import { type ColorChannelFieldState, type ColorFieldProps, type ColorFieldState } from "@rivetjs/cdk/color";
+import { type MaybeAccessor } from "../interactions/utils.js";
+import { type FieldIds } from "../label/behaviour.js";
+import { type ValidationResult } from "../state/form-validation.js";
+import { type SpinButtonProps, type SpinButtonState } from "../spinbutton/behaviour.jsx";
+import { type AriaNumberFieldProps, type NumberFieldAria } from "../number-field/behaviour.jsx";
+type Bag = Record<string, unknown>;
+export interface AriaColorFieldProps extends ColorFieldProps {
+    id?: string;
+    /** The content of the visible label (RA `label`; any truthy value = a label renders). */
+    label?: unknown;
+    /** RA `description` (truthy: a description renders). */
+    description?: unknown;
+    /** RA `errorMessage`. */
+    errorMessage?: unknown;
+    placeholder?: string;
+    autoFocus?: boolean;
+    name?: string;
+    form?: string;
+    /** Enables or disables changing the value with scroll. */
+    isWheelDisabled?: boolean;
+    /** Whether the input should be excluded from the tab order. */
+    excludeFromTabOrder?: boolean;
+    /** Rivet: the locale of the spin button's "Empty" announcement (RA `useLocale()`). */
+    locale?: MaybeAccessor<string | undefined>;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-details"?: string;
+    "aria-errormessage"?: string;
+    onFocus?: (e: FocusEvent) => void;
+    onBlur?: (e: FocusEvent) => void;
+    onFocusChange?: (isFocused: boolean) => void;
+    onKeyDown?: (e: KeyboardEvent) => void;
+    onKeyUp?: (e: KeyboardEvent) => void;
+    onCopy?: (e: ClipboardEvent) => void;
+    onCut?: (e: ClipboardEvent) => void;
+    onPaste?: (e: ClipboardEvent) => void;
+    onCompositionStart?: (e: CompositionEvent) => void;
+    onCompositionEnd?: (e: CompositionEvent) => void;
+    onCompositionUpdate?: (e: CompositionEvent) => void;
+    onSelect?: (e: Event) => void;
+    onBeforeInput?: (e: InputEvent) => void;
+    onInput?: (e: Event) => void;
+}
+export interface ColorFieldAria {
+    /** Props for the label element. */
+    labelProps: Bag;
+    /** Props for the input element. */
+    inputProps: Bag;
+    /** Props for the text field's description element, if any. */
+    descriptionProps: Bag;
+    /** Props for the text field's error message element, if any. */
+    errorMessageProps: Bag;
+    isInvalid: () => boolean;
+    validationErrors: () => string[];
+    validationDetails: () => ValidationResult["validationDetails"];
+    /** Rivet: ids of the parts. */
+    ids: FieldIds & {
+        inputId: string;
+    };
+    /** Rivet: the spin button's state (RA refs of useSpinButton; plain JSON). */
+    spin: SpinButtonState;
+    /** Rivet: focus-within state (RA `useFocusWithin`) + the attached wheel listener (browser only). */
+    within: {
+        isFocusWithin: boolean;
+    };
+}
+/** The spin button props RA passes to useSpinButton (built at event / binding time). */
+export declare function colorFieldSpinProps(props: AriaColorFieldProps, state: ColorFieldState): SpinButtonProps;
+/**
+ * Provides the behavior and accessibility implementation for a color field component.
+ * Color fields allow users to enter and adjust a hex color value.
+ */
+export declare function colorFieldProps(props: AriaColorFieldProps, state: ColorFieldState): ColorFieldAria;
+/** RA text field `onChange` (native `input`): accept the text when it is a valid partial hex value. */
+export declare function colorFieldInput(event: Event, props: AriaColorFieldProps, state: ColorFieldState, _aria?: ColorFieldAria): void;
+/** Native `change` (RA useFormValidation change listener): commit the validation. */
+export declare function colorFieldChange(event: Event, _props: AriaColorFieldProps, state: ColorFieldState): void;
+/** `invalid` (form submit / checkValidity). */
+export declare function colorFieldInvalid(event: Event, _props: AriaColorFieldProps, state: ColorFieldState): void;
+/** beforeinput (useFormattedTextField): cancel input that would make an invalid partial hex value. */
+export declare function colorFieldBeforeInput(event: InputEvent, props: AriaColorFieldProps, state: ColorFieldState): void;
+export declare function colorFieldCompositionStart(event: CompositionEvent, props: AriaColorFieldProps, _state: ColorFieldState): void;
+export declare function colorFieldCompositionEnd(event: CompositionEvent, props: AriaColorFieldProps, state: ColorFieldState): void;
+/** RA `onWheel`: vertical wheel increments / decrements (mostly-horizontal trackpad motion is ignored). */
+export declare function colorFieldScroll(e: {
+    deltaX: number;
+    deltaY: number;
+}, state: ColorFieldState): void;
+/** keydown: useKeyboard (Enter commits, user `onKeyDown`), then the spin button shortcuts (RA mergeProps order). */
+export declare function colorFieldKeyDown(event: KeyboardEvent, props: AriaColorFieldProps, state: ColorFieldState, aria: ColorFieldAria): void;
+/** keyup. */
+export declare function colorFieldKeyUp(event: KeyboardEvent, props: AriaColorFieldProps, state: ColorFieldState, aria: ColorFieldAria): void;
+/** focus: spin button announcements, focus within (wheel listener), native custom validity, user focus events. */
+export declare function colorFieldFocus(event: FocusEvent, props: AriaColorFieldProps, state: ColorFieldState, aria: ColorFieldAria): void;
+/** blur: spin button, focus within, `onBlur: commit`, user focus events. */
+export declare function colorFieldBlur(event: FocusEvent, props: AriaColorFieldProps, state: ColorFieldState, aria: ColorFieldAria): void;
+/** RA unmount cleanup (spin timers, wheel listener). */
+export declare function colorFieldDispose(aria: ColorFieldAria): void;
+export interface AriaColorChannelFieldProps extends Omit<AriaNumberFieldProps, "value" | "defaultValue" | "onChange" | "validate"> {
+}
+export interface ColorChannelFieldAria extends NumberFieldAria {
+}
+/** The number field props RA passes for a channel field (value / onChange come from the channel state). */
+export declare function colorChannelFieldNumberProps(props: AriaColorChannelFieldProps, state: ColorChannelFieldState): AriaNumberFieldProps;
+/**
+ * Provides the behavior and accessibility implementation for a color channel field, allowing users
+ * to edit the value of an individual color channel.
+ */
+export declare function colorChannelFieldProps(props: AriaColorChannelFieldProps, state: ColorChannelFieldState): ColorChannelFieldAria;
+export {};

package/color-field/behaviour.jsx

@@ -0,0 +1,262 @@
+// Ported from react-aria `useColorField`, `useColorChannelField` (packages/react-aria/src/color/useColorField.ts,
+// useColorChannelField.ts), Apache-2.0, © Adobe.
+// Rivet:
+// - `useColorField(props, state, ref)` → `colorFieldProps(props, state)`: RA's bags (`labelProps`, `inputProps`,
+//   `descriptionProps`, `errorMessageProps`) + validation accessors; values that change are accessors (this module
+//   is `.tsx`: resume-compiled). RA's merged handlers (useKeyboard Enter commit, useFormattedTextField, useSpinButton,
+//   useFocusWithin + useScrollWheel, `onBlur: commit`) are free functions `colorField<Event>(event, props, state, aria)`;
+//   `aria` = the returned `ColorFieldAria` (ids + the spin button's JSON state).
+// - State = `createColorFieldState` (`@rivetjs/cdk/color`, free functions over plain signals).
+// - `flushSync(commit)` → `commit(state)` then the DOM input value is written at once (bindings are synchronous).
+// - useScrollWheel: the non-passive wheel listener is attached to the input on focus and removed on blur (RA attaches
+//   it in an effect and ignores wheels unless focus is within) — same behaviour, no code before interaction.
+// - useFormReset → `onFormReset` (form/behaviour.ts), attached by the first input / focus handler.
+// - `useColorChannelField(props, state, ref)` → `colorChannelFieldProps(props, state)`: `numberFieldProps` over
+//   `numberFieldView(state)` (`@rivetjs/cdk/color`; upstream spreads useNumberFieldState into the channel state);
+//   handlers = the `numberField<Event>` functions with `numberFieldView(state)` built inside the handler.
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { untrack } from "@rivetjs/reactivity";
+import { colorValue, commit, decrementToMin, defaultColorValue, incrementToMax, inputValue, numberFieldView, setColorValue, setInputValue, validate, increment, decrement, } from "@rivetjs/cdk/color";
+import { channelFieldColorValue } from "../color/channel-field-state.jsx";
+import { createId } from "../utils/id.js";
+import { focusBlur, focusFocus } from "../interactions/focus.jsx";
+import { keyboardKeyDown, keyboardKeyUp } from "../interactions/keyboard.jsx";
+import { getEventTarget, read } from "../interactions/utils.js";
+import { scrollWheel } from "../interactions/scroll-wheel.jsx";
+import { describedBy, fieldProps } from "../label/behaviour.js";
+import { onFormReset, syncValidity, validationChange, validationInvalid } from "../form/behaviour.js";
+import { commitValidation, displayValidation } from "../state/form-validation.js";
+import { formattedTextFieldBeforeInput, formattedTextFieldCompositionEnd, formattedTextFieldCompositionStart, } from "../text-field/behaviour.jsx";
+import { createSpinButtonState, spinButtonBlur, spinButtonDispose, spinButtonFocus, spinButtonKeyDown, spinButtonKeyUp, } from "../spinbutton/behaviour.jsx";
+import { numberFieldProps } from "../number-field/behaviour.jsx";
+/** The spin button props RA passes to useSpinButton (built at event / binding time). */
+export function colorFieldSpinProps(props, state) {
+    return {
+        isDisabled: props.isDisabled,
+        isReadOnly: props.isReadOnly,
+        isRequired: props.isRequired,
+        maxValue: 0xffffff,
+        minValue: 0,
+        onIncrement: () => increment(state),
+        onIncrementToMax: () => incrementToMax(state),
+        onDecrement: () => decrement(state),
+        onDecrementToMin: () => decrementToMin(state),
+        value: () => colorValue(state)?.toHexInt(),
+        textValue: () => {
+            const color = colorValue(state);
+            return color ? color.toString("hex") : undefined;
+        },
+        locale: props.locale,
+    };
+}
+/**
+ * Provides the behavior and accessibility implementation for a color field component.
+ * Color fields allow users to enter and adjust a hex color value.
+ */
+export function colorFieldProps(props, state) {
+    const { placeholder, autoFocus } = props;
+    // Live props (P5): `isDisabled` / `isReadOnly` / `isRequired` may be accessors (the attributes then are bindings).
+    const isDisabled = (props.isDisabled ?? false);
+    const isReadOnly = (props.isReadOnly ?? false);
+    const isRequired = (props.isRequired ?? false);
+    const behaviour = state.validation.behavior;
+    const inputId = createId();
+    const field = fieldProps({ ...props, id: inputId });
+    const isInvalid = () => displayValidation(state.validation).isInvalid;
+    return {
+        labelProps: { ...field.labelProps },
+        inputProps: {
+            id: inputId,
+            type: "text",
+            autoComplete: "off",
+            autoCorrect: "off",
+            spellCheck: "false",
+            // useSpinButton's role is overridden; its aria-value* are removed.
+            role: "textbox",
+            "aria-valuemax": null,
+            "aria-valuemin": null,
+            "aria-valuenow": null,
+            "aria-valuetext": null,
+            value: () => inputValue(state),
+            placeholder,
+            autoFocus,
+            name: props.name,
+            form: props.form,
+            tabIndex: props.excludeFromTabOrder ? -1 : undefined,
+            disabled: typeof isDisabled === "function" ? liveFlag(isDisabled) : isDisabled,
+            readOnly: typeof isReadOnly === "function" ? liveFlag(isReadOnly) : isReadOnly,
+            required: behaviour === "native" ? flagAttr(isRequired) : undefined,
+            "aria-disabled": flagAttr(isDisabled),
+            "aria-readonly": flagAttr(isReadOnly),
+            "aria-required": behaviour === "native" ? undefined : flagAttr(isRequired),
+            "aria-invalid": () => isInvalid() || undefined,
+            "aria-errormessage": props["aria-errormessage"],
+            "aria-label": field.fieldProps["aria-label"],
+            "aria-labelledby": field.fieldProps["aria-labelledby"],
+            "aria-describedby": () => describedBy(field, isInvalid()),
+            "aria-details": props["aria-details"],
+        },
+        descriptionProps: { id: field.descriptionId },
+        errorMessageProps: { id: field.errorMessageId },
+        isInvalid,
+        validationErrors: () => displayValidation(state.validation).validationErrors,
+        validationDetails: () => displayValidation(state.validation).validationDetails,
+        ids: { ...field, inputId },
+        spin: createSpinButtonState(),
+        within: { isFocusWithin: false },
+    };
+}
+/** `true` while a live flag is set (a returned arrow: resumable symbol). */
+function liveFlag(flag) {
+    return () => !!flag() || undefined;
+}
+/** A flag attribute: `true` / `undefined`, or an accessor of it while the flag is live. */
+const flagAttr = (flag) => typeof flag === "function" ? liveFlag(flag) : flag || undefined;
+const formatted = (state) => ({
+    validate,
+    setInputValue: (value) => setInputValue(state, value),
+});
+// Browser-only wheel listeners per spin state (never serialized).
+const wheels = new WeakMap();
+/** Writes the state's input text to the element when it differs (React re-renders the controlled input). */
+function syncInput(state, input) {
+    const text = untrack(() => inputValue(state));
+    if (input && input.value !== text)
+        input.value = text;
+}
+function attachReset(state, input) {
+    // RA useFormReset(ref, state.defaultColorValue, state.setColorValue)
+    onFormReset(state, input, () => setColorValue(state, defaultColorValue(state) ?? null));
+}
+/** RA text field `onChange` (native `input`): accept the text when it is a valid partial hex value. */
+export function colorFieldInput(event, props, state, _aria) {
+    const input = getEventTarget(event);
+    attachReset(state, input);
+    if (validate(input.value)) {
+        setInputValue(state, input.value);
+    }
+    else {
+        syncInput(state, input);
+    }
+    syncValidity(state.validation, input);
+    props.onInput?.(event);
+}
+/** Native `change` (RA useFormValidation change listener): commit the validation. */
+export function colorFieldChange(event, _props, state) {
+    validationChange(state.validation, event.currentTarget);
+}
+/** `invalid` (form submit / checkValidity). */
+export function colorFieldInvalid(event, _props, state) {
+    validationInvalid(state.validation, event);
+}
+/** beforeinput (useFormattedTextField): cancel input that would make an invalid partial hex value. */
+export function colorFieldBeforeInput(event, props, state) {
+    formattedTextFieldBeforeInput(event, formatted(state));
+    props.onBeforeInput?.(event);
+}
+export function colorFieldCompositionStart(event, props, _state) {
+    formattedTextFieldCompositionStart(event);
+    props.onCompositionStart?.(event);
+}
+export function colorFieldCompositionEnd(event, props, state) {
+    formattedTextFieldCompositionEnd(event, formatted(state));
+    props.onCompositionEnd?.(event);
+}
+/** RA `onWheel`: vertical wheel increments / decrements (mostly-horizontal trackpad motion is ignored). */
+export function colorFieldScroll(e, state) {
+    if (Math.abs(e.deltaY) <= Math.abs(e.deltaX)) {
+        return;
+    }
+    if (e.deltaY > 0) {
+        increment(state);
+    }
+    else if (e.deltaY < 0) {
+        decrement(state);
+    }
+}
+/** keydown: useKeyboard (Enter commits, user `onKeyDown`), then the spin button shortcuts (RA mergeProps order). */
+export function colorFieldKeyDown(event, props, state, aria) {
+    const input = event.currentTarget;
+    keyboardKeyDown({
+        isDisabled: read(props.isDisabled) || read(props.isReadOnly),
+        shortcuts: {
+            Enter: () => {
+                commit(state);
+                syncInput(state, input);
+                commitValidation(state.validation);
+                return { shouldPreventDefault: false };
+            },
+        },
+        onKeyDown: props.onKeyDown,
+    }, event);
+    spinButtonKeyDown(event, colorFieldSpinProps(props, state), aria.spin);
+}
+/** keyup. */
+export function colorFieldKeyUp(event, props, state, aria) {
+    keyboardKeyUp({ isDisabled: read(props.isDisabled) || read(props.isReadOnly), shortcuts: {}, onKeyUp: props.onKeyUp }, event);
+    spinButtonKeyUp(event, colorFieldSpinProps(props, state), aria.spin);
+}
+/** focus: spin button announcements, focus within (wheel listener), native custom validity, user focus events. */
+export function colorFieldFocus(event, props, state, aria) {
+    const input = event.currentTarget;
+    spinButtonFocus(event, colorFieldSpinProps(props, state), aria.spin);
+    attachReset(state, input);
+    syncValidity(state.validation, input);
+    if (!read(props.isDisabled) && !aria.within.isFocusWithin) {
+        aria.within.isFocusWithin = true;
+        const listener = (e) => {
+            // If the input isn't supposed to receive input, disable scrolling.
+            const disabled = props.isWheelDisabled || read(props.isDisabled) || read(props.isReadOnly) || !aria.within.isFocusWithin;
+            scrollWheel({ isDisabled: disabled, onScroll: (s) => colorFieldScroll(s, state) }, e);
+        };
+        input.addEventListener("wheel", listener, { passive: false });
+        wheels.set(aria.spin, () => input.removeEventListener("wheel", listener));
+    }
+    if (props.onFocus || props.onFocusChange)
+        focusFocus(props, event);
+}
+/** blur: spin button, focus within, `onBlur: commit`, user focus events. */
+export function colorFieldBlur(event, props, state, aria) {
+    const input = event.currentTarget;
+    spinButtonBlur(event, colorFieldSpinProps(props, state), aria.spin);
+    aria.within.isFocusWithin = false;
+    wheels.get(aria.spin)?.();
+    wheels.delete(aria.spin);
+    commit(state);
+    syncInput(state, input);
+    syncValidity(state.validation, input);
+    if (props.onBlur || props.onFocusChange)
+        focusBlur(props, event);
+}
+/** RA unmount cleanup (spin timers, wheel listener). */
+export function colorFieldDispose(aria) {
+    spinButtonDispose(aria.spin);
+    wheels.get(aria.spin)?.();
+    wheels.delete(aria.spin);
+}
+/** The number field props RA passes for a channel field (value / onChange come from the channel state). */
+export function colorChannelFieldNumberProps(props, state) {
+    return {
+        ...props,
+        // Provide a default aria-label if no other label is provided.
+        "aria-label": props["aria-label"] ||
+            (props.label || props["aria-labelledby"] ? undefined : untrack(() => channelFieldColorValue(state)).getChannelName(state.channel, read(props.locale))),
+    };
+}
+/**
+ * Provides the behavior and accessibility implementation for a color channel field, allowing users
+ * to edit the value of an individual color channel.
+ */
+export function colorChannelFieldProps(props, state) {
+    return numberFieldProps(colorChannelFieldNumberProps(props, state), numberFieldView(state));
+}

package/color-field/index.d.ts

@@ -0,0 +1,72 @@
+import { type Color, type ColorChannel, type ColorChannelFieldState, type ColorFieldState, type ColorInput, type ColorSpace } from "@rivetjs/cdk/color";
+import type { MaybeAccessor } from "../state/form-validation.js";
+import { type GlobalDOMAttributes } from "../utils/dom-props.js";
+import { type DOMRenderProps } from "../utils/render.js";
+import { type ContextValue, type RACValidation, type RefValue, type RenderProps, type SlotProps } from "../slots/index.jsx";
+import { type AriaColorFieldProps } from "./behaviour.jsx";
+export * from "./behaviour.jsx";
+export interface ColorFieldRenderProps {
+    /**
+     * Whether the color field is disabled.
+     *
+     * @selector [data-disabled]
+     */
+    isDisabled: () => boolean;
+    /**
+     * Whether the color field is invalid.
+     *
+     * @selector [data-invalid]
+     */
+    isInvalid: () => boolean;
+    /**
+     * Whether the color field is read only.
+     *
+     * @selector [data-readonly]
+     */
+    isReadOnly: () => boolean;
+    /**
+     * Whether the color field is required.
+     *
+     * @selector [data-required]
+     */
+    isRequired: () => boolean;
+    /**
+     * The color channel that this field edits, or "hex" if no `channel` prop is set.
+     *
+     * @selector [data-channel="hex | hue | saturation | ..."]
+     */
+    channel: ColorChannel | "hex";
+    /** State of the color field. */
+    state: ColorFieldState | ColorChannelFieldState;
+}
+export interface ColorFieldProps extends Omit<AriaColorFieldProps, "label" | "placeholder" | "description" | "errorMessage" | "validationBehavior" | "locale" | "isInvalid" | "value">, RACValidation, RenderProps<ColorFieldRenderProps>, DOMRenderProps<"div", ColorFieldRenderProps>, SlotProps, Omit<GlobalDOMAttributes<HTMLDivElement>, "style" | "onInput" | "onBeforeInput" | "onCopy" | "onCut" | "onPaste" | "onSelect"> {
+    /** The current value (controlled): a two-way signal, a read-only accessor or a fixed value. */
+    value?: ColorInput<string | Color | null>;
+    /** Whether the value is invalid (a value, or an accessor that stays live). */
+    isInvalid?: MaybeAccessor<boolean | undefined>;
+    /**
+     * The color channel that this field edits. If not provided,
+     * the color is edited as a hex value.
+     */
+    channel?: ColorChannel;
+    /**
+     * The color space that the color field operates in if a `channel` prop is provided.
+     * If no `channel` is provided, the color field always displays the color as an RGB hex value.
+     */
+    colorSpace?: ColorSpace;
+    /**
+     * The CSS class for the element. A function may be provided to compute the class based on component state.
+     *
+     * @default 'rv-ColorField'
+     */
+    class?: RenderProps<ColorFieldRenderProps>["class"];
+    ref?: RefValue<HTMLDivElement>;
+}
+/** RAC `ColorFieldContext`. */
+export declare const ColorFieldContext: import("@rivetjs/reactivity").Context<ContextValue<Partial<ColorFieldProps>, HTMLDivElement>>;
+/** RAC `ColorFieldStateContext`. */
+export declare const ColorFieldStateContext: import("@rivetjs/reactivity").Context<ColorChannelFieldState | ColorFieldState | null>;
+/**
+ * A color field allows users to edit a hex color or individual color channel value.
+ */
+export declare function ColorField(props: ColorFieldProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement | null;