@funstack/ui 0.1.0-alpha.2 → 0.1.0-alpha.4

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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"}

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

@@ -1,6 +1,6 @@
 "use client";
 import { dataAttr } from "./data-attr.mjs";
-import { rendersButton } from "./use-render.mjs";
+import { rendersButton } from "./render-element.mjs";
 import { useCallback } from "react";
 //#region src/internal/use-popover-trigger.ts
 const isDev = process.env.NODE_ENV !== "production";

package/dist/internal/use-render.mjs

@@ -1,49 +1,26 @@
 "use client";
-import { mergeProps, mergeRefs } from "./merge-props.mjs";
-import { cloneElement, createElement, isValidElement, useMemo } from "react";
+import { mergeRefs } from "./merge-props.mjs";
+import { renderElement, rendersButton, resolveStateValue } from "./render-element.mjs";
+import { isValidElement, useMemo } from "react";
 //#region src/internal/use-render.tsx
-function resolveStateValue(value, state) {
-	return typeof value === "function" ? value(state) : value;
-}
-/**
-* Whether a part whose default element is a `<button>` should add `type="button"`: no `render`,
-* a `render` element whose type is the intrinsic `"button"`, or the function form (it receives
-* button props and decides itself what to spread). An element of any other type (an `<a>`, a
-* router `Link`) does not get it: `type` means something else, or nothing, there.
-*/
-function rendersButton(render) {
-	if (render === void 0 || typeof render === "function") return true;
-	return isValidElement(render) && render.type === "button";
-}
 /**
 * Resolves `render` and the function-form `className` / `style` / `children` of a part against
-* its state and produces the element (conventions 1.2, 1.3, 1.4).
+* its state and produces the element (conventions 1.2, 1.3, 1.4). The pure work is
+* `renderElement` (`render-element.ts`); this hook adds the memoised ref merge.
 */
 function useRender(options) {
-	const { defaultElement, render, state, className, style, children, props, libraryProps, ref } = options;
+	const { render, props, ref } = options;
 	const consumerRef = props.ref;
-	const renderElement = isValidElement(render) ? render : void 0;
-	const elementRef = renderElement?.props.ref;
+	const elementRef = isValidElement(render) ? render.props.ref : void 0;
 	const mergedRef = useMemo(() => mergeRefs(ref, consumerRef, elementRef), [
 		ref,
 		consumerRef,
 		elementRef
 	]);
-	const partProps = {
-		...props,
-		ref: mergedRef,
-		className: resolveStateValue(className, state),
-		style: resolveStateValue(style, state),
-		children: resolveStateValue(children, state)
-	};
-	const controlled = libraryProps ?? {};
-	if (renderElement !== void 0) {
-		const { ref: _ignored, ...elementProps } = renderElement.props;
-		return cloneElement(renderElement, mergeProps(partProps, elementProps, controlled));
-	}
-	const resolved = mergeProps(partProps, {}, controlled);
-	if (typeof render === "function") return render(resolved, state);
-	return createElement(defaultElement, resolved);
+	return renderElement({
+		...options,
+		ref: mergedRef
+	});
 }
 //#endregion
 export { rendersButton, resolveStateValue, useRender };

