ropav 0.2.0 → 0.3.0

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

@@ -0,0 +1,334 @@
+import { useId as useId$1 } from "./use-id.js";
+import { isIOS } from "../utils/platform.js";
+import { useLocale } from "./use-locale.js";
+import { useDateFormatter } from "./use-date-formatter.js";
+import { useDisplayNames } from "./use-display-names.js";
+import { useLabels } from "./use-labels.js";
+import { useSpinButton } from "./use-spin-button.js";
+import { useFilter } from "./use-filter.js";
+import { computed, onScopeDispose, toValue } from "vue";
+import { CalendarDate, toCalendar } from "@internationalized/date";
+import { NumberParser } from "@internationalized/number";
+//#region src/composables/use-date-segment.ts
+/** How many leading characters every string in the list shares. */
+var commonPrefixLength = (strings) => {
+	const sorted = [...strings].sort();
+	const first = sorted[0] ?? "";
+	const last = sorted[sorted.length - 1] ?? "";
+	for (let index = 0; index < first.length; index += 1) if (first[index] !== last[index]) return index;
+	return 0;
+};
+/** The day-period name a 12-hour clock uses for the given hour. */
+var dayPeriodName = (formatter, hour) => {
+	const date = /* @__PURE__ */ new Date();
+	date.setHours(hour);
+	return formatter.formatToParts(date).find((part) => part.type === "dayPeriod")?.value ?? "";
+};
+/**
+* Behaviour and accessibility for one segment of a date field.
+*
+* Ported from React Aria's `packages/react-aria/src/datepicker/useDateSegment.ts`
+* (react-aria 3.51.0).
+*
+* A segment is a `contenteditable` span that behaves like a spin button: arrows step it, digits
+* type into it, and it hands focus on to the next segment as soon as no further digit could fit.
+* Everything the browser would normally do with the typed text is cancelled — `beforeinput` is
+* always prevented and the state decides what the segment shows — so the DOM never disagrees with
+* the value.
+*/
+var useDateSegment = (options) => {
+	const { focusManager, state } = options;
+	const locale = useLocale();
+	const displayNames = useDisplayNames();
+	const segment = computed(() => toValue(options.segment));
+	const getElement = () => toValue(options.element) ?? null;
+	/** The digits typed into this segment so far, which is how "23" follows "2". */
+	let enteredKeys = "";
+	/** The segment's text as it stood when a composition began, to put back afterwards. */
+	let composed = "";
+	const resolvedOptions = computed(() => state.dateFormatter.value.resolvedOptions());
+	const monthFormatter = useDateFormatter(() => ({
+		month: "long",
+		timeZone: resolvedOptions.value.timeZone
+	}));
+	const hourFormatter = useDateFormatter(() => ({
+		hour: "numeric",
+		hour12: resolvedOptions.value.hour12,
+		timeZone: resolvedOptions.value.timeZone
+	}));
+	/**
+	* How the segment should be read out.
+	*
+	* A month reads as its name as well as its number, and an hour as the clock reads it, because
+	* "3" alone says nothing about which three.
+	*/
+	const textValue = computed(() => {
+		const current = segment.value;
+		if (current.isPlaceholder) return "";
+		if (current.type === "month") {
+			const name = monthFormatter.value.format(state.dateValue.value);
+			return name === current.text ? name : `${current.text} – ${name}`;
+		}
+		if (current.type === "hour") return hourFormatter.value.format(state.dateValue.value);
+		return current.text;
+	});
+	const spin = useSpinButton({
+		isDisabled: state.isDisabled,
+		isReadOnly: () => state.isReadOnly.value || !segment.value.isEditable,
+		isRequired: state.isRequired,
+		maxValue: () => segment.value.maxValue,
+		minValue: () => segment.value.minValue,
+		onDecrement: () => {
+			enteredKeys = "";
+			state.decrement(segment.value.type);
+		},
+		onDecrementPage: () => {
+			enteredKeys = "";
+			state.decrementPage(segment.value.type);
+		},
+		onDecrementToMin: () => {
+			enteredKeys = "";
+			state.decrementToMin(segment.value.type);
+		},
+		onIncrement: () => {
+			enteredKeys = "";
+			state.increment(segment.value.type);
+		},
+		onIncrementPage: () => {
+			enteredKeys = "";
+			state.incrementPage(segment.value.type);
+		},
+		onIncrementToMax: () => {
+			enteredKeys = "";
+			state.incrementToMax(segment.value.type);
+		},
+		textValue,
+		value: () => segment.value.value ?? void 0
+	});
+	const parser = computed(() => new NumberParser(locale.value.locale, { maximumFractionDigits: 0 }));
+	const filter = useFilter({ sensitivity: "base" });
+	const dayPeriodFormatter = useDateFormatter({
+		hour: "numeric",
+		hour12: true
+	});
+	const am = computed(() => dayPeriodName(dayPeriodFormatter.value, 0));
+	const pm = computed(() => dayPeriodName(dayPeriodFormatter.value, 12));
+	const eraFormatter = useDateFormatter({
+		era: "narrow",
+		timeZone: "UTC",
+		year: "numeric"
+	});
+	/**
+	* The era names, so typing their first character picks one.
+	*
+	* Their common prefix is dropped first: a calendar whose eras are named ERA0 and ERA1 would
+	* otherwise offer nothing to tell them apart by, and Ethiopic is exactly that case.
+	*/
+	const eras = computed(() => {
+		if (segment.value.type !== "era") return [];
+		const base = toCalendar(new CalendarDate(1, 1, 1), state.calendar.value);
+		const named = state.calendar.value.getEras().map((era) => ({
+			era,
+			formatted: eraFormatter.value.formatToParts(base.set({
+				day: 1,
+				era,
+				month: 1,
+				year: 1
+			}).toDate("UTC")).find((part) => part.type === "era")?.value ?? ""
+		}));
+		const prefix = commonPrefixLength(named.map((entry) => entry.formatted));
+		return prefix ? named.map((entry) => ({
+			...entry,
+			formatted: entry.formatted.slice(prefix)
+		})) : named;
+	});
+	const type = () => segment.value.type;
+	const backspace = () => {
+		const current = segment.value;
+		if (current.text === current.placeholder) focusManager.focusPrevious();
+		if (parser.value.isValidPartialNumber(current.text) && !state.isReadOnly.value && !current.isPlaceholder) {
+			const trimmed = current.text.slice(0, -1);
+			const parsed = parser.value.parse(trimmed);
+			if (trimmed.length === 0 || parsed === 0) state.clearSegment(current.type);
+			else state.setSegment(current.type, parsed);
+			enteredKeys = parsed === 0 ? "" : trimmed;
+		} else if (current.type === "dayPeriod" || current.type === "era") state.clearSegment(current.type);
+	};
+	/** Take one typed character, which is not the same as taking one digit. */
+	const typeCharacter = (key) => {
+		if (state.isDisabled.value || state.isReadOnly.value) return;
+		const current = segment.value;
+		const candidate = enteredKeys + key;
+		switch (current.type) {
+			case "dayPeriod": {
+				const { startsWith } = filter.value;
+				if (startsWith(am.value, key)) state.setSegment("dayPeriod", 0);
+				else if (startsWith(pm.value, key)) state.setSegment("dayPeriod", 1);
+				else return;
+				focusManager.focusNext();
+				return;
+			}
+			case "era": {
+				const matched = eras.value.find((entry) => filter.value.startsWith(entry.formatted, key));
+				if (!matched) return;
+				state.setSegment("era", matched.era);
+				focusManager.focusNext();
+				return;
+			}
+			case "day":
+			case "hour":
+			case "minute":
+			case "month":
+			case "second":
+			case "year": {
+				if (!parser.value.isValidPartialNumber(candidate)) return;
+				const typed = parser.value.parse(candidate);
+				if (Number.isNaN(typed)) return;
+				const { maxValue } = current;
+				const next = maxValue !== void 0 && typed > maxValue ? parser.value.parse(key) : typed;
+				state.setSegment(current.type, next);
+				if (maxValue !== void 0 && (Number(`${typed}0`) > maxValue || candidate.length >= String(maxValue).length)) {
+					enteredKeys = "";
+					focusManager.focusNext();
+				} else enteredKeys = candidate;
+				return;
+			}
+			default: return;
+		}
+	};
+	const onFocus = () => {
+		const element = getElement();
+		enteredKeys = "";
+		element?.scrollIntoView?.({ block: "nearest" });
+		if (element) window.getSelection()?.collapse(element);
+		spin.onFocus();
+	};
+	const onSelectionChange = () => {
+		const element = getElement();
+		if (!element) return;
+		const selection = window.getSelection();
+		const anchor = selection?.anchorNode;
+		if (anchor && element.contains(anchor) && element.ownerDocument.activeElement === element) selection.collapse(element);
+	};
+	if (typeof document !== "undefined") {
+		document.addEventListener("selectionchange", onSelectionChange);
+		onScopeDispose(() => document.removeEventListener("selectionchange", onSelectionChange), true);
+	}
+	onScopeDispose(() => {
+		const element = getElement();
+		if (!element || element.ownerDocument.activeElement !== element) return;
+		if (!focusManager.focusPrevious()) focusManager.focusNext();
+	}, true);
+	const onKeydown = (event) => {
+		if (event.key === "Backspace" || event.key === "Delete") {
+			event.preventDefault();
+			event.stopPropagation();
+			backspace();
+			return;
+		}
+		if (event.key === "a" && (event.metaKey || event.ctrlKey)) {
+			event.preventDefault();
+			event.stopPropagation();
+			return;
+		}
+		spin.onKeydown(event);
+	};
+	const onBeforeinput = (event) => {
+		const element = getElement();
+		event.preventDefault();
+		if (!element) return;
+		switch (event.inputType) {
+			case "deleteContentBackward":
+			case "deleteContentForward":
+				if (parser.value.isValidPartialNumber(segment.value.text) && !state.isReadOnly.value) backspace();
+				return;
+			case "insertCompositionText":
+				composed = element.textContent;
+				element.textContent = element.textContent;
+				return;
+			default:
+				if (event.data != null) typeCharacter(event.data);
+				return;
+		}
+	};
+	const onInput = (event) => {
+		const { data, inputType } = event;
+		if (inputType !== "insertCompositionText") return;
+		const element = getElement();
+		if (element) element.textContent = composed;
+		if (data != null && (filter.value.startsWith(am.value, data) || filter.value.startsWith(pm.value, data))) typeCharacter(data);
+	};
+	const id = useId$1();
+	const isEditable = computed(() => !state.isDisabled.value && !state.isReadOnly.value && segment.value.isEditable);
+	/** The name of this part of a date, which precedes the field's own label. */
+	const name = computed(() => type() === "literal" ? "" : displayNames.value.of(type()));
+	const labels = useLabels(() => {
+		const label = toValue(options.ariaLabel);
+		const labelledBy = toValue(options.ariaLabelledBy);
+		return {
+			"aria-label": `${name.value ?? ""}${label ? `, ${label}` : ""}${labelledBy ? ", " : ""}`,
+			"aria-labelledby": labelledBy,
+			id: id.value
+		};
+	});
+	/**
+	* Only the first editable segment carries the field's description, unless the field is invalid.
+	* Otherwise it would be read again on every segment the user moves to.
+	*/
+	const describedBy = computed(() => {
+		const first = state.segments.value.find((candidate) => candidate.isEditable);
+		if (segment.value !== first && !state.isInvalid.value) return void 0;
+		return toValue(options.ariaDescribedBy);
+	});
+	const attrs = computed(() => {
+		const current = segment.value;
+		if (current.type === "literal") return { "aria-hidden": "true" };
+		const editable = isEditable.value;
+		const all = {
+			...spin.attrs.value,
+			...labels.value,
+			"aria-describedby": describedBy.value,
+			"aria-invalid": state.isInvalid.value ? "true" : void 0,
+			"aria-readonly": state.isReadOnly.value || !current.isEditable ? "true" : void 0,
+			autocorrect: editable ? "off" : void 0,
+			contenteditable: editable ? "true" : void 0,
+			"data-placeholder": current.isPlaceholder ? "true" : void 0,
+			enterkeyhint: editable ? "next" : void 0,
+			id: id.value,
+			inputmode: state.isDisabled.value || current.type === "dayPeriod" || current.type === "era" || !editable ? void 0 : "numeric",
+			spellcheck: editable ? "false" : void 0,
+			tabindex: state.isDisabled.value ? void 0 : 0
+		};
+		if (isIOS() || current.type === "timeZoneName") {
+			all["role"] = "textbox";
+			delete all["aria-valuemax"];
+			delete all["aria-valuemin"];
+			delete all["aria-valuenow"];
+			delete all["aria-valuetext"];
+		}
+		for (const key of Object.keys(all)) if (all[key] === void 0) delete all[key];
+		return all;
+	});
+	const style = computed(() => {
+		if (segment.value.type === "literal") return {};
+		const all = { caretColor: "transparent" };
+		if (locale.value.direction !== "rtl") return all;
+		all["unicodeBidi"] = "embed";
+		const format = resolvedOptions.value[segment.value.type];
+		if (format === "numeric" || format === "2-digit") all["direction"] = "ltr";
+		return all;
+	});
+	return {
+		attrs,
+		onBeforeinput,
+		onBlur: spin.onBlur,
+		onFocus,
+		onInput,
+		onKeydown,
+		onMousedown: (event) => event.stopPropagation(),
+		onPointerdown: (event) => event.stopPropagation(),
+		style
+	};
+};
+//#endregion
+export { useDateSegment };

