@funstack/ui 0.0.0-stage → 0.1.0-alpha.1

package/dist/internal/platform-attributes.d.mts

@@ -0,0 +1,55 @@
+//#region src/internal/platform-attributes.d.ts
+declare module "react" {
+  interface HTMLAttributes<T> {
+    /**
+     * `focusgroup` (Chromium 150+): native roving focus. A behaviour token (`tablist`, `toolbar`,
+     * ...) plus modifiers (`inline`, `block`, `wrap`, `nowrap`, `nomemory`).
+     * Not in `@types/react` 19.3.0 (no DefinitelyTyped issue filed as of 2026-10-16).
+     */
+    focusgroup?: string | undefined;
+    /**
+     * `focusgroupstart` (Chromium 150+): marks the item a `focusgroup` enters on when focus
+     * arrives from outside (with `nomemory`, always). Boolean attribute: pass `""`.
+     * Not in `@types/react` 19.3.0 (no DefinitelyTyped issue filed as of 2026-10-17).
+     */
+    focusgroupstart?: "" | undefined;
+  }
+  interface ButtonHTMLAttributes<T> {
+    /**
+     * `interestfor` (Interest Invokers, Chromium 142+): id of the element, usually a popover,
+     * shown when the user shows interest in this button (hover, keyboard focus, long-press).
+     * Not in `@types/react` 19.3.0 (DefinitelyTyped #74664).
+     */
+    interestfor?: string | undefined;
+    /**
+     * `commandfor` (Invoker Commands): id of the element the button's `command` acts on.
+     * Not in `@types/react` 19.3.0 (DefinitelyTyped #74664).
+     */
+    commandfor?: string | undefined;
+    /**
+     * `command` (Invoker Commands): a built-in command (`show-popover`, `hide-popover`,
+     * `toggle-popover`, `show-modal`, `close`, `request-close`) or a custom `--command`.
+     * Not in `@types/react` 19.3.0 (DefinitelyTyped #74664).
+     */
+    command?: "show-popover" | "hide-popover" | "toggle-popover" | "show-modal" | "close" | "request-close" | `--${string}` | undefined;
+  }
+  interface AnchorHTMLAttributes<T> {
+    /** `interestfor` on `<a href>` (Chromium 142+). Not in `@types/react` 19.3.0 (DefinitelyTyped #74664). */
+    interestfor?: string | undefined;
+  }
+  interface AreaHTMLAttributes<T> {
+    /** `interestfor` on `<area href>` (Chromium 142+). Not in `@types/react` 19.3.0 (DefinitelyTyped #74664). */
+    interestfor?: string | undefined;
+  }
+  interface CSSProperties {
+    /** `interest-delay` shorthand (Chromium 142+). Not in `csstype` 3.2.3. */
+    interestDelay?: string | undefined;
+    /** `interest-delay-start` (Chromium 142+; default `0.25s`). Not in `csstype` 3.2.3. */
+    interestDelayStart?: string | undefined;
+    /** `interest-delay-end` (Chromium 142+; default `0.15s`). Not in `csstype` 3.2.3. */
+    interestDelayEnd?: string | undefined;
+  }
+}
+//#endregion
+export {};
+//# sourceMappingURL=platform-attributes.d.mts.map

package/dist/internal/platform-attributes.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-attributes.d.mts","names":[],"sources":["../../src/internal/platform-attributes.ts"],"mappings":";;YAkBY,eAAe;;;;;;IAMvB;;;;;;IAMA;;YAGQ,qBAAqB;;;;;;IAM7B;;;;;IAKA;;;;;;IAMA;;YAWQ,qBAAqB;;IAE7B;;YAGQ,mBAAmB;;IAE3B;;YAGQ;;IAER;;IAEA;;IAEA"}

package/dist/internal/sync-presence.mjs

@@ -0,0 +1,19 @@
+//#region src/internal/sync-presence.ts
+/**
+* Makes a boolean attribute's presence match `present`. For group members that may hydrate after
+* their Root (`RadioGroup.Item`, `CheckboxGroup.Item` / `Parent`): hydration keeps server
+* attributes that differ from the client render (React only warns), and a member hydrating late
+* can render a different state than the server did.
+*
+* No `"use client"` directive: no client-only API (conventions 7.1).
+*/
+function syncPresence(el, name, present) {
+	if (el.hasAttribute(name) !== present) {
+		if (present) el.setAttribute(name, "");
+		else el.removeAttribute(name);
+	}
+}
+//#endregion
+export { syncPresence };
+
+//# sourceMappingURL=sync-presence.mjs.map

