ropav 0.2.0 → 0.3.0

package/dist/composables/use-date-picker-group.js

@@ -0,0 +1,113 @@
+import { createFocusManager, tabbableIn } from "../utils/focus.js";
+import { usePress } from "./use-press.js";
+import { useLocale } from "./use-locale.js";
+import { toValue } from "vue";
+//#region src/composables/use-date-picker-group.ts
+/**
+* The segment nearest `fromX` on the given side, measured rather than counted.
+*
+* In a right-to-left locale the segments are laid out right to left while staying in date order in
+* the DOM, so "the next segment to the left" is a question about geometry, not about document
+* order.
+*/
+var findNextSegment = (group, fromX, direction) => {
+	let closest = null;
+	let closestDistance = Infinity;
+	for (const node of tabbableIn(group)) {
+		const distance = node.getBoundingClientRect().left - fromX;
+		const absolute = Math.abs(distance);
+		if (Math.sign(distance) === direction && absolute < closestDistance) {
+			closest = node;
+			closestDistance = absolute;
+		}
+	}
+	return closest;
+};
+/**
+* Keyboard and pointer behaviour for the group around a field's segments.
+*
+* Ported from React Aria's `packages/react-aria/src/datepicker/useDatePickerGroup.ts`
+* (react-aria 3.51.0).
+*
+* Clicking the empty part of a field is the interesting case: it puts the cursor on the last
+* segment before the click that still has nothing in it, so clicking a half-filled field carries
+* on where the typing left off rather than jumping to the end.
+*/
+var useDatePickerGroup = (options) => {
+	const locale = useLocale();
+	const getElement = () => toValue(options.element);
+	const focusManager = createFocusManager(getElement);
+	/** Focus the last segment before `target` that is still empty, or the last one of all. */
+	const focusLast = (target) => {
+		const group = getElement();
+		if (!group) return;
+		const stops = tabbableIn(group);
+		if (stops.length === 0) return;
+		const preceding = target ? stops.filter((node) => Boolean(target.compareDocumentPosition(node) & Node.DOCUMENT_POSITION_PRECEDING)) : [];
+		let index = preceding.length > 0 ? stops.indexOf(preceding[preceding.length - 1]) : stops.length - 1;
+		while (index > 0 && stops[index]?.hasAttribute("data-placeholder") && stops[index - 1]?.hasAttribute("data-placeholder")) index -= 1;
+		stops[index]?.focus();
+	};
+	/**
+	* Where the last press actually landed.
+	*
+	* A press event reports the group as its target, since that is what the listener is on, but
+	* which segment to focus depends on where inside the group the pointer went down. React reaches
+	* for `window.event` to recover that; recording it on the way through is the same information
+	* without the global.
+	*/
+	let pressTarget = null;
+	const { handlers: pressHandlers } = usePress({
+		onPress: (event) => {
+			if (event.pointerType === "touch" || event.pointerType === "pen") focusLast(pressTarget);
+		},
+		onPressStart: (event) => {
+			if (event.pointerType === "mouse") focusLast(pressTarget);
+		},
+		preventFocusOnPress: true
+	});
+	const handlers = {
+		...pressHandlers,
+		onPointerdown: (event) => {
+			pressTarget = event.target instanceof Element ? event.target : null;
+			pressHandlers.onPointerdown(event);
+		}
+	};
+	const onKeydown = (event) => {
+		const handled = () => {
+			event.preventDefault();
+			event.stopPropagation();
+		};
+		if (event.altKey && (event.key === "ArrowDown" || event.key === "ArrowUp")) {
+			if (options.setOpen) {
+				options.setOpen(true);
+				handled();
+			}
+			return;
+		}
+		if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return;
+		if (toValue(options.disableArrowNavigation)) return;
+		const forwards = event.key === "ArrowRight";
+		if (locale.value.direction !== "rtl") {
+			if (forwards) focusManager.focusNext();
+			else focusManager.focusPrevious();
+			handled();
+			return;
+		}
+		const group = getElement();
+		const target = event.target;
+		if (!group || !(target instanceof HTMLElement)) return;
+		const next = findNextSegment(group, target.getBoundingClientRect().left, forwards ? 1 : -1);
+		if (next) {
+			next.focus();
+			handled();
+		}
+	};
+	return {
+		focusManager,
+		handlers,
+		onKeydown
+	};
+};
+//#endregion
+export { useDatePickerGroup };

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

