@funstack/ui 0.1.0-alpha.0 → 0.1.0-alpha.1

package/dist/internal/use-native-group-reconciliation.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-native-group-reconciliation.mjs","names":[],"sources":["../../src/internal/use-native-group-reconciliation.ts"],"sourcesContent":["\"use client\";\nimport { useCallback, useEffectEvent, useLayoutEffect, useRef } from \"react\";\nimport type { RefObject } from \"react\";\nimport { useFormReset } from \"./use-form-reset.js\";\n\nexport interface UseNativeGroupReconciliationOptions<T> {\n  /** The group's form-associated container (`RadioGroup.Root`'s `<fieldset>`). */\n  readonly element: RefObject<HTMLFieldSetElement | null>;\n  /** The group's value as the DOM shows it now (`checked` of the members). */\n  readonly readCurrent: () => T;\n  /** The value the browser resets the group to (`defaultChecked` of the members, rule 5). */\n  readonly readDefault: () => T;\n  /**\n   * What the user intends (rule 1): the latest in-flight dispatch's `next`, else the optimistic\n   * value. Use an explicit null check, `const f = latestInFlight(); return f === null ?\n   * optimistic : f.next;`, not `?.next ?? optimistic`, which drops an in-flight dispatch of a\n   * nullish value (a pending reset to \"nothing checked\").\n   */\n  readonly base: () => T;\n  /**\n   * The browser changed the group's value on a residual path and it differs from `base()`.\n   * `event` is the `reset` event, or `undefined` for mount reconciliation (the Root's mount, or a\n   * member mounting later). The Root dispatches once for the whole group with\n   * `reason: \"platform\"`.\n   */\n  readonly onPlatformChange: (next: T, event: Event | undefined) => void;\n}\n\nexport interface UseNativeGroupReconciliationResult {\n  /**\n   * Stable. Pass it to every member, which hands it to\n   * `useNativeChecked({ group: true, onItemMounted })`; the hook calls it from the member's mount\n   * layout effect. A member that mounts after the Root's own mount reconciliation (inside a\n   * Suspense boundary that hydrates later, selective hydration, or a member added on the client)\n   * makes the adapter reconcile the group again: `readCurrent()` vs `base()`, in a microtask, once\n   * for all members mounted in the same commit. Members mounting in the Root's own commit are\n   * covered by the Root's mount reconciliation (their effects run before the Root's) and are\n   * ignored.\n   *\n   * RadioGroup wiring: `const { onItemMounted } = useNativeGroupReconciliation(...)` in the Root,\n   * put `onItemMounted` in the group context, and in each Item\n   * `useNativeChecked({ type: \"radio\", group: true, onItemMounted: ctx.onItemMounted, ... })`.\n   * The member's element argument is not used here; the Root may use it (dev warnings).\n   */\n  readonly onItemMounted: (element?: Element | null) => void;\n}\n\n/**\n * Group adapter of the native-input machinery (conventions 3.8): one dispatch per group for the\n * residual browser paths, from the Root rather than once per member.\n *\n * - Mount reconciliation, once, in a layout effect: `readCurrent()` vs `base()`. The members'\n *   `useNativeChecked({ group: true })` leaves `checked` alone in their mount commit, so this\n *   effect, which runs after the members' (children first), still reads the hydrated DOM.\n * - Late members: a member mounting in a later commit (a Suspense boundary that hydrates after the\n *   Root, where a click before hydration changed the DOM) reports through `onItemMounted`, and the\n *   group is reconciled again the same way (see `UseNativeGroupReconciliationResult`).\n * - Form reset through `useFormReset` on the container: in a microtask after the reset,\n *   `readDefault()` vs `base()`.\n *\n * Values are compared with `Object.is`.\n */\nexport function useNativeGroupReconciliation<T>(\n  options: UseNativeGroupReconciliationOptions<T>,\n): UseNativeGroupReconciliationResult {\n  const { element } = options;\n\n  // The latest committed options, for the late reconciliation, which runs in a microtask outside\n  // any effect (so it cannot go through an Effect Event).\n  const latest = useRef(options);\n  useLayoutEffect(() => {\n    latest.current = options;\n  });\n\n  /** The Root's own mount reconciliation has run (reset by its cleanup, StrictMode included). */\n  const rootReconciled = useRef(false);\n  /** A late reconciliation is queued; members mounting in the same commit share it. */\n  const lateQueued = useRef(false);\n\n  const reconcileMount = useEffectEvent(() => {\n    if (element.current === null) return;\n    reconcile(options, options.readCurrent());\n  });\n  useLayoutEffect(() => {\n    reconcileMount();\n    rootReconciled.current = true;\n    return () => {\n      rootReconciled.current = false;\n    };\n  }, []);\n\n  const onItemMounted = useCallback(() => {\n    if (!rootReconciled.current || lateQueued.current) return;\n    lateQueued.current = true;\n    queueMicrotask(() => {\n      lateQueued.current = false;\n      if (!rootReconciled.current) return;\n      const current = latest.current;\n      if (current.element.current === null) return;\n      reconcile(current, current.readCurrent());\n    });\n  }, []);\n\n  useFormReset(element, (event) => {\n    if (element.current === null) return;\n    reconcile(options, options.readDefault(), event);\n  });\n\n  return { onItemMounted };\n}\n\nfunction reconcile<T>(options: UseNativeGroupReconciliationOptions<T>, next: T, event?: Event) {\n  if (!Object.is(next, options.base())) options.onPlatformChange(next, event);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA8DA,SAAgB,6BACd,SACoC;CACpC,MAAM,EAAE,YAAY;CAIpB,MAAM,SAAS,OAAO,OAAO;CAC7B,sBAAsB;EACpB,OAAO,UAAU;CACnB,CAAC;;CAGD,MAAM,iBAAiB,OAAO,KAAK;;CAEnC,MAAM,aAAa,OAAO,KAAK;CAE/B,MAAM,iBAAiB,qBAAqB;EAC1C,IAAI,QAAQ,YAAY,MAAM;EAC9B,UAAU,SAAS,QAAQ,YAAY,CAAC;CAC1C,CAAC;CACD,sBAAsB;EACpB,eAAe;EACf,eAAe,UAAU;EACzB,aAAa;GACX,eAAe,UAAU;EAC3B;CACF,GAAG,CAAC,CAAC;CAEL,MAAM,gBAAgB,kBAAkB;EACtC,IAAI,CAAC,eAAe,WAAW,WAAW,SAAS;EACnD,WAAW,UAAU;EACrB,qBAAqB;GACnB,WAAW,UAAU;GACrB,IAAI,CAAC,eAAe,SAAS;GAC7B,MAAM,UAAU,OAAO;GACvB,IAAI,QAAQ,QAAQ,YAAY,MAAM;GACtC,UAAU,SAAS,QAAQ,YAAY,CAAC;EAC1C,CAAC;CACH,GAAG,CAAC,CAAC;CAEL,aAAa,UAAU,UAAU;EAC/B,IAAI,QAAQ,YAAY,MAAM;EAC9B,UAAU,SAAS,QAAQ,YAAY,GAAG,KAAK;CACjD,CAAC;CAED,OAAO,EAAE,cAAc;AACzB;AAEA,SAAS,UAAa,SAAiD,MAAS,OAAe;CAC7F,IAAI,CAAC,OAAO,GAAG,MAAM,QAAQ,KAAK,CAAC,GAAG,QAAQ,iBAAiB,MAAM,KAAK;AAC5E"}
+{"version":3,"file":"use-native-group-reconciliation.mjs","names":[],"sources":["../../src/internal/use-native-group-reconciliation.ts"],"sourcesContent":["\"use client\";\nimport { useCallback, useEffectEvent, useLayoutEffect, useRef } from \"react\";\nimport type { RefObject } from \"react\";\nimport { useFormReset } from \"./use-form-reset.js\";\n\nexport interface UseNativeGroupReconciliationOptions<T> {\n  /** The group's form-associated container (`RadioGroup.Root`'s `<fieldset>`). */\n  readonly element: RefObject<HTMLFieldSetElement | null>;\n  /** The group's value as the DOM shows it now (`checked` of the members). */\n  readonly readCurrent: () => T;\n  /** The value the browser resets the group to (`defaultChecked` of the members, rule 5). */\n  readonly readDefault: () => T;\n  /**\n   * What the user intends (rule 1): the latest in-flight dispatch's `next`, else the optimistic\n   * value. Use an explicit null check, `const f = latestInFlight(); return f === null ?\n   * optimistic : f.next;`, not `?.next ?? optimistic`, which drops an in-flight dispatch of a\n   * nullish value (a pending reset to \"nothing checked\").\n   */\n  readonly base: () => T;\n  /**\n   * The browser changed the group's value on a residual path and it differs from `base()`.\n   * `event` is the `reset` event, or `undefined` for mount reconciliation (the Root's mount, or a\n   * member mounting later). The Root dispatches once for the whole group with\n   * `reason: \"platform\"`.\n   */\n  readonly onPlatformChange: (next: T, event: Event | undefined) => void;\n  /**\n   * Equality between a read value and `base()`. Default `Object.is`, right for a primitive value\n   * (RadioGroup's `string | null`); a group with a collection value (CheckboxGroup's\n   * `ReadonlySet<string>`) passes structural equality, since every read builds a new object.\n   */\n  readonly equals?: ((a: T, b: T) => boolean) | undefined;\n}\n\nexport interface UseNativeGroupReconciliationResult {\n  /**\n   * Stable. Pass it to every member, which hands it to\n   * `useNativeChecked({ group: true, onItemMounted })`; the hook calls it from the member's mount\n   * layout effect. A member that mounts after the Root's own mount reconciliation (inside a\n   * Suspense boundary that hydrates later, selective hydration, or a member added on the client)\n   * makes the adapter reconcile the group again: `readCurrent()` vs `base()`, in a microtask, once\n   * for all members mounted in the same commit. Members mounting in the Root's own commit are\n   * covered by the Root's mount reconciliation (their effects run before the Root's) and are\n   * ignored.\n   *\n   * RadioGroup wiring: `const { onItemMounted } = useNativeGroupReconciliation(...)` in the Root,\n   * put `onItemMounted` in the group context, and in each Item\n   * `useNativeChecked({ type: \"radio\", group: true, onItemMounted: ctx.onItemMounted, ... })`.\n   * The member's element argument is not used here; the Root may use it (dev warnings).\n   */\n  readonly onItemMounted: (element?: Element | null) => void;\n}\n\n/**\n * Group adapter of the native-input machinery (conventions 3.8): one dispatch per group for the\n * residual browser paths, from the Root rather than once per member.\n *\n * - Mount reconciliation, once, in a layout effect: `readCurrent()` vs `base()`. The members'\n *   `useNativeChecked({ group: true })` leaves `checked` alone in their mount commit, so this\n *   effect, which runs after the members' (children first), still reads the hydrated DOM.\n * - Late members: a member mounting in a later commit (a Suspense boundary that hydrates after the\n *   Root, where a click before hydration changed the DOM) reports through `onItemMounted`, and the\n *   group is reconciled again the same way (see `UseNativeGroupReconciliationResult`).\n * - Form reset through `useFormReset` on the container: in a microtask after the reset,\n *   `readDefault()` vs `base()`.\n *\n * Values are compared with `equals` (default `Object.is`).\n */\nexport function useNativeGroupReconciliation<T>(\n  options: UseNativeGroupReconciliationOptions<T>,\n): UseNativeGroupReconciliationResult {\n  const { element } = options;\n\n  // The latest committed options, for the late reconciliation, which runs in a microtask outside\n  // any effect (so it cannot go through an Effect Event).\n  const latest = useRef(options);\n  useLayoutEffect(() => {\n    latest.current = options;\n  });\n\n  /** The Root's own mount reconciliation has run (reset by its cleanup, StrictMode included). */\n  const rootReconciled = useRef(false);\n  /** A late reconciliation is queued; members mounting in the same commit share it. */\n  const lateQueued = useRef(false);\n\n  const reconcileMount = useEffectEvent(() => {\n    if (element.current === null) return;\n    reconcile(options, options.readCurrent());\n  });\n  useLayoutEffect(() => {\n    reconcileMount();\n    rootReconciled.current = true;\n    return () => {\n      rootReconciled.current = false;\n    };\n  }, []);\n\n  const onItemMounted = useCallback(() => {\n    if (!rootReconciled.current || lateQueued.current) return;\n    lateQueued.current = true;\n    queueMicrotask(() => {\n      lateQueued.current = false;\n      if (!rootReconciled.current) return;\n      const current = latest.current;\n      if (current.element.current === null) return;\n      reconcile(current, current.readCurrent());\n    });\n  }, []);\n\n  useFormReset(element, (event) => {\n    if (element.current === null) return;\n    reconcile(options, options.readDefault(), event);\n  });\n\n  return { onItemMounted };\n}\n\nfunction reconcile<T>(options: UseNativeGroupReconciliationOptions<T>, next: T, event?: Event) {\n  const equals = options.equals ?? Object.is;\n  if (!equals(next, options.base())) options.onPlatformChange(next, event);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAoEA,SAAgB,6BACd,SACoC;CACpC,MAAM,EAAE,YAAY;CAIpB,MAAM,SAAS,OAAO,OAAO;CAC7B,sBAAsB;EACpB,OAAO,UAAU;CACnB,CAAC;;CAGD,MAAM,iBAAiB,OAAO,KAAK;;CAEnC,MAAM,aAAa,OAAO,KAAK;CAE/B,MAAM,iBAAiB,qBAAqB;EAC1C,IAAI,QAAQ,YAAY,MAAM;EAC9B,UAAU,SAAS,QAAQ,YAAY,CAAC;CAC1C,CAAC;CACD,sBAAsB;EACpB,eAAe;EACf,eAAe,UAAU;EACzB,aAAa;GACX,eAAe,UAAU;EAC3B;CACF,GAAG,CAAC,CAAC;CAEL,MAAM,gBAAgB,kBAAkB;EACtC,IAAI,CAAC,eAAe,WAAW,WAAW,SAAS;EACnD,WAAW,UAAU;EACrB,qBAAqB;GACnB,WAAW,UAAU;GACrB,IAAI,CAAC,eAAe,SAAS;GAC7B,MAAM,UAAU,OAAO;GACvB,IAAI,QAAQ,QAAQ,YAAY,MAAM;GACtC,UAAU,SAAS,QAAQ,YAAY,CAAC;EAC1C,CAAC;CACH,GAAG,CAAC,CAAC;CAEL,aAAa,UAAU,UAAU;EAC/B,IAAI,QAAQ,YAAY,MAAM;EAC9B,UAAU,SAAS,QAAQ,YAAY,GAAG,KAAK;CACjD,CAAC;CAED,OAAO,EAAE,cAAc;AACzB;AAEA,SAAS,UAAa,SAAiD,MAAS,OAAe;CAE7F,IAAI,EADW,QAAQ,UAAU,OAAO,GAAA,CAC5B,MAAM,QAAQ,KAAK,CAAC,GAAG,QAAQ,iBAAiB,MAAM,KAAK;AACzE"}

package/dist/internal/use-popover-popup.mjs

@@ -0,0 +1,274 @@
+"use client";
+import { exitAnimations, useExitAnimation } from "./use-exit-animation.mjs";
+import { createElement, useCallback, useEffect, useEffectEvent, useInsertionEffect, useLayoutEffect, useRef, useState } from "react";
+//#region src/internal/use-popover-popup.ts
+const isDev = process.env.NODE_ENV !== "production";
+function isPopoverOpen(element) {
+	try {
+		return element.matches(":popover-open");
+	} catch {
+		return false;
+	}
+}
+let focusVisibleOption;
+/**
+* The engine reads the `focusVisible` member of `focus()`'s options (Chromium 145, Firefox 104,
+* Safari 18.4). Detected once through a getter: the bindings convert the dictionary before the
+* method runs, so a detached element is enough and nothing is focused.
+*/
+function supportsFocusVisibleOption(doc) {
+	if (focusVisibleOption === void 0) {
+		let read = false;
+		try {
+			doc.createElement("div").focus({ get focusVisible() {
+				read = true;
+				return false;
+			} });
+		} catch {
+			read = false;
+		}
+		focusVisibleOption = read;
+	}
+	return focusVisibleOption;
+}
+/** Resolves `initialFocus` against the popup (a ref, or a selector inside the popup). */
+function resolveInitialFocus(popup, initialFocus) {
+	if (typeof initialFocus === "string") return popup.querySelector(initialFocus);
+	return initialFocus.current;
+}
+/** Whether `element` sits inside a popover that is not shown (an outer popup that closed). */
+function insideHiddenPopover(element) {
+	for (let node = element.parentElement; node !== null; node = node.parentElement) if (node.hasAttribute("popover") && !isPopoverOpen(node)) return true;
+	return false;
+}
+/**
+* Records, from its layout-effect cleanup, whether focus is inside the popup when the content
+* goes away: React runs a deleted component's layout cleanups before it detaches the host nodes,
+* so `document.activeElement` still names the focused element there.
+*/
+function ContentFocusProbe({ onDetach, children }) {
+	useLayoutEffect(() => onDetach, [onDetach]);
+	return children;
+}
+/**
+* Everything in a popover-like Popup except rendering (design/components/popover.md 14.2): mount
+* reconciliation, the apply effect, the native `beforetoggle` / `toggle` / `command` listeners,
+* close intents, the focus-return fallback, the JS-free `aria-expanded` sync, the deferred
+* unmount while a hide animates, and `initialFocus`. Shared by Popover and Menu.
+*/
+function usePopoverPopup(ctx, options) {
+	const { part, initialFocus, transition, onBeforeToggle: onBeforeToggleOption } = options;
+	const onToggleOption = options.onToggle;
+	const isLibrary = ctx.mode === "library";
+	const { popupRef, triggerRef } = ctx;
+	const opening = useRef(false);
+	const awaitingClose = useRef(false);
+	const focusWasInside = useRef(false);
+	const contentHadFocus = useRef(false);
+	const warnedFocus = useRef(false);
+	const exit = useExitAnimation();
+	const [prevCommitted, setPrevCommitted] = useState(ctx.committed);
+	if (prevCommitted !== ctx.committed) {
+		setPrevCommitted(ctx.committed);
+		if (isLibrary && prevCommitted && transition === void 0) exit.holdDuringRender();
+	}
+	const recordContentFocus = useCallback(() => {
+		const element = popupRef.current;
+		if (element === null) return;
+		const active = element.ownerDocument.activeElement;
+		if (active !== null && active !== element && element.contains(active)) contentHadFocus.current = true;
+	}, [popupRef]);
+	const wrapContent = useCallback((children) => createElement(ContentFocusProbe, { onDetach: recordContentFocus }, children), [recordContentFocus]);
+	const syncExpanded = (element) => {
+		triggerRef.current?.setAttribute("aria-expanded", String(isPopoverOpen(element)));
+	};
+	/**
+	* Design 6.2 rule 2, for a close that began with focus inside: when focus is now on `<body>`
+	* or still inside the hidden popup, focus the Trigger (connected, not inside a hidden
+	* popover), else blur what holds focus.
+	*/
+	const returnFocus = (element) => {
+		const doc = element.ownerDocument;
+		const active = doc.activeElement;
+		if (active !== null && active !== doc.body && !element.contains(active)) return;
+		const trigger = triggerRef.current;
+		if (trigger !== null && trigger.isConnected && !insideHiddenPopover(trigger)) trigger.focus();
+		else if (active instanceof HTMLElement && active !== doc.body) active.blur();
+	};
+	const resolveFocusTarget = (element) => {
+		if (options.resolveInitialFocus !== void 0) {
+			const resolved = options.resolveInitialFocus(element);
+			if (resolved === null) return null;
+			const target = resolved instanceof HTMLElement ? resolved : resolved.element;
+			return element.contains(target) ? resolved : null;
+		}
+		if (initialFocus === void 0) return null;
+		const target = resolveInitialFocus(element, initialFocus);
+		if (target !== null && element.contains(target)) return target;
+		if (isDev && !warnedFocus.current) {
+			warnedFocus.current = true;
+			console.error(target === null ? `${part}: \`initialFocus\` resolved to no element; the platform picks the focus target.` : `${part}: \`initialFocus\` is outside the popup; the platform picks the focus target.`);
+		}
+		return null;
+	};
+	const showPopup = (element) => {
+		const resolved = resolveFocusTarget(element);
+		const target = resolved === null || resolved instanceof HTMLElement ? resolved : resolved.element;
+		const quiet = target !== null && !(resolved instanceof HTMLElement) && supportsFocusVisibleOption(element.ownerDocument);
+		const added = target !== null && !quiet && !target.hasAttribute("autofocus");
+		if (added) target.setAttribute("autofocus", "");
+		opening.current = true;
+		try {
+			const source = triggerRef.current;
+			element.showPopover(source !== null && source.isConnected ? { source } : void 0);
+		} finally {
+			opening.current = false;
+			if (added) target.removeAttribute("autofocus");
+		}
+		if (quiet && isPopoverOpen(element) && element.contains(target)) target.focus({ focusVisible: false });
+	};
+	const reconcileOnMount = useEffectEvent(() => {
+		const element = popupRef.current;
+		if (element === null) return;
+		if (!isLibrary) {
+			syncExpanded(element);
+			return;
+		}
+		if (isPopoverOpen(element)) ctx.requestOpen(void 0, "platform");
+	});
+	useLayoutEffect(() => {
+		reconcileOnMount();
+	}, []);
+	useLayoutEffect(() => {
+		if (!isLibrary) return;
+		const element = popupRef.current;
+		if (element === null || !element.isConnected) return;
+		if (!ctx.pending && ctx.latestInFlight() === null) {
+			const shown = isPopoverOpen(element);
+			if (ctx.committed && !shown) {
+				if (!awaitingClose.current) showPopup(element);
+			} else if (!ctx.committed && shown) {
+				ctx.recordCloseIntent(void 0);
+				element.hidePopover();
+				if (focusWasInside.current) returnFocus(element);
+			}
+		}
+		if (ctx.committed && isPopoverOpen(element)) contentHadFocus.current = false;
+		if (exit.held && !ctx.committed && !exit.waiting() && !awaitingClose.current && !isPopoverOpen(element)) exit.release();
+	});
+	const onBeforeToggle = (event) => {
+		const element = popupRef.current;
+		if (element === null || event.target !== element) return;
+		const toggle = event;
+		if (toggle.newState === "open") {
+			if (isLibrary && !opening.current) {
+				event.preventDefault();
+				ctx.requestOpen(event, "activate");
+			} else ctx.nextOpenGeneration();
+			contentHadFocus.current = false;
+		} else {
+			awaitingClose.current = true;
+			const active = element.ownerDocument.activeElement;
+			focusWasInside.current = active !== null && element.contains(active) || contentHadFocus.current;
+			contentHadFocus.current = false;
+		}
+		onBeforeToggleOption?.(toggle);
+	};
+	const onToggle = (event) => {
+		const element = popupRef.current;
+		if (element === null || event.target !== element) return;
+		awaitingClose.current = false;
+		if (!isLibrary) syncExpanded(element);
+		if (!isPopoverOpen(element)) {
+			const wasInside = focusWasInside.current;
+			focusWasInside.current = false;
+			if (wasInside) returnFocus(element);
+			const intent = ctx.takeCloseIntent();
+			if (isLibrary) {
+				if (!!ctx.intended() || transition === void 0) {
+					const animations = exitAnimations(element);
+					if (animations.length > 0) exit.holdUntil(animations);
+					else exit.release();
+				}
+				ctx.notifyClosed(intent?.event ?? event, intent?.reason ?? "dismiss");
+			}
+		}
+		onToggleOption?.(event);
+	};
+	const onCommand = (event) => {
+		const element = popupRef.current;
+		if (element === null || event.target !== element || event.defaultPrevented) return;
+		const command = String(event.command ?? "").toLowerCase();
+		if (command === "hide-popover" || command === "toggle-popover" && isPopoverOpen(element)) ctx.recordCloseIntent({
+			reason: "activate",
+			event
+		});
+	};
+	const handlers = useRef({
+		onBeforeToggle,
+		onToggle,
+		onCommand
+	});
+	useInsertionEffect(() => {
+		handlers.current = {
+			onBeforeToggle,
+			onToggle,
+			onCommand
+		};
+	});
+	const setElement = useCallback((element) => {
+		if (isDev && element.tagName !== "DIALOG" && element.tagName !== "DIV") console.error(`${part}: expected to render a <dialog> or a <div> but got <${element.tagName.toLowerCase()}>.`);
+		popupRef.current = element;
+		const listeners = [
+			["beforetoggle", (event) => handlers.current.onBeforeToggle(event)],
+			["toggle", (event) => handlers.current.onToggle(event)],
+			["command", (event) => handlers.current.onCommand(event)]
+		];
+		for (const [type, listener] of listeners) element.addEventListener(type, listener);
+		let autofocused = null;
+		if (!isLibrary && initialFocus !== void 0) {
+			const target = resolveInitialFocus(element, initialFocus);
+			if (target !== null && element.contains(target) && !target.hasAttribute("autofocus")) {
+				target.setAttribute("autofocus", "");
+				autofocused = target;
+			}
+		}
+		return () => {
+			for (const [type, listener] of listeners) element.removeEventListener(type, listener);
+			autofocused?.removeAttribute("autofocus");
+			if (popupRef.current === element) popupRef.current = null;
+		};
+	}, [
+		part,
+		popupRef,
+		isLibrary,
+		initialFocus
+	]);
+	const shown = !isLibrary || ctx.committed;
+	const warnedName = useRef(false);
+	useEffect(() => {
+		const element = popupRef.current;
+		if (!isDev || element === null || !shown || warnedName.current) return;
+		if (element.hasAttribute("aria-label")) return;
+		const labelledBy = (element.getAttribute("aria-labelledby") ?? "").split(/\s+/);
+		const doc = element.ownerDocument;
+		if (labelledBy.some((id) => id !== "" && doc.getElementById(id) !== null)) return;
+		const role = element.getAttribute("role");
+		if (role !== "dialog" && role !== "alertdialog" && role !== "menu") return;
+		warnedName.current = true;
+		console.error(`${part}: the popup has no accessible name. Render a Title, or give the Popup an \`aria-label\`.`);
+	}, [
+		popupRef,
+		shown,
+		part
+	]);
+	return {
+		setElement,
+		visible: ctx.committed || exit.held,
+		wrapContent
+	};
+}
+//#endregion
+export { usePopoverPopup };
+
+//# sourceMappingURL=use-popover-popup.mjs.map

package/dist/internal/use-popover-popup.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-popover-popup.mjs","names":[],"sources":["../../src/internal/use-popover-popup.ts"],"sourcesContent":["\"use client\";\nimport {\n  createElement,\n  useCallback,\n  useEffect,\n  useEffectEvent,\n  useInsertionEffect,\n  useLayoutEffect,\n  useRef,\n  useState,\n} from \"react\";\nimport type { ReactNode, RefObject, ViewTransitionClass } from \"react\";\nimport { exitAnimations, useExitAnimation } from \"./use-exit-animation.js\";\nimport type { PopoverRootValue } from \"./use-popover-root.js\";\n\nexport interface UsePopoverPopupOptions {\n  /** Public name of the part for development warnings (`\"Popover.Popup\"`). */\n  readonly part: string;\n  /** Element to focus on open: a ref, or a selector resolved inside the popup (design 6.1). */\n  readonly initialFocus: RefObject<HTMLElement | null> | string | undefined;\n  /**\n   * Replaces `initialFocus` with a function called right before each library open (Menu: the\n   * first or last item by open cause). `null` leaves the choice to the platform. A\n   * `QuietFocusTarget` asks for focus without the focus ring (a pointer-opened menu).\n   */\n  readonly resolveInitialFocus?: (popup: HTMLElement) => HTMLElement | QuietFocusTarget | null;\n  readonly keepMounted: boolean | undefined;\n  /** The consumer's `transition`; decides how a library-driven close keeps its content (4.4). */\n  readonly transition: ViewTransitionClass | undefined;\n  /** Runs after the library's own `beforetoggle` handling (Menu: focus bookkeeping). */\n  readonly onBeforeToggle?: (event: ToggleEvent) => void;\n  /** Runs after the library's own `toggle` handling (Menu: close the stack on Tab-out). */\n  readonly onToggle?: (event: ToggleEvent) => void;\n}\n\n/**\n * An initial focus target opened by a pointer: where the engine reads `focus({ focusVisible })`,\n * the library focuses it with `focusVisible: false` right after `showPopover()` instead of\n * writing `autofocus` (WebKit shows the ring for an `autofocus` target after a click; review H1).\n * Elsewhere it is an ordinary target.\n */\nexport interface QuietFocusTarget {\n  readonly element: HTMLElement;\n  readonly focusVisible: false;\n}\n\nexport interface PopoverPopupHook {\n  /** Callback ref for the popup element; pass as `useRender`'s `ref`. */\n  readonly setElement: (element: HTMLElement) => () => void;\n  /**\n   * Whether the children are shown: committed open, or held while the hide animates (4.4).\n   * Library mode only; JS-free mode always renders them.\n   */\n  readonly visible: boolean;\n  /**\n   * Wraps the library-mode content: call it only while `visible` (`visible ? wrapContent(x) :\n   * null`), or inside the `<Activity>` for `keepMounted`. When a close commit unmounts the\n   * content while it holds focus (a library-driven close with `transition`, where the focused\n   * element is gone before `hidePopover()` runs and the platform restores nothing), the hide\n   * that follows returns focus to the Trigger (design 6.2).\n   */\n  readonly wrapContent: (children: ReactNode) => ReactNode;\n}\n\nconst isDev = process.env.NODE_ENV !== \"production\";\n\nfunction isPopoverOpen(element: Element): boolean {\n  try {\n    return element.matches(\":popover-open\");\n  } catch {\n    return false;\n  }\n}\n\nlet focusVisibleOption: boolean | undefined;\n\n/**\n * The engine reads the `focusVisible` member of `focus()`'s options (Chromium 145, Firefox 104,\n * Safari 18.4). Detected once through a getter: the bindings convert the dictionary before the\n * method runs, so a detached element is enough and nothing is focused.\n */\nfunction supportsFocusVisibleOption(doc: Document): boolean {\n  if (focusVisibleOption === undefined) {\n    let read = false;\n    try {\n      doc.createElement(\"div\").focus({\n        get focusVisible() {\n          read = true;\n          return false;\n        },\n      } as FocusOptions);\n    } catch {\n      read = false;\n    }\n    focusVisibleOption = read;\n  }\n  return focusVisibleOption;\n}\n\n/** Resolves `initialFocus` against the popup (a ref, or a selector inside the popup). */\nfunction resolveInitialFocus(\n  popup: HTMLElement,\n  initialFocus: RefObject<HTMLElement | null> | string,\n): HTMLElement | null {\n  if (typeof initialFocus === \"string\") return popup.querySelector<HTMLElement>(initialFocus);\n  return initialFocus.current;\n}\n\n/** Whether `element` sits inside a popover that is not shown (an outer popup that closed). */\nfunction insideHiddenPopover(element: Element): boolean {\n  for (let node = element.parentElement; node !== null; node = node.parentElement) {\n    if (node.hasAttribute(\"popover\") && !isPopoverOpen(node)) return true;\n  }\n  return false;\n}\n\n/**\n * Records, from its layout-effect cleanup, whether focus is inside the popup when the content\n * goes away: React runs a deleted component's layout cleanups before it detaches the host nodes,\n * so `document.activeElement` still names the focused element there.\n */\nfunction ContentFocusProbe({\n  onDetach,\n  children,\n}: {\n  onDetach: () => void;\n  children?: ReactNode;\n}): ReactNode {\n  useLayoutEffect(() => onDetach, [onDetach]);\n  return children;\n}\n\n/**\n * Everything in a popover-like Popup except rendering (design/components/popover.md 14.2): mount\n * reconciliation, the apply effect, the native `beforetoggle` / `toggle` / `command` listeners,\n * close intents, the focus-return fallback, the JS-free `aria-expanded` sync, the deferred\n * unmount while a hide animates, and `initialFocus`. Shared by Popover and Menu.\n */\nexport function usePopoverPopup(\n  ctx: PopoverRootValue,\n  options: UsePopoverPopupOptions,\n): PopoverPopupHook {\n  const { part, initialFocus, transition, onBeforeToggle: onBeforeToggleOption } = options;\n  const onToggleOption = options.onToggle;\n  const isLibrary = ctx.mode === \"library\";\n  const { popupRef, triggerRef } = ctx;\n\n  // The opening `beforetoggle` lets this one through: the library's own `showPopover()`.\n  const opening = useRef(false);\n  // Set by the synchronous `beforetoggle` of a close, cleared by `toggle` a task later: the\n  // popup is hidden but its `toggle` has not arrived, so the apply effect must not re-open it\n  // from a commit that lands in between (design 2.5).\n  const awaitingClose = useRef(false);\n  // Whether focus was inside the popup when its last close began (design 6.2 rule 1).\n  const focusWasInside = useRef(false);\n  // Whether the content unmounted while holding focus since the popup was last shown (H1).\n  const contentHadFocus = useRef(false);\n  const warnedFocus = useRef(false);\n\n  // --- `held`: children stay mounted while the hide animates (design 4.4) -------------------\n\n  const exit = useExitAnimation();\n\n  // A library-driven close commits `false` first and hides in the layout effect, so without\n  // `transition` the children are held through the close commit (\"previous value in state\").\n  // With `transition` the close commit unmounts them inside the view transition, whose old\n  // snapshot carries the content out.\n  const [prevCommitted, setPrevCommitted] = useState(ctx.committed);\n  if (prevCommitted !== ctx.committed) {\n    setPrevCommitted(ctx.committed);\n    if (isLibrary && prevCommitted && transition === undefined) exit.holdDuringRender();\n  }\n\n  const recordContentFocus = useCallback(() => {\n    const element = popupRef.current;\n    if (element === null) return;\n    const active = element.ownerDocument.activeElement;\n    if (active !== null && active !== element && element.contains(active)) {\n      contentHadFocus.current = true;\n    }\n  }, [popupRef]);\n\n  const wrapContent = useCallback(\n    (children: ReactNode): ReactNode =>\n      createElement(ContentFocusProbe, { onDetach: recordContentFocus }, children),\n    [recordContentFocus],\n  );\n\n  const syncExpanded = (element: HTMLElement): void => {\n    // JS-free mode only (design 9): read the DOM, not `newState`, so a stale task cannot lie.\n    triggerRef.current?.setAttribute(\"aria-expanded\", String(isPopoverOpen(element)));\n  };\n\n  /**\n   * Design 6.2 rule 2, for a close that began with focus inside: when focus is now on `<body>`\n   * or still inside the hidden popup, focus the Trigger (connected, not inside a hidden\n   * popover), else blur what holds focus.\n   */\n  const returnFocus = (element: HTMLElement): void => {\n    const doc = element.ownerDocument;\n    const active = doc.activeElement;\n    if (active !== null && active !== doc.body && !element.contains(active)) return;\n    const trigger = triggerRef.current;\n    if (trigger !== null && trigger.isConnected && !insideHiddenPopover(trigger)) {\n      trigger.focus();\n    } else if (active instanceof HTMLElement && active !== doc.body) {\n      active.blur();\n    }\n  };\n\n  // --- Opening ------------------------------------------------------------------------------\n\n  const resolveFocusTarget = (element: HTMLElement): HTMLElement | QuietFocusTarget | null => {\n    if (options.resolveInitialFocus !== undefined) {\n      const resolved = options.resolveInitialFocus(element);\n      if (resolved === null) return null;\n      const target = resolved instanceof HTMLElement ? resolved : resolved.element;\n      return element.contains(target) ? resolved : null;\n    }\n    if (initialFocus === undefined) return null;\n    const target = resolveInitialFocus(element, initialFocus);\n    if (target !== null && element.contains(target)) return target;\n    if (isDev && !warnedFocus.current) {\n      warnedFocus.current = true;\n      console.error(\n        target === null\n          ? `${part}: \\`initialFocus\\` resolved to no element; the platform picks the focus target.`\n          : `${part}: \\`initialFocus\\` is outside the popup; the platform picks the focus target.`,\n      );\n    }\n    return null;\n  };\n\n  const showPopup = (element: HTMLElement): void => {\n    const resolved = resolveFocusTarget(element);\n    const target =\n      resolved === null || resolved instanceof HTMLElement ? resolved : resolved.element;\n    // A pointer open asks for no focus ring: `focus({ focusVisible: false })` after the show,\n    // where the engine reads that option (QuietFocusTarget).\n    const quiet =\n      target !== null &&\n      !(resolved instanceof HTMLElement) &&\n      supportsFocusVisibleOption(element.ownerDocument);\n    // Otherwise the popover focusing steps honour `autofocus` (and run the dialog focusing steps\n    // for a <dialog>, in every engine); React drops `autoFocus` on client-rendered content.\n    // Never `.focus()` (6.1) except for the quiet target above.\n    const added = target !== null && !quiet && !target.hasAttribute(\"autofocus\");\n    if (added) target.setAttribute(\"autofocus\", \"\");\n    opening.current = true;\n    try {\n      const source = triggerRef.current;\n      element.showPopover(source !== null && source.isConnected ? { source } : undefined);\n    } finally {\n      opening.current = false;\n      if (added) target.removeAttribute(\"autofocus\");\n    }\n    if (quiet && isPopoverOpen(element) && element.contains(target)) {\n      target.focus({ focusVisible: false } as FocusOptions);\n    }\n  };\n\n  // Mount reconciliation (design 2.4): a click before hydration opened the popover natively.\n  // Runs before the apply effect; the dispatch makes the apply effect wait for it.\n  const reconcileOnMount = useEffectEvent(() => {\n    const element = popupRef.current;\n    if (element === null) return;\n    if (!isLibrary) {\n      syncExpanded(element);\n      return;\n    }\n    if (isPopoverOpen(element)) ctx.requestOpen(undefined, \"platform\");\n  });\n  useLayoutEffect(() => {\n    reconcileOnMount();\n  }, []);\n\n  // The apply effect (design 2.5): after every commit, once nothing is in flight, the DOM\n  // follows committed state. One effect covers the normal open, `defaultOpen`, a controlled open\n  // or close, a library-driven close after `openChangeAction(false)` settled, the re-open of a\n  // refused dismissal, and the close after a refused or failed pre-hydration open.\n  useLayoutEffect(() => {\n    if (!isLibrary) return;\n    const element = popupRef.current;\n    if (element === null || !element.isConnected) return;\n    if (!ctx.pending && ctx.latestInFlight() === null) {\n      const shown = isPopoverOpen(element);\n      if (ctx.committed && !shown) {\n        if (!awaitingClose.current) showPopup(element);\n      } else if (!ctx.committed && shown) {\n        // An echo: the `toggle` listener finds `false` intended and skips the dispatch.\n        ctx.recordCloseIntent(undefined);\n        element.hidePopover();\n        // The close commit may have unmounted the focused content before the hide (H1): the\n        // platform restores focus only from inside the popover, so do it now.\n        if (focusWasInside.current) returnFocus(element);\n      }\n    }\n    // Content that unmounted while the popup stays open (not a close): forget it.\n    if (ctx.committed && isPopoverOpen(element)) contentHadFocus.current = false;\n    // A hold the close commit set (or a dismissal's notification commit) that no hide animation\n    // is going to release: the popup is already hidden and its `toggle` has been handled.\n    if (\n      exit.held &&\n      !ctx.committed &&\n      !exit.waiting() &&\n      !awaitingClose.current &&\n      !isPopoverOpen(element)\n    ) {\n      exit.release();\n    }\n  });\n\n  // --- Native listeners (conventions 7.4; filtered on target: React 19.3.1 emulates bubbling\n  // of `toggle`, and a nested popover's events reach this element through the real DOM too) ---\n\n  const onBeforeToggle = (event: Event): void => {\n    const element = popupRef.current;\n    if (element === null || event.target !== element) return;\n    const toggle = event as ToggleEvent;\n    if (toggle.newState === \"open\") {\n      // Every open the library did not start itself is routed through the Root (design 2.2):\n      // a foreign `show-popover` / `toggle-popover` invoker, a script `showPopover()`.\n      if (isLibrary && !opening.current) {\n        event.preventDefault();\n        ctx.requestOpen(event, \"activate\");\n      } else {\n        // A Close action that resolves after this open must not close it (design 3.4).\n        ctx.nextOpenGeneration();\n      }\n      contentHadFocus.current = false;\n    } else {\n      awaitingClose.current = true;\n      const active = element.ownerDocument.activeElement;\n      focusWasInside.current =\n        (active !== null && element.contains(active)) || contentHadFocus.current;\n      contentHadFocus.current = false;\n    }\n    onBeforeToggleOption?.(toggle);\n  };\n\n  const onToggle = (event: Event): void => {\n    const element = popupRef.current;\n    if (element === null || event.target !== element) return;\n    awaitingClose.current = false;\n    if (!isLibrary) syncExpanded(element);\n\n    if (!isPopoverOpen(element)) {\n      // Focus return for what the platform leaves out (design 6.2): a nested popover restores\n      // nothing, and an opener that is gone leaves focus inside the hidden popup.\n      const wasInside = focusWasInside.current;\n      focusWasInside.current = false;\n      if (wasInside) returnFocus(element);\n\n      const intent = ctx.takeCloseIntent();\n      if (isLibrary) {\n        // `false` already intended: the library's own hide (or a dismissal during a pending\n        // part-initiated close). With `transition` such a close needs no hold (4.4).\n        const echo = !ctx.intended();\n        if (!echo || transition === undefined) {\n          const animations = exitAnimations(element);\n          if (animations.length > 0) {\n            // Before the notification, so its commit keeps the children (urgent, internal).\n            exit.holdUntil(animations);\n          } else {\n            // Nothing animates (Firefox, or no CSS exit): release a hold now; the commit is\n            // invisible, the popup is already `display: none`.\n            exit.release();\n          }\n        }\n        ctx.notifyClosed(intent?.event ?? event, intent?.reason ?? \"dismiss\");\n      }\n    }\n    onToggleOption?.(event as ToggleEvent);\n  };\n\n  const onCommand = (event: Event): void => {\n    const element = popupRef.current;\n    if (element === null || event.target !== element || event.defaultPrevented) return;\n    const command = String((event as Event & { command?: string }).command ?? \"\").toLowerCase();\n    // A foreign invoker closing the popup (design 2.3). Opens are caught at `beforetoggle`.\n    if (command === \"hide-popover\" || (command === \"toggle-popover\" && isPopoverOpen(element))) {\n      ctx.recordCloseIntent({ reason: \"activate\", event });\n    }\n  };\n\n  // The listeners the callback ref attaches call the latest render's handlers. An insertion\n  // effect publishes them before refs attach and before any layout effect (whose\n  // `hidePopover()` dispatches `beforetoggle` synchronously).\n  const handlers = useRef({ onBeforeToggle, onToggle, onCommand });\n  useInsertionEffect(() => {\n    handlers.current = { onBeforeToggle, onToggle, onCommand };\n  });\n\n  // --- Element ------------------------------------------------------------------------------\n\n  // The listeners attach in the callback ref, so they are in place from the commit that mounts\n  // the element (no passive-effect window, no extra render). JS-free mode: there is no \"right\n  // before showPopover()\" (the browser runs the command), so the `autofocus` attribute stays on\n  // the `initialFocus` target while it is mounted (as Dialog).\n  const setElement = useCallback(\n    (element: HTMLElement) => {\n      if (isDev && element.tagName !== \"DIALOG\" && element.tagName !== \"DIV\") {\n        console.error(\n          `${part}: expected to render a <dialog> or a <div> but got ` +\n            `<${element.tagName.toLowerCase()}>.`,\n        );\n      }\n      popupRef.current = element;\n      const listeners: [string, EventListener][] = [\n        [\"beforetoggle\", (event) => handlers.current.onBeforeToggle(event)],\n        [\"toggle\", (event) => handlers.current.onToggle(event)],\n        [\"command\", (event) => handlers.current.onCommand(event)],\n      ];\n      for (const [type, listener] of listeners) element.addEventListener(type, listener);\n\n      let autofocused: HTMLElement | null = null;\n      if (!isLibrary && initialFocus !== undefined) {\n        const target = resolveInitialFocus(element, initialFocus);\n        if (target !== null && element.contains(target) && !target.hasAttribute(\"autofocus\")) {\n          target.setAttribute(\"autofocus\", \"\");\n          autofocused = target;\n        }\n      }\n\n      return () => {\n        for (const [type, listener] of listeners) element.removeEventListener(type, listener);\n        autofocused?.removeAttribute(\"autofocus\");\n        if (popupRef.current === element) popupRef.current = null;\n      };\n    },\n    [part, popupRef, isLibrary, initialFocus],\n  );\n\n  // Development check (design 9): `role=\"dialog\"` needs a name once the popup is (or can be)\n  // shown.\n  const shown = !isLibrary || ctx.committed;\n  const warnedName = useRef(false);\n  useEffect(() => {\n    const element = popupRef.current;\n    if (!isDev || element === null || !shown || warnedName.current) return;\n    if (element.hasAttribute(\"aria-label\")) return;\n    const labelledBy = (element.getAttribute(\"aria-labelledby\") ?? \"\").split(/\\s+/);\n    const doc = element.ownerDocument;\n    if (labelledBy.some((id) => id !== \"\" && doc.getElementById(id) !== null)) return;\n    const role = element.getAttribute(\"role\");\n    if (role !== \"dialog\" && role !== \"alertdialog\" && role !== \"menu\") return;\n    warnedName.current = true;\n    console.error(\n      `${part}: the popup has no accessible name. Render a Title, or give the Popup an ` +\n        \"`aria-label`.\",\n    );\n  }, [popupRef, shown, part]);\n\n  return { setElement, visible: ctx.committed || exit.held, wrapContent };\n}\n"],"mappings":"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"}