package/dist/internal/sync-presence.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-presence.mjs","names":[],"sources":["../../src/internal/sync-presence.ts"],"sourcesContent":["/**\n * Makes a boolean attribute's presence match `present`. For group members that may hydrate after\n * their Root (`RadioGroup.Item`, `CheckboxGroup.Item` / `Parent`): hydration keeps server\n * attributes that differ from the client render (React only warns), and a member hydrating late\n * can render a different state than the server did.\n *\n * No `\"use client\"` directive: no client-only API (conventions 7.1).\n */\nexport function syncPresence(el: Element, name: string, present: boolean): void {\n  if (el.hasAttribute(name) !== present) {\n    if (present) el.setAttribute(name, \"\");\n    else el.removeAttribute(name);\n  }\n}\n"],"mappings":";;;;;;;;;AAQA,SAAgB,aAAa,IAAa,MAAc,SAAwB;CAC9E,IAAI,GAAG,aAAa,IAAI,MAAM,SAAS;EACrC,IAAI,SAAS,GAAG,aAAa,MAAM,EAAE;OAChC,GAAG,gBAAgB,IAAI;CAC9B;AACF"}

package/dist/internal/transition-boundary.mjs

@@ -0,0 +1,52 @@
+"use client";
+import { ViewTransition, useEffect, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/internal/transition-boundary.tsx
+const isDev = process.env.NODE_ENV !== "production";
+/**
+* Wraps a part's output in `<ViewTransition default={transition}>` **only when the consumer
+* passed `transition`** (conventions 5.1). With `transition === undefined` the node is returned
+* unwrapped and the part renders no boundary at all.
+*
+* Reason (docs/research/view-transition-mount-cost.md, issue #35): react-dom 19.3 starts a
+* document view transition whenever a `<ViewTransition>` mounts or is revealed by `<Activity>` in
+* a transition-lane commit, whatever its class resolves to (`"none"` included). The browser's
+* 250 ms root cross-fade then runs and every later transition commit waits for it. Exits and
+* updates of a `"none"` boundary are free, so an explicit `transition="none"` keeps the boundary
+* and lets a consumer switch between `"none"` and a class without remounting.
+*
+* The boundary stays the outermost node of the part's output, so a part that is the top of an
+* inserted subtree gets enter / exit. A plain function (not a component), so it adds no fiber
+* between the boundary and the element.
+*/
+function transitionBoundary(transition, node) {
+	if (transition === void 0) return node;
+	return /* @__PURE__ */ jsx(ViewTransition, {
+		default: transition,
+		children: node
+	});
+}
+/**
+* {@link transitionBoundary} plus the development warning for a non-static `transition`
+* (conventions 5.1): changing it between `undefined` and a value changes the element type at the
+* part's root, so React remounts the part's subtree (DOM and state lost). Warns once per
+* instance, from an effect. `part` is the public name used in the message (`"Tabs.Panel"`).
+*
+* Pass the *effective* value: a part that ignores `transition` in some mode (Accordion, Dialog
+* JS-free mode) passes `undefined` there.
+*/
+function useTransitionBoundary(part, transition, node) {
+	const hasBoundary = transition !== void 0;
+	const initial = useRef(hasBoundary);
+	const warned = useRef(false);
+	useEffect(() => {
+		if (!isDev || warned.current || hasBoundary === initial.current) return;
+		warned.current = true;
+		console.error(`${part}: \`transition\` changed between undefined and a value after mount. The part renders a <ViewTransition> only when \`transition\` is given, so this remounts its subtree (DOM and state are lost). Keep \`transition\` static; use \`transition="none"\` to switch animation off without removing the boundary.`);
+	}, [hasBoundary, part]);
+	return transitionBoundary(transition, node);
+}
+//#endregion
+export { transitionBoundary, useTransitionBoundary };
+
+//# sourceMappingURL=transition-boundary.mjs.map

package/dist/internal/transition-boundary.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition-boundary.mjs","names":[],"sources":["../../src/internal/transition-boundary.tsx"],"sourcesContent":["\"use client\";\nimport { useEffect, useRef, ViewTransition } from \"react\";\nimport type { ReactNode, ViewTransitionClass } from \"react\";\n\nconst isDev = process.env.NODE_ENV !== \"production\";\n\n/**\n * Wraps a part's output in `<ViewTransition default={transition}>` **only when the consumer\n * passed `transition`** (conventions 5.1). With `transition === undefined` the node is returned\n * unwrapped and the part renders no boundary at all.\n *\n * Reason (docs/research/view-transition-mount-cost.md, issue #35): react-dom 19.3 starts a\n * document view transition whenever a `<ViewTransition>` mounts or is revealed by `<Activity>` in\n * a transition-lane commit, whatever its class resolves to (`\"none\"` included). The browser's\n * 250 ms root cross-fade then runs and every later transition commit waits for it. Exits and\n * updates of a `\"none\"` boundary are free, so an explicit `transition=\"none\"` keeps the boundary\n * and lets a consumer switch between `\"none\"` and a class without remounting.\n *\n * The boundary stays the outermost node of the part's output, so a part that is the top of an\n * inserted subtree gets enter / exit. A plain function (not a component), so it adds no fiber\n * between the boundary and the element.\n */\nexport function transitionBoundary(\n  transition: ViewTransitionClass | undefined,\n  node: ReactNode,\n): ReactNode {\n  if (transition === undefined) return node;\n  return <ViewTransition default={transition}>{node}</ViewTransition>;\n}\n\n/**\n * {@link transitionBoundary} plus the development warning for a non-static `transition`\n * (conventions 5.1): changing it between `undefined` and a value changes the element type at the\n * part's root, so React remounts the part's subtree (DOM and state lost). Warns once per\n * instance, from an effect. `part` is the public name used in the message (`\"Tabs.Panel\"`).\n *\n * Pass the *effective* value: a part that ignores `transition` in some mode (Accordion, Dialog\n * JS-free mode) passes `undefined` there.\n */\nexport function useTransitionBoundary(\n  part: string,\n  transition: ViewTransitionClass | undefined,\n  node: ReactNode,\n): ReactNode {\n  const hasBoundary = transition !== undefined;\n  const initial = useRef(hasBoundary);\n  const warned = useRef(false);\n  useEffect(() => {\n    if (!isDev || warned.current || hasBoundary === initial.current) return;\n    warned.current = true;\n    console.error(\n      `${part}: \\`transition\\` changed between undefined and a value after mount. The part ` +\n        \"renders a <ViewTransition> only when `transition` is given, so this remounts its \" +\n        'subtree (DOM and state are lost). Keep `transition` static; use `transition=\"none\"` ' +\n        \"to switch animation off without removing the boundary.\",\n    );\n  }, [hasBoundary, part]);\n  return transitionBoundary(transition, node);\n}\n"],"mappings":";;;;AAIA,MAAM,QAAQ,QAAQ,IAAI,aAAa;;;;;;;;;;;;;;;;;AAkBvC,SAAgB,mBACd,YACA,MACW;CACX,IAAI,eAAe,KAAA,GAAW,OAAO;CACrC,OAAO,oBAAC,gBAAD;EAAgB,SAAS;EAAa,UAAA;CAAqB,CAAA;AACpE;;;;;;;;;;AAWA,SAAgB,sBACd,MACA,YACA,MACW;CACX,MAAM,cAAc,eAAe,KAAA;CACnC,MAAM,UAAU,OAAO,WAAW;CAClC,MAAM,SAAS,OAAO,KAAK;CAC3B,gBAAgB;EACd,IAAI,CAAC,SAAS,OAAO,WAAW,gBAAgB,QAAQ,SAAS;EACjE,OAAO,UAAU;EACjB,QAAQ,MACN,GAAG,KAAK,+SAIV;CACF,GAAG,CAAC,aAAa,IAAI,CAAC;CACtB,OAAO,mBAAmB,YAAY,IAAI;AAC5C"}

package/dist/internal/transition-types.mjs

@@ -0,0 +1,15 @@
+//#region src/internal/transition-types.ts
+/**
+* Builds the library's View Transition type names for one dispatch (conventions 5.3):
+* `fsui-<component>` plus, when the change has a kind, `fsui-<component>-<change>`.
+*
+* Hyphens only: the names are also matched by `:active-view-transition-type(...)` in CSS.
+*/
+function transitionTypes(component, change) {
+	const base = `fsui-${component}`;
+	return change ? [base, `${base}-${change}`] : [base];
+}
+//#endregion
+export { transitionTypes };
+
+//# sourceMappingURL=transition-types.mjs.map

package/dist/internal/transition-types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transition-types.mjs","names":[],"sources":["../../src/internal/transition-types.ts"],"sourcesContent":["/**\n * Builds the library's View Transition type names for one dispatch (conventions 5.3):\n * `fsui-<component>` plus, when the change has a kind, `fsui-<component>-<change>`.\n *\n * Hyphens only: the names are also matched by `:active-view-transition-type(...)` in CSS.\n */\nexport function transitionTypes(\n  component: string,\n  change?: string | null | undefined,\n): readonly string[] {\n  const base = `fsui-${component}`;\n  return change ? [base, `${base}-${change}`] : [base];\n}\n"],"mappings":";;;;;;;AAMA,SAAgB,gBACd,WACA,QACmB;CACnB,MAAM,OAAO,QAAQ;CACrB,OAAO,SAAS,CAAC,MAAM,GAAG,KAAK,GAAG,QAAQ,IAAI,CAAC,IAAI;AACrD"}

