ropav 0.2.0 → 0.3.0

package/dist/composables/use-combo-box.js

@@ -0,0 +1,319 @@
+import { useId as useId$1 } from "./use-id.js";
+import { ariaHideOutside } from "../utils/aria-hide-outside.js";
+import { isAppleDevice } from "../utils/platform.js";
+import { useOverlayTrigger } from "./use-overlay-trigger.js";
+import { usePress } from "./use-press.js";
+import { useAutocomplete } from "./use-autocomplete.js";
+import { useLocalizedStringFormatter } from "./use-localized-string-formatter.js";
+import { comboBoxStrings } from "../i18n/combobox.js";
+import { useFormReset } from "./use-form-reset.js";
+import { announce } from "../utils/live-announcer.js";
+import { useLabels } from "./use-labels.js";
+import { useTextField } from "./use-text-field.js";
+import { computed, shallowRef, toValue, watch } from "vue";
+//#region src/composables/use-combo-box.ts
+/** How long two touchend events have to be apart to count as two taps rather than one. */
+var DOUBLE_TOUCH_MS = 500;
+/**
+* Behaviour and accessibility for a combo box, ported from React Aria's
+* `packages/react-aria/src/combobox/useComboBox.ts` (react-aria 3.51.0).
+*
+* The arrangement is that real focus never leaves the input. The arrows move a *nominal* focus
+* over the options, the input names whichever one holds it with `aria-activedescendant`, and Enter
+* acts on it — which is what lets typing and choosing go on in one breath. That much is shared with
+* an autocomplete and comes from {@link useAutocomplete}; what is added here is everything about
+* the text being a value in its own right: Enter commits, Escape reverts, Tab commits and leaves,
+* and the arrows open a shut popover instead of navigating nothing.
+*
+* @example
+* ```ts
+* const state = useComboBoxState({items: () => props.items});
+* const comboBox = useComboBox({keyboard: () => keyboard.value}, state);
+*
+* provideTextFieldControlContext(comboBox.control);
+* ```
+*/
+var useComboBox = (options, state) => {
+	const strings = useLocalizedStringFormatter(comboBoxStrings);
+	const isDisabled = computed(() => Boolean(toValue(options.isDisabled)));
+	const isReadOnly = computed(() => Boolean(toValue(options.isReadOnly)));
+	const { overlayId: listId, triggerAttributes: overlayAttributes } = useOverlayTrigger({ type: "listbox" }, state);
+	const inputElement = shallowRef(null);
+	const triggerElement = shallowRef(null);
+	const focusInput = () => {
+		inputElement.value?.focus();
+	};
+	const autocomplete = useAutocomplete({
+		collection: state.collection,
+		collectionId: listId,
+		disableAutoFocusFirst: true,
+		inputElement,
+		inputValue: () => state.inputValue.value,
+		keyboard: options.keyboard,
+		onInputChange: state.setInputValue,
+		selection: state.selection
+	});
+	/** The option the arrows have landed on, or nothing when the popover is shut. */
+	const focusedKey = computed(() => state.isOpen.value ? state.selection.focusedKey.value : null);
+	/**
+	* Whether a key belongs to the list rather than to the caret.
+	*
+	* Enter is carved out of what {@link useAutocomplete} handles: it selects the focused option
+	* there, but a combo box has more to settle than that — unmatched text to keep or throw away,
+	* a popover to close, and a form submit to hold back — so it is answered here instead.
+	*/
+	const onShortcut = (event) => {
+		switch (event.key) {
+			case "Enter":
+				if (state.isOpen.value) event.preventDefault();
+				state.commit();
+				return true;
+			case "Tab":
+				if (state.isOpen.value) state.commit();
+				return true;
+			case "Escape":
+				state.revert();
+				return !(state.selection.isEmpty.value || state.inputValue.value === "");
+			case "ArrowDown":
+			case "ArrowUp":
+				if (state.isOpen.value) return false;
+				state.open(event.key === "ArrowDown" ? "first" : "last", "manual");
+				return true;
+			default: return false;
+		}
+	};
+	const onKeydown = (event) => {
+		if (isReadOnly.value) {
+			options.onKeydown?.(event);
+			return;
+		}
+		if (!onShortcut(event)) autocomplete.onKeydown(event);
+		options.onKeydown?.(event);
+	};
+	const field = useTextField({
+		ariaActivedescendant: () => autocomplete.inputAttributes.value["aria-activedescendant"],
+		ariaAutocomplete: () => autocomplete.inputAttributes.value["aria-autocomplete"],
+		ariaControls: () => overlayAttributes.value["aria-controls"],
+		ariaDescribedby: options.ariaDescribedby,
+		ariaExpanded: () => overlayAttributes.value["aria-expanded"],
+		ariaLabel: options.ariaLabel,
+		ariaLabelledby: options.ariaLabelledby,
+		autoComplete: () => autocomplete.inputAttributes.value.autocomplete,
+		autoCorrect: () => autocomplete.inputAttributes.value.autocorrect,
+		autoFocus: options.autoFocus,
+		defaultValue: () => state.defaultInputValue.value,
+		form: options.form,
+		id: options.id,
+		inputMode: options.inputMode,
+		isDisabled: options.isDisabled,
+		isReadOnly: options.isReadOnly,
+		isRequired: options.isRequired,
+		maxLength: options.maxLength,
+		minLength: options.minLength,
+		name: options.name,
+		onChange: autocomplete.setInputValue,
+		pattern: options.pattern,
+		placeholder: options.placeholder,
+		role: "combobox",
+		spellCheck: () => autocomplete.inputAttributes.value.spellcheck,
+		validationState: state,
+		value: () => state.inputValue.value
+	});
+	useFormReset(computed(() => inputElement.value), () => state.defaultValue.value, state.setValue);
+	/**
+	* Whether focus is still somewhere inside the combo box.
+	*
+	* The chevron and the options are part of the same widget as the field, and the popover is
+	* rendered at the end of the document — so a blur into either is not a blur out of anything.
+	*/
+	const staysInside = (target) => {
+		if (!(target instanceof Node)) return false;
+		if (triggerElement.value?.contains(target)) return true;
+		const popover = toValue(options.popoverElement);
+		return Boolean(popover?.contains(target));
+	};
+	const control = {
+		attrs: field.attrs,
+		handlers: {
+			onBlur: (event) => {
+				if (staysInside(event.relatedTarget)) return;
+				autocomplete.onBlur();
+				field.handlers.onBlur(event);
+				options.onFocusChange?.(false);
+				state.setFocused(false);
+			},
+			onFocus: (event) => {
+				if (state.isFocused.value) return;
+				field.handlers.onFocus(event);
+				options.onFocusChange?.(true);
+				state.setFocused(true);
+			},
+			onInput: field.handlers.onInput,
+			onKeydown,
+			onKeyup: (event) => {
+				autocomplete.onKeyup(event);
+				field.handlers.onKeyup(event);
+			}
+		},
+		isDisabled: field.isDisabled,
+		isInvalid: field.isInvalid,
+		isReadOnly: field.isReadOnly,
+		isRequired: field.isRequired,
+		registerElement: (element) => {
+			inputElement.value = element instanceof HTMLInputElement ? element : null;
+			field.registerElement(element);
+		},
+		setValueOwned: field.setValueOwned
+	};
+	const triggerId = useId$1();
+	const triggerPress = usePress({
+		isDisabled: () => isDisabled.value || isReadOnly.value,
+		isPressed: () => state.isOpen.value,
+		onPress: (event) => {
+			if (event.pointerType !== "touch") return;
+			state.toggle(null, "manual");
+			focusInput();
+		},
+		onPressStart: (event) => {
+			if (event.pointerType === "touch") return;
+			state.toggle(event.pointerType === "keyboard" || event.pointerType === "virtual" ? "first" : null, "manual");
+			focusInput();
+		},
+		preventFocusOnPress: true
+	});
+	const triggerLabels = useLabels(() => ({
+		"aria-label": strings.value.format("buttonLabel"),
+		"aria-labelledby": toValue(options.ariaLabelledby) ?? field.labelId.value,
+		id: triggerId.value
+	}));
+	const listLabels = useLabels(() => ({
+		"aria-label": strings.value.format("listboxLabel"),
+		"aria-labelledby": toValue(options.ariaLabelledby) ?? field.labelId.value,
+		id: listId.value
+	}));
+	let lastTouchAt = 0;
+	const onTouchend = (event) => {
+		if (isDisabled.value || isReadOnly.value) return;
+		if (event.timeStamp - lastTouchAt < DOUBLE_TOUCH_MS) {
+			event.preventDefault();
+			focusInput();
+			return;
+		}
+		const target = event.target;
+		if (!(target instanceof Element)) return;
+		const rect = target.getBoundingClientRect();
+		const touch = event.changedTouches[0];
+		if (!touch) return;
+		const centreX = Math.ceil(rect.left + .5 * rect.width);
+		const centreY = Math.ceil(rect.top + .5 * rect.height);
+		if (touch.clientX !== centreX || touch.clientY !== centreY) return;
+		event.preventDefault();
+		focusInput();
+		state.toggle(null, "manual");
+		lastTouchAt = event.timeStamp;
+	};
+	watch(inputElement, (element, _previous, onCleanup) => {
+		if (!element) return;
+		element.addEventListener("touchend", onTouchend);
+		onCleanup(() => element.removeEventListener("touchend", onTouchend));
+	}, {
+		flush: "post",
+		immediate: true
+	});
+	/**
+	* Everything but the field and its options is taken out of the accessibility tree while the
+	* popover is open.
+	*
+	* The overlay layer does this for a modal popover; a combo box's is not one, because focus has
+	* to stay in the field behind it. So it is done here, over both halves at once, which is what
+	* keeps a screen reader's browse mode inside the widget it is reading.
+	*/
+	watch([
+		() => state.isOpen.value,
+		inputElement,
+		() => toValue(options.popoverElement)
+	], ([isOpen, input, popover], _previous, onCleanup) => {
+		if (!isOpen || !popover) return;
+		onCleanup(ariaHideOutside([input, popover].filter((element) => element != null)));
+	}, {
+		flush: "post",
+		immediate: true
+	});
+	/** The option the arrows have landed on, announced by hand where the platform needs it. */
+	let lastAnnouncedKey = null;
+	watch(() => focusedKey.value, (key) => {
+		if (!isAppleDevice() || key == null) {
+			lastAnnouncedKey = key == null ? null : String(key);
+			return;
+		}
+		if (String(key) === lastAnnouncedKey) return;
+		lastAnnouncedKey = String(key);
+		const item = state.collection.getItem(key);
+		if (!item) return;
+		announce(strings.value.format("focusAnnouncement", {
+			groupCount: 0,
+			groupTitle: "",
+			isGroupChange: false,
+			isSelected: state.selection.isSelected(key),
+			optionText: item.textValue()
+		}));
+	}, { flush: "post" });
+	/** How many options were on offer last time, so only a change is worth saying. */
+	let lastCount = state.collection.size.value;
+	let wasOpen = state.isOpen.value;
+	watch(() => [state.isOpen.value, state.collection.size.value], ([isOpen, count]) => {
+		const openedWithoutFocus = isOpen !== wasOpen && (state.selection.focusedKey.value == null || isAppleDevice());
+		if (isOpen && (openedWithoutFocus || count !== lastCount)) announce(strings.value.format("countAnnouncement", { optionCount: count }));
+		lastCount = count;
+		wasOpen = isOpen;
+	}, { flush: "post" });
+	/** What was chosen last time, so only a change is worth saying. */
+	let lastSelectedKey = state.selectedKey.value;
+	watch(() => state.selectedKey.value, (key) => {
+		const changed = key !== lastSelectedKey;
+		lastSelectedKey = key;
+		if (!isAppleDevice() || !changed || key == null || !state.isFocused.value) return;
+		const item = state.collection.getItem(key);
+		if (!item) return;
+		announce(strings.value.format("selectedAnnouncement", { optionText: item.textValue() }));
+	}, { flush: "post" });
+	const triggerAttributes = computed(() => ({
+		...overlayAttributes.value,
+		"aria-label": triggerLabels.value["aria-label"],
+		"aria-labelledby": triggerLabels.value["aria-labelledby"],
+		disabled: isDisabled.value || isReadOnly.value || void 0,
+		id: triggerId.value,
+		tabindex: -1,
+		type: "button"
+	}));
+	const triggerResponder = {
+		attrs: triggerAttributes,
+		handlers: computed(() => triggerPress.handlers),
+		isPressed: triggerPress.isPressed,
+		registerElement: (next) => {
+			triggerElement.value = next;
+		}
+	};
+	return {
+		clearVirtualFocus: autocomplete.clearVirtualFocus,
+		control,
+		describedBy: field.describedBy,
+		fieldIds: field.fieldIds,
+		inputElement: computed(() => inputElement.value),
+		inputId: field.inputId,
+		isInvalid: field.isInvalid,
+		labelId: field.labelId,
+		listId,
+		listLabel: computed(() => ({
+			"aria-label": listLabels.value["aria-label"],
+			"aria-labelledby": listLabels.value["aria-labelledby"]
+		})),
+		reassert: field.reassert,
+		triggerAttributes,
+		triggerElement: computed(() => triggerElement.value),
+		triggerResponder,
+		validation: state.displayValidation
+	};
+};
+//#endregion
+export { useComboBox };

