ropav 0.2.0 → 0.3.0

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

@@ -0,0 +1,48 @@
+import type { Granularity, TimeValue } from "../utils/date-format";
+import type { DateFieldState } from "./use-date-field-state";
+import type { ValidationBehavior } from "./use-form-validation-state";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+import { Time } from "@internationalized/date";
+/** A time has no day, so the smallest unit it can show stops at the hour. */
+export type TimeGranularity = Exclude<Granularity, "day">;
+export interface UseTimeFieldStateOptions {
+    value?: MaybeRefOrGetter<TimeValue | null | undefined>;
+    defaultValue?: MaybeRefOrGetter<TimeValue | null | undefined>;
+    onChange?: (value: TimeValue | null) => void;
+    /** A time whose shape the placeholder follows. Defaults to midnight. */
+    placeholderValue?: MaybeRefOrGetter<TimeValue | null | undefined>;
+    minValue?: MaybeRefOrGetter<TimeValue | null | undefined>;
+    maxValue?: MaybeRefOrGetter<TimeValue | null | undefined>;
+    granularity?: MaybeRefOrGetter<TimeGranularity | 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: TimeValue | null) => string | string[] | true | null | undefined;
+    validationBehavior?: MaybeRefOrGetter<ValidationBehavior | undefined>;
+    name?: MaybeRefOrGetter<string | undefined>;
+    /** Overrides the locale in force, for a field that must not follow its surroundings. */
+    locale?: MaybeRefOrGetter<string | undefined>;
+}
+export interface TimeFieldState extends DateFieldState {
+    /**
+     * The current time, with any date dropped.
+     *
+     * Null while the field is empty. React types this as always present, which its own
+     * implementation contradicts, so the honest type is carried over instead.
+     */
+    timeValue: ComputedRef<Time | null>;
+}
+/**
+ * The state behind a time field.
+ *
+ * Ported from react-stately's `packages/react-stately/src/datepicker/useTimeFieldState.ts`
+ * (react-stately 3.49.0).
+ *
+ * A time field is a date field with the date hidden: the time is padded out to a full date on the
+ * way in and stripped back down on the way out, so all of the segment editing lives in one place.
+ */
+export declare const useTimeFieldState: (options: UseTimeFieldStateOptions) => TimeFieldState;

package/dist/composables/use-time-field-state.js