package/dist/internal/types.d.mts

@@ -0,0 +1,38 @@
+import { ReactElement, ReactNode } from "react";
+//#region src/internal/types.d.ts
+/**
+ * A callback the library runs inside a Transition. May be sync or async: the library awaits
+ * whatever it returns (a thenable is awaited, anything else is ignored). The return type is
+ * `unknown` rather than `void | Promise<void>` so that `(next) => save(next)` compiles when `save`
+ * returns data, as Server Functions usually do (conventions 2.2).
+ */
+export type Action<Args extends readonly unknown[] = []> = (...args: Args) => unknown;
+export interface ActionDetails {
+  /** The DOM event that caused the action, or `undefined` for programmatic changes. */
+  readonly event: Event | undefined;
+}
+/** An action called with the next value of a controllable state. */
+export type ChangeAction<T, Details extends ActionDetails = ActionDetails> = Action<[next: T, details: Details]>;
+/**
+ * Why a change action was dispatched (conventions 2.2). One library-wide vocabulary: every
+ * `<Component><State>ChangeDetails` that exposes `reason` declares it with this type.
+ *
+ * - `"activate"`: the user acted on a trigger part (click, Enter/Space, label click, focus in an
+ *   automatic-activation mode). `details.event` is the native event.
+ * - `"dismiss"`: the user closed the component without acting on one of its parts: Escape,
+ *   Android back, an assistive-technology dismiss gesture, or a click outside (light dismiss).
+ *   `details.event` is the platform's `close` event. Dialog is the first component to use it.
+ * - `"platform"`: the browser changed the state itself: find-in-page, a form reset (`event` is
+ *   the `reset` event), or interaction before hydration found at mount (`event` is `undefined`).
+ */
+export type ChangeReason = "activate" | "dismiss" | "platform";
+/** A prop value that is either a plain value or a function of the part's state. */
+export type StateValue<T, State> = T | ((state: State) => T);
+/**
+ * Element polymorphism. Element form replaces the default element and the library merges its
+ * props into it; function form receives the merged props and the part's state and renders
+ * whatever it likes (it must spread `props` onto a DOM element).
+ */
+export type RenderProp<Props, State> = ReactElement<Partial<Props>> | ((props: Props, state: State) => ReactNode);
+//#endregion
+//# sourceMappingURL=types.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/internal/types.ts"],"mappings":";;;;;;;;YAQY,OAAO,4CAA4C,MAAM;iBAEpD;;WAEN,OAAO;;;YAIN,aAAa,GAAG,gBAAgB,gBAAgB,iBAAiB,QAC1E,MAAM,GAAG,SAAS;;;;;;;;;;;;;YAeT;;YAGA,WAAW,GAAG,SAAS,MAAM,OAAO,UAAU;;;;;;YAO9C,WAAW,OAAO,SAC1B,aAAa,QAAQ,YACnB,OAAO,OAAO,OAAO,UAAU"}

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

@@ -0,0 +1,58 @@
+"use client";
+import { useEffect, useRef, useState, useTransition } from "react";
+//#region src/internal/use-action-trigger.ts
+/** Reports an error that cannot reach a boundary (conventions 2.4: never swallow). */
+function report(error) {
+	if (typeof reportError === "function") reportError(error);
+	else console.error(error);
+}
+/**
+* The transition of a pure-trigger part: an `action` with no state of its own (`Dialog.Close`,
+* `Popover.Close`, `Menu.Item`; conventions 3.4). Same superseded-rejection surfacing as
+* `useControllableAction`: React keeps only the newest thenable per `useTransition`, so the
+* rejection of a run that a later run superseded would be dropped. The hook catches it and throws
+* it from render, so it reaches the same boundary as the latest run's rejection does.
+*/
+function useActionTrigger(openGeneration) {
+	const [supersededError, setSupersededError] = useState(null);
+	const hasSupersededError = useRef(false);
+	if (supersededError !== null) throw supersededError.error;
+	const [pending, startOwnTransition] = useTransition();
+	const latest = useRef(0);
+	const mounted = useRef(false);
+	useEffect(() => {
+		mounted.current = true;
+		return () => {
+			mounted.current = false;
+		};
+	}, []);
+	const run = (work, then) => {
+		const id = ++latest.current;
+		const generation = openGeneration?.();
+		startOwnTransition(async () => {
+			try {
+				await work();
+			} catch (error) {
+				if (id === latest.current) throw error;
+				if (!mounted.current) return;
+				if (hasSupersededError.current) {
+					report(error);
+					return;
+				}
+				hasSupersededError.current = true;
+				setSupersededError({ error });
+				return;
+			}
+			if (openGeneration !== void 0 && openGeneration() !== generation) return;
+			then?.();
+		});
+	};
+	return {
+		pending,
+		run
+	};
+}
+//#endregion
+export { useActionTrigger };
+
+//# sourceMappingURL=use-action-trigger.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-action-trigger.mjs","names":[],"sources":["../../src/internal/use-action-trigger.ts"],"sourcesContent":["\"use client\";\nimport { useEffect, useRef, useState, useTransition } from \"react\";\n\nexport interface ActionTrigger {\n  /** A run started through this hook is in flight (the part's own transition). */\n  readonly pending: boolean;\n  /**\n   * Runs `work` inside the part's own transition and, once it resolves, `then` (still inside the\n   * transition: a Close part's close, a menu item's close). A rejection skips `then` and reaches\n   * the nearest Error Boundary above the part, also when a later run superseded this one. With\n   * `openGeneration` (the hook's argument), `then` is skipped when a newer open of the overlay\n   * started after the run began.\n   */\n  readonly run: (work: () => unknown, then?: () => void) => void;\n}\n\n/** Reports an error that cannot reach a boundary (conventions 2.4: never swallow). */\nfunction report(error: unknown): void {\n  if (typeof reportError === \"function\") reportError(error);\n  else console.error(error);\n}\n\n/**\n * The transition of a pure-trigger part: an `action` with no state of its own (`Dialog.Close`,\n * `Popover.Close`, `Menu.Item`; conventions 3.4). Same superseded-rejection surfacing as\n * `useControllableAction`: React keeps only the newest thenable per `useTransition`, so the\n * rejection of a run that a later run superseded would be dropped. The hook catches it and throws\n * it from render, so it reaches the same boundary as the latest run's rejection does.\n */\nexport function useActionTrigger(openGeneration?: () => number): ActionTrigger {\n  // Thrown before `useTransition` on purpose (see use-controllable-action.ts): in the retry of\n  // an errored render `useTransition` would suspend on the newer run's pending thenable.\n  const [supersededError, setSupersededError] = useState<{ readonly error: unknown } | null>(null);\n  const hasSupersededError = useRef(false);\n  if (supersededError !== null) throw supersededError.error;\n\n  const [pending, startOwnTransition] = useTransition();\n  const latest = useRef(0);\n  const mounted = useRef(false);\n\n  useEffect(() => {\n    mounted.current = true;\n    return () => {\n      mounted.current = false;\n    };\n  }, []);\n\n  const run = (work: () => unknown, then?: () => void): void => {\n    const id = ++latest.current;\n    // The open this run belongs to (design/components/popover.md, review M2 / PO rule): if the\n    // user dismisses and re-opens while the action runs, its close must not close the new open.\n    const generation = openGeneration?.();\n    startOwnTransition(async () => {\n      try {\n        await work();\n      } catch (error) {\n        // The latest run's rejection takes React's own route to the boundary.\n        if (id === latest.current) throw error;\n        if (!mounted.current) return;\n        if (hasSupersededError.current) {\n          report(error);\n          return;\n        }\n        hasSupersededError.current = true;\n        // After an await, outside the transition: urgent, so the part re-renders and throws.\n        setSupersededError({ error });\n        return;\n      }\n      if (openGeneration !== undefined && openGeneration() !== generation) return;\n      then?.();\n    });\n  };\n\n  return { pending, run };\n}\n"],"mappings":";;;;AAiBA,SAAS,OAAO,OAAsB;CACpC,IAAI,OAAO,gBAAgB,YAAY,YAAY,KAAK;MACnD,QAAQ,MAAM,KAAK;AAC1B;;;;;;;;AASA,SAAgB,iBAAiB,gBAA8C;CAG7E,MAAM,CAAC,iBAAiB,sBAAsB,SAA6C,IAAI;CAC/F,MAAM,qBAAqB,OAAO,KAAK;CACvC,IAAI,oBAAoB,MAAM,MAAM,gBAAgB;CAEpD,MAAM,CAAC,SAAS,sBAAsB,cAAc;CACpD,MAAM,SAAS,OAAO,CAAC;CACvB,MAAM,UAAU,OAAO,KAAK;CAE5B,gBAAgB;EACd,QAAQ,UAAU;EAClB,aAAa;GACX,QAAQ,UAAU;EACpB;CACF,GAAG,CAAC,CAAC;CAEL,MAAM,OAAO,MAAqB,SAA4B;EAC5D,MAAM,KAAK,EAAE,OAAO;EAGpB,MAAM,aAAa,iBAAiB;EACpC,mBAAmB,YAAY;GAC7B,IAAI;IACF,MAAM,KAAK;GACb,SAAS,OAAO;IAEd,IAAI,OAAO,OAAO,SAAS,MAAM;IACjC,IAAI,CAAC,QAAQ,SAAS;IACtB,IAAI,mBAAmB,SAAS;KAC9B,OAAO,KAAK;KACZ;IACF;IACA,mBAAmB,UAAU;IAE7B,mBAAmB,EAAE,MAAM,CAAC;IAC5B;GACF;GACA,IAAI,mBAAmB,KAAA,KAAa,eAAe,MAAM,YAAY;GACrE,OAAO;EACT,CAAC;CACH;CAEA,OAAO;EAAE;EAAS;CAAI;AACxB"}