package/dist/internal/use-popover-root.d.mts

@@ -0,0 +1,2 @@
+import "./types.mjs";
+import { RefObject } from "react";

package/dist/internal/use-popover-root.mjs

@@ -0,0 +1,112 @@
+"use client";
+import { createActionDetails } from "./action-details.mjs";
+import { transitionTypes } from "./transition-types.mjs";
+import { useControllableAction } from "./use-controllable-action.mjs";
+import { useDevWarning } from "./use-dev-warning.mjs";
+import { useCallback, useId, useInsertionEffect, useRef, useState } from "react";
+//#region src/internal/use-popover-root.ts
+function isPopoverOpen(element) {
+	if (element === null) return false;
+	try {
+		return element.matches(":popover-open");
+	} catch {
+		return false;
+	}
+}
+/** How long a recorded close intent survives when the popover did not close (design 2.3). */
+function clearLater(intentRef, intent, popupRef) {
+	setTimeout(() => {
+		if (intentRef.current === intent && isPopoverOpen(popupRef.current)) intentRef.current = void 0;
+	}, 0);
+}
+/**
+* The Root of a popover-like component without its public props (design 14.1): mode detection
+* (once, from the first render), `useControllableAction<boolean>`, ids, refs, close intents and
+* the intent-aware `requestOpen` / `requestClose` / `notifyClosed`.
+*/
+function usePopoverRoot(options) {
+	const { component, part, open, defaultOpen, openChangeAction, details, onDispatch } = options;
+	const isLibraryNow = options.mode === "library" || open !== void 0 || defaultOpen !== void 0 || openChangeAction !== void 0;
+	const [mode] = useState(isLibraryNow ? "library" : "static");
+	const isLibrary = mode === "library";
+	useDevWarning(isLibrary !== isLibraryNow, `${part}: the mode changed after mount (\`open\`, \`defaultOpen\` and \`openChangeAction\` were all absent on one render and present on another). Switching between JS-free and library mode is not supported.`);
+	const { committed, optimistic, pending, dispatch, latestInFlight } = useControllableAction({
+		controlled: isLibrary ? open : void 0,
+		defaultValue: isLibrary ? defaultOpen : void 0,
+		initialValue: false,
+		action: isLibrary ? openChangeAction : void 0,
+		transitionTypes: (next) => transitionTypes(component, next ? "open" : "close"),
+		warn: {
+			component: part,
+			prop: "open"
+		}
+	});
+	const id = useId();
+	const triggerRef = useRef(null);
+	const popupRef = useRef(null);
+	const closeIntent = useRef(void 0);
+	const committedOptimistic = useRef(optimistic);
+	useInsertionEffect(() => {
+		committedOptimistic.current = optimistic;
+	});
+	const generation = useRef(0);
+	const openGeneration = useCallback(() => generation.current, []);
+	const nextOpenGeneration = useCallback(() => {
+		generation.current++;
+	}, []);
+	const recordCloseIntent = useCallback((intent) => {
+		closeIntent.current = intent;
+		if (intent !== void 0) clearLater(closeIntent, intent, popupRef);
+	}, []);
+	const takeCloseIntent = useCallback(() => {
+		const intent = closeIntent.current;
+		closeIntent.current = void 0;
+		return intent;
+	}, []);
+	const intended = () => latestInFlight()?.next ?? committedOptimistic.current;
+	const buildDetails = (event, reason) => details !== void 0 ? details(event, reason) : createActionDetails(event, { reason });
+	const send = (next, event, reason) => {
+		const built = buildDetails(event, reason);
+		if (next) nextOpenGeneration();
+		onDispatch?.(next, built);
+		dispatch(next, built);
+	};
+	const requestOpen = (event, reason) => {
+		if (!isLibrary || intended()) return;
+		send(true, event, reason);
+	};
+	const requestClose = (event, reason) => {
+		if (!isLibrary || !intended()) return;
+		send(false, event, reason);
+	};
+	const notifyClosed = (event, reason) => {
+		if (!isLibrary || !intended()) return;
+		send(false, event, reason);
+	};
+	return {
+		mode,
+		ids: {
+			popup: id,
+			title: `${id}-title`,
+			description: `${id}-description`
+		},
+		committed: isLibrary && committed,
+		optimistic: isLibrary && optimistic,
+		pending: isLibrary && pending,
+		intended,
+		openGeneration,
+		nextOpenGeneration,
+		requestOpen,
+		requestClose,
+		notifyClosed,
+		latestInFlight,
+		triggerRef,
+		popupRef,
+		recordCloseIntent,
+		takeCloseIntent
+	};
+}
+//#endregion
+export { usePopoverRoot };
+
+//# sourceMappingURL=use-popover-root.mjs.map