package/dist/composables/use-controllable-state.d.ts

@@ -0,0 +1,38 @@
+import type { ComputedRef, MaybeRefOrGetter, WritableComputedRef } from "vue";
+export interface UseControllableStateOptions<T> {
+    /**
+     * Externally controlled value. While this resolves to anything other than
+     * `undefined`, the composable is in controlled mode and never mutates its own state.
+     */
+    value?: MaybeRefOrGetter<T | undefined>;
+    /** Value used in uncontrolled mode. */
+    defaultValue: T;
+    /** Called whenever the value changes, in both controlled and uncontrolled mode. */
+    onValueChange?: (value: T) => void;
+}
+export interface UseControllableStateReturn<T> {
+    /** Current value. Writable — assignment routes through `setState`. */
+    state: WritableComputedRef<T>;
+    /** Whether an external `value` is driving the state. */
+    isControlled: ComputedRef<boolean>;
+    /** Update the value, either directly or with an updater function. */
+    setState: (next: T | ((previous: T) => T)) => void;
+}
+/**
+ * Controlled/uncontrolled state, the Vue counterpart of React Stately's
+ * `useControlledState`.
+ *
+ * In controlled mode the value is read from `value` and `setState` only notifies
+ * `onValueChange` — the owner of `value` decides what happens next. In uncontrolled
+ * mode the value is held internally. `onValueChange` fires only on an actual change.
+ *
+ * @example
+ * ```ts
+ * const {setState, state} = useControllableState<boolean>({
+ *   defaultValue: false,
+ *   onValueChange: (open) => emit("update:open", open),
+ *   value: () => props.open,
+ * });
+ * ```
+ */
+export declare const useControllableState: <T>(options: UseControllableStateOptions<T>) => UseControllableStateReturn<T>;

