ropav 0.2.0 → 0.3.0

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

@@ -0,0 +1,134 @@
+import type { CalendarSelectionMode, CalendarState } from "./use-calendar-state";
+import type { CalendarDate, DateValue } from "@internationalized/date";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+/**
+ * The extra state a range calendar carries.
+ *
+ * Declared here rather than in the state file because the behaviour hooks are what branch on it:
+ * they take either kind of calendar and tell the two apart by whether `highlightedRange` is
+ * present, exactly as react-aria does.
+ */
+export interface RangeCalendarStateExtras {
+    /** The range under the cursor, which is the pending one while a drag is in progress. */
+    highlightedRange: ComputedRef<CalendarRange | null>;
+    /** The end the user pinned first, or `null` when no range is being built. */
+    anchorDate: ComputedRef<CalendarDate | null>;
+    /** Whether a pointer is dragging a range out. */
+    isDragging: ComputedRef<boolean>;
+    setAnchorDate: (date: CalendarDate | null) => void;
+    setDragging: (isDragging: boolean) => void;
+    highlightDate: (date: CalendarDate) => void;
+    focusNearestAvailableDate: (date: CalendarDate) => void;
+}
+/** Two dates and everything between them, as the calendar on screen numbers them. */
+export interface CalendarRange {
+    start: CalendarDate;
+    end: CalendarDate;
+}
+/**
+ * A selected range, as the caller's own value spells it.
+ *
+ * Kept apart from `CalendarRange` because the two are not the same thing: what is highlighted is
+ * always plain dates in the calendar system on screen, while the value keeps whatever system and
+ * whatever time of day the caller passed in.
+ */
+export interface DateRange {
+    start: DateValue;
+    end: DateValue;
+}
+/** Whatever this calendar has selected: one date, a set of them, or a range. */
+export type CalendarSelectedValue = CalendarDate | CalendarDate[] | DateRange | null;
+/**
+ * Either kind of calendar state, since every behaviour hook below takes both.
+ *
+ * `value` is widened rather than left as the single calendar's, and `selectionMode` becomes optional
+ * — a range calendar has no mode of its own. Everything else the hooks read is common to both, so
+ * they need no narrowing except where they genuinely branch.
+ */
+export type AnyCalendarState = Omit<CalendarState, "selectionMode" | "setValue" | "value"> & {
+    value: ComputedRef<CalendarSelectedValue>;
+    selectionMode?: ComputedRef<CalendarSelectionMode>;
+} & Partial<RangeCalendarStateExtras>;
+/** A range calendar's state: the shared surface, plus the extras, with `value` narrowed to a range. */
+export type RangeCalendarLikeState = Omit<AnyCalendarState, "value"> & RangeCalendarStateExtras & {
+    value: ComputedRef<DateRange | null>;
+};
+/** Whether a range calendar's own state is in play, which is how react-aria branches. */
+export declare const isRangeCalendarState: (state: AnyCalendarState) => state is RangeCalendarLikeState;
+/**
+ * Whether a date needs its era spelled out.
+ *
+ * Only for Gregorian dates before AD 1: "15 June 44" would otherwise read as a year the user
+ * recognises when it is not.
+ */
+export declare const getEraFormat: (date: CalendarDate | undefined) => "short" | undefined;
+/**
+ * A spoken description of what is selected, for announcing a change no visible text reports.
+ *
+ * Ported from react-aria's `packages/react-aria/src/calendar/utils.ts` (react-aria 3.51.0).
+ */
+export declare const useSelectedDateDescription: (state: AnyCalendarState) => ComputedRef<string>;
+/**
+ * A description of the dates on screen, used as the calendar's title and as part of its name.
+ *
+ * Ported from react-aria's `packages/react-aria/src/calendar/utils.ts` (react-aria 3.51.0).
+ *
+ * `isAria` picks between the two readings of the same range: the visible title uses the browser's
+ * own range formatting, while the accessible name spells the separator out as a word.
+ */
+export declare const useVisibleRangeDescription: (startDate: MaybeRefOrGetter<CalendarDate>, endDate: MaybeRefOrGetter<CalendarDate>, timeZone: MaybeRefOrGetter<string>, isAria: boolean) => ComputedRef<string>;
+export interface UseCalendarOptions {
+    id?: MaybeRefOrGetter<string | undefined>;
+    ariaLabel?: MaybeRefOrGetter<string | undefined>;
+    ariaLabelledby?: MaybeRefOrGetter<string | undefined>;
+    ariaDescribedby?: MaybeRefOrGetter<string | undefined>;
+    ariaDetails?: MaybeRefOrGetter<string | undefined>;
+    /** Whether an error message is being rendered, which is what gives its id something to point at. */
+    hasErrorMessage?: MaybeRefOrGetter<boolean | undefined>;
+    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    isInvalid?: MaybeRefOrGetter<boolean | undefined>;
+}
+/** A previous/next button, which the calendar owns because only it knows where the bounds are. */
+export interface CalendarPageButton {
+    /** Spread with `v-bind`. Never carries an `on*` key. */
+    attrs: ComputedRef<Record<string, unknown>>;
+    isDisabled: ComputedRef<boolean>;
+    onPress: () => void;
+    onFocusChange: (isFocused: boolean) => void;
+}
+/**
+ * What the grids and cells need from the calendar above them.
+ *
+ * react-aria smuggles this through a module-level `WeakMap` keyed by the state object, because a
+ * nested grid has no other way to reach the calendar's own labelling. Published through
+ * provide/inject instead, so a grid rendered inside a date picker — with no calendar root of its
+ * own in the tree — still finds it.
+ */
+export interface CalendarShared {
+    ariaLabel: ComputedRef<string | undefined>;
+    ariaLabelledBy: ComputedRef<string | undefined>;
+    errorMessageId: ComputedRef<string | undefined>;
+    selectedDateDescription: ComputedRef<string>;
+}
+export interface UseCalendarReturn {
+    /** Spread with `v-bind` onto the calendar's own element. */
+    attrs: ComputedRef<Record<string, unknown>>;
+    prevButton: CalendarPageButton;
+    nextButton: CalendarPageButton;
+    errorMessageProps: ComputedRef<{
+        id: string | undefined;
+    }>;
+    /** A description of the visible range, for the calendar's heading. */
+    title: ComputedRef<string>;
+    shared: CalendarShared;
+}
+/**
+ * The behaviour and accessibility wiring for a calendar.
+ *
+ * Ported from react-aria's `packages/react-aria/src/calendar/useCalendarBase.ts` and
+ * `useCalendar.ts` (react-aria 3.51.0).
+ *
+ * `role="application"` rather than a grid role on the wrapper is deliberate upstream: it stops a
+ * screen reader's own table navigation from taking the arrow keys the calendar needs.
+ */
+export declare const useCalendar: (options: UseCalendarOptions, state: AnyCalendarState) => UseCalendarReturn;