package/dist/composables/use-default-date-props.d.ts

@@ -0,0 +1,22 @@
+import type { Granularity } from "../utils/date-format";
+import type { DateValue } from "@internationalized/date";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface DefaultDateProps {
+    /** How precise the field is: down to the day, the hour, the minute or the second. */
+    granularity: ComputedRef<Granularity>;
+    /** The zone the value carries, or `undefined` for a value that has none. */
+    defaultTimeZone: ComputedRef<string | undefined>;
+}
+/**
+ * How precise a date control is, and which time zone it works in.
+ *
+ * Ported from react-stately's `useDefaultProps`
+ * (`packages/react-stately/src/datepicker/utils.ts`, react-stately 3.49.0). Shared by the field
+ * and by both pickers, because all three have to agree: a picker that thought it was date-only
+ * while its field showed time segments would drop the time on every selection.
+ *
+ * Both answers are **remembered** rather than recomputed from scratch. Clearing a date-and-time
+ * value would otherwise collapse the control back to the date-only default, taking its time
+ * segments away while the user is still editing it.
+ */
+export declare const useDefaultDateProps: (value: MaybeRefOrGetter<DateValue | null | undefined>, granularity: MaybeRefOrGetter<Granularity | undefined>) => DefaultDateProps;

package/dist/composables/use-default-date-props.js

