ropav 0.2.0 → 0.3.0

package/dist/composables/use-collection.d.ts

@@ -0,0 +1,66 @@
+import type { VirtualizerCollection } from "../utils/virtualizer-layout";
+import type { ComputedRef } from "vue";
+export type CollectionKey = string | number;
+export interface CollectionItemMeta {
+    /** The item's element, or `null` before it mounts and after it goes away. */
+    element: () => HTMLElement | null;
+    /** Text the item is matched on by typeahead. */
+    textValue: () => string;
+    /** The item's own disabled state. The collection's `disabledKeys` merge in separately. */
+    isDisabled: () => boolean;
+}
+export interface UseCollectionOptions {
+    /**
+     * Where the collection's contents come from, when they do not come from the DOM.
+     *
+     * A virtualized collection renders only a window of its items, so the registry below can only
+     * ever see that window. Given a source, order, size and metadata are read from the data, and
+     * the registry is left with the one job the data cannot do: handing out the element a key
+     * currently occupies.
+     */
+    source?: () => VirtualizerCollection | null | undefined;
+}
+export interface UseCollectionReturn {
+    /** How many items are registered. Read during render, so it has to be reactive. */
+    size: ComputedRef<number>;
+    /** Registered keys in document order. */
+    orderedKeys: () => CollectionKey[];
+    getItem: (key: CollectionKey) => CollectionItemMeta | undefined;
+    getElement: (key: CollectionKey) => HTMLElement | null;
+    getFirstKey: () => CollectionKey | null;
+    getLastKey: () => CollectionKey | null;
+    getKeyAfter: (key: CollectionKey) => CollectionKey | null;
+    getKeyBefore: (key: CollectionKey) => CollectionKey | null;
+    /** The item's position among its siblings, or `-1` when it is not in the collection. */
+    getIndex: (key: CollectionKey) => number;
+    /** Register an item and return the call that unregisters it. */
+    register: (key: CollectionKey, meta: CollectionItemMeta) => () => void;
+}
+/**
+ * The set of items a listbox, menu or tag group navigates over.
+ *
+ * React Aria builds this by rendering the children into a hidden tree and reading the result
+ * back, so the parent knows every item before the first paint. That is not possible here:
+ * rendering a slot is what creates its DOM, so there is no "render to inspect" pass. The flow
+ * is inverted instead — each item registers itself, and the parent asks the DOM for the order.
+ *
+ * Two choices carry the weight:
+ *
+ * Metadata is stored as **getters**, not values, so the parent always reads an item's current
+ * text and disabled state. Nothing has to re-register when a prop changes, and no
+ * `MutationObserver` is needed to notice edited text.
+ *
+ * `orderedKeys()` is a **function rather than a computed**. A computed would have to be
+ * invalidated by a counter bumped on register and unregister — but reordering items that are
+ * already registered changes their document order without touching that counter, which would
+ * silently break arrow navigation. Order is only ever read on an interaction (a keypress, a
+ * focus change, extending a selection), never during render, so re-sorting per call is both
+ * correct and cheap. `size` stays reactive because it *is* read during render.
+ *
+ * A collection that is virtualized cannot work that way at all: all but a window of its items are
+ * absent from the DOM, so asking the DOM would answer for the window and call the rest
+ * non-existent. Such a collection passes a `source`, and then order, size and metadata come from
+ * the data while the registry keeps the one job the data cannot do — saying which element a key
+ * currently occupies, for focus.
+ */
+export declare const useCollection: (options?: UseCollectionOptions) => UseCollectionReturn;

package/dist/composables/use-collection.js