package/dist/composables/use-calendar.js

@@ -0,0 +1,215 @@
+import { useId as useId$1 } from "./use-id.js";
+import { useLocale } from "./use-locale.js";
+import { useLocalizedStringFormatter } from "./use-localized-string-formatter.js";
+import { calendarStrings } from "../i18n/calendar.js";
+import { announce } from "../utils/live-announcer.js";
+import { useDateFormatter } from "./use-date-formatter.js";
+import { useLabels } from "./use-labels.js";
+import { computed, shallowRef, toValue, watch, watchEffect } from "vue";
+import { endOfMonth, isSameDay, startOfMonth } from "@internationalized/date";
+//#region src/composables/use-calendar.ts
+/** Whether a range calendar's own state is in play, which is how react-aria branches. */
+var isRangeCalendarState = (state) => "highlightedRange" in state;
+/**
+* Whether a date needs its era spelled out.
+*
+* Only for Gregorian dates before AD 1: "15 June 44" would otherwise read as a year the user
+* recognises when it is not.
+*/
+var getEraFormat = (date) => date?.calendar.identifier === "gregory" && date.era === "BC" ? "short" : void 0;
+/**
+* Split a formatted date range back into its two halves and rejoin them with a localised word.
+*
+* `formatRange` produces something like "June 1 – 30, 2026", which reads badly to a screen reader
+* one character at a time. The separator is found as the last literal shared by both ends, and the
+* halves are rejoined through the "{startDate} to {endDate}" message instead.
+*/
+var formatRangeForAria = (dateFormatter, stringFormatter, start, end, timeZone) => {
+	const parts = dateFormatter.formatRangeToParts(start.toDate(timeZone), end.toDate(timeZone));
+	let separatorIndex = -1;
+	for (let index = 0; index < parts.length; index++) {
+		const part = parts[index];
+		if (part.source === "shared" && part.type === "literal") separatorIndex = index;
+		else if (part.source === "endRange") break;
+	}
+	let startValue = "";
+	let endValue = "";
+	for (let index = 0; index < parts.length; index++) if (index < separatorIndex) startValue += parts[index].value;
+	else if (index > separatorIndex) endValue += parts[index].value;
+	return stringFormatter.format("dateRange", {
+		endDate: endValue,
+		startDate: startValue
+	});
+};
+/**
+* A spoken description of what is selected, for announcing a change no visible text reports.
+*
+* Ported from react-aria's `packages/react-aria/src/calendar/utils.ts` (react-aria 3.51.0).
+*/
+var useSelectedDateDescription = (state) => {
+	const stringFormatter = useLocalizedStringFormatter(calendarStrings);
+	const locale = useLocale();
+	const ends = computed(() => {
+		if (isRangeCalendarState(state)) return state.highlightedRange.value ?? {};
+		const value = state.value.value;
+		if (Array.isArray(value)) return {
+			end: value.at(-1),
+			start: value[0]
+		};
+		const date = value && "start" in value ? null : value;
+		return {
+			end: date ?? void 0,
+			start: date ?? void 0
+		};
+	});
+	const dateFormatter = useDateFormatter(() => ({
+		day: "numeric",
+		era: getEraFormat(ends.value.start) || getEraFormat(ends.value.end),
+		month: "long",
+		timeZone: state.timeZone.value,
+		weekday: "long",
+		year: "numeric"
+	}));
+	return computed(() => {
+		const { end, start } = ends.value;
+		if ((state.anchorDate?.value ?? null) || !start || !end) return "";
+		const timeZone = state.timeZone.value;
+		if (isSameDay(start, end)) return stringFormatter.value.format("selectedDateDescription", { date: dateFormatter.value.format(start.toDate(timeZone)) });
+		if (isRangeCalendarState(state)) return stringFormatter.value.format("selectedRangeDescription", { dateRange: formatRangeForAria(dateFormatter.value, stringFormatter.value, start, end, timeZone) });
+		const value = state.value.value;
+		if (Array.isArray(value)) return stringFormatter.value.format("selectedDateDescription", { date: new Intl.ListFormat(locale.value.locale).format(value.map((date) => dateFormatter.value.format(date.toDate(timeZone)))) });
+		return "";
+	});
+};
+/**
+* A description of the dates on screen, used as the calendar's title and as part of its name.
+*
+* Ported from react-aria's `packages/react-aria/src/calendar/utils.ts` (react-aria 3.51.0).
+*
+* `isAria` picks between the two readings of the same range: the visible title uses the browser's
+* own range formatting, while the accessible name spells the separator out as a word.
+*/
+var useVisibleRangeDescription = (startDate, endDate, timeZone, isAria) => {
+	const stringFormatter = useLocalizedStringFormatter(calendarStrings);
+	const era = computed(() => getEraFormat(toValue(startDate)) || getEraFormat(toValue(endDate)));
+	const monthFormatter = useDateFormatter(() => ({
+		calendar: toValue(startDate).calendar.identifier,
+		era: era.value,
+		month: "long",
+		timeZone: toValue(timeZone),
+		year: "numeric"
+	}));
+	const dateFormatter = useDateFormatter(() => ({
+		calendar: toValue(startDate).calendar.identifier,
+		day: "numeric",
+		era: era.value,
+		month: "long",
+		timeZone: toValue(timeZone),
+		year: "numeric"
+	}));
+	return computed(() => {
+		const start = toValue(startDate);
+		const end = toValue(endDate);
+		const zone = toValue(timeZone);
+		if (isSameDay(start, startOfMonth(start))) {
+			const startMonth = start.calendar.getFormattableMonth?.(start) ?? start;
+			const endMonth = end.calendar.getFormattableMonth?.(end) ?? end;
+			if (isSameDay(end, endOfMonth(start))) return monthFormatter.value.format(startMonth.toDate(zone));
+			if (isSameDay(end, endOfMonth(end))) return isAria ? formatRangeForAria(monthFormatter.value, stringFormatter.value, startMonth, endMonth, zone) : monthFormatter.value.formatRange(startMonth.toDate(zone), endMonth.toDate(zone));
+		}
+		return isAria ? formatRangeForAria(dateFormatter.value, stringFormatter.value, start, end, zone) : dateFormatter.value.formatRange(start.toDate(zone), end.toDate(zone));
+	});
+};
+/**
+* An id that resolves to `undefined` unless something in the document actually uses it.
+*
+* Ported from react-aria's `useSlotId`. The calendar hands its cells an `aria-describedby`
+* pointing at an error message that the caller may never render — a dangling reference reads as a
+* broken control to a screen reader, so the id disappears when no element claims it.
+*/
+var useSlotId = (deps) => {
+	const id = useId$1();
+	const isUsed = shallowRef(true);
+	watchEffect(() => {
+		toValue(deps);
+		isUsed.value = Boolean(document.getElementById(id.value));
+	}, { flush: "post" });
+	return computed(() => isUsed.value ? id.value : void 0);
+};
+/**
+* The behaviour and accessibility wiring for a calendar.
+*
+* Ported from react-aria's `packages/react-aria/src/calendar/useCalendarBase.ts` and
+* `useCalendar.ts` (react-aria 3.51.0).
+*
+* `role="application"` rather than a grid role on the wrapper is deliberate upstream: it stops a
+* screen reader's own table navigation from taking the arrow keys the calendar needs.
+*/
+var useCalendar = (options, state) => {
+	const stringFormatter = useLocalizedStringFormatter(calendarStrings);
+	const title = useVisibleRangeDescription(() => state.visibleRange.value.start, () => state.visibleRange.value.end, () => state.timeZone.value, false);
+	const visibleRangeDescription = useVisibleRangeDescription(() => state.visibleRange.value.start, () => state.visibleRange.value.end, () => state.timeZone.value, true);
+	watch(visibleRangeDescription, (description) => {
+		if (!state.isFocused.value) announce(description);
+	});
+	const selectedDateDescription = useSelectedDateDescription(state);
+	watch(selectedDateDescription, (description) => {
+		if (description) announce(description, "polite");
+	});
+	const errorMessageId = useSlotId(() => [Boolean(toValue(options.hasErrorMessage)), toValue(options.isInvalid)]);
+	const isNextFocused = shallowRef(false);
+	const isPreviousFocused = shallowRef(false);
+	const isNextDisabled = computed(() => Boolean(toValue(options.isDisabled)) || state.isNextVisibleRangeInvalid());
+	const isPreviousDisabled = computed(() => Boolean(toValue(options.isDisabled)) || state.isPreviousVisibleRangeInvalid());
+	watch([isNextDisabled, isNextFocused], ([isDisabled, isFocused]) => {
+		if (isDisabled && isFocused) {
+			isNextFocused.value = false;
+			state.setFocused(true);
+		}
+	});
+	watch([isPreviousDisabled, isPreviousFocused], ([isDisabled, isFocused]) => {
+		if (isDisabled && isFocused) {
+			isPreviousFocused.value = false;
+			state.setFocused(true);
+		}
+	});
+	const labels = useLabels(() => ({
+		"aria-label": [toValue(options.ariaLabel), visibleRangeDescription.value].filter(Boolean).join(", "),
+		"aria-labelledby": toValue(options.ariaLabelledby),
+		id: toValue(options.id)
+	}));
+	return {
+		attrs: computed(() => ({
+			...labels.value,
+			"aria-describedby": toValue(options.ariaDescribedby) || void 0,
+			"aria-details": toValue(options.ariaDetails) || void 0,
+			role: "application"
+		})),
+		errorMessageProps: computed(() => ({ id: errorMessageId.value })),
+		nextButton: {
+			attrs: computed(() => ({ "aria-label": stringFormatter.value.format("next") })),
+			isDisabled: isNextDisabled,
+			onFocusChange: (isFocused) => {
+				isNextFocused.value = isFocused;
+			},
+			onPress: () => state.focusNextPage()
+		},
+		prevButton: {
+			attrs: computed(() => ({ "aria-label": stringFormatter.value.format("previous") })),
+			isDisabled: isPreviousDisabled,
+			onFocusChange: (isFocused) => {
+				isPreviousFocused.value = isFocused;
+			},
+			onPress: () => state.focusPreviousPage()
+		},
+		shared: {
+			ariaLabel: computed(() => toValue(options.ariaLabel)),
+			ariaLabelledBy: computed(() => toValue(options.ariaLabelledby)),
+			errorMessageId,
+			selectedDateDescription
+		},
+		title
+	};
+};
+//#endregion
+export { getEraFormat, isRangeCalendarState, useCalendar, useSelectedDateDescription, useVisibleRangeDescription };