@@ -0,0 +1,37 @@
+import { computed, shallowRef, toValue, watch } from "vue";
+//#region src/composables/use-default-date-props.ts
+/**
+* How precise a date control is, and which time zone it works in.
+*
+* Ported from react-stately's `useDefaultProps`
+* (`packages/react-stately/src/datepicker/utils.ts`, react-stately 3.49.0). Shared by the field
+* and by both pickers, because all three have to agree: a picker that thought it was date-only
+* while its field showed time segments would drop the time on every selection.
+*
+* Both answers are **remembered** rather than recomputed from scratch. Clearing a date-and-time
+* value would otherwise collapse the control back to the date-only default, taking its time
+* segments away while the user is still editing it.
+*/
+var useDefaultDateProps = (value, granularity) => {
+	const shape = computed(() => toValue(value) ?? null);
+	const remembered = shallowRef(["day", void 0]);
+	watch(shape, (current) => {
+		if (!current) return;
+		remembered.value = ["minute" in current ? "minute" : "day", "timeZone" in current ? current.timeZone : void 0];
+	}, {
+		flush: "sync",
+		immediate: true
+	});
+	return {
+		defaultTimeZone: computed(() => shape.value ? "timeZone" in shape.value ? shape.value.timeZone : void 0 : remembered.value[1]),
+		granularity: computed(() => {
+			const current = shape.value;
+			const requested = toValue(granularity);
+			if (current && requested && !(requested in current)) throw new Error(`Invalid granularity ${requested} for value ${current.toString()}`);
+			if (requested) return requested;
+			return current ? "minute" in current ? "minute" : "day" : remembered.value[0];
+		})
+	};
+};
+//#endregion
+export { useDefaultDateProps };

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

