ropav 0.2.0 → 0.3.0

package/dist/composables/use-color-area.js

@@ -0,0 +1,343 @@
+import { useLocale } from "./use-locale.js";
+import { useLocalizedStringFormatter } from "./use-localized-string-formatter.js";
+import { colorStrings } from "../i18n/color.js";
+import { useFormReset } from "./use-form-reset.js";
+import { visuallyHiddenStyle } from "../utils/visually-hidden.js";
+import { useLabels } from "./use-labels.js";
+import { setFormValue } from "../utils/form-value.js";
+import { useColorAreaGradient } from "./use-color-area-gradient.js";
+import { useMove } from "./use-move.js";
+import { computed, nextTick, onScopeDispose, shallowRef, toValue, watch } from "vue";
+//#region src/composables/use-color-area.ts
+/**
+* A two dimensional colour control: two channels on two axes, one thumb, two hidden inputs.
+*
+* Ported from React Aria's `packages/react-aria/src/color/useColorArea.ts` (react-aria 3.51.0).
+* Four things here are easy to port wrongly, and each of them is invisible in a screenshot:
+*
+* - **Two move handlers, not one.** The thumb has its own, and the *container* has a second one
+*   gated on a flag set by a press that landed on the area itself. That is what makes a press on
+*   the background jump the colour there and then carry on as a drag, rather than needing a second
+*   press on the thumb.
+* - **`Home` / `End` page along x, they do not jump to the ends.** `PageUp` / `PageDown` page along
+*   y. This is *not* the slider's meaning of those keys, so copying them from `useSliderThumb`
+*   would silently give a colour area the wrong keyboard.
+* - **`aria-valuetext` has two shapes**, and which one is used depends on whether the value was
+*   last changed with the keyboard: before that a screen reader hears all three channels, after it
+*   only the one that moved. Both flags reset when focus leaves.
+* - **The two inputs juggle `tabindex` and `aria-hidden`** so that assistive technology lists one
+*   two-dimensional control rather than two sliders — until the keyboard is used, at which point
+*   both are revealed so each channel can be read.
+*
+* @example
+* ```ts
+* const area = useColorArea({containerEl, inputXEl, inputYEl, state});
+* // <div v-bind="area.areaAttrs.value" @pointerdown="area.areaHandlers.onPointerdown">
+* ```
+*/
+var useColorArea = (options) => {
+	const { containerEl, inputXEl, inputYEl, state } = options;
+	const locale = useLocale();
+	const strings = useLocalizedStringFormatter(colorStrings);
+	const isDisabled = computed(() => Boolean(toValue(options.isDisabled)));
+	const focusedInput = shallowRef(null);
+	const valueChangedViaKeyboard = shallowRef(false);
+	const valueChangedViaInputChangeEvent = shallowRef(false);
+	const focusInput = (element = inputXEl) => {
+		element.value?.focus({ preventScroll: true });
+	};
+	/**
+	* Put both inputs back to what the state holds, attribute included.
+	*
+	* Vapor writes `value` as a property and skips the write when the bound value has not changed —
+	* and a form reset does not go through the binding at all. Without a `value` *attribute* the
+	* browser puts a reset range input back to the **midpoint of its range**, which for a hue is
+	* 180°, so one axis of a reset colour area would show a value the state never had. Keeping the
+	* attribute in step is what makes the restore land on the right value. See {@link setFormValue}.
+	*/
+	const reassert = () => {
+		setFormValue(inputXEl.value, String(state.xValue.value));
+		setFormValue(inputYEl.value, String(state.yValue.value));
+	};
+	watch([
+		inputXEl,
+		inputYEl,
+		state.xValue,
+		state.yValue
+	], reassert, {
+		flush: "post",
+		immediate: true
+	});
+	useFormReset(inputXEl, () => state.defaultValue.value, (value) => {
+		state.setValue(value);
+		nextTick(reassert);
+	});
+	/** Where the thumb is during a drag, in fractions of the area — not in pixels. */
+	let currentPosition = null;
+	/** The pointer that owns the interaction in flight, if any. */
+	let currentPointer;
+	/** Whether the press that started this interaction landed on the area rather than the thumb. */
+	let isOnColorArea = false;
+	let detachRelease;
+	const onMoveStart = () => {
+		currentPosition = null;
+		state.setDragging(true);
+	};
+	const onMove = ({ deltaX, deltaY, pointerType, shiftKey }) => {
+		currentPosition ??= state.getThumbPosition();
+		const rect = containerEl.value?.getBoundingClientRect();
+		const width = rect?.width ?? 0;
+		const height = rect?.height ?? 0;
+		const valueChanged = deltaX !== 0 || deltaY !== 0;
+		const isRTL = locale.value.direction === "rtl";
+		if (pointerType === "keyboard") {
+			const stepX = shiftKey && state.xChannelPageStep.value > state.xChannelStep.value ? state.xChannelPageStep.value : state.xChannelStep.value;
+			const stepY = shiftKey && state.yChannelPageStep.value > state.yChannelStep.value ? state.yChannelPageStep.value : state.yChannelStep.value;
+			if (deltaX > 0 && !isRTL || deltaX < 0 && isRTL) state.incrementX(stepX);
+			else if (deltaX < 0 && !isRTL || deltaX > 0 && isRTL) state.decrementX(stepX);
+			else if (deltaY > 0) state.decrementY(stepY);
+			else if (deltaY < 0) state.incrementY(stepY);
+			valueChangedViaKeyboard.value = valueChanged;
+			focusedInput.value = valueChanged && Math.abs(deltaY) > Math.abs(deltaX) ? "y" : "x";
+			return;
+		}
+		currentPosition.x += (isRTL ? -1 : 1) * deltaX / width;
+		currentPosition.y += deltaY / height;
+		state.setColorFromPoint(currentPosition.x, currentPosition.y);
+	};
+	const onMoveEnd = () => {
+		isOnColorArea = false;
+		state.setDragging(false);
+		focusInput(focusedInput.value === "y" ? inputYEl : inputXEl);
+	};
+	const { handlers: thumbMove } = useMove({
+		onMove,
+		onMoveEnd,
+		onMoveStart
+	});
+	const { handlers: containerMove } = useMove({
+		onMove: (event) => isOnColorArea && onMove(event),
+		onMoveEnd: () => isOnColorArea && onMoveEnd(),
+		onMoveStart: () => isOnColorArea && onMoveStart()
+	});
+	/** Bracket a keyboard change in a drag, so the interaction reports an end of its own. */
+	const keyboardUpdate = (update, element, input) => {
+		state.setDragging(true);
+		valueChangedViaKeyboard.value = true;
+		update();
+		state.setDragging(false);
+		focusInput(element);
+		focusedInput.value = input;
+	};
+	const onKeydown = (event) => {
+		if (isDisabled.value) return;
+		const isRTL = locale.value.direction === "rtl";
+		switch (event.key) {
+			case "PageUp":
+				keyboardUpdate(() => state.incrementY(state.yChannelPageStep.value), inputYEl, "y");
+				break;
+			case "PageDown":
+				keyboardUpdate(() => state.decrementY(state.yChannelPageStep.value), inputYEl, "y");
+				break;
+			case "Home":
+				keyboardUpdate(() => isRTL ? state.incrementX(state.xChannelPageStep.value) : state.decrementX(state.xChannelPageStep.value), inputXEl, "x");
+				break;
+			case "End":
+				keyboardUpdate(() => isRTL ? state.decrementX(state.xChannelPageStep.value) : state.incrementX(state.xChannelPageStep.value), inputXEl, "x");
+				break;
+			default:
+				thumbMove.onKeydown(event);
+				return;
+		}
+		event.preventDefault();
+		event.stopPropagation();
+	};
+	/** Anything but the primary button, or a modified click, belongs to the browser. */
+	const isForeignPress = (event) => event.pointerType === "mouse" && (event.button !== 0 || event.altKey || event.ctrlKey || event.metaKey);
+	const onRelease = (event) => {
+		if (event.pointerId !== currentPointer) return;
+		valueChangedViaKeyboard.value = false;
+		focusInput();
+		state.setDragging(false);
+		currentPointer = void 0;
+		isOnColorArea = false;
+		detachRelease?.();
+	};
+	const watchRelease = () => {
+		window.addEventListener("pointerup", onRelease, false);
+		window.addEventListener("pointercancel", onRelease, false);
+		detachRelease = () => {
+			window.removeEventListener("pointerup", onRelease, false);
+			window.removeEventListener("pointercancel", onRelease, false);
+			detachRelease = void 0;
+		};
+	};
+	const onThumbPointerdown = (event) => {
+		if (isDisabled.value || isForeignPress(event)) return;
+		if (!state.isDragging.value) {
+			currentPointer = event.pointerId;
+			valueChangedViaKeyboard.value = false;
+			focusInput();
+			state.setDragging(true);
+			watchRelease();
+		}
+		thumbMove.onPointerdown(event);
+	};
+	const onAreaPointerdown = (event) => {
+		if (isDisabled.value || isForeignPress(event)) return;
+		const area = event.currentTarget;
+		if (area instanceof Element) {
+			const rect = area.getBoundingClientRect();
+			let x = (event.clientX - rect.x) / rect.width;
+			const y = (event.clientY - rect.y) / rect.height;
+			if (locale.value.direction === "rtl") x = 1 - x;
+			if (x >= 0 && x <= 1 && y >= 0 && y <= 1 && !state.isDragging.value && currentPointer === void 0) {
+				isOnColorArea = true;
+				valueChangedViaKeyboard.value = false;
+				currentPointer = event.pointerId;
+				state.setColorFromPoint(x, y);
+				focusInput();
+				state.setDragging(true);
+				watchRelease();
+			}
+		}
+		containerMove.onPointerdown(event);
+	};
+	onScopeDispose(() => detachRelease?.(), true);
+	const onChange = (event) => {
+		const input = event.target;
+		if (!(input instanceof HTMLInputElement)) return;
+		valueChangedViaInputChangeEvent.value = true;
+		if (input === inputXEl.value) state.setXValue(parseFloat(input.value));
+		else if (input === inputYEl.value) state.setYValue(parseFloat(input.value));
+	};
+	const colorPickerLabel = computed(() => strings.value.format("colorPicker"));
+	/**
+	* The value text a screen reader reads for one channel.
+	*
+	* Before the value has been touched it reads all three channels, so the listener knows where in
+	* the square they are; once a keystroke or an input change has moved one channel, only that
+	* channel is read, so a stream of arrow presses is not a stream of three-channel sentences.
+	*/
+	const valueTextFor = (channel) => {
+		const color = state.getDisplayColor();
+		const { xChannel, yChannel, zChannel } = state.channels.value;
+		const tag = locale.value.locale;
+		const nameAndValue = (of) => strings.value.format("colorNameAndValue", {
+			name: color.getChannelName(of, tag),
+			value: color.formatChannelValue(of, tag)
+		});
+		return `${valueChangedViaInputChangeEvent.value || valueChangedViaKeyboard.value ? nameAndValue(channel) : [
+			nameAndValue(channel),
+			nameAndValue(channel === yChannel ? xChannel : yChannel),
+			nameAndValue(zChannel)
+		].join(", ")}, ${color.getColorName(tag)}`;
+	};
+	/**
+	* Both inputs are named for the whole control, not for their own channel: they are two halves of
+	* one two-dimensional slider, and naming them separately would announce two controls.
+	*/
+	const inputLabel = computed(() => {
+		const given = toValue(options.ariaLabel);
+		if (!given) return colorPickerLabel.value;
+		return strings.value.format("colorInputLabel", {
+			channelLabel: colorPickerLabel.value,
+			label: given
+		});
+	});
+	const areaLabels = useLabels(() => {
+		const given = toValue(options.ariaLabel);
+		return {
+			"aria-label": given ? `${given}, ${colorPickerLabel.value}` : void 0,
+			"aria-labelledby": toValue(options.ariaLabelledby),
+			id: toValue(options.id)
+		};
+	});
+	const gradient = useColorAreaGradient({
+		direction: () => locale.value.direction,
+		state
+	});
+	const inputFor = (axis) => computed(() => {
+		const isX = axis === "x";
+		const channel = isX ? state.channels.value.xChannel : state.channels.value.yChannel;
+		const range = state.value.value.getChannelRange(channel);
+		const id = `${areaLabels.value.id}-${axis}`;
+		const labelledby = toValue(options.ariaLabelledby);
+		/**
+		* Only one of the two is reachable at a time, so a tab stop lands on a single control. The
+		* x input is the one that answers before anything has focus, which is why its condition
+		* also covers `null`.
+		*/
+		const isReachable = isX ? !focusedInput.value || focusedInput.value === "x" : focusedInput.value === "y";
+		return {
+			"aria-describedby": toValue(options.ariaDescribedby),
+			/**
+			* Hidden so that listing the form controls shows one two-dimensional slider rather than
+			* two — but revealed again once the keyboard has moved the value, because then each
+			* channel has to be readable on its own.
+			*/
+			"aria-hidden": isReachable || valueChangedViaKeyboard.value ? void 0 : "true",
+			"aria-label": inputLabel.value,
+			"aria-labelledby": labelledby ? `${id} ${labelledby}` : void 0,
+			"aria-orientation": isX ? "horizontal" : "vertical",
+			"aria-roledescription": strings.value.format("twoDimensionalSlider"),
+			"aria-valuetext": valueTextFor(channel),
+			disabled: isDisabled.value,
+			form: toValue(options.form),
+			id,
+			max: range.maxValue,
+			min: range.minValue,
+			name: toValue(isX ? options.xName : options.yName),
+			step: isX ? state.xChannelStep.value : state.yChannelStep.value,
+			tabindex: isReachable ? void 0 : -1,
+			type: "range",
+			value: isX ? state.xValue.value : state.yValue.value
+		};
+	});
+	return {
+		areaAttrs: computed(() => ({
+			"aria-label": areaLabels.value["aria-label"],
+			"aria-labelledby": areaLabels.value["aria-labelledby"],
+			id: areaLabels.value.id,
+			role: "group"
+		})),
+		areaHandlers: { onPointerdown: onAreaPointerdown },
+		areaStyle: gradient.areaStyle,
+		inputStyle: {
+			...visuallyHiddenStyle,
+			height: "100%",
+			opacity: 1e-4,
+			pointerEvents: "none",
+			width: "100%"
+		},
+		isDisabled,
+		thumbAttrs: { role: "presentation" },
+		thumbHandlers: {
+			onFocusout: (event) => {
+				const { currentTarget, relatedTarget } = event;
+				if (currentTarget instanceof Node && relatedTarget instanceof Node && currentTarget.contains(relatedTarget)) return;
+				valueChangedViaKeyboard.value = false;
+				valueChangedViaInputChangeEvent.value = false;
+			},
+			onKeydown,
+			onPointerdown: onThumbPointerdown
+		},
+		thumbStyle: gradient.thumbStyle,
+		xInputHandlers: {
+			onChange,
+			onFocus: () => {
+				focusedInput.value = "x";
+			}
+		},
+		xInputProps: inputFor("x"),
+		yInputHandlers: {
+			onChange,
+			onFocus: () => {
+				focusedInput.value = "y";
+			}
+		},
+		yInputProps: inputFor("y")
+	};
+};
+//#endregion
+export { useColorArea };

