ropav 0.2.0 → 0.3.0

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

@@ -0,0 +1,81 @@
+import type { Color, ColorChannel } from "../utils/color-types";
+import type { ColorSliderState } from "./use-color-slider-state";
+import type { SliderGroupAttrs, SliderOutputAttrs } from "./use-slider";
+import type { SliderThumbInputAttrs, UseSliderThumbReturn } from "./use-slider-thumb";
+import type { CSSProperties, ComputedRef, MaybeRefOrGetter, Ref } from "vue";
+export interface UseColorSliderOptions {
+    state: ColorSliderState;
+    /** The track element. Its length is the distance the thumb can travel. */
+    trackEl: Ref<HTMLElement | null>;
+    /** The visually hidden range input the thumb stands for. */
+    inputEl: Ref<HTMLInputElement | null>;
+    /** The channel the slider drives. */
+    channel: MaybeRefOrGetter<ColorChannel>;
+    /** The group's own id, and the stem the thumb id grows from. */
+    id: MaybeRefOrGetter<string>;
+    /** Id of the visible label, when one is rendered. */
+    labelId?: MaybeRefOrGetter<string | undefined>;
+    ariaLabel?: MaybeRefOrGetter<string | undefined>;
+    ariaLabelledby?: MaybeRefOrGetter<string | undefined>;
+    ariaDescribedby?: MaybeRefOrGetter<string | undefined>;
+    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    /** Name submitted with the form. */
+    name?: MaybeRefOrGetter<string | undefined>;
+    /** `id` of the form to submit with, for a slider rendered outside it. */
+    form?: MaybeRefOrGetter<string | undefined>;
+}
+export interface UseColorSliderReturn {
+    /**
+     * For the **track**, not the root: this is where the group role and the accessible name live.
+     * @see {@link useColorSlider}
+     */
+    trackAttrs: ComputedRef<SliderGroupAttrs>;
+    /** Inline styles the track needs whatever the stylesheet says, gradient included. */
+    trackStyle: ComputedRef<CSSProperties>;
+    /**
+     * 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 it.
+     */
+    trackHandlers: {
+        onPointerdown: (event: PointerEvent) => void;
+    };
+    outputProps: ComputedRef<SliderOutputAttrs>;
+    /** For the visually hidden range input, with the colour's name folded into its value text. */
+    inputProps: ComputedRef<SliderThumbInputAttrs>;
+    /** Takes the input out of sight without taking it out of the tab order. */
+    inputStyle: CSSProperties;
+    inputHandlers: UseSliderThumbReturn["inputHandlers"];
+    /** Position along the track. Carries `backgroundColor`: the thumb shows the colour it holds. */
+    thumbStyle: ComputedRef<CSSProperties>;
+    thumbHandlers: UseSliderThumbReturn["thumbHandlers"];
+    /** The colour the track and the thumb are painted with, which is not always the value. */
+    displayColor: ComputedRef<Color>;
+    isDragging: ComputedRef<boolean>;
+    isDisabled: ComputedRef<boolean>;
+    /** Hand focus to the thumb, for a click on the label. */
+    focusThumb: () => void;
+}
+/**
+ * A slider over one channel of a colour: its gradient, its labelling, and its single thumb.
+ *
+ * Ported from React Aria's `packages/react-aria/src/color/useColorSlider.ts` (react-aria 3.51.0),
+ * with the thumb's own attributes coming from the same {@link useSliderThumb} the plain slider
+ * uses. Three things are particular to a colour and are the reason this exists at all:
+ *
+ * - **The group is the track.** Upstream merges `groupProps` into `trackProps`, so `role="group"`
+ *   and the accessible name sit on `.color-slider__track` rather than on the root the way they do
+ *   on a plain slider. Binding them on the root instead gives a slider two mislabelled elements
+ *   and no visible sign of it.
+ * - **The gradient is computed, not styled.** The track's `background` is generated from the
+ *   channel — seven stops for hue, three for lightness, two for everything else — so it cannot
+ *   live in the stylesheet.
+ * - **The value text names the colour.** A screen reader hears `"200°, cyan blue"` rather than
+ *   `"200°"`, because a number on its own says nothing about a colour.
+ *
+ * @example
+ * ```ts
+ * const slider = useColorSlider({channel: () => props.channel, id, inputEl, state, trackEl});
+ * // <div v-bind="slider.trackAttrs.value" :style="slider.trackStyle.value">
+ * ```
+ */
+export declare const useColorSlider: (options: UseColorSliderOptions) => UseColorSliderReturn;

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

