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

package/color/field-state.d.ts

@@ -0,0 +1,66 @@
+import { type Signal } from "@rivetjs/reactivity";
+import { type FormValidationOptions, type FormValidationState } from "@rivetjs/cdk/state/form-validation";
+import { type Color } from "./color.js";
+import { type ColorCell, type ColorInput } from "./value.js";
+export interface ColorFieldProps extends Omit<FormValidationOptions<Color | null>, "validate"> {
+    /** 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;
+    /** Custom client validation of the current value. */
+    validate?: (value: Color | null) => string | string[] | true | null | undefined;
+    /** Whether the input is disabled. */
+    isDisabled?: boolean;
+    /** Whether the input can be selected but not changed by the user. */
+    isReadOnly?: boolean;
+    /** Whether user input is required on the input before form submission. */
+    isRequired?: boolean;
+}
+export interface ColorFieldState {
+    readonly kind: "field";
+    readonly cell: ColorCell<string | Color | null | undefined>;
+    /** Whether `value` was given (upstream `value === undefined` check in `commit`). */
+    readonly controlled: boolean;
+    /** Input text and the color key it was typed against. */
+    readonly input: Signal<{
+        text: string;
+        key: string | null | undefined;
+    }>;
+    /** The default value of the color field (lossless color string, or null / undefined). */
+    readonly defaultColorValue: string | null | undefined;
+    /** Form validation state of the field. */
+    readonly validation: FormValidationState;
+    readonly onChange: ((color: Color | null) => void) | undefined;
+}
+/**
+ * Provides state management for a color field component. Color fields allow
+ * users to enter and adjust a hex color value.
+ */
+export declare function createColorFieldState(props: ColorFieldProps): ColorFieldState;
+/** The currently parsed color value, or null / undefined if the field is empty. */
+export declare const colorValue: (state: ColorFieldState) => Color | null | undefined;
+/** The default value of the color field. */
+export declare const defaultColorValue: (state: ColorFieldState) => Color | null | undefined;
+/** The current text value of the input. Updated as the user types, and formatted on commit. */
+export declare function inputValue(state: ColorFieldState): string;
+/** Sets the current text value of the input. */
+export declare function setInputValue(state: ColorFieldState, value: string): void;
+/** Sets the color value of the field. */
+export declare function setColorValue(state: ColorFieldState, value: Color | null): void;
+/** Updates the input value based on the currently parsed color value. Typically this is called when the field is blurred. */
+export declare function commit(state: ColorFieldState): void;
+/** Increments the current input value to the next step boundary, and fires `onChange`. */
+export declare const incrementColorField: (state: ColorFieldState) => void;
+/** Decrements the current input value to the next step boundary, and fires `onChange`. */
+export declare const decrementColorField: (state: ColorFieldState) => void;
+/** Sets the current value to the maximum color value, and fires `onChange`. */
+export declare const incrementToMax: (state: ColorFieldState) => void;
+/** Sets the current value to the minimum color value, and fires `onChange`. */
+export declare const decrementToMin: (state: ColorFieldState) => void;
+/**
+ * Validates a user input string. Values can be partially entered, and may be valid even if they
+ * cannot currently be parsed to a color. Can be used to implement validation as a user types.
+ */
+export declare const validate: (value: string) => boolean;

package/color/field-state.jsx