package/dist/composables/use-checkbox-group-state.d.ts

@@ -0,0 +1,69 @@
+import type { FormValidationState, ValidationBehavior, ValidationFunction } from "./use-form-validation-state";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseCheckboxGroupStateOptions {
+    /** Selected values. Makes the group controlled. */
+    value?: MaybeRefOrGetter<string[] | undefined>;
+    /** Values selected to begin with, when the group is uncontrolled. */
+    defaultValue?: MaybeRefOrGetter<string[] | undefined>;
+    onValueChange?: (value: string[]) => void;
+    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    isReadOnly?: MaybeRefOrGetter<boolean | undefined>;
+    /** Whether at least one item has to be selected. */
+    isRequired?: MaybeRefOrGetter<boolean | undefined>;
+    isInvalid?: MaybeRefOrGetter<boolean | undefined>;
+    validate?: MaybeRefOrGetter<ValidationFunction<string[]> | undefined>;
+    validationBehavior?: MaybeRefOrGetter<ValidationBehavior | undefined>;
+    /** Name every item submits under, and the key server errors arrive on. */
+    name?: MaybeRefOrGetter<string | undefined>;
+}
+export interface CheckboxGroupState {
+    /** Currently selected values. */
+    value: ComputedRef<string[]>;
+    /** Values a form reset goes back to. */
+    defaultValue: ComputedRef<string[]>;
+    isDisabled: ComputedRef<boolean>;
+    isReadOnly: ComputedRef<boolean>;
+    /** Requiredness as the group announces it. */
+    isRequired: ComputedRef<boolean>;
+    /**
+     * Requiredness as each item *renders* it — true only while nothing is selected. See
+     * `useCheckboxGroupState` for why it has to drop off every item at once.
+     */
+    isItemRequired: ComputedRef<boolean>;
+    isInvalid: ComputedRef<boolean>;
+    /** The group's own validation, which its `FieldError` shows. */
+    validation: FormValidationState;
+    /** What each item hands to `useFormValidation`. */
+    itemValidation: FormValidationState;
+    isSelected: (value: string) => boolean;
+    setValue: (value: string[]) => void;
+    addValue: (value: string) => void;
+    removeValue: (value: string) => void;
+    toggleValue: (value: string, isSelected: boolean) => void;
+    /** Item inputs register here so the group can read validity off real elements. */
+    registerInput: (input: HTMLInputElement) => () => void;
+}
+/**
+ * Selection and validation for a group of checkboxes, ported from React Aria's
+ * `packages/react-stately/src/checkbox/useCheckboxGroupState.ts` (react-stately 3.49.0).
+ *
+ * The interesting part is `isRequired`. HTML can say "this control is required" but has no
+ * way to say "at least one control of this name", so the group emulates it: while nothing is
+ * selected, **every** item renders `required`, so the browser refuses the submit and reports
+ * `valueMissing`. The moment anything is selected the flag drops off *all* of them at once —
+ * which is the whole trick, because one leftover `required` unchecked sibling would keep the
+ * form invalid for good.
+ *
+ * The violation therefore lands on the items rather than on the group, so the group reads it
+ * back from the inputs that registered with it.
+ *
+ * @example
+ * ```ts
+ * const state = useCheckboxGroupState({
+ *   isRequired: () => props.isRequired,
+ *   onValueChange: (value) => emit("change", value),
+ *   value: () => props.value,
+ * });
+ * ```
+ */
+export declare const useCheckboxGroupState: (options?: UseCheckboxGroupStateOptions) => CheckboxGroupState;