@@ -0,0 +1,140 @@
+import { useLocale } from "./use-locale.js";
+import { visuallyHiddenStyle } from "../utils/visually-hidden.js";
+import { useSlider } from "./use-slider.js";
+import { useSliderThumb } from "./use-slider-thumb.js";
+import { computed, toValue } from "vue";
+//#region src/composables/use-color-slider.ts
+/** Stops of the hue wheel the gradient is drawn through, in degrees. */
+var HUE_STOPS = [
+	0,
+	60,
+	120,
+	180,
+	240,
+	300,
+	360
+];
+/**
+* A slider over one channel of a colour: its gradient, its labelling, and its single thumb.
+*
+* Ported from React Aria's `packages/react-aria/src/color/useColorSlider.ts` (react-aria 3.51.0),
+* with the thumb's own attributes coming from the same {@link useSliderThumb} the plain slider
+* uses. Three things are particular to a colour and are the reason this exists at all:
+*
+* - **The group is the track.** Upstream merges `groupProps` into `trackProps`, so `role="group"`
+*   and the accessible name sit on `.color-slider__track` rather than on the root the way they do
+*   on a plain slider. Binding them on the root instead gives a slider two mislabelled elements
+*   and no visible sign of it.
+* - **The gradient is computed, not styled.** The track's `background` is generated from the
+*   channel — seven stops for hue, three for lightness, two for everything else — so it cannot
+*   live in the stylesheet.
+* - **The value text names the colour.** A screen reader hears `"200°, cyan blue"` rather than
+*   `"200°"`, because a number on its own says nothing about a colour.
+*
+* @example
+* ```ts
+* const slider = useColorSlider({channel: () => props.channel, id, inputEl, state, trackEl});
+* // <div v-bind="slider.trackAttrs.value" :style="slider.trackStyle.value">
+* ```
+*/
+var useColorSlider = (options) => {
+	const { inputEl, state, trackEl } = options;
+	const locale = useLocale();
+	const channel = computed(() => toValue(options.channel));
+	/**
+	* A slider with nothing else naming it is named after its channel, which is what makes
+	* `<ColorSlider aria-label>`-less markup announce as "Hue" rather than as an unnamed group.
+	*/
+	const ariaLabel = computed(() => {
+		const given = toValue(options.ariaLabel);
+		if (given) return given;
+		if (toValue(options.labelId) ?? toValue(options.ariaLabelledby)) return void 0;
+		return state.value.value.getChannelName(channel.value, locale.value.locale);
+	});
+	const slider = useSlider({
+		ariaDescribedby: () => toValue(options.ariaDescribedby),
+		ariaLabel,
+		ariaLabelledby: () => toValue(options.ariaLabelledby),
+		id: options.id,
+		labelId: options.labelId,
+		state,
+		trackEl
+	});
+	const thumb = useSliderThumb({
+		describedBy: slider.describedBy,
+		form: () => toValue(options.form),
+		id: () => slider.getThumbId(0),
+		index: 0,
+		inputEl,
+		isDisabled: () => toValue(options.isDisabled),
+		labelledBy: slider.labelledBy,
+		name: () => toValue(options.name),
+		state,
+		trackEl
+	});
+	const displayColor = computed(() => state.getDisplayColor());
+	/**
+	* The gradient runs along the track, so a vertical slider paints upwards and a horizontal one
+	* in the reading direction — a right-to-left page has its minimum on the right.
+	*/
+	const background = computed(() => {
+		const color = displayColor.value;
+		const to = state.orientation.value === "vertical" ? "top" : locale.value.direction === "ltr" ? "right" : "left";
+		const min = state.getThumbMinValue(0);
+		const max = state.getThumbMaxValue(0);
+		const at = (value) => color.withChannelValue(channel.value, value).toString("css");
+		switch (channel.value) {
+			case "hue": return `linear-gradient(to ${to}, ${HUE_STOPS.map((hue) => color.withChannelValue("hue", hue).toString("css")).join(", ")})`;
+			case "lightness": return `linear-gradient(to ${to}, ${at(min)}, ${at((max - min) / 2)}, ${at(max)})`;
+			case "saturation":
+			case "brightness":
+			case "red":
+			case "green":
+			case "blue":
+			case "alpha": return `linear-gradient(to ${to}, ${at(min)}, ${at(max)})`;
+			default: throw new Error("Unknown color channel: " + channel.value);
+		}
+	});
+	/** The bare number the thumb would announce, with the colour it names appended. */
+	const valueText = computed(() => {
+		const text = thumb.inputProps.value["aria-valuetext"];
+		const color = displayColor.value;
+		if (channel.value === "hue") return `${text}, ${color.getHueName(locale.value.locale)}`;
+		if (channel.value !== "alpha") return `${text}, ${color.getColorName(locale.value.locale)}`;
+		return text;
+	});
+	return {
+		displayColor,
+		focusThumb: slider.focusFirstThumb,
+		inputHandlers: thumb.inputHandlers,
+		inputProps: computed(() => ({
+			...thumb.inputProps.value,
+			"aria-valuetext": valueText.value
+		})),
+		inputStyle: {
+			...visuallyHiddenStyle,
+			height: "100%",
+			opacity: 1e-4,
+			pointerEvents: "none",
+			width: "100%"
+		},
+		isDisabled: thumb.isDisabled,
+		isDragging: thumb.isDragging,
+		outputProps: slider.outputProps,
+		thumbHandlers: thumb.thumbHandlers,
+		thumbStyle: computed(() => ({
+			...thumb.thumbStyle.value,
+			backgroundColor: displayColor.value.toString("css"),
+			forcedColorAdjust: "none"
+		})),
+		trackAttrs: slider.groupProps,
+		trackHandlers: slider.trackHandlers,
+		trackStyle: computed(() => ({
+			...slider.trackStyle,
+			background: background.value,
+			forcedColorAdjust: "none"
+		}))
+	};
+};
+//#endregion
+export { useColorSlider };

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

