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

package/color/area-state.js

@@ -0,0 +1,160 @@
+// Ported from react-stately `useColorAreaState` (packages/react-stately/src/color/useColorAreaState.ts), Apache-2.0, © Adobe.
+// Rivet: plain signals + JSON (serializable); methods are free functions taking the state first
+// (`state.setXValue(v)` → `setXValue(state, v)`; shared names `getValue` / `setValue` / `getDisplayColor` /
+// `isDragging` / `setDragging` / `getThumbPosition` dispatch on `state.kind` in `./index.ts`). Values that
+// upstream recomputes per render (`value`, `channels`, `xValue`, steps) are accessors. Color stored as a
+// string (`./value.ts`); `valueRef` / `isDraggingRef` → `state.refs`.
+import { signal, untrack, _regionState } from "@rivetjs/reactivity";
+import { clamp, snapValueToStep } from "@rivetjs/cdk/utils";
+import { normalizeColor, parseColor, stringifyColor } from "./color.js";
+import { colorCell, writeColor } from "./value.js";
+const DEFAULT_COLOR = "#ffffff";
+/**
+ * Provides state management for a color area component. Color area allows users to adjust two
+ * channels of an HSL, HSB or RGB color value against a two-dimensional gradient background.
+ */
+export function createColorAreaState(props) {
+    let { value, defaultValue } = props;
+    const { colorSpace, xChannel, yChannel, onChange, onChangeEnd } = props;
+    if (!value && !defaultValue) {
+        defaultValue = DEFAULT_COLOR;
+    }
+    const cell = colorCell(value, (defaultValue ?? DEFAULT_COLOR));
+    const initialValue = normalizeColor(untrack(cell.read));
+    // Rivet (live props): an `isDisabled` accessor is stored as given (`isColorAreaDisabled` reads it).
+    const disabled = typeof props.isDisabled === "function" ? props.isDisabled : undefined;
+    const state = {
+        kind: "area",
+        cell,
+        colorSpace,
+        xChannel,
+        yChannel,
+        isDisabled: disabled ? !!untrack(disabled) : (props.isDisabled ?? false),
+        ...(disabled ? { disabled } : {}),
+        defaultValue: stringifyColor(value !== undefined ? initialValue : normalizeColor(defaultValue)),
+        dragging: _regionState(() => signal(false)),
+        onChange,
+        onChangeEnd,
+        refs: { value: stringifyColor(colorSpace ? initialValue.toFormat(colorSpace) : initialValue), dragging: false },
+    };
+    return state;
+}
+/** Whether the color area is disabled now (its live `isDisabled` accessor, else the creation value). */
+export const isColorAreaDisabled = (state) => (state.disabled ? !!state.disabled() : state.isDisabled);
+/** The current color value displayed by the color area (in `colorSpace` when given). */
+export function colorAreaValue(state) {
+    const colorValue = normalizeColor(state.cell.read());
+    return state.colorSpace && colorValue ? colorValue.toFormat(state.colorSpace) : colorValue;
+}
+/** The default value of the color area. */
+export const colorAreaDefaultValue = (state) => parseColor(state.defaultValue);
+function setColor(state, color) {
+    state.refs.value = stringifyColor(color);
+    writeColor(state.cell, color, state.onChange);
+}
+/** Sets the current color value. If a string is passed, it will be parsed to a Color. */
+export function setColorAreaValue(state, value) {
+    setColor(state, normalizeColor(value));
+}
+/** Returns the xChannel, yChannel and zChannel names based on the color value. */
+export function getChannels(state) {
+    return colorAreaValue(state).getColorSpaceAxes({ xChannel: state.xChannel, yChannel: state.yChannel });
+}
+/** Step / page step of the x and y channels (upstream `xChannelStep`, `yChannelStep`, `xChannelPageStep`, `yChannelPageStep`). */
+export function getChannelSteps(state) {
+    const color = colorAreaValue(state);
+    const channels = getChannels(state);
+    const x = color.getChannelRange(channels.xChannel);
+    const y = color.getChannelRange(channels.yChannel);
+    return { xChannelStep: x.step, yChannelStep: y.step, xChannelPageStep: x.pageSize, yChannelPageStep: y.pageSize };
+}
+function ranges(state) {
+    const color = colorAreaValue(state);
+    const channels = color.getColorSpaceAxes({ xChannel: state.xChannel, yChannel: state.yChannel });
+    const { minValue: minValueX, maxValue: maxValueX, step: stepX } = color.getChannelRange(channels.xChannel);
+    const { minValue: minValueY, maxValue: maxValueY, step: stepY } = color.getChannelRange(channels.yChannel);
+    const xValue = color.getChannelValue(channels.xChannel);
+    const yValue = color.getChannelValue(channels.yChannel);
+    return { color, channels, minValueX, maxValueX, stepX, minValueY, maxValueY, stepY, xValue, yValue };
+}
+/** The current value of the horizontal axis channel displayed by the color area. */
+export const getXValue = (state) => colorAreaValue(state).getChannelValue(getChannels(state).xChannel);
+/** The current value of the vertical axis channel displayed by the color area. */
+export const getYValue = (state) => colorAreaValue(state).getChannelValue(getChannels(state).yChannel);
+/** Sets the value for the horizontal axis channel displayed by the color area, and triggers `onChange`. */
+export function setXValue(state, v) {
+    const { color, channels, xValue } = untrack(() => ranges(state));
+    if (v === xValue) {
+        return;
+    }
+    setColor(state, color.withChannelValue(channels.xChannel, v));
+}
+/** Sets the value for the vertical axis channel displayed by the color area, and triggers `onChange`. */
+export function setYValue(state, v) {
+    const { color, channels, yValue } = untrack(() => ranges(state));
+    if (v === yValue) {
+        return;
+    }
+    setColor(state, color.withChannelValue(channels.yChannel, v));
+}
+/**
+ * Sets the x and y channels of the current color value based on a percentage of the width and
+ * height of the color area, and triggers `onChange`.
+ */
+export function setColorFromPoint(state, x, y) {
+    const { color, channels, minValueX, maxValueX, stepX, minValueY, maxValueY, stepY, xValue, yValue } = untrack(() => ranges(state));
+    let newXValue = minValueX + clamp(x, 0, 1) * (maxValueX - minValueX);
+    let newYValue = minValueY + (1 - clamp(y, 0, 1)) * (maxValueY - minValueY);
+    let newColor;
+    if (newXValue !== xValue) {
+        // Round new value to multiple of step, clamp value between min and max
+        newXValue = snapValueToStep(newXValue, minValueX, maxValueX, stepX);
+        newColor = color.withChannelValue(channels.xChannel, newXValue);
+    }
+    if (newYValue !== yValue) {
+        // Round new value to multiple of step, clamp value between min and max
+        newYValue = snapValueToStep(newYValue, minValueY, maxValueY, stepY);
+        newColor = (newColor || color).withChannelValue(channels.yChannel, newYValue);
+    }
+    if (newColor) {
+        setColor(state, newColor);
+    }
+}
+/** Returns the coordinates of the thumb relative to the upper left corner of the color area as a percentage. */
+export function getColorAreaThumbPosition(state) {
+    const { minValueX, maxValueX, minValueY, maxValueY, xValue, yValue } = ranges(state);
+    const x = (xValue - minValueX) / (maxValueX - minValueX);
+    const y = 1 - (yValue - minValueY) / (maxValueY - minValueY);
+    return { x, y };
+}
+/** Increments the value of the horizontal axis channel by the channel step or page amount. */
+export function incrementX(state, stepSize = 1) {
+    const { minValueX, maxValueX, stepX, xValue } = untrack(() => ranges(state));
+    setXValue(state, xValue + stepSize > maxValueX ? maxValueX : snapValueToStep(xValue + stepSize, minValueX, maxValueX, stepX));
+}
+/** Increments the value of the vertical axis channel by the channel step or page amount. */
+export function incrementY(state, stepSize = 1) {
+    const { minValueY, maxValueY, stepY, yValue } = untrack(() => ranges(state));
+    setYValue(state, yValue + stepSize > maxValueY ? maxValueY : snapValueToStep(yValue + stepSize, minValueY, maxValueY, stepY));
+}
+/** Decrements the value of the horizontal axis channel by the channel step or page amount. */
+export function decrementX(state, stepSize = 1) {
+    const { minValueX, maxValueX, stepX, xValue } = untrack(() => ranges(state));
+    setXValue(state, snapValueToStep(xValue - stepSize, minValueX, maxValueX, stepX));
+}
+/** Decrements the value of the vertical axis channel by the channel step or page amount. */
+export function decrementY(state, stepSize = 1) {
+    const { minValueY, maxValueY, stepY, yValue } = untrack(() => ranges(state));
+    setYValue(state, snapValueToStep(yValue - stepSize, minValueY, maxValueY, stepY));
+}
+/** Sets whether the color area is being dragged (fires `onChangeEnd` when a drag ends). */
+export function setColorAreaDragging(state, isDragging) {
+    const wasDragging = state.refs.dragging;
+    state.refs.dragging = isDragging;
+    if (state.onChangeEnd && !isDragging && wasDragging) {
+        state.onChangeEnd(parseColor(state.refs.value));
+    }
+    state.dragging.set(isDragging);
+}
+/** Returns the color that should be displayed in the color area thumb instead of `value`. */
+export const getColorAreaDisplayColor = (state) => colorAreaValue(state).withChannelValue("alpha", 1);