package/dist/composables/use-checkbox-group-state.js

@@ -0,0 +1,106 @@
+import { useControllableState } from "./use-controllable-state.js";
+import { DEFAULT_VALIDATION_RESULT, getNativeValidation, useFormValidationState } from "./use-form-validation-state.js";
+import { computed, nextTick, toValue } from "vue";
+//#region src/composables/use-checkbox-group-state.ts
+/**
+* Selection and validation for a group of checkboxes, ported from React Aria's
+* `packages/react-stately/src/checkbox/useCheckboxGroupState.ts` (react-stately 3.49.0).
+*
+* The interesting part is `isRequired`. HTML can say "this control is required" but has no
+* way to say "at least one control of this name", so the group emulates it: while nothing is
+* selected, **every** item renders `required`, so the browser refuses the submit and reports
+* `valueMissing`. The moment anything is selected the flag drops off *all* of them at once —
+* which is the whole trick, because one leftover `required` unchecked sibling would keep the
+* form invalid for good.
+*
+* The violation therefore lands on the items rather than on the group, so the group reads it
+* back from the inputs that registered with it.
+*
+* @example
+* ```ts
+* const state = useCheckboxGroupState({
+*   isRequired: () => props.isRequired,
+*   onValueChange: (value) => emit("change", value),
+*   value: () => props.value,
+* });
+* ```
+*/
+var useCheckboxGroupState = (options = {}) => {
+	const defaultValue = computed(() => toValue(options.defaultValue) ?? []);
+	const { setState, state } = useControllableState({
+		defaultValue: defaultValue.value,
+		onValueChange: options.onValueChange,
+		value: () => toValue(options.value)
+	});
+	const value = computed(() => state.value);
+	const isDisabled = computed(() => Boolean(toValue(options.isDisabled)));
+	const isReadOnly = computed(() => Boolean(toValue(options.isReadOnly)));
+	const isRequired = computed(() => Boolean(toValue(options.isRequired)));
+	const isItemRequired = computed(() => isRequired.value && value.value.length === 0);
+	const validation = useFormValidationState({
+		isInvalid: () => toValue(options.isInvalid),
+		name: () => toValue(options.name),
+		validate: () => toValue(options.validate),
+		validationBehavior: () => toValue(options.validationBehavior),
+		value: () => value.value
+	});
+	const inputs = /* @__PURE__ */ new Set();
+	const registerInput = (input) => {
+		inputs.add(input);
+		return () => {
+			inputs.delete(input);
+		};
+	};
+	const readNativeValidation = () => {
+		for (const input of inputs) {
+			if (input.disabled || input.validity.valid) continue;
+			return getNativeValidation(input);
+		}
+		return DEFAULT_VALIDATION_RESULT;
+	};
+	const setValue = (next) => {
+		if (isReadOnly.value || isDisabled.value) return;
+		setState(next);
+	};
+	const isSelected = (itemValue) => value.value.includes(itemValue);
+	const addValue = (itemValue) => {
+		if (isSelected(itemValue)) return;
+		setValue([...value.value, itemValue]);
+	};
+	const removeValue = (itemValue) => {
+		if (!isSelected(itemValue)) return;
+		setValue(value.value.filter((existing) => existing !== itemValue));
+	};
+	const toggleValue = (itemValue, nextIsSelected) => {
+		if (nextIsSelected) addValue(itemValue);
+		else removeValue(itemValue);
+	};
+	return {
+		addValue,
+		defaultValue,
+		isDisabled,
+		isInvalid: computed(() => validation.displayValidation.value.isInvalid),
+		isItemRequired,
+		isReadOnly,
+		isRequired,
+		isSelected,
+		itemValidation: {
+			...validation,
+			commitValidation: () => {
+				nextTick(() => {
+					validation.updateValidation(readNativeValidation());
+					validation.commitValidation();
+				});
+			},
+			updateValidation: () => {}
+		},
+		registerInput,
+		removeValue,
+		setValue,
+		toggleValue,
+		validation,
+		value
+	};
+};
+//#endregion
+export { useCheckboxGroupState };

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