package/dist/internal/use-controllable-action.mjs

@@ -0,0 +1,115 @@
+"use client";
+import { addTransitionType, startTransition, useEffect, useOptimistic, useRef, useState, useTransition } from "react";
+//#region src/internal/use-controllable-action.ts
+const isDev = process.env.NODE_ENV !== "production";
+function capitalize(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/** Reports an error that cannot reach a boundary (conventions 2.4: never swallow). */
+function report(error) {
+	if (typeof reportError === "function") reportError(error);
+	else console.error(error);
+}
+/**
+* The one place the state model of conventions section 3 is implemented: committed state,
+* optimistic state (`useOptimistic`, reducer form), the component's own transition, the
+* post-`await` write of uncontrolled state, the latest-dispatch guard, and the surfacing of
+* superseded rejections (conventions 2.4).
+*/
+function useControllableAction(options) {
+	const { controlled, defaultValue, initialValue, action, transitionTypes, reducer, warn } = options;
+	const [supersededError, setSupersededError] = useState(null);
+	const hasSupersededError = useRef(false);
+	if (supersededError !== null) throw supersededError.error;
+	const [internal, setInternal] = useState(defaultValue === void 0 ? initialValue : defaultValue);
+	const isControlled = controlled !== void 0;
+	const committed = isControlled ? controlled : internal;
+	const [optimistic, setOptimistic] = useOptimistic(committed, (prev, patch) => reducer ? reducer(prev, patch.next, patch.details) : patch.next);
+	const [pending, startOwnTransition] = useTransition();
+	const latest = useRef(0);
+	const inFlight = useRef({
+		count: 0,
+		next: void 0
+	});
+	const mounted = useRef(false);
+	useDevWarnings(isControlled, defaultValue !== void 0, warn);
+	useEffect(() => {
+		mounted.current = true;
+		return () => {
+			mounted.current = false;
+		};
+	}, []);
+	function dispatch(next, details) {
+		const prev = committed;
+		const id = ++latest.current;
+		inFlight.current.count += 1;
+		inFlight.current.next = next;
+		startOwnTransition(async () => {
+			for (const type of transitionTypes?.(next, prev, details) ?? []) addTransitionType(type);
+			setOptimistic({
+				next,
+				details
+			});
+			try {
+				await action?.(next, details);
+			} catch (error) {
+				settle();
+				if (id === latest.current) throw error;
+				if (!mounted.current) return;
+				if (hasSupersededError.current) {
+					report(error);
+					return;
+				}
+				hasSupersededError.current = true;
+				setSupersededError({ error });
+				return;
+			}
+			settle();
+			if (!isControlled && id === latest.current) startTransition(() => setInternal(next));
+		});
+	}
+	function settle() {
+		inFlight.current.count -= 1;
+		if (inFlight.current.count === 0) inFlight.current.next = void 0;
+	}
+	function latestInFlight() {
+		const { count, next } = inFlight.current;
+		return count > 0 ? { next } : null;
+	}
+	return {
+		committed,
+		optimistic,
+		pending,
+		dispatch,
+		latestInFlight
+	};
+}
+function useDevWarnings(isControlled, hasDefault, warn) {
+	const initialMode = useRef(isControlled);
+	const warnedBoth = useRef(false);
+	const warnedSwitch = useRef(false);
+	const component = warn?.component ?? "A component";
+	const prop = warn?.prop ?? "value";
+	useEffect(() => {
+		if (!isDev) return;
+		const defaultProp = `default${capitalize(prop)}`;
+		if (isControlled && hasDefault && !warnedBoth.current) {
+			warnedBoth.current = true;
+			console.error(`${component}: both \`${prop}\` and \`${defaultProp}\` are set. Use \`${prop}\` for controlled mode or \`${defaultProp}\` for uncontrolled mode, not both.`);
+		}
+		if (initialMode.current !== isControlled && !warnedSwitch.current) {
+			warnedSwitch.current = true;
+			const from = initialMode.current ? "controlled" : "uncontrolled";
+			console.error(`${component}: \`${prop}\` changed from ${from} to ${isControlled ? "controlled" : "uncontrolled"}. Switching modes after mount is not supported; keep \`${prop}\` either always defined or always undefined.`);
+		}
+	}, [
+		component,
+		prop,
+		isControlled,
+		hasDefault
+	]);
+}
+//#endregion
+export { useControllableAction };
+
+//# sourceMappingURL=use-controllable-action.mjs.map

package/dist/internal/use-controllable-action.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-controllable-action.mjs","names":[],"sources":["../../src/internal/use-controllable-action.ts"],"sourcesContent":["\"use client\";\nimport {\n  addTransitionType,\n  startTransition,\n  useEffect,\n  useOptimistic,\n  useRef,\n  useState,\n  useTransition,\n} from \"react\";\nimport type { ActionDetails, ChangeAction } from \"./types.js\";\n\nexport interface UseControllableActionOptions<T, Details extends ActionDetails> {\n  /** The controlled prop (`x`). `undefined` means uncontrolled. */\n  controlled: T | undefined;\n  /** The `defaultX` prop as the consumer passed it; `undefined` when omitted. */\n  defaultValue: T | undefined;\n  /** Initial uncontrolled value when neither `x` nor `defaultX` is given. */\n  initialValue: T;\n  /** The `xChangeAction` prop. Awaited inside this hook's transition. */\n  action: ChangeAction<T, Details> | undefined;\n  /**\n   * View Transition types to attach to the commit that ends a dispatch. Receives the previous\n   * committed value and the details object (Tabs derives next/prev direction from them).\n   */\n  transitionTypes?: (next: T, prev: T, details: Details) => readonly string[];\n  /**\n   * Optimistic reducer (conventions 3.4). Default: replace the value with `next`. Multi-item\n   * states (Accordion's open set) pass a reducer keyed by item, reading the item from `details`,\n   * so stacked optimistic patches re-base onto a changed committed value.\n   */\n  reducer?: (prev: T, next: T, details: Details) => T;\n  /** Names used in development warnings. */\n  warn?: { readonly component: string; readonly prop: string };\n}\n\nexport interface ControllableAction<T, Details extends ActionDetails> {\n  /** Committed value (`x ?? internal`). Content regions render this. */\n  readonly committed: T;\n  /** Optimistic value; trigger parts render this. */\n  readonly optimistic: T;\n  /** An action dispatched through this hook is in flight. */\n  readonly pending: boolean;\n  /** Runs the action inside the hook's transition with optimistic feedback. */\n  readonly dispatch: (next: T, details: Details) => void;\n  /**\n   * The `next` of the most recent dispatch while any dispatch's action is still unsettled, else\n   * `null`. Lets a component with a browser-owned path (Accordion's find-in-page reveal) build on\n   * what the user already intends instead of on the DOM. Read it from handlers and effects only.\n   */\n  readonly latestInFlight: () => { readonly next: T } | null;\n}\n\nconst isDev = process.env.NODE_ENV !== \"production\";\n\nfunction capitalize(s: string): string {\n  return s.charAt(0).toUpperCase() + s.slice(1);\n}\n\n/** Reports an error that cannot reach a boundary (conventions 2.4: never swallow). */\nfunction report(error: unknown): void {\n  if (typeof reportError === \"function\") reportError(error);\n  else console.error(error);\n}\n\n/**\n * The one place the state model of conventions section 3 is implemented: committed state,\n * optimistic state (`useOptimistic`, reducer form), the component's own transition, the\n * post-`await` write of uncontrolled state, the latest-dispatch guard, and the surfacing of\n * superseded rejections (conventions 2.4).\n */\nexport function useControllableAction<T, Details extends ActionDetails = ActionDetails>(\n  options: UseControllableActionOptions<T, Details>,\n): ControllableAction<T, Details> {\n  const { controlled, defaultValue, initialValue, action, transitionTypes, reducer, warn } =\n    options;\n\n  // React keeps only the newest thenable per `useTransition`, so a rejection from a dispatch that\n  // was superseded by a later one would be dropped entirely (no boundary, no `reportError`). The\n  // hook catches those itself, keeps the first, and throws it from render so it reaches the same\n  // nearest Error Boundary as the latest dispatch's rejection does through React.\n  //\n  // The throw sits before `useTransition` on purpose: React retries an errored render with every\n  // pending lane, and in that retry `useTransition` unwraps the still-pending action thenable and\n  // suspends, which would hold the boundary commit until the newer action settles.\n  const [supersededError, setSupersededError] = useState<{ readonly error: unknown } | null>(null);\n  const hasSupersededError = useRef(false);\n  if (supersededError !== null) throw supersededError.error;\n\n  const [internal, setInternal] = useState<T>(\n    defaultValue === undefined ? initialValue : defaultValue,\n  );\n  const isControlled = controlled !== undefined;\n  const committed = isControlled ? controlled : internal;\n  const [optimistic, setOptimistic] = useOptimistic(\n    committed,\n    (prev: T, patch: { next: T; details: Details }) =>\n      reducer ? reducer(prev, patch.next, patch.details) : patch.next,\n  );\n  const [pending, startOwnTransition] = useTransition();\n  const latest = useRef(0);\n  const inFlight = useRef<{ count: number; next: T | undefined }>({ count: 0, next: undefined });\n  const mounted = useRef(false);\n\n  useDevWarnings(isControlled, defaultValue !== undefined, warn);\n\n  useEffect(() => {\n    mounted.current = true;\n    return () => {\n      mounted.current = false;\n    };\n  }, []);\n\n  function dispatch(next: T, details: Details): void {\n    const prev = committed;\n    const id = ++latest.current;\n    inFlight.current.count += 1;\n    inFlight.current.next = next;\n    startOwnTransition(async () => {\n      for (const type of transitionTypes?.(next, prev, details) ?? []) addTransitionType(type);\n      setOptimistic({ next, details });\n      try {\n        await action?.(next, details);\n      } catch (error) {\n        settle();\n        // The latest dispatch's rejection takes React's own route to the boundary.\n        if (id === latest.current) throw error;\n        // Nothing to throw to once unmounted (React drops its own thenables the same way).\n        if (!mounted.current) return;\n        if (hasSupersededError.current) {\n          // One boundary reset per burst is enough; later errors are still reported.\n          report(error);\n          return;\n        }\n        hasSupersededError.current = true;\n        // Outside the transition by now (after an await), so this is an urgent update: the owner\n        // re-renders promptly and throws.\n        setSupersededError({ error });\n        return;\n      }\n      settle();\n      if (!isControlled && id === latest.current) {\n        startTransition(() => setInternal(next));\n      }\n    });\n  }\n\n  function settle(): void {\n    inFlight.current.count -= 1;\n    if (inFlight.current.count === 0) inFlight.current.next = undefined;\n  }\n\n  function latestInFlight(): { readonly next: T } | null {\n    const { count, next } = inFlight.current;\n    return count > 0 ? { next: next as T } : null;\n  }\n\n  return { committed, optimistic, pending, dispatch, latestInFlight };\n}\n\nfunction useDevWarnings(\n  isControlled: boolean,\n  hasDefault: boolean,\n  warn: { readonly component: string; readonly prop: string } | undefined,\n): void {\n  const initialMode = useRef(isControlled);\n  const warnedBoth = useRef(false);\n  const warnedSwitch = useRef(false);\n  const component = warn?.component ?? \"A component\";\n  const prop = warn?.prop ?? \"value\";\n\n  useEffect(() => {\n    if (!isDev) return;\n    const defaultProp = `default${capitalize(prop)}`;\n\n    if (isControlled && hasDefault && !warnedBoth.current) {\n      warnedBoth.current = true;\n      console.error(\n        `${component}: both \\`${prop}\\` and \\`${defaultProp}\\` are set. ` +\n          `Use \\`${prop}\\` for controlled mode or \\`${defaultProp}\\` for uncontrolled mode, not both.`,\n      );\n    }\n\n    if (initialMode.current !== isControlled && !warnedSwitch.current) {\n      warnedSwitch.current = true;\n      const from = initialMode.current ? \"controlled\" : \"uncontrolled\";\n      const to = isControlled ? \"controlled\" : \"uncontrolled\";\n      console.error(\n        `${component}: \\`${prop}\\` changed from ${from} to ${to}. Switching modes after mount ` +\n          `is not supported; keep \\`${prop}\\` either always defined or always undefined.`,\n      );\n    }\n  }, [component, prop, isControlled, hasDefault]);\n}\n"],"mappings":"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"}

