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

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,22 +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;
-	}
-	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
-	};
+		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\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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"}
+{"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-field-control.mjs

@@ -0,0 +1,107 @@
+"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 } = options;
+	const field = use(FieldContext);
+	const registerControl = field?.registerControl;
+	const ref = useCallback((element) => {
+		if (registerControl === void 0) return () => {};
+		return registerControl({
+			element,
+			labelable,
+			required,
+			disabled
+		});
+	}, [
+		registerControl,
+		labelable,
+		required,
+		disabled
+	]);
+	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\";\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\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 { labelable, name, disabled = false, required = false, id, component } = 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 });\n    },\n    [registerControl, labelable, required, disabled],\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":";;;;;;;;;;;;AA4DA,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,EAAE,WAAW,MAAM,WAAW,OAAO,WAAW,OAAO,IAAI,cAAc;CAC/E,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;EAAS,CAAC;CACnE,GACA;EAAC;EAAiB;EAAW;EAAU;CAAQ,CACjD;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

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-form-owner-event.mjs","names":[],"sources":["../../src/internal/use-form-owner-event.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 =\n  | HTMLInputElement\n  | HTMLFieldSetElement\n  | HTMLSelectElement\n  | HTMLTextAreaElement;\n\ninterface Subscription {\n  readonly form: HTMLFormElement;\n  readonly listener: (event: Event) => void;\n}\n\n/**\n * Stable subscription to `type` on the form owner of `ref.current` (conventions 3.8 rule 4,\n * generalised for Field, design/components/field-form.md 14).\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.\n * - `handler` always sees the latest committed render's values (`useEffectEvent`).\n * - `ref.current` may be any element: one without a `form` property has no owner.\n */\nexport function useFormOwnerEvent(\n  ref: RefObject<Element | null>,\n  type: string,\n  handler: (event: Event, form: HTMLFormElement) => void,\n): void {\n  const handle = useEffectEvent((event: Event, form: HTMLFormElement) => {\n    handler(event, form);\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 element = ref.current as Partial<FormAssociatedElement> | null;\n    const form = element?.form ?? null;\n    const current = subscription.current;\n    if (current !== null && current.form === form) return;\n    if (current !== null) current.form.removeEventListener(type, current.listener);\n    subscription.current = null;\n    if (form === null) return;\n    const listener = (event: Event) => handle(event, form);\n    form.addEventListener(type, 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(type, current.listener);\n      subscription.current = null;\n    },\n    [type],\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;AA4BA,SAAgB,kBACd,KACA,MACA,SACM;CACN,MAAM,SAAS,gBAAgB,OAAc,SAA0B;EACrE,QAAQ,OAAO,IAAI;CACrB,CAAC;CACD,MAAM,eAAe,OAA4B,IAAI;CAIrD,sBAAsB;EAEpB,MAAM,OADU,IAAI,SACE,QAAQ;EAC9B,MAAM,UAAU,aAAa;EAC7B,IAAI,YAAY,QAAQ,QAAQ,SAAS,MAAM;EAC/C,IAAI,YAAY,MAAM,QAAQ,KAAK,oBAAoB,MAAM,QAAQ,QAAQ;EAC7E,aAAa,UAAU;EACvB,IAAI,SAAS,MAAM;EACnB,MAAM,YAAY,UAAiB,OAAO,OAAO,IAAI;EACrD,KAAK,iBAAiB,MAAM,QAAQ;EACpC,aAAa,UAAU;GAAE;GAAM;EAAS;CAC1C,CAAC;CAID,4BACc;EACV,MAAM,UAAU,aAAa;EAC7B,IAAI,YAAY,MAAM,QAAQ,KAAK,oBAAoB,MAAM,QAAQ,QAAQ;EAC7E,aAAa,UAAU;CACzB,GACA,CAAC,IAAI,CACP;AACF"}

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

@@ -1,5 +1,6 @@
 "use client";
-import { useEffectEvent, useLayoutEffect, useRef } from "react";
+import { useLatest } from "./use-latest.mjs";
+import { useFormOwnerEvent } from "./use-form-owner-event.mjs";
 //#region src/internal/use-form-reset.ts
 /**
 * Stable `reset` subscription on the form owner of `ref.current` (conventions 3.8).
@@ -8,41 +9,21 @@ import { useEffectEvent, useLayoutEffect, useRef } from "react";
 *   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).
+*   followed every commit would miss it (rule 4). Built on `useFormOwnerEvent`.
 * - 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`).
+* - `onReset` always sees the latest committed render's values.
 */
-function useFormReset(ref, onReset) {
-	const handleReset = useEffectEvent((event) => {
-		onReset(event);
+function useFormReset(ref, onReset, onResetEvent) {
+	const latestOnReset = useLatest(onReset);
+	useFormOwnerEvent(ref, "reset", (event) => {
+		onResetEvent?.(event);
+		queueMicrotask(() => {
+			if (event.defaultPrevented) return;
+			latestOnReset.current(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 };

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

@@ -1 +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"}
+{"version":3,"file":"use-form-reset.mjs","names":[],"sources":["../../src/internal/use-form-reset.ts"],"sourcesContent":["\"use client\";\nimport type { RefObject } from \"react\";\nimport { useFormOwnerEvent } from \"./use-form-owner-event.js\";\nimport type { FormAssociatedElement } from \"./use-form-owner-event.js\";\nimport { useLatest } from \"./use-latest.js\";\n\nexport type { FormAssociatedElement } from \"./use-form-owner-event.js\";\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). Built on `useFormOwnerEvent`.\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.\n */\nexport function useFormReset(\n  ref: RefObject<FormAssociatedElement | null>,\n  onReset: (event: Event) => void,\n  /**\n   * Called synchronously from the `reset` event, before the reset algorithm runs: the last\n   * moment to write a reset target the browser will restore (Combobox re-applies its mirrored\n   * `defaultValue`, which react-dom's attribute syncing overwrites after every keystroke).\n   */\n  onResetEvent?: (event: Event) => void,\n): void {\n  // Read in the microtask, after the commit that may have run the reset (React's own reset runs\n  // in a commit's mutation phase): the latest committed `onReset`.\n  const latestOnReset = useLatest(onReset);\n  useFormOwnerEvent(ref, \"reset\", (event) => {\n    onResetEvent?.(event);\n    queueMicrotask(() => {\n      if (event.defaultPrevented) return;\n      latestOnReset.current(event);\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAqBA,SAAgB,aACd,KACA,SAMA,cACM;CAGN,MAAM,gBAAgB,UAAU,OAAO;CACvC,kBAAkB,KAAK,UAAU,UAAU;EACzC,eAAe,KAAK;EACpB,qBAAqB;GACnB,IAAI,MAAM,kBAAkB;GAC5B,cAAc,QAAQ,KAAK;EAC7B,CAAC;CACH,CAAC;AACH"}

package/dist/internal/use-hydrated-mount.mjs

@@ -0,0 +1,21 @@
+"use client";
+import { useSyncExternalStore } from "react";
+//#region src/internal/use-hydrated-mount.ts
+const subscribe = () => () => {};
+const clientSnapshot = () => false;
+const serverSnapshot = () => true;
+/**
+* Whether this render hydrates server HTML: `true` in the render that hydrates the component
+* (React uses `useSyncExternalStore`'s server snapshot there, also inside a Suspense boundary that
+* hydrates after its parent) and `false` in a client-created render, including a hydration that
+* fell back to client rendering. After a hydration React re-renders once with the client snapshot
+* (scheduled from a passive effect), so read the value captured by the **mount layout effect**,
+* which belongs to the hydration render (design/components/select.md 6.2).
+*/
+function useHydratedMount() {
+	return useSyncExternalStore(subscribe, clientSnapshot, serverSnapshot);
+}
+//#endregion
+export { useHydratedMount };
+
+//# sourceMappingURL=use-hydrated-mount.mjs.map

package/dist/internal/use-hydrated-mount.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-hydrated-mount.mjs","names":[],"sources":["../../src/internal/use-hydrated-mount.ts"],"sourcesContent":["\"use client\";\nimport { useSyncExternalStore } from \"react\";\n\nconst subscribe = () => () => {};\nconst clientSnapshot = () => false;\nconst serverSnapshot = () => true;\n\n/**\n * Whether this render hydrates server HTML: `true` in the render that hydrates the component\n * (React uses `useSyncExternalStore`'s server snapshot there, also inside a Suspense boundary that\n * hydrates after its parent) and `false` in a client-created render, including a hydration that\n * fell back to client rendering. After a hydration React re-renders once with the client snapshot\n * (scheduled from a passive effect), so read the value captured by the **mount layout effect**,\n * which belongs to the hydration render (design/components/select.md 6.2).\n */\nexport function useHydratedMount(): boolean {\n  return useSyncExternalStore(subscribe, clientSnapshot, serverSnapshot);\n}\n"],"mappings":";;;AAGA,MAAM,wBAAwB,CAAC;AAC/B,MAAM,uBAAuB;AAC7B,MAAM,uBAAuB;;;;;;;;;AAU7B,SAAgB,mBAA4B;CAC1C,OAAO,qBAAqB,WAAW,gBAAgB,cAAc;AACvE"}

package/dist/internal/use-latest.mjs

@@ -0,0 +1,32 @@
+"use client";
+import { useInsertionEffect, useRef } from "react";
+//#region src/internal/use-latest.ts
+/**
+* A ref holding the value of the last **committed** render, for stable callbacks (handlers,
+* actions, effects) that must read the current props without changing identity on every render.
+*
+* Written in an insertion effect: it runs in the mutation phase, before every layout effect of
+* the same commit (a child's included), so a callback called from a layout effect of the commit
+* that changed the value already sees it. A render that never commits (a discarded concurrent or
+* StrictMode render) never writes it. Never read it during render.
+*
+* Stale window: the write happens in the owner's own insertion effect, and React runs a commit's
+* insertion effects children first, interleaved with that subtree's DOM mutations. So a callback
+* called before the owner's insertion effect of the commit that changed the value still sees the
+* previous commit's value: from a descendant's insertion effect, or from a DOM event the browser
+* fires synchronously during the mutation phase (Chromium fires `blur` / `focusout` when a
+* focused node is removed). This is the same value a per-render closure would have given (the
+* handler attached then was the previous commit's too), so it is not a regression; just do not
+* rely on the new value before the layout phase.
+*/
+function useLatest(value) {
+	const ref = useRef(value);
+	useInsertionEffect(() => {
+		ref.current = value;
+	});
+	return ref;
+}
+//#endregion
+export { useLatest };
+
+//# sourceMappingURL=use-latest.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-latest.mjs","names":[],"sources":["../../src/internal/use-latest.ts"],"sourcesContent":["\"use client\";\nimport { useInsertionEffect, useRef } from \"react\";\nimport type { RefObject } from \"react\";\n\n/**\n * A ref holding the value of the last **committed** render, for stable callbacks (handlers,\n * actions, effects) that must read the current props without changing identity on every render.\n *\n * Written in an insertion effect: it runs in the mutation phase, before every layout effect of\n * the same commit (a child's included), so a callback called from a layout effect of the commit\n * that changed the value already sees it. A render that never commits (a discarded concurrent or\n * StrictMode render) never writes it. Never read it during render.\n *\n * Stale window: the write happens in the owner's own insertion effect, and React runs a commit's\n * insertion effects children first, interleaved with that subtree's DOM mutations. So a callback\n * called before the owner's insertion effect of the commit that changed the value still sees the\n * previous commit's value: from a descendant's insertion effect, or from a DOM event the browser\n * fires synchronously during the mutation phase (Chromium fires `blur` / `focusout` when a\n * focused node is removed). This is the same value a per-render closure would have given (the\n * handler attached then was the previous commit's too), so it is not a regression; just do not\n * rely on the new value before the layout phase.\n */\nexport function useLatest<T>(value: T): RefObject<T> {\n  const ref = useRef(value);\n  useInsertionEffect(() => {\n    ref.current = value;\n  });\n  return ref;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,UAAa,OAAwB;CACnD,MAAM,MAAM,OAAO,KAAK;CACxB,yBAAyB;EACvB,IAAI,UAAU;CAChB,CAAC;CACD,OAAO;AACT"}

package/dist/internal/use-modal-registration.mjs

@@ -0,0 +1,47 @@
+"use client";
+import { pushModal, removeModal } from "./modal-registry.mjs";
+import { useLayoutEffect } from "react";
+//#region src/internal/use-modal-registration.ts
+function isModal(dialog) {
+	if (!dialog.isConnected || !dialog.open) return false;
+	try {
+		return dialog.matches(":modal");
+	} catch {
+		return false;
+	}
+}
+/**
+* Keeps the modal registry (`modal-registry.ts`) in step with a `<dialog>`: registered while it
+* is open as a modal (`showModal()`), removed when it closes or unmounts. Reads the DOM truth
+* (`:modal`) instead of the component's state, so every way of opening counts.
+*
+* `beforetoggle` fires synchronously inside `showModal()` / `close()`, before the state changes,
+* so that check runs a microtask later; `toggle` and `close` re-check.
+*/
+function useModalRegistration(dialog) {
+	useLayoutEffect(() => {
+		if (dialog === null) return;
+		let active = true;
+		const sync = () => {
+			if (!active) return;
+			if (isModal(dialog)) pushModal(dialog);
+			else removeModal(dialog);
+		};
+		const syncSoon = () => queueMicrotask(sync);
+		dialog.addEventListener("beforetoggle", syncSoon);
+		dialog.addEventListener("toggle", sync);
+		dialog.addEventListener("close", sync);
+		sync();
+		return () => {
+			active = false;
+			dialog.removeEventListener("beforetoggle", syncSoon);
+			dialog.removeEventListener("toggle", sync);
+			dialog.removeEventListener("close", sync);
+			removeModal(dialog);
+		};
+	}, [dialog]);
+}
+//#endregion
+export { useModalRegistration };
+
+//# sourceMappingURL=use-modal-registration.mjs.map

package/dist/internal/use-modal-registration.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-modal-registration.mjs","names":[],"sources":["../../src/internal/use-modal-registration.ts"],"sourcesContent":["\"use client\";\nimport { useLayoutEffect } from \"react\";\nimport { pushModal, removeModal } from \"./modal-registry.js\";\n\nfunction isModal(dialog: HTMLDialogElement): boolean {\n  if (!dialog.isConnected || !dialog.open) return false;\n  try {\n    return dialog.matches(\":modal\");\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Keeps the modal registry (`modal-registry.ts`) in step with a `<dialog>`: registered while it\n * is open as a modal (`showModal()`), removed when it closes or unmounts. Reads the DOM truth\n * (`:modal`) instead of the component's state, so every way of opening counts.\n *\n * `beforetoggle` fires synchronously inside `showModal()` / `close()`, before the state changes,\n * so that check runs a microtask later; `toggle` and `close` re-check.\n */\nexport function useModalRegistration(dialog: HTMLDialogElement | null): void {\n  useLayoutEffect(() => {\n    if (dialog === null) return;\n    let active = true;\n    const sync = (): void => {\n      if (!active) return;\n      if (isModal(dialog)) pushModal(dialog);\n      else removeModal(dialog);\n    };\n    const syncSoon = (): void => queueMicrotask(sync);\n    dialog.addEventListener(\"beforetoggle\", syncSoon);\n    dialog.addEventListener(\"toggle\", sync);\n    dialog.addEventListener(\"close\", sync);\n    sync();\n    return () => {\n      active = false;\n      dialog.removeEventListener(\"beforetoggle\", syncSoon);\n      dialog.removeEventListener(\"toggle\", sync);\n      dialog.removeEventListener(\"close\", sync);\n      removeModal(dialog);\n    };\n  }, [dialog]);\n}\n"],"mappings":";;;;AAIA,SAAS,QAAQ,QAAoC;CACnD,IAAI,CAAC,OAAO,eAAe,CAAC,OAAO,MAAM,OAAO;CAChD,IAAI;EACF,OAAO,OAAO,QAAQ,QAAQ;CAChC,QAAQ;EACN,OAAO;CACT;AACF;;;;;;;;;AAUA,SAAgB,qBAAqB,QAAwC;CAC3E,sBAAsB;EACpB,IAAI,WAAW,MAAM;EACrB,IAAI,SAAS;EACb,MAAM,aAAmB;GACvB,IAAI,CAAC,QAAQ;GACb,IAAI,QAAQ,MAAM,GAAG,UAAU,MAAM;QAChC,YAAY,MAAM;EACzB;EACA,MAAM,iBAAuB,eAAe,IAAI;EAChD,OAAO,iBAAiB,gBAAgB,QAAQ;EAChD,OAAO,iBAAiB,UAAU,IAAI;EACtC,OAAO,iBAAiB,SAAS,IAAI;EACrC,KAAK;EACL,aAAa;GACX,SAAS;GACT,OAAO,oBAAoB,gBAAgB,QAAQ;GACnD,OAAO,oBAAoB,UAAU,IAAI;GACzC,OAAO,oBAAoB,SAAS,IAAI;GACxC,YAAY,MAAM;EACpB;CACF,GAAG,CAAC,MAAM,CAAC;AACb"}

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

@@ -1,4 +1,5 @@
 "use client";
+import { useLatest } from "./use-latest.mjs";
 import { useFormReset } from "./use-form-reset.mjs";
 import { useCallback, useEffectEvent, useLayoutEffect, useRef } from "react";
 //#region src/internal/use-native-group-reconciliation.ts
@@ -19,10 +20,7 @@ import { useCallback, useEffectEvent, useLayoutEffect, useRef } from "react";
 */
 function useNativeGroupReconciliation(options) {
 	const { element } = options;
-	const latest = useRef(options);
-	useLayoutEffect(() => {
-		latest.current = options;
-	});
+	const latest = useLatest(options);
 	/** The Root's own mount reconciliation has run (reset by its cleanup, StrictMode included). */
 	const rootReconciled = useRef(false);
 	/** A late reconciliation is queued; members mounting in the same commit share it. */
@@ -48,10 +46,13 @@ function useNativeGroupReconciliation(options) {
 			if (current.element.current === null) return;
 			reconcile(current, current.readCurrent());
 		});
-	}, []);
+	}, [latest]);
 	useFormReset(element, (event) => {
 		if (element.current === null) return;
 		reconcile(options, options.readDefault(), event);
+	}, (event) => {
+		if (element.current === null) return;
+		options.onResetEvent?.(event);
 	});
 	return { onItemMounted };
 }

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

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