@@ -0,0 +1,21 @@
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseDescriptionReturn {
+    /** The id of the description node, or `undefined` when there is no description. */
+    describedBy: ComputedRef<string | undefined>;
+}
+/**
+ * Attach a description to a control for assistive technology only, ported from React Aria's
+ * `useDescription`.
+ *
+ * Some behaviour cannot be discovered without being told: a long-press trigger looks like an
+ * ordinary button, and nothing on screen says the press has to be held. The text goes into a
+ * hidden node appended to the body rather than inside the control, so it is not read as part
+ * of the control's own name and does not affect layout.
+ *
+ * @example
+ * ```ts
+ * const {describedBy} = useDescription(() => (isLongPress ? "Long press to open menu" : undefined));
+ * // <button :aria-describedby="describedBy.value">
+ * ```
+ */
+export declare const useDescription: (description: MaybeRefOrGetter<string | undefined>) => UseDescriptionReturn;

package/dist/composables/use-description.js

@@ -0,0 +1,56 @@
+import { computed, shallowRef, toValue, watch } from "vue";
+//#region src/composables/use-description.ts
+var nextId = 0;
+/** One node per distinct description, shared by every consumer that asks for that text. */
+var nodes = /* @__PURE__ */ new Map();
+/**
+* Attach a description to a control for assistive technology only, ported from React Aria's
+* `useDescription`.
+*
+* Some behaviour cannot be discovered without being told: a long-press trigger looks like an
+* ordinary button, and nothing on screen says the press has to be held. The text goes into a
+* hidden node appended to the body rather than inside the control, so it is not read as part
+* of the control's own name and does not affect layout.
+*
+* @example
+* ```ts
+* const {describedBy} = useDescription(() => (isLongPress ? "Long press to open menu" : undefined));
+* // <button :aria-describedby="describedBy.value">
+* ```
+*/
+var useDescription = (description) => {
+	const id = shallowRef();
+	const release = (text) => {
+		const node = nodes.get(text);
+		if (!node) return;
+		if (--node.refCount === 0) {
+			node.element.remove();
+			nodes.delete(text);
+		}
+	};
+	watch(() => toValue(description), (text, _previous, onCleanup) => {
+		if (!text) {
+			id.value = void 0;
+			return;
+		}
+		let node = nodes.get(text);
+		if (!node) {
+			const element = document.createElement("div");
+			element.id = `ropav-description-${nextId++}`;
+			element.style.display = "none";
+			element.textContent = text;
+			document.body.appendChild(element);
+			node = {
+				element,
+				refCount: 0
+			};
+			nodes.set(text, node);
+		}
+		node.refCount++;
+		id.value = node.element.id;
+		onCleanup(() => release(text));
+	}, { immediate: true });
+	return { describedBy: computed(() => id.value) };
+};
+//#endregion
+export { useDescription };