package/color/aria-intl.d.ts

@@ -0,0 +1,3 @@
+import type { LocalizedStrings } from "@rivetjs/cdk/i18n";
+export type ColorAriaMessageKey = "colorInputLabel" | "colorNameAndValue" | "colorPicker" | "colorSwatch" | "transparent" | "twoDimensionalSlider";
+export declare const colorAriaMessages: LocalizedStrings<ColorAriaMessageKey>;

package/color/aria-intl.js

@@ -0,0 +1,274 @@
+export const colorAriaMessages = {
+    "ar-AE": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "أداة انتقاء اللون",
+        colorSwatch: "تغيير الألوان",
+        transparent: "شفاف",
+        twoDimensionalSlider: "مُنزلق 2D",
+    },
+    "bg-BG": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Средство за избиране на цвят",
+        colorSwatch: "цветна мостра",
+        transparent: "прозрачен",
+        twoDimensionalSlider: "2D плъзгач",
+    },
+    "cs-CZ": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Výběr barvy",
+        colorSwatch: "barevný vzorek",
+        transparent: "průhledný",
+        twoDimensionalSlider: "2D posuvník",
+    },
+    "da-DK": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Farvevælger",
+        colorSwatch: "farveprøve",
+        transparent: "gennemsigtig",
+        twoDimensionalSlider: "2D-skyder",
+    },
+    "de-DE": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Farbwähler",
+        colorSwatch: "Farbfeld",
+        transparent: "transparent",
+        twoDimensionalSlider: "2D-Schieberegler",
+    },
+    "el-GR": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Επιλογέας χρωμάτων",
+        colorSwatch: "χρωματικό δείγμα",
+        transparent: "διαφανές",
+        twoDimensionalSlider: "Ρυθμιστικό 2D",
+    },
+    "en-US": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Color picker",
+        colorSwatch: "color swatch",
+        transparent: "transparent",
+        twoDimensionalSlider: "2D slider",
+    },
+    "es-ES": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Selector de color",
+        colorSwatch: "muestra de color",
+        transparent: "transparente",
+        twoDimensionalSlider: "Regulador 2D",
+    },
+    "et-EE": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Värvivalija",
+        colorSwatch: "värvinäidis",
+        transparent: "läbipaistev",
+        twoDimensionalSlider: "2D-liugur",
+    },
+    "fi-FI": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Värimuokkain",
+        colorSwatch: "värimalli",
+        transparent: "läpinäkyvä",
+        twoDimensionalSlider: "2D-liukusäädin",
+    },
+    "fr-FR": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name} : {value}",
+        colorPicker: "Sélecteur de couleurs",
+        colorSwatch: "Échantillon de couleurs",
+        transparent: "Transparent",
+        twoDimensionalSlider: "Curseur 2D",
+    },
+    "he-IL": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "בוחר הצבעים",
+        colorSwatch: "דוגמית צבע",
+        transparent: "שקוף",
+        twoDimensionalSlider: "מחוון דו מימדי",
+    },
+    "hr-HR": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Odabir boje",
+        colorSwatch: "uzorak boje",
+        transparent: "transparentno",
+        twoDimensionalSlider: "2D klizač",
+    },
+    "hu-HU": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Színválasztó",
+        colorSwatch: "színtár",
+        transparent: "átlátszó",
+        twoDimensionalSlider: "2D-csúszka",
+    },
+    "it-IT": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Selettore colore",
+        colorSwatch: "campione di colore",
+        transparent: "trasparente",
+        twoDimensionalSlider: "Cursore 2D",
+    },
+    "ja-JP": {
+        colorInputLabel: "{label}、{channelLabel}",
+        colorNameAndValue: "{name} : {value}",
+        colorPicker: "カラーピッカー",
+        colorSwatch: "カラースウォッチ",
+        transparent: "透明",
+        twoDimensionalSlider: "2D スライダー",
+    },
+    "ko-KR": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "색상 피커",
+        colorSwatch: "색상 견본",
+        transparent: "투명도",
+        twoDimensionalSlider: "2D 슬라이더",
+    },
+    "lt-LT": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Spalvų parinkiklis",
+        colorSwatch: "spalvų pavyzdys",
+        transparent: "skaidrus",
+        twoDimensionalSlider: "2D slankiklis",
+    },
+    "lv-LV": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Krāsu atlasītājs",
+        colorSwatch: "krāsu paraugs",
+        transparent: "caurspīdīgs",
+        twoDimensionalSlider: "2D slīdnis",
+    },
+    "nb-NO": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Fargevelger",
+        colorSwatch: "fargekart",
+        transparent: "gjennomsiktig",
+        twoDimensionalSlider: "2D-glidebryter",
+    },
+    "nl-NL": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Kleurkiezer",
+        colorSwatch: "kleurstaal",
+        transparent: "transparant",
+        twoDimensionalSlider: "2D-schuifregelaar",
+    },
+    "pl-PL": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Próbnik kolorów",
+        colorSwatch: "próbka koloru",
+        transparent: "przezroczysty",
+        twoDimensionalSlider: "Suwak 2D",
+    },
+    "pt-BR": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Seletor de cores",
+        colorSwatch: "amostra de cores",
+        transparent: "transparente",
+        twoDimensionalSlider: "Controle deslizante 2D",
+    },
+    "pt-PT": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Seletor de cores",
+        colorSwatch: "amostra de cor",
+        transparent: "transparente",
+        twoDimensionalSlider: "Controle deslizante 2D",
+    },
+    "ro-RO": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Selector de culori",
+        colorSwatch: "specimen de culoare",
+        transparent: "transparent",
+        twoDimensionalSlider: "Glisor 2D",
+    },
+    "ru-RU": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Палитра цветов",
+        colorSwatch: "цветовой образец",
+        transparent: "прозрачный",
+        twoDimensionalSlider: "Ползунок 2D",
+    },
+    "sk-SK": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Výber farieb",
+        colorSwatch: "vzorkovník farieb",
+        transparent: "transparentný",
+        twoDimensionalSlider: "2D jazdec",
+    },
+    "sl-SI": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Izbirnik barv",
+        colorSwatch: "barvna paleta",
+        transparent: "prozorno",
+        twoDimensionalSlider: "2D drsnik",
+    },
+    "sr-SP": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Birač boja",
+        colorSwatch: "Uzorak boje",
+        transparent: "providno",
+        twoDimensionalSlider: "2D klizač",
+    },
+    "sv-SE": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Färgväljaren",
+        colorSwatch: "färgruta",
+        transparent: "genomskinlig",
+        twoDimensionalSlider: "2D-reglage",
+    },
+    "tr-TR": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Renk Seçici",
+        colorSwatch: "renk örneği",
+        transparent: "saydam",
+        twoDimensionalSlider: "2D sürgü",
+    },
+    "uk-UA": {
+        colorInputLabel: "{label}, {channelLabel}",
+        colorNameAndValue: "{name}: {value}",
+        colorPicker: "Палітра кольорів",
+        colorSwatch: "зразок кольору",
+        transparent: "прозорий",
+        twoDimensionalSlider: "Повзунок 2D",
+    },
+    "zh-CN": {
+        colorInputLabel: "{label}、{channelLabel}",
+        colorNameAndValue: "{name}：{value}",
+        colorPicker: "拾色器",
+        colorSwatch: "颜色色板",
+        transparent: "透明",
+        twoDimensionalSlider: "2D 滑块",
+    },
+    "zh-TW": {
+        colorInputLabel: "{label}，{channelLabel}",
+        colorNameAndValue: "{name}：{value}",
+        colorPicker: "檢色器",
+        colorSwatch: "色票",
+        transparent: "透明",
+        twoDimensionalSlider: "2D 滑桿",
+    },
+};