@@ -0,0 +1,88 @@
+import { useControllableState } from "./use-controllable-state.js";
+import { useDateFieldState } from "./use-date-field-state.js";
+import { computed, toValue } from "vue";
+import { GregorianCalendar, Time, getLocalTimeZone, toCalendarDateTime, toTime, toZoned, today } from "@internationalized/date";
+//#region src/composables/use-time-field-state.ts
+/**
+* Midnight, used when no placeholder was given.
+*
+* Held at module scope rather than built per evaluation so its identity is stable — every value in
+* `@internationalized/date` is immutable, so one instance is safe to share.
+*/
+var MIDNIGHT = new Time();
+/**
+* A date whose time part is `value`, so a time can travel through the date field machinery.
+*
+* `date` supplies the day when the time has none of its own; today is a good enough stand-in,
+* because a time-only field never shows it.
+*/
+var toDateTime = (value, date) => {
+	if (!value) return null;
+	if ("day" in value) return value;
+	return toCalendarDateTime(date ?? today(getLocalTimeZone()), value);
+};
+/**
+* The state behind a time field.
+*
+* Ported from react-stately's `packages/react-stately/src/datepicker/useTimeFieldState.ts`
+* (react-stately 3.49.0).
+*
+* A time field is a date field with the date hidden: the time is padded out to a full date on the
+* way in and stripped back down on the way out, so all of the segment editing lives in one place.
+*/
+var useTimeFieldState = (options) => {
+	const placeholderValue = computed(() => toValue(options.placeholderValue) ?? MIDNIGHT);
+	const { setState: setTime, state: value } = useControllableState({
+		defaultValue: toValue(options.defaultValue) ?? null,
+		onValueChange: options.onChange,
+		value: () => toValue(options.value)
+	});
+	/** Whatever the field can read its shape from, which is the placeholder while it is empty. */
+	const shape = computed(() => value.value ?? placeholderValue.value);
+	/** The day the value carries, if it has one — the bounds have to land on that same day. */
+	const day = computed(() => "day" in shape.value ? shape.value : void 0);
+	const defaultValueTimeZone = computed(() => {
+		const initial = toValue(options.defaultValue);
+		return initial && "timeZone" in initial ? initial.timeZone : void 0;
+	});
+	const placeholderDate = computed(() => {
+		const zone = ("timeZone" in shape.value ? shape.value.timeZone : void 0) ?? defaultValueTimeZone.value;
+		const asDate = toDateTime(placeholderValue.value);
+		return zone && asDate ? toZoned(asDate, zone) : asDate;
+	});
+	const timeValue = computed(() => {
+		const current = value.value;
+		if (current == null) return null;
+		return "day" in current ? toTime(current) : current;
+	});
+	return {
+		...useDateFieldState({
+			createCalendar: () => new GregorianCalendar(),
+			defaultValue: () => toDateTime(toValue(options.defaultValue)),
+			granularity: () => toValue(options.granularity) ?? "minute",
+			hideTimeZone: () => toValue(options.hideTimeZone),
+			hourCycle: () => toValue(options.hourCycle),
+			isDisabled: () => toValue(options.isDisabled),
+			isInvalid: () => toValue(options.isInvalid),
+			isReadOnly: () => toValue(options.isReadOnly),
+			isRequired: () => toValue(options.isRequired),
+			locale: () => toValue(options.locale),
+			maxGranularity: "hour",
+			maxValue: () => toDateTime(toValue(options.maxValue), day.value),
+			minValue: () => toDateTime(toValue(options.minValue), day.value),
+			name: () => toValue(options.name),
+			onChange: (next) => {
+				const time = next && "hour" in next ? next : null;
+				setTime(day.value || defaultValueTimeZone.value ? time : time && toTime(time));
+			},
+			placeholderValue: () => placeholderDate.value ?? void 0,
+			shouldForceLeadingZeros: () => toValue(options.shouldForceLeadingZeros),
+			validate: options.validate ? () => options.validate(value.value) : void 0,
+			validationBehavior: () => toValue(options.validationBehavior),
+			value: () => toDateTime(value.value)
+		}),
+		timeValue
+	};
+};
+//#endregion
+export { useTimeFieldState };

package/dist/composables/use-toast-region.d.ts

@@ -0,0 +1,55 @@
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+import { TOP_LAYER_ATTRIBUTE } from "../utils/top-layer";
+/** The only thing the region needs to know about a queued toast. */
+interface ToastIdentity {
+    key: string;
+}
+export interface UseToastRegionOptions {
+    /** Overrides the generated notification-count label. */
+    ariaLabel?: MaybeRefOrGetter<string | undefined>;
+    /** The region element, which is also what the toasts are looked up inside. */
+    elementRef: MaybeRefOrGetter<HTMLElement | null | undefined>;
+    /** Stops every visible toast's clock. */
+    onPauseAll: () => void;
+    /** Restarts every visible toast's clock. */
+    onResumeAll: () => void;
+    visibleToasts: MaybeRefOrGetter<ToastIdentity[]>;
+}
+export interface ToastRegionAttrs {
+    "aria-label": string;
+    [TOP_LAYER_ATTRIBUTE]: true;
+    role: "region";
+    tabindex: -1;
+}
+export interface UseToastRegionReturn {
+    onFocusin: (event: FocusEvent) => void;
+    onFocusout: (event: FocusEvent) => void;
+    onPointerenter: (event: PointerEvent) => void;
+    onPointerleave: () => void;
+    regionAttrs: ComputedRef<ToastRegionAttrs>;
+}
+/**
+ * The behaviour and accessibility wiring of the toast region, ported from react-aria's
+ * `useToastRegion`.
+ *
+ * Three jobs, and they are only in one composable because they share the same state:
+ *
+ * 1. **Naming.** A landmark region labelled with how many notifications it holds.
+ * 2. **Pausing.** Hover *or* focus anywhere inside stops every visible toast's clock, so a toast
+ *    cannot expire while it is being read or operated. Losing both restarts them.
+ * 3. **Focus recovery.** A toast that had focus and is then removed hands focus to a neighbour
+ *    rather than dropping it on `<body>` — except under a pointer, where focus is pushed back out
+ *    of the region, because a pointer user who is no longer hovering would otherwise hold every
+ *    remaining clock paused by the focus they did not ask for.
+ *
+ * One narrowing, recorded rather than hidden: upstream also registers the region with a
+ * document-level landmark manager, which is what makes F6 cycle between landmarks. Nothing else
+ * in react-aria registers one, so with a single registrant F6 has nowhere to go — the rendered
+ * DOM is identical either way, and toasts are still reachable by Tab.
+ *
+ * One simplification: upstream runs focus-within and raw focus as two channels, because its
+ * focus-within fires once on entry and it needs every change. `focusin` and `focusout` bubble and
+ * fire on every change already, so one pair answers both questions.
+ */
+export declare const useToastRegion: (options: UseToastRegionOptions) => UseToastRegionReturn;
+export {};

