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

package/dist/internal/use-native-select-value.mjs

@@ -0,0 +1,184 @@
+"use client";
+import { useLatest } from "./use-latest.mjs";
+import { useNativeGroupReconciliation } from "./use-native-group-reconciliation.mjs";
+import { useCallback, useEffectEvent, useLayoutEffect, useMemo, useRef } from "react";
+//#region src/internal/use-native-select-value.ts
+/** The first option whose value is `value` (react-dom's `updateOptions` selects the first). */
+function findOption(select, value) {
+	for (const option of select.options) if (option.value === value) return option;
+	return null;
+}
+function isEnabled(option) {
+	if (option.disabled) return false;
+	const parent = option.parentElement;
+	return !(parent?.tagName === "OPTGROUP" && parent.disabled);
+}
+function firstEnabled(select) {
+	for (const option of select.options) if (isEnabled(option)) return option.value;
+	return "";
+}
+/**
+* The spec's reset result for a single select: the last option whose `defaultSelected` is true,
+* else the first enabled option, else `""` (nothing selected).
+*/
+function readResetValue(select) {
+	let last = null;
+	for (const option of select.options) if (option.defaultSelected) last = option;
+	return last !== null ? last.value : firstEnabled(select);
+}
+/**
+* The option a `<select>` rendered with the value `""` selects: an option whose value is `""`
+* (react-dom's `updateOptions("")` and Fizz's `selected` attribute both pick it, even when it is
+* disabled), else the first enabled option (the selectedness setting algorithm), else `""`.
+*/
+function implicitDefault(select) {
+	return findOption(select, "") !== null ? "" : firstEnabled(select);
+}
+/**
+* The reset-target mirror followed by the re-apply, in one synchronous step
+* (design/components/select.md 6.1). Writing `defaultSelected = true` on an option whose
+* dirtiness is false selects it, so the intended option is re-selected right after. Writes only
+* what differs: the common commit writes nothing.
+*/
+function applySelection(select, target, resetTarget) {
+	if (resetTarget !== void 0) {
+		const def = findOption(select, resetTarget);
+		for (const option of select.options) {
+			const want = option === def;
+			if (option.defaultSelected !== want) option.defaultSelected = want;
+		}
+	}
+	const option = findOption(select, target);
+	if (option !== null && !option.selected) option.selected = true;
+}
+const read = (select) => ({
+	value: select.value,
+	index: select.selectedIndex
+});
+/**
+* Native-`<select>` machinery for `Select.Root` (conventions 3.8, the select analogue of
+* `useNativeChecked`), on top of `useNativeGroupReconciliation`:
+*
+* 1. Adoption (uncontrolled without `defaultValue`): at mount the browser's default becomes the
+*    committed value with no dispatch, and the mount reconciliation compares against it, so a
+*    pre-hydration pick of another option still dispatches. It is also the reset target (the
+*    value Fizz marks `selected` when it comes from a `""` option). While no dispatch has set
+*    the value, late options mounting without the state's option adopt again (loading).
+* 2. Mount reconciliation and form reset through the group adapter: one dispatch per Select, and
+*    only when the intended option exists in the DOM (a value whose option is still loading is
+*    never "reconciled" to the fallback).
+* 3. After every Root commit: the reset-target mirror, then the re-apply of the intended option.
+* 4. Late options: the same, once per commit; a hydrated late option is also reconciled, from a
+*    snapshot of the selection taken before the re-apply.
+*/
+function useNativeSelectValue(options) {
+	const { ref: elementRef } = options;
+	const ref = useMemo(() => ({ get current() {
+		const el = elementRef.current;
+		return el?.tagName === "SELECT" ? el : null;
+	} }), [elementRef]);
+	const latest = useLatest(options);
+	/**
+	* A default adopted in this layout phase. Until the adoption's render (a sync update, flushed
+	* right after this commit) the state still says the old value, so this is what the user
+	* intends unless a dispatch is in flight. Cleared in a microtask, after that render.
+	*/
+	const adopted = useRef(null);
+	const intended = (o) => {
+		const f = o.latestInFlight();
+		if (f !== null) return f.next;
+		return adopted.current ?? o.optimistic;
+	};
+	const adoptNow = (value, adopt) => {
+		adopted.current = value;
+		adopt(value);
+		queueMicrotask(() => {
+			adopted.current = null;
+		});
+	};
+	/** Adopt mode: the value adopted at mount, the reset target (as the mount value is, controlled). */
+	const mountAdopted = useRef(void 0);
+	const resetTargetOf = (o) => o.adoptDefault !== void 0 ? mountAdopted.current : o.resetTarget;
+	/** The selection read in the layout phase of a late-option commit (conventions 3.8 rule 3). */
+	const lateSnapshot = useRef(null);
+	const adoptAtMount = useEffectEvent(() => {
+		const select = ref.current;
+		const adoptDefault = options.adoptDefault;
+		if (select === null || adoptDefault === void 0 || adoptDefault.established()) return;
+		const value = implicitDefault(select);
+		mountAdopted.current = value === "" && findOption(select, "") === null ? void 0 : value;
+		adoptNow(value, adoptDefault.adopt);
+	});
+	useLayoutEffect(() => {
+		adoptAtMount();
+	}, []);
+	const { onItemMounted } = useNativeGroupReconciliation({
+		element: ref,
+		readCurrent: () => {
+			const select = ref.current;
+			const snapshot = lateSnapshot.current;
+			lateSnapshot.current = null;
+			const base = intended(latest.current);
+			if (select === null) return base;
+			const current = snapshot ?? read(select);
+			if (current.index === -1 || findOption(select, base) === null) return base;
+			return current.value;
+		},
+		readDefault: () => {
+			const select = ref.current;
+			return select === null ? intended(latest.current) : readResetValue(select);
+		},
+		base: () => intended(latest.current),
+		onPlatformChange: (next, event) => latest.current.onPlatformChange(next, event)
+	});
+	useLayoutEffect(() => {
+		const select = ref.current;
+		if (select === null) return;
+		applySelection(select, intended(options), resetTargetOf(options));
+	});
+	/** The Root's own mount effects have run: later Option mounts are late. */
+	const rootMounted = useRef(false);
+	useLayoutEffect(() => {
+		rootMounted.current = true;
+		return () => {
+			rootMounted.current = false;
+		};
+	}, []);
+	/**
+	* This commit's late options were handled (snapshot, adoption, re-apply). A microtask window,
+	* not a per-commit flag: an Option's layout effect cannot tell which commit it belongs to (the
+	* Root does not commit with a boundary that resolves inside it). A second commit in the same
+	* task is covered by the per-report re-apply below; its hydrated options are reconciled against
+	* the first commit's snapshot (theoretical: no part triggers such a commit).
+	*/
+	const lateHandled = useRef(false);
+	return { optionMounted: useCallback((el, hydrated) => {
+		if (!rootMounted.current) return;
+		const select = ref.current;
+		if (select === null) return;
+		if (!lateHandled.current) {
+			lateHandled.current = true;
+			lateSnapshot.current = read(select);
+			const current = latest.current;
+			const adoptDefault = current.adoptDefault;
+			if (adoptDefault !== void 0 && !adoptDefault.established() && current.latestInFlight() === null && findOption(select, intended(current)) === null) adoptNow(implicitDefault(select), adoptDefault.adopt);
+			applySelection(select, intended(current), resetTargetOf(current));
+			queueMicrotask(() => queueMicrotask(() => {
+				lateHandled.current = false;
+				lateSnapshot.current = null;
+			}));
+		} else if (el !== null) {
+			const current = latest.current;
+			if (el.value === intended(current) || el.value === resetTargetOf(current)) applySelection(select, intended(current), resetTargetOf(current));
+		}
+		if (hydrated) onItemMounted(el);
+	}, [
+		ref,
+		latest,
+		onItemMounted
+	]) };
+}
+//#endregion
+export { applySelection, findOption, implicitDefault, readResetValue, useNativeSelectValue };
+
+//# sourceMappingURL=use-native-select-value.mjs.map