@@ -0,0 +1,94 @@
+import { computed, shallowRef } from "vue";
+//#region src/composables/use-collection.ts
+/**
+* The set of items a listbox, menu or tag group navigates over.
+*
+* React Aria builds this by rendering the children into a hidden tree and reading the result
+* back, so the parent knows every item before the first paint. That is not possible here:
+* rendering a slot is what creates its DOM, so there is no "render to inspect" pass. The flow
+* is inverted instead — each item registers itself, and the parent asks the DOM for the order.
+*
+* Two choices carry the weight:
+*
+* Metadata is stored as **getters**, not values, so the parent always reads an item's current
+* text and disabled state. Nothing has to re-register when a prop changes, and no
+* `MutationObserver` is needed to notice edited text.
+*
+* `orderedKeys()` is a **function rather than a computed**. A computed would have to be
+* invalidated by a counter bumped on register and unregister — but reordering items that are
+* already registered changes their document order without touching that counter, which would
+* silently break arrow navigation. Order is only ever read on an interaction (a keypress, a
+* focus change, extending a selection), never during render, so re-sorting per call is both
+* correct and cheap. `size` stays reactive because it *is* read during render.
+*
+* A collection that is virtualized cannot work that way at all: all but a window of its items are
+* absent from the DOM, so asking the DOM would answer for the window and call the rest
+* non-existent. Such a collection passes a `source`, and then order, size and metadata come from
+* the data while the registry keeps the one job the data cannot do — saying which element a key
+* currently occupies, for focus.
+*/
+var useCollection = (options = {}) => {
+	const items = /* @__PURE__ */ new Map();
+	const version = shallowRef(0);
+	const register = (key, meta) => {
+		items.set(key, meta);
+		version.value += 1;
+		return () => {
+			if (items.get(key) === meta) {
+				items.delete(key);
+				version.value += 1;
+			}
+		};
+	};
+	const source = () => options.source?.() ?? null;
+	/**
+	* Metadata for an item the data knows about but the DOM does not hold yet.
+	*
+	* Typeahead and the disabled check are asked about every key, not only the rendered ones, so
+	* an item outside the window has to answer for itself out of the data.
+	*/
+	const metaFromSource = (key) => {
+		const node = source()?.getNode(key);
+		if (!node) return void 0;
+		return {
+			element: () => null,
+			isDisabled: () => Boolean(node.isDisabled),
+			textValue: () => node.textValue ?? ""
+		};
+	};
+	const orderedKeys = () => {
+		const sourced = source();
+		if (sourced) return sourced.keys;
+		return domOrderedKeys();
+	};
+	const domOrderedKeys = () => [...items.entries()].filter(([, meta]) => meta.element()?.isConnected).sort(([, a], [, b]) => a.element().compareDocumentPosition(b.element()) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1).map(([key]) => key);
+	const keyAt = (index) => {
+		return orderedKeys()[index] ?? null;
+	};
+	const neighbour = (key, step) => {
+		const keys = orderedKeys();
+		const index = keys.indexOf(key);
+		if (index === -1) return null;
+		return keys[index + step] ?? null;
+	};
+	return {
+		getElement: (key) => {
+			return items.get(key)?.element() ?? null;
+		},
+		getFirstKey: () => keyAt(0),
+		getIndex: (key) => orderedKeys().indexOf(key),
+		getItem: (key) => {
+			return items.get(key) ?? metaFromSource(key);
+		},
+		getKeyAfter: (key) => neighbour(key, 1),
+		getKeyBefore: (key) => neighbour(key, -1),
+		getLastKey: () => keyAt(orderedKeys().length - 1),
+		orderedKeys,
+		register,
+		size: computed(() => {
+			return source()?.itemCount ?? items.size;
+		})
+	};
+};
+//#endregion
+export { useCollection };

package/dist/composables/use-color-area-gradient.d.ts