package/dist/composables/use-toast-region.js

@@ -0,0 +1,160 @@
+import { getInteractionModality, useInteractionStates } from "./use-interaction-states.js";
+import { TOP_LAYER_ATTRIBUTE } from "../utils/top-layer.js";
+import { useLocalizedStringFormatter } from "./use-localized-string-formatter.js";
+import { toastStrings } from "../i18n/toast.js";
+import { computed, onScopeDispose, toValue, watch } from "vue";
+//#region src/composables/use-toast-region.ts
+var TOAST_SELECTOR = "[role=\"alertdialog\"]";
+/** The package's spelling of react-aria's `focusWithoutScrolling`. */
+var focusQuietly = (element) => {
+	element.focus({ preventScroll: true });
+};
+/**
+* The behaviour and accessibility wiring of the toast region, ported from react-aria's
+* `useToastRegion`.
+*
+* Three jobs, and they are only in one composable because they share the same state:
+*
+* 1. **Naming.** A landmark region labelled with how many notifications it holds.
+* 2. **Pausing.** Hover *or* focus anywhere inside stops every visible toast's clock, so a toast
+*    cannot expire while it is being read or operated. Losing both restarts them.
+* 3. **Focus recovery.** A toast that had focus and is then removed hands focus to a neighbour
+*    rather than dropping it on `<body>` — except under a pointer, where focus is pushed back out
+*    of the region, because a pointer user who is no longer hovering would otherwise hold every
+*    remaining clock paused by the focus they did not ask for.
+*
+* One narrowing, recorded rather than hidden: upstream also registers the region with a
+* document-level landmark manager, which is what makes F6 cycle between landmarks. Nothing else
+* in react-aria registers one, so with a single registrant F6 has nowhere to go — the rendered
+* DOM is identical either way, and toasts are still reachable by Tab.
+*
+* One simplification: upstream runs focus-within and raw focus as two channels, because its
+* focus-within fires once on entry and it needs every change. `focusin` and `focusout` bubble and
+* fire on every change already, so one pair answers both questions.
+*/
+var useToastRegion = (options) => {
+	const strings = useLocalizedStringFormatter(toastStrings);
+	const hover = useInteractionStates();
+	let isFocusWithin = false;
+	const updateTimers = () => {
+		if (hover.isHovered.value || isFocusWithin) options.onPauseAll();
+		else options.onResumeAll();
+	};
+	/**
+	* Hover has to settle the clocks *in the handler*, not in a watcher on the state it sets.
+	*
+	* A watcher runs a tick later, and a tick is long enough for a toast to expire under the
+	* pointer that was supposed to be holding it — which is the entire job. The state is still
+	* reported through `useInteractionStates` so touch is filtered out the same way the stylesheet
+	* filters it.
+	*/
+	const onPointerenter = (event) => {
+		hover.onPointerenter(event);
+		updateTimers();
+	};
+	const onPointerleave = () => {
+		hover.onPointerleave();
+		updateTimers();
+	};
+	/** The alertdialog elements, as of the last change to the visible toasts. */
+	let toastElements = [];
+	let previousToasts = toValue(options.visibleToasts);
+	/** Index of the toast holding focus, in visible-toast order; `-1` for none. */
+	let focusedIndex = -1;
+	/** Where focus came from before it entered the region. */
+	let lastFocused = null;
+	const restoreLastFocused = () => {
+		if (!lastFocused?.isConnected) return;
+		if (getInteractionModality() === "pointer") focusQuietly(lastFocused);
+		else lastFocused.focus();
+		lastFocused = null;
+	};
+	/**
+	* Which neighbour inherits focus from a removed toast, ported arithmetic and all.
+	*
+	* The rule it encodes: prefer the nearest surviving toast on the *newer* side, fall back to the
+	* older side. Read against the list as it was before the change, then applied to the list as it
+	* is now — which is why the indices look off by one.
+	*
+	* Only reachable for a toast that is not frontmost, and only the frontmost toast is focusable
+	* (the rest are `tabindex="-1"` and `pointer-events: none`), so in practice this always resolves
+	* to the toast that moved into the front. Ported whole regardless, so no path here can drift.
+	*/
+	const recoverFocus = (removedIndex, previous) => {
+		let i = 0;
+		let prevToast;
+		let nextToast;
+		while (i <= removedIndex) {
+			if (!previous[i].isRemoved) prevToast = Math.max(0, i - 1);
+			i++;
+		}
+		while (i < previous.length) {
+			if (!previous[i].isRemoved) {
+				nextToast = i - 1;
+				break;
+			}
+			i++;
+		}
+		if (prevToast === void 0 && nextToast === void 0) prevToast = 0;
+		const target = prevToast !== void 0 && prevToast < toastElements.length ? toastElements[prevToast] : nextToast !== void 0 && nextToast >= 0 && nextToast < toastElements.length ? toastElements[nextToast] : void 0;
+		if (target) focusQuietly(target);
+	};
+	watch(() => toValue(options.visibleToasts), (visibleToasts) => {
+		const element = toValue(options.elementRef);
+		if (focusedIndex === -1 || visibleToasts.length === 0 || !element) {
+			toastElements = [];
+			previousToasts = visibleToasts;
+			return;
+		}
+		toastElements = [...element.querySelectorAll(TOAST_SELECTOR)];
+		if (previousToasts.length === visibleToasts.length && visibleToasts.every((toast, index) => toast.key === previousToasts[index]?.key)) {
+			previousToasts = visibleToasts;
+			return;
+		}
+		const previous = previousToasts.map((toast) => ({ isRemoved: !visibleToasts.some((next) => next.key === toast.key) }));
+		const removedIndex = previous[focusedIndex]?.isRemoved === true ? focusedIndex : -1;
+		if (removedIndex > -1) {
+			if (getInteractionModality() === "pointer" && lastFocused?.isConnected) focusQuietly(lastFocused);
+			else recoverFocus(removedIndex, previous);
+		}
+		previousToasts = visibleToasts;
+	}, { flush: "post" });
+	watch(() => toValue(options.visibleToasts).length, (count) => {
+		if (count === 0) restoreLastFocused();
+	}, { flush: "post" });
+	onScopeDispose(restoreLastFocused, true);
+	const onFocusin = (event) => {
+		if (!isFocusWithin) {
+			isFocusWithin = true;
+			lastFocused = event.relatedTarget instanceof HTMLElement ? event.relatedTarget : null;
+			updateTimers();
+		}
+		const { target } = event;
+		const toast = target instanceof Element ? target.closest(TOAST_SELECTOR) : null;
+		const element = toValue(options.elementRef);
+		focusedIndex = toast && element ? [...element.querySelectorAll(TOAST_SELECTOR)].indexOf(toast) : -1;
+	};
+	const onFocusout = (event) => {
+		const { currentTarget, relatedTarget, target } = event;
+		if (target instanceof Node && !target.isConnected) return;
+		if (currentTarget instanceof Node && relatedTarget instanceof Node && currentTarget.contains(relatedTarget)) return;
+		isFocusWithin = false;
+		lastFocused = null;
+		focusedIndex = -1;
+		updateTimers();
+	};
+	return {
+		onFocusin,
+		onFocusout,
+		onPointerenter,
+		onPointerleave,
+		regionAttrs: computed(() => ({
+			[TOP_LAYER_ATTRIBUTE]: true,
+			"aria-label": toValue(options.ariaLabel) || strings.value.format("notifications", { count: toValue(options.visibleToasts).length }),
+			role: "region",
+			tabindex: -1
+		}))
+	};
+};
+//#endregion
+export { useToastRegion };

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