package/dist/internal/use-native-select-value.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-native-select-value.mjs","names":[],"sources":["../../src/internal/use-native-select-value.ts"],"sourcesContent":["\"use client\";\nimport { useCallback, useEffectEvent, useLayoutEffect, useMemo, useRef } from \"react\";\nimport type { RefObject } from \"react\";\nimport { useLatest } from \"./use-latest.js\";\nimport { useNativeGroupReconciliation } from \"./use-native-group-reconciliation.js\";\n\nexport interface UseNativeSelectValueOptions {\n  /** The `<select>`. */\n  readonly ref: RefObject<HTMLSelectElement | null>;\n  /** The optimistic value (what the `<select>` renders). */\n  readonly optimistic: string;\n  /** From `useControllableAction`: the latest in-flight dispatch, if any. */\n  readonly latestInFlight: () => { readonly next: string } | null;\n  /**\n   * The value a form reset must return to, mirrored into `option.defaultSelected` after every\n   * commit: uncontrolled, the latest `defaultValue`; controlled, the Root's mount-time value.\n   * Ignored in adopt mode (`adoptDefault` set), where the target is the value adopted at mount.\n   */\n  readonly resetTarget: string | undefined;\n  /**\n   * Uncontrolled without `defaultValue` (design/components/select.md 5): adopts the browser's\n   * choice as the committed value, without a dispatch. `undefined` in every other mode.\n   */\n  readonly adoptDefault: AdoptDefault | undefined;\n  /**\n   * The browser changed the value on a residual path (pre-hydration pick, Firefox form-state\n   * restoration, a late hydrated option, a form reset) and it differs from what the user intends.\n   * `event` is the `reset` event or `undefined`. The Root dispatches once with\n   * `reason: \"platform\"`.\n   */\n  readonly onPlatformChange: (next: string, event: Event | undefined) => void;\n}\n\nexport interface AdoptDefault {\n  /** `adopt` of `useControllableAction`: writes the committed value, no action. */\n  readonly adopt: (next: string) => void;\n  /**\n   * A dispatch (a pick or a platform change) has set the value. From then on the browser's\n   * default is never adopted again: late options only get the re-apply, so options that suspend\n   * again (a keyed boundary, a refetch) and come back keep the user's value.\n   */\n  readonly established: () => boolean;\n}\n\nexport interface UseNativeSelectValueResult {\n  /**\n   * Stable. Each `Select.Option` calls it from its mount layout effect with its element and\n   * whether that render hydrated server HTML (`useHydratedMount`). Reports from the Root's own\n   * commit are ignored (the Root's effects cover them). A later report re-applies the intended\n   * option (React never selects options mounted after the select's own commit); a hydrated one\n   * is also reconciled, from a DOM snapshot taken before the re-apply.\n   */\n  readonly optionMounted: (el: HTMLOptionElement | null, hydrated: boolean) => void;\n}\n\n/** The first option whose value is `value` (react-dom's `updateOptions` selects the first). */\nexport function findOption(select: HTMLSelectElement, value: string): HTMLOptionElement | null {\n  for (const option of select.options) {\n    if (option.value === value) return option;\n  }\n  return null;\n}\n\nfunction isEnabled(option: HTMLOptionElement): boolean {\n  if (option.disabled) return false;\n  const parent = option.parentElement;\n  return !(parent?.tagName === \"OPTGROUP\" && (parent as HTMLOptGroupElement).disabled);\n}\n\nfunction firstEnabled(select: HTMLSelectElement): string {\n  for (const option of select.options) {\n    if (isEnabled(option)) return option.value;\n  }\n  return \"\";\n}\n\n/**\n * The spec's reset result for a single select: the last option whose `defaultSelected` is true,\n * else the first enabled option, else `\"\"` (nothing selected).\n */\nexport function readResetValue(select: HTMLSelectElement): string {\n  let last: HTMLOptionElement | null = null;\n  for (const option of select.options) {\n    if (option.defaultSelected) last = option;\n  }\n  return last !== null ? last.value : firstEnabled(select);\n}\n\n/**\n * The option a `<select>` rendered with the value `\"\"` selects: an option whose value is `\"\"`\n * (react-dom's `updateOptions(\"\")` and Fizz's `selected` attribute both pick it, even when it is\n * disabled), else the first enabled option (the selectedness setting algorithm), else `\"\"`.\n */\nexport function implicitDefault(select: HTMLSelectElement): string {\n  return findOption(select, \"\") !== null ? \"\" : firstEnabled(select);\n}\n\n/**\n * The reset-target mirror followed by the re-apply, in one synchronous step\n * (design/components/select.md 6.1). Writing `defaultSelected = true` on an option whose\n * dirtiness is false selects it, so the intended option is re-selected right after. Writes only\n * what differs: the common commit writes nothing.\n */\nexport function applySelection(\n  select: HTMLSelectElement,\n  target: string,\n  resetTarget: string | undefined,\n): void {\n  if (resetTarget !== undefined) {\n    // Only the first match, the option react-dom would select for that value.\n    const def = findOption(select, resetTarget);\n    for (const option of select.options) {\n      const want = option === def;\n      if (option.defaultSelected !== want) option.defaultSelected = want;\n    }\n  }\n  const option = findOption(select, target);\n  if (option !== null && !option.selected) option.selected = true;\n}\n\ninterface Snapshot {\n  readonly value: string;\n  readonly index: number;\n}\n\nconst read = (select: HTMLSelectElement): Snapshot => ({\n  value: select.value,\n  index: select.selectedIndex,\n});\n\n/**\n * Native-`<select>` machinery for `Select.Root` (conventions 3.8, the select analogue of\n * `useNativeChecked`), on top of `useNativeGroupReconciliation`:\n *\n * 1. Adoption (uncontrolled without `defaultValue`): at mount the browser's default becomes the\n *    committed value with no dispatch, and the mount reconciliation compares against it, so a\n *    pre-hydration pick of another option still dispatches. It is also the reset target (the\n *    value Fizz marks `selected` when it comes from a `\"\"` option). While no dispatch has set\n *    the value, late options mounting without the state's option adopt again (loading).\n * 2. Mount reconciliation and form reset through the group adapter: one dispatch per Select, and\n *    only when the intended option exists in the DOM (a value whose option is still loading is\n *    never \"reconciled\" to the fallback).\n * 3. After every Root commit: the reset-target mirror, then the re-apply of the intended option.\n * 4. Late options: the same, once per commit; a hydrated late option is also reconciled, from a\n *    snapshot of the selection taken before the re-apply.\n */\nexport function useNativeSelectValue(\n  options: UseNativeSelectValueOptions,\n): UseNativeSelectValueResult {\n  const { ref: elementRef } = options;\n  // A `render` element that is not a <select> (dev warning in the Root) gets no DOM work.\n  const ref = useMemo(\n    () => ({\n      get current(): HTMLSelectElement | null {\n        const el = elementRef.current;\n        // Tag, not `instanceof`: the element may come from another realm (an iframe).\n        return el?.tagName === \"SELECT\" ? (el as HTMLSelectElement) : null;\n      },\n    }),\n    [elementRef],\n  );\n\n  // The latest committed options. Written in the mutation phase (`useLatest`), so an Option's\n  // mount layout effect, which runs before this Root's layout effects, already reads this commit's.\n  const latest = useLatest(options);\n\n  /**\n   * A default adopted in this layout phase. Until the adoption's render (a sync update, flushed\n   * right after this commit) the state still says the old value, so this is what the user\n   * intends unless a dispatch is in flight. Cleared in a microtask, after that render.\n   */\n  const adopted = useRef<string | null>(null);\n  const intended = (o: UseNativeSelectValueOptions): string => {\n    const f = o.latestInFlight();\n    if (f !== null) return f.next;\n    return adopted.current ?? o.optimistic;\n  };\n\n  const adoptNow = (value: string, adopt: (next: string) => void) => {\n    adopted.current = value;\n    adopt(value);\n    queueMicrotask(() => {\n      adopted.current = null;\n    });\n  };\n\n  /** Adopt mode: the value adopted at mount, the reset target (as the mount value is, controlled). */\n  const mountAdopted = useRef<string | undefined>(undefined);\n  const resetTargetOf = (o: UseNativeSelectValueOptions): string | undefined =>\n    o.adoptDefault !== undefined ? mountAdopted.current : o.resetTarget;\n\n  /** The selection read in the layout phase of a late-option commit (conventions 3.8 rule 3). */\n  const lateSnapshot = useRef<Snapshot | null>(null);\n\n  // 1. Adoption at mount. Declared before the adapter so that its mount reconciliation compares\n  //    the DOM against the adopted default.\n  const adoptAtMount = useEffectEvent(() => {\n    const select = ref.current;\n    const adoptDefault = options.adoptDefault;\n    // `established`: StrictMode's re-run after a mount reconciliation already dispatched.\n    if (select === null || adoptDefault === undefined || adoptDefault.established()) return;\n    const value = implicitDefault(select);\n    // `\"\"` from a select with nothing selectable is no reset target (design 6.1): only a `\"\"`\n    // option, the placeholder react-dom and Fizz select, is mirrored.\n    mountAdopted.current = value === \"\" && findOption(select, \"\") === null ? undefined : value;\n    adoptNow(value, adoptDefault.adopt);\n  });\n  useLayoutEffect(() => {\n    adoptAtMount();\n  }, []);\n\n  // 2. Residual paths: one dispatch per Select.\n  const { onItemMounted } = useNativeGroupReconciliation<string>({\n    element: ref,\n    readCurrent: () => {\n      const select = ref.current;\n      const snapshot = lateSnapshot.current;\n      lateSnapshot.current = null;\n      const base = intended(latest.current);\n      if (select === null) return base;\n      const current = snapshot ?? read(select);\n      // The dispatch gate: nothing selected, or the intended option absent, is not a pick.\n      if (current.index === -1 || findOption(select, base) === null) return base;\n      return current.value;\n    },\n    readDefault: () => {\n      const select = ref.current;\n      return select === null ? intended(latest.current) : readResetValue(select);\n    },\n    base: () => intended(latest.current),\n    onPlatformChange: (next, event) => latest.current.onPlatformChange(next, event),\n  });\n\n  // 3. After every commit. Declared after the adapter, so the mount commit's DOM is read by the\n  //    mount reconciliation before anything is re-applied.\n  useLayoutEffect(() => {\n    const select = ref.current;\n    if (select === null) return;\n    applySelection(select, intended(options), resetTargetOf(options));\n  });\n\n  /** The Root's own mount effects have run: later Option mounts are late. */\n  const rootMounted = useRef(false);\n  useLayoutEffect(() => {\n    rootMounted.current = true;\n    return () => {\n      rootMounted.current = false;\n    };\n  }, []);\n  /**\n   * This commit's late options were handled (snapshot, adoption, re-apply). A microtask window,\n   * not a per-commit flag: an Option's layout effect cannot tell which commit it belongs to (the\n   * Root does not commit with a boundary that resolves inside it). A second commit in the same\n   * task is covered by the per-report re-apply below; its hydrated options are reconciled against\n   * the first commit's snapshot (theoretical: no part triggers such a commit).\n   */\n  const lateHandled = useRef(false);\n\n  // 4. Late options.\n  const optionMounted = useCallback(\n    (el: HTMLOptionElement | null, hydrated: boolean) => {\n      if (!rootMounted.current) return;\n      const select = ref.current;\n      if (select === null) return;\n      if (!lateHandled.current) {\n        lateHandled.current = true;\n        // Every option of this commit is in the DOM already (the mutation phase precedes layout).\n        lateSnapshot.current = read(select);\n        const current = latest.current;\n        const adoptDefault = current.adoptDefault;\n        if (\n          adoptDefault !== undefined &&\n          !adoptDefault.established() &&\n          current.latestInFlight() === null &&\n          findOption(select, intended(current)) === null\n        ) {\n          // Still loading and nothing chosen yet (the fallback-only case): adopt the browser's\n          // default. Never after a dispatch: that would overwrite the user's value silently.\n          adoptNow(implicitDefault(select), adoptDefault.adopt);\n        }\n        applySelection(select, intended(current), resetTargetOf(current));\n        // Cleared after the adapter's microtask, which a later report of this same commit may\n        // queue after this point: two hops keep the snapshot for it.\n        queueMicrotask(() =>\n          queueMicrotask(() => {\n            lateHandled.current = false;\n            lateSnapshot.current = null;\n          }),\n        );\n      } else if (el !== null) {\n        // Per report, for an option that matters (cheap: at most the intended and the reset\n        // target's options): a second commit within the window gets its re-apply too.\n        const current = latest.current;\n        if (el.value === intended(current) || el.value === resetTargetOf(current)) {\n          applySelection(select, intended(current), resetTargetOf(current));\n        }\n      }\n      if (hydrated) onItemMounted(el);\n    },\n    [ref, latest, onItemMounted],\n  );\n\n  return { optionMounted };\n}\n"],"mappings":"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"}

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