@@ -0,0 +1,69 @@
+import type { FieldOptions, FormatterOptions, Granularity, TimeValue } from "../utils/date-format";
+import type { FormValidationState, ValidationBehavior } from "./use-form-validation-state";
+import type { OverlayTriggerState } from "./use-overlay-trigger-state";
+import type { CalendarDate, DateValue } from "@internationalized/date";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+import { DateFormatter } from "@internationalized/date";
+export interface UseDatePickerStateOptions {
+    value?: MaybeRefOrGetter<DateValue | null | undefined>;
+    defaultValue?: MaybeRefOrGetter<DateValue | null | undefined>;
+    onChange?: (value: DateValue | null) => void;
+    /** The date the empty segments stand on, which is also where the calendar opens. */
+    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>;
+    hourCycle?: MaybeRefOrGetter<12 | 24 | undefined>;
+    hideTimeZone?: MaybeRefOrGetter<boolean | undefined>;
+    shouldForceLeadingZeros?: MaybeRefOrGetter<boolean | undefined>;
+    isInvalid?: MaybeRefOrGetter<boolean | undefined>;
+    validate?: (value: DateValue | null) => string | string[] | true | null | undefined;
+    validationBehavior?: MaybeRefOrGetter<ValidationBehavior | undefined>;
+    name?: MaybeRefOrGetter<string | undefined>;
+    /** Whether the popover closes as soon as a date is picked. @default true */
+    shouldCloseOnSelect?: MaybeRefOrGetter<boolean | (() => boolean) | undefined>;
+    isOpen?: MaybeRefOrGetter<boolean | undefined>;
+    defaultOpen?: boolean;
+    onOpenChange?: (isOpen: boolean) => void;
+}
+export interface DatePickerState extends OverlayTriggerState, FormValidationState {
+    value: ComputedRef<DateValue | null>;
+    defaultValue: ComputedRef<DateValue | null>;
+    setValue: (value: DateValue | null) => void;
+    /**
+     * The date half of the value, which can be set before the time half is.
+     *
+     * A date-and-time picker lets the user pick a day in the calendar and a time in the field, in
+     * either order, so each half is held on its own until both are known.
+     */
+    dateValue: ComputedRef<DateValue | null>;
+    setDateValue: (value: CalendarDate) => void;
+    timeValue: ComputedRef<TimeValue | null>;
+    setTimeValue: (value: TimeValue) => void;
+    granularity: ComputedRef<Granularity>;
+    /** Whether this picker takes a time as well as a date. */
+    hasTime: ComputedRef<boolean>;
+    isInvalid: ComputedRef<boolean>;
+    /** The value written out for a screen reader, in whatever shape the caller asks for. */
+    formatValue: (locale: string, fieldOptions: FieldOptions) => string;
+    getDateFormatter: (locale: string, formatOptions: FormatterOptions) => DateFormatter;
+}
+/**
+ * The state behind a date picker: the value, whether the popover is open, and how the two halves of
+ * a date-and-time value are assembled.
+ *
+ * Ported from react-stately's `packages/react-stately/src/datepicker/useDatePickerState.ts`
+ * (react-stately 3.49.0).
+ *
+ * The picker owns the validation for the field inside it. It holds the value and the bounds, so it
+ * is the only thing that can judge them, and the field reports through this state rather than
+ * reaching a second verdict of its own.
+ */
+export declare const useDatePickerState: (options: UseDatePickerStateOptions) => DatePickerState;