package/dist/internal/use-render.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-render.mjs","names":[],"sources":["../../src/internal/use-render.tsx"],"sourcesContent":["\"use client\";\nimport { cloneElement, createElement, isValidElement, useMemo } from \"react\";\nimport type { CSSProperties, ReactNode, Ref } from \"react\";\nimport { mergeProps, mergeRefs } from \"./merge-props.js\";\nimport type { RenderProp, StateValue } from \"./types.js\";\n\ninterface ElementLikeProps {\n  className?: string | undefined;\n  style?: CSSProperties | undefined;\n  children?: ReactNode;\n  ref?: Ref<unknown> | undefined;\n}\n\n/** `data-*` attributes are valid JSX but absent from the element prop types. */\nexport type DataAttributes = { [key: `data-${string}`]: string | undefined };\n\nexport interface UseRenderOptions<Props extends ElementLikeProps, State> {\n  /** Intrinsic element rendered when `render` is not given. */\n  defaultElement: string;\n  render: RenderProp<Props, State> | undefined;\n  state: State;\n  className: StateValue<string | undefined, State> | undefined;\n  style: StateValue<CSSProperties | undefined, State> | undefined;\n  children: StateValue<ReactNode, State> | undefined;\n  /** The part's pass-through props for the element. A `render` element's own props win over these. */\n  props: Omit<Props, \"className\" | \"style\" | \"children\"> & DataAttributes;\n  /**\n   * Library-controlled attributes the part computes (`role`, `aria-*` state, id wiring, `data-*`\n   * state, the library's own event handlers). These win over a `render` element's props\n   * (conventions 1.2).\n   */\n  libraryProps?: Partial<Omit<Props, \"className\" | \"style\" | \"children\">> & DataAttributes;\n  /** The library's own ref, if the part needs the DOM node. */\n  ref?: Ref<unknown> | undefined;\n}\n\nexport function resolveStateValue<T, State>(value: StateValue<T, State>, state: State): T {\n  return typeof value === \"function\" ? (value as (state: State) => T)(state) : value;\n}\n\n/**\n * Whether a part whose default element is a `<button>` should add `type=\"button\"`: no `render`,\n * a `render` element whose type is the intrinsic `\"button\"`, or the function form (it receives\n * button props and decides itself what to spread). An element of any other type (an `<a>`, a\n * router `Link`) does not get it: `type` means something else, or nothing, there.\n */\nexport function rendersButton<Props, State>(render: RenderProp<Props, State> | undefined): boolean {\n  if (render === undefined || typeof render === \"function\") return true;\n  return isValidElement(render) && render.type === \"button\";\n}\n\n/**\n * Resolves `render` and the function-form `className` / `style` / `children` of a part against\n * its state and produces the element (conventions 1.2, 1.3, 1.4).\n */\nexport function useRender<Props extends ElementLikeProps, State>(\n  options: UseRenderOptions<Props, State>,\n): ReactNode {\n  const { defaultElement, render, state, className, style, children, props, libraryProps, ref } =\n    options;\n\n  const consumerRef = (props as ElementLikeProps).ref;\n  const renderElement = isValidElement<ElementLikeProps>(render) ? render : undefined;\n  const elementRef = renderElement?.props.ref;\n  // Memoised so that the callback ref keeps its identity across renders and React does not\n  // detach and re-attach the node every time.\n  const mergedRef = useMemo(\n    () => mergeRefs(ref, consumerRef, elementRef),\n    [ref, consumerRef, elementRef],\n  );\n\n  const partProps = {\n    ...props,\n    ref: mergedRef,\n    className: resolveStateValue(className, state),\n    style: resolveStateValue(style, state),\n    children: resolveStateValue(children, state),\n  } as Record<string, unknown>;\n  const controlled = (libraryProps ?? {}) as Record<string, unknown>;\n\n  if (renderElement !== undefined) {\n    // The element's ref is already part of `mergedRef`.\n    const { ref: _ignored, ...elementProps } = renderElement.props as Record<string, unknown>;\n    return cloneElement(\n      renderElement,\n      mergeProps(partProps, elementProps, controlled) as Partial<Props>,\n    );\n  }\n  const resolved = mergeProps(partProps, {}, controlled) as unknown as Props;\n  if (typeof render === \"function\") {\n    return render(resolved, state);\n  }\n  return createElement(defaultElement, resolved);\n}\n"],"mappings":";;;;AAoCA,SAAgB,kBAA4B,OAA6B,OAAiB;CACxF,OAAO,OAAO,UAAU,aAAc,MAA8B,KAAK,IAAI;AAC/E;;;;;;;AAQA,SAAgB,cAA4B,QAAuD;CACjG,IAAI,WAAW,KAAA,KAAa,OAAO,WAAW,YAAY,OAAO;CACjE,OAAO,eAAe,MAAM,KAAK,OAAO,SAAS;AACnD;;;;;AAMA,SAAgB,UACd,SACW;CACX,MAAM,EAAE,gBAAgB,QAAQ,OAAO,WAAW,OAAO,UAAU,OAAO,cAAc,QACtF;CAEF,MAAM,cAAe,MAA2B;CAChD,MAAM,gBAAgB,eAAiC,MAAM,IAAI,SAAS,KAAA;CAC1E,MAAM,aAAa,eAAe,MAAM;CAGxC,MAAM,YAAY,cACV,UAAU,KAAK,aAAa,UAAU,GAC5C;EAAC;EAAK;EAAa;CAAU,CAC/B;CAEA,MAAM,YAAY;EAChB,GAAG;EACH,KAAK;EACL,WAAW,kBAAkB,WAAW,KAAK;EAC7C,OAAO,kBAAkB,OAAO,KAAK;EACrC,UAAU,kBAAkB,UAAU,KAAK;CAC7C;CACA,MAAM,aAAc,gBAAgB,CAAC;CAErC,IAAI,kBAAkB,KAAA,GAAW;EAE/B,MAAM,EAAE,KAAK,UAAU,GAAG,iBAAiB,cAAc;EACzD,OAAO,aACL,eACA,WAAW,WAAW,cAAc,UAAU,CAChD;CACF;CACA,MAAM,WAAW,WAAW,WAAW,CAAC,GAAG,UAAU;CACrD,IAAI,OAAO,WAAW,YACpB,OAAO,OAAO,UAAU,KAAK;CAE/B,OAAO,cAAc,gBAAgB,QAAQ;AAC/C"}
+{"version":3,"file":"use-render.mjs","names":[],"sources":["../../src/internal/use-render.tsx"],"sourcesContent":["\"use client\";\nimport { isValidElement, useMemo } from \"react\";\nimport type { ReactNode, Ref } from \"react\";\nimport { mergeRefs } from \"./merge-props.js\";\nimport { renderElement } from \"./render-element.js\";\nimport type { ElementLikeProps, RenderElementOptions } from \"./render-element.js\";\n\nexport { rendersButton, resolveStateValue } from \"./render-element.js\";\nexport type { DataAttributes } from \"./render-element.js\";\n\nexport interface UseRenderOptions<Props extends ElementLikeProps, State> extends Omit<\n  RenderElementOptions<Props, State>,\n  \"ref\"\n> {\n  /** The library's own ref, if the part needs the DOM node. */\n  ref?: Ref<unknown> | undefined;\n}\n\n/**\n * Resolves `render` and the function-form `className` / `style` / `children` of a part against\n * its state and produces the element (conventions 1.2, 1.3, 1.4). The pure work is\n * `renderElement` (`render-element.ts`); this hook adds the memoised ref merge.\n */\nexport function useRender<Props extends ElementLikeProps, State>(\n  options: UseRenderOptions<Props, State>,\n): ReactNode {\n  const { render, props, ref } = options;\n\n  const consumerRef = (props as ElementLikeProps).ref;\n  const elementRef = isValidElement<ElementLikeProps>(render) ? render.props.ref : undefined;\n  // Memoised so that the callback ref keeps its identity across renders and React does not\n  // detach and re-attach the node every time.\n  const mergedRef = useMemo(\n    () => mergeRefs(ref, consumerRef, elementRef),\n    [ref, consumerRef, elementRef],\n  );\n\n  return renderElement<Props, State>({ ...options, ref: mergedRef });\n}\n"],"mappings":";;;;;;;;;;AAuBA,SAAgB,UACd,SACW;CACX,MAAM,EAAE,QAAQ,OAAO,QAAQ;CAE/B,MAAM,cAAe,MAA2B;CAChD,MAAM,aAAa,eAAiC,MAAM,IAAI,OAAO,MAAM,MAAM,KAAA;CAGjF,MAAM,YAAY,cACV,UAAU,KAAK,aAAa,UAAU,GAC5C;EAAC;EAAK;EAAa;CAAU,CAC/B;CAEA,OAAO,cAA4B;EAAE,GAAG;EAAS,KAAK;CAAU,CAAC;AACnE"}

package/dist/internal/use-roving-focus.mjs