package/dist/internal/use-popover-root.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-popover-root.mjs","names":[],"sources":["../../src/internal/use-popover-root.ts"],"sourcesContent":["\"use client\";\nimport { useCallback, useId, useInsertionEffect, useRef, useState } from \"react\";\nimport type { RefObject } from \"react\";\nimport { createActionDetails } from \"./action-details.js\";\nimport { transitionTypes } from \"./transition-types.js\";\nimport type { ActionDetails, ChangeAction, ChangeReason } from \"./types.js\";\nimport { useControllableAction } from \"./use-controllable-action.js\";\nimport { useDevWarning } from \"./use-dev-warning.js\";\n\n/**\n * \"static\": JS-free mode, the browser owns open and close through Invoker Commands. \"library\":\n * opening and part-initiated closing are library-owned (transitions keyed on committed state);\n * dismissals are the browser's and notified (design/components/popover.md section 2).\n */\nexport type PopoverMode = \"static\" | \"library\";\n\n/**\n * What caused the next close, recorded just before it happens (design 2.3). The `toggle` event\n * carries no source; without an intent a close is a `\"dismiss\"`.\n */\nexport interface PopoverCloseIntent {\n  readonly reason: ChangeReason;\n  readonly event: Event | undefined;\n}\n\n/** The `details` every popover-like `openChangeAction` receives. */\nexport interface PopoverLikeDetails extends ActionDetails {\n  readonly reason: ChangeReason;\n}\n\n/**\n * The Root's state and machinery, shared by Popover and Menu (design 14). The component puts it\n * in its own context; `usePopoverTrigger` and `usePopoverPopup` take it as their first argument.\n */\nexport interface PopoverRootValue {\n  readonly mode: PopoverMode;\n  /** `useId`-based ids: the popup, its Title and its Description. */\n  readonly ids: { readonly popup: string; readonly title: string; readonly description: string };\n  /** Committed open state (library mode); `false` in JS-free mode. */\n  readonly committed: boolean;\n  /** Optimistic open state (library mode); `false` in JS-free mode. */\n  readonly optimistic: boolean;\n  /** The Root's transition is pending (library mode). */\n  readonly pending: boolean;\n  /**\n   * What the user already intends: the latest in-flight dispatch's `next`, else the optimistic\n   * value of the last commit. Safe to call from handlers and effects (layout effects included,\n   * also in the commit that changed it), and after an `await`. Not during render.\n   */\n  readonly intended: () => boolean;\n  /**\n   * A counter that grows with every open (a requested open, or the popup being shown). A part\n   * whose close runs after an `await` records it first and drops the close when it changed: the\n   * user dismissed and re-opened meanwhile (Popover.Close, design 3.4). Handlers only.\n   */\n  readonly openGeneration: () => number;\n  /** Advance `openGeneration` (the Popup's `beforetoggle` for an open). */\n  readonly nextOpenGeneration: () => void;\n  /**\n   * Open through the Root's transition (library mode): a Trigger click, a foreign open caught at\n   * `beforetoggle`, or mount reconciliation. A no-op when `true` is already intended.\n   */\n  readonly requestOpen: (event: Event | undefined, reason: ChangeReason) => void;\n  /**\n   * A library-owned close (library mode): a Trigger click while open, a Close part, Menu's item\n   * activation. `openChangeAction(false)` is awaited and the popup hides in the commit. A no-op\n   * when `false` is already intended.\n   */\n  readonly requestClose: (event: Event | undefined, reason: ChangeReason) => void;\n  /**\n   * The browser hid the popup (a dismissal or a foreign invoker): dispatch the `false`\n   * notification unless `false` is already intended (the library's own echo, or a dismissal\n   * during a pending part-initiated close).\n   */\n  readonly notifyClosed: (event: Event | undefined, reason: ChangeReason) => void;\n  /** From `useControllableAction`: the latest in-flight intent, or `null`. */\n  readonly latestInFlight: () => { readonly next: boolean } | null;\n  /** The registered Trigger: `showPopover({ source })` and the focus-return fallback. */\n  readonly triggerRef: RefObject<HTMLElement | null>;\n  /** The popup element, set by the Popup's ref; how Close reaches `hidePopover()`. */\n  readonly popupRef: RefObject<HTMLElement | null>;\n  /** Record what causes the next close. Cleared after a task if the popover did not close. */\n  readonly recordCloseIntent: (intent: PopoverCloseIntent | undefined) => void;\n  /** Read and clear the recorded intent (the Popup's `toggle` listener). */\n  readonly takeCloseIntent: () => PopoverCloseIntent | undefined;\n}\n\nexport interface UsePopoverRootOptions<Details extends PopoverLikeDetails> {\n  /** Transition types and messages: `\"popover\"` gives `fsui-popover`, `fsui-popover-open`, … */\n  readonly component: string;\n  /** Public name of the Root part for development warnings (`\"Popover.Root\"`). */\n  readonly part: string;\n  readonly open: boolean | undefined;\n  readonly defaultOpen: boolean | undefined;\n  readonly openChangeAction: ChangeAction<boolean, Details> | undefined;\n  /**\n   * Builds the `details` of a dispatch. Default: `createActionDetails(event, { reason })`. A\n   * component with more fields (Menu) passes its own.\n   */\n  readonly details?: (event: Event | undefined, reason: ChangeReason) => Details;\n  /**\n   * `\"library\"` forces library mode whatever the props (Menu, which has no JS-free mode). Default:\n   * detected from `open` / `defaultOpen` / `openChangeAction` on the first render.\n   */\n  readonly mode?: \"library\";\n  /**\n   * Called synchronously for every dispatch, before the action runs (Menu: cancel hover timers,\n   * read the open cause).\n   */\n  readonly onDispatch?: (next: boolean, details: Details) => void;\n}\n\nfunction isPopoverOpen(element: Element | null): boolean {\n  if (element === null) return false;\n  try {\n    return element.matches(\":popover-open\");\n  } catch {\n    return false;\n  }\n}\n\n/** How long a recorded close intent survives when the popover did not close (design 2.3). */\nfunction clearLater(\n  intentRef: { current: PopoverCloseIntent | undefined },\n  intent: PopoverCloseIntent,\n  popupRef: { current: HTMLElement | null },\n): void {\n  setTimeout(() => {\n    // Closed: its `toggle` event (queued as a task) consumes the intent. Still open: the close\n    // was cancelled or invalid, so the intent is stale.\n    if (intentRef.current === intent && isPopoverOpen(popupRef.current)) {\n      intentRef.current = undefined;\n    }\n  }, 0);\n}\n\n/**\n * The Root of a popover-like component without its public props (design 14.1): mode detection\n * (once, from the first render), `useControllableAction<boolean>`, ids, refs, close intents and\n * the intent-aware `requestOpen` / `requestClose` / `notifyClosed`.\n */\nexport function usePopoverRoot<Details extends PopoverLikeDetails>(\n  options: UsePopoverRootOptions<Details>,\n): PopoverRootValue {\n  const { component, part, open, defaultOpen, openChangeAction, details, onDispatch } = options;\n\n  // Mode is decided once, from the first render's props (design 2).\n  const isLibraryNow =\n    options.mode === \"library\" ||\n    open !== undefined ||\n    defaultOpen !== undefined ||\n    openChangeAction !== undefined;\n  const [mode] = useState<PopoverMode>(isLibraryNow ? \"library\" : \"static\");\n  const isLibrary = mode === \"library\";\n  useDevWarning(\n    isLibrary !== isLibraryNow,\n    `${part}: the mode changed after mount (\\`open\\`, \\`defaultOpen\\` and \\`openChangeAction\\` ` +\n      \"were all absent on one render and present on another). Switching between JS-free and \" +\n      \"library mode is not supported.\",\n  );\n\n  // Hooks cannot be conditional: JS-free mode calls the hook too and never dispatches.\n  const { committed, optimistic, pending, dispatch, latestInFlight } = useControllableAction<\n    boolean,\n    Details\n  >({\n    controlled: isLibrary ? open : undefined,\n    defaultValue: isLibrary ? defaultOpen : undefined,\n    initialValue: false,\n    action: isLibrary ? openChangeAction : undefined,\n    transitionTypes: (next) => transitionTypes(component, next ? \"open\" : \"close\"),\n    warn: { component: part, prop: \"open\" },\n  });\n\n  const id = useId();\n  const triggerRef = useRef<HTMLElement | null>(null);\n  const popupRef = useRef<HTMLElement | null>(null);\n  const closeIntent = useRef<PopoverCloseIntent | undefined>(undefined);\n\n  // The optimistic value of the last commit, for callers that run after an `await` (a Close\n  // action's continuation) and would otherwise read the value of the render they were created in.\n  // An insertion effect runs in the mutation phase, before any layout effect of the same commit\n  // (a child's included), so `intended()` is current there too.\n  const committedOptimistic = useRef(optimistic);\n  useInsertionEffect(() => {\n    committedOptimistic.current = optimistic;\n  });\n  const generation = useRef(0);\n  const openGeneration = useCallback(() => generation.current, []);\n  const nextOpenGeneration = useCallback(() => {\n    generation.current++;\n  }, []);\n\n  const recordCloseIntent = useCallback((intent: PopoverCloseIntent | undefined) => {\n    closeIntent.current = intent;\n    if (intent !== undefined) clearLater(closeIntent, intent, popupRef);\n  }, []);\n  const takeCloseIntent = useCallback(() => {\n    const intent = closeIntent.current;\n    closeIntent.current = undefined;\n    return intent;\n  }, []);\n\n  // Conventions 3.8 rule 1: judge no-ops against what the user already intends. That also\n  // deduplicates the StrictMode re-run of the mount reconciliation and recognises the library's\n  // own `hidePopover()` echoing back through `toggle`.\n  const intended = (): boolean => latestInFlight()?.next ?? committedOptimistic.current;\n\n  const buildDetails = (event: Event | undefined, reason: ChangeReason): Details =>\n    details !== undefined\n      ? details(event, reason)\n      : (createActionDetails(event, { reason }) as unknown as Details);\n\n  const send = (next: boolean, event: Event | undefined, reason: ChangeReason): void => {\n    const built = buildDetails(event, reason);\n    if (next) nextOpenGeneration();\n    onDispatch?.(next, built);\n    dispatch(next, built);\n  };\n\n  const requestOpen = (event: Event | undefined, reason: ChangeReason): void => {\n    if (!isLibrary || intended()) return;\n    send(true, event, reason);\n  };\n\n  const requestClose = (event: Event | undefined, reason: ChangeReason): void => {\n    if (!isLibrary || !intended()) return;\n    send(false, event, reason);\n  };\n\n  // Same guard as `requestClose`; a separate name because the callers mean different things.\n  const notifyClosed = (event: Event | undefined, reason: ChangeReason): void => {\n    if (!isLibrary || !intended()) return;\n    send(false, event, reason);\n  };\n\n  // Not memoised: `dispatch` is a new function on every render (as Dialog), so parts re-render\n  // with the Root, which they do anyway when its state changes.\n  return {\n    mode,\n    ids: { popup: id, title: `${id}-title`, description: `${id}-description` },\n    committed: isLibrary && committed,\n    optimistic: isLibrary && optimistic,\n    pending: isLibrary && pending,\n    intended,\n    openGeneration,\n    nextOpenGeneration,\n    requestOpen,\n    requestClose,\n    notifyClosed,\n    latestInFlight,\n    triggerRef,\n    popupRef,\n    recordCloseIntent,\n    takeCloseIntent,\n  };\n}\n"],"mappings":";;;;;;;AAgHA,SAAS,cAAc,SAAkC;CACvD,IAAI,YAAY,MAAM,OAAO;CAC7B,IAAI;EACF,OAAO,QAAQ,QAAQ,eAAe;CACxC,QAAQ;EACN,OAAO;CACT;AACF;;AAGA,SAAS,WACP,WACA,QACA,UACM;CACN,iBAAiB;EAGf,IAAI,UAAU,YAAY,UAAU,cAAc,SAAS,OAAO,GAChE,UAAU,UAAU,KAAA;CAExB,GAAG,CAAC;AACN;;;;;;AAOA,SAAgB,eACd,SACkB;CAClB,MAAM,EAAE,WAAW,MAAM,MAAM,aAAa,kBAAkB,SAAS,eAAe;CAGtF,MAAM,eACJ,QAAQ,SAAS,aACjB,SAAS,KAAA,KACT,gBAAgB,KAAA,KAChB,qBAAqB,KAAA;CACvB,MAAM,CAAC,QAAQ,SAAsB,eAAe,YAAY,QAAQ;CACxE,MAAM,YAAY,SAAS;CAC3B,cACE,cAAc,cACd,GAAG,KAAK,uMAGV;CAGA,MAAM,EAAE,WAAW,YAAY,SAAS,UAAU,mBAAmB,sBAGnE;EACA,YAAY,YAAY,OAAO,KAAA;EAC/B,cAAc,YAAY,cAAc,KAAA;EACxC,cAAc;EACd,QAAQ,YAAY,mBAAmB,KAAA;EACvC,kBAAkB,SAAS,gBAAgB,WAAW,OAAO,SAAS,OAAO;EAC7E,MAAM;GAAE,WAAW;GAAM,MAAM;EAAO;CACxC,CAAC;CAED,MAAM,KAAK,MAAM;CACjB,MAAM,aAAa,OAA2B,IAAI;CAClD,MAAM,WAAW,OAA2B,IAAI;CAChD,MAAM,cAAc,OAAuC,KAAA,CAAS;CAMpE,MAAM,sBAAsB,OAAO,UAAU;CAC7C,yBAAyB;EACvB,oBAAoB,UAAU;CAChC,CAAC;CACD,MAAM,aAAa,OAAO,CAAC;CAC3B,MAAM,iBAAiB,kBAAkB,WAAW,SAAS,CAAC,CAAC;CAC/D,MAAM,qBAAqB,kBAAkB;EAC3C,WAAW;CACb,GAAG,CAAC,CAAC;CAEL,MAAM,oBAAoB,aAAa,WAA2C;EAChF,YAAY,UAAU;EACtB,IAAI,WAAW,KAAA,GAAW,WAAW,aAAa,QAAQ,QAAQ;CACpE,GAAG,CAAC,CAAC;CACL,MAAM,kBAAkB,kBAAkB;EACxC,MAAM,SAAS,YAAY;EAC3B,YAAY,UAAU,KAAA;EACtB,OAAO;CACT,GAAG,CAAC,CAAC;CAKL,MAAM,iBAA0B,eAAe,CAAC,EAAE,QAAQ,oBAAoB;CAE9E,MAAM,gBAAgB,OAA0B,WAC9C,YAAY,KAAA,IACR,QAAQ,OAAO,MAAM,IACpB,oBAAoB,OAAO,EAAE,OAAO,CAAC;CAE5C,MAAM,QAAQ,MAAe,OAA0B,WAA+B;EACpF,MAAM,QAAQ,aAAa,OAAO,MAAM;EACxC,IAAI,MAAM,mBAAmB;EAC7B,aAAa,MAAM,KAAK;EACxB,SAAS,MAAM,KAAK;CACtB;CAEA,MAAM,eAAe,OAA0B,WAA+B;EAC5E,IAAI,CAAC,aAAa,SAAS,GAAG;EAC9B,KAAK,MAAM,OAAO,MAAM;CAC1B;CAEA,MAAM,gBAAgB,OAA0B,WAA+B;EAC7E,IAAI,CAAC,aAAa,CAAC,SAAS,GAAG;EAC/B,KAAK,OAAO,OAAO,MAAM;CAC3B;CAGA,MAAM,gBAAgB,OAA0B,WAA+B;EAC7E,IAAI,CAAC,aAAa,CAAC,SAAS,GAAG;EAC/B,KAAK,OAAO,OAAO,MAAM;CAC3B;CAIA,OAAO;EACL;EACA,KAAK;GAAE,OAAO;GAAI,OAAO,GAAG,GAAG;GAAS,aAAa,GAAG,GAAG;EAAc;EACzE,WAAW,aAAa;EACxB,YAAY,aAAa;EACzB,SAAS,aAAa;EACtB;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;CACF;AACF"}