@@ -0,0 +1,52 @@
+import type { Timer } from "../components/toast/toast-queue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export interface UseToastOptions {
+    /** Called when the toast should close, whether from its own clock or the close button. */
+    onClose: () => void;
+    /** The toast's clock, if it has one. */
+    timer: MaybeRefOrGetter<Timer | undefined>;
+    /** Milliseconds the clock should run for. */
+    timeout: MaybeRefOrGetter<number | undefined>;
+}
+export interface ToastAttrs {
+    "aria-describedby": string | undefined;
+    "aria-labelledby": string;
+    "aria-modal": "false";
+    role: "alertdialog";
+}
+export interface ToastContentAttrs {
+    "aria-atomic": "true";
+    "aria-hidden": "true" | undefined;
+    role: "alert";
+}
+export interface UseToastReturn {
+    /** Closes this toast. */
+    close: () => void;
+    contentAttrs: ComputedRef<ToastContentAttrs>;
+    descriptionAttrs: ComputedRef<{
+        id: string;
+    }>;
+    /** Called by a rendered description so the toast knows to point at it. Returns the release. */
+    registerDescription: () => () => void;
+    titleAttrs: ComputedRef<{
+        id: string;
+    }>;
+    toastAttrs: ComputedRef<ToastAttrs>;
+}
+/**
+ * The behaviour and accessibility wiring of one toast, ported from react-aria's `useToast`.
+ *
+ * `role="alertdialog"` with `aria-modal="false"` rather than `alert`: a toast holds controls, so
+ * it has to be a dialog for a screen reader to let the user into it, and a non-modal one because
+ * the rest of the page stays live. The content inside carries the `role="alert"` that does the
+ * announcing.
+ *
+ * The clock starts **here**, on mount, and not when the toast was queued: a toast added while the
+ * region is not rendered has not already spent its life waiting to appear. Unmounting pauses it
+ * rather than dropping it, so a toast that comes back has the time it had left.
+ *
+ * One narrowing against upstream: it also returns a localized `aria-label` for the close button,
+ * which nothing can use — `CloseButton` writes its own `aria-label="Close"`, and that hardcoded
+ * label wins over the one offered through context.
+ */
+export declare const useToast: (options: UseToastOptions) => UseToastReturn;