@@ -0,0 +1,255 @@
+"use client";
+import { useEffect, useInsertionEffect, useLayoutEffect, useState } from "react";
+//#region src/internal/use-roving-focus.ts
+const FOCUSABLE = [
+	"button",
+	"a[href]",
+	"input:not([type=\"hidden\"])",
+	"select",
+	"textarea",
+	"summary",
+	"[contenteditable]:not([contenteditable=\"false\"])",
+	"[tabindex]"
+].join(",");
+function isVisible(el) {
+	if (typeof el.checkVisibility === "function") return el.checkVisibility();
+	return el.closest("[hidden]") === null;
+}
+/**
+* Whether `el` or an ancestor below `root` takes it out of `root`'s sequence: a nested toolbar
+* (its own sequence), a popover or a dialog rendered inside the container (a `Menu.Popup`'s items
+* are the menu's).
+*/
+function isNestedOut(el, root) {
+	for (let node = el; node !== null && node !== root; node = node.parentElement) if (node.getAttribute("role") === "toolbar" || node.hasAttribute("popover") || node.tagName === "DIALOG") return true;
+	return false;
+}
+/**
+* The items of `root` in DOM order (design 6.2): its focusable descendants minus `:disabled`,
+* `inert`, invisible, nested-toolbar / popover / dialog content, and elements whose own
+* `tabindex="-1"` was not written by this engine (`managed`). `aria-disabled` elements are items.
+*/
+function itemsOf(root, managed) {
+	const items = [];
+	for (const el of root.querySelectorAll(FOCUSABLE)) {
+		if (el.matches(":disabled")) continue;
+		if (el.closest("[inert]") !== null) continue;
+		if (el.getAttribute("tabindex") === "-1" && !managed.has(el)) continue;
+		if (isNestedOut(el, root)) continue;
+		if (!isVisible(el)) continue;
+		items.push(el);
+	}
+	return items;
+}
+const BUTTON_LIKE_INPUTS = /* @__PURE__ */ new Set([
+	"button",
+	"submit",
+	"reset",
+	"checkbox",
+	"radio",
+	"image",
+	"color",
+	"file"
+]);
+const ARROW_OWNING_ROLES = /* @__PURE__ */ new Set([
+	"textbox",
+	"combobox",
+	"spinbutton",
+	"slider"
+]);
+/**
+* An item that owns the arrow keys (design 6.3): text-like `input`s, `textarea`, `select`,
+* `[contenteditable]`, and `role` `textbox` / `combobox` / `spinbutton` / `slider`.
+*/
+function isTextEntryItem(el) {
+	const role = el.getAttribute("role");
+	if (role !== null && ARROW_OWNING_ROLES.has(role)) return true;
+	if (el instanceof HTMLInputElement) return !BUTTON_LIKE_INPUTS.has(el.type);
+	if (el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) return true;
+	const editable = el.getAttribute("contenteditable");
+	if (editable !== null && editable !== "false") return true;
+	return el instanceof HTMLElement && el.isContentEditable === true;
+}
+function resolveKey(key, orientation, rtl) {
+	switch (key) {
+		case "Home": return "first";
+		case "End": return "last";
+		case "ArrowRight": return orientation === "horizontal" ? rtl ? "prev" : "next" : null;
+		case "ArrowLeft": return orientation === "horizontal" ? rtl ? "next" : "prev" : null;
+		case "ArrowDown": return orientation === "vertical" ? "next" : null;
+		case "ArrowUp": return orientation === "vertical" ? "prev" : null;
+		default: return null;
+	}
+}
+function focusItem(item) {
+	item.focus({ focusVisible: true });
+}
+function createEngine() {
+	let current = null;
+	let latestOptions = null;
+	/**
+	* Elements this engine wrote `tabindex` on, with the attribute value they had before the first
+	* write (`null`: none). Restored when the engine lets go of an element (native path, element
+	* left the container): React does not re-write a `tabIndex` prop it believes it rendered, so a
+	* `[tabindex="0"]` widget would otherwise become unreachable.
+	*/
+	const managed = /* @__PURE__ */ new Map();
+	const restore = (el) => {
+		const original = managed.get(el);
+		managed.delete(el);
+		if (!el.isConnected || original === void 0) return;
+		if (original === null) el.removeAttribute("tabindex");
+		else el.setAttribute("tabindex", original);
+	};
+	const active = (options) => options !== null && options.enabled !== false;
+	/** Native path: give back every `tabindex` this engine wrote (a hydration render may have). */
+	const release = () => {
+		for (const el of [...managed.keys()]) restore(el);
+		current = null;
+	};
+	const apply = (root, focused) => {
+		const options = latestOptions;
+		if (root === null || !active(options)) return;
+		if (options.native) {
+			release();
+			return;
+		}
+		const items = itemsOf(root, managed);
+		if (!options.memory) current = focused instanceof HTMLElement && items.includes(focused) ? focused : options.entry(items) ?? null;
+		else if (current === null || !items.includes(current)) current = options.entry(items) ?? null;
+		for (const el of items) {
+			if (!managed.has(el)) managed.set(el, el.getAttribute("tabindex"));
+			const want = el === current ? "0" : "-1";
+			if (el.getAttribute("tabindex") !== want) el.setAttribute("tabindex", want);
+		}
+		for (const el of [...managed.keys()]) {
+			if (items.includes(el)) continue;
+			if (!root.contains(el)) restore(el);
+			else if (el.getAttribute("tabindex") !== "-1") el.setAttribute("tabindex", "-1");
+		}
+	};
+	const onFocus = (event) => {
+		const options = latestOptions;
+		if (!active(options) || options.native) return;
+		const target = event.target;
+		if (!(target instanceof HTMLElement)) return;
+		if (!itemsOf(event.currentTarget, managed).includes(target)) return;
+		current = target;
+		apply(event.currentTarget, target);
+	};
+	const onBlur = (event) => {
+		const options = latestOptions;
+		if (!active(options) || options.native || options.memory) return;
+		const next = event.relatedTarget;
+		if (next instanceof Node && event.currentTarget.contains(next)) return;
+		apply(event.currentTarget, null);
+	};
+	const onPointerDown = (event) => {
+		const options = latestOptions;
+		if (!active(options) || options.native) return;
+		const target = event.target;
+		if (!(target instanceof Node)) return;
+		const item = itemsOf(event.currentTarget, managed).find((el) => el.contains(target));
+		if (item === void 0) return;
+		current = item;
+		apply(event.currentTarget, options.memory ? item : event.currentTarget.ownerDocument.activeElement);
+	};
+	const onKeyDown = (event) => {
+		if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return;
+		const options = latestOptions;
+		if (!active(options) || options.native) return;
+		const root = event.currentTarget;
+		const target = event.target;
+		if (!(target instanceof HTMLElement)) return;
+		const items = itemsOf(root, managed);
+		const index = items.indexOf(target);
+		if (index < 0) return;
+		if (isTextEntryItem(target)) {
+			if (event.key !== "Tab") return;
+			const next = items[index + (event.shiftKey ? -1 : 1)];
+			if (next === void 0) return;
+			event.preventDefault();
+			focusItem(next);
+			return;
+		}
+		const rtl = options.orientation === "horizontal" && getComputedStyle(root).direction === "rtl";
+		const move = resolveKey(event.key, options.orientation, rtl);
+		if (move === null) return;
+		event.preventDefault();
+		const last = items.length - 1;
+		let nextIndex;
+		switch (move) {
+			case "first":
+				nextIndex = 0;
+				break;
+			case "last":
+				nextIndex = last;
+				break;
+			case "next":
+				nextIndex = index >= last ? options.loop ? 0 : last : index + 1;
+				break;
+			case "prev": nextIndex = index <= 0 ? options.loop ? last : 0 : index - 1;
+		}
+		const next = items[nextIndex];
+		if (next !== void 0 && next !== target) focusItem(next);
+	};
+	return {
+		setOptions: (options) => {
+			latestOptions = options;
+		},
+		apply,
+		handlers: {
+			onFocus,
+			onBlur,
+			onPointerDown,
+			onKeyDown
+		}
+	};
+}
+/**
+* Roving focus over the focusable descendants of `ref`'s element (design 6.2). Writes `tabindex`
+* (`0` on the Tab stop, `-1` on the other items) from a layout effect after every commit of the
+* calling component, from a `MutationObserver` on the subtree and from focus / pointer events;
+* the items render none. Returns the container's handlers for its library props.
+*/
+function useRovingFocus(ref, options) {
+	const [engine] = useState(createEngine);
+	useInsertionEffect(() => {
+		engine.setOptions(options);
+	});
+	const enabled = options.enabled !== false;
+	useLayoutEffect(() => {
+		const root = ref.current;
+		engine.apply(root, root?.ownerDocument.activeElement ?? null);
+	});
+	useEffect(() => {
+		const root = ref.current;
+		if (!enabled || root === null) return;
+		const observer = new MutationObserver(() => {
+			engine.apply(root, root.ownerDocument.activeElement);
+		});
+		observer.observe(root, {
+			childList: true,
+			subtree: true,
+			attributes: true,
+			attributeFilter: [
+				"disabled",
+				"hidden",
+				"inert",
+				"aria-disabled"
+			]
+		});
+		return () => {
+			observer.disconnect();
+		};
+	}, [
+		engine,
+		enabled,
+		ref
+	]);
+	return engine.handlers;
+}
+//#endregion
+export { isTextEntryItem, itemsOf, useRovingFocus };
+
+//# sourceMappingURL=use-roving-focus.mjs.map