package/dist/composables/use-date-picker-state.js

@@ -0,0 +1,124 @@
+import { useControllableState } from "./use-controllable-state.js";
+import { useOverlayTriggerState } from "./use-overlay-trigger-state.js";
+import { useFormValidationState } from "./use-form-validation-state.js";
+import { getFormatOptions, getPlaceholderTime } from "../utils/date-format.js";
+import { getDateValidationResult } from "../utils/date-validation.js";
+import { useDefaultDateProps } from "./use-default-date-props.js";
+import { computed, shallowRef, toValue } from "vue";
+import { DateFormatter, toCalendarDate, toCalendarDateTime } from "@internationalized/date";
+//#region src/composables/use-date-picker-state.ts
+/**
+* The state behind a date picker: the value, whether the popover is open, and how the two halves of
+* a date-and-time value are assembled.
+*
+* Ported from react-stately's `packages/react-stately/src/datepicker/useDatePickerState.ts`
+* (react-stately 3.49.0).
+*
+* The picker owns the validation for the field inside it. It holds the value and the bounds, so it
+* is the only thing that can judge them, and the field reports through this state rather than
+* reaching a second verdict of its own.
+*/
+var useDatePickerState = (options) => {
+	const overlay = useOverlayTriggerState({
+		defaultOpen: options.defaultOpen,
+		isOpen: () => toValue(options.isOpen),
+		onOpenChange: options.onOpenChange
+	});
+	const { setState: setValue, state: value } = useControllableState({
+		defaultValue: toValue(options.defaultValue) ?? null,
+		onValueChange: options.onChange,
+		value: () => toValue(options.value)
+	});
+	const initialValue = value.value;
+	/** Whatever value the picker can learn its shape from, even before anything is chosen. */
+	const shape = computed(() => value.value || toValue(options.placeholderValue) || null);
+	const { defaultTimeZone, granularity } = useDefaultDateProps(shape, () => toValue(options.granularity));
+	const hasTime = computed(() => granularity.value === "hour" || granularity.value === "minute" || granularity.value === "second");
+	const pendingDate = shallowRef(null);
+	const pendingTime = shallowRef(null);
+	const selectedDate = computed(() => value.value ?? pendingDate.value);
+	const selectedTime = computed(() => {
+		const current = value.value;
+		if (current && "hour" in current) return current;
+		return pendingTime.value;
+	});
+	const showEra = computed(() => value.value?.calendar.identifier === "gregory" && value.value.era === "BC");
+	const formatOpts = computed(() => ({
+		granularity: granularity.value,
+		hideTimeZone: toValue(options.hideTimeZone),
+		hourCycle: toValue(options.hourCycle),
+		shouldForceLeadingZeros: toValue(options.shouldForceLeadingZeros),
+		showEra: showEra.value,
+		timeZone: defaultTimeZone.value
+	}));
+	const validation = useFormValidationState({
+		builtinValidation: computed(() => getDateValidationResult(value.value, toValue(options.minValue), toValue(options.maxValue), options.isDateUnavailable, formatOpts.value)),
+		isInvalid: () => toValue(options.isInvalid),
+		name: () => toValue(options.name),
+		validate: () => options.validate,
+		validationBehavior: () => toValue(options.validationBehavior),
+		value: () => value.value
+	});
+	/** Whether picking a date should close the popover, which the caller may decide per press. */
+	const shouldCloseOnSelect = () => {
+		const requested = toValue(options.shouldCloseOnSelect) ?? true;
+		return typeof requested === "function" ? requested() : requested;
+	};
+	const placeholderTime = () => getPlaceholderTime(toValue(options.defaultValue) ?? toValue(options.placeholderValue));
+	const commitValue = (date, time) => {
+		setValue("timeZone" in time ? time.set(toCalendarDate(date)) : toCalendarDateTime(date, time));
+		pendingDate.value = null;
+		pendingTime.value = null;
+		validation.commitValidation();
+	};
+	/**
+	* Take a date from the calendar without disturbing the time.
+	*
+	* The calendar only knows about days, so committing its answer directly would reset the clock on
+	* a value that already had one.
+	*/
+	const setDateValue = (newValue) => {
+		const shouldClose = shouldCloseOnSelect();
+		if (hasTime.value) {
+			if (selectedTime.value || shouldClose) commitValue(newValue, selectedTime.value ?? placeholderTime());
+			else pendingDate.value = newValue;
+		} else {
+			setValue(newValue);
+			validation.commitValidation();
+		}
+		if (shouldClose) overlay.setOpen(false);
+	};
+	const setTimeValue = (newValue) => {
+		if (selectedDate.value && newValue) commitValue(selectedDate.value, newValue);
+		else pendingTime.value = newValue;
+	};
+	return {
+		...validation,
+		...overlay,
+		dateValue: selectedDate,
+		defaultValue: computed(() => toValue(options.defaultValue) ?? initialValue),
+		formatValue: (locale, fieldOptions) => {
+			const current = value.value;
+			if (!current) return "";
+			return new DateFormatter(locale, getFormatOptions(fieldOptions, formatOpts.value)).format(current.toDate(defaultTimeZone.value ?? "UTC"));
+		},
+		getDateFormatter: (locale, formatOptions) => new DateFormatter(locale, getFormatOptions({}, {
+			...formatOpts.value,
+			...formatOptions
+		})),
+		granularity,
+		hasTime,
+		isInvalid: computed(() => validation.displayValidation.value.isInvalid),
+		setDateValue,
+		setOpen: (isOpen) => {
+			if (!isOpen && !value.value && pendingDate.value && hasTime.value) commitValue(pendingDate.value, pendingTime.value ?? placeholderTime());
+			overlay.setOpen(isOpen);
+		},
+		setTimeValue,
+		setValue,
+		timeValue: selectedTime,
+		value: computed(() => value.value)
+	};
+};
+//#endregion
+export { useDatePickerState };