@@ -0,0 +1,6 @@
+import type { ComputedRef } from "vue";
+/**
+ * An `Intl.Collator` for the locale that applies here, ported from React Aria's
+ * `packages/react-aria/src/i18n/useCollator.ts` (react-aria 3.51.0).
+ */
+export declare const useCollator: (options?: Intl.CollatorOptions) => ComputedRef<Intl.Collator>;

package/dist/composables/use-collator.js

@@ -0,0 +1,29 @@
+import { useLocale } from "./use-locale.js";
+import { computed } from "vue";
+//#region src/composables/use-collator.ts
+/**
+* Collators built so far, keyed by locale and options.
+*
+* Building one is expensive enough that React Aria caches them across components, and a collator
+* is stateless once built. Unbounded, as upstream: the key space is the set of locale/option pairs
+* a build actually uses, which is small and fixed.
+*/
+var collators = /* @__PURE__ */ new Map();
+var cacheKey = (locale, options) => locale + (options ? Object.entries(options).sort((a, b) => a[0] < b[0] ? -1 : 1).join() : "");
+/**
+* An `Intl.Collator` for the locale that applies here, ported from React Aria's
+* `packages/react-aria/src/i18n/useCollator.ts` (react-aria 3.51.0).
+*/
+var useCollator = (options) => {
+	const locale = useLocale();
+	return computed(() => {
+		const key = cacheKey(locale.value.locale, options);
+		const cached = collators.get(key);
+		if (cached) return cached;
+		const collator = new Intl.Collator(locale.value.locale, options);
+		collators.set(key, collator);
+		return collator;
+	});
+};
+//#endregion
+export { useCollator };

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