package/dist/composables/use-dialog-trigger.d.ts

@@ -0,0 +1,36 @@
+import type { PressResponder } from "./press-responder";
+import type { OverlayTriggerState } from "./use-overlay-trigger-state";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseDialogTriggerOptions {
+    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+}
+export interface UseDialogTriggerReturn {
+    /** Hand to `providePressResponder`, so the trigger element picks all of this up. */
+    responder: PressResponder;
+    /** The trigger's id, which the dialog is labelled by when nothing inside names it. */
+    triggerId: ComputedRef<string>;
+    /** The id the dialog carries, which the trigger's `aria-controls` points at. */
+    overlayId: ComputedRef<string>;
+    /** The trigger element, which the overlay is positioned against. */
+    triggerElement: ComputedRef<HTMLElement | null>;
+}
+/**
+ * Turn any pressable into a trigger for a dialog, ported from React Aria's `DialogTrigger`.
+ *
+ * Much smaller than the menu equivalent, because a dialog has none of the menu's timing: it opens
+ * on the press however that press arrived, and there is no direction to carry into it. What it
+ * does have is a labelling fallback — a dialog with no heading is named by the thing that opened
+ * it, which is why the trigger's id is published rather than kept private.
+ *
+ * No `aria-haspopup` is set. ARIA 1.1 allows `"dialog"`, but screen readers announce most values
+ * as "menu", so `useOverlayTrigger` only sets it for a menu and a listbox.
+ *
+ * @example
+ * ```ts
+ * const state = useOverlayTriggerState({isOpen: () => props.isOpen});
+ * const trigger = useDialogTrigger({isDisabled: () => props.isDisabled}, state);
+ *
+ * providePressResponder(trigger.responder);
+ * ```
+ */
+export declare const useDialogTrigger: (options: UseDialogTriggerOptions, state: OverlayTriggerState) => UseDialogTriggerReturn;