package/dist/composables/use-date-picker.d.ts

@@ -0,0 +1,122 @@
+import type { DayOfWeek } from "../utils/calendar";
+import type { FocusManager } from "../utils/focus";
+import type { PageBehavior } from "./use-calendar-state";
+import type { DatePickerState } from "./use-date-picker-state";
+import type { FieldIdsContext } from "./use-field-ids";
+import type { FormValidationState } from "./use-form-validation-state";
+import type { UsePressHandlers } from "./use-press";
+import type { DateValue } from "@internationalized/date";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseDatePickerOptions {
+    id?: MaybeRefOrGetter<string | undefined>;
+    ariaLabel?: MaybeRefOrGetter<string | undefined>;
+    ariaLabelledby?: MaybeRefOrGetter<string | undefined>;
+    ariaDescribedby?: MaybeRefOrGetter<string | undefined>;
+    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    isReadOnly?: MaybeRefOrGetter<boolean | 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;
+    /** Which month the calendar opens on while nothing is chosen yet. */
+    placeholderValue?: MaybeRefOrGetter<DateValue | null | undefined>;
+    firstDayOfWeek?: MaybeRefOrGetter<DayOfWeek | undefined>;
+    pageBehavior?: MaybeRefOrGetter<PageBehavior | undefined>;
+    /** The group around the segments and the trigger. A getter: it does not exist yet at setup. */
+    element: MaybeRefOrGetter<HTMLElement | null | undefined>;
+    onFocus?: (event: FocusEvent) => void;
+    onBlur?: (event: FocusEvent) => void;
+    onFocusChange?: (isFocused: boolean) => void;
+}
+/** What the date field nested inside the picker needs from it. */
+export interface DatePickerFieldOptions {
+    /** The field's own id, which is not the group's. */
+    id: ComputedRef<string>;
+    ariaDescribedBy: ComputedRef<string | undefined>;
+    /**
+     * What names the picker, for the segments to repeat after their own part of the date.
+     *
+     * Not the same as what names the group: this one is empty when nothing labels the picker, where
+     * the group falls back to pointing at itself. A segment reading "month, " and then nothing would
+     * be worse than a segment reading "month".
+     */
+    ariaLabelledBy: ComputedRef<string | undefined>;
+    /**
+     * `"presentation"`, always.
+     *
+     * The picker already carries the group role, its name and its description; a second group role
+     * on the segments inside would have a screen reader announce the same thing twice.
+     */
+    role: "presentation";
+    /**
+     * The picker's own focus manager, shared with the field.
+     *
+     * A range picker's row of segments spans *two* fields, so arrow keys have to move across a
+     * boundary neither field can see — which is why the manager belongs to the picker.
+     */
+    focusManager: FocusManager;
+    /** The picker's validation state, which the field reports through instead of judging itself. */
+    validationState: FormValidationState;
+}
+/**
+ * What the calendar inside the popover is driven by.
+ *
+ * The picker holds the value, the bounds and the verdict about them, so the calendar is told all of
+ * it rather than being given any of it in markup.
+ */
+export interface DatePickerCalendarProps {
+    ariaLabel: string;
+    autoFocus: boolean;
+    value: DateValue | null;
+    onChange: (value: DateValue | DateValue[] | null) => void;
+    minValue?: DateValue | null;
+    maxValue?: DateValue | null;
+    isDateUnavailable?: (date: DateValue) => boolean;
+    isDisabled?: boolean;
+    isReadOnly?: boolean;
+    isInvalid: boolean;
+    defaultFocusedValue?: DateValue | null;
+    firstDayOfWeek?: DayOfWeek;
+    pageBehavior?: PageBehavior;
+}
+export interface UseDatePickerReturn {
+    /** Spread with `v-bind` onto the group around the segments. Never carries an `on*` key. */
+    groupAttrs: ComputedRef<Record<string, unknown>>;
+    /** Wire with `@event`, never with `v-bind`. */
+    groupHandlers: UsePressHandlers & {
+        onKeydown: (event: KeyboardEvent) => void;
+        onFocusin: (event: FocusEvent) => void;
+        onFocusout: (event: FocusEvent) => void;
+    };
+    /** Spread onto the button that opens the popover. */
+    triggerAttrs: ComputedRef<Record<string, unknown>>;
+    /** Whether the button is out of action: a read-only picker has nothing to pick. */
+    isTriggerDisabled: ComputedRef<boolean>;
+    /** Opens the popover. Not disabled here — the button reports that itself. */
+    onTriggerPress: () => void;
+    /** Spread onto the popover's dialog element. */
+    dialogAttrs: ComputedRef<Record<string, unknown>>;
+    /** Bind onto the calendar inside the popover. */
+    calendarProps: ComputedRef<DatePickerCalendarProps>;
+    field: DatePickerFieldOptions;
+    /** Pass to `provideFieldIdsContext` so the label, description and error message get their ids. */
+    fieldIds: FieldIdsContext;
+}
+/**
+ * The behaviour and accessibility wiring for a date picker.
+ *
+ * Ported from react-aria's `packages/react-aria/src/datepicker/useDatePicker.ts`
+ * (react-aria 3.51.0).
+ *
+ * Two things travel *down* into the field rather than being rebuilt there, and both are the reason
+ * a picker's segments work with no field root of their own: the focus manager, so arrow keys can
+ * cross from one field to the next, and the validation state, so the field's verdict about a date
+ * is the picker's. react-aria smuggles both through a module-level `WeakMap` keyed by the state
+ * object plus two symbol props; here they are returned for the root to publish through `provide`.
+ */
+export declare const useDatePicker: (options: UseDatePickerOptions, state: DatePickerState) => UseDatePickerReturn;