package/color/channel-field-state.d.ts

@@ -0,0 +1,50 @@
+import { type NumberFieldState } from "../number/number-field-state.jsx";
+import { type Color, type ColorChannel, type ColorSpace } from "./color.js";
+import { type ColorCell, type ColorInput } from "./value.js";
+export interface ColorChannelFieldProps {
+    /** The current value (controlled): a two-way signal or a fixed value. */
+    value?: ColorInput<string | Color | null>;
+    /** The default value (uncontrolled). */
+    defaultValue?: string | Color | null;
+    /** Handler that is called when the value changes. */
+    onChange?: (color: Color | null) => void;
+    colorSpace?: ColorSpace;
+    channel: ColorChannel;
+    /** Whether the input is disabled. */
+    isDisabled?: boolean;
+    /** Whether the input can be selected but not changed by the user. */
+    isReadOnly?: boolean;
+}
+export interface ColorChannelFieldStateOptions extends ColorChannelFieldProps {
+    locale: string;
+}
+export interface ColorChannelFieldState {
+    readonly kind: "channel-field";
+    readonly cell: ColorCell<string | Color | null | undefined>;
+    readonly channel: ColorChannel;
+    readonly colorSpace: ColorSpace | undefined;
+    /** Percent channels with a 0–100 range are edited as 0–1 (upstream `multiplier`). */
+    readonly multiplier: number;
+    /** The default value of the field (lossless color string, or null). */
+    readonly defaultColorValue: string | null;
+    /** Stored number field data; use `numberFieldView(state)` with the number field functions. */
+    readonly numberField: NumberFieldState;
+    readonly onChange: ((color: Color | null) => void) | undefined;
+}
+/**
+ * Provides state management for a color channel field, allowing users to edit the
+ * value of an individual color channel.
+ */
+export declare function createColorChannelFieldState(props: ColorChannelFieldStateOptions): ColorChannelFieldState;
+/** The current value of the field (black when empty, in `colorSpace` when given). */
+export declare const channelFieldColorValue: (state: ColorChannelFieldState) => Color;
+/** The default value of the field. */
+export declare const channelFieldDefaultColorValue: (state: ColorChannelFieldState) => Color | null;
+/** Sets the color value of the field. */
+export declare function setChannelFieldColorValue(state: ColorChannelFieldState, value: Color | null): void;
+/**
+ * Transient `NumberFieldState` over the color channel (upstream: the spread `useNumberFieldState`
+ * result): controlled by the channel value, `onChange` writes the color (NaN → null). Build it per
+ * call; never store it (it holds closures).
+ */
+export declare function numberFieldView(state: ColorChannelFieldState): NumberFieldState;