package/dist/composables/use-color-channel-field-state.d.ts

@@ -0,0 +1,58 @@
+import type { Color, ColorChannel, ColorSpace } from "../utils/color-types";
+import type { ValidationBehavior } from "./use-form-validation-state";
+import type { NumberFieldState } from "./use-number-field-state";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseColorChannelFieldStateOptions {
+    /** The channel the field edits. */
+    channel: MaybeRefOrGetter<ColorChannel>;
+    /**
+     * The space the field works in; `channel` has to belong to it. Defaults to the space the value
+     * itself is in.
+     */
+    colorSpace?: MaybeRefOrGetter<ColorSpace | undefined>;
+    /** Controlled colour. A string is parsed; one that will not parse is treated as absent. */
+    value?: MaybeRefOrGetter<Color | string | null | undefined>;
+    /** Colour the field starts with, and goes back to when the form is reset. */
+    defaultValue?: MaybeRefOrGetter<Color | string | null | undefined>;
+    onChange?: (value: Color | null) => void;
+    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    isReadOnly?: MaybeRefOrGetter<boolean | undefined>;
+    /** Locale the number is written and read in. @default the runtime's own */
+    locale?: MaybeRefOrGetter<string | undefined>;
+    /**
+     * Whether the browser blocks the submit or the field merely announces the requirement.
+     *
+     * Not one of upstream's state options, but it has to be here: the number field resolves it
+     * from its state, so a state built outside would otherwise pin the field to the default and
+     * `validationBehavior="aria"` would silently do nothing.
+     */
+    validationBehavior?: MaybeRefOrGetter<ValidationBehavior | undefined>;
+}
+export interface ColorChannelFieldState extends NumberFieldState {
+    /** The colour the field edits, in the field's own colour space. */
+    colorValue: ComputedRef<Color>;
+    /** What a form reset goes back to. `null` when the field started empty. */
+    defaultColorValue: ComputedRef<Color | null>;
+    setColorValue: (value: Color | null) => void;
+    /** How the channel is written, which the behaviour layer needs for the announcement. */
+    formatOptions: ComputedRef<Intl.NumberFormatOptions>;
+}
+/**
+ * State for a colour channel field, ported from React Stately's
+ * `packages/react-stately/src/color/useColorChannelFieldState.ts` (react-stately 3.49.0).
+ *
+ * Built on {@link useNumberFieldState}, and the number it holds is a *view* of one channel of the
+ * colour rather than a value of its own: the state is always in controlled mode, so every edit
+ * goes straight back through `withChannelValue` and the colour stays the only thing stored.
+ *
+ * The `multiplier` is the part worth reading twice. A channel written as a percent whose range
+ * runs 0–100 is edited as 0–1 and formatted back up, because `Intl` multiplies a percent by a
+ * hundred itself — without it a saturation of 100 would come out as `10,000%`. Alpha already runs
+ * 0–1, so it keeps a multiplier of one.
+ *
+ * @example
+ * ```ts
+ * const state = useColorChannelFieldState({channel: () => props.channel, value: () => props.value});
+ * ```
+ */
+export declare const useColorChannelFieldState: (options: UseColorChannelFieldStateOptions) => ColorChannelFieldState;

