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

package/dist/internal/form-status-watcher.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-status-watcher.mjs","names":[],"sources":["../../src/internal/form-status-watcher.tsx"],"sourcesContent":["\"use client\";\nimport { useEffect, useRef } from \"react\";\nimport { useFormStatus } from \"react-dom\";\n\nexport interface FormStatusWatcherProps {\n  readonly onPendingChange: (pending: boolean) => void;\n  readonly onSettled: () => void;\n}\n\n/**\n * Observes React's form channel (Dialog design 8.1, Field/Form design 3.2): rendered inside a\n * `<form>`, `useFormStatus().pending` covers the action's whole transition, including the\n * Suspense wait of what it re-renders. On `true → false` the submission settled without throwing\n * (a rejection unmounts the form through the nearest Error Boundary, so the edge is never seen).\n * Used by `Dialog.Form` and `Form.Root`.\n */\nexport function FormStatusWatcher({ onPendingChange, onSettled }: FormStatusWatcherProps) {\n  const { pending } = useFormStatus();\n  const previous = useRef(false);\n  useEffect(() => {\n    const was = previous.current;\n    previous.current = pending;\n    if (was === pending) return;\n    onPendingChange(pending);\n    if (was && !pending) onSettled();\n  }, [pending, onPendingChange, onSettled]);\n  return null;\n}\n"],"mappings":";;;;;;;;;;;AAgBA,SAAgB,kBAAkB,EAAE,iBAAiB,aAAqC;CACxF,MAAM,EAAE,YAAY,cAAc;CAClC,MAAM,WAAW,OAAO,KAAK;CAC7B,gBAAgB;EACd,MAAM,MAAM,SAAS;EACrB,SAAS,UAAU;EACnB,IAAI,QAAQ,SAAS;EACrB,gBAAgB,OAAO;EACvB,IAAI,OAAO,CAAC,SAAS,UAAU;CACjC,GAAG;EAAC;EAAS;EAAiB;CAAS,CAAC;CACxC,OAAO;AACT"}

package/dist/internal/modal-registry.mjs

@@ -0,0 +1,39 @@
+//#region src/internal/modal-registry.ts
+const stack = [];
+const listeners = /* @__PURE__ */ new Set();
+function notify() {
+	for (const listener of [...listeners]) listener();
+}
+/** Records `dialog` as the topmost open modal dialog (moves it to the top if already present). */
+function pushModal(dialog) {
+	const index = stack.indexOf(dialog);
+	if (index !== -1 && index === stack.length - 1) return;
+	if (index !== -1) stack.splice(index, 1);
+	stack.push(dialog);
+	notify();
+}
+/** Forgets `dialog` (closed or unmounted). */
+function removeModal(dialog) {
+	const index = stack.indexOf(dialog);
+	if (index === -1) return;
+	stack.splice(index, 1);
+	notify();
+}
+function subscribeModals(listener) {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}
+/** The topmost open modal dialog the library opened, or `null`. */
+function getTopmostModal() {
+	return stack.at(-1) ?? null;
+}
+/** The server snapshot: nothing is open on the server. */
+function getServerTopmostModal() {
+	return null;
+}
+//#endregion
+export { getServerTopmostModal, getTopmostModal, pushModal, removeModal, subscribeModals };
+
+//# sourceMappingURL=modal-registry.mjs.map

package/dist/internal/modal-registry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"modal-registry.mjs","names":[],"sources":["../../src/internal/modal-registry.ts"],"sourcesContent":["// No \"use client\" directive: a plain module-level store, no React and no DOM calls\n// (design/components/toast.md 4.3, conventions 3.5 \"module-level registry\").\n//\n// The stack of open modal `<dialog>` elements the library's Dialog opened. A top-layer element\n// outside the topmost modal dialog is inert and absent from the accessibility tree, so Toast's\n// Viewport portals its region into the topmost one. Writers (`use-modal-registration.ts`) run\n// in layout effects and platform event listeners, never during render; readers subscribe through\n// `useSyncExternalStore` with a server snapshot of `null`. Never the source of truth for a\n// component's own state.\n\nconst stack: Element[] = [];\nconst listeners = new Set<() => void>();\n\nfunction notify(): void {\n  for (const listener of [...listeners]) listener();\n}\n\n/** Records `dialog` as the topmost open modal dialog (moves it to the top if already present). */\nexport function pushModal(dialog: Element): void {\n  const index = stack.indexOf(dialog);\n  if (index !== -1 && index === stack.length - 1) return;\n  if (index !== -1) stack.splice(index, 1);\n  stack.push(dialog);\n  notify();\n}\n\n/** Forgets `dialog` (closed or unmounted). */\nexport function removeModal(dialog: Element): void {\n  const index = stack.indexOf(dialog);\n  if (index === -1) return;\n  stack.splice(index, 1);\n  notify();\n}\n\nexport function subscribeModals(listener: () => void): () => void {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/** The topmost open modal dialog the library opened, or `null`. */\nexport function getTopmostModal(): Element | null {\n  return stack.at(-1) ?? null;\n}\n\n/** The server snapshot: nothing is open on the server. */\nexport function getServerTopmostModal(): Element | null {\n  return null;\n}\n"],"mappings":";AAUA,MAAM,QAAmB,CAAC;AAC1B,MAAM,4BAAY,IAAI,IAAgB;AAEtC,SAAS,SAAe;CACtB,KAAK,MAAM,YAAY,CAAC,GAAG,SAAS,GAAG,SAAS;AAClD;;AAGA,SAAgB,UAAU,QAAuB;CAC/C,MAAM,QAAQ,MAAM,QAAQ,MAAM;CAClC,IAAI,UAAU,MAAM,UAAU,MAAM,SAAS,GAAG;CAChD,IAAI,UAAU,IAAI,MAAM,OAAO,OAAO,CAAC;CACvC,MAAM,KAAK,MAAM;CACjB,OAAO;AACT;;AAGA,SAAgB,YAAY,QAAuB;CACjD,MAAM,QAAQ,MAAM,QAAQ,MAAM;CAClC,IAAI,UAAU,IAAI;CAClB,MAAM,OAAO,OAAO,CAAC;CACrB,OAAO;AACT;AAEA,SAAgB,gBAAgB,UAAkC;CAChE,UAAU,IAAI,QAAQ;CACtB,aAAa;EACX,UAAU,OAAO,QAAQ;CAC3B;AACF;;AAGA,SAAgB,kBAAkC;CAChD,OAAO,MAAM,GAAG,EAAE,KAAK;AACzB;;AAGA,SAAgB,wBAAwC;CACtD,OAAO;AACT"}