package/color/channel-field-state.jsx

@@ -0,0 +1,87 @@
+// Ported from react-stately `useColorChannelFieldState` (packages/react-stately/src/color/useColorChannelFieldState.ts), Apache-2.0, © Adobe.
+// Rivet: plain signals + JSON (serializable); methods are free functions taking the state first.
+// Upstream spreads `useNumberFieldState` into the result; here `state.numberField` is the stored
+// `NumberFieldState` data (input text, sync record) and `numberFieldView(state)` builds, per call, a
+// transient `NumberFieldState` whose value reads the color channel (÷ multiplier) and whose writes set
+// the color — pass it to the `@rivetjs/cdk/number` functions (`commit(numberFieldView(state))`).
+// Color stored as a string (`./value.ts`).
+import { untrack } from "@rivetjs/reactivity";
+import { createNumberFieldState } from "../number/number-field-state.jsx";
+import { parseColor, stringifyColor, toColor } from "./color.js";
+import { colorCell, isColorSource, writeColor } from "./value.js";
+const BLACK = "#000";
+function convertColor(colorValue, colorSpace) {
+    const nonNullColorValue = colorValue || parseColor(BLACK);
+    return colorSpace && nonNullColorValue ? nonNullColorValue.toFormat(colorSpace) : nonNullColorValue;
+}
+/**
+ * Provides state management for a color channel field, allowing users to edit the
+ * value of an individual color channel.
+ */
+export function createColorChannelFieldState(props) {
+    const { channel, colorSpace, locale } = props;
+    const initialValue = isColorSource(props.value) ? props.value : toColor(props.value);
+    const initialDefaultValue = toColor(props.defaultValue);
+    const cell = colorCell(initialValue, initialDefaultValue ?? null);
+    const colorValue = toColor(untrack(cell.read)) ?? null;
+    const color = convertColor(colorValue, colorSpace);
+    const defaultColorValue = initialDefaultValue ?? colorValue;
+    const defaultColor = convertColor(defaultColorValue, colorSpace);
+    const value = color.getChannelValue(channel);
+    const range = color.getChannelRange(channel);
+    const formatOptions = color.getChannelFormatOptions(channel);
+    const multiplier = formatOptions.style === "percent" && range.maxValue === 100 ? 100 : 1;
+    const numberField = createNumberFieldState({
+        locale,
+        value: colorValue === null ? NaN : value / multiplier,
+        defaultValue: defaultColorValue === null ? NaN : defaultColor.getChannelValue(channel) / multiplier,
+        minValue: range.minValue / multiplier,
+        maxValue: range.maxValue / multiplier,
+        step: range.step / multiplier,
+        formatOptions,
+    });
+    return {
+        kind: "channel-field",
+        cell,
+        channel,
+        colorSpace,
+        multiplier,
+        defaultColorValue: defaultColorValue ? stringifyColor(defaultColorValue) : null,
+        numberField,
+        onChange: props.onChange,
+    };
+}
+/** The current value of the field (black when empty, in `colorSpace` when given). */
+export const channelFieldColorValue = (state) => convertColor(toColor(state.cell.read()), state.colorSpace);
+/** The default value of the field. */
+export const channelFieldDefaultColorValue = (state) => toColor(state.defaultColorValue) ?? null;
+/** Sets the color value of the field. */
+export function setChannelFieldColorValue(state, value) {
+    writeColor(state.cell, value, state.onChange);
+}
+/**
+ * Transient `NumberFieldState` over the color channel (upstream: the spread `useNumberFieldState`
+ * result): controlled by the channel value, `onChange` writes the color (NaN → null). Build it per
+ * call; never store it (it holds closures).
+ */
+export function numberFieldView(state) {
+    const read = () => {
+        const colorValue = toColor(state.cell.read());
+        return colorValue == null ? NaN : convertColor(colorValue, state.colorSpace).getChannelValue(state.channel) / state.multiplier;
+    };
+    return {
+        ...state.numberField,
+        value: read,
+        controlled: true,
+        fixed: true,
+        onChange: (v) => {
+            if (!Number.isNaN(v)) {
+                const color = untrack(() => channelFieldColorValue(state));
+                setChannelFieldColorValue(state, color.withChannelValue(state.channel, v * state.multiplier));
+            }
+            else {
+                setChannelFieldColorValue(state, null);
+            }
+        },
+    };
+}