package/dist/composables/use-color-channel-field-state.js

@@ -0,0 +1,78 @@
+import { useControllableState } from "./use-controllable-state.js";
+import { parseColor } from "../utils/color.js";
+import { parseColorValue } from "./use-color-field-state.js";
+import { useNumberFieldState } from "./use-number-field-state.js";
+import { computed, toValue } from "vue";
+//#region src/composables/use-color-channel-field-state.ts
+/**
+* Stand-in for an absent colour, so a channel still has something to read.
+*
+* An empty field shows nothing, but the *range* of its channel still has to come from somewhere —
+* and black is the colour whose every channel sits at its minimum.
+*/
+var BLACK = parseColor("#000");
+/**
+* State for a colour channel field, ported from React Stately's
+* `packages/react-stately/src/color/useColorChannelFieldState.ts` (react-stately 3.49.0).
+*
+* Built on {@link useNumberFieldState}, and the number it holds is a *view* of one channel of the
+* colour rather than a value of its own: the state is always in controlled mode, so every edit
+* goes straight back through `withChannelValue` and the colour stays the only thing stored.
+*
+* The `multiplier` is the part worth reading twice. A channel written as a percent whose range
+* runs 0–100 is edited as 0–1 and formatted back up, because `Intl` multiplies a percent by a
+* hundred itself — without it a saturation of 100 would come out as `10,000%`. Alpha already runs
+* 0–1, so it keeps a multiplier of one.
+*
+* @example
+* ```ts
+* const state = useColorChannelFieldState({channel: () => props.channel, value: () => props.value});
+* ```
+*/
+var useColorChannelFieldState = (options) => {
+	const channel = computed(() => toValue(options.channel));
+	const colorSpace = computed(() => toValue(options.colorSpace));
+	const controlledValue = computed(() => parseColorValue(toValue(options.value)));
+	const defaultValue = computed(() => parseColorValue(toValue(options.defaultValue)));
+	const { setState: setColorValue, state: colorValue } = useControllableState({
+		defaultValue: defaultValue.value ?? null,
+		onValueChange: (value) => options.onChange?.(value),
+		value: () => controlledValue.value
+	});
+	const convert = (value) => {
+		const nonNull = value ?? BLACK;
+		return colorSpace.value ? nonNull.toFormat(colorSpace.value) : nonNull;
+	};
+	const color = computed(() => convert(colorValue.value));
+	/** Captured once: a form reset goes back to where the field started, not to where it is now. */
+	const initialValue = colorValue.value;
+	const defaultColorValue = computed(() => defaultValue.value ?? initialValue);
+	const defaultColor = computed(() => convert(defaultColorValue.value));
+	const range = computed(() => color.value.getChannelRange(channel.value));
+	const formatOptions = computed(() => color.value.getChannelFormatOptions(channel.value));
+	const multiplier = computed(() => formatOptions.value.style === "percent" && range.value.maxValue === 100 ? 100 : 1);
+	return {
+		...useNumberFieldState({
+			defaultValue: () => defaultColorValue.value === null ? NaN : defaultColor.value.getChannelValue(channel.value) / multiplier.value,
+			formatOptions,
+			isDisabled: () => toValue(options.isDisabled),
+			isReadOnly: () => toValue(options.isReadOnly),
+			locale: () => toValue(options.locale),
+			maxValue: () => range.value.maxValue / multiplier.value,
+			minValue: () => range.value.minValue / multiplier.value,
+			onChange: (value) => {
+				if (Number.isNaN(value)) setColorValue(null);
+				else setColorValue(color.value.withChannelValue(channel.value, value * multiplier.value));
+			},
+			step: () => range.value.step / multiplier.value,
+			validationBehavior: () => toValue(options.validationBehavior),
+			value: () => colorValue.value === null ? NaN : color.value.getChannelValue(channel.value) / multiplier.value
+		}),
+		colorValue: color,
+		defaultColorValue,
+		formatOptions,
+		setColorValue
+	};
+};
+//#endregion
+export { useColorChannelFieldState };