package/dist/internal/use-delayed-pair.mjs

@@ -0,0 +1,40 @@
+"use client";
+import { useEffect, useState } from "react";
+//#region src/internal/use-delayed-pair.ts
+/** Plain factory, for code that owns its timers inside an effect (Tooltip). */
+function createDelayedPair() {
+	let timer;
+	let kind;
+	const cancel = () => {
+		if (timer !== void 0) clearTimeout(timer);
+		timer = void 0;
+		kind = void 0;
+	};
+	const schedule = (next, delay, callback) => {
+		cancel();
+		kind = next;
+		timer = setTimeout(() => {
+			timer = void 0;
+			kind = void 0;
+			callback();
+		}, delay);
+	};
+	return {
+		open: (delay, callback) => schedule("open", delay, callback),
+		close: (delay, callback) => schedule("close", delay, callback),
+		cancelClose: () => {
+			if (kind === "close") cancel();
+		},
+		cancel
+	};
+}
+/** One `DelayedPair` per component instance, cancelled on unmount. */
+function useDelayedPair() {
+	const [pair] = useState(createDelayedPair);
+	useEffect(() => pair.cancel, [pair]);
+	return pair;
+}
+//#endregion
+export { createDelayedPair, useDelayedPair };
+
+//# sourceMappingURL=use-delayed-pair.mjs.map