package/dist/composables/use-date-picker.js

@@ -0,0 +1,154 @@
+import { useId as useId$1 } from "./use-id.js";
+import { createFocusManager } from "../utils/focus.js";
+import { useFieldIds } from "./use-field-ids.js";
+import { useLocale } from "./use-locale.js";
+import { useLocalizedStringFormatter } from "./use-localized-string-formatter.js";
+import { useDescription } from "./use-description.js";
+import { datepickerStrings } from "../i18n/datepicker.js";
+import { useDatePickerGroup } from "./use-date-picker-group.js";
+import { computed, toValue } from "vue";
+import { toCalendarDate } from "@internationalized/date";
+//#region src/composables/use-date-picker.ts
+/**
+* The behaviour and accessibility wiring for a date picker.
+*
+* Ported from react-aria's `packages/react-aria/src/datepicker/useDatePicker.ts`
+* (react-aria 3.51.0).
+*
+* Two things travel *down* into the field rather than being rebuilt there, and both are the reason
+* a picker's segments work with no field root of their own: the focus manager, so arrow keys can
+* cross from one field to the next, and the validation state, so the field's verdict about a date
+* is the picker's. react-aria smuggles both through a module-level `WeakMap` keyed by the state
+* object plus two symbol props; here they are returned for the root to publish through `provide`.
+*/
+var useDatePicker = (options, state) => {
+	const strings = useLocalizedStringFormatter(datepickerStrings);
+	const locale = useLocale();
+	const groupId = useId$1(() => toValue(options.id));
+	const fieldId = useId$1();
+	const triggerId = useId$1();
+	const dialogId = useId$1();
+	const focusManager = createFocusManager(() => toValue(options.element));
+	const { context: fieldIds, describedBy: fieldDescribedBy, labelId } = useFieldIds({
+		labelElementType: "span",
+		onLabelClick: () => focusManager.focusFirst(),
+		slots: [
+			"label",
+			"description",
+			"errorMessage"
+		]
+	});
+	/**
+	* The value in words, for a screen reader to read after the picker's own name.
+	*
+	* The segments read as bare numbers, so the month spelled out is what makes them a date.
+	*/
+	const valueDescription = computed(() => {
+		const date = state.formatValue(locale.value.locale, { month: "long" });
+		return date ? strings.value.format("selectedDateDescription", { date }) : "";
+	});
+	const { describedBy: valueDescribedBy } = useDescription(valueDescription);
+	const describedBy = computed(() => [
+		valueDescribedBy.value,
+		fieldDescribedBy.value,
+		toValue(options.ariaDescribedby)
+	].filter(Boolean).join(" ") || void 0);
+	/** The label this picker actually has, which is nothing at all when none was rendered. */
+	const ownLabelledBy = computed(() => [labelId.value, toValue(options.ariaLabelledby)].filter(Boolean).join(" ") || void 0);
+	/**
+	* What names the picker: an explicit reference, else its own label, else the group itself.
+	*
+	* The last fallback looks circular and is upstream's: with no label rendered, the group is named
+	* by its own contents, and pointing at itself is what keeps the trigger's name — which is built
+	* from this — from being left dangling.
+	*/
+	const labelledBy = computed(() => toValue(options.ariaLabelledby) || labelId.value || groupId.value);
+	const group = useDatePickerGroup({
+		element: options.element,
+		setOpen: (open) => state.setOpen(open)
+	});
+	/**
+	* Whether focus is somewhere inside the picker, tracked by hand rather than through
+	* `useFocusWithin`.
+	*
+	* Moving from a segment to the trigger never left the picker, and neither does opening the
+	* popover — focus lands in the calendar, which is not in this subtree at all but is still part of
+	* the same picker as far as the caller is concerned.
+	*/
+	let isFocused = false;
+	const onFocusin = (event) => {
+		if (isFocused) return;
+		isFocused = true;
+		options.onFocus?.(event);
+		options.onFocusChange?.(true);
+	};
+	const onFocusout = (event) => {
+		if (!isFocused) return;
+		const next = event.relatedTarget;
+		if (next instanceof Node) {
+			if (toValue(options.element)?.contains(next)) return;
+			if (document.getElementById(dialogId.value)?.contains(next)) return;
+		}
+		isFocused = false;
+		options.onBlur?.(event);
+		options.onFocusChange?.(false);
+	};
+	return {
+		calendarProps: computed(() => ({
+			ariaLabel: strings.value.format("calendar"),
+			autoFocus: true,
+			defaultFocusedValue: state.dateValue.value ? void 0 : toValue(options.placeholderValue),
+			firstDayOfWeek: toValue(options.firstDayOfWeek),
+			isDateUnavailable: options.isDateUnavailable,
+			isDisabled: toValue(options.isDisabled),
+			isInvalid: state.isInvalid.value,
+			isReadOnly: toValue(options.isReadOnly),
+			maxValue: toValue(options.maxValue),
+			minValue: toValue(options.minValue),
+			onChange: (value) => {
+				if (value && !Array.isArray(value)) state.setDateValue(toCalendarDate(value));
+			},
+			pageBehavior: toValue(options.pageBehavior),
+			value: state.dateValue.value
+		})),
+		dialogAttrs: computed(() => ({
+			"aria-labelledby": [triggerId.value, labelledBy.value].filter(Boolean).join(" ") || void 0,
+			id: dialogId.value
+		})),
+		field: {
+			ariaDescribedBy: describedBy,
+			ariaLabelledBy: ownLabelledBy,
+			focusManager,
+			id: fieldId,
+			role: "presentation",
+			validationState: state
+		},
+		fieldIds,
+		groupAttrs: computed(() => ({
+			"aria-describedby": describedBy.value,
+			"aria-disabled": toValue(options.isDisabled) || void 0,
+			"aria-label": toValue(options.ariaLabel) || void 0,
+			"aria-labelledby": labelledBy.value,
+			id: groupId.value,
+			role: "group"
+		})),
+		groupHandlers: {
+			...group.handlers,
+			onFocusin,
+			onFocusout,
+			onKeydown: group.onKeydown
+		},
+		isTriggerDisabled: computed(() => Boolean(toValue(options.isDisabled)) || Boolean(toValue(options.isReadOnly))),
+		onTriggerPress: () => state.setOpen(true),
+		triggerAttrs: computed(() => ({
+			"aria-describedby": describedBy.value,
+			"aria-expanded": state.isOpen.value,
+			"aria-haspopup": "dialog",
+			"aria-label": strings.value.format("calendar"),
+			"aria-labelledby": [triggerId.value, labelledBy.value].filter(Boolean).join(" ") || void 0,
+			id: triggerId.value
+		}))
+	};
+};
+//#endregion
+export { useDatePicker };