package/dist/composables/use-dialog-trigger.js

@@ -0,0 +1,52 @@
+import { useId as useId$1 } from "./use-id.js";
+import { useOverlayTrigger } from "./use-overlay-trigger.js";
+import { usePress } from "./use-press.js";
+import { computed, shallowRef } from "vue";
+//#region src/composables/use-dialog-trigger.ts
+/**
+* Turn any pressable into a trigger for a dialog, ported from React Aria's `DialogTrigger`.
+*
+* Much smaller than the menu equivalent, because a dialog has none of the menu's timing: it opens
+* on the press however that press arrived, and there is no direction to carry into it. What it
+* does have is a labelling fallback — a dialog with no heading is named by the thing that opened
+* it, which is why the trigger's id is published rather than kept private.
+*
+* No `aria-haspopup` is set. ARIA 1.1 allows `"dialog"`, but screen readers announce most values
+* as "menu", so `useOverlayTrigger` only sets it for a menu and a listbox.
+*
+* @example
+* ```ts
+* const state = useOverlayTriggerState({isOpen: () => props.isOpen});
+* const trigger = useDialogTrigger({isDisabled: () => props.isDisabled}, state);
+*
+* providePressResponder(trigger.responder);
+* ```
+*/
+var useDialogTrigger = (options, state) => {
+	const triggerId = useId$1();
+	const element = shallowRef(null);
+	const { overlayId, triggerAttributes } = useOverlayTrigger({ type: "dialog" }, state);
+	const press = usePress({
+		isDisabled: options.isDisabled,
+		isPressed: () => state.isOpen.value,
+		onPress: () => state.toggle()
+	});
+	return {
+		overlayId,
+		responder: {
+			attrs: computed(() => ({
+				...triggerAttributes.value,
+				id: triggerId.value
+			})),
+			handlers: computed(() => press.handlers),
+			isPressed: press.isPressed,
+			registerElement: (next) => {
+				element.value = next;
+			}
+		},
+		triggerElement: computed(() => element.value),
+		triggerId
+	};
+};
+//#endregion
+export { useDialogTrigger };

package/dist/composables/use-disclosure-group-navigation.d.ts