package/dist/composables/use-controllable-state.js

@@ -0,0 +1,42 @@
+import { computed, shallowRef, toValue } from "vue";
+//#region src/composables/use-controllable-state.ts
+/**
+* Controlled/uncontrolled state, the Vue counterpart of React Stately's
+* `useControlledState`.
+*
+* In controlled mode the value is read from `value` and `setState` only notifies
+* `onValueChange` — the owner of `value` decides what happens next. In uncontrolled
+* mode the value is held internally. `onValueChange` fires only on an actual change.
+*
+* @example
+* ```ts
+* const {setState, state} = useControllableState<boolean>({
+*   defaultValue: false,
+*   onValueChange: (open) => emit("update:open", open),
+*   value: () => props.open,
+* });
+* ```
+*/
+var useControllableState = (options) => {
+	const { defaultValue, onValueChange, value } = options;
+	const uncontrolled = shallowRef(defaultValue);
+	const isControlled = computed(() => toValue(value) !== void 0);
+	const current = computed(() => isControlled.value ? toValue(value) : uncontrolled.value);
+	const setState = (next) => {
+		const previous = current.value;
+		const resolved = typeof next === "function" ? next(previous) : next;
+		if (Object.is(resolved, previous)) return;
+		if (!isControlled.value) uncontrolled.value = resolved;
+		onValueChange?.(resolved);
+	};
+	return {
+		isControlled,
+		setState,
+		state: computed({
+			get: () => current.value,
+			set: setState
+		})
+	};
+};
+//#endregion
+export { useControllableState };