package/dist/composables/use-date-range-picker-state.d.ts

@@ -0,0 +1,96 @@
+import type { FieldOptions, FormatterOptions, Granularity, TimeValue } from "../utils/date-format";
+import type { DateRange } from "./use-calendar";
+import type { FormValidationState, ValidationBehavior } from "./use-form-validation-state";
+import type { OverlayTriggerState } from "./use-overlay-trigger-state";
+import type { DateValue } from "@internationalized/date";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+import { DateFormatter } from "@internationalized/date";
+/** A range where either end may still be missing, which is what a half-typed range looks like. */
+export interface PartialDateRange {
+    start: DateValue | null;
+    end: DateValue | null;
+}
+/** The time halves of a range, held apart from the dates until both are known. */
+export interface PartialTimeRange {
+    start: TimeValue | null;
+    end: TimeValue | null;
+}
+export interface UseDateRangePickerStateOptions {
+    value?: MaybeRefOrGetter<DateRange | null | undefined>;
+    defaultValue?: MaybeRefOrGetter<DateRange | null | undefined>;
+    onChange?: (value: DateRange | null) => void;
+    /** The date the empty segments stand on, which is also where the calendar opens. */
+    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>;
+    hourCycle?: MaybeRefOrGetter<12 | 24 | undefined>;
+    hideTimeZone?: MaybeRefOrGetter<boolean | undefined>;
+    shouldForceLeadingZeros?: MaybeRefOrGetter<boolean | undefined>;
+    isInvalid?: MaybeRefOrGetter<boolean | undefined>;
+    validate?: (value: DateRange | null) => string | string[] | true | null | undefined;
+    validationBehavior?: MaybeRefOrGetter<ValidationBehavior | undefined>;
+    /** Name the start of the range is submitted under. */
+    startName?: MaybeRefOrGetter<string | undefined>;
+    endName?: MaybeRefOrGetter<string | undefined>;
+    /** Whether the popover closes as soon as a range is picked. @default true */
+    shouldCloseOnSelect?: MaybeRefOrGetter<boolean | (() => boolean) | undefined>;
+    isOpen?: MaybeRefOrGetter<boolean | undefined>;
+    defaultOpen?: boolean;
+    onOpenChange?: (isOpen: boolean) => void;
+}
+export interface DateRangePickerState extends OverlayTriggerState, FormValidationState {
+    /**
+     * The range on screen, which is not the same as the value the caller owns: the two ends are
+     * typed one at a time, and only a complete range is ever emitted.
+     */
+    value: ComputedRef<PartialDateRange>;
+    defaultValue: ComputedRef<DateRange | null>;
+    setValue: (value: PartialDateRange | null) => void;
+    /**
+     * The date half of the range, which can be set before the time half is.
+     *
+     * A range of days and a range of times are picked in either order — the calendar answers one, the
+     * fields the other — so each half is held on its own until both are known.
+     */
+    dateRange: ComputedRef<PartialDateRange | null>;
+    setDateRange: (value: PartialDateRange) => void;
+    timeRange: ComputedRef<PartialTimeRange | null>;
+    setTimeRange: (value: PartialTimeRange) => void;
+    /** Sets the date half of one end, leaving the other alone. */
+    setDate: (part: "start" | "end", value: DateValue | null) => void;
+    setTime: (part: "start" | "end", value: TimeValue | null) => void;
+    /** Sets one end outright, date and time together, which is what a field reports. */
+    setDateTime: (part: "start" | "end", value: DateValue | null) => void;
+    granularity: ComputedRef<Granularity>;
+    /** Whether this picker takes times as well as dates. */
+    hasTime: ComputedRef<boolean>;
+    isInvalid: ComputedRef<boolean>;
+    /** Both ends written out for a screen reader, or `null` while the range is incomplete. */
+    formatValue: (locale: string, fieldOptions: FieldOptions) => {
+        start: string;
+        end: string;
+    } | null;
+    getDateFormatter: (locale: string, formatOptions: FormatterOptions) => DateFormatter;
+}
+/**
+ * The state behind a date range picker: the two ends of the range, whether the popover is open, and
+ * how the dates and the times are assembled into one value.
+ *
+ * Ported from react-stately's `packages/react-stately/src/datepicker/useDateRangePickerState.ts`
+ * (react-stately 3.49.0).
+ *
+ * Two things separate this from a single picker. The value the caller owns is only ever a complete
+ * range, so a half-typed one is held here instead and emitted as `null` — which is why what is on
+ * screen and what has been emitted are two different things. And the picker owns the validation for
+ * both fields inside it: they report through this state rather than each reaching a verdict about
+ * one end in isolation.
+ */
+export declare const useDateRangePickerState: (options: UseDateRangePickerStateOptions) => DateRangePickerState;