package/dist/internal/use-popover-trigger.mjs

@@ -0,0 +1,86 @@
+"use client";
+import { dataAttr } from "./data-attr.mjs";
+import { rendersButton } from "./use-render.mjs";
+import { useCallback } from "react";
+//#region src/internal/use-popover-trigger.ts
+const isDev = process.env.NODE_ENV !== "production";
+function isPopoverOpen(element) {
+	if (element === null) return false;
+	try {
+		return element.matches(":popover-open");
+	} catch {
+		return false;
+	}
+}
+/**
+* The Trigger of a popover-like component (design/components/popover.md 14.3):
+* `button[commandfor][command="toggle-popover"]` with `aria-expanded`. In JS-free mode the
+* browser runs the command and the Popup keeps `aria-expanded` current on the element. In library
+* mode the click is cancelled (so the command does not run) and toggles against what the user
+* already intends: an open through `requestOpen`, a library-owned close through `requestClose`.
+*
+* Menu adds `aria-haspopup="menu"` and its own key handling on top.
+*/
+function usePopoverTrigger(ctx, options) {
+	const { part, disabled, render, handlers, activate, disabledAs = "native" } = options;
+	const isLibrary = ctx.mode === "library";
+	const { ids, triggerRef, popupRef } = ctx;
+	const state = {
+		open: ctx.optimistic,
+		pending: ctx.pending,
+		disabled
+	};
+	const ref = useCallback((element) => {
+		if (isDev && !isLibrary && element.tagName !== "BUTTON") console.error(`${part}: rendered a <${element.tagName.toLowerCase()}> in JS-free mode. Only a <button> runs \`command="toggle-popover"\`; this trigger will not open the popover. Render a <button>, or put the component in library mode (\`defaultOpen={false}\`).`);
+		triggerRef.current = element;
+		if (!isLibrary && popupRef.current !== null) element.setAttribute("aria-expanded", String(isPopoverOpen(popupRef.current)));
+		return () => {
+			if (triggerRef.current === element) triggerRef.current = null;
+		};
+	}, [
+		isLibrary,
+		part,
+		triggerRef,
+		popupRef
+	]);
+	const onClick = (event) => {
+		event.preventDefault();
+		if (disabled) return;
+		if (activate !== void 0) {
+			activate(event);
+			return;
+		}
+		const native = event.nativeEvent;
+		if (ctx.intended()) ctx.requestClose(native, "activate");
+		else ctx.requestOpen(native, "activate");
+	};
+	const merged = { ...handlers };
+	if (isLibrary) {
+		const extra = handlers?.onClick;
+		merged.onClick = extra === void 0 ? onClick : (event) => {
+			extra(event);
+			onClick(event);
+		};
+	}
+	const ariaDisabled = disabledAs === "aria";
+	return {
+		state,
+		libraryProps: {
+			...rendersButton(render) && { type: "button" },
+			disabled: ariaDisabled ? void 0 : disabled,
+			...ariaDisabled && { "aria-disabled": disabled ? true : void 0 },
+			commandfor: ids.popup,
+			command: "toggle-popover",
+			"aria-expanded": isLibrary ? state.open : false,
+			...merged,
+			"data-open": dataAttr(state.open),
+			"data-pending": dataAttr(state.pending),
+			"data-disabled": dataAttr((isLibrary || ariaDisabled) && disabled)
+		},
+		ref
+	};
+}
+//#endregion
+export { usePopoverTrigger };
+
+//# sourceMappingURL=use-popover-trigger.mjs.map