package/dist/composables/use-toast.js

@@ -0,0 +1,83 @@
+import { useId as useId$1 } from "./use-id.js";
+import { computed, onMounted, onScopeDispose, shallowRef, toValue, watch } from "vue";
+//#region src/composables/use-toast.ts
+/**
+* The behaviour and accessibility wiring of one toast, ported from react-aria's `useToast`.
+*
+* `role="alertdialog"` with `aria-modal="false"` rather than `alert`: a toast holds controls, so
+* it has to be a dialog for a screen reader to let the user into it, and a non-modal one because
+* the rest of the page stays live. The content inside carries the `role="alert"` that does the
+* announcing.
+*
+* The clock starts **here**, on mount, and not when the toast was queued: a toast added while the
+* region is not rendered has not already spent its life waiting to appear. Unmounting pauses it
+* rather than dropping it, so a toast that comes back has the time it had left.
+*
+* One narrowing against upstream: it also returns a localized `aria-label` for the close button,
+* which nothing can use — `CloseButton` writes its own `aria-label="Close"`, and that hardcoded
+* label wins over the one offered through context.
+*/
+var useToast = (options) => {
+	const titleId = useId$1();
+	const descriptionId = useId$1();
+	let descriptionClaims = 0;
+	const hasDescription = shallowRef(false);
+	/**
+	* Upstream resolves this with `useSlotId`, which hands out the id and then withdraws it in a
+	* layout effect when no element turns out to carry it. The claim is the same answer asked
+	* directly rather than probed off the document, and it is how the rest of this package settles
+	* whether an id has an owner.
+	*/
+	const registerDescription = () => {
+		descriptionClaims += 1;
+		hasDescription.value = true;
+		return () => {
+			descriptionClaims -= 1;
+			hasDescription.value = descriptionClaims > 0;
+		};
+	};
+	/**
+	* Withheld for the first tick, then dropped.
+	*
+	* NVDA does not announce the toast at all without this — the alert has to become visible to the
+	* accessibility tree *after* it exists for the announcement to fire. Upstream carries the same
+	* flag and the same reason.
+	*/
+	const isVisible = shallowRef(false);
+	onMounted(() => {
+		isVisible.value = true;
+	});
+	const pause = () => {
+		toValue(options.timer)?.pause();
+	};
+	onMounted(() => {
+		watch(() => ({
+			timeout: toValue(options.timeout),
+			timer: toValue(options.timer)
+		}), (next, previous) => {
+			previous?.timer?.pause();
+			if (next.timer == null || next.timeout == null) return;
+			next.timer.reset(next.timeout);
+		}, { immediate: true });
+	});
+	onScopeDispose(pause, true);
+	return {
+		close: () => options.onClose(),
+		contentAttrs: computed(() => ({
+			"aria-atomic": "true",
+			"aria-hidden": isVisible.value ? void 0 : "true",
+			role: "alert"
+		})),
+		descriptionAttrs: computed(() => ({ id: descriptionId.value })),
+		registerDescription,
+		titleAttrs: computed(() => ({ id: titleId.value })),
+		toastAttrs: computed(() => ({
+			"aria-describedby": hasDescription.value ? descriptionId.value : void 0,
+			"aria-labelledby": titleId.value,
+			"aria-modal": "false",
+			role: "alertdialog"
+		}))
+	};
+};
+//#endregion
+export { useToast };

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