package/color/color.d.ts

@@ -0,0 +1,78 @@
+/** A list of supported color formats. */
+export type ColorFormat = "hex" | "hexa" | "rgb" | "rgba" | "hsl" | "hsla" | "hsb" | "hsba";
+export type ColorSpace = "rgb" | "hsl" | "hsb";
+/** A list of color channels. */
+export type ColorChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue" | "alpha";
+export type ColorAxes = {
+    xChannel: ColorChannel;
+    yChannel: ColorChannel;
+    zChannel: ColorChannel;
+};
+export interface ColorChannelRange {
+    /** The minimum value of the color channel. */
+    minValue: number;
+    /** The maximum value of the color channel. */
+    maxValue: number;
+    /** The step value of the color channel, used when incrementing and decrementing. */
+    step: number;
+    /** The page step value of the color channel, used when incrementing and decrementing. */
+    pageSize: number;
+}
+/** Represents a color value. */
+export interface Color {
+    /** Converts the color to the given color format, and returns a new Color object. */
+    toFormat(format: ColorFormat): Color;
+    /** Converts the color to a string in the given format. */
+    toString(format?: ColorFormat | "css"): string;
+    /** Returns a duplicate of the color value. */
+    clone(): Color;
+    /** Converts the color to hex, and returns an integer representation. */
+    toHexInt(): number;
+    /**
+     * Returns the numeric value for a given channel.
+     * Throws an error if the channel is unsupported in the current color format.
+     */
+    getChannelValue(channel: ColorChannel): number;
+    /**
+     * Sets the numeric value for a given channel, and returns a new Color object.
+     * Throws an error if the channel is unsupported in the current color format.
+     */
+    withChannelValue(channel: ColorChannel, value: number): Color;
+    /** Returns the minimum, maximum, and step values for a given channel. */
+    getChannelRange(channel: ColorChannel): ColorChannelRange;
+    /** Returns a localized color channel name for a given channel and locale, for use in visual or accessibility labels. */
+    getChannelName(channel: ColorChannel, locale: string): string;
+    /** Returns the number formatting options for the given channel. */
+    getChannelFormatOptions(channel: ColorChannel): Intl.NumberFormatOptions;
+    /** Formats the numeric value for a given channel for display according to the provided locale. */
+    formatChannelValue(channel: ColorChannel, locale: string): string;
+    /** Returns the color space, 'rgb', 'hsb' or 'hsl', for the current color. */
+    getColorSpace(): ColorSpace;
+    /** Returns the color space axes, xChannel, yChannel, zChannel. */
+    getColorSpaceAxes(xyChannels: {
+        xChannel?: ColorChannel;
+        yChannel?: ColorChannel;
+    }): ColorAxes;
+    /** Returns an array of the color channels within the current color space space. */
+    getColorChannels(): [ColorChannel, ColorChannel, ColorChannel];
+    /** Returns a localized name for the color, for use in visual or accessibility labels. */
+    getColorName(locale: string): string;
+    /** Returns a localized name for the hue, for use in visual or accessibility labels. */
+    getHueName(locale: string): string;
+}
+/** Parses a color from a string value. Throws an error if the string could not be parsed. */
+export declare function parseColor(value: string): Color;
+export declare function normalizeColor(v: string | Color): Color;
+/** react-stately `useColor`: parses a string (invalid → `undefined`), passes a Color / null / undefined through. */
+export declare function toColor(value: string | Color | undefined | null): Color | null | undefined;
+/** Returns a list of color channels for a given color space. */
+export declare function getColorChannels(colorSpace: ColorSpace): [ColorChannel, ColorChannel, ColorChannel];
+/** Returns the hue value normalized to the range of 0 to 360. */
+export declare function normalizeHue(hue: number): number;
+/**
+ * Rivet: lossless string form of `color` in its own color space (`rgba(…)`, `hsla(…)`, `hsba(…)` with
+ * unrounded channels); `parseColor(stringifyColor(c))` restores the same space and channel values.
+ */
+export declare function stringifyColor(color: Color): string;
+/** Rivet: identity key of a stored color value (string or Color): `stringifyColor` of the parsed value; invalid strings → `undefined`, null / undefined pass through. */
+export declare function colorKey(value: string | Color | null | undefined): string | null | undefined;