package/dist/composables/use-css-variable.d.ts

@@ -0,0 +1,22 @@
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseCssVariableOptions {
+    /** Takes precedence over the property, for a caller passing the value in as a prop. */
+    override?: MaybeRefOrGetter<string | undefined>;
+    /** @default true */
+    cache?: boolean;
+}
+/**
+ * Read a CSS custom property off the document root.
+ *
+ * Read where it is declared rather than passed down as a default in code, so a theme can move a
+ * timing without the component knowing. Absent on the server, where there is nothing to read from
+ * and the caller falls back to its own default.
+ *
+ * @example
+ * ```ts
+ * const delay = computed(() => parseCssTime(useCssVariable("--tooltip-delay").value));
+ * ```
+ */
+export declare const useCssVariable: (name: MaybeRefOrGetter<string>, options?: UseCssVariableOptions) => ComputedRef<string | undefined>;
+/** Forget everything read so far. For a test that changes a property between cases. */
+export declare const clearCssVariableCache: () => void;

package/dist/composables/use-css-variable.js

@@ -0,0 +1,40 @@
+import { computed, toValue } from "vue";
+//#region src/composables/use-css-variable.ts
+/**
+* Values already read off the document, so a page full of tooltips asks once.
+*
+* Kept at module scope on purpose: a custom property on the root is a theme constant, and a
+* `getComputedStyle` call is a layout read.
+*/
+var cache = /* @__PURE__ */ new Map();
+/**
+* Read a CSS custom property off the document root.
+*
+* Read where it is declared rather than passed down as a default in code, so a theme can move a
+* timing without the component knowing. Absent on the server, where there is nothing to read from
+* and the caller falls back to its own default.
+*
+* @example
+* ```ts
+* const delay = computed(() => parseCssTime(useCssVariable("--tooltip-delay").value));
+* ```
+*/
+var useCssVariable = (name, options = {}) => {
+	const shouldCache = options.cache ?? true;
+	return computed(() => {
+		const override = toValue(options.override);
+		if (override !== void 0) return override;
+		if (typeof document === "undefined") return void 0;
+		const property = toValue(name);
+		if (shouldCache && cache.has(property)) return cache.get(property);
+		const value = getComputedStyle(document.documentElement).getPropertyValue(property).trim() || void 0;
+		if (shouldCache) cache.set(property, value);
+		return value;
+	});
+};
+/** Forget everything read so far. For a test that changes a property between cases. */
+var clearCssVariableCache = () => {
+	cache.clear();
+};
+//#endregion
+export { clearCssVariableCache, useCssVariable };

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