package/dist/internal/use-popover-trigger.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-popover-trigger.mjs","names":[],"sources":["../../src/internal/use-popover-trigger.ts"],"sourcesContent":["\"use client\";\nimport { useCallback } from \"react\";\nimport type { ComponentPropsWithRef, DOMAttributes, MouseEvent } from \"react\";\nimport { dataAttr } from \"./data-attr.js\";\nimport type { RenderProp } from \"./types.js\";\nimport { rendersButton } from \"./use-render.js\";\nimport type { DataAttributes } from \"./use-render.js\";\nimport type { PopoverRootValue } from \"./use-popover-root.js\";\n\nexport interface PopoverTriggerHookState {\n  /** Optimistic open state (library mode); `false` in JS-free mode. */\n  readonly open: boolean;\n  /** The Root's transition is pending (an open, a part-initiated close or a notification). */\n  readonly pending: boolean;\n  readonly disabled: boolean;\n}\n\n/** Event handlers a component layers onto the Trigger's own (Menu's keys and hover intent). */\nexport type PopoverTriggerHandlers = Pick<\n  DOMAttributes<HTMLButtonElement>,\n  \"onClick\" | \"onKeyDown\" | \"onPointerMove\" | \"onPointerEnter\" | \"onPointerLeave\"\n>;\n\nexport interface UsePopoverTriggerOptions<State> {\n  /** Public name of the part for development warnings (`\"Popover.Trigger\"`). */\n  readonly part: string;\n  readonly disabled: boolean;\n  readonly render: RenderProp<ComponentPropsWithRef<\"button\">, State> | undefined;\n  /**\n   * Extra handlers, merged in front of the Trigger's own: for a key both define, the extra one\n   * runs first (the consumer's pass-through handler still runs before both, conventions 1.2).\n   */\n  readonly handlers?: PopoverTriggerHandlers;\n  /**\n   * What a click does in library mode, after the command has been cancelled and `disabled`\n   * checked. Default: toggle against `intended()` (`requestOpen` / `requestClose`). Menu's\n   * SubmenuTrigger opens, or moves focus into an already open submenu, and never closes.\n   */\n  readonly activate?: (event: MouseEvent<HTMLElement>) => void;\n  /**\n   * How `disabled` is rendered. `\"native\"` (default): the `disabled` attribute, so the button is\n   * no invoker at all. `\"aria\"`: `aria-disabled=\"true\"` and no `disabled` (a menu item stays\n   * focusable); the click handler still refuses.\n   */\n  readonly disabledAs?: \"native\" | \"aria\";\n}\n\nexport interface PopoverTriggerHook {\n  readonly state: PopoverTriggerHookState;\n  /** Owned props (conventions 1.2) for `useRender`'s `libraryProps`. */\n  readonly libraryProps: ComponentPropsWithRef<\"button\"> & DataAttributes;\n  /** Registers the element as the Root's Trigger; pass as `useRender`'s `ref`. */\n  readonly ref: (element: HTMLElement) => () => void;\n}\n\nconst isDev = process.env.NODE_ENV !== \"production\";\n\nfunction isPopoverOpen(element: Element | null): boolean {\n  if (element === null) return false;\n  try {\n    return element.matches(\":popover-open\");\n  } catch {\n    return false;\n  }\n}\n\n/**\n * The Trigger of a popover-like component (design/components/popover.md 14.3):\n * `button[commandfor][command=\"toggle-popover\"]` with `aria-expanded`. In JS-free mode the\n * browser runs the command and the Popup keeps `aria-expanded` current on the element. In library\n * mode the click is cancelled (so the command does not run) and toggles against what the user\n * already intends: an open through `requestOpen`, a library-owned close through `requestClose`.\n *\n * Menu adds `aria-haspopup=\"menu\"` and its own key handling on top.\n */\nexport function usePopoverTrigger<State>(\n  ctx: PopoverRootValue,\n  options: UsePopoverTriggerOptions<State>,\n): PopoverTriggerHook {\n  const { part, disabled, render, handlers, activate, disabledAs = \"native\" } = options;\n  const isLibrary = ctx.mode === \"library\";\n  const { ids, triggerRef, popupRef } = ctx;\n\n  const state: PopoverTriggerHookState = {\n    open: ctx.optimistic,\n    // Opens, part-initiated closes and dismissal notifications all belong to the Trigger (4.2).\n    pending: ctx.pending,\n    disabled,\n  };\n\n  const ref = useCallback(\n    (element: HTMLElement) => {\n      if (isDev && !isLibrary && element.tagName !== \"BUTTON\") {\n        console.error(\n          `${part}: rendered a <${element.tagName.toLowerCase()}> in JS-free mode. Only a ` +\n            '<button> runs `command=\"toggle-popover\"`; this trigger will not open the popover. ' +\n            \"Render a <button>, or put the component in library mode (`defaultOpen={false}`).\",\n        );\n      }\n      triggerRef.current = element;\n      // JS-free mode: the DOM owns `aria-expanded` (design 9). A Trigger that mounts after the\n      // Popup (or is re-created) picks up the current state here.\n      if (!isLibrary && popupRef.current !== null) {\n        element.setAttribute(\"aria-expanded\", String(isPopoverOpen(popupRef.current)));\n      }\n      return () => {\n        if (triggerRef.current === element) triggerRef.current = null;\n      };\n    },\n    [isLibrary, part, triggerRef, popupRef],\n  );\n\n  const onClick = (event: MouseEvent<HTMLElement>) => {\n    // Cancelling the click cancels the command (it runs as the button's activation behaviour,\n    // only if the click was not cancelled). Enter and Space synthesise the same click.\n    event.preventDefault();\n    if (disabled) return;\n    if (activate !== undefined) {\n      activate(event);\n      return;\n    }\n    const native = event.nativeEvent;\n    if (ctx.intended()) ctx.requestClose(native, \"activate\");\n    else ctx.requestOpen(native, \"activate\");\n  };\n\n  // The component's handlers first, then the Trigger's (design/components/menu.md 14). The click\n  // handler is only owned when installed, so a render element keeps its own `onClick` in JS-free\n  // mode.\n  const merged: PopoverTriggerHandlers = { ...handlers };\n  if (isLibrary) {\n    const extra = handlers?.onClick;\n    merged.onClick =\n      extra === undefined\n        ? onClick\n        : (event) => {\n            extra(event);\n            onClick(event);\n          };\n  }\n  const ariaDisabled = disabledAs === \"aria\";\n\n  const libraryProps: ComponentPropsWithRef<\"button\"> & DataAttributes = {\n    // `type` only applies to a <button>; on any other element the key is not owned.\n    ...(rendersButton(render) && { type: \"button\" as const }),\n    // Owned: a render element must not re-enable a disabled Trigger (in JS-free mode the browser\n    // would run its command). With `disabledAs: \"aria\"` it is owned as absent.\n    disabled: ariaDisabled ? undefined : disabled,\n    ...(ariaDisabled && { \"aria-disabled\": disabled ? true : undefined }),\n    commandfor: ids.popup,\n    command: \"toggle-popover\",\n    // Library mode: optimistic. JS-free mode: \"false\" in React; the Popup's `toggle` listener\n    // writes the DOM value, and React never rewrites an unchanged prop.\n    \"aria-expanded\": isLibrary ? state.open : false,\n    ...merged,\n    \"data-open\": dataAttr(state.open),\n    \"data-pending\": dataAttr(state.pending),\n    \"data-disabled\": dataAttr((isLibrary || ariaDisabled) && disabled),\n  };\n\n  return { state, libraryProps, ref };\n}\n"],"mappings":";;;;;AAuDA,MAAM,QAAQ,QAAQ,IAAI,aAAa;AAEvC,SAAS,cAAc,SAAkC;CACvD,IAAI,YAAY,MAAM,OAAO;CAC7B,IAAI;EACF,OAAO,QAAQ,QAAQ,eAAe;CACxC,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;;;AAWA,SAAgB,kBACd,KACA,SACoB;CACpB,MAAM,EAAE,MAAM,UAAU,QAAQ,UAAU,UAAU,aAAa,aAAa;CAC9E,MAAM,YAAY,IAAI,SAAS;CAC/B,MAAM,EAAE,KAAK,YAAY,aAAa;CAEtC,MAAM,QAAiC;EACrC,MAAM,IAAI;EAEV,SAAS,IAAI;EACb;CACF;CAEA,MAAM,MAAM,aACT,YAAyB;EACxB,IAAI,SAAS,CAAC,aAAa,QAAQ,YAAY,UAC7C,QAAQ,MACN,GAAG,KAAK,gBAAgB,QAAQ,QAAQ,YAAY,EAAE,iMAGxD;EAEF,WAAW,UAAU;EAGrB,IAAI,CAAC,aAAa,SAAS,YAAY,MACrC,QAAQ,aAAa,iBAAiB,OAAO,cAAc,SAAS,OAAO,CAAC,CAAC;EAE/E,aAAa;GACX,IAAI,WAAW,YAAY,SAAS,WAAW,UAAU;EAC3D;CACF,GACA;EAAC;EAAW;EAAM;EAAY;CAAQ,CACxC;CAEA,MAAM,WAAW,UAAmC;EAGlD,MAAM,eAAe;EACrB,IAAI,UAAU;EACd,IAAI,aAAa,KAAA,GAAW;GAC1B,SAAS,KAAK;GACd;EACF;EACA,MAAM,SAAS,MAAM;EACrB,IAAI,IAAI,SAAS,GAAG,IAAI,aAAa,QAAQ,UAAU;OAClD,IAAI,YAAY,QAAQ,UAAU;CACzC;CAKA,MAAM,SAAiC,EAAE,GAAG,SAAS;CACrD,IAAI,WAAW;EACb,MAAM,QAAQ,UAAU;EACxB,OAAO,UACL,UAAU,KAAA,IACN,WACC,UAAU;GACT,MAAM,KAAK;GACX,QAAQ,KAAK;EACf;CACR;CACA,MAAM,eAAe,eAAe;CAoBpC,OAAO;EAAE;EAAO,cAAA;GAhBd,GAAI,cAAc,MAAM,KAAK,EAAE,MAAM,SAAkB;GAGvD,UAAU,eAAe,KAAA,IAAY;GACrC,GAAI,gBAAgB,EAAE,iBAAiB,WAAW,OAAO,KAAA,EAAU;GACnE,YAAY,IAAI;GAChB,SAAS;GAGT,iBAAiB,YAAY,MAAM,OAAO;GAC1C,GAAG;GACH,aAAa,SAAS,MAAM,IAAI;GAChC,gBAAgB,SAAS,MAAM,OAAO;GACtC,iBAAiB,UAAU,aAAa,iBAAiB,QAAQ;EAGxC;EAAG;CAAI;AACpC"}