@@ -0,0 +1,32 @@
+import type { Direction } from "../utils/locale";
+import type { ColorAreaState } from "./use-color-area-state";
+import type { CSSProperties, ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseColorAreaGradientOptions {
+    state: ColorAreaState;
+    /** Reading direction: the x axis of a colour area runs with the text. */
+    direction: MaybeRefOrGetter<Direction>;
+}
+export interface UseColorAreaGradientReturn {
+    /** Inline style for the area, gradient included. */
+    areaStyle: ComputedRef<CSSProperties>;
+    /** Inline style for the thumb: where it sits, and the colour it stands for. */
+    thumbStyle: ComputedRef<CSSProperties>;
+}
+/**
+ * The two-dimensional gradient behind a colour area, and where its thumb sits on it.
+ *
+ * Ported from React Aria's `packages/react-aria/src/color/useColorAreaGradient.ts`
+ * (react-aria 3.51.0). Three shapes, one per colour space, and they are not variations of each
+ * other:
+ *
+ * - **`rgb`** stacks three layers and blends them with `screen`, which multiplies the inverse of
+ *   each channel — so a red ramp over a green ramp over a flat blue combines channel by channel
+ *   into the square a viewer expects. `background-blend-mode` is load-bearing: without it the top
+ *   layer simply covers the others, and the result still *looks* like a plausible colour square.
+ * - **`hsl`** and **`hsb`** paint one gradient per non-held channel, **reversed** so the x axis
+ *   ends up underneath, and push a flat colour beneath both when the held channel is the hue.
+ *
+ * The joining is not cosmetic either: `rgb` joins its layers with a bare comma and the other two
+ * with comma-space, which is why the two are written out separately here rather than shared.
+ */
+export declare const useColorAreaGradient: (options: UseColorAreaGradientOptions) => UseColorAreaGradientReturn;

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

@@ -0,0 +1,92 @@
+import { parseColor } from "../utils/color.js";
+import { computed, toValue } from "vue";
+//#region src/composables/use-color-area-gradient.ts
+/** Stops of the hue wheel a gradient is drawn through, in degrees. */
+var HUE_STOPS = [
+	0,
+	60,
+	120,
+	180,
+	240,
+	300,
+	360
+];
+var hue = (color) => HUE_STOPS.map((stop) => color.withChannelValue("hue", stop).toString("css")).join(", ");
+/** Grey to see-through, so whatever is painted underneath shows at full saturation. */
+var saturation = (color) => `${color.withChannelValue("saturation", 0).toString("css")}, transparent`;
+var HSL_CHANNELS = {
+	hue,
+	lightness: () => "black, transparent, white",
+	saturation
+};
+var HSB_CHANNELS = {
+	brightness: () => "black, transparent",
+	hue,
+	saturation
+};
+/**
+* The two-dimensional gradient behind a colour area, and where its thumb sits on it.
+*
+* Ported from React Aria's `packages/react-aria/src/color/useColorAreaGradient.ts`
+* (react-aria 3.51.0). Three shapes, one per colour space, and they are not variations of each
+* other:
+*
+* - **`rgb`** stacks three layers and blends them with `screen`, which multiplies the inverse of
+*   each channel — so a red ramp over a green ramp over a flat blue combines channel by channel
+*   into the square a viewer expects. `background-blend-mode` is load-bearing: without it the top
+*   layer simply covers the others, and the result still *looks* like a plausible colour square.
+* - **`hsl`** and **`hsb`** paint one gradient per non-held channel, **reversed** so the x axis
+*   ends up underneath, and push a flat colour beneath both when the held channel is the hue.
+*
+* The joining is not cosmetic either: `rgb` joins its layers with a bare comma and the other two
+* with comma-space, which is why the two are written out separately here rather than shared.
+*/
+var useColorAreaGradient = (options) => {
+	const { state } = options;
+	/** Where the far end of the x axis is, which is where the text ends. */
+	const end = computed(() => toValue(options.direction) === "rtl" ? "left" : "right");
+	const background = computed(() => {
+		const { xChannel, yChannel, zChannel } = state.channels.value;
+		const value = state.value.value;
+		const zValue = value.getChannelValue(zChannel);
+		const to = end.value;
+		if (value.getColorSpace() === "rgb") {
+			const rgb = parseColor("rgb(0, 0, 0)");
+			return {
+				background: [
+					`linear-gradient(to ${to}, ${rgb.withChannelValue(xChannel, 0).toString("css")}, ${rgb.withChannelValue(xChannel, 255).toString("css")})`,
+					`linear-gradient(to top, ${rgb.withChannelValue(yChannel, 0).toString("css")}, ${rgb.withChannelValue(yChannel, 255).toString("css")})`,
+					rgb.withChannelValue(zChannel, zValue).toString("css")
+				].join(","),
+				backgroundBlendMode: "screen"
+			};
+		}
+		const isHsl = value.getColorSpace() === "hsl";
+		const table = isHsl ? HSL_CHANNELS : HSB_CHANNELS;
+		const base = parseColor(isHsl ? "hsl(0, 100%, 50%)" : "hsb(0, 100%, 100%)").withChannelValue(zChannel, zValue);
+		const layers = value.getColorChannels().filter((channel) => channel !== zChannel).map((channel) => `linear-gradient(to ${channel === xChannel ? to : "top"}, ${table[channel](base)})`).reverse();
+		if (zChannel === "hue") layers.push(base.toString("css"));
+		return { background: layers.join(", ") };
+	});
+	return {
+		areaStyle: computed(() => ({
+			forcedColorAdjust: "none",
+			position: "relative",
+			touchAction: "none",
+			...background.value
+		})),
+		thumbStyle: computed(() => {
+			const { x, y } = state.getThumbPosition();
+			return {
+				forcedColorAdjust: "none",
+				left: `${(toValue(options.direction) === "rtl" ? 1 - x : x) * 100}%`,
+				position: "absolute",
+				top: `${y * 100}%`,
+				touchAction: "none",
+				transform: "translate(-50%, -50%)"
+			};
+		})
+	};
+};
+//#endregion
+export { useColorAreaGradient };

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

@@ -0,0 +1,79 @@
+import type { Color, ColorAxes, ColorChannel, ColorSpace } from "../utils/color-types";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseColorAreaStateOptions {
+    /** Current colour. A string is parsed. */
+    value?: MaybeRefOrGetter<Color | string | undefined>;
+    /** Colour used while the area is uncontrolled. @default "#ffffff" */
+    defaultValue?: MaybeRefOrGetter<Color | string | undefined>;
+    /**
+     * The space the area works in; `xChannel` and `yChannel` have to belong to it. Defaults to the
+     * space the value itself is in.
+     */
+    colorSpace?: MaybeRefOrGetter<ColorSpace | undefined>;
+    /** Channel on the horizontal axis. Defaults to the first channel of the space. */
+    xChannel?: MaybeRefOrGetter<ColorChannel | undefined>;
+    /** Channel on the vertical axis. Defaults to the next channel of the space. */
+    yChannel?: MaybeRefOrGetter<ColorChannel | undefined>;
+    /** Called on every change, while dragging included. */
+    onChange?: (value: Color) => void;
+    /** Called once the interaction that changed the colour is over. */
+    onChangeEnd?: (value: Color) => void;
+}
+export interface ColorAreaState {
+    /** The colour the area holds, in the area's own colour space. */
+    value: ComputedRef<Color>;
+    /** The colour a form reset goes back to. */
+    defaultValue: ComputedRef<Color>;
+    /** Replace the whole colour. A string is parsed. */
+    setValue: (value: Color | string) => void;
+    /** The three channels the two axes and the held channel stand for. */
+    channels: ComputedRef<ColorAxes>;
+    xValue: ComputedRef<number>;
+    setXValue: (value: number) => void;
+    yValue: ComputedRef<number>;
+    setYValue: (value: number) => void;
+    /** Both channels at once, from a point given as fractions of the area's width and height. */
+    setColorFromPoint: (x: number, y: number) => void;
+    /** Where the thumb sits, as fractions from the area's top left corner. */
+    getThumbPosition: () => {
+        x: number;
+        y: number;
+    };
+    incrementX: (stepSize?: number) => void;
+    decrementX: (stepSize?: number) => void;
+    incrementY: (stepSize?: number) => void;
+    decrementY: (stepSize?: number) => void;
+    isDragging: ComputedRef<boolean>;
+    setDragging: (value: boolean) => void;
+    xChannelStep: ComputedRef<number>;
+    yChannelStep: ComputedRef<number>;
+    xChannelPageStep: ComputedRef<number>;
+    yChannelPageStep: ComputedRef<number>;
+    /** The colour the thumb is painted with: the value, made opaque. */
+    getDisplayColor: () => Color;
+}
+/**
+ * Two channels of a colour at once, driven by a point in a square.
+ *
+ * Ported from React Stately's `packages/react-stately/src/color/useColorAreaState.ts`
+ * (react-stately 3.49.0). Unlike {@link useColorSliderState} this is **not** built on the slider
+ * layer — a slider is one thumb on one axis, and nothing of its penning-in between neighbours or
+ * its percentage-of-track maths carries over to a square. It borrows only `clamp` and
+ * `snapValueToStep`.
+ *
+ * Two upstream hacks are deliberately absent rather than ported. React keeps the colour in a ref
+ * beside the state so `onChangeEnd` can read the value the render has not seen yet, and keeps a
+ * second ref for "was dragging" for the same reason; in Vue a write is visible to the next read in
+ * the same tick, so one `shallowRef` does both jobs. What is kept is the **edge**: `onChangeEnd`
+ * fires only on the true → false transition, never on a repeated `setDragging(false)`.
+ *
+ * @example
+ * ```ts
+ * const state = useColorAreaState({
+ *   defaultValue: () => props.defaultValue,
+ *   xChannel: () => props.xChannel,
+ *   onChange: (value) => emit("change", value),
+ * });
+ * ```
+ */
+export declare const useColorAreaState: (options?: UseColorAreaStateOptions) => ColorAreaState;

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

@@ -0,0 +1,138 @@
+import { useControllableState } from "./use-controllable-state.js";
+import { clamp, snapValueToStep } from "../utils/number.js";
+import { normalizeColor, parseColor } from "../utils/color.js";
+import { computed, shallowRef, toValue } from "vue";
+//#region src/composables/use-color-area-state.ts
+/**
+* What a colour area with nothing to show starts from.
+*
+* White, and white is in `rgb`, so an area given no value is **red × green with blue held at its
+* maximum** — not the hue × saturation square the name "color area" suggests.
+*/
+var DEFAULT_COLOR = parseColor("#ffffff");
+/**
+* Two channels of a colour at once, driven by a point in a square.
+*
+* Ported from React Stately's `packages/react-stately/src/color/useColorAreaState.ts`
+* (react-stately 3.49.0). Unlike {@link useColorSliderState} this is **not** built on the slider
+* layer — a slider is one thumb on one axis, and nothing of its penning-in between neighbours or
+* its percentage-of-track maths carries over to a square. It borrows only `clamp` and
+* `snapValueToStep`.
+*
+* Two upstream hacks are deliberately absent rather than ported. React keeps the colour in a ref
+* beside the state so `onChangeEnd` can read the value the render has not seen yet, and keeps a
+* second ref for "was dragging" for the same reason; in Vue a write is visible to the next read in
+* the same tick, so one `shallowRef` does both jobs. What is kept is the **edge**: `onChangeEnd`
+* fires only on the true → false transition, never on a repeated `setDragging(false)`.
+*
+* @example
+* ```ts
+* const state = useColorAreaState({
+*   defaultValue: () => props.defaultValue,
+*   xChannel: () => props.xChannel,
+*   onChange: (value) => emit("change", value),
+* });
+* ```
+*/
+var useColorAreaState = (options = {}) => {
+	const controlledValue = computed(() => {
+		const value = toValue(options.value);
+		return value ? normalizeColor(value) : void 0;
+	});
+	const givenDefault = computed(() => {
+		const value = toValue(options.defaultValue);
+		if (value) return normalizeColor(value);
+		return toValue(options.value) ? void 0 : DEFAULT_COLOR;
+	});
+	const { setState: setColor, state: colorValue } = useControllableState({
+		defaultValue: givenDefault.value ?? controlledValue.value,
+		onValueChange: (value) => options.onChange?.(value),
+		value: () => controlledValue.value
+	});
+	/** Where a controlled area's form reset goes back to: wherever it started. */
+	const initialValue = colorValue.value;
+	const color = computed(() => {
+		const space = toValue(options.colorSpace);
+		return space ? colorValue.value.toFormat(space) : colorValue.value;
+	});
+	const channels = computed(() => color.value.getColorSpaceAxes({
+		xChannel: toValue(options.xChannel),
+		yChannel: toValue(options.yChannel)
+	}));
+	const xRange = computed(() => color.value.getChannelRange(channels.value.xChannel));
+	const yRange = computed(() => color.value.getChannelRange(channels.value.yChannel));
+	const xValue = computed(() => color.value.getChannelValue(channels.value.xChannel));
+	const yValue = computed(() => color.value.getChannelValue(channels.value.yChannel));
+	const setXValue = (value) => {
+		if (value === xValue.value) return;
+		setColor(color.value.withChannelValue(channels.value.xChannel, value));
+	};
+	const setYValue = (value) => {
+		if (value === yValue.value) return;
+		setColor(color.value.withChannelValue(channels.value.yChannel, value));
+	};
+	const isDragging = shallowRef(false);
+	return {
+		channels,
+		decrementX: (stepSize = 1) => {
+			const { maxValue, minValue, step } = xRange.value;
+			setXValue(snapValueToStep(xValue.value - stepSize, minValue, maxValue, step));
+		},
+		decrementY: (stepSize = 1) => {
+			const { maxValue, minValue, step } = yRange.value;
+			setYValue(snapValueToStep(yValue.value - stepSize, minValue, maxValue, step));
+		},
+		defaultValue: computed(() => controlledValue.value !== void 0 ? initialValue : givenDefault.value),
+		getDisplayColor: () => color.value.withChannelValue("alpha", 1),
+		getThumbPosition: () => {
+			return {
+				x: (xValue.value - xRange.value.minValue) / (xRange.value.maxValue - xRange.value.minValue),
+				y: 1 - (yValue.value - yRange.value.minValue) / (yRange.value.maxValue - yRange.value.minValue)
+			};
+		},
+		incrementX: (stepSize = 1) => {
+			const { maxValue, minValue, step } = xRange.value;
+			const next = xValue.value + stepSize;
+			setXValue(next > maxValue ? maxValue : snapValueToStep(next, minValue, maxValue, step));
+		},
+		incrementY: (stepSize = 1) => {
+			const { maxValue, minValue, step } = yRange.value;
+			const next = yValue.value + stepSize;
+			setYValue(next > maxValue ? maxValue : snapValueToStep(next, minValue, maxValue, step));
+		},
+		isDragging: computed(() => isDragging.value),
+		setColorFromPoint: (x, y) => {
+			const { maxValue: maxX, minValue: minX, step: stepX } = xRange.value;
+			const { maxValue: maxY, minValue: minY, step: stepY } = yRange.value;
+			let nextX = minX + clamp(x, 0, 1) * (maxX - minX);
+			let nextY = minY + (1 - clamp(y, 0, 1)) * (maxY - minY);
+			let next;
+			if (nextX !== xValue.value) {
+				nextX = snapValueToStep(nextX, minX, maxX, stepX);
+				next = color.value.withChannelValue(channels.value.xChannel, nextX);
+			}
+			if (nextY !== yValue.value) {
+				nextY = snapValueToStep(nextY, minY, maxY, stepY);
+				next = (next ?? color.value).withChannelValue(channels.value.yChannel, nextY);
+			}
+			if (next) setColor(next);
+		},
+		setDragging: (dragging) => {
+			const wasDragging = isDragging.value;
+			isDragging.value = dragging;
+			if (!dragging && wasDragging) options.onChangeEnd?.(color.value);
+		},
+		setValue: (value) => setColor(normalizeColor(value)),
+		setXValue,
+		setYValue,
+		value: color,
+		xChannelPageStep: computed(() => xRange.value.pageSize),
+		xChannelStep: computed(() => xRange.value.step),
+		xValue,
+		yChannelPageStep: computed(() => yRange.value.pageSize),
+		yChannelStep: computed(() => yRange.value.step),
+		yValue
+	};
+};
+//#endregion
+export { useColorAreaState };

package/dist/composables/use-color-area.d.ts

@@ -0,0 +1,109 @@
+import type { ColorAreaState } from "./use-color-area-state";
+import type { CSSProperties, ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+export interface ColorAreaInputAttrs {
+    id: string;
+    type: "range";
+    min: number;
+    max: number;
+    step: number;
+    value: number;
+    name: string | undefined;
+    form: string | undefined;
+    disabled: boolean;
+    tabindex: number | undefined;
+    "aria-hidden": "true" | undefined;
+    "aria-label": string | undefined;
+    "aria-labelledby": string | undefined;
+    "aria-describedby": string | undefined;
+    "aria-orientation": "horizontal" | "vertical";
+    "aria-roledescription": string;
+    "aria-valuetext": string;
+}
+export interface UseColorAreaOptions {
+    state: ColorAreaState;
+    /** The area element. Its size is what a drag is measured against. */
+    containerEl: Ref<HTMLElement | null>;
+    /** The visually hidden range input for the horizontal channel. */
+    inputXEl: Ref<HTMLInputElement | null>;
+    /** The visually hidden range input for the vertical channel. */
+    inputYEl: Ref<HTMLInputElement | null>;
+    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    /** Id override for the area element. */
+    id?: MaybeRefOrGetter<string | undefined>;
+    ariaLabel?: MaybeRefOrGetter<string | undefined>;
+    ariaLabelledby?: MaybeRefOrGetter<string | undefined>;
+    ariaDescribedby?: MaybeRefOrGetter<string | undefined>;
+    /** Name the horizontal channel is submitted under. */
+    xName?: MaybeRefOrGetter<string | undefined>;
+    /** Name the vertical channel is submitted under. */
+    yName?: MaybeRefOrGetter<string | undefined>;
+    /** `id` of the form to submit with, for an area rendered outside it. */
+    form?: MaybeRefOrGetter<string | undefined>;
+}
+export interface ColorAreaAttrs {
+    role: "group";
+    id: string;
+    "aria-label": string | undefined;
+    "aria-labelledby": string | undefined;
+}
+export interface UseColorAreaReturn {
+    areaAttrs: ComputedRef<ColorAreaAttrs>;
+    areaStyle: ComputedRef<CSSProperties>;
+    /**
+     * A press anywhere on the area jumps the colour there **and** keeps dragging it. Attach with
+     * `@pointerdown`, never through `v-bind`: a vapor render re-attaches every `on*` key that
+     * arrived that way, which drops the listener when the press itself re-rendered the element.
+     */
+    areaHandlers: {
+        onPointerdown: (event: PointerEvent) => void;
+    };
+    thumbAttrs: {
+        role: "presentation";
+    };
+    thumbStyle: ComputedRef<CSSProperties>;
+    thumbHandlers: {
+        onFocusout: (event: FocusEvent) => void;
+        onKeydown: (event: KeyboardEvent) => void;
+        onPointerdown: (event: PointerEvent) => void;
+    };
+    xInputProps: ComputedRef<ColorAreaInputAttrs>;
+    yInputProps: ComputedRef<ColorAreaInputAttrs>;
+    /** Takes an input out of sight while leaving it focusable, and lets a press through it. */
+    inputStyle: CSSProperties;
+    xInputHandlers: {
+        onChange: (event: Event) => void;
+        onFocus: () => void;
+    };
+    yInputHandlers: {
+        onChange: (event: Event) => void;
+        onFocus: () => void;
+    };
+    isDisabled: ComputedRef<boolean>;
+}
+/**
+ * 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">
+ * ```
+ */
+export declare const useColorArea: (options: UseColorAreaOptions) => UseColorAreaReturn;