@@ -0,0 +1,32 @@
+import type { UseListKeyboardReturn } from "./use-list-keyboard";
+import type { FocusStrategy } from "./use-overlay-trigger-state";
+import type { UseSelectionManagerReturn } from "./use-selection-manager";
+import type { MaybeRefOrGetter, ShallowRef } from "vue";
+export interface UseCollectionAutoFocusOptions {
+    /** The element carrying the collection role, which takes focus when no item does. */
+    element: ShallowRef<HTMLElement | null>;
+    keyboard: UseListKeyboardReturn;
+    selection: UseSelectionManagerReturn;
+    /**
+     * Where focus lands when the collection appears. `"first"`/`"last"` pick an end, `true` focuses
+     * the collection itself, and a selected item wins over any of them.
+     */
+    autoFocus?: MaybeRefOrGetter<boolean | FocusStrategy | undefined>;
+}
+/**
+ * Move focus in once, when a collection inside an overlay appears.
+ *
+ * A selected item wins over the requested end of the list, because reopening a list of choices on
+ * the choice already made is where the user left off. With nothing selected and no end asked for,
+ * the collection itself takes focus — that is what makes the first arrow press start from the top
+ * rather than from wherever focus happened to be.
+ *
+ * Shared by the menu and by a listbox driven from above, which are the two collections that appear
+ * already open and so have to place focus for themselves.
+ *
+ * @example
+ * ```ts
+ * useCollectionAutoFocus({autoFocus: () => target.autoFocus.value, element, keyboard, selection});
+ * ```
+ */
+export declare const useCollectionAutoFocus: (options: UseCollectionAutoFocusOptions) => void;