@@ -0,0 +1,37 @@
+import type { Color } from "../utils/color-types";
+import type { ComputedRef, MaybeRefOrGetter, StyleValue } from "vue";
+export interface UseColorSwatchOptions {
+    /** A labelling id supplied by the caller, prepended to the swatch's own. */
+    ariaLabelledby?: MaybeRefOrGetter<string | undefined>;
+    /** A label supplied by the caller, appended after the colour's name. */
+    ariaLabel?: MaybeRefOrGetter<string | undefined>;
+    /** The color value to display in the swatch. */
+    color?: MaybeRefOrGetter<Color | string | undefined>;
+    /**
+     * A localized accessible name for the color. By default one is generated from the colour value,
+     * but a caller with a more specific name — a Pantone number, a brand colour — can say so.
+     */
+    colorName?: MaybeRefOrGetter<string | undefined>;
+    /** Id override for the swatch element. */
+    id?: MaybeRefOrGetter<string | undefined>;
+}
+export interface UseColorSwatchReturn {
+    /** Attributes for the swatch element. Carries no listeners — a swatch is not interactive. */
+    attrs: ComputedRef<Record<string, unknown>>;
+    /** The parsed colour the swatch is showing. */
+    color: ComputedRef<Color>;
+    /** Inline style for the swatch element. */
+    style: ComputedRef<StyleValue>;
+}
+/**
+ * A swatch showing one colour, named for a screen reader.
+ *
+ * Ported from React Aria's `packages/react-aria/src/color/useColorSwatch.ts` (react-aria 3.51.0).
+ * Entirely presentational: there is no interaction here, so unlike every other control in this
+ * package the return has attributes and a style but no handlers.
+ *
+ * `#fff0` is the default because a swatch with no colour is a *transparent* swatch, not an
+ * error — and a fully transparent colour is announced as "transparent" rather than by hue, which
+ * would be meaningless.
+ */
+export declare const useColorSwatch: (options?: UseColorSwatchOptions) => UseColorSwatchReturn;

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

@@ -0,0 +1,54 @@
+import { useId as useId$1 } from "./use-id.js";
+import { useLocale } from "./use-locale.js";
+import { useLocalizedStringFormatter } from "./use-localized-string-formatter.js";
+import { colorStrings } from "../i18n/color.js";
+import { normalizeColor } from "../utils/color.js";
+import { computed, toValue } from "vue";
+//#region src/composables/use-color-swatch.ts
+/**
+* A swatch showing one colour, named for a screen reader.
+*
+* Ported from React Aria's `packages/react-aria/src/color/useColorSwatch.ts` (react-aria 3.51.0).
+* Entirely presentational: there is no interaction here, so unlike every other control in this
+* package the return has attributes and a style but no handlers.
+*
+* `#fff0` is the default because a swatch with no colour is a *transparent* swatch, not an
+* error — and a fully transparent colour is announced as "transparent" rather than by hue, which
+* would be meaningless.
+*/
+var useColorSwatch = (options = {}) => {
+	const locale = useLocale();
+	const strings = useLocalizedStringFormatter(colorStrings);
+	const swatchId = useId$1(() => toValue(options.id));
+	const color = computed(() => normalizeColor(toValue(options.color) || "#fff0"));
+	const colorName = computed(() => {
+		const given = toValue(options.colorName);
+		if (given) return given;
+		return color.value.getChannelValue("alpha") === 0 ? strings.value.format("transparent") : color.value.getColorName(locale.value.locale);
+	});
+	const style = computed(() => ({
+		backgroundColor: color.value.toString("css"),
+		forcedColorAdjust: "none"
+	}));
+	return {
+		attrs: computed(() => {
+			const labelledby = toValue(options.ariaLabelledby);
+			const label = toValue(options.ariaLabel);
+			return {
+				/**
+				* The caller's own label is appended rather than replacing the colour name, so a swatch
+				* labelled "Brand" still announces which colour it is.
+				*/
+				"aria-label": [colorName.value, label ?? ""].filter(Boolean).join(", "),
+				"aria-labelledby": labelledby ? `${swatchId.value} ${labelledby}` : void 0,
+				"aria-roledescription": strings.value.format("colorSwatch"),
+				id: swatchId.value,
+				role: "img"
+			};
+		}),
+		color,
+		style
+	};
+};
+//#endregion
+export { useColorSwatch };