@@ -0,0 +1,51 @@
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export type ToggleGroupKey = string | number;
+export type ToggleGroupSelectionMode = "single" | "multiple";
+export interface UseToggleGroupStateOptions {
+    /** Selected keys in uncontrolled mode. */
+    defaultSelectedKeys?: Iterable<ToggleGroupKey>;
+    /** Whether the group must always keep at least one key selected. */
+    disallowEmptySelection?: MaybeRefOrGetter<boolean | undefined>;
+    /** Whether the whole group is disabled. */
+    isDisabled?: MaybeRefOrGetter<boolean | undefined>;
+    /** Called with the next selected key set whenever it changes. */
+    onSelectionChange?: (keys: Set<ToggleGroupKey>) => void;
+    /** Selected keys in controlled mode. */
+    selectedKeys?: MaybeRefOrGetter<Iterable<ToggleGroupKey> | undefined>;
+    /** Whether one or many keys can be selected at a time. @default "single" */
+    selectionMode?: MaybeRefOrGetter<ToggleGroupSelectionMode | undefined>;
+}
+export interface UseToggleGroupStateReturn {
+    /** Currently selected keys. */
+    selectedKeys: ComputedRef<Set<ToggleGroupKey>>;
+    /** Whether one or many keys can be selected at a time. */
+    selectionMode: ComputedRef<ToggleGroupSelectionMode>;
+    /** Whether the whole group is disabled. */
+    isDisabled: ComputedRef<boolean>;
+    /** Whether a given key is selected. */
+    isSelected: (key: ToggleGroupKey) => boolean;
+    /** Flip a key's selection, honouring the selection mode. */
+    toggleKey: (key: ToggleGroupKey) => void;
+    /** Drive a key to an explicit state. A no-op when it already holds it. */
+    setSelected: (key: ToggleGroupKey, isSelected: boolean) => void;
+}
+/**
+ * Selected-key state for a group of toggle buttons, the Vue counterpart of React
+ * Stately's `useToggleGroupState`.
+ *
+ * `selectionMode` decides what a toggle does rather than which keys are legal: in
+ * `"multiple"` a key is added to or removed from the set, while in `"single"` it replaces
+ * whatever was selected. `disallowEmptySelection` keeps the last remaining key from being
+ * turned off, which is what makes a single-selection group behave like a radio group
+ * rather than a row of independent toggles.
+ *
+ * @example
+ * ```ts
+ * const state = useToggleGroupState({
+ *   selectedKeys: () => props.selectedKeys,
+ *   selectionMode: () => props.selectionMode,
+ *   onSelectionChange: (keys) => emit("selectionChange", keys),
+ * });
+ * ```
+ */
+export declare const useToggleGroupState: (options?: UseToggleGroupStateOptions) => UseToggleGroupStateReturn;

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

