ropav 0.11.1 → 0.12.1

package/dist/components/toast/toast-queue.js

@@ -1,4 +1,4 @@
-import "./toast.constants.js";
+import { DEFAULT_TOAST_TIMEOUT } from "./toast.constants.js";
 import { computed, nextTick, onScopeDispose, shallowRef, toValue, watch } from "vue";
 //#region src/components/toast/toast-queue.ts
 /**
@@ -16,7 +16,9 @@ var Timer = class {
 		this.callback = callback;
 		this.remaining = delay;
 	}
+	/** Starts the clock again on `delay`, whether or not it was already running. */
 	reset(delay) {
+		this.pause();
 		this.remaining = delay;
 		this.resume();
 	}
@@ -27,7 +29,7 @@ var Timer = class {
 		this.remaining -= Date.now() - this.startTime;
 	}
 	resume() {
-		if (this.remaining <= 0) return;
+		if (this.timerId != null || this.remaining <= 0) return;
 		this.startTime = Date.now();
 		this.timerId = setTimeout(() => {
 			this.timerId = null;
@@ -40,7 +42,7 @@ var Timer = class {
 * The order toasts are shown in, and the clocks that close them.
 *
 * Ported from `react-stately`'s `ToastQueue`, merged with the wrapper that normally sits around
-* it. Upstream those are two classes because the wrapper had a primitive to wrap; writing both
+* it. There those are two classes because the wrapper had a primitive to wrap; writing both
 * here means keeping them apart would be two paths doing one job. What the merge keeps from the
 * wrapper: the default timeout, the serialized view transition, and `maxVisibleToasts` as a hint
 * the region reads rather than a truncation.
@@ -58,12 +60,8 @@ var ToastQueue = class {
 	visibleToasts = [];
 	constructor(options = {}) {
 		this.maxVisibleToasts = options.maxVisibleToasts;
-		const transitions = createViewTransitionUpdate();
-		this.resetTransitions = transitions.reset;
-		this.wrapUpdate = options.wrapUpdate ?? transitions.wrapUpdate;
+		this.wrapUpdate = options.wrapUpdate ?? ((fn) => fn());
 	}
-	/** Forgets any transitions still queued. For a test, since a chain outlives a mount. */
-	resetTransitions;
 	/** Adds a toast and returns its key. */
 	add(content, options = {}) {
 		const key = `_${Math.random().toString(36).slice(2)}`;
@@ -75,9 +73,40 @@ var ToastQueue = class {
 			timeout,
 			timer: timeout ? new Timer(() => this.close(key), timeout) : void 0
 		});
-		this.update("add");
+		this.notify("add");
 		return key;
 	}
+	/**
+	* Replaces a toast's content where it stands, keeping its key and its place in the stack.
+	* Returns `false` for a key the queue no longer holds.
+	*
+	* Options the caller leaves out are kept rather than resolved: a toast asked to stay until
+	* something closes it must not pick up the default life because its message changed. That is
+	* why this reads the keys that are *present* instead of their values — an explicit `undefined`
+	* is a caller clearing a handler, and an absent key is a caller not mentioning one.
+	*
+	* The entry is replaced rather than mutated so the toast re-renders. The list is shallow, so a
+	* toast whose fields changed underneath it is the same object as far as anything watching is
+	* concerned; a new one keyed the same patches the node it already has.
+	*/
+	update(key, content, options = {}) {
+		const index = this.queue.findIndex((toast) => toast.key === key);
+		if (index < 0) return false;
+		const previous = this.queue[index];
+		const next = {
+			...previous,
+			content
+		};
+		if ("onClose" in options) next.onClose = options.onClose;
+		if ("timeout" in options) {
+			previous.timer?.pause();
+			next.timeout = options.timeout;
+			next.timer = options.timeout ? new Timer(() => this.close(key), options.timeout) : void 0;
+		}
+		this.queue[index] = next;
+		this.notify("add");
+		return true;
+	}
 	/** Closes one toast. Notifies even for a key that is no longer held. */
 	close(key) {
 		const index = this.queue.findIndex((toast) => toast.key === key);
@@ -85,12 +114,12 @@ var ToastQueue = class {
 			this.queue[index].onClose?.();
 			this.queue.splice(index, 1);
 		}
-		this.update("remove");
+		this.notify("remove");
 	}
 	/** Drops every toast at once. Deliberately does not run their `onClose` — nothing closed them. */
 	clear() {
 		this.queue = [];
-		this.update("clear");
+		this.notify("clear");
 	}
 	/** Stops the clocks of the toasts on screen. */
 	pauseAll() {
@@ -107,7 +136,7 @@ var ToastQueue = class {
 			this.subscriptions.delete(fn);
 		};
 	}
-	update(action) {
+	notify(action) {
 		this.visibleToasts = [...this.queue];
 		this.wrapUpdate(() => {
 			for (const fn of [...this.subscriptions]) fn();
@@ -115,7 +144,21 @@ var ToastQueue = class {
 	}
 };
 /**
-* A queue's own chain of view transitions, so its updates animate one after another.
+* A queue's own chain of view transitions, so its updates animate one after another. Hand the
+* `wrapUpdate` it returns to a queue to animate that queue's toasts this way.
+*
+* Not what a queue does by default, and the reason is measured rather than assumed: a chain is
+* serial, so under a burst each toast waits for every transition queued ahead of it — the fifth
+* toast of five added 80ms apart took 1.5s to appear, against 0.37s when the stack animates
+* itself. A transition also replaces the toast with a snapshot that answers no hit test, so the
+* close and action buttons of the frontmost toast are unreachable for as long as it runs. Neither
+* shows up as dropped frames; both are plainly visible to someone using the thing.
+*
+* It stays because it is the only way to get a genuine cross-fade between two different toasts,
+* and because a caller who wants it should not have to rebuild the chain below. Each toast names
+* itself for the transition through `view-transition-name`, which is what makes the capture
+* per-toast; without it the document root would be the only captured element and every toast
+* would cross-fade the whole page.
 *
 * The View Transitions API allows one active transition per document: starting a second while the
 * first is still animating aborts the first, which surfaces as a rejection on `ready`. Each new
@@ -128,7 +171,7 @@ var ToastQueue = class {
 * regions on a page, a burst of toasts in one of them puts every other region's toast behind the
 * whole burst, so a toast added elsewhere does not appear until seconds later. Independent chains
 * let a second region interrupt instead — the superseded transition is skipped, which the catch
-* below already handles, which is why the chain is scoped per queue inside the constructor.
+* below already handles, which is why a chain belongs to one queue and is built per caller.
 */
 var createViewTransitionUpdate = () => {
 	let chain = Promise.resolve();
@@ -185,17 +228,19 @@ var useToastQueue = (queue) => {
 */
 var resolve = (value, input) => typeof value === "function" ? value(input) : value;
 var createToastFunction = (queue) => {
-	const add = (message, options = {}) => queue.add({
+	const contentOf = (message, options) => ({
 		actionProps: options.actionProps,
 		description: options.description,
 		indicator: options.indicator,
 		isLoading: options.isLoading,
 		title: message,
 		variant: options.variant ?? "default"
-	}, {
-		onClose: options.onClose ? () => {
-			requestAnimationFrame(() => options.onClose?.());
-		} : void 0,
+	});
+	const deferred = (onClose) => onClose ? () => {
+		requestAnimationFrame(() => onClose());
+	} : void 0;
+	const add = (message, options = {}) => queue.add(contentOf(message, options), {
+		onClose: deferred(options.onClose),
 		timeout: options.timeout
 	});
 	const withVariant = (variant) => (message, options = {}) => add(message, {
@@ -212,6 +257,14 @@ var createToastFunction = (queue) => {
 	toastFn.resumeAll = () => queue.resumeAll();
 	toastFn.success = withVariant("success");
 	toastFn.warning = withVariant("warning");
+	toastFn.update = (key, message, options = {}) => {
+		const inherited = {
+			..."onClose" in options ? { onClose: deferred(options.onClose) } : null,
+			..."timeout" in options ? { timeout: options.timeout } : null
+		};
+		if (queue.update(key, contentOf(message, options), inherited)) return key;
+		return add(message, options);
+	};
 	toastFn.promise = (promise, options) => {
 		const pending = typeof promise === "function" ? promise() : promise;
 		const loadingKey = queue.add({
@@ -220,11 +273,17 @@ var createToastFunction = (queue) => {
 			variant: "default"
 		}, { timeout: 0 });
 		pending.then((data) => {
-			queue.close(loadingKey);
-			toastFn.success(resolve(options.success, data));
-		}, (error) => {
-			queue.close(loadingKey);
-			toastFn.danger(resolve(options.error, error));
+			toastFn.update(loadingKey, resolve(options.success, data), {
+				isLoading: false,
+				timeout: DEFAULT_TOAST_TIMEOUT,
+				variant: "success"
+			});
+		}).catch((error) => {
+			toastFn.update(loadingKey, resolve(options.error, error), {
+				isLoading: false,
+				timeout: DEFAULT_TOAST_TIMEOUT,
+				variant: "danger"
+			});
 		});
 		return loadingKey;
 	};
@@ -240,10 +299,9 @@ var toastQueue = new ToastQueue();
 var toast = createToastFunction(toastQueue);
 /** How many toasts the default queue holds. For a test asserting it did not leak into the next. */
 var getQueuedToastCount = () => toastQueue.visibleToasts.length;
-/** Empties the default queue and the transition chain. For a test, since both outlive a mount. */
+/** Empties the default queue. For a test, since the queue outlives a mount. */
 var resetToastQueue = () => {
 	toastQueue.clear();
-	toastQueue.resetTransitions();
 };
 //#endregion
-export { Timer, ToastQueue, createToastFunction, getQueuedToastCount, resetToastQueue, toast, toastQueue, useToastQueue };
+export { Timer, ToastQueue, createToastFunction, createViewTransitionUpdate, getQueuedToastCount, resetToastQueue, toast, toastQueue, useToastQueue };

package/dist/components/toast/toast-root.js

@@ -1,9 +1,10 @@
 import { dataAttr } from "../../utils/assertion.js";
 import { provideSurfaceContext } from "../surface/surface.context.js";
+import { createAnimationSettleWaiter } from "../../utils/animation-settled.js";
 import { provideToastItemContext, useToastRegionContext } from "./toast.context.js";
 import { useMeasuredHeight } from "../../composables/use-measured-height.js";
 import { useToast } from "../../composables/use-toast.js";
-import { computed, createSlot, defineVaporComponent, onScopeDispose, renderEffect, setDynamicProps, setInsertionState, setTemplateRefBinding, shallowRef, template, unref, watch } from "vue";
+import { computed, createSlot, defineVaporComponent, onMounted, onScopeDispose, renderEffect, setDynamicProps, setInsertionState, setTemplateRefBinding, shallowRef, template, unref, watch } from "vue";
 //#region src/components/toast/toast-root.vue?vue&type=script&setup=true&vapor=true&lang.ts
 var t0 = template("<div>", 1);
 var toast_root_vue_vue_type_script_setup_true_vapor_true_lang_default = /*@__PURE__*/ defineVaporComponent({
@@ -24,10 +25,53 @@ var toast_root_vue_vue_type_script_setup_true_vapor_true_lang_default = /*@__PUR
 		};
 		const placement = computed(() => props.placement ?? region.placement.value);
 		const scaleFactor = computed(() => props.scaleFactor ?? region.scaleFactor.value);
-		/** Index 0 is the newest toast, which is the one in front of the stack. */
-		const index = computed(() => region.visibleToasts.value.findIndex((entry) => entry.key === props.toast.key));
+		const isExiting = computed(() => region.exitingKeys.value.has(props.toast.key));
+		/**
+		* The place this toast holds in the stack. Index 0 is the newest, which is the one in front.
+		*
+		* A toast on its way out keeps the slot it had while the ones behind it renumber and close up,
+		* so the stack reflows around it instead of waiting for it to finish.
+		*/
+		const lastIndex = shallowRef(0);
+		const index = computed(() => {
+			if (isExiting.value) return lastIndex.value;
+			return Math.max(region.visibleToasts.value.findIndex((entry) => entry.key === props.toast.key), 0);
+		});
+		watch(index, (next) => {
+			if (!isExiting.value) lastIndex.value = next;
+		}, { immediate: true });
 		const isFrontmost = computed(() => index.value <= 0);
-		const isHidden = computed(() => index.value >= region.maxVisibleToasts.value);
+		const isHidden = computed(() => !isExiting.value && index.value >= region.maxVisibleToasts.value);
+		/**
+		* Rendered from the very first frame rather than set once mounted.
+		*
+		* A transition needs a style to leave, so the offset has to be the element's *first* resolved
+		* style. Written after the element already exists, the browser transitions towards the offset and
+		* the flip below then drags it back — which reads as a toast that twitches instead of arriving.
+		*/
+		const isEntering = shallowRef(true);
+		onMounted(() => {
+			let inner = 0;
+			const outer = requestAnimationFrame(() => {
+				inner = requestAnimationFrame(() => {
+					isEntering.value = false;
+				});
+			});
+			onScopeDispose(() => {
+				cancelAnimationFrame(outer);
+				cancelAnimationFrame(inner);
+			}, true);
+		});
+		/**
+		* The exit is waited for rather than timed, so its length lives in the stylesheet — the one place
+		* that knows it — and no number here can fall out of step with it.
+		*/
+		const exit = createAnimationSettleWaiter(() => element.value);
+		watch(isExiting, (exiting) => {
+			if (!exiting) return;
+			exit.whenSettled(() => region.onExitFinished(props.toast.key));
+		});
+		onScopeDispose(exit.cancel, true);
 		const { height } = useMeasuredHeight(element);
 		/**
 		* Every toast reports its height up, because a toast that is *not* frontmost is clipped to the
@@ -64,32 +108,41 @@ var toast_root_vue_vue_type_script_setup_true_vapor_true_lang_default = /*@__PUR
 		}));
 		const style = computed(() => {
 			const visible = region.visibleToasts.value;
+			const heights = region.heightsByKey.value;
 			const frontKey = visible[0]?.key;
-			const frontHeight = (frontKey === void 0 ? void 0 : region.heightsByKey.value[frontKey]) ?? height.value ?? 0;
-			const offset = index.value * region.gap.value;
-			const direction = placement.value?.startsWith("bottom") ? -1 : 1;
+			const frontHeight = (frontKey === void 0 ? void 0 : heights[frontKey]) ?? height.value ?? 0;
+			let heightsBefore = 0;
+			for (let position = 0; position < index.value; position += 1) {
+				const key = visible[position]?.key;
+				heightsBefore += (key === void 0 ? void 0 : heights[key]) ?? frontHeight;
+			}
+			const gap = index.value * region.gap.value;
 			return {
-				opacity: isHidden.value ? 0 : 1,
-				pointerEvents: isHidden.value ? "none" : "auto",
-				scale: `${1 - index.value * scaleFactor.value}`,
-				translate: `0 ${direction * offset}px 0`,
+				...frontHeight ? { "--front-height": `${frontHeight}px` } : null,
+				"--offset-collapsed": `${gap}px`,
+				"--offset-expanded": `${heightsBefore + gap}px`,
+				"--scale-collapsed": `${1 - index.value * scaleFactor.value}`,
 				viewTransitionName: `rp-toast-${props.toast.key.replace(/[^a-zA-Z0-9]/g, "-")}`,
-				zIndex: visible.length - index.value,
-				...frontHeight ? { "--front-height": `${frontHeight}px` } : null
+				zIndex: isExiting.value ? 0 : visible.length - index.value,
+				...height.value === void 0 ? null : { "--toast-height": `${height.value}px` }
 			};
 		});
 		const n1 = t0();
 		renderEffect(() => {
 			const _dataAttr = unref(dataAttr);
+			const _isExiting = isExiting.value;
 			const _isFrontmost = isFrontmost.value;
 			setDynamicProps(n1, [{
 				class: styles.value,
+				"data-entering": _dataAttr(isEntering.value),
+				"data-exiting": _dataAttr(_isExiting),
+				"data-expanded": _dataAttr(unref(region).isExpanded.value),
 				"data-frontmost": _dataAttr(_isFrontmost),
 				"data-hidden": _dataAttr(isHidden.value),
 				"data-index": index.value,
 				"data-slot": "toast",
 				style: style.value,
-				tabindex: _isFrontmost ? 0 : -1
+				tabindex: _isFrontmost && !_isExiting ? 0 : -1
 			}, unref(api).toastAttrs.value]);
 		});
 		setInsertionState(n1);

package/dist/components/toast/toast.constants.d.ts

@@ -12,5 +12,21 @@ export declare const DEFAULT_MAX_VISIBLE_TOAST = 3;
 export declare const DEFAULT_SCALE_FACTOR = 0.05;
 /** Pixels wide, written out as `--toast-width` for the stylesheet to read. */
 export declare const DEFAULT_TOAST_WIDTH = 460;
-/** Milliseconds a toast lives for. Matches sonner's default. */
+/** Milliseconds a toast lives for. */
 export declare const DEFAULT_TOAST_TIMEOUT = 4000;
+/**
+ * Milliseconds after which a closed toast is dropped whether or not it reported its exit.
+ *
+ * Not the length of the exit, which the toast waits out against its own animations. This is the
+ * ceiling for a toast that can never report one — a slot the caller filled with something other
+ * than a `ToastRoot` — so a list of them cannot grow without end.
+ */
+export declare const EXIT_FALLBACK = 2000;
+/**
+ * The key combination that moves focus to the toast region.
+ *
+ * An entry naming one of the `KeyboardEvent` modifier booleans matches that modifier; anything
+ * else matches `event.code`, so what counts is the key in that position rather than the character
+ * the layout produces there. An empty list turns the shortcut off.
+ */
+export declare const DEFAULT_HOTKEY: readonly string[];

package/dist/components/toast/toast.constants.js

@@ -13,7 +13,23 @@ var DEFAULT_MAX_VISIBLE_TOAST = 3;
 var DEFAULT_SCALE_FACTOR = .05;
 /** Pixels wide, written out as `--toast-width` for the stylesheet to read. */
 var DEFAULT_TOAST_WIDTH = 460;
-/** Milliseconds a toast lives for. Matches sonner's default. */
+/** Milliseconds a toast lives for. */
 var DEFAULT_TOAST_TIMEOUT = 4e3;
+/**
+* Milliseconds after which a closed toast is dropped whether or not it reported its exit.
+*
+* Not the length of the exit, which the toast waits out against its own animations. This is the
+* ceiling for a toast that can never report one — a slot the caller filled with something other
+* than a `ToastRoot` — so a list of them cannot grow without end.
+*/
+var EXIT_FALLBACK = 2e3;
+/**
+* The key combination that moves focus to the toast region.
+*
+* An entry naming one of the `KeyboardEvent` modifier booleans matches that modifier; anything
+* else matches `event.code`, so what counts is the key in that position rather than the character
+* the layout produces there. An empty list turns the shortcut off.
+*/
+var DEFAULT_HOTKEY = ["altKey", "KeyT"];
 //#endregion
-export { DEFAULT_GAP, DEFAULT_MAX_VISIBLE_TOAST, DEFAULT_SCALE_FACTOR, DEFAULT_TOAST_TIMEOUT, DEFAULT_TOAST_WIDTH };
+export { DEFAULT_GAP, DEFAULT_HOTKEY, DEFAULT_MAX_VISIBLE_TOAST, DEFAULT_SCALE_FACTOR, DEFAULT_TOAST_TIMEOUT, DEFAULT_TOAST_WIDTH, EXIT_FALLBACK };

package/dist/components/toast/toast.context.d.ts

@@ -12,10 +12,16 @@ import type { ComputedRef } from "vue";
 export interface ToastRegionContext {
     /** Closes one toast by key. */
     close: (key: string) => void;
+    /** Keys still mounted for their exit animation, which have left the queue already. */
+    exitingKeys: ComputedRef<ReadonlySet<string>>;
     gap: ComputedRef<number>;
     /** Every mounted toast's measured height, so a stacked toast can be clipped to the front one. */
     heightsByKey: ComputedRef<Record<string, number>>;
+    /** Whether the stack is opened out, so every toast shows at its own height. */
+    isExpanded: ComputedRef<boolean>;
     maxVisibleToasts: ComputedRef<number>;
+    /** Reported by a toast once its exit animation has finished, so it can be unmounted. */
+    onExitFinished: (key: string) => void;
     onToastHeightChange: (key: string, height: number) => void;
     onToastHeightRemove: (key: string) => void;
     placement: ComputedRef<ToastVariants["placement"]>;

package/dist/components/toast/toast.types.d.ts

@@ -82,6 +82,19 @@ export interface ToastProviderProps {
     class?: string;
     /** Pixels between stacked toasts. @default 12 */
     gap?: number;
+    /**
+     * Key combination that moves focus to the region, as `KeyboardEvent` modifier names plus an
+     * `event.code`. Modifiers left out have to be up, so `Alt`+`T` does not answer `Ctrl`+`Alt`+`T`.
+     * Pass an empty list to turn it off.
+     *
+     * @default ["altKey", "KeyT"]
+     */
+    hotkey?: readonly string[];
+    /**
+     * Holds the stack open regardless of pointer or focus. Deliberately does not pause the clocks:
+     * expansion asked for by the page is not someone reading the toasts.
+     */
+    isExpanded?: boolean;
     /**
      * How many toasts are drawn at once. Visual only — the rest are faded out, not dropped.
      *
@@ -118,6 +131,12 @@ export interface ToastContentProps {
 }
 export interface ToastIndicatorProps {
     class?: string;
+    /**
+     * Whether this indicator is replacing one the toast was already showing, which the stylesheet
+     * animates. The first indicator a toast renders is not a replacement and must not be marked as
+     * one, or every toast would arrive with its icon animating.
+     */
+    isSwapped?: boolean;
     /** Picks the default icon. Falls back to the toast's own variant. */
     variant?: ToastVariants["variant"];
 }

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

@@ -39,7 +39,9 @@ var useCheckboxGroupState = (options = {}) => {
 	const isItemRequired = computed(() => isRequired.value && value.value.length === 0);
 	const validation = useFormValidationState({
 		isInvalid: () => toValue(options.isInvalid),
+		isRequired,
 		name: () => toValue(options.name),
+		requiredControl: "checkbox",
 		validate: () => toValue(options.validate),
 		validationBehavior: () => toValue(options.validationBehavior),
 		value: () => value.value

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

@@ -68,6 +68,7 @@ var useColorFieldState = (options = {}) => {
 	const inputValue = shallowRef(hasInitialValue && colorValue.value ? colorValue.value.toString("hex") : "");
 	const validation = useFormValidationState({
 		isInvalid: () => toValue(options.isInvalid),
+		isRequired: () => toValue(options.isRequired),
 		name: () => toValue(options.name),
 		validate: () => toValue(options.validate),
 		validationBehavior: () => toValue(options.validationBehavior),

package/dist/composables/use-combo-box-state.d.ts

@@ -78,6 +78,8 @@ export interface UseComboBoxStateOptions<T> {
     disabledBehavior?: MaybeRefOrGetter<DisabledBehavior | undefined>;
     isReadOnly?: MaybeRefOrGetter<boolean | undefined>;
     isInvalid?: MaybeRefOrGetter<boolean | undefined>;
+    /** Whether the field has to hold a value. Enforced by the validation state under `"aria"`. */
+    isRequired?: MaybeRefOrGetter<boolean | undefined>;
     validate?: MaybeRefOrGetter<ValidationFunction<ComboBoxValidationValue> | undefined>;
     validationBehavior?: MaybeRefOrGetter<ValidationBehavior | undefined>;
     name?: MaybeRefOrGetter<string | undefined>;

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

@@ -2,7 +2,7 @@ import { useControllableState } from "./use-controllable-state.js";
 import { useMenuTriggerState } from "./use-overlay-trigger-state.js";
 import { useCollection } from "./use-collection.js";
 import { createListCollection } from "../utils/virtualizer-collection.js";
-import { useFormValidationState } from "./use-form-validation-state.js";
+import { isValueMissing, useFormValidationState } from "./use-form-validation-state.js";
 import { useSelectionManager } from "./use-selection-manager.js";
 import { defaultItemTextValue } from "./use-select-state.js";
 import { useFilter } from "./use-filter.js";
@@ -137,7 +137,9 @@ var useComboBoxState = (options) => {
 	});
 	const inputValue = computed(() => input.state.value);
 	const validation = useFormValidationState({
+		isEmpty: (current) => !current || isValueMissing(current.value),
 		isInvalid: options.isInvalid,
+		isRequired: options.isRequired,
 		name: options.name,
 		validate: options.validate,
 		validationBehavior: options.validationBehavior,

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

@@ -170,6 +170,7 @@ var useDateFieldState = (options) => {
 	const validation = useFormValidationState({
 		builtinValidation,
 		isInvalid: () => toValue(options.isInvalid),
+		isRequired,
 		name: () => toValue(options.name),
 		validate: () => options.validate,
 		validationBehavior: () => toValue(options.validationBehavior),

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

@@ -24,6 +24,8 @@ export interface UseDatePickerStateOptions {
     hideTimeZone?: MaybeRefOrGetter<boolean | undefined>;
     shouldForceLeadingZeros?: MaybeRefOrGetter<boolean | undefined>;
     isInvalid?: MaybeRefOrGetter<boolean | undefined>;
+    /** Whether the field has to hold a value. Enforced by the validation state under `"aria"`. */
+    isRequired?: MaybeRefOrGetter<boolean | undefined>;
     validate?: (value: DateValue | null) => string | string[] | true | null | undefined;
     validationBehavior?: MaybeRefOrGetter<ValidationBehavior | undefined>;
     name?: MaybeRefOrGetter<string | undefined>;

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

@@ -54,6 +54,7 @@ var useDatePickerState = (options) => {
 	const validation = useFormValidationState({
 		builtinValidation: computed(() => getDateValidationResult(value.value, toValue(options.minValue), toValue(options.maxValue), options.isDateUnavailable, formatOpts.value)),
 		isInvalid: () => toValue(options.isInvalid),
+		isRequired: () => toValue(options.isRequired),
 		name: () => toValue(options.name),
 		validate: () => options.validate,
 		validationBehavior: () => toValue(options.validationBehavior),

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

@@ -35,6 +35,8 @@ export interface UseDateRangePickerStateOptions {
     hideTimeZone?: MaybeRefOrGetter<boolean | undefined>;
     shouldForceLeadingZeros?: MaybeRefOrGetter<boolean | undefined>;
     isInvalid?: MaybeRefOrGetter<boolean | undefined>;
+    /** Whether the field has to hold a value. Enforced by the validation state under `"aria"`. */
+    isRequired?: 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. */

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

@@ -78,7 +78,9 @@ var useDateRangePickerState = (options) => {
 	}));
 	const validation = useFormValidationState({
 		builtinValidation: computed(() => getRangeValidationResult(value.value, toValue(options.minValue), toValue(options.maxValue), options.isDateUnavailable, formatOpts.value)),
+		isEmpty: (range) => !range?.start || !range.end,
 		isInvalid: () => toValue(options.isInvalid),
+		isRequired: () => toValue(options.isRequired),
 		name: () => [toValue(options.startName), toValue(options.endName)].filter(Boolean),
 		validate: () => options.validate,
 		validationBehavior: () => toValue(options.validationBehavior),

package/dist/composables/use-description.js

@@ -33,6 +33,7 @@ var useDescription = (description) => {
 			id.value = void 0;
 			return;
 		}
+		if (typeof document === "undefined") return;
 		let node = nodes.get(text);
 		if (!node) {
 			const element = document.createElement("div");

package/dist/composables/use-form-validation-state.d.ts

@@ -1,4 +1,4 @@
-import type { ComputedRef, MaybeRefOrGetter } from "vue";
+import type { ComputedRef, MaybeRefOrGetter, Ref } from "vue";
 /**
  * Snapshot of an element's `ValidityState`.
  *
@@ -39,6 +39,8 @@ export type ValidationFunction<T> = (value: T) => string | string[] | true | nul
 export declare const VALID_VALIDITY_STATE: ValidationDetails;
 /** Failure that came from a prop, a `validate` function or the server rather than the browser. */
 export declare const CUSTOM_VALIDITY_STATE: ValidationDetails;
+/** A required field with nothing in it. What the browser reports under `"native"`. */
+export declare const MISSING_VALIDITY_STATE: ValidationDetails;
 export declare const DEFAULT_VALIDATION_RESULT: ValidationResult;
 /**
  * One verdict out of several, for a control whose value has more than one part.
@@ -51,6 +53,23 @@ export declare const mergeValidation: (...results: ValidationResult[]) => Valida
 export type ValidatableElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
 /** Freeze an element's live validity into a result the state layer can hold. */
 export declare const getNativeValidation: (element: ValidatableElement) => ValidationResult;
+/**
+ * The kinds of control a required field can be. Each is a different sentence: a list asks to be
+ * chosen from, a checkbox to be ticked.
+ */
+export type RequiredControl = "checkbox" | "radio" | "select" | "text";
+/**
+ * What the browser would say about an empty control of this kind.
+ *
+ * Read off a detached probe rather than translated here. The platform already holds the sentence,
+ * in the *browser's* locale — which is the locale a validation message belongs in, since it sits
+ * beside the browser's own — and it is the one the same field would report under `"native"`.
+ *
+ * Empty on a server, where the field cannot have been revealed yet and so has nothing to say.
+ */
+export declare const missingValueMessage: (kind: RequiredControl) => string;
+/** Whether a value counts as nothing. Covers every shape a field holds when it is empty. */
+export declare const isValueMissing: (value: unknown) => boolean;
 /** Errors a server returned, keyed by the `name` each field submits under. */
 export type FormValidationErrors = Record<string, string | string[]>;
 export interface FormContext {
@@ -58,6 +77,14 @@ export interface FormContext {
     validationErrors: ComputedRef<FormValidationErrors>;
     /** Default for every field inside, unless the field names its own. */
     validationBehavior: ComputedRef<ValidationBehavior>;
+    /**
+     * Bumped by every submit attempt.
+     *
+     * Under `"native"` a field learns of a failed submit from the browser, which fires `invalid` at
+     * it. Under `"aria"` the browser is not involved, so this is the only thing that tells a field
+     * holding an unrevealed error that it is now being asked for.
+     */
+    submitCount?: Readonly<Ref<number>>;
 }
 /**
  * React splits this in two — `FormValidationContext` in react-stately for the errors,
@@ -83,6 +110,18 @@ export interface UseFormValidationStateOptions<T> {
     name?: MaybeRefOrGetter<string | string[] | undefined>;
     /** Validity a composite field worked out from its own parts. */
     builtinValidation?: MaybeRefOrGetter<ValidationResult | undefined>;
+    /**
+     * Whether the field has to hold a value.
+     *
+     * Enforced here only under `"aria"`. Under `"native"` the control carries the `required`
+     * attribute and the browser reaches the same verdict itself, so a second one here would only
+     * be a chance to disagree.
+     */
+    isRequired?: MaybeRefOrGetter<boolean | undefined>;
+    /** Which sentence a missing value is reported with. @default "text" */
+    requiredControl?: RequiredControl;
+    /** Whether the value counts as nothing. @default {@link isValueMissing} */
+    isEmpty?: (value: T | null | undefined) => boolean;
     /**
      * A validation state owned by something above, which this field reports through instead of
      * keeping one of its own.
@@ -118,15 +157,19 @@ export declare const isEqualValidation: (a: ValidationResult | null, b: Validati
  * Decide what a field's validation currently says, ported from React Aria's
  * `packages/react-stately/src/form/useFormValidationState.ts` (react-stately 3.49.0).
  *
- * Knows nothing about the DOM — `useFormValidation` is what connects this to a real input.
- * Four sources feed it, in a fixed order of precedence:
+ * Holds no element of its own — `useFormValidation` is what connects this to a real input.
+ * Five sources feed it, in a fixed order of precedence:
  *
  * ```
- * realtime        = controlled ?? server ?? client ?? builtin ?? valid
+ * realtime        = controlled ?? server ?? client ?? required ?? builtin ?? valid
  * display(native) = controlled ?? server ?? committed
- * display(aria)   = controlled ?? server ?? client ?? builtin ?? committed
+ * display(aria)   = controlled ?? server ?? client ?? required* ?? builtin ?? committed
  * ```
  *
+ * `required` is the missing-value rule, and it is there for `"aria"` alone: under `"native"` the
+ * control carries the attribute and the browser reaches the verdict itself. The `*` is the reveal
+ * — it waits for a commit or a submit, so a form does not arrive with every required field red.
+ *
  * `realtimeValidation` is what the field pushes onto the input through `setCustomValidity`,
  * so the browser blocks submission the moment the value stops being acceptable.
  * `displayValidation` is what the user reads, and under `"native"` it moves only on commit —