package/dist/composables/use-color-channel-field.d.ts

@@ -0,0 +1,55 @@
+import type { ColorChannelFieldState, UseColorChannelFieldStateOptions } from "./use-color-channel-field-state";
+import type { FieldIdsContext } from "./use-field-ids";
+import type { ValidationBehavior } from "./use-form-validation-state";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseColorChannelFieldOptions extends UseColorChannelFieldStateOptions {
+    id?: MaybeRefOrGetter<string | undefined>;
+    autoFocus?: MaybeRefOrGetter<boolean | undefined>;
+    isRequired?: MaybeRefOrGetter<boolean | undefined>;
+    validationBehavior?: MaybeRefOrGetter<ValidationBehavior | undefined>;
+    ariaLabel?: MaybeRefOrGetter<string | undefined>;
+    ariaLabelledby?: MaybeRefOrGetter<string | undefined>;
+    ariaDescribedby?: MaybeRefOrGetter<string | undefined>;
+    /** Whether the wheel over a focused field is ignored. */
+    isWheelDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    onFocusChange?: (isFocused: boolean) => void;
+    onKeydown?: (event: KeyboardEvent) => void;
+    onKeyup?: (event: KeyboardEvent) => void;
+}
+export interface UseColorChannelFieldReturn {
+    state: ColorChannelFieldState;
+    /** Pass to `provideFieldIdsContext`. */
+    fieldIds: FieldIdsContext;
+    /** Attributes for the input. Spread with `v-bind`. Never carries an `on*` key. */
+    attrs: ComputedRef<Record<string, unknown>>;
+    /** The input reports its element, which the wheel, reset and validation wiring hang off. */
+    registerElement: (element: HTMLInputElement | null) => void;
+    element: ComputedRef<HTMLInputElement | null>;
+    isDisabled: ComputedRef<boolean>;
+    isInvalid: ComputedRef<boolean>;
+    isReadOnly: ComputedRef<boolean>;
+    isRequired: ComputedRef<boolean>;
+    onInput: (event: Event) => void;
+    onKeydown: (event: KeyboardEvent) => void;
+    onKeyup: (event: KeyboardEvent) => void;
+    onFocus: (event: FocusEvent) => void;
+    onBlur: (event: FocusEvent) => void;
+    onPaste: (event: ClipboardEvent) => void;
+    /** Put the input's text back to what the state holds. */
+    reassert: () => void;
+}
+/**
+ * Behaviour and accessibility for a colour channel field, ported from React Aria's
+ * `packages/react-aria/src/color/useColorChannelField.ts` (react-aria 3.51.0).
+ *
+ * Almost entirely {@link useNumberField}, which is the point: a channel field *is* a number
+ * field, over a number that happens to live inside a colour. Only two things are added — the
+ * channel's own name as a fallback label, and the format options, which upstream forgets to hand
+ * over (see the deviation note below).
+ *
+ * @example
+ * ```ts
+ * const field = useColorChannelField({channel: () => props.channel, value: () => props.value});
+ * ```
+ */
+export declare const useColorChannelField: (options: UseColorChannelFieldOptions) => UseColorChannelFieldReturn;