package/dist/internal/range-value.mjs

@@ -0,0 +1,51 @@
+//#region src/internal/range-value.ts
+/** The platform's clamp (`<progress>` 150 of 100 is 100). A degenerate range yields `min`. */
+function clamp(value, min, max) {
+	return Math.max(min, Math.min(max, value));
+}
+/** Whether `[min, max]` is empty or a point (`max <= min`): a bug at the call site. */
+function isDegenerate(min, max) {
+	return !(max > min);
+}
+/** `(value - min) / (max - min)`, `0` for a degenerate range. */
+function fraction(value, min, max) {
+	return isDegenerate(min, max) ? 0 : (value - min) / (max - min);
+}
+/** The fraction as a number 0–100. */
+function percentage(value, min, max) {
+	return fraction(value, min, max) * 100;
+}
+const PERCENT = { style: "percent" };
+const CACHE_LIMIT = 32;
+const formatters = /* @__PURE__ */ new Map();
+/**
+* One `Intl.NumberFormat` per `locale` + `format`, so an update loop does not construct one per
+* render. Bounded: past 32 entries the oldest is dropped.
+*/
+function getNumberFormat(locale, format) {
+	const options = format ?? PERCENT;
+	const key = `${locale ?? ""}\u0000${JSON.stringify(options)}`;
+	let formatter = formatters.get(key);
+	if (formatter === void 0) {
+		formatter = new Intl.NumberFormat(locale, options);
+		if (formatters.size >= CACHE_LIMIT) {
+			const oldest = formatters.keys().next().value;
+			if (oldest !== void 0) formatters.delete(oldest);
+		}
+		formatters.set(key, formatter);
+	}
+	return formatter;
+}
+/**
+* The visible text of a (clamped) value: the fraction of the range for the `percent` style (the
+* default when `format` is absent), the value itself for any other style. A `format` without
+* `style` is `decimal` per `Intl` and formats the value.
+*/
+function formatRangeValue(value, min, max, format, locale) {
+	const percentStyle = format === void 0 || format.style === "percent";
+	return getNumberFormat(locale, format).format(percentStyle ? fraction(value, min, max) : value);
+}
+//#endregion
+export { clamp, formatRangeValue, fraction, getNumberFormat, isDegenerate, percentage };
+
+//# sourceMappingURL=range-value.mjs.map

package/dist/internal/range-value.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"range-value.mjs","names":[],"sources":["../../src/internal/range-value.ts"],"sourcesContent":["// No \"use client\": pure arithmetic and formatting shared by the directive-free `Progress.Root`\n// and `Meter.Root` (design/components/progress.md 2.1, 2.2 and implementation note 14.4).\n\n/** The platform's clamp (`<progress>` 150 of 100 is 100). A degenerate range yields `min`. */\nexport function clamp(value: number, min: number, max: number): number {\n  return Math.max(min, Math.min(max, value));\n}\n\n/** Whether `[min, max]` is empty or a point (`max <= min`): a bug at the call site. */\nexport function isDegenerate(min: number, max: number): boolean {\n  return !(max > min);\n}\n\n/** `(value - min) / (max - min)`, `0` for a degenerate range. */\nexport function fraction(value: number, min: number, max: number): number {\n  return isDegenerate(min, max) ? 0 : (value - min) / (max - min);\n}\n\n/** The fraction as a number 0–100. */\nexport function percentage(value: number, min: number, max: number): number {\n  return fraction(value, min, max) * 100;\n}\n\nconst PERCENT: Intl.NumberFormatOptions = { style: \"percent\" };\nconst CACHE_LIMIT = 32;\nconst formatters = new Map<string, Intl.NumberFormat>();\n\n/**\n * One `Intl.NumberFormat` per `locale` + `format`, so an update loop does not construct one per\n * render. Bounded: past 32 entries the oldest is dropped.\n */\nexport function getNumberFormat(\n  locale: string | undefined,\n  format: Intl.NumberFormatOptions | undefined,\n): Intl.NumberFormat {\n  const options = format ?? PERCENT;\n  const key = `${locale ?? \"\"}\\u0000${JSON.stringify(options)}`;\n  let formatter = formatters.get(key);\n  if (formatter === undefined) {\n    formatter = new Intl.NumberFormat(locale, options);\n    if (formatters.size >= CACHE_LIMIT) {\n      const oldest = formatters.keys().next().value;\n      if (oldest !== undefined) formatters.delete(oldest);\n    }\n    formatters.set(key, formatter);\n  }\n  return formatter;\n}\n\n/**\n * The visible text of a (clamped) value: the fraction of the range for the `percent` style (the\n * default when `format` is absent), the value itself for any other style. A `format` without\n * `style` is `decimal` per `Intl` and formats the value.\n */\nexport function formatRangeValue(\n  value: number,\n  min: number,\n  max: number,\n  format: Intl.NumberFormatOptions | undefined,\n  locale: string | undefined,\n): string {\n  const percentStyle = format === undefined || format.style === \"percent\";\n  return getNumberFormat(locale, format).format(percentStyle ? fraction(value, min, max) : value);\n}\n"],"mappings":";;AAIA,SAAgB,MAAM,OAAe,KAAa,KAAqB;CACrE,OAAO,KAAK,IAAI,KAAK,KAAK,IAAI,KAAK,KAAK,CAAC;AAC3C;;AAGA,SAAgB,aAAa,KAAa,KAAsB;CAC9D,OAAO,EAAE,MAAM;AACjB;;AAGA,SAAgB,SAAS,OAAe,KAAa,KAAqB;CACxE,OAAO,aAAa,KAAK,GAAG,IAAI,KAAK,QAAQ,QAAQ,MAAM;AAC7D;;AAGA,SAAgB,WAAW,OAAe,KAAa,KAAqB;CAC1E,OAAO,SAAS,OAAO,KAAK,GAAG,IAAI;AACrC;AAEA,MAAM,UAAoC,EAAE,OAAO,UAAU;AAC7D,MAAM,cAAc;AACpB,MAAM,6BAAa,IAAI,IAA+B;;;;;AAMtD,SAAgB,gBACd,QACA,QACmB;CACnB,MAAM,UAAU,UAAU;CAC1B,MAAM,MAAM,GAAG,UAAU,GAAG,QAAQ,KAAK,UAAU,OAAO;CAC1D,IAAI,YAAY,WAAW,IAAI,GAAG;CAClC,IAAI,cAAc,KAAA,GAAW;EAC3B,YAAY,IAAI,KAAK,aAAa,QAAQ,OAAO;EACjD,IAAI,WAAW,QAAQ,aAAa;GAClC,MAAM,SAAS,WAAW,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;GACxC,IAAI,WAAW,KAAA,GAAW,WAAW,OAAO,MAAM;EACpD;EACA,WAAW,IAAI,KAAK,SAAS;CAC/B;CACA,OAAO;AACT;;;;;;AAOA,SAAgB,iBACd,OACA,KACA,KACA,QACA,QACQ;CACR,MAAM,eAAe,WAAW,KAAA,KAAa,OAAO,UAAU;CAC9D,OAAO,gBAAgB,QAAQ,MAAM,CAAC,CAAC,OAAO,eAAe,SAAS,OAAO,KAAK,GAAG,IAAI,KAAK;AAChG"}