package/dist/internal/use-roving-focus.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-roving-focus.mjs","names":[],"sources":["../../src/internal/use-roving-focus.ts"],"sourcesContent":["\"use client\";\nimport { useEffect, useInsertionEffect, useLayoutEffect, useState } from \"react\";\nimport type { FocusEvent, KeyboardEvent, PointerEvent, RefObject } from \"react\";\n\n// The roving-focus engine shared by `Toolbar.Root` and a standalone `ToggleGroup.Root`\n// (design/components/toggle-group.md section 6, conventions 3.2 and 7.4). Items are the focusable\n// descendants of the container, found in the DOM; which one is the Tab stop is urgent library\n// state kept outside React and written to the items as `tabindex` through the DOM.\n\nexport type RovingOrientation = \"horizontal\" | \"vertical\";\n\nexport interface RovingFocusOptions {\n  /** `false`: the engine writes nothing and handles nothing (a ToggleGroup inside a Toolbar). Default `true`. */\n  readonly enabled?: boolean;\n  readonly orientation: RovingOrientation;\n  readonly loop: boolean;\n  /** The native `focusgroup` path is active: write no `tabindex`, handle no navigation key. */\n  readonly native: boolean;\n  /** Which item is the Tab stop when there is no usable memory. */\n  readonly entry: (items: readonly HTMLElement[]) => HTMLElement | undefined;\n  /**\n   * `true`: the last focused item stays the Tab stop after focus leaves (Toolbar). `false`: while\n   * focus is inside, the focused item is the stop (so Tab and Shift+Tab leave the container);\n   * once it leaves, the stop is re-derived from `entry` (ToggleGroup: the pressed Item).\n   */\n  readonly memory: boolean;\n}\n\nexport interface RovingFocusHandlers {\n  readonly onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;\n  readonly onFocus: (event: FocusEvent<HTMLElement>) => void;\n  readonly onBlur: (event: FocusEvent<HTMLElement>) => void;\n  readonly onPointerDown: (event: PointerEvent<HTMLElement>) => void;\n}\n\nconst FOCUSABLE = [\n  \"button\",\n  \"a[href]\",\n  'input:not([type=\"hidden\"])',\n  \"select\",\n  \"textarea\",\n  \"summary\",\n  '[contenteditable]:not([contenteditable=\"false\"])',\n  \"[tabindex]\",\n].join(\",\");\n\nfunction isVisible(el: HTMLElement): boolean {\n  // jsdom has no `checkVisibility`; `hidden` is the part of it a test can observe there.\n  if (typeof el.checkVisibility === \"function\") return el.checkVisibility();\n  return el.closest(\"[hidden]\") === null;\n}\n\n/**\n * Whether `el` or an ancestor below `root` takes it out of `root`'s sequence: a nested toolbar\n * (its own sequence), a popover or a dialog rendered inside the container (a `Menu.Popup`'s items\n * are the menu's).\n */\nfunction isNestedOut(el: HTMLElement, root: HTMLElement): boolean {\n  for (let node: Element | null = el; node !== null && node !== root; node = node.parentElement) {\n    if (\n      node.getAttribute(\"role\") === \"toolbar\" ||\n      node.hasAttribute(\"popover\") ||\n      node.tagName === \"DIALOG\"\n    ) {\n      return true;\n    }\n  }\n  return false;\n}\n\n/**\n * The items of `root` in DOM order (design 6.2): its focusable descendants minus `:disabled`,\n * `inert`, invisible, nested-toolbar / popover / dialog content, and elements whose own\n * `tabindex=\"-1\"` was not written by this engine (`managed`). `aria-disabled` elements are items.\n */\nexport function itemsOf(root: HTMLElement, managed: { has(el: Element): boolean }): HTMLElement[] {\n  const items: HTMLElement[] = [];\n  for (const el of root.querySelectorAll<HTMLElement>(FOCUSABLE)) {\n    if (el.matches(\":disabled\")) continue;\n    if (el.closest(\"[inert]\") !== null) continue;\n    if (el.getAttribute(\"tabindex\") === \"-1\" && !managed.has(el)) continue;\n    if (isNestedOut(el, root)) continue;\n    if (!isVisible(el)) continue;\n    items.push(el);\n  }\n  return items;\n}\n\nconst BUTTON_LIKE_INPUTS = new Set([\n  \"button\",\n  \"submit\",\n  \"reset\",\n  \"checkbox\",\n  \"radio\",\n  \"image\",\n  \"color\",\n  \"file\",\n]);\nconst ARROW_OWNING_ROLES = new Set([\"textbox\", \"combobox\", \"spinbutton\", \"slider\"]);\n\n/**\n * An item that owns the arrow keys (design 6.3): text-like `input`s, `textarea`, `select`,\n * `[contenteditable]`, and `role` `textbox` / `combobox` / `spinbutton` / `slider`.\n */\nexport function isTextEntryItem(el: Element): boolean {\n  const role = el.getAttribute(\"role\");\n  if (role !== null && ARROW_OWNING_ROLES.has(role)) return true;\n  if (el instanceof HTMLInputElement) return !BUTTON_LIKE_INPUTS.has(el.type);\n  if (el instanceof HTMLTextAreaElement || el instanceof HTMLSelectElement) return true;\n  const editable = el.getAttribute(\"contenteditable\");\n  if (editable !== null && editable !== \"false\") return true;\n  return el instanceof HTMLElement && el.isContentEditable === true;\n}\n\ntype Move = \"next\" | \"prev\" | \"first\" | \"last\";\n\nfunction resolveKey(key: string, orientation: RovingOrientation, rtl: boolean): Move | null {\n  switch (key) {\n    case \"Home\":\n      return \"first\";\n    case \"End\":\n      return \"last\";\n    case \"ArrowRight\":\n      return orientation === \"horizontal\" ? (rtl ? \"prev\" : \"next\") : null;\n    case \"ArrowLeft\":\n      return orientation === \"horizontal\" ? (rtl ? \"next\" : \"prev\") : null;\n    case \"ArrowDown\":\n      return orientation === \"vertical\" ? \"next\" : null;\n    case \"ArrowUp\":\n      return orientation === \"vertical\" ? \"prev\" : null;\n    default:\n      return null;\n  }\n}\n\nfunction focusItem(item: HTMLElement): void {\n  // Keyboard focus: the ring shows even where the engine's heuristic would not (as Tabs).\n  item.focus({ focusVisible: true } as FocusOptions);\n}\n\ninterface Engine {\n  /** The options of the last committed render (written from an insertion effect). */\n  readonly setOptions: (options: RovingFocusOptions) => void;\n  /**\n   * Re-derives the Tab stop of `root` and writes `tabindex`. `focused`: the element focus is on,\n   * if any.\n   */\n  readonly apply: (root: HTMLElement | null, focused: Element | null) => void;\n  readonly handlers: RovingFocusHandlers;\n}\n\nfunction createEngine(): Engine {\n  let current: HTMLElement | null = null;\n  let latestOptions: RovingFocusOptions | null = null;\n  /**\n   * Elements this engine wrote `tabindex` on, with the attribute value they had before the first\n   * write (`null`: none). Restored when the engine lets go of an element (native path, element\n   * left the container): React does not re-write a `tabIndex` prop it believes it rendered, so a\n   * `[tabindex=\"0\"]` widget would otherwise become unreachable.\n   */\n  const managed = new Map<HTMLElement, string | null>();\n\n  const restore = (el: HTMLElement) => {\n    const original = managed.get(el);\n    managed.delete(el);\n    if (!el.isConnected || original === undefined) return;\n    if (original === null) el.removeAttribute(\"tabindex\");\n    else el.setAttribute(\"tabindex\", original);\n  };\n\n  const active = (options: RovingFocusOptions | null): options is RovingFocusOptions =>\n    options !== null && options.enabled !== false;\n\n  /** Native path: give back every `tabindex` this engine wrote (a hydration render may have). */\n  const release = () => {\n    for (const el of [...managed.keys()]) restore(el);\n    current = null;\n  };\n\n  const apply = (root: HTMLElement | null, focused: Element | null) => {\n    const options = latestOptions;\n    if (root === null || !active(options)) return;\n    if (options.native) {\n      release();\n      return;\n    }\n    const items = itemsOf(root, managed);\n    if (!options.memory) {\n      current =\n        focused instanceof HTMLElement && items.includes(focused)\n          ? focused\n          : (options.entry(items) ?? null);\n    } else if (current === null || !items.includes(current)) {\n      current = options.entry(items) ?? null;\n    }\n    for (const el of items) {\n      if (!managed.has(el)) managed.set(el, el.getAttribute(\"tabindex\"));\n      const want = el === current ? \"0\" : \"-1\";\n      if (el.getAttribute(\"tabindex\") !== want) el.setAttribute(\"tabindex\", want);\n    }\n    // Elements written before that are no longer items: a stale `0` must not stay a Tab stop\n    // (it would be one again when re-enabled); one that left the container gets its own back.\n    for (const el of [...managed.keys()]) {\n      if (items.includes(el)) continue;\n      if (!root.contains(el)) {\n        restore(el);\n      } else if (el.getAttribute(\"tabindex\") !== \"-1\") {\n        el.setAttribute(\"tabindex\", \"-1\");\n      }\n    }\n  };\n\n  const onFocus = (event: FocusEvent<HTMLElement>) => {\n    const options = latestOptions;\n    if (!active(options) || options.native) return;\n    const target = event.target;\n    if (!(target instanceof HTMLElement)) return;\n    const items = itemsOf(event.currentTarget, managed);\n    if (!items.includes(target)) return;\n    current = target;\n    apply(event.currentTarget, target);\n  };\n\n  const onBlur = (event: FocusEvent<HTMLElement>) => {\n    const options = latestOptions;\n    if (!active(options) || options.native || options.memory) return;\n    // Focus moving to another item is handled by its focus event.\n    const next = event.relatedTarget;\n    if (next instanceof Node && event.currentTarget.contains(next)) return;\n    apply(event.currentTarget, null);\n  };\n\n  const onPointerDown = (event: PointerEvent<HTMLElement>) => {\n    const options = latestOptions;\n    if (!active(options) || options.native) return;\n    const target = event.target;\n    if (!(target instanceof Node)) return;\n    const items = itemsOf(event.currentTarget, managed);\n    // Safari does not focus a button on click; the pointer still makes it the stop.\n    const item = items.find((el) => el.contains(target));\n    if (item === undefined) return;\n    current = item;\n    apply(\n      event.currentTarget,\n      options.memory ? item : event.currentTarget.ownerDocument.activeElement,\n    );\n  };\n\n  const onKeyDown = (event: KeyboardEvent<HTMLElement>) => {\n    if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return;\n    const options = latestOptions;\n    // The browser moves focus itself where `focusgroup` is implemented.\n    if (!active(options) || options.native) return;\n    const root = event.currentTarget;\n    const target = event.target;\n    if (!(target instanceof HTMLElement)) return;\n    const items = itemsOf(root, managed);\n    const index = items.indexOf(target);\n    if (index < 0) return;\n\n    if (isTextEntryItem(target)) {\n      // The item keeps its arrows, Home and End; Tab / Shift+Tab move to the next / previous item\n      // while one exists, as Chromium's `focusgroup=\"toolbar\"` does (design 6.3).\n      if (event.key !== \"Tab\") return;\n      const next = items[index + (event.shiftKey ? -1 : 1)];\n      if (next === undefined) return;\n      event.preventDefault();\n      focusItem(next);\n      return;\n    }\n\n    const rtl = options.orientation === \"horizontal\" && getComputedStyle(root).direction === \"rtl\";\n    const move = resolveKey(event.key, options.orientation, rtl);\n    if (move === null) return;\n    event.preventDefault();\n    const last = items.length - 1;\n    let nextIndex: number;\n    switch (move) {\n      case \"first\":\n        nextIndex = 0;\n        break;\n      case \"last\":\n        nextIndex = last;\n        break;\n      case \"next\":\n        nextIndex = index >= last ? (options.loop ? 0 : last) : index + 1;\n        break;\n      case \"prev\":\n        nextIndex = index <= 0 ? (options.loop ? last : 0) : index - 1;\n        break;\n    }\n    const next = items[nextIndex];\n    if (next !== undefined && next !== target) focusItem(next);\n  };\n\n  return {\n    setOptions: (options) => {\n      latestOptions = options;\n    },\n    apply,\n    handlers: { onFocus, onBlur, onPointerDown, onKeyDown },\n  };\n}\n\n/**\n * Roving focus over the focusable descendants of `ref`'s element (design 6.2). Writes `tabindex`\n * (`0` on the Tab stop, `-1` on the other items) from a layout effect after every commit of the\n * calling component, from a `MutationObserver` on the subtree and from focus / pointer events;\n * the items render none. Returns the container's handlers for its library props.\n */\nexport function useRovingFocus(\n  ref: RefObject<HTMLElement | null>,\n  options: RovingFocusOptions,\n): RovingFocusHandlers {\n  const [engine] = useState(createEngine);\n  // Before every layout effect of the same commit (as `useLatest`): handlers and the observer\n  // read the options of the last committed render.\n  useInsertionEffect(() => {\n    engine.setOptions(options);\n  });\n  const enabled = options.enabled !== false;\n\n  // After every commit of the container (a deps-less layout effect).\n  useLayoutEffect(() => {\n    const root = ref.current;\n    engine.apply(root, root?.ownerDocument.activeElement ?? null);\n  });\n\n  // Children that change without the container re-rendering.\n  useEffect(() => {\n    const root = ref.current;\n    if (!enabled || root === null) return;\n    const observer = new MutationObserver(() => {\n      engine.apply(root, root.ownerDocument.activeElement);\n    });\n    observer.observe(root, {\n      childList: true,\n      subtree: true,\n      attributes: true,\n      attributeFilter: [\"disabled\", \"hidden\", \"inert\", \"aria-disabled\"],\n    });\n    return () => {\n      observer.disconnect();\n    };\n  }, [engine, enabled, ref]);\n\n  return engine.handlers;\n}\n"],"mappings":";;;AAmCA,MAAM,YAAY;CAChB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC,CAAC,KAAK,GAAG;AAEV,SAAS,UAAU,IAA0B;CAE3C,IAAI,OAAO,GAAG,oBAAoB,YAAY,OAAO,GAAG,gBAAgB;CACxE,OAAO,GAAG,QAAQ,UAAU,MAAM;AACpC;;;;;;AAOA,SAAS,YAAY,IAAiB,MAA4B;CAChE,KAAK,IAAI,OAAuB,IAAI,SAAS,QAAQ,SAAS,MAAM,OAAO,KAAK,eAC9E,IACE,KAAK,aAAa,MAAM,MAAM,aAC9B,KAAK,aAAa,SAAS,KAC3B,KAAK,YAAY,UAEjB,OAAO;CAGX,OAAO;AACT;;;;;;AAOA,SAAgB,QAAQ,MAAmB,SAAuD;CAChG,MAAM,QAAuB,CAAC;CAC9B,KAAK,MAAM,MAAM,KAAK,iBAA8B,SAAS,GAAG;EAC9D,IAAI,GAAG,QAAQ,WAAW,GAAG;EAC7B,IAAI,GAAG,QAAQ,SAAS,MAAM,MAAM;EACpC,IAAI,GAAG,aAAa,UAAU,MAAM,QAAQ,CAAC,QAAQ,IAAI,EAAE,GAAG;EAC9D,IAAI,YAAY,IAAI,IAAI,GAAG;EAC3B,IAAI,CAAC,UAAU,EAAE,GAAG;EACpB,MAAM,KAAK,EAAE;CACf;CACA,OAAO;AACT;AAEA,MAAM,qCAAqB,IAAI,IAAI;CACjC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;AACD,MAAM,qCAAqB,IAAI,IAAI;CAAC;CAAW;CAAY;CAAc;AAAQ,CAAC;;;;;AAMlF,SAAgB,gBAAgB,IAAsB;CACpD,MAAM,OAAO,GAAG,aAAa,MAAM;CACnC,IAAI,SAAS,QAAQ,mBAAmB,IAAI,IAAI,GAAG,OAAO;CAC1D,IAAI,cAAc,kBAAkB,OAAO,CAAC,mBAAmB,IAAI,GAAG,IAAI;CAC1E,IAAI,cAAc,uBAAuB,cAAc,mBAAmB,OAAO;CACjF,MAAM,WAAW,GAAG,aAAa,iBAAiB;CAClD,IAAI,aAAa,QAAQ,aAAa,SAAS,OAAO;CACtD,OAAO,cAAc,eAAe,GAAG,sBAAsB;AAC/D;AAIA,SAAS,WAAW,KAAa,aAAgC,KAA2B;CAC1F,QAAQ,KAAR;EACE,KAAK,QACH,OAAO;EACT,KAAK,OACH,OAAO;EACT,KAAK,cACH,OAAO,gBAAgB,eAAgB,MAAM,SAAS,SAAU;EAClE,KAAK,aACH,OAAO,gBAAgB,eAAgB,MAAM,SAAS,SAAU;EAClE,KAAK,aACH,OAAO,gBAAgB,aAAa,SAAS;EAC/C,KAAK,WACH,OAAO,gBAAgB,aAAa,SAAS;EAC/C,SACE,OAAO;CACX;AACF;AAEA,SAAS,UAAU,MAAyB;CAE1C,KAAK,MAAM,EAAE,cAAc,KAAK,CAAiB;AACnD;AAaA,SAAS,eAAuB;CAC9B,IAAI,UAA8B;CAClC,IAAI,gBAA2C;;;;;;;CAO/C,MAAM,0BAAU,IAAI,IAAgC;CAEpD,MAAM,WAAW,OAAoB;EACnC,MAAM,WAAW,QAAQ,IAAI,EAAE;EAC/B,QAAQ,OAAO,EAAE;EACjB,IAAI,CAAC,GAAG,eAAe,aAAa,KAAA,GAAW;EAC/C,IAAI,aAAa,MAAM,GAAG,gBAAgB,UAAU;OAC/C,GAAG,aAAa,YAAY,QAAQ;CAC3C;CAEA,MAAM,UAAU,YACd,YAAY,QAAQ,QAAQ,YAAY;;CAG1C,MAAM,gBAAgB;EACpB,KAAK,MAAM,MAAM,CAAC,GAAG,QAAQ,KAAK,CAAC,GAAG,QAAQ,EAAE;EAChD,UAAU;CACZ;CAEA,MAAM,SAAS,MAA0B,YAA4B;EACnE,MAAM,UAAU;EAChB,IAAI,SAAS,QAAQ,CAAC,OAAO,OAAO,GAAG;EACvC,IAAI,QAAQ,QAAQ;GAClB,QAAQ;GACR;EACF;EACA,MAAM,QAAQ,QAAQ,MAAM,OAAO;EACnC,IAAI,CAAC,QAAQ,QACX,UACE,mBAAmB,eAAe,MAAM,SAAS,OAAO,IACpD,UACC,QAAQ,MAAM,KAAK,KAAK;OAC1B,IAAI,YAAY,QAAQ,CAAC,MAAM,SAAS,OAAO,GACpD,UAAU,QAAQ,MAAM,KAAK,KAAK;EAEpC,KAAK,MAAM,MAAM,OAAO;GACtB,IAAI,CAAC,QAAQ,IAAI,EAAE,GAAG,QAAQ,IAAI,IAAI,GAAG,aAAa,UAAU,CAAC;GACjE,MAAM,OAAO,OAAO,UAAU,MAAM;GACpC,IAAI,GAAG,aAAa,UAAU,MAAM,MAAM,GAAG,aAAa,YAAY,IAAI;EAC5E;EAGA,KAAK,MAAM,MAAM,CAAC,GAAG,QAAQ,KAAK,CAAC,GAAG;GACpC,IAAI,MAAM,SAAS,EAAE,GAAG;GACxB,IAAI,CAAC,KAAK,SAAS,EAAE,GACnB,QAAQ,EAAE;QACL,IAAI,GAAG,aAAa,UAAU,MAAM,MACzC,GAAG,aAAa,YAAY,IAAI;EAEpC;CACF;CAEA,MAAM,WAAW,UAAmC;EAClD,MAAM,UAAU;EAChB,IAAI,CAAC,OAAO,OAAO,KAAK,QAAQ,QAAQ;EACxC,MAAM,SAAS,MAAM;EACrB,IAAI,EAAE,kBAAkB,cAAc;EAEtC,IAAI,CADU,QAAQ,MAAM,eAAe,OAClC,CAAC,CAAC,SAAS,MAAM,GAAG;EAC7B,UAAU;EACV,MAAM,MAAM,eAAe,MAAM;CACnC;CAEA,MAAM,UAAU,UAAmC;EACjD,MAAM,UAAU;EAChB,IAAI,CAAC,OAAO,OAAO,KAAK,QAAQ,UAAU,QAAQ,QAAQ;EAE1D,MAAM,OAAO,MAAM;EACnB,IAAI,gBAAgB,QAAQ,MAAM,cAAc,SAAS,IAAI,GAAG;EAChE,MAAM,MAAM,eAAe,IAAI;CACjC;CAEA,MAAM,iBAAiB,UAAqC;EAC1D,MAAM,UAAU;EAChB,IAAI,CAAC,OAAO,OAAO,KAAK,QAAQ,QAAQ;EACxC,MAAM,SAAS,MAAM;EACrB,IAAI,EAAE,kBAAkB,OAAO;EAG/B,MAAM,OAFQ,QAAQ,MAAM,eAAe,OAE1B,CAAC,CAAC,MAAM,OAAO,GAAG,SAAS,MAAM,CAAC;EACnD,IAAI,SAAS,KAAA,GAAW;EACxB,UAAU;EACV,MACE,MAAM,eACN,QAAQ,SAAS,OAAO,MAAM,cAAc,cAAc,aAC5D;CACF;CAEA,MAAM,aAAa,UAAsC;EACvD,IAAI,MAAM,oBAAoB,MAAM,UAAU,MAAM,WAAW,MAAM,SAAS;EAC9E,MAAM,UAAU;EAEhB,IAAI,CAAC,OAAO,OAAO,KAAK,QAAQ,QAAQ;EACxC,MAAM,OAAO,MAAM;EACnB,MAAM,SAAS,MAAM;EACrB,IAAI,EAAE,kBAAkB,cAAc;EACtC,MAAM,QAAQ,QAAQ,MAAM,OAAO;EACnC,MAAM,QAAQ,MAAM,QAAQ,MAAM;EAClC,IAAI,QAAQ,GAAG;EAEf,IAAI,gBAAgB,MAAM,GAAG;GAG3B,IAAI,MAAM,QAAQ,OAAO;GACzB,MAAM,OAAO,MAAM,SAAS,MAAM,WAAW,KAAK;GAClD,IAAI,SAAS,KAAA,GAAW;GACxB,MAAM,eAAe;GACrB,UAAU,IAAI;GACd;EACF;EAEA,MAAM,MAAM,QAAQ,gBAAgB,gBAAgB,iBAAiB,IAAI,CAAC,CAAC,cAAc;EACzF,MAAM,OAAO,WAAW,MAAM,KAAK,QAAQ,aAAa,GAAG;EAC3D,IAAI,SAAS,MAAM;EACnB,MAAM,eAAe;EACrB,MAAM,OAAO,MAAM,SAAS;EAC5B,IAAI;EACJ,QAAQ,MAAR;GACE,KAAK;IACH,YAAY;IACZ;GACF,KAAK;IACH,YAAY;IACZ;GACF,KAAK;IACH,YAAY,SAAS,OAAQ,QAAQ,OAAO,IAAI,OAAQ,QAAQ;IAChE;GACF,KAAK,QACH,YAAY,SAAS,IAAK,QAAQ,OAAO,OAAO,IAAK,QAAQ;EAEjE;EACA,MAAM,OAAO,MAAM;EACnB,IAAI,SAAS,KAAA,KAAa,SAAS,QAAQ,UAAU,IAAI;CAC3D;CAEA,OAAO;EACL,aAAa,YAAY;GACvB,gBAAgB;EAClB;EACA;EACA,UAAU;GAAE;GAAS;GAAQ;GAAe;EAAU;CACxD;AACF;;;;;;;AAQA,SAAgB,eACd,KACA,SACqB;CACrB,MAAM,CAAC,UAAU,SAAS,YAAY;CAGtC,yBAAyB;EACvB,OAAO,WAAW,OAAO;CAC3B,CAAC;CACD,MAAM,UAAU,QAAQ,YAAY;CAGpC,sBAAsB;EACpB,MAAM,OAAO,IAAI;EACjB,OAAO,MAAM,MAAM,MAAM,cAAc,iBAAiB,IAAI;CAC9D,CAAC;CAGD,gBAAgB;EACd,MAAM,OAAO,IAAI;EACjB,IAAI,CAAC,WAAW,SAAS,MAAM;EAC/B,MAAM,WAAW,IAAI,uBAAuB;GAC1C,OAAO,MAAM,MAAM,KAAK,cAAc,aAAa;EACrD,CAAC;EACD,SAAS,QAAQ,MAAM;GACrB,WAAW;GACX,SAAS;GACT,YAAY;GACZ,iBAAiB;IAAC;IAAY;IAAU;IAAS;GAAe;EAClE,CAAC;EACD,aAAa;GACX,SAAS,WAAW;EACtB;CACF,GAAG;EAAC;EAAQ;EAAS;CAAG,CAAC;CAEzB,OAAO,OAAO;AAChB"}