package/dist/composables/use-color-channel-field.js

@@ -0,0 +1,76 @@
+import { useLocale } from "./use-locale.js";
+import { useFormValidation } from "./use-form-validation.js";
+import { useColorChannelFieldState } from "./use-color-channel-field-state.js";
+import { useNumberField } from "./use-number-field.js";
+import { computed, toValue } from "vue";
+//#region src/composables/use-color-channel-field.ts
+/**
+* Behaviour and accessibility for a colour channel field, ported from React Aria's
+* `packages/react-aria/src/color/useColorChannelField.ts` (react-aria 3.51.0).
+*
+* Almost entirely {@link useNumberField}, which is the point: a channel field *is* a number
+* field, over a number that happens to live inside a colour. Only two things are added — the
+* channel's own name as a fallback label, and the format options, which upstream forgets to hand
+* over (see the deviation note below).
+*
+* @example
+* ```ts
+* const field = useColorChannelField({channel: () => props.channel, value: () => props.value});
+* ```
+*/
+var useColorChannelField = (options) => {
+	const state = useColorChannelFieldState(options);
+	const locale = useLocale();
+	const field = useNumberField({
+		ariaDescribedby: () => toValue(options.ariaDescribedby),
+		ariaLabel: () => toValue(options.ariaLabel),
+		ariaLabelledby: () => toValue(options.ariaLabelledby),
+		autoFocus: () => toValue(options.autoFocus),
+		/**
+		* Handed over even though upstream does not.
+		*
+		* React's `useColorChannelField` spreads its props into `useNumberField`, and those props
+		* carry no `formatOptions` — so the value a screen reader hears is formatted with none, and
+		* a hue is announced as `300` rather than `300°`. The state already holds the channel's own
+		* options, so withholding them here would be a bug to explain rather than a port to defend.
+		* Invisible in the DOM: the announcement is the only thing that reads them.
+		*/
+		formatOptions: state.formatOptions,
+		id: () => toValue(options.id),
+		isDisabled: () => toValue(options.isDisabled),
+		isReadOnly: () => toValue(options.isReadOnly),
+		isRequired: () => toValue(options.isRequired),
+		isWheelDisabled: () => toValue(options.isWheelDisabled),
+		locale: () => toValue(options.locale),
+		onFocusChange: options.onFocusChange,
+		onKeydown: options.onKeydown,
+		onKeyup: options.onKeyup,
+		state,
+		validationBehavior: () => toValue(options.validationBehavior)
+	});
+	useFormValidation(field.element, state);
+	return {
+		attrs: computed(() => {
+			const all = { ...field.attrs.value };
+			if (!all["aria-label"] && !all["aria-labelledby"]) all["aria-label"] = state.colorValue.value.getChannelName(toValue(options.channel), locale.value.locale);
+			return all;
+		}),
+		element: field.element,
+		fieldIds: field.fieldIds,
+		isDisabled: field.isDisabled,
+		isInvalid: field.isInvalid,
+		isReadOnly: field.isReadOnly,
+		isRequired: field.isRequired,
+		onBlur: field.onBlur,
+		onFocus: field.onFocus,
+		onInput: field.onInput,
+		onKeydown: field.onKeydown,
+		onKeyup: field.onKeyup,
+		onPaste: field.onPaste,
+		reassert: field.reassert,
+		registerElement: field.registerElement,
+		state
+	};
+};
+//#endregion
+export { useColorChannelField };