@@ -0,0 +1,46 @@
+import type { DisclosureKey } from "./use-disclosure-group";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseDisclosureGroupNavigationOptions {
+    /** Whether more than one item can be expanded at a time. */
+    allowsMultipleExpanded?: MaybeRefOrGetter<boolean | undefined>;
+    /** Currently expanded keys. */
+    expandedKeys: MaybeRefOrGetter<Iterable<DisclosureKey>>;
+    /** Keys of the items to step through, in the order they are shown. */
+    itemIds: MaybeRefOrGetter<Iterable<DisclosureKey>>;
+    /** Called with the next expanded key set. */
+    onExpandedChange: (keys: Set<DisclosureKey>) => void;
+}
+export interface UseDisclosureGroupNavigationReturn {
+    /** Index of the item the steppers move from, or `-1` when there are no items. */
+    currentIndex: ComputedRef<number>;
+    /** Whether there is nothing before the current item. */
+    isPrevDisabled: ComputedRef<boolean>;
+    /** Whether there is nothing after the current item. */
+    isNextDisabled: ComputedRef<boolean>;
+    /** Expand the item before the current one. */
+    onPrevious: () => void;
+    /** Expand the item after the current one. */
+    onNext: () => void;
+}
+/**
+ * Steps a group of disclosures forwards and backwards from outside it.
+ *
+ * This drives the paging controls a group can be wrapped in — a stepper that walks through
+ * items one at a time — and is deliberately separate from the group's own state: it only ever
+ * hands back a next key set for the caller to apply, so it works the same whether the group is
+ * controlled by the caller or not.
+ *
+ * The item it moves from is the **first expanded one**, falling back to the first item when
+ * nothing is expanded. While more than one item may be expanded the steppers only ever add
+ * keys, so walking forwards opens items cumulatively rather than replacing.
+ *
+ * @example
+ * ```ts
+ * const {isNextDisabled, onNext} = useDisclosureGroupNavigation({
+ *   expandedKeys,
+ *   itemIds: () => items.map((item) => item.id),
+ *   onExpandedChange: (keys) => (expandedKeys.value = keys),
+ * });
+ * ```
+ */
+export declare const useDisclosureGroupNavigation: (options: UseDisclosureGroupNavigationOptions) => UseDisclosureGroupNavigationReturn;

package/dist/composables/use-disclosure-group-navigation.js

@@ -0,0 +1,57 @@
+import { computed, toValue } from "vue";
+//#region src/composables/use-disclosure-group-navigation.ts
+/**
+* Steps a group of disclosures forwards and backwards from outside it.
+*
+* This drives the paging controls a group can be wrapped in — a stepper that walks through
+* items one at a time — and is deliberately separate from the group's own state: it only ever
+* hands back a next key set for the caller to apply, so it works the same whether the group is
+* controlled by the caller or not.
+*
+* The item it moves from is the **first expanded one**, falling back to the first item when
+* nothing is expanded. While more than one item may be expanded the steppers only ever add
+* keys, so walking forwards opens items cumulatively rather than replacing.
+*
+* @example
+* ```ts
+* const {isNextDisabled, onNext} = useDisclosureGroupNavigation({
+*   expandedKeys,
+*   itemIds: () => items.map((item) => item.id),
+*   onExpandedChange: (keys) => (expandedKeys.value = keys),
+* });
+* ```
+*/
+var useDisclosureGroupNavigation = (options) => {
+	const itemIds = computed(() => [...toValue(options.itemIds)]);
+	const expandedKeys = computed(() => new Set(toValue(options.expandedKeys)));
+	const currentIndex = computed(() => {
+		const expanded = itemIds.value.filter((id) => expandedKeys.value.has(id));
+		const current = expanded.length > 0 ? expanded[0] : itemIds.value[0];
+		return current === void 0 ? -1 : itemIds.value.indexOf(current);
+	});
+	const isPrevDisabled = computed(() => currentIndex.value <= 0);
+	const isNextDisabled = computed(() => currentIndex.value >= itemIds.value.length - 1);
+	/** Expands `key`, on its own or alongside what is already open. */
+	const expand = (key) => {
+		options.onExpandedChange(toValue(options.allowsMultipleExpanded) ?? false ? /* @__PURE__ */ new Set([...expandedKeys.value, key]) : /* @__PURE__ */ new Set([key]));
+	};
+	const onPrevious = () => {
+		if (isPrevDisabled.value) return;
+		const previous = itemIds.value[currentIndex.value - 1];
+		if (previous !== void 0) expand(previous);
+	};
+	const onNext = () => {
+		if (isNextDisabled.value) return;
+		const next = itemIds.value[currentIndex.value + 1];
+		if (next !== void 0) expand(next);
+	};
+	return {
+		currentIndex,
+		isNextDisabled,
+		isPrevDisabled,
+		onNext,
+		onPrevious
+	};
+};
+//#endregion
+export { useDisclosureGroupNavigation };