package/dist/internal/use-delayed-pair.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-delayed-pair.mjs","names":[],"sources":["../../src/internal/use-delayed-pair.ts"],"sourcesContent":["\"use client\";\nimport { useEffect, useState } from \"react\";\n\n/**\n * An open timer and a close timer that exclude each other: scheduling one cancels the other, so a\n * hover that leaves before the open delay elapses never opens, and coming back before the close\n * delay elapses never closes. Shared by Tooltip's JS path and Menu's submenu hover intent\n * (design/components/menu.md 7).\n */\nexport interface DelayedPair {\n  /** Run `callback` after `delay` ms, replacing any pending open or close. */\n  readonly open: (delay: number, callback: () => void) => void;\n  /** Run `callback` after `delay` ms, replacing any pending open or close. */\n  readonly close: (delay: number, callback: () => void) => void;\n  /** Cancel a pending close only (a pending open keeps running). */\n  readonly cancelClose: () => void;\n  /** Cancel whatever is pending. */\n  readonly cancel: () => void;\n}\n\n/** Plain factory, for code that owns its timers inside an effect (Tooltip). */\nexport function createDelayedPair(): DelayedPair {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  let kind: \"open\" | \"close\" | undefined;\n\n  const cancel = (): void => {\n    if (timer !== undefined) clearTimeout(timer);\n    timer = undefined;\n    kind = undefined;\n  };\n  const schedule = (next: \"open\" | \"close\", delay: number, callback: () => void): void => {\n    cancel();\n    kind = next;\n    timer = setTimeout(() => {\n      timer = undefined;\n      kind = undefined;\n      callback();\n    }, delay);\n  };\n\n  return {\n    open: (delay, callback) => schedule(\"open\", delay, callback),\n    close: (delay, callback) => schedule(\"close\", delay, callback),\n    cancelClose: () => {\n      if (kind === \"close\") cancel();\n    },\n    cancel,\n  };\n}\n\n/** One `DelayedPair` per component instance, cancelled on unmount. */\nexport function useDelayedPair(): DelayedPair {\n  const [pair] = useState(createDelayedPair);\n  useEffect(() => pair.cancel, [pair]);\n  return pair;\n}\n"],"mappings":";;;;AAqBA,SAAgB,oBAAiC;CAC/C,IAAI;CACJ,IAAI;CAEJ,MAAM,eAAqB;EACzB,IAAI,UAAU,KAAA,GAAW,aAAa,KAAK;EAC3C,QAAQ,KAAA;EACR,OAAO,KAAA;CACT;CACA,MAAM,YAAY,MAAwB,OAAe,aAA+B;EACtF,OAAO;EACP,OAAO;EACP,QAAQ,iBAAiB;GACvB,QAAQ,KAAA;GACR,OAAO,KAAA;GACP,SAAS;EACX,GAAG,KAAK;CACV;CAEA,OAAO;EACL,OAAO,OAAO,aAAa,SAAS,QAAQ,OAAO,QAAQ;EAC3D,QAAQ,OAAO,aAAa,SAAS,SAAS,OAAO,QAAQ;EAC7D,mBAAmB;GACjB,IAAI,SAAS,SAAS,OAAO;EAC/B;EACA;CACF;AACF;;AAGA,SAAgB,iBAA8B;CAC5C,MAAM,CAAC,QAAQ,SAAS,iBAAiB;CACzC,gBAAgB,KAAK,QAAQ,CAAC,IAAI,CAAC;CACnC,OAAO;AACT"}

package/dist/internal/use-dev-warning.mjs

@@ -0,0 +1,21 @@
+"use client";
+import { useEffect, useRef } from "react";
+//#region src/internal/use-dev-warning.ts
+const isDev = process.env.NODE_ENV !== "production";
+/**
+* Logs `message` through `console.error` once per component instance, the first time
+* `condition` is true. Runs in an effect (never during render) so the warning cannot fire for a
+* render that is discarded.
+*/
+function useDevWarning(condition, message) {
+	const warned = useRef(false);
+	useEffect(() => {
+		if (!isDev || !condition || warned.current) return;
+		warned.current = true;
+		console.error(message);
+	}, [condition, message]);
+}
+//#endregion
+export { useDevWarning };
+
+//# sourceMappingURL=use-dev-warning.mjs.map