@@ -0,0 +1,98 @@
+import type { FieldOptions, FormatterOptions, Granularity, MaxGranularity } from "../utils/date-format";
+import type { DateSegmentType, SegmentLimits } from "../utils/incomplete-date";
+import type { FormValidationState, ValidationBehavior } from "./use-form-validation-state";
+import type { Calendar, CalendarIdentifier, DateValue } from "@internationalized/date";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+import { DateFormatter } from "@internationalized/date";
+import { IncompleteDate } from "../utils/incomplete-date";
+export interface DateSegment extends Partial<SegmentLimits> {
+    /** Which part of the date this is. */
+    type: DateSegmentType;
+    /** What the segment shows, which is the placeholder while it is still blank. */
+    text: string;
+    /** Whether nothing has been typed here yet. */
+    isPlaceholder: boolean;
+    /** What to show while the segment is blank. */
+    placeholder: string;
+    /** Whether the user can change this segment at all. */
+    isEditable: boolean;
+}
+export interface UseDateFieldStateOptions {
+    value?: MaybeRefOrGetter<DateValue | null | undefined>;
+    defaultValue?: MaybeRefOrGetter<DateValue | null | undefined>;
+    onChange?: (value: DateValue | null) => void;
+    placeholderValue?: MaybeRefOrGetter<DateValue | null | undefined>;
+    minValue?: MaybeRefOrGetter<DateValue | null | undefined>;
+    maxValue?: MaybeRefOrGetter<DateValue | null | undefined>;
+    /**
+     * Rules a date out even though it is inside the range.
+     *
+     * A plain callback rather than a getter: `toValue` cannot tell a predicate from a getter that
+     * returns one, so it would invoke the predicate with no date and use whatever came back.
+     */
+    isDateUnavailable?: (date: DateValue) => boolean;
+    granularity?: MaybeRefOrGetter<Granularity | undefined>;
+    maxGranularity?: MaybeRefOrGetter<MaxGranularity | undefined>;
+    hourCycle?: MaybeRefOrGetter<12 | 24 | undefined>;
+    hideTimeZone?: MaybeRefOrGetter<boolean | undefined>;
+    shouldForceLeadingZeros?: MaybeRefOrGetter<boolean | undefined>;
+    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    isReadOnly?: MaybeRefOrGetter<boolean | undefined>;
+    isRequired?: MaybeRefOrGetter<boolean | undefined>;
+    isInvalid?: MaybeRefOrGetter<boolean | undefined>;
+    validate?: (value: DateValue | null) => string | string[] | true | null | undefined;
+    validationBehavior?: MaybeRefOrGetter<ValidationBehavior | undefined>;
+    /**
+     * A validation state owned by the picker above, which this field reports through.
+     *
+     * The picker holds the value and the bounds, so it is the one that can judge them; without this
+     * the field would build a second state and the two could disagree about the same date.
+     */
+    validationState?: FormValidationState;
+    name?: MaybeRefOrGetter<string | undefined>;
+    /** Overrides the locale in force, for a field that must not follow its surroundings. */
+    locale?: MaybeRefOrGetter<string | undefined>;
+    /** Builds the calendar system for an identifier. Injectable so a build can ship fewer of them. */
+    createCalendar: (identifier: CalendarIdentifier) => Calendar;
+}
+export interface DateFieldState extends FormValidationState {
+    value: ComputedRef<DateValue | null>;
+    defaultValue: ComputedRef<DateValue | null>;
+    /** The current value as a native `Date`, which is what a formatter takes. */
+    dateValue: ComputedRef<Date>;
+    calendar: ComputedRef<Calendar>;
+    segments: ComputedRef<DateSegment[]>;
+    dateFormatter: ComputedRef<DateFormatter>;
+    isInvalid: ComputedRef<boolean>;
+    granularity: ComputedRef<Granularity>;
+    maxGranularity: ComputedRef<MaxGranularity>;
+    isDisabled: ComputedRef<boolean>;
+    isReadOnly: ComputedRef<boolean>;
+    isRequired: ComputedRef<boolean>;
+    setValue: (value: DateValue | IncompleteDate | null) => void;
+    increment: (type: DateSegmentType) => void;
+    decrement: (type: DateSegmentType) => void;
+    incrementPage: (type: DateSegmentType) => void;
+    decrementPage: (type: DateSegmentType) => void;
+    incrementToMax: (type: DateSegmentType) => void;
+    decrementToMin: (type: DateSegmentType) => void;
+    setSegment: (type: DateSegmentType, value: number | string) => void;
+    /** Commits a complete-but-unconstrained value, which is what leaving the field does. */
+    confirmPlaceholder: () => void;
+    clearSegment: (type: DateSegmentType) => void;
+    formatValue: (fieldOptions: FieldOptions) => string;
+    getDateFormatter: (locale: string, formatOptions: FormatterOptions) => DateFormatter;
+}
+/**
+ * The state behind a date field: which segments it has, what each one shows, and what typing or
+ * stepping one of them does.
+ *
+ * Ported from react-stately's `packages/react-stately/src/datepicker/useDateFieldState.ts`
+ * (react-stately 3.49.0).
+ *
+ * The value the owner sees and the value on screen are deliberately two different things. A field
+ * being typed into can hold "February 30" or a year with no month, neither of which is a real date,
+ * so an `IncompleteDate` carries what is displayed and `onChange` only fires once the segments add
+ * up to a date that survives its own validation.
+ */
+export declare const useDateFieldState: (options: UseDateFieldStateOptions) => DateFieldState;