package/dist/composables/use-color-field-state.d.ts

@@ -0,0 +1,61 @@
+import type { Color } from "../utils/color-types";
+import type { FormValidationState, ValidationBehavior, ValidationFunction } from "./use-form-validation-state";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseColorFieldStateOptions {
+    /** Controlled colour. A string is parsed; one that will not parse is treated as absent. */
+    value?: MaybeRefOrGetter<Color | string | null | undefined>;
+    /** Colour the field starts with, and goes back to when the form is reset. */
+    defaultValue?: MaybeRefOrGetter<Color | string | null | undefined>;
+    onChange?: (value: Color | null) => void;
+    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    isReadOnly?: MaybeRefOrGetter<boolean | undefined>;
+    isRequired?: MaybeRefOrGetter<boolean | undefined>;
+    isInvalid?: MaybeRefOrGetter<boolean | undefined>;
+    validate?: MaybeRefOrGetter<ValidationFunction<Color | null> | undefined>;
+    validationBehavior?: MaybeRefOrGetter<ValidationBehavior | undefined>;
+    name?: MaybeRefOrGetter<string | undefined>;
+}
+export interface ColorFieldState extends FormValidationState {
+    /** Text in the input. Follows the typing, and is rewritten in full on commit. */
+    inputValue: ComputedRef<string>;
+    /** The colour the text currently parses to, or `null` when the field is empty. */
+    colorValue: ComputedRef<Color | null>;
+    /** What a form reset goes back to. */
+    defaultColorValue: ComputedRef<Color | null>;
+    setColorValue: (value: Color | null) => void;
+    setInputValue: (value: string) => void;
+    /** Parse the text, write it back out in full, and reveal validation. What blurring does. */
+    commit: () => void;
+    increment: () => void;
+    decrement: () => void;
+    incrementToMax: () => void;
+    decrementToMin: () => void;
+    /** Whether a half-typed string could still become a hex colour. */
+    validate: (value: string) => boolean;
+}
+/**
+ * A colour that may arrive as a string, forgiving one that will not parse.
+ *
+ * The Vue counterpart of react-stately's `useColor`: swallowing the error is what lets a caller
+ * hand over half-written text without the field throwing at them. Exported for the channel
+ * branch, which needs the same leniency.
+ */
+export declare const parseColorValue: (value: Color | string | null | undefined) => Color | null | undefined;
+/**
+ * State for a hex colour field, ported from React Stately's
+ * `packages/react-stately/src/color/useColorFieldState.ts` (react-stately 3.49.0).
+ *
+ * Like a number field it holds two values at once — the text being typed, which may not be a
+ * colour yet, and the colour it parses to — and only brings them back together on commit. That
+ * is what lets someone type `#ff` on the way to `#ffcc00` without the field fighting them.
+ *
+ * The upstream original synchronises the text from inside the render body, which Vue has no
+ * counterpart for; here it is a synchronous watcher, and it has to stay synchronous — stepping
+ * the value and then reading the input back has to see the new text.
+ *
+ * @example
+ * ```ts
+ * const state = useColorFieldState({value: () => props.value, onChange: (c) => emit("change", c)});
+ * ```
+ */
+export declare const useColorFieldState: (options?: UseColorFieldStateOptions) => ColorFieldState;