package/dist/internal/use-dev-warning.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-dev-warning.mjs","names":[],"sources":["../../src/internal/use-dev-warning.ts"],"sourcesContent":["\"use client\";\nimport { useEffect, useRef } from \"react\";\n\nconst isDev = process.env.NODE_ENV !== \"production\";\n\n/**\n * Logs `message` through `console.error` once per component instance, the first time\n * `condition` is true. Runs in an effect (never during render) so the warning cannot fire for a\n * render that is discarded.\n */\nexport function useDevWarning(condition: boolean, message: string): void {\n  const warned = useRef(false);\n  useEffect(() => {\n    if (!isDev || !condition || warned.current) return;\n    warned.current = true;\n    console.error(message);\n  }, [condition, message]);\n}\n"],"mappings":";;;AAGA,MAAM,QAAQ,QAAQ,IAAI,aAAa;;;;;;AAOvC,SAAgB,cAAc,WAAoB,SAAuB;CACvE,MAAM,SAAS,OAAO,KAAK;CAC3B,gBAAgB;EACd,IAAI,CAAC,SAAS,CAAC,aAAa,OAAO,SAAS;EAC5C,OAAO,UAAU;EACjB,QAAQ,MAAM,OAAO;CACvB,GAAG,CAAC,WAAW,OAAO,CAAC;AACzB"}

package/dist/internal/use-exit-animation.mjs

@@ -0,0 +1,55 @@
+"use client";
+import { useRef, useState } from "react";
+//#region src/internal/use-exit-animation.ts
+/** An animation that ends: infinite ones (a spinner) would hold the content forever. */
+function ends(animation) {
+	const end = animation.effect?.getComputedTiming().endTime;
+	return typeof end === "number" && Number.isFinite(end);
+}
+/**
+* The running exit animations of a top-layer element that has just been hidden, read after a
+* style flush so that `transition-behavior: allow-discrete` exits exist. Empty where the engine
+* does not animate the exit (Firefox) or there is no CSS exit.
+*/
+function exitAnimations(element) {
+	if (!element.isConnected || typeof element.getAnimations !== "function") return [];
+	getComputedStyle(element).opacity;
+	return element.getAnimations({ subtree: true }).filter(ends);
+}
+/**
+* The deferred unmount of a top-layer popup's content while its hide animates. `held` is cleared
+* with a normal (urgent) update, never in a transition: the popup is already hidden, nothing
+* visible changes, and only transition commits start a document view transition, so a dismissal
+* runs one (its notification commit) instead of two (design 4.4).
+*/
+function useExitAnimation() {
+	const [held, setHeld] = useState(false);
+	const wait = useRef(null);
+	const generation = useRef(0);
+	const holdUntil = (animations) => {
+		const current = ++generation.current;
+		wait.current = current;
+		setHeld(true);
+		Promise.allSettled(animations.map((animation) => animation.finished)).then(() => {
+			if (generation.current !== current) return;
+			wait.current = null;
+			setHeld(false);
+		});
+	};
+	const release = () => {
+		generation.current++;
+		wait.current = null;
+		setHeld(false);
+	};
+	return {
+		held,
+		holdUntil,
+		release,
+		holdDuringRender: () => setHeld(true),
+		waiting: () => wait.current !== null
+	};
+}
+//#endregion
+export { exitAnimations, useExitAnimation };
+
+//# sourceMappingURL=use-exit-animation.mjs.map

package/dist/internal/use-exit-animation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-exit-animation.mjs","names":[],"sources":["../../src/internal/use-exit-animation.ts"],"sourcesContent":["\"use client\";\nimport { useRef, useState } from \"react\";\n\n/** An animation that ends: infinite ones (a spinner) would hold the content forever. */\nfunction ends(animation: Animation): boolean {\n  const end = animation.effect?.getComputedTiming().endTime;\n  return typeof end === \"number\" && Number.isFinite(end);\n}\n\n/**\n * The running exit animations of a top-layer element that has just been hidden, read after a\n * style flush so that `transition-behavior: allow-discrete` exits exist. Empty where the engine\n * does not animate the exit (Firefox) or there is no CSS exit.\n */\nexport function exitAnimations(element: Element): Animation[] {\n  if (!element.isConnected || typeof element.getAnimations !== \"function\") return [];\n  void getComputedStyle(element).opacity;\n  return element.getAnimations({ subtree: true }).filter(ends);\n}\n\nexport interface ExitAnimation {\n  /** Keep the content mounted (design/components/popover.md 4.4). */\n  readonly held: boolean;\n  /** Set `held` now (urgent, library-internal) and clear it when `animations` settle. */\n  readonly holdUntil: (animations: readonly Animation[]) => void;\n  /** Clear `held` now (a normal update, never a transition), cancelling any wait in progress. */\n  readonly release: () => void;\n  /** Set `held` during render (the \"previous value in state\" pattern). */\n  readonly holdDuringRender: () => void;\n  /** Whether a `holdUntil` wait is still running. Handlers and effects only. */\n  readonly waiting: () => boolean;\n}\n\n/**\n * The deferred unmount of a top-layer popup's content while its hide animates. `held` is cleared\n * with a normal (urgent) update, never in a transition: the popup is already hidden, nothing\n * visible changes, and only transition commits start a document view transition, so a dismissal\n * runs one (its notification commit) instead of two (design 4.4).\n */\nexport function useExitAnimation(): ExitAnimation {\n  const [held, setHeld] = useState(false);\n  // The generation of the wait in progress, or null; a newer wait supersedes an older one.\n  const wait = useRef<number | null>(null);\n  const generation = useRef(0);\n\n  const holdUntil = (animations: readonly Animation[]): void => {\n    const current = ++generation.current;\n    wait.current = current;\n    setHeld(true);\n    void Promise.allSettled(animations.map((animation) => animation.finished)).then(() => {\n      if (generation.current !== current) return;\n      wait.current = null;\n      setHeld(false);\n    });\n  };\n\n  const release = (): void => {\n    generation.current++;\n    wait.current = null;\n    setHeld(false);\n  };\n\n  return {\n    held,\n    holdUntil,\n    release,\n    holdDuringRender: () => setHeld(true),\n    waiting: () => wait.current !== null,\n  };\n}\n"],"mappings":";;;;AAIA,SAAS,KAAK,WAA+B;CAC3C,MAAM,MAAM,UAAU,QAAQ,kBAAkB,CAAC,CAAC;CAClD,OAAO,OAAO,QAAQ,YAAY,OAAO,SAAS,GAAG;AACvD;;;;;;AAOA,SAAgB,eAAe,SAA+B;CAC5D,IAAI,CAAC,QAAQ,eAAe,OAAO,QAAQ,kBAAkB,YAAY,OAAO,CAAC;CACjF,iBAAsB,OAAO,CAAC,CAAC;CAC/B,OAAO,QAAQ,cAAc,EAAE,SAAS,KAAK,CAAC,CAAC,CAAC,OAAO,IAAI;AAC7D;;;;;;;AAqBA,SAAgB,mBAAkC;CAChD,MAAM,CAAC,MAAM,WAAW,SAAS,KAAK;CAEtC,MAAM,OAAO,OAAsB,IAAI;CACvC,MAAM,aAAa,OAAO,CAAC;CAE3B,MAAM,aAAa,eAA2C;EAC5D,MAAM,UAAU,EAAE,WAAW;EAC7B,KAAK,UAAU;EACf,QAAQ,IAAI;EACZ,QAAa,WAAW,WAAW,KAAK,cAAc,UAAU,QAAQ,CAAC,CAAC,CAAC,WAAW;GACpF,IAAI,WAAW,YAAY,SAAS;GACpC,KAAK,UAAU;GACf,QAAQ,KAAK;EACf,CAAC;CACH;CAEA,MAAM,gBAAsB;EAC1B,WAAW;EACX,KAAK,UAAU;EACf,QAAQ,KAAK;CACf;CAEA,OAAO;EACL;EACA;EACA;EACA,wBAAwB,QAAQ,IAAI;EACpC,eAAe,KAAK,YAAY;CAClC;AACF"}