@@ -0,0 +1,61 @@
+import { useControllableState } from "./use-controllable-state.js";
+import { computed, toValue } from "vue";
+//#region src/composables/use-toggle-group-state.ts
+/**
+* Selected-key state for a group of toggle buttons, the Vue counterpart of React
+* Stately's `useToggleGroupState`.
+*
+* `selectionMode` decides what a toggle does rather than which keys are legal: in
+* `"multiple"` a key is added to or removed from the set, while in `"single"` it replaces
+* whatever was selected. `disallowEmptySelection` keeps the last remaining key from being
+* turned off, which is what makes a single-selection group behave like a radio group
+* rather than a row of independent toggles.
+*
+* @example
+* ```ts
+* const state = useToggleGroupState({
+*   selectedKeys: () => props.selectedKeys,
+*   selectionMode: () => props.selectionMode,
+*   onSelectionChange: (keys) => emit("selectionChange", keys),
+* });
+* ```
+*/
+var useToggleGroupState = (options = {}) => {
+	const selectionMode = computed(() => toValue(options.selectionMode) ?? "single");
+	const disallowEmptySelection = computed(() => toValue(options.disallowEmptySelection) ?? false);
+	const isDisabled = computed(() => toValue(options.isDisabled) ?? false);
+	const { setState, state } = useControllableState({
+		defaultValue: new Set(options.defaultSelectedKeys ?? []),
+		onValueChange: options.onSelectionChange,
+		value: () => {
+			const keys = toValue(options.selectedKeys);
+			return keys === void 0 ? void 0 : new Set(keys);
+		}
+	});
+	const isSelected = (key) => state.value.has(key);
+	const toggleKey = (key) => {
+		if (isDisabled.value) return;
+		setState((previous) => {
+			if (selectionMode.value === "multiple") {
+				const next = new Set(previous);
+				if (next.has(key) && (!disallowEmptySelection.value || next.size > 1)) next.delete(key);
+				else next.add(key);
+				return next;
+			}
+			return new Set(previous.has(key) && !disallowEmptySelection.value ? [] : [key]);
+		});
+	};
+	const setSelected = (key, selected) => {
+		if (selected !== isSelected(key)) toggleKey(key);
+	};
+	return {
+		isDisabled,
+		isSelected,
+		selectedKeys: computed(() => state.value),
+		selectionMode,
+		setSelected,
+		toggleKey
+	};
+};
+//#endregion
+export { useToggleGroupState };

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

@@ -0,0 +1,42 @@
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+export type ToolbarOrientation = "horizontal" | "vertical";
+export interface UseToolbarOptions {
+    /** The toolbar element, read imperatively to move focus between its children. */
+    element: MaybeRefOrGetter<HTMLElement | null | undefined>;
+    /** Axis the controls are laid out along, which decides the arrow keys. */
+    orientation?: MaybeRefOrGetter<ToolbarOrientation | undefined>;
+}
+export interface UseToolbarReturn {
+    /** `"toolbar"`, or `"group"` when already inside one — toolbars do not nest. */
+    role: ComputedRef<"toolbar" | "group">;
+    /** Whether this is the outermost toolbar, and so the one owning the keyboard. */
+    isOutermost: ComputedRef<boolean>;
+    /** `keydown` handler. Attach on the capture phase so a nested group cannot claim it. */
+    onKeydown: (event: KeyboardEvent) => void;
+    /** `focusin` handler. Restores the last focused control when focus returns. */
+    onFocusin: (event: FocusEvent) => void;
+    /** `focusout` handler. Remembers where focus was when it leaves. */
+    onFocusout: (event: FocusEvent) => void;
+}
+/**
+ * Keyboard behaviour for the WAI-ARIA Toolbar pattern, the Vue counterpart of React
+ * Aria's `useToolbar`.
+ *
+ * A toolbar is one tab stop's worth of *meaning* but not of markup: every control stays
+ * tabbable, and the arrow keys move between them. Two details carry most of the value.
+ * Tab moves focus to the far end of the toolbar first and then lets the browser continue,
+ * so a keyboard user leaves the whole toolbar in one press instead of walking through
+ * every button. And the control focus last sat on is restored when focus comes back from
+ * outside, so returning to a toolbar does not reset the user to its first button.
+ *
+ * Only the outermost toolbar owns the keyboard. A nested one reports `role="group"` and
+ * hands its keys upward, which is what keeps arrow keys from being consumed twice.
+ *
+ * @example
+ * ```ts
+ * const element = shallowRef<HTMLElement | null>(null);
+ * const toolbar = useToolbar({element, orientation: () => props.orientation});
+ * // <div :ref="element" :role="toolbar.role.value" @keydown.capture="toolbar.onKeydown">
+ * ```
+ */
+export declare const useToolbar: (options: UseToolbarOptions) => UseToolbarReturn;