package/dist/composables/use-combo-box-state.d.ts

@@ -0,0 +1,139 @@
+import type { CollectionKey, UseCollectionReturn } from "./use-collection";
+import type { FormValidationState, ValidationBehavior, ValidationFunction } from "./use-form-validation-state";
+import type { FocusStrategy, MenuTriggerState } from "./use-overlay-trigger-state";
+import type { SelectSelectionMode, SelectedItem, SelectedValue } from "./use-select-state";
+import type { DisabledBehavior, UseSelectionManagerReturn } from "./use-selection-manager";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+/**
+ * What made the popover open, which decides whether it shows every option or only the matches.
+ *
+ * Also what `menuTrigger` names: `"focus"` opens on focus, `"input"` on the first keystroke, and
+ * `"manual"` only when the button is pressed or an arrow key is used.
+ */
+export type ComboBoxMenuTrigger = "focus" | "input" | "manual";
+/** Whether an option's text matches what has been typed. */
+export type ComboBoxFilter = (textValue: string, inputValue: string) => boolean;
+/** What a combo box hands `validate`: the chosen key(s) *and* the text beside them. */
+export interface ComboBoxValidationValue {
+    /** The chosen key, or keys when multiple. */
+    value: SelectedValue;
+    /** The text in the input, which may be a value of its own when custom values are allowed. */
+    inputValue: string;
+}
+export interface UseComboBoxStateOptions<T> {
+    /**
+     * The options, as data.
+     *
+     * React Aria renders its children into a hidden tree to learn the collection before the first
+     * paint. Rendering is what creates DOM here, so there is no such pass — and the options only
+     * exist in the DOM while the popover is open. Everything a closed combo box has to answer for
+     * reads this instead: the text the input shows for the chosen option, the list the filter runs
+     * over, and the key the form submits.
+     */
+    items: MaybeRefOrGetter<readonly T[]>;
+    /** An item's key. Defaults to its own `id`, then `key`, then its index. */
+    itemKey?: (item: T, index: number) => CollectionKey;
+    /** Text shown for an item in the input, and matched on by the filter. Defaults to its text. */
+    itemTextValue?: (item: T) => string | undefined;
+    /** Whether an item cannot be chosen. Merges with `disabledKeys`. */
+    itemDisabled?: (item: T) => boolean;
+    /** Whether one or several options can be chosen. @default "single" */
+    selectionMode?: MaybeRefOrGetter<SelectSelectionMode | undefined>;
+    /** The chosen key, or keys when multiple. Controlled. */
+    value?: MaybeRefOrGetter<SelectedValue | undefined>;
+    defaultValue?: SelectedValue;
+    onChange?: (value: SelectedValue) => void;
+    /** Text in the input. Present at all puts the caller in charge of it. */
+    inputValue?: MaybeRefOrGetter<string | undefined>;
+    /** Text the input starts with. Defaults to the chosen option's own text. */
+    defaultInputValue?: MaybeRefOrGetter<string | undefined>;
+    onInputChange?: (value: string) => void;
+    /**
+     * Reports the open state along with what opened it.
+     *
+     * There is no `isOpen`/`defaultOpen` to go with it, and that is upstream's design rather than an
+     * omission: a combo box opens and closes as a consequence of typing, choosing and blurring, so
+     * a caller pinning it open would be fighting its own state machine on every keystroke.
+     */
+    onOpenChange?: (isOpen: boolean, menuTrigger?: ComboBoxMenuTrigger) => void;
+    /** What has to happen for the popover to appear. @default "input" */
+    menuTrigger?: MaybeRefOrGetter<ComboBoxMenuTrigger | undefined>;
+    /**
+     * Whether an option's text matches what has been typed.
+     *
+     * Absent means the locale-aware `contains` of `useFilter`, which is what upstream defaults to.
+     * An explicit `null` means the caller narrows `items` itself — an asynchronous search, or a
+     * list sliced for a virtualizer — and nothing here filters a second time.
+     */
+    defaultFilter?: MaybeRefOrGetter<ComboBoxFilter | null | undefined>;
+    /** Whether text matching no option may stand as the value. */
+    allowsCustomValue?: MaybeRefOrGetter<boolean | undefined>;
+    /** Whether the popover may open with nothing in it. */
+    allowsEmptyCollection?: MaybeRefOrGetter<boolean | undefined>;
+    /** Whether leaving the field commits what is in it and closes the popover. @default true */
+    shouldCloseOnBlur?: MaybeRefOrGetter<boolean | undefined>;
+    /** Keys that cannot be chosen. */
+    disabledKeys?: MaybeRefOrGetter<Iterable<CollectionKey> | undefined>;
+    /** @default "all" */
+    disabledBehavior?: MaybeRefOrGetter<DisabledBehavior | undefined>;
+    isReadOnly?: MaybeRefOrGetter<boolean | undefined>;
+    isInvalid?: MaybeRefOrGetter<boolean | undefined>;
+    validate?: MaybeRefOrGetter<ValidationFunction<ComboBoxValidationValue> | undefined>;
+    validationBehavior?: MaybeRefOrGetter<ValidationBehavior | undefined>;
+    name?: MaybeRefOrGetter<string | undefined>;
+}
+export interface UseComboBoxStateReturn<T> extends MenuTriggerState, FormValidationState {
+    /** The options on screen: the matches while open, and frozen at what they were while closing. */
+    collection: UseCollectionReturn;
+    /**
+     * The same options as data, in the same order.
+     *
+     * Handed out because the markup for the options is written by the caller here, not rendered from
+     * the collection the way React Aria does it — so whoever writes the listbox needs the list. Read
+     * off the displayed collection rather than filtered again, so it freezes with it.
+     */
+    displayedItems: ComputedRef<T[]>;
+    /** The selection, over **every** option rather than only the matches. */
+    selection: UseSelectionManagerReturn;
+    selectionMode: ComputedRef<SelectSelectionMode>;
+    /** The current value: one key when single, a list of them when multiple. */
+    value: ComputedRef<SelectedValue>;
+    /** The value a form reset goes back to. */
+    defaultValue: ComputedRef<SelectedValue>;
+    setValue: (value: SelectedValue) => void;
+    /** The first chosen key, which is the whole value when single. */
+    selectedKey: ComputedRef<CollectionKey | null>;
+    selectedItems: ComputedRef<SelectedItem<T>[]>;
+    /** The text in the input. */
+    inputValue: ComputedRef<string>;
+    /** The text a form reset goes back to. */
+    defaultInputValue: ComputedRef<string>;
+    setInputValue: (value: string) => void;
+    /** Choose whatever the arrows have landed on, or settle the text when they have landed nowhere. */
+    commit: () => void;
+    /** Put the text back to what the chosen option says and close, as Escape does. */
+    revert: () => void;
+    /** Whether the input holds focus. */
+    isFocused: ComputedRef<boolean>;
+    setFocused: (isFocused: boolean) => void;
+    open: (focusStrategy?: FocusStrategy | null, trigger?: ComboBoxMenuTrigger) => void;
+    toggle: (focusStrategy?: FocusStrategy | null, trigger?: ComboBoxMenuTrigger) => void;
+}
+/**
+ * State for a combo box, ported from React Stately's
+ * `packages/react-stately/src/combobox/useComboBoxState.ts` (react-stately 3.49.0).
+ *
+ * What separates this from a select is that the field holds *text*, and the text and the chosen
+ * key have to be kept in step in both directions: typing narrows the options and may clear the
+ * value, while choosing an option writes its name back into the field. Neither direction is a
+ * one-way binding, which is why they are reconciled in one place — see `sync` below — rather than
+ * at each of the events that can move either half.
+ *
+ * The collection is built from **data**, not from what rendered. See `items`.
+ *
+ * @example
+ * ```ts
+ * const state = useComboBoxState({items: () => props.items, value: () => props.value});
+ * ```
+ */
+export declare const useComboBoxState: <T>(options: UseComboBoxStateOptions<T>) => UseComboBoxStateReturn<T>;