package/dist/internal/validity.d.mts

@@ -0,0 +1,24 @@
+//#region src/internal/validity.d.ts
+/** A field error: a message, several messages, or nothing (`""`, `[]`, `null`, `undefined`). */
+export type FieldErrorValue = string | readonly string[] | null | undefined;
+/** Field errors keyed by field `name` (usually `state.errors` from `useActionState`). */
+export type FormErrors = Readonly<Record<string, FieldErrorValue>>;
+/**
+ * A plain, serialisable snapshot of the control's `ValidityState` (all `false` and
+ * `valid: true` on the server and before the first read).
+ */
+export interface FieldValidity {
+  readonly valueMissing: boolean;
+  readonly typeMismatch: boolean;
+  readonly patternMismatch: boolean;
+  readonly tooLong: boolean;
+  readonly tooShort: boolean;
+  readonly rangeUnderflow: boolean;
+  readonly rangeOverflow: boolean;
+  readonly stepMismatch: boolean;
+  readonly badInput: boolean;
+  readonly customError: boolean;
+  readonly valid: boolean;
+}
+//#endregion
+//# sourceMappingURL=validity.d.mts.map

package/dist/internal/validity.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validity.d.mts","names":[],"sources":["../../src/internal/validity.ts"],"mappings":";;YAIY;;YAGA,aAAa,SAAS,eAAe;;;;;iBAMhC;WACN;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA;WACA"}