@@ -1,6 +1,7 @@
 "use client";
+import { useContentFocusProbe } from "./content-focus-probe.mjs";
 import { exitAnimations, useExitAnimation } from "./use-exit-animation.mjs";
-import { createElement, useCallback, useEffect, useEffectEvent, useInsertionEffect, useLayoutEffect, useRef, useState } from "react";
+import { 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) {
@@ -42,15 +43,6 @@ function insideHiddenPopover(element) {
 	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
@@ -64,7 +56,6 @@ function usePopoverPopup(ctx, options) {
 	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);
@@ -72,13 +63,8 @@ function usePopoverPopup(ctx, options) {
 		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 contentProbe = useContentFocusProbe(popupRef);
+	const { wrapContent } = contentProbe;
 	const syncExpanded = (element) => {
 		triggerRef.current?.setAttribute("aria-expanded", String(isPopoverOpen(element)));
 	};
@@ -153,7 +139,7 @@ function usePopoverPopup(ctx, options) {
 				if (focusWasInside.current) returnFocus(element);
 			}
 		}
-		if (ctx.committed && isPopoverOpen(element)) contentHadFocus.current = false;
+		if (ctx.committed && isPopoverOpen(element)) contentProbe.forget();
 		if (exit.held && !ctx.committed && !exit.waiting() && !awaitingClose.current && !isPopoverOpen(element)) exit.release();
 	});
 	const onBeforeToggle = (event) => {
@@ -165,12 +151,12 @@ function usePopoverPopup(ctx, options) {
 				event.preventDefault();
 				ctx.requestOpen(event, "activate");
 			} else ctx.nextOpenGeneration();
-			contentHadFocus.current = false;
+			contentProbe.forget();
 		} else {
 			awaitingClose.current = true;
 			const active = element.ownerDocument.activeElement;
-			focusWasInside.current = active !== null && element.contains(active) || contentHadFocus.current;
-			contentHadFocus.current = false;
+			focusWasInside.current = active !== null && element.contains(active) || contentProbe.hadFocus();
+			contentProbe.forget();
 		}
 		onBeforeToggleOption?.(toggle);
 	};

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