@@ -0,0 +1,159 @@
+// Ported from react-stately `useColorFieldState` (packages/react-stately/src/color/useColorFieldState.ts), Apache-2.0, © Adobe.
+// Rivet: plain signals + JSON (serializable); methods are free functions taking the state first
+// (`state.commit()` → `commit(state)`; `increment` / `decrement` dispatch on `state.kind` in `./index.ts`).
+// - Color stored as a string (`./value.ts`); `colorValue(state)` parses it.
+// - Upstream's "set state during render" sync (`prevValue !== colorValue` → reformat the input) is
+//   derived: the input signal stores `{ text, key }` (`key` = the color's `colorKey` when the text was
+//   set); while the color still has that key the text shows, otherwise the formatted color does.
+// - Upstream compares colors by identity (`newValue === colorValue`, useControlledState `Object.is`);
+//   here by `colorKey` (same space + channels).
+// - Validation = `createFormValidationState` (`state.validation`, functions from
+//   `@rivetjs/cdk/state/form-validation`); a user `validate` receives the parsed Color | null.
+import { signal, untrack, _regionState } from "@rivetjs/reactivity";
+import { commitValidation, createFormValidationState } from "@rivetjs/cdk/state/form-validation";
+import { colorKey, parseColor, stringifyColor, toColor } from "./color.js";
+import { colorCell, isColorSource, writeColor } from "./value.js";
+const MIN_COLOR = "#000000";
+const MAX_COLOR = "#FFFFFF";
+const hex = (color) => (color ? color.toString("hex") : "");
+/**
+ * Provides state management for a color field component. Color fields allow
+ * users to enter and adjust a hex color value.
+ */
+export function createColorFieldState(props) {
+    const { value, defaultValue, onChange } = props;
+    const initialDefaultValue = toColor(defaultValue);
+    const controlledInput = isColorSource(value) ? value : toColor(value);
+    const cell = colorCell(controlledInput, initialDefaultValue);
+    const initial = toColor(untrack(cell.read));
+    // Upstream validates `colorValue` (the parsed Color | null): with a custom `validate`, a resumable accessor (this
+    // module is .tsx; a wrapper around `validate` in a .ts module made a resumed ColorField with `validate` unserializable).
+    // Without one only `validate` reads the value: the raw cell (plain state, keeps the resume-table round trip).
+    const validation = createFormValidationState({
+        ...props,
+        value: props.validate ? validationValue(cell) : cell.read,
+    });
+    return {
+        kind: "field",
+        cell,
+        controlled: value !== undefined,
+        input: _regionState(() => signal({ text: (value || defaultValue) && initial ? hex(initial) : "", key: colorKey(initial) })),
+        defaultColorValue: initialDefaultValue ? stringifyColor(initialDefaultValue) : initial ? stringifyColor(initial) : initial,
+        validation,
+        onChange,
+    };
+}
+/** The value custom `validate` receives (upstream `colorValue`): a resumable accessor (R2 return value). */
+function validationValue(cell) {
+    return () => toColor(cell.read()) ?? null;
+}
+/** The currently parsed color value, or null / undefined if the field is empty. */
+export const colorValue = (state) => toColor(state.cell.read());
+/** The default value of the color field. */
+export const defaultColorValue = (state) => toColor(state.defaultColorValue);
+/** The current text value of the input. Updated as the user types, and formatted on commit. */
+export function inputValue(state) {
+    const color = colorValue(state);
+    const input = state.input();
+    return input.key === colorKey(color) ? input.text : hex(color);
+}
+/** Sets the current text value of the input. */
+export function setInputValue(state, value) {
+    setInputAt(state, value, colorKey(untrack(() => colorValue(state))));
+}
+function setInputAt(state, text, key) {
+    state.input.set({ text, key });
+}
+/** Sets the color value of the field. */
+export function setColorValue(state, value) {
+    writeColor(state.cell, value, state.onChange);
+}
+function safelySetColorValue(state, newColor) {
+    const current = untrack(() => colorValue(state));
+    if (!current || !newColor) {
+        setColorValue(state, newColor);
+        return;
+    }
+    if (newColor.toHexInt() !== current.toHexInt()) {
+        setColorValue(state, newColor);
+        return;
+    }
+}
+function parsedValue(state) {
+    const text = untrack(() => inputValue(state));
+    let color;
+    try {
+        color = parseColor(text.startsWith("#") ? text : `#${text}`);
+    }
+    catch {
+        color = null;
+    }
+    return color;
+}
+/** Updates the input value based on the currently parsed color value. Typically this is called when the field is blurred. */
+export function commit(state) {
+    const text = untrack(() => inputValue(state));
+    const current = untrack(() => colorValue(state));
+    // Upstream sets the input against the render-time color: a changed color then reformats it.
+    const key = colorKey(current);
+    // Set to empty state if input value is empty
+    if (!text.length) {
+        safelySetColorValue(state, null);
+        if (!state.controlled || current === null) {
+            setInputAt(state, "", key);
+        }
+        else {
+            setInputAt(state, hex(current), key);
+        }
+        return;
+    }
+    const parsed = parsedValue(state);
+    // if it failed to parse, then reset input to formatted version of current number
+    if (parsed == null) {
+        setInputAt(state, hex(current), key);
+        return;
+    }
+    safelySetColorValue(state, parsed);
+    // in a controlled state, the numberValue won't change, so we won't go back to our old input without help
+    setInputAt(state, hex(current), key);
+    commitValidation(state.validation);
+}
+function addColorValue(color, step) {
+    let newColor = color ? color : parseColor(MIN_COLOR);
+    const colorInt = newColor.toHexInt();
+    const minInt = parseColor(MIN_COLOR).toHexInt();
+    const maxInt = parseColor(MAX_COLOR).toHexInt();
+    const clampInt = Math.min(Math.max(colorInt + step, minInt), maxInt);
+    if (clampInt !== colorInt) {
+        const newColorString = `#${clampInt.toString(16).padStart(6, "0").toUpperCase()}`;
+        newColor = parseColor(newColorString);
+    }
+    return newColor;
+}
+function step(state, delta) {
+    const { step } = parseColor(MIN_COLOR).getChannelRange("red");
+    const newValue = addColorValue(parsedValue(state), delta * step);
+    const current = untrack(() => colorValue(state));
+    // if we've arrived at the same value that was previously in the state, the
+    // input value should be updated to match
+    // ex type 4, press increment, highlight the number in the input, type 4 again, press increment
+    // you'd be at 5, then incrementing to 5 again, so no re-render would happen and 4 would be left in the input
+    if (colorKey(newValue) === colorKey(current)) {
+        setInputAt(state, newValue.toString("hex"), colorKey(current));
+    }
+    safelySetColorValue(state, newValue);
+    commitValidation(state.validation);
+}
+/** Increments the current input value to the next step boundary, and fires `onChange`. */
+export const incrementColorField = (state) => step(state, 1);
+/** Decrements the current input value to the next step boundary, and fires `onChange`. */
+export const decrementColorField = (state) => step(state, -1);
+/** Sets the current value to the maximum color value, and fires `onChange`. */
+export const incrementToMax = (state) => safelySetColorValue(state, parseColor(MAX_COLOR));
+/** Sets the current value to the minimum color value, and fires `onChange`. */
+export const decrementToMin = (state) => safelySetColorValue(state, parseColor(MIN_COLOR));
+/**
+ * Validates a user input string. Values can be partially entered, and may be valid even if they
+ * cannot currently be parsed to a color. Can be used to implement validation as a user types.
+ */
+export const validate = (value) => value === "" || !!value.match(/^#?[0-9a-f]{0,6}$/i)?.[0];

package/color/index.d.ts

@@ -0,0 +1,58 @@
+import type { ColorAreaState } from "./area-state.js";
+import { type ColorChannelFieldState } from "./channel-field-state.jsx";
+import type { Color } from "./color.js";
+import { type ColorFieldState } from "./field-state.jsx";
+import { type ColorSliderState } from "./slider-state.jsx";
+import { type ColorWheelState } from "./wheel-state.js";
+export { parseColor, getColorChannels, normalizeColor, normalizeHue, toColor, stringifyColor, colorKey } from "./color.js";
+export type { Color, ColorChannel, ColorFormat, ColorSpace, ColorAxes, ColorChannelRange } from "./color.js";
+export type { ColorInput, ColorValue } from "./value.js";
+export { createColorAreaState, getChannels, getChannelSteps, getXValue, getYValue, setXValue, setYValue, setColorFromPoint, incrementX, incrementY, decrementX, decrementY, } from "./area-state.js";
+export type { ColorAreaProps, ColorAreaState } from "./area-state.js";
+export { createColorSliderState, sliderView } from "./slider-state.jsx";
+export type { ColorSliderProps, ColorSliderState, ColorSliderStateOptions } from "./slider-state.jsx";
+export { createColorWheelState, getHue, setHue, setHueFromPoint } from "./wheel-state.js";
+export type { ColorWheelProps, ColorWheelState } from "./wheel-state.js";
+export { createColorFieldState, inputValue, setInputValue, commit, incrementToMax, decrementToMin, validate } from "./field-state.jsx";
+export type { ColorFieldProps, ColorFieldState } from "./field-state.jsx";
+export { createColorChannelFieldState, numberFieldView } from "./channel-field-state.jsx";
+export type { ColorChannelFieldProps, ColorChannelFieldState, ColorChannelFieldStateOptions } from "./channel-field-state.jsx";
+export { createColorPickerState, getColor, setColor } from "./picker-state.js";
+export type { ColorPickerProps, ColorPickerState } from "./picker-state.js";
+type ValueState = ColorAreaState | ColorSliderState | ColorWheelState;
+/** The current color value (area: in `colorSpace`; slider: in `colorSpace`; wheel: hsl / hsb). */
+export declare function getValue(state: ValueState): Color;
+/** The default value (area, wheel). */
+export declare function getDefaultValue(state: ColorAreaState | ColorWheelState): Color;
+/** Sets the current color value (fires `onChange`). If a string is passed, it will be parsed to a Color. */
+export declare function setValue(state: ValueState, value: string | Color): void;
+/** Returns the color that should be displayed in the thumb / track instead of `value`. */
+export declare function getDisplayColor(state: ValueState): Color;
+/** Whether the area / slider / wheel is currently being dragged. */
+export declare function isDragging(state: ValueState): boolean;
+/** Sets whether the area / wheel is being dragged (`onChangeEnd` fires when a drag ends). Slider: `setThumbDragging(sliderView(state), 0, v)`. */
+export declare function setDragging(state: ColorAreaState | ColorWheelState, value: boolean): void;
+/** Thumb position: area — percentages from the upper left corner; wheel — coordinates from the center for `radius`. */
+export declare function getThumbPosition(state: ColorAreaState): {
+    x: number;
+    y: number;
+};
+export declare function getThumbPosition(state: ColorWheelState, radius: number): {
+    x: number;
+    y: number;
+};
+/** Wheel: increments the hue by `stepSize` (default 1). Field: increments the hex value by one step. */
+export declare function increment(state: ColorWheelState | ColorFieldState, stepSize?: number): void;
+/** Wheel: decrements the hue by `stepSize` (default 1). Field: decrements the hex value by one step. */
+export declare function decrement(state: ColorWheelState | ColorFieldState, stepSize?: number): void;
+/** Color slider: the channel value formatted for the slider's locale. */
+export declare const getThumbValueLabel: (state: ColorSliderState) => string;
+/** Color slider: the channel value formatted for the slider's locale. */
+export declare const getFormattedValue: (state: ColorSliderState) => string;
+/** Field: the parsed color (null / undefined when empty). Channel field: the color (black when empty). */
+export declare function colorValue(state: ColorFieldState): Color | null | undefined;
+export declare function colorValue(state: ColorChannelFieldState): Color;
+/** The default value of the field. */
+export declare function defaultColorValue(state: ColorFieldState | ColorChannelFieldState): Color | null | undefined;
+/** Sets the color value of the field (fires `onChange`). */
+export declare function setColorValue(state: ColorFieldState | ColorChannelFieldState, value: Color | null): void;

package/color/index.js

@@ -0,0 +1,88 @@
+// Ported from @react-stately/color (packages/@react-stately/color/src/index.ts → react-stately src/color/*), Apache-2.0, © Adobe.
+// Rivet: `use*State` hooks → `create*State` factories (plain signals + JSON, resumable); state members are
+// free functions taking the state first. Members shared by several upstream states (`value`, `setValue`,
+// `getDisplayColor`, `isDragging`, `setDragging`, `getThumbPosition`, `increment`, `decrement`,
+// `colorValue`, `defaultColorValue`, `setColorValue`) dispatch on `state.kind`.
+import { getColorAreaDisplayColor, getColorAreaThumbPosition, colorAreaDefaultValue, colorAreaValue, setColorAreaDragging, setColorAreaValue, } from "./area-state.js";
+import { channelFieldColorValue, channelFieldDefaultColorValue, setChannelFieldColorValue } from "./channel-field-state.jsx";
+import { colorValue as fieldColorValue, decrementColorField, defaultColorValue as fieldDefaultColorValue, incrementColorField, setColorValue as setFieldColorValue, } from "./field-state.jsx";
+import { colorSliderValue, getColorSliderDisplayColor, getColorSliderFormattedValue, getColorSliderThumbValueLabel, isColorSliderDragging, setColorSliderValue, } from "./slider-state.jsx";
+import { colorWheelDefaultValue, colorWheelValue, decrementHue, getColorWheelDisplayColor, getColorWheelThumbPosition, incrementHue, setColorWheelDragging, setColorWheelValue, } from "./wheel-state.js";
+export { parseColor, getColorChannels, normalizeColor, normalizeHue, toColor, stringifyColor, colorKey } from "./color.js";
+export { createColorAreaState, getChannels, getChannelSteps, getXValue, getYValue, setXValue, setYValue, setColorFromPoint, incrementX, incrementY, decrementX, decrementY, } from "./area-state.js";
+export { createColorSliderState, sliderView } from "./slider-state.jsx";
+export { createColorWheelState, getHue, setHue, setHueFromPoint } from "./wheel-state.js";
+export { createColorFieldState, inputValue, setInputValue, commit, incrementToMax, decrementToMin, validate } from "./field-state.jsx";
+export { createColorChannelFieldState, numberFieldView } from "./channel-field-state.jsx";
+export { createColorPickerState, getColor, setColor } from "./picker-state.js";
+/** The current color value (area: in `colorSpace`; slider: in `colorSpace`; wheel: hsl / hsb). */
+export function getValue(state) {
+    return state.kind === "area" ? colorAreaValue(state) : state.kind === "slider" ? colorSliderValue(state) : colorWheelValue(state);
+}
+/** The default value (area, wheel). */
+export function getDefaultValue(state) {
+    return state.kind === "area" ? colorAreaDefaultValue(state) : colorWheelDefaultValue(state);
+}
+/** Sets the current color value (fires `onChange`). If a string is passed, it will be parsed to a Color. */
+export function setValue(state, value) {
+    if (state.kind === "area")
+        setColorAreaValue(state, value);
+    else if (state.kind === "slider")
+        setColorSliderValue(state, value);
+    else
+        setColorWheelValue(state, value);
+}
+/** Returns the color that should be displayed in the thumb / track instead of `value`. */
+export function getDisplayColor(state) {
+    return state.kind === "area"
+        ? getColorAreaDisplayColor(state)
+        : state.kind === "slider"
+            ? getColorSliderDisplayColor(state)
+            : getColorWheelDisplayColor(state);
+}
+/** Whether the area / slider / wheel is currently being dragged. */
+export function isDragging(state) {
+    return state.kind === "slider" ? isColorSliderDragging(state) : state.dragging();
+}
+/** Sets whether the area / wheel is being dragged (`onChangeEnd` fires when a drag ends). Slider: `setThumbDragging(sliderView(state), 0, v)`. */
+export function setDragging(state, value) {
+    if (state.kind === "area")
+        setColorAreaDragging(state, value);
+    else
+        setColorWheelDragging(state, value);
+}
+export function getThumbPosition(state, radius) {
+    return state.kind === "area" ? getColorAreaThumbPosition(state) : getColorWheelThumbPosition(state, radius);
+}
+/** Wheel: increments the hue by `stepSize` (default 1). Field: increments the hex value by one step. */
+export function increment(state, stepSize) {
+    if (state.kind === "wheel")
+        incrementHue(state, stepSize);
+    else
+        incrementColorField(state);
+}
+/** Wheel: decrements the hue by `stepSize` (default 1). Field: decrements the hex value by one step. */
+export function decrement(state, stepSize) {
+    if (state.kind === "wheel")
+        decrementHue(state, stepSize);
+    else
+        decrementColorField(state);
+}
+/** Color slider: the channel value formatted for the slider's locale. */
+export const getThumbValueLabel = (state) => getColorSliderThumbValueLabel(state);
+/** Color slider: the channel value formatted for the slider's locale. */
+export const getFormattedValue = (state) => getColorSliderFormattedValue(state);
+export function colorValue(state) {
+    return state.kind === "field" ? fieldColorValue(state) : channelFieldColorValue(state);
+}
+/** The default value of the field. */
+export function defaultColorValue(state) {
+    return state.kind === "field" ? fieldDefaultColorValue(state) : channelFieldDefaultColorValue(state);
+}
+/** Sets the color value of the field (fires `onChange`). */
+export function setColorValue(state, value) {
+    if (state.kind === "field")
+        setFieldColorValue(state, value);
+    else
+        setChannelFieldColorValue(state, value);
+}

package/color/intl.d.ts

@@ -0,0 +1,3 @@
+import type { LocalizedStrings } from "@rivetjs/cdk/i18n";
+export type ColorMessageKey = "hue" | "saturation" | "lightness" | "brightness" | "red" | "green" | "blue" | "alpha" | "colorName" | "transparentColorName" | "very dark" | "dark" | "light" | "very light" | "pale" | "grayish" | "vibrant" | "black" | "white" | "gray" | "pink" | "pink red" | "red orange" | "brown" | "orange" | "orange yellow" | "brown yellow" | "yellow" | "yellow green" | "green cyan" | "cyan" | "cyan blue" | "blue purple" | "purple" | "purple magenta" | "magenta" | "magenta pink";
+export declare const colorMessages: LocalizedStrings<ColorMessageKey>;