package/dist/composables/use-collection-auto-focus.js

@@ -0,0 +1,43 @@
+import { nextTick, toValue, watch } from "vue";
+//#region src/composables/use-collection-auto-focus.ts
+/**
+* Move focus in once, when a collection inside an overlay appears.
+*
+* A selected item wins over the requested end of the list, because reopening a list of choices on
+* the choice already made is where the user left off. With nothing selected and no end asked for,
+* the collection itself takes focus — that is what makes the first arrow press start from the top
+* rather than from wherever focus happened to be.
+*
+* Shared by the menu and by a listbox driven from above, which are the two collections that appear
+* already open and so have to place focus for themselves.
+*
+* @example
+* ```ts
+* useCollectionAutoFocus({autoFocus: () => target.autoFocus.value, element, keyboard, selection});
+* ```
+*/
+var useCollectionAutoFocus = (options) => {
+	const { element, keyboard, selection } = options;
+	let hasAutoFocused = false;
+	watch(element, (current) => {
+		if (!current || hasAutoFocused) return;
+		hasAutoFocused = true;
+		const autoFocus = toValue(options.autoFocus);
+		if (!autoFocus) return;
+		nextTick(() => {
+			if (current.contains(current.ownerDocument.activeElement)) return;
+			let focusedKey = null;
+			if (autoFocus === "first") focusedKey = keyboard.getFirstKey();
+			if (autoFocus === "last") focusedKey = keyboard.getLastKey();
+			for (const key of selection.selectedKeys.value) if (selection.canSelectItem(key)) {
+				focusedKey = key;
+				break;
+			}
+			selection.setFocused(true);
+			if (focusedKey == null) current.focus({ preventScroll: true });
+			else keyboard.focusKey(focusedKey);
+		});
+	}, { flush: "post" });
+};
+//#endregion
+export { useCollectionAutoFocus };