package/dist/internal/use-form-reset.mjs

@@ -0,0 +1,50 @@
+"use client";
+import { useEffectEvent, useLayoutEffect, useRef } from "react";
+//#region src/internal/use-form-reset.ts
+/**
+* Stable `reset` subscription on the form owner of `ref.current` (conventions 3.8).
+*
+* - The owner (`element.form`, which honours the `form` attribute) is re-read after every commit,
+*   but the listener is moved only when the owner changed. It is never removed and re-added on an
+*   ordinary re-render: React's automatic reset after a successful `<form action>` runs in the
+*   commit's mutation phase, between an effect's cleanup and its next run, so a subscription that
+*   followed every commit would miss it (rule 4).
+* - The `reset` event fires before the reset algorithm, so `onReset` is called in a microtask,
+*   when the inputs hold their reset values (rule 5), and only if no listener cancelled the reset
+*   (rule 7).
+* - `onReset` always sees the latest committed render's values (`useEffectEvent`).
+*/
+function useFormReset(ref, onReset) {
+	const handleReset = useEffectEvent((event) => {
+		onReset(event);
+	});
+	const subscription = useRef(null);
+	useLayoutEffect(() => {
+		const form = ref.current?.form ?? null;
+		const current = subscription.current;
+		if (current !== null && current.form === form) return;
+		if (current !== null) current.form.removeEventListener("reset", current.listener);
+		subscription.current = null;
+		if (form === null) return;
+		const listener = (event) => {
+			queueMicrotask(() => {
+				if (event.defaultPrevented) return;
+				handleReset(event);
+			});
+		};
+		form.addEventListener("reset", listener);
+		subscription.current = {
+			form,
+			listener
+		};
+	});
+	useLayoutEffect(() => () => {
+		const current = subscription.current;
+		if (current !== null) current.form.removeEventListener("reset", current.listener);
+		subscription.current = null;
+	}, []);
+}
+//#endregion
+export { useFormReset };
+
+//# sourceMappingURL=use-form-reset.mjs.map

package/dist/internal/use-form-reset.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-form-reset.mjs","names":[],"sources":["../../src/internal/use-form-reset.ts"],"sourcesContent":["\"use client\";\nimport { useEffectEvent, useLayoutEffect, useRef } from \"react\";\nimport type { RefObject } from \"react\";\n\n/** A form-associated element whose form owner the hook follows. */\nexport type FormAssociatedElement = HTMLInputElement | HTMLFieldSetElement;\n\ninterface Subscription {\n  readonly form: HTMLFormElement;\n  readonly listener: (event: Event) => void;\n}\n\n/**\n * Stable `reset` subscription on the form owner of `ref.current` (conventions 3.8).\n *\n * - The owner (`element.form`, which honours the `form` attribute) is re-read after every commit,\n *   but the listener is moved only when the owner changed. It is never removed and re-added on an\n *   ordinary re-render: React's automatic reset after a successful `<form action>` runs in the\n *   commit's mutation phase, between an effect's cleanup and its next run, so a subscription that\n *   followed every commit would miss it (rule 4).\n * - The `reset` event fires before the reset algorithm, so `onReset` is called in a microtask,\n *   when the inputs hold their reset values (rule 5), and only if no listener cancelled the reset\n *   (rule 7).\n * - `onReset` always sees the latest committed render's values (`useEffectEvent`).\n */\nexport function useFormReset(\n  ref: RefObject<FormAssociatedElement | null>,\n  onReset: (event: Event) => void,\n): void {\n  const handleReset = useEffectEvent((event: Event) => {\n    onReset(event);\n  });\n  const subscription = useRef<Subscription | null>(null);\n\n  // No deps on purpose: follows the form owner after every commit (a changed `form` attribute, the\n  // element moved to another form), but re-subscribes only when the owner actually changed.\n  useLayoutEffect(() => {\n    const form = ref.current?.form ?? null;\n    const current = subscription.current;\n    if (current !== null && current.form === form) return;\n    if (current !== null) current.form.removeEventListener(\"reset\", current.listener);\n    subscription.current = null;\n    if (form === null) return;\n    const listener = (event: Event) => {\n      queueMicrotask(() => {\n        if (event.defaultPrevented) return;\n        handleReset(event);\n      });\n    };\n    form.addEventListener(\"reset\", listener);\n    subscription.current = { form, listener };\n  });\n\n  // The only place the subscription is torn down: unmount (and StrictMode's simulated unmount,\n  // after which the effect above subscribes again).\n  useLayoutEffect(\n    () => () => {\n      const current = subscription.current;\n      if (current !== null) current.form.removeEventListener(\"reset\", current.listener);\n      subscription.current = null;\n    },\n    [],\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAyBA,SAAgB,aACd,KACA,SACM;CACN,MAAM,cAAc,gBAAgB,UAAiB;EACnD,QAAQ,KAAK;CACf,CAAC;CACD,MAAM,eAAe,OAA4B,IAAI;CAIrD,sBAAsB;EACpB,MAAM,OAAO,IAAI,SAAS,QAAQ;EAClC,MAAM,UAAU,aAAa;EAC7B,IAAI,YAAY,QAAQ,QAAQ,SAAS,MAAM;EAC/C,IAAI,YAAY,MAAM,QAAQ,KAAK,oBAAoB,SAAS,QAAQ,QAAQ;EAChF,aAAa,UAAU;EACvB,IAAI,SAAS,MAAM;EACnB,MAAM,YAAY,UAAiB;GACjC,qBAAqB;IACnB,IAAI,MAAM,kBAAkB;IAC5B,YAAY,KAAK;GACnB,CAAC;EACH;EACA,KAAK,iBAAiB,SAAS,QAAQ;EACvC,aAAa,UAAU;GAAE;GAAM;EAAS;CAC1C,CAAC;CAID,4BACc;EACV,MAAM,UAAU,aAAa;EAC7B,IAAI,YAAY,MAAM,QAAQ,KAAK,oBAAoB,SAAS,QAAQ,QAAQ;EAChF,aAAa,UAAU;CACzB,GACA,CAAC,CACH;AACF"}