@@ -1 +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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"}
+{"version":3,"file":"use-popover-popup.mjs","names":[],"sources":["../../src/internal/use-popover-popup.ts"],"sourcesContent":["\"use client\";\nimport {\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 { useContentFocusProbe } from \"./content-focus-probe.js\";\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 * 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  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  // Whether the content unmounted while holding focus since the popup was last shown (H1).\n  const contentProbe = useContentFocusProbe(popupRef);\n  const { wrapContent } = contentProbe;\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 that re-renders the Popup, once nothing is\n  // in flight, the DOM follows committed state. Since the Root's value is memoised (#48) an\n  // unrelated Root render does not re-render the Popup, so this does not run for it; every path\n  // that makes the DOM diverge from state goes through a dispatch, whose `pending` flips re-render\n  // the Popup (review of #48, finding 4). Do not rely on an unrelated render to re-apply state.\n  // 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)) contentProbe.forget();\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      contentProbe.forget();\n    } else {\n      awaitingClose.current = true;\n      const active = element.ownerDocument.activeElement;\n      focusWasInside.current =\n        (active !== null && element.contains(active)) || contentProbe.hadFocus();\n      contentProbe.forget();\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.mjs

@@ -1,9 +1,10 @@
 "use client";
 import { createActionDetails } from "./action-details.mjs";
 import { transitionTypes } from "./transition-types.mjs";
+import { useLatest } from "./use-latest.mjs";
 import { useControllableAction } from "./use-controllable-action.mjs";
 import { useDevWarning } from "./use-dev-warning.mjs";
-import { useCallback, useId, useInsertionEffect, useRef, useState } from "react";
+import { useCallback, useId, useMemo, useRef, useState } from "react";
 //#region src/internal/use-popover-root.ts
 function isPopoverOpen(element) {
 	if (element === null) return false;
@@ -45,10 +46,7 @@ function usePopoverRoot(options) {
 	const triggerRef = useRef(null);
 	const popupRef = useRef(null);
 	const closeIntent = useRef(void 0);
-	const committedOptimistic = useRef(optimistic);
-	useInsertionEffect(() => {
-		committedOptimistic.current = optimistic;
-	});
+	const committedOptimistic = useLatest(optimistic);
 	const generation = useRef(0);
 	const openGeneration = useCallback(() => generation.current, []);
 	const nextOpenGeneration = useCallback(() => {
@@ -63,33 +61,54 @@ function usePopoverRoot(options) {
 		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);
+	const intended = useCallback(() => latestInFlight()?.next ?? committedOptimistic.current, [latestInFlight, committedOptimistic]);
+	const callbacks = useLatest({
+		details,
+		onDispatch
+	});
+	const send = useCallback((next, event, reason) => {
+		const { details, onDispatch } = callbacks.current;
+		const built = details !== void 0 ? details(event, reason) : createActionDetails(event, { reason });
 		if (next) nextOpenGeneration();
 		onDispatch?.(next, built);
 		dispatch(next, built);
-	};
-	const requestOpen = (event, reason) => {
+	}, [
+		callbacks,
+		nextOpenGeneration,
+		dispatch
+	]);
+	const requestOpen = useCallback((event, reason) => {
 		if (!isLibrary || intended()) return;
 		send(true, event, reason);
-	};
-	const requestClose = (event, reason) => {
+	}, [
+		isLibrary,
+		intended,
+		send
+	]);
+	const requestClose = useCallback((event, reason) => {
 		if (!isLibrary || !intended()) return;
 		send(false, event, reason);
-	};
-	const notifyClosed = (event, reason) => {
+	}, [
+		isLibrary,
+		intended,
+		send
+	]);
+	const notifyClosed = useCallback((event, reason) => {
 		if (!isLibrary || !intended()) return;
 		send(false, event, reason);
-	};
-	return {
+	}, [
+		isLibrary,
+		intended,
+		send
+	]);
+	const ids = useMemo(() => ({
+		popup: id,
+		title: `${id}-title`,
+		description: `${id}-description`
+	}), [id]);
+	return useMemo(() => ({
 		mode,
-		ids: {
-			popup: id,
-			title: `${id}-title`,
-			description: `${id}-description`
-		},
+		ids,
 		committed: isLibrary && committed,
 		optimistic: isLibrary && optimistic,
 		pending: isLibrary && pending,
@@ -104,7 +123,23 @@ function usePopoverRoot(options) {
 		popupRef,
 		recordCloseIntent,
 		takeCloseIntent
-	};
+	}), [
+		mode,
+		ids,
+		isLibrary,
+		committed,
+		optimistic,
+		pending,
+		intended,
+		openGeneration,
+		nextOpenGeneration,
+		requestOpen,
+		requestClose,
+		notifyClosed,
+		latestInFlight,
+		recordCloseIntent,
+		takeCloseIntent
+	]);
 }
 //#endregion
 export { usePopoverRoot };

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

@@ -1 +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"}
+{"version":3,"file":"use-popover-root.mjs","names":[],"sources":["../../src/internal/use-popover-root.ts"],"sourcesContent":["\"use client\";\nimport { useCallback, useId, useMemo, 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\";\nimport { useLatest } from \"./use-latest.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 = useLatest(optimistic);\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 = useCallback(\n    (): boolean => latestInFlight()?.next ?? committedOptimistic.current,\n    [latestInFlight, committedOptimistic],\n  );\n\n  // `details` and `onDispatch` are usually inline functions: read the committed render's through a\n  // ref so that the functions below, and with them the returned value, stay stable (#48).\n  const callbacks = useLatest({ details, onDispatch });\n\n  const send = useCallback(\n    (next: boolean, event: Event | undefined, reason: ChangeReason): void => {\n      const { details, onDispatch } = callbacks.current;\n      const built =\n        details !== undefined\n          ? details(event, reason)\n          : (createActionDetails(event, { reason }) as unknown as Details);\n      if (next) nextOpenGeneration();\n      onDispatch?.(next, built);\n      dispatch(next, built);\n    },\n    [callbacks, nextOpenGeneration, dispatch],\n  );\n\n  const requestOpen = useCallback(\n    (event: Event | undefined, reason: ChangeReason): void => {\n      if (!isLibrary || intended()) return;\n      send(true, event, reason);\n    },\n    [isLibrary, intended, send],\n  );\n\n  const requestClose = useCallback(\n    (event: Event | undefined, reason: ChangeReason): void => {\n      if (!isLibrary || !intended()) return;\n      send(false, event, reason);\n    },\n    [isLibrary, intended, send],\n  );\n\n  // Same guard as `requestClose`; a separate name because the callers mean different things.\n  const notifyClosed = useCallback(\n    (event: Event | undefined, reason: ChangeReason): void => {\n      if (!isLibrary || !intended()) return;\n      send(false, event, reason);\n    },\n    [isLibrary, intended, send],\n  );\n\n  const ids = useMemo(\n    () => ({ popup: id, title: `${id}-title`, description: `${id}-description` }),\n    [id],\n  );\n\n  // Memoised: every function above is stable, so the value changes only with the open state and\n  // pending, and the components' context values built on it are reused otherwise (#48).\n  return useMemo(\n    () => ({\n      mode,\n      ids,\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      mode,\n      ids,\n      isLibrary,\n      committed,\n      optimistic,\n      pending,\n      intended,\n      openGeneration,\n      nextOpenGeneration,\n      requestOpen,\n      requestClose,\n      notifyClosed,\n      latestInFlight,\n      recordCloseIntent,\n      takeCloseIntent,\n    ],\n  );\n}\n"],"mappings":"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"}