package/dist/internal/render-element.mjs

@@ -0,0 +1,54 @@
+import { mergeProps, mergeRefs } from "./merge-props.mjs";
+import { cloneElement, createElement, isValidElement } from "react";
+//#region src/internal/render-element.ts
+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";
+}
+/**
+* The ref of a part with no library ref, merged from the consumer's `ref` and a `render`
+* element's ref without memoisation (a directive-free part cannot `useMemo`, design
+* progress.md 14.1). A fresh callback ref per render is correct because every merged callback
+* returns a cleanup; a single ref is passed through untouched.
+*/
+function mergeRenderRef(consumerRef, render) {
+	const elementRef = isValidElement(render) ? render.props.ref : void 0;
+	if (consumerRef != null && elementRef != null) return mergeRefs(consumerRef, elementRef);
+	return consumerRef ?? elementRef;
+}
+/**
+* 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). Pure: the caller merges the
+* refs (`useRender` memoises the merge; a directive-free part merges unmemoised).
+*/
+function renderElement(options) {
+	const { defaultElement, render, state, className, style, children, props, libraryProps, ref } = options;
+	const partProps = {
+		...props,
+		ref,
+		className: resolveStateValue(className, state),
+		style: resolveStateValue(style, state),
+		children: resolveStateValue(children, state)
+	};
+	const controlled = libraryProps ?? {};
+	if (isValidElement(render)) {
+		const { ref: _ignored, ...elementProps } = render.props;
+		return cloneElement(render, mergeProps(partProps, elementProps, controlled));
+	}
+	const resolved = mergeProps(partProps, {}, controlled);
+	if (typeof render === "function") return render(resolved, state);
+	return createElement(defaultElement, resolved);
+}
+//#endregion
+export { mergeRenderRef, renderElement, rendersButton, resolveStateValue };
+
+//# sourceMappingURL=render-element.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render-element.mjs","names":[],"sources":["../../src/internal/render-element.ts"],"sourcesContent":["// No \"use client\": the pure half of `useRender`, usable from a directive-free part (a Root that\n// may run as a Server Component, design/components/progress.md 8.1 and implementation note 14.1).\nimport { cloneElement, createElement, isValidElement } from \"react\";\nimport type { CSSProperties, ReactNode, Ref } from \"react\";\nimport { mergeProps, mergeRefs } from \"./merge-props.js\";\nimport type { RenderProp, StateValue } from \"./types.js\";\n\nexport interface 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 RenderElementOptions<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  /**\n   * The part's pass-through props for the element. A `render` element's own props win over\n   * these. Their `ref` is replaced by `ref` below.\n   */\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  /**\n   * The element's ref, already merged from the library's ref, the consumer's `ref` and the\n   * `render` element's ref. The `render` element's own ref is not attached separately.\n   */\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 * The ref of a part with no library ref, merged from the consumer's `ref` and a `render`\n * element's ref without memoisation (a directive-free part cannot `useMemo`, design\n * progress.md 14.1). A fresh callback ref per render is correct because every merged callback\n * returns a cleanup; a single ref is passed through untouched.\n */\nexport function mergeRenderRef(\n  consumerRef: Ref<unknown> | undefined,\n  render: unknown,\n): Ref<unknown> | undefined {\n  const elementRef = isValidElement<ElementLikeProps>(render) ? render.props.ref : undefined;\n  if (consumerRef != null && elementRef != null) return mergeRefs(consumerRef, elementRef);\n  return consumerRef ?? elementRef;\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). Pure: the caller merges the\n * refs (`useRender` memoises the merge; a directive-free part merges unmemoised).\n */\nexport function renderElement<Props extends ElementLikeProps, State>(\n  options: RenderElementOptions<Props, State>,\n): ReactNode {\n  const { defaultElement, render, state, className, style, children, props, libraryProps, ref } =\n    options;\n\n  const partProps = {\n    ...props,\n    ref,\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 (isValidElement<ElementLikeProps>(render)) {\n    // The element's ref is already part of `ref`.\n    const { ref: _ignored, ...elementProps } = render.props as Record<string, unknown>;\n    return cloneElement(render, mergeProps(partProps, elementProps, controlled) as Partial<Props>);\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":";;;AA2CA,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;;;;;;;AAQA,SAAgB,eACd,aACA,QAC0B;CAC1B,MAAM,aAAa,eAAiC,MAAM,IAAI,OAAO,MAAM,MAAM,KAAA;CACjF,IAAI,eAAe,QAAQ,cAAc,MAAM,OAAO,UAAU,aAAa,UAAU;CACvF,OAAO,eAAe;AACxB;;;;;;AAOA,SAAgB,cACd,SACW;CACX,MAAM,EAAE,gBAAgB,QAAQ,OAAO,WAAW,OAAO,UAAU,OAAO,cAAc,QACtF;CAEF,MAAM,YAAY;EAChB,GAAG;EACH;EACA,WAAW,kBAAkB,WAAW,KAAK;EAC7C,OAAO,kBAAkB,OAAO,KAAK;EACrC,UAAU,kBAAkB,UAAU,KAAK;CAC7C;CACA,MAAM,aAAc,gBAAgB,CAAC;CAErC,IAAI,eAAiC,MAAM,GAAG;EAE5C,MAAM,EAAE,KAAK,UAAU,GAAG,iBAAiB,OAAO;EAClD,OAAO,aAAa,QAAQ,WAAW,WAAW,cAAc,UAAU,CAAmB;CAC/F;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"}

package/dist/internal/toolbar-context.mjs

@@ -0,0 +1,17 @@
+"use client";
+import { createContext, use } from "react";
+//#region src/internal/toolbar-context.ts
+/**
+* Provided by `Toolbar.Root`; read across folders by `ToggleGroup.Root` (joins the Toolbar's
+* sequence instead of running its own engine), `Toolbar.Separator` (perpendicular orientation)
+* and `Menu.Trigger` (opening arrows in a vertical Toolbar). Conventions 7.1.
+*/
+const ToolbarContext = createContext(null);
+/** The enclosing Toolbar, or `null` outside one. Works during SSR (context, not DOM). */
+function useToolbarContext() {
+	return use(ToolbarContext);
+}
+//#endregion
+export { ToolbarContext, useToolbarContext };
+
+//# sourceMappingURL=toolbar-context.mjs.map

package/dist/internal/toolbar-context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolbar-context.mjs","names":[],"sources":["../../src/internal/toolbar-context.ts"],"sourcesContent":["\"use client\";\nimport { createContext, use } from \"react\";\n\n/** What a part inside a `Toolbar.Root` learns about it (design/components/toggle-group.md 7.3, 7.4). */\nexport interface ToolbarContextValue {\n  /** The Toolbar's arrow-key axis. */\n  readonly orientation: \"horizontal\" | \"vertical\";\n}\n\n/**\n * Provided by `Toolbar.Root`; read across folders by `ToggleGroup.Root` (joins the Toolbar's\n * sequence instead of running its own engine), `Toolbar.Separator` (perpendicular orientation)\n * and `Menu.Trigger` (opening arrows in a vertical Toolbar). Conventions 7.1.\n */\nexport const ToolbarContext = createContext<ToolbarContextValue | null>(null);\n\n/** The enclosing Toolbar, or `null` outside one. Works during SSR (context, not DOM). */\nexport function useToolbarContext(): ToolbarContextValue | null {\n  return use(ToolbarContext);\n}\n"],"mappings":";;;;;;;;AAcA,MAAa,iBAAiB,cAA0C,IAAI;;AAG5E,SAAgB,oBAAgD;CAC9D,OAAO,IAAI,cAAc;AAC3B"}

package/dist/internal/types.d.mts

@@ -32,8 +32,10 @@ export type UrgentChangeAction<T, Details extends ActionDetails = ActionDetails>
  *   `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`).
+ * - `"timeout"`: the library's own timer closed the component; no user gesture and no platform
+ *   event (`event` is `undefined`). Toast's auto-dismiss is the only user.
  */
-export type ChangeReason = "activate" | "dismiss" | "platform";
+export type ChangeReason = "activate" | "dismiss" | "platform" | "timeout";
 /** 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);
 /**

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

@@ -1 +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;;;;;;;;YAUT,mBAAmB,GAAG,gBAAgB,gBAAgB,kBAChE,MAAM,GACN,SAAS;;;;;;;;;;;;;YAeC;;YAGA,WAAW,GAAG,SAAS,MAAM,OAAO,UAAU;;;;;;YAO9C,WAAW,OAAO,SAC1B,aAAa,QAAQ,YACnB,OAAO,OAAO,OAAO,UAAU"}
+{"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;;;;;;;;YAUT,mBAAmB,GAAG,gBAAgB,gBAAgB,kBAChE,MAAM,GACN,SAAS;;;;;;;;;;;;;;;YAiBC;;YAGA,WAAW,GAAG,SAAS,MAAM,OAAO,UAAU;;;;;;YAO9C,WAAW,OAAO,SAC1B,aAAa,QAAQ,YACnB,OAAO,OAAO,OAAO,UAAU"}

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

@@ -1,5 +1,6 @@
 "use client";
-import { addTransitionType, startTransition, useEffect, useOptimistic, useRef, useState, useTransition } from "react";
+import { useLatest } from "./use-latest.mjs";
+import { addTransitionType, startTransition, useCallback, useEffect, useMemo, useOptimistic, useRef, useState, useTransition } from "react";
 //#region src/internal/use-controllable-action.ts
 const isDev = process.env.NODE_ENV !== "production";
 function capitalize(s) {
@@ -39,8 +40,18 @@ function useControllableAction(options) {
 			mounted.current = false;
 		};
 	}, []);
-	function dispatch(next, details) {
-		const prev = committed;
+	const props = useLatest({
+		committed,
+		isControlled,
+		action,
+		transitionTypes
+	});
+	const settle = useCallback(() => {
+		inFlight.current.count -= 1;
+		if (inFlight.current.count === 0) inFlight.current.next = void 0;
+	}, []);
+	const dispatch = useCallback((next, details) => {
+		const { committed: prev, isControlled, action, transitionTypes } = props.current;
 		const id = ++latest.current;
 		inFlight.current.count += 1;
 		inFlight.current.next = next;
@@ -67,26 +78,33 @@ function useControllableAction(options) {
 			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() {
+	}, [
+		props,
+		settle,
+		setOptimistic
+	]);
+	const latestInFlight = useCallback(() => {
 		const { count, next } = inFlight.current;
 		return count > 0 ? { next } : null;
-	}
-	function adopt(next) {
-		if (!isControlled) setInternal(next);
-	}
-	return {
+	}, []);
+	const adopt = useCallback((next) => {
+		if (!props.current.isControlled) setInternal(next);
+	}, [props]);
+	return useMemo(() => ({
 		committed,
 		optimistic,
 		pending,
 		dispatch,
 		latestInFlight,
 		adopt
-	};
+	}), [
+		committed,
+		optimistic,
+		pending,
+		dispatch,
+		latestInFlight,
+		adopt
+	]);
 }
 function useDevWarnings(isControlled, hasDefault, warn) {
 	const initialMode = useRef(isControlled);

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

@@ -1 +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   * Uncontrolled mode only (a no-op when controlled): writes the committed value without calling\n   * the action, without an optimistic step and without a transition. For a component that adopts\n   * a default the browser chose (Select with neither `value` nor `defaultValue` takes the first\n   * enabled option, design/components/select.md 5). Call it from a layout effect so the write is\n   * flushed before paint.\n   */\n  readonly adopt: (next: T) => void;\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  function adopt(next: T): void {\n    if (!isControlled) setInternal(next);\n  }\n\n  return { committed, optimistic, pending, dispatch, latestInFlight, adopt };\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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"}
+{"version":3,"file":"use-controllable-action.mjs","names":[],"sources":["../../src/internal/use-controllable-action.ts"],"sourcesContent":["\"use client\";\nimport {\n  addTransitionType,\n  startTransition,\n  useCallback,\n  useEffect,\n  useMemo,\n  useOptimistic,\n  useRef,\n  useState,\n  useTransition,\n} from \"react\";\nimport type { ActionDetails, ChangeAction } from \"./types.js\";\nimport { useLatest } from \"./use-latest.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   * Uncontrolled mode only (a no-op when controlled): writes the committed value without calling\n   * the action, without an optimistic step and without a transition. For a component that adopts\n   * a default the browser chose (Select with neither `value` nor `defaultValue` takes the first\n   * enabled option, design/components/select.md 5). Call it from a layout effect so the write is\n   * flushed before paint.\n   */\n  readonly adopt: (next: T) => void;\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  // The functions below keep one identity for the hook's lifetime, so the returned object changes\n  // only with `committed`, `optimistic` and `pending`, and the components' memoised context values\n  // are reused across renders that change none of them (#48). They read the props of the last\n  // committed render through `props`; they run from handlers, actions and effects, never render.\n  const props = useLatest({ committed, isControlled, action, transitionTypes });\n\n  const settle = useCallback((): void => {\n    inFlight.current.count -= 1;\n    if (inFlight.current.count === 0) inFlight.current.next = undefined;\n  }, []);\n\n  const dispatch = useCallback(\n    (next: T, details: Details): void => {\n      // Read once, at the call, as the per-render closure did: the action, the mode and the\n      // previous value belong to the UI the user acted on, even after the `await`.\n      const { committed: prev, isControlled, action, transitionTypes } = props.current;\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\n          // owner 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    [props, settle, setOptimistic],\n  );\n\n  const latestInFlight = useCallback((): { readonly next: T } | null => {\n    const { count, next } = inFlight.current;\n    return count > 0 ? { next: next as T } : null;\n  }, []);\n\n  const adopt = useCallback(\n    (next: T): void => {\n      if (!props.current.isControlled) setInternal(next);\n    },\n    [props],\n  );\n\n  return useMemo(\n    () => ({ committed, optimistic, pending, dispatch, latestInFlight, adopt }),\n    [committed, optimistic, pending, dispatch, latestInFlight, adopt],\n  );\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-exit-animation.mjs

@@ -7,14 +7,25 @@ function ends(animation) {
 	return typeof end === "number" && Number.isFinite(end);
 }
 /**
+* The animations running in an element's subtree right before it closes (the synchronous
+* `beforetoggle` of the hide, Toast's `data-ending` write): the baseline that `exitAnimations`
+* excludes, so a finite animation already running inside (a progress bar) does not hold the exit
+* (Toast 10.2, #64). Empty where `getAnimations` is absent (jsdom).
+*/
+function animationBaseline(element) {
+	if (!element.isConnected || typeof element.getAnimations !== "function") return /* @__PURE__ */ new Set();
+	return new Set(element.getAnimations({ subtree: true }));
+}
+/**
 * 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.
+* style flush so that `transition-behavior: allow-discrete` exits exist, minus the `baseline`
+* of animations that were already running before the close. Empty where the engine does not
+* animate the exit (Firefox) or there is no CSS exit.
 */
-function exitAnimations(element) {
+function exitAnimations(element, baseline) {
 	if (!element.isConnected || typeof element.getAnimations !== "function") return [];
 	getComputedStyle(element).opacity;
-	return element.getAnimations({ subtree: true }).filter(ends);
+	return element.getAnimations({ subtree: true }).filter((animation) => ends(animation) && !(baseline?.has(animation) ?? false));
 }
 /**
 * The deferred unmount of a top-layer popup's content while its hide animates. `held` is cleared
@@ -26,6 +37,7 @@ function useExitAnimation() {
 	const [held, setHeld] = useState(false);
 	const wait = useRef(null);
 	const generation = useRef(0);
+	const baseline = useRef(null);
 	const holdUntil = (animations) => {
 		const current = ++generation.current;
 		wait.current = current;
@@ -46,10 +58,18 @@ function useExitAnimation() {
 		holdUntil,
 		release,
 		holdDuringRender: () => setHeld(true),
-		waiting: () => wait.current !== null
+		waiting: () => wait.current !== null,
+		recordBaseline: (element) => {
+			baseline.current = animationBaseline(element);
+		},
+		exitAnimations: (element) => {
+			const recorded = baseline.current ?? void 0;
+			baseline.current = null;
+			return exitAnimations(element, recorded);
+		}
 	};
 }
 //#endregion
-export { exitAnimations, useExitAnimation };
+export { animationBaseline, exitAnimations, useExitAnimation };
 
 //# sourceMappingURL=use-exit-animation.mjs.map

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

@@ -1 +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"}
+{"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 animations running in an element's subtree right before it closes (the synchronous\n * `beforetoggle` of the hide, Toast's `data-ending` write): the baseline that `exitAnimations`\n * excludes, so a finite animation already running inside (a progress bar) does not hold the exit\n * (Toast 10.2, #64). Empty where `getAnimations` is absent (jsdom).\n */\nexport function animationBaseline(element: Element): ReadonlySet<Animation> {\n  if (!element.isConnected || typeof element.getAnimations !== \"function\") return new Set();\n  return new Set(element.getAnimations({ subtree: true }));\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, minus the `baseline`\n * of animations that were already running before the close. Empty where the engine does not\n * animate the exit (Firefox) or there is no CSS exit.\n */\nexport function exitAnimations(element: Element, baseline?: ReadonlySet<Animation>): Animation[] {\n  if (!element.isConnected || typeof element.getAnimations !== \"function\") return [];\n  void getComputedStyle(element).opacity;\n  return element\n    .getAnimations({ subtree: true })\n    .filter((animation) => ends(animation) && !(baseline?.has(animation) ?? false));\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   * Record the animations already running in `element`'s subtree. Call from the synchronous\n   * `beforetoggle` of a close, before the hide starts the exit (#64).\n   */\n  readonly recordBaseline: (element: Element) => void;\n  /** `exitAnimations(element)` minus the recorded baseline, which it consumes. */\n  readonly exitAnimations: (element: Element) => Animation[];\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  // The animations running right before the latest close (#64), consumed by `exitAnimations`.\n  const baseline = useRef<ReadonlySet<Animation> | null>(null);\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    recordBaseline: (element) => {\n      baseline.current = animationBaseline(element);\n    },\n    exitAnimations: (element) => {\n      const recorded = baseline.current ?? undefined;\n      baseline.current = null;\n      return exitAnimations(element, recorded);\n    },\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;;;;;;;AAQA,SAAgB,kBAAkB,SAA0C;CAC1E,IAAI,CAAC,QAAQ,eAAe,OAAO,QAAQ,kBAAkB,YAAY,uBAAO,IAAI,IAAI;CACxF,OAAO,IAAI,IAAI,QAAQ,cAAc,EAAE,SAAS,KAAK,CAAC,CAAC;AACzD;;;;;;;AAQA,SAAgB,eAAe,SAAkB,UAAgD;CAC/F,IAAI,CAAC,QAAQ,eAAe,OAAO,QAAQ,kBAAkB,YAAY,OAAO,CAAC;CACjF,iBAAsB,OAAO,CAAC,CAAC;CAC/B,OAAO,QACJ,cAAc,EAAE,SAAS,KAAK,CAAC,CAAC,CAChC,QAAQ,cAAc,KAAK,SAAS,KAAK,EAAE,UAAU,IAAI,SAAS,KAAK,MAAM;AAClF;;;;;;;AA4BA,SAAgB,mBAAkC;CAChD,MAAM,CAAC,MAAM,WAAW,SAAS,KAAK;CAEtC,MAAM,OAAO,OAAsB,IAAI;CACvC,MAAM,aAAa,OAAO,CAAC;CAE3B,MAAM,WAAW,OAAsC,IAAI;CAE3D,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;EAChC,iBAAiB,YAAY;GAC3B,SAAS,UAAU,kBAAkB,OAAO;EAC9C;EACA,iBAAiB,YAAY;GAC3B,MAAM,WAAW,SAAS,WAAW,KAAA;GACrC,SAAS,UAAU;GACnB,OAAO,eAAe,SAAS,QAAQ;EACzC;CACF;AACF"}

package/dist/internal/use-field-control.mjs

@@ -0,0 +1,109 @@
+"use client";
+import { dataAttr } from "./data-attr.mjs";
+import { mergeRefs } from "./merge-props.mjs";
+import { useDevWarning } from "./use-dev-warning.mjs";
+import { FieldContext } from "./field-context.mjs";
+import { use, useCallback, useLayoutEffect, useMemo, useRef } from "react";
+//#region src/internal/use-field-control.ts
+/**
+* The owned props of a labelable native control (`<input>`, `<select>`) inside a Field: the
+* ARIA wiring plus `name` and `required` ("own or the Field's"). Empty outside a Field, so the
+* consumer's own `id` / `name` / `required` keep passing through untouched there.
+*/
+function fieldInputProps(field) {
+	if (!field.inField) return {};
+	return {
+		...field.attributes,
+		name: field.name,
+		required: field.required
+	};
+}
+/** `mergeRefs` with a stable identity while both refs keep theirs. */
+function useMergedRef(a, b) {
+	return useMemo(() => b === void 0 ? a : a === void 0 ? b : mergeRefs(a, b), [a, b]);
+}
+/**
+* The contract between a Field and its control (design/components/field-form.md 7.1), called by
+* `Field.Control` and by the owner part of every FUNSTACK form control. Outside a `Field.Root` it
+* returns the control's own props and nothing to merge.
+*
+* Inside a Field: registers the element from the returned ref (the Field attaches its listeners
+* and reads validity there; a group's `<fieldset>` makes `Field.Label` drop `for`), resolves "own
+* or the Field's" for `name` / `disabled` / `required`, and returns the owned ARIA wiring.
+*/
+function useFieldControl(options) {
+	const { labelable, name, disabled = false, required = false, id, component, validityElement } = options;
+	const field = use(FieldContext);
+	const registerControl = field?.registerControl;
+	const ref = useCallback((element) => {
+		if (registerControl === void 0) return () => {};
+		return registerControl({
+			element,
+			labelable,
+			required,
+			disabled,
+			validityElement
+		});
+	}, [
+		registerControl,
+		labelable,
+		required,
+		disabled,
+		validityElement
+	]);
+	useDevWarning(field !== null && id !== void 0, `${component}: the \`id\` prop is ignored inside a Field.Root; the Field owns the control's id so that Field.Label can point at it.`);
+	useDevWarning(field !== null && name !== void 0 && field.name !== void 0 && name !== field.name, `${component}: its \`name\` ("${name}") differs from the Field.Root's ("${field?.name}"). The Field reads server errors and \`validate\`'s value by the Field's name.`);
+	if (field === null) return {
+		inField: false,
+		ref: void 0,
+		id,
+		name,
+		disabled,
+		required,
+		attributes: {},
+		state: void 0
+	};
+	const { ids, state } = field;
+	const attributes = {
+		"aria-describedby": state.invalid ? `${ids.description} ${ids.error}` : ids.description,
+		"aria-invalid": state.invalid ? "true" : "false",
+		"data-invalid": dataAttr(state.invalid)
+	};
+	if (labelable) attributes.id = ids.control;
+	else attributes["aria-labelledby"] = ids.label;
+	return {
+		inField: true,
+		ref,
+		id: labelable ? ids.control : void 0,
+		name: name ?? field.name,
+		disabled: disabled || field.disabled,
+		required: required || field.required,
+		attributes,
+		state
+	};
+}
+/**
+* Tells the enclosing Field (if any) that the control's value changed, after the commit that
+* wrote it to the DOM (design/components/field-form.md 2.1: `validate` and the mirror follow the
+* value). Needed where the DOM changes without an `input` / `change` event the Field hears: a
+* Combobox selection (React writes the hidden input), a CheckboxGroup's derived `required`, a
+* Parent checking Items, a rejected action rolling the value back. Nothing at mount.
+*
+* `takeEdit` is read when the value changed: `true` when the user made this change (a shown
+* server error is dismissed, like an `input` event would). Native controls whose own events
+* already dismiss pass nothing.
+*/
+function useFieldValueChange(value, takeEdit) {
+	const notifyChange = use(FieldContext)?.notifyChange;
+	const previous = useRef(value);
+	useLayoutEffect(() => {
+		if (Object.is(previous.current, value)) return;
+		previous.current = value;
+		const edit = takeEdit?.() ?? false;
+		notifyChange?.(edit);
+	});
+}
+//#endregion
+export { fieldInputProps, useFieldControl, useFieldValueChange, useMergedRef };
+
+//# sourceMappingURL=use-field-control.mjs.map

package/dist/internal/use-field-control.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-field-control.mjs","names":[],"sources":["../../src/internal/use-field-control.ts"],"sourcesContent":["\"use client\";\nimport { use, useCallback, useLayoutEffect, useMemo, useRef } from \"react\";\nimport type { Ref, RefCallback } from \"react\";\nimport { dataAttr } from \"./data-attr.js\";\nimport { FieldContext } from \"./field-context.js\";\nimport type { FieldState } from \"./field-context.js\";\nimport { mergeRefs } from \"./merge-props.js\";\nimport { useDevWarning } from \"./use-dev-warning.js\";\nimport type { ValidatableElement } from \"./validity.js\";\n\nexport interface UseFieldControlOptions {\n  /** `<label for>` can target the element (input, select, textarea). Groups pass `false`. */\n  readonly labelable: boolean;\n  /** The control's own props, so \"own or the Field's\" can be computed. */\n  readonly name?: string | undefined;\n  readonly disabled?: boolean | undefined;\n  readonly required?: boolean | undefined;\n  /** The consumer's own `id` prop: ignored inside a Field (the Field owns it), with a warning. */\n  readonly id?: string | undefined;\n  /** Dev warning tag. */\n  readonly component: string;\n  /**\n   * The element whose validity is real when it is not the registered one (NumberField's hidden\n   * number input; field-form.md amendment `validityElement`). Keep its identity stable.\n   */\n  readonly validityElement?: (() => ValidatableElement | null) | undefined;\n}\n\n/** The ARIA and state attributes a part spreads into its owned layer. */\nexport interface FieldControlAttributes {\n  /** Labelable controls only: the id `Field.Label`'s `for` points at. */\n  id?: string;\n  \"aria-labelledby\"?: string;\n  \"aria-describedby\"?: string;\n  \"aria-invalid\"?: \"true\" | \"false\";\n  \"data-invalid\"?: \"\" | undefined;\n}\n\nexport interface FieldControlBinding {\n  /** The control is inside a `Field.Root`. */\n  readonly inField: boolean;\n  /** Merge into the part's library ref: registers the element with the Field. `undefined` outside a Field. */\n  readonly ref: RefCallback<HTMLElement> | undefined;\n  /** The control id the Field's Label points at (labelable controls inside a Field), else the consumer's. */\n  readonly id: string | undefined;\n  /** Own `name` ?? the Field's. */\n  readonly name: string | undefined;\n  /** Own `disabled` || the Field's. */\n  readonly disabled: boolean;\n  /** Own `required` || the Field's. */\n  readonly required: boolean;\n  /**\n   * Owned attributes: `id` (labelable controls), `aria-invalid`, `data-invalid`,\n   * `aria-labelledby` (groups) and `aria-describedby` (both token-merged by the owned layer, the\n   * consumer's tokens first). Empty outside a Field, so nothing is owned there.\n   */\n  readonly attributes: FieldControlAttributes;\n  /** The Field's state, `undefined` outside a Field. */\n  readonly state: FieldState | undefined;\n}\n\n/**\n * The owned props of a labelable native control (`<input>`, `<select>`) inside a Field: the\n * ARIA wiring plus `name` and `required` (\"own or the Field's\"). Empty outside a Field, so the\n * consumer's own `id` / `name` / `required` keep passing through untouched there.\n */\nexport function fieldInputProps(field: FieldControlBinding): FieldControlAttributes & {\n  name?: string | undefined;\n  required?: boolean;\n} {\n  if (!field.inField) return {};\n  return { ...field.attributes, name: field.name, required: field.required };\n}\n\n/** `mergeRefs` with a stable identity while both refs keep theirs. */\nexport function useMergedRef<T>(\n  a: Ref<T> | undefined,\n  b: Ref<T> | undefined,\n): RefCallback<T> | Ref<T> | undefined {\n  return useMemo(() => (b === undefined ? a : a === undefined ? b : mergeRefs(a, b)), [a, b]);\n}\n\n/**\n * The contract between a Field and its control (design/components/field-form.md 7.1), called by\n * `Field.Control` and by the owner part of every FUNSTACK form control. Outside a `Field.Root` it\n * returns the control's own props and nothing to merge.\n *\n * Inside a Field: registers the element from the returned ref (the Field attaches its listeners\n * and reads validity there; a group's `<fieldset>` makes `Field.Label` drop `for`), resolves \"own\n * or the Field's\" for `name` / `disabled` / `required`, and returns the owned ARIA wiring.\n */\nexport function useFieldControl(options: UseFieldControlOptions): FieldControlBinding {\n  const {\n    labelable,\n    name,\n    disabled = false,\n    required = false,\n    id,\n    component,\n    validityElement,\n  } = options;\n  const field = use(FieldContext);\n  const registerControl = field?.registerControl;\n\n  const ref = useCallback(\n    (element: HTMLElement) => {\n      if (registerControl === undefined) return () => {};\n      return registerControl({ element, labelable, required, disabled, validityElement });\n    },\n    [registerControl, labelable, required, disabled, validityElement],\n  );\n\n  useDevWarning(\n    field !== null && id !== undefined,\n    `${component}: the \\`id\\` prop is ignored inside a Field.Root; the Field owns the control's ` +\n      \"id so that Field.Label can point at it.\",\n  );\n  useDevWarning(\n    field !== null && name !== undefined && field.name !== undefined && name !== field.name,\n    `${component}: its \\`name\\` (\"${name}\") differs from the Field.Root's (\"${field?.name}\"). ` +\n      \"The Field reads server errors and `validate`'s value by the Field's name.\",\n  );\n\n  if (field === null) {\n    return {\n      inField: false,\n      ref: undefined,\n      id,\n      name,\n      disabled,\n      required,\n      attributes: {},\n      state: undefined,\n    };\n  }\n\n  const { ids, state } = field;\n  const attributes: FieldControlAttributes = {\n    \"aria-describedby\": state.invalid ? `${ids.description} ${ids.error}` : ids.description,\n    \"aria-invalid\": state.invalid ? \"true\" : \"false\",\n    \"data-invalid\": dataAttr(state.invalid),\n  };\n  if (labelable) attributes.id = ids.control;\n  else attributes[\"aria-labelledby\"] = ids.label;\n\n  return {\n    inField: true,\n    ref: ref as RefCallback<HTMLElement>,\n    id: labelable ? ids.control : undefined,\n    name: name ?? field.name,\n    disabled: disabled || field.disabled,\n    required: required || field.required,\n    attributes,\n    state,\n  };\n}\n\n/**\n * Tells the enclosing Field (if any) that the control's value changed, after the commit that\n * wrote it to the DOM (design/components/field-form.md 2.1: `validate` and the mirror follow the\n * value). Needed where the DOM changes without an `input` / `change` event the Field hears: a\n * Combobox selection (React writes the hidden input), a CheckboxGroup's derived `required`, a\n * Parent checking Items, a rejected action rolling the value back. Nothing at mount.\n *\n * `takeEdit` is read when the value changed: `true` when the user made this change (a shown\n * server error is dismissed, like an `input` event would). Native controls whose own events\n * already dismiss pass nothing.\n */\nexport function useFieldValueChange(value: unknown, takeEdit?: () => boolean): void {\n  const notifyChange = use(FieldContext)?.notifyChange;\n  const previous = useRef(value);\n  // No deps: compares with the last committed value after every commit of the caller.\n  useLayoutEffect(() => {\n    if (Object.is(previous.current, value)) return;\n    previous.current = value;\n    const edit = takeEdit?.() ?? false;\n    notifyChange?.(edit);\n  });\n}\n"],"mappings":";;;;;;;;;;;;AAkEA,SAAgB,gBAAgB,OAG9B;CACA,IAAI,CAAC,MAAM,SAAS,OAAO,CAAC;CAC5B,OAAO;EAAE,GAAG,MAAM;EAAY,MAAM,MAAM;EAAM,UAAU,MAAM;CAAS;AAC3E;;AAGA,SAAgB,aACd,GACA,GACqC;CACrC,OAAO,cAAe,MAAM,KAAA,IAAY,IAAI,MAAM,KAAA,IAAY,IAAI,UAAU,GAAG,CAAC,GAAI,CAAC,GAAG,CAAC,CAAC;AAC5F;;;;;;;;;;AAWA,SAAgB,gBAAgB,SAAsD;CACpF,MAAM,EACJ,WACA,MACA,WAAW,OACX,WAAW,OACX,IACA,WACA,oBACE;CACJ,MAAM,QAAQ,IAAI,YAAY;CAC9B,MAAM,kBAAkB,OAAO;CAE/B,MAAM,MAAM,aACT,YAAyB;EACxB,IAAI,oBAAoB,KAAA,GAAW,aAAa,CAAC;EACjD,OAAO,gBAAgB;GAAE;GAAS;GAAW;GAAU;GAAU;EAAgB,CAAC;CACpF,GACA;EAAC;EAAiB;EAAW;EAAU;EAAU;CAAe,CAClE;CAEA,cACE,UAAU,QAAQ,OAAO,KAAA,GACzB,GAAG,UAAU,uHAEf;CACA,cACE,UAAU,QAAQ,SAAS,KAAA,KAAa,MAAM,SAAS,KAAA,KAAa,SAAS,MAAM,MACnF,GAAG,UAAU,mBAAmB,KAAK,qCAAqC,OAAO,KAAK,gFAExF;CAEA,IAAI,UAAU,MACZ,OAAO;EACL,SAAS;EACT,KAAK,KAAA;EACL;EACA;EACA;EACA;EACA,YAAY,CAAC;EACb,OAAO,KAAA;CACT;CAGF,MAAM,EAAE,KAAK,UAAU;CACvB,MAAM,aAAqC;EACzC,oBAAoB,MAAM,UAAU,GAAG,IAAI,YAAY,GAAG,IAAI,UAAU,IAAI;EAC5E,gBAAgB,MAAM,UAAU,SAAS;EACzC,gBAAgB,SAAS,MAAM,OAAO;CACxC;CACA,IAAI,WAAW,WAAW,KAAK,IAAI;MAC9B,WAAW,qBAAqB,IAAI;CAEzC,OAAO;EACL,SAAS;EACJ;EACL,IAAI,YAAY,IAAI,UAAU,KAAA;EAC9B,MAAM,QAAQ,MAAM;EACpB,UAAU,YAAY,MAAM;EAC5B,UAAU,YAAY,MAAM;EAC5B;EACA;CACF;AACF;;;;;;;;;;;;AAaA,SAAgB,oBAAoB,OAAgB,UAAgC;CAClF,MAAM,eAAe,IAAI,YAAY,CAAC,EAAE;CACxC,MAAM,WAAW,OAAO,KAAK;CAE7B,sBAAsB;EACpB,IAAI,OAAO,GAAG,SAAS,SAAS,KAAK,GAAG;EACxC,SAAS,UAAU;EACnB,MAAM,OAAO,WAAW,KAAK;EAC7B,eAAe,IAAI;CACrB,CAAC;AACH"}

package/dist/internal/use-form-owner-event.mjs

@@ -0,0 +1,44 @@
+"use client";
+import { useEffectEvent, useLayoutEffect, useRef } from "react";
+//#region src/internal/use-form-owner-event.ts
+/**
+* Stable subscription to `type` on the form owner of `ref.current` (conventions 3.8 rule 4,
+* generalised for Field, design/components/field-form.md 14).
+*
+* - 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.
+* - `handler` always sees the latest committed render's values (`useEffectEvent`).
+* - `ref.current` may be any element: one without a `form` property has no owner.
+*/
+function useFormOwnerEvent(ref, type, handler) {
+	const handle = useEffectEvent((event, form) => {
+		handler(event, form);
+	});
+	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(type, current.listener);
+		subscription.current = null;
+		if (form === null) return;
+		const listener = (event) => handle(event, form);
+		form.addEventListener(type, listener);
+		subscription.current = {
+			form,
+			listener
+		};
+	});
+	useLayoutEffect(() => () => {
+		const current = subscription.current;
+		if (current !== null) current.form.removeEventListener(type, current.listener);
+		subscription.current = null;
+	}, [type]);
+}
+//#endregion
+export { useFormOwnerEvent };
+
+//# sourceMappingURL=use-form-owner-event.mjs.map