@vtex/faststore 0.0.5 → 0.0.6

package/dist/particles/form/form.js

@@ -0,0 +1,485 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { useIntl } from "../../sdk/i18n/client.js";
+import { clearBoundField } from "../field/bound-field-registry.js";
+import { Button } from "../button/button.js";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+import { FormProvider, useForm, useFormContext, useFormState } from "react-hook-form";
+//#region src/particles/form/form.tsx
+const FormRegistryContext = createContext(null);
+/** Throws when no FormRoot is above the caller. */
+function useFormRegistry() {
+	const registry = useContext(FormRegistryContext);
+	if (!registry) throw new Error("Form parts must be used inside FormRoot.");
+	return registry;
+}
+/**
+* Internal-only seam between the six parts in this file. `FormClear` and `FormReset` iterate every
+* registered fieldset's field names (Invariant 11 — the form reaches a field name only through a
+* registration's `getFieldNames()`), which the public `FormRegistry` contract does not expose to a
+* fieldset — it only ever calls `registerFieldset` and reads `failures`. Not exported from this
+* module or the barrel.
+*/
+const FieldsetSnapshotContext = createContext(null);
+function useFieldsetSnapshot() {
+	const snapshot = useContext(FieldsetSnapshotContext);
+	if (!snapshot) throw new Error("Form parts must be used inside FormRoot.");
+	return snapshot;
+}
+/**
+* A second, internal-only seam beside `FieldsetSnapshotContext`, for the same reason: `FormEnterSubmit`
+* takes a form-wide keyboard allowance the public `FormRegistry` must not expose to a fieldset. Not
+* exported from this module or the barrel.
+*/
+const ImplicitSubmissionContext = createContext(null);
+/**
+* Takes an allowance token for the life of the calling component, so `handleKeyDown` allows implicit
+* submission on this FormRoot's own text-entry inputs while at least one caller holds a token. Throws
+* the same error as every other part when there is no FormRoot above it.
+*/
+function useAllowImplicitSubmission() {
+	const allow = useContext(ImplicitSubmissionContext);
+	const [token] = useState(() => Symbol());
+	useEffect(() => {
+		if (!allow) return;
+		return allow(token);
+	}, [allow, token]);
+	if (!allow) throw new Error("Form parts must be used inside FormRoot.");
+}
+/**
+* Two namespaces are in conflict when one equals, prefixes or is a descendant of the other —
+* `profile` collides with itself and with `profile.address` alike, because a fieldset under either
+* arrangement would dispatch on the other's edits and marshal its values into the wrong payload.
+*/
+function namespacesCollide(a, b) {
+	if (a === b) return true;
+	return a.startsWith(`${b}.`) || b.startsWith(`${a}.`);
+}
+/**
+* Is any of `names` dirty? React Hook Form nests `dirtyFields` by dot-path segment, so each full
+* field name is walked segment by segment rather than read as a flat key.
+*
+* Callers pass the names a fieldset's mounted controls currently hold, not its whole namespace. With
+* `shouldUnregister` unset, a control that has left the screen keeps its value and its dirty flag,
+* and nothing resets it — reconciliation, `FormReset` and `FormClear` all act on mounted names only.
+* Asking about the namespace would keep that flag reporting the fieldset dirty, so every later
+* submit would dispatch again for a field the shopper can no longer see, and the same holds for a
+* fieldset that has not mounted its controls yet.
+*/
+function isAnyFieldDirty(dirtyFields, names) {
+	return names.some((name) => {
+		let node = dirtyFields;
+		for (const segment of name.split(".")) {
+			if (typeof node !== "object" || node === null) return false;
+			node = node[segment];
+		}
+		return Boolean(node);
+	});
+}
+/**
+* Shallow-unsafe but adequate: field values are the primitives and plain records a bound Control
+* produces (strings, booleans, small objects), never functions or circular structures, so a
+* `JSON.stringify` comparison is a safe stand-in for a real deep-equal. Used only to tell whether a
+* shopper's keystroke landed while a dispatch was in flight (Decision 6) — a false "changed" verdict
+* merely means the field is resubmitted needlessly, never data loss.
+*/
+function valuesEqual(a, b) {
+	return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+* Ceiling on one fieldset's `dispatch`. A dispatch that neither resolves nor rejects — a fetch to a
+* server that accepts the connection and never answers, for which browsers apply no default timeout —
+* would otherwise leave `onValid` awaiting forever, so the submit boundary's `finally` never runs and
+* the re-entrancy guard stays armed for the life of the page. This is not cancellation: the request
+* keeps running and may still reach the server, and the form stops waiting for it.
+*
+* The ceiling is per fieldset, not per submit: `onValid` visits dirty fieldsets one at a time, in
+* registration order, so a submit over *n* hung fieldsets takes up to *n* times this long to release.
+* That is measured and accepted, not overlooked (Decision 3) — the wait stays bounded and
+* self-releasing, since the submit boundary's `finally` always runs once the last ceiling fires.
+*/
+const FORM_DISPATCH_TIMEOUT_MS = 3e4;
+/**
+* Resolves with the dispatch's own result, or rejects once `FORM_DISPATCH_TIMEOUT_MS` has elapsed,
+* whichever happens first. The no-op handler on `dispatch` is what stops a late rejection surfacing as
+* an unhandled rejection after the race has already been lost; the timer is cleared either way, so a
+* dispatch that settles normally leaves nothing pending.
+*/
+function withDispatchTimeout(dispatch) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			reject(/* @__PURE__ */ new Error(`Dispatch exceeded FORM_DISPATCH_TIMEOUT_MS (${FORM_DISPATCH_TIMEOUT_MS}ms).`));
+		}, FORM_DISPATCH_TIMEOUT_MS);
+		dispatch.then((userErrors) => {
+			clearTimeout(timer);
+			resolve(userErrors);
+		}, (error) => {
+			clearTimeout(timer);
+			reject(error);
+		});
+	});
+}
+/**
+* The HTML spec's text-entry `<input>` types — the ones that block implicit submission for anything
+* other than the field a shopper is typing in. An `<input>` with no `type` attribute reports
+* `type === 'text'`, so it is covered without a separate case.
+*/
+const TEXT_ENTRY_INPUT_TYPES = /* @__PURE__ */ new Set([
+	"text",
+	"search",
+	"url",
+	"tel",
+	"email",
+	"password",
+	"number",
+	"date",
+	"month",
+	"week",
+	"time",
+	"datetime-local"
+]);
+const FormRootDefinition = defineComponent({
+	name: "FormRoot",
+	importPath: "@vtex/faststore/components",
+	component: FormRoot,
+	providesContext: "form",
+	editor: {
+		label: "Form",
+		category: "action"
+	},
+	schema: {},
+	guideline: "The only <form> its own fieldset registry dispatches from — a composed CartCouponForm, ShippingSimulatorForm or RegionForm renders its own, and a submit-origin check keeps theirs out of this one. Calls react-hook-form's useForm() once and holds the registry a submit dispatches in registration order. Compose FormSubmit/FormEnterSubmit/FormError/FormClear/FormReset anywhere inside it, and a fieldset as a descendant to give the submit something to persist — FormRoot itself declares no actions."
+});
+const FormSubmitDefinition = defineComponent({
+	name: "FormSubmit",
+	importPath: "@vtex/faststore/components",
+	component: FormSubmit,
+	requiresContext: "form",
+	editor: {
+		label: "Form Submit",
+		category: "action"
+	},
+	schema: { label: {
+		type: "string",
+		label: "Label"
+	} },
+	guideline: "Submits every registered fieldset the shopper changed, in registration order, and disables itself while a write is in flight. Renders children, then label, then the message catalog (fs/form.submit) — never a hard-coded English default. A fieldset with nothing changed contributes no request; an invalid field blocks every dispatch and moves focus to it instead of submitting. Enter in a text input does not submit — see FormEnterSubmit for a form where it does."
+});
+const FormEnterSubmitDefinition = defineComponent({
+	name: "FormEnterSubmit",
+	importPath: "@vtex/faststore/components",
+	component: FormEnterSubmit,
+	requiresContext: "form",
+	editor: {
+		label: "Form Enter Submit",
+		category: "action"
+	},
+	schema: { label: {
+		type: "string",
+		label: "Label"
+	} },
+	guideline: "Renders the same button as FormSubmit, sharing its children/label/fs/form.submit resolution, and additionally allows Enter to submit this form from any text-entry input while mounted. The allowance is form-scoped: placed inside one fieldset of a multi-fieldset FormRoot, it allows Enter for every text input in the enclosing form, not only that fieldset. Enter that commits an IME candidate never submits."
+});
+const FormErrorDefinition = defineComponent({
+	name: "FormError",
+	importPath: "@vtex/faststore/components",
+	component: FormError,
+	requiresContext: "form",
+	editor: {
+		label: "Form Error",
+		category: "content"
+	},
+	schema: { fallbackMessage: {
+		type: "string",
+		label: "Fallback message"
+	} },
+	guideline: "Renders the last submit's write failures grouped by fieldset, or nothing when there were none. Set fallbackMessage for a fieldset whose write rejected rather than resolving with userErrors."
+});
+const FormClearDefinition = defineComponent({
+	name: "FormClear",
+	importPath: "@vtex/faststore/components",
+	component: FormClear,
+	requiresContext: "form",
+	editor: {
+		label: "Form Clear",
+		category: "action"
+	},
+	schema: { label: {
+		type: "string",
+		label: "Label"
+	} },
+	guideline: "Empties every field registered by every fieldset inside the enclosing FormRoot, not only the nearest one, but marks dirty only the fields whose value actually changed — a field already empty stays clean. Renders children, then label, then the message catalog (fs/form.clear). The following submit dispatches a write for every fieldset that had something to clear, and nothing for one where clearing was a no-op. There is no way to scope it to a single fieldset; place it only where clearing the whole form is the intended action, not by analogy with a per-field clear."
+});
+const FormResetDefinition = defineComponent({
+	name: "FormReset",
+	importPath: "@vtex/faststore/components",
+	component: FormReset,
+	requiresContext: "form",
+	editor: {
+		label: "Form Reset",
+		category: "action"
+	},
+	schema: { label: {
+		type: "string",
+		label: "Label"
+	} },
+	guideline: "Returns every registered field to react-hook-form's baseline for that name and clears its dirty/touched state. Renders children, then label, then the message catalog (fs/form.reset). Before a fieldset's first successful write, that baseline is whatever the field's own seed resolves to — not empty — so Reset reverts to the original value rather than clearing it; only after a successful submit does the baseline become what was last written."
+});
+function FormRoot({ className, children, onKeyDown, ...props }) {
+	const form = useForm();
+	const { handleSubmit, formState: { dirtyFields, isSubmitting }, getValues, resetField } = form;
+	const fieldsets = useRef(/* @__PURE__ */ new Map());
+	/**
+	* Insertion order of every namespace ever registered, independent of `fieldsets`' own Map order.
+	* A namespace's slot here is created once and never moved — re-registering it (the cleanup-then-
+	* effect cycle a changed dep triggers) deletes and re-adds the `fieldsets` entry, which would push
+	* a plain `Map` iteration to the tail; reading dispatch order through this array instead keeps a
+	* namespace in its original position across any number of re-registrations.
+	*/
+	const order = useRef([]);
+	const submitting = useRef(false);
+	const [failures, setFailures] = useState([]);
+	/**
+	* One token per mounted part that allows implicit submission (Decision 1). A `Set`, not a boolean or
+	* a count: two mounted allowing parts must compose, unmounting one must leave the allowance held by
+	* the other in place, and a token's cleanup — including a double-invoked one under StrictMode — must
+	* be a no-op once already removed. `handleKeyDown` only ever reads `.size`; nothing renders from it.
+	*/
+	const allowance = useRef(/* @__PURE__ */ new Set());
+	const registerFieldset = useCallback((registration) => {
+		const { namespace } = registration;
+		for (const existing of fieldsets.current.values()) if (namespacesCollide(namespace, existing.namespace)) throw new Error(`FormRoot already has a fieldset registered under namespace "${existing.namespace}", which collides with "${namespace}". Two different fieldsets cannot share a namespace or nest one inside the other — re-registering the same namespace is only valid once its previous registration has been unregistered.`);
+		if (!order.current.includes(namespace)) order.current.push(namespace);
+		fieldsets.current.set(namespace, registration);
+		return () => {
+			if (fieldsets.current.get(namespace) === registration) fieldsets.current.delete(namespace);
+		};
+	}, []);
+	const getFieldsetSnapshot = useCallback(() => order.current.flatMap((namespace) => fieldsets.current.get(namespace) ?? []), []);
+	const registerAllowance = useCallback((token) => {
+		allowance.current.add(token);
+		return () => {
+			allowance.current.delete(token);
+		};
+	}, []);
+	const onValid = useCallback(async () => {
+		setFailures([]);
+		const collected = [];
+		const snapshot = getFieldsetSnapshot();
+		for (const fieldset of snapshot) {
+			let preDispatchValues;
+			let userErrors;
+			try {
+				const fieldNames = fieldset.getFieldNames();
+				if (!isAnyFieldDirty(dirtyFields, fieldNames)) continue;
+				preDispatchValues = fieldNames.map((name) => [name, getValues(name)]);
+				const payload = fieldset.toPayload(getValues(fieldset.namespace) ?? {});
+				userErrors = await withDispatchTimeout(fieldset.dispatch(payload));
+			} catch {
+				collected.push({
+					label: fieldset.label,
+					userErrors: []
+				});
+				continue;
+			}
+			if (userErrors.length > 0) {
+				collected.push({
+					label: fieldset.label,
+					userErrors
+				});
+				continue;
+			}
+			for (const [name, capturedValue] of preDispatchValues) if (valuesEqual(getValues(name), capturedValue)) resetField(name, { defaultValue: capturedValue });
+		}
+		setFailures(collected);
+	}, [
+		dirtyFields,
+		getValues,
+		resetField,
+		getFieldsetSnapshot
+	]);
+	const onInvalid = useCallback(() => {
+		setFailures([]);
+	}, []);
+	/**
+	* Ignores a submit event whose origin isn't this FormRoot's own <form>. Submit events bubble, so a
+	* nested <form>'s own submission — the shape CartCouponForm, ShippingSimulatorForm and RegionForm
+	* each render when composed inside a checkout FormRoot — reaches this handler too; without this
+	* check, that bubbled event would run react-hook-form's handleSubmit and commit an entity write the
+	* shopper never asked this FormRoot to make. Mirrors handleKeyDown's own origin check (there scoped
+	* by `target.form`), for the same reason: a nested form is never this one.
+	*
+	* Two properties of where this check sits are load-bearing. First, it reads `event.currentTarget`
+	* before any `await`: React nulls `currentTarget` once the synchronous part of a handler returns,
+	* so the same comparison placed after an await degrades to `event.target !== null` — always true —
+	* and rejects every submit, a permanently dead submit button with no error raised. It needs no test
+	* of its own: inserting an await above this check fails most of the tests in form.test.tsx, and
+	* moving it below the awaited `handleSubmit(...)` below fails the nested-form test in *Implicit
+	* submission*. Second, it runs before the re-entrancy check immediately below: while this form's own
+	* write is in flight, `submitting.current` is `true`, so a bubbled nested submit that reached the
+	* re-entrancy check first would call `event.preventDefault()` and cancel a nested form's own
+	* submission that this FormRoot never rendered. The last test in *Re-entrancy* pins that second
+	* property; nothing caught it before that test existed.
+	*/
+	const handleFormSubmit = useCallback(async (event) => {
+		if (event.target !== event.currentTarget) return;
+		if (submitting.current) {
+			event.preventDefault();
+			return;
+		}
+		submitting.current = true;
+		try {
+			await handleSubmit(onValid, onInvalid)(event);
+		} finally {
+			submitting.current = false;
+		}
+	}, [
+		handleSubmit,
+		onValid,
+		onInvalid
+	]);
+	/**
+	* Cancels HTML implicit submission by default. A text input inside a form with a default button
+	* submits that form on Enter, which for an entity form means committing a write from a keystroke a
+	* shopper means as "look this up" or "next field" — before they have finished editing the rest of
+	* the sendable unit. That default is form-scoped and opt-in to override: mounting `FormEnterSubmit`
+	* anywhere inside this FormRoot allows Enter to submit from any of this form's own text-entry
+	* inputs, not only the fieldset the allowing part happens to sit in; a form composing only
+	* `FormSubmit` keeps today's cancelling behaviour. Enter that commits an IME candidate is cancelled
+	* either way, allowance or not, so choosing a word never submits a half-finished form. Submitting
+	* stays fully keyboard-operable either way, through a focusable native `FormSubmit`/`FormEnterSubmit`
+	* button, so no capability is removed (WCAG 2.1 SC 2.1.1). Scoped to text-entry inputs by target, so
+	* Enter on a button, a link, a `<textarea>`, a `contentEditable` region or a Base UI select trigger is
+	* untouched, and scoped to Enter, so typing is untouched. Also scoped to this form's own inputs by
+	* `target.form`: a keydown from a nested `<form>`'s own control bubbles up here too, and without that
+	* check this guard would cancel implicit submission for a form it never rendered. Composes rather
+	* than replaces an author-supplied `onKeyDown`: theirs runs first, unconditionally, before any of
+	* this guard's own checks — it can cancel Enter on an allowing form, but it cannot force Enter on a
+	* cancelling one, because this guard's own `preventDefault()` runs after it.
+	*/
+	const handleKeyDown = useCallback((event) => {
+		onKeyDown?.(event);
+		if (event.key !== "Enter" || event.defaultPrevented) return;
+		const { target } = event;
+		if (!(target instanceof HTMLInputElement) || !TEXT_ENTRY_INPUT_TYPES.has(target.type)) return;
+		if (target.form !== event.currentTarget) return;
+		if (allowance.current.size > 0 && !event.nativeEvent.isComposing) return;
+		event.preventDefault();
+	}, [onKeyDown]);
+	const registry = useMemo(() => ({
+		registerFieldset,
+		failures
+	}), [registerFieldset, failures]);
+	return /* @__PURE__ */ jsx("form", {
+		...props,
+		noValidate: true,
+		onSubmit: handleFormSubmit,
+		onKeyDown: handleKeyDown,
+		className,
+		"data-fs-form": "",
+		"data-fs-form-pending": isSubmitting ? "" : void 0,
+		children: /* @__PURE__ */ jsx(FormProvider, {
+			...form,
+			children: /* @__PURE__ */ jsx(FormRegistryContext.Provider, {
+				value: registry,
+				children: /* @__PURE__ */ jsx(FieldsetSnapshotContext.Provider, {
+					value: getFieldsetSnapshot,
+					children: /* @__PURE__ */ jsx(ImplicitSubmissionContext.Provider, {
+						value: registerAllowance,
+						children
+					})
+				})
+			})
+		})
+	});
+}
+/**
+* The shared render for both submit parts: same button, same hooks, same data-fs-form-submit hook.
+* Text resolves `children ?? label ?? formatMessage(...)` (RFC sketch) — never a hard-coded English
+* default — so an unauthored FormEnterSubmit reads correctly in every shipped locale, not only
+* en-US. One id, `fs/form.submit`, covers both parts: they render the same button, so a second id
+* for the Enter variant would only be a second translation of the same word.
+*/
+function SubmitButton({ className, label, children }) {
+	const { isSubmitting } = useFormState();
+	const intl = useIntl();
+	return /* @__PURE__ */ jsx(Button, {
+		type: "submit",
+		disabled: isSubmitting,
+		className,
+		"data-fs-form-submit": "",
+		"data-fs-form-submit-pending": isSubmitting ? "" : void 0,
+		children: children ?? label ?? intl.formatMessage({ id: "fs/form.submit" })
+	});
+}
+function FormSubmit(props) {
+	useFormRegistry();
+	return /* @__PURE__ */ jsx(SubmitButton, { ...props });
+}
+/**
+* Renders the same button as `FormSubmit` and additionally allows Enter to submit this FormRoot's own
+* text-entry inputs while mounted — see `handleKeyDown`'s own doc for the form-scoped allowance and
+* the IME carve-out.
+*/
+function FormEnterSubmit(props) {
+	useFormRegistry();
+	useAllowImplicitSubmission();
+	return /* @__PURE__ */ jsx(SubmitButton, { ...props });
+}
+function FormError({ className, fallbackMessage = "Something went wrong. Please try again." }) {
+	const { failures } = useFormRegistry();
+	if (failures.length === 0) return null;
+	return /* @__PURE__ */ jsx("div", {
+		role: "alert",
+		className,
+		"data-fs-form-error": "",
+		children: failures.map((failure, failureIndex) => /* @__PURE__ */ jsx("ul", {
+			"data-fs-form-error-item": failure.label,
+			children: failure.userErrors.length > 0 ? failure.userErrors.map((error, errorIndex) => /* @__PURE__ */ jsx("li", { children: error.message }, `${failure.label}-${failureIndex}-${errorIndex}`)) : /* @__PURE__ */ jsx("li", { children: fallbackMessage })
+		}, `${failure.label}-${failureIndex}`))
+	});
+}
+function FormClear({ className, label, children }) {
+	const getFieldsets = useFieldsetSnapshot();
+	const { control } = useFormContext();
+	const intl = useIntl();
+	function handleClear() {
+		for (const fieldset of getFieldsets()) for (const name of fieldset.getFieldNames()) clearBoundField(control, name);
+	}
+	return /* @__PURE__ */ jsx(Button, {
+		type: "button",
+		onClick: handleClear,
+		className,
+		"data-fs-form-clear": "",
+		children: children ?? label ?? intl.formatMessage({ id: "fs/form.clear" })
+	});
+}
+function FormReset({ className, label, children }) {
+	const getFieldsets = useFieldsetSnapshot();
+	const { resetField } = useFormContext();
+	const intl = useIntl();
+	function handleReset() {
+		for (const fieldset of getFieldsets()) for (const name of fieldset.getFieldNames()) resetField(name);
+	}
+	return /* @__PURE__ */ jsx(Button, {
+		type: "button",
+		onClick: handleReset,
+		className,
+		"data-fs-form-reset": "",
+		children: children ?? label ?? intl.formatMessage({ id: "fs/form.reset" })
+	});
+}
+const Form = {
+	Root: FormRoot,
+	Submit: FormSubmit,
+	EnterSubmit: FormEnterSubmit,
+	Error: FormError,
+	Clear: FormClear,
+	Reset: FormReset
+};
+//#endregion
+export { FORM_DISPATCH_TIMEOUT_MS, Form, FormClear, FormClearDefinition, FormEnterSubmit, FormEnterSubmitDefinition, FormError, FormErrorDefinition, FormRegistryContext, FormReset, FormResetDefinition, FormRoot, FormRootDefinition, FormSubmit, FormSubmitDefinition, useFormRegistry };
+
+//# sourceMappingURL=form.js.map

package/dist/particles/form/form.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.js","names":[],"sources":["../../../src/particles/form/form.tsx"],"sourcesContent":["'use client';\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef, Context, FormEvent, KeyboardEvent, ReactNode } from 'react';\nimport { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';\nimport { FormProvider, useForm, useFormContext, useFormState } from 'react-hook-form';\nimport { useIntl } from '../../sdk/i18n/client.js';\nimport { Button } from '../button/button.js';\nimport { clearBoundField } from '../field/bound-field-registry.js';\n\n// ---------------------------------------------------------------------------\n// Data models\n// ---------------------------------------------------------------------------\n\n/**\n * The structural minimum every SDK user-error type satisfies. `code` is optional so that every\n * shipped shape is assignable, including `RegionUserError`, the one that declares it optional;\n * `ShippingAddressUpdateErrorEntity`, `ClientProfileUserError`, `CartUserError` and\n * `SessionUserError` all declare `Readonly<{ code: string; message: string }>`. There is no shared\n * user-error type in the SDK to reuse.\n */\nexport type FormUserError = Readonly<{ code?: string; message: string }>;\n\n/** What one fieldset hands the form. The form learns nothing else about it. */\nexport type FieldsetRegistration = Readonly<{\n  /** Matches the field-name prefix every one of this fieldset's controls registers under. */\n  namespace: string;\n  /** Every full, namespaced field name this fieldset currently has mounted. */\n  getFieldNames: () => readonly string[];\n  /**\n   * Closes over the fieldset's own injected `$actions`. Rejecting is allowed; the form catches it.\n   * Must settle: the form gives up on a dispatch still pending after `FORM_DISPATCH_TIMEOUT_MS` and\n   * reports it as a failed write. Must also be idempotent: giving up on a dispatch does not cancel it,\n   * so a timed-out write may already be landing on the server, and the same payload is re-dispatched on\n   * the shopper's next submit while the field stays dirty.\n   */\n  dispatch: (payload: Record<string, unknown>) => Promise<readonly FormUserError[]>;\n  /** Shapes react-hook-form's raw values into the mutation's payload, including type coercion. */\n  toPayload: (values: Record<string, unknown>) => Record<string, unknown>;\n  /**\n   * Machine identifier for this fieldset's write. `FormError` renders it as the\n   * `data-fs-form-error-item` attribute value and uses it in two React keys; it is never displayed,\n   * because the visible text is each `userError`'s own `message` or `FormError`'s `fallbackMessage`.\n   * Its value is the kebab-case ASCII rendering of this registration's own `namespace`\n   * (`shippingAddress` → `shipping-address`), so a stylesheet selecting\n   * `[data-fs-form-error-item=\"…\"]` needs one predictable shape and no diacritics.\n   */\n  label: string;\n}>;\n\n/**\n * One fieldset's write that did not land. An empty `userErrors` means the dispatch rejected or never\n * settled within `FORM_DISPATCH_TIMEOUT_MS`; either way `FormError` renders `fallbackMessage`.\n */\nexport type FormWriteFailure = Readonly<{\n  label: string;\n  userErrors: readonly FormUserError[];\n}>;\n\nexport type FormRegistry = Readonly<{\n  /** Stable for the life of the FormRoot. Returns the unregister function. */\n  registerFieldset: (registration: FieldsetRegistration) => () => void;\n  /** The last submit's failures, in dispatch order. */\n  failures: readonly FormWriteFailure[];\n}>;\n\n// ---------------------------------------------------------------------------\n// Registry context\n// ---------------------------------------------------------------------------\n\nexport const FormRegistryContext: Context<FormRegistry | null> = createContext<FormRegistry | null>(null);\n\n/** Throws when no FormRoot is above the caller. */\nexport function useFormRegistry(): FormRegistry {\n  const registry = useContext(FormRegistryContext);\n  if (!registry) throw new Error('Form parts must be used inside FormRoot.');\n  return registry;\n}\n\n/**\n * Internal-only seam between the six parts in this file. `FormClear` and `FormReset` iterate every\n * registered fieldset's field names (Invariant 11 — the form reaches a field name only through a\n * registration's `getFieldNames()`), which the public `FormRegistry` contract does not expose to a\n * fieldset — it only ever calls `registerFieldset` and reads `failures`. Not exported from this\n * module or the barrel.\n */\nconst FieldsetSnapshotContext = createContext<(() => readonly FieldsetRegistration[]) | null>(null);\n\nfunction useFieldsetSnapshot(): () => readonly FieldsetRegistration[] {\n  const snapshot = useContext(FieldsetSnapshotContext);\n  if (!snapshot) throw new Error('Form parts must be used inside FormRoot.');\n  return snapshot;\n}\n\n/** Adds one token for as long as the caller is mounted; the returned cleanup removes that token. */\ntype AllowImplicitSubmission = (token: symbol) => () => void;\n\n/**\n * A second, internal-only seam beside `FieldsetSnapshotContext`, for the same reason: `FormEnterSubmit`\n * takes a form-wide keyboard allowance the public `FormRegistry` must not expose to a fieldset. Not\n * exported from this module or the barrel.\n */\nconst ImplicitSubmissionContext: Context<AllowImplicitSubmission | null> =\n  createContext<AllowImplicitSubmission | null>(null);\n\n/**\n * Takes an allowance token for the life of the calling component, so `handleKeyDown` allows implicit\n * submission on this FormRoot's own text-entry inputs while at least one caller holds a token. Throws\n * the same error as every other part when there is no FormRoot above it.\n */\nfunction useAllowImplicitSubmission(): void {\n  const allow = useContext(ImplicitSubmissionContext);\n  // useState's lazy initialiser, not a ref written during render: it runs Symbol() exactly once, on\n  // this component instance's first render, and every re-render reads back the same value.\n  const [token] = useState(() => Symbol());\n\n  useEffect(() => {\n    if (!allow) return;\n    return allow(token);\n  }, [allow, token]);\n\n  // All hooks above run unconditionally on every render; only this line is conditional, so throwing\n  // here (rather than before the hooks) is not a rules-of-hooks violation.\n  if (!allow) throw new Error('Form parts must be used inside FormRoot.');\n}\n\n/**\n * Two namespaces are in conflict when one equals, prefixes or is a descendant of the other —\n * `profile` collides with itself and with `profile.address` alike, because a fieldset under either\n * arrangement would dispatch on the other's edits and marshal its values into the wrong payload.\n */\nfunction namespacesCollide(a: string, b: string): boolean {\n  if (a === b) return true;\n  return a.startsWith(`${b}.`) || b.startsWith(`${a}.`);\n}\n\n/**\n * Is any of `names` dirty? React Hook Form nests `dirtyFields` by dot-path segment, so each full\n * field name is walked segment by segment rather than read as a flat key.\n *\n * Callers pass the names a fieldset's mounted controls currently hold, not its whole namespace. With\n * `shouldUnregister` unset, a control that has left the screen keeps its value and its dirty flag,\n * and nothing resets it — reconciliation, `FormReset` and `FormClear` all act on mounted names only.\n * Asking about the namespace would keep that flag reporting the fieldset dirty, so every later\n * submit would dispatch again for a field the shopper can no longer see, and the same holds for a\n * fieldset that has not mounted its controls yet.\n */\nfunction isAnyFieldDirty(dirtyFields: Record<string, unknown>, names: readonly string[]): boolean {\n  return names.some((name) => {\n    let node: unknown = dirtyFields;\n    for (const segment of name.split('.')) {\n      if (typeof node !== 'object' || node === null) return false;\n      node = (node as Record<string, unknown>)[segment];\n    }\n    return Boolean(node);\n  });\n}\n\n/**\n * Shallow-unsafe but adequate: field values are the primitives and plain records a bound Control\n * produces (strings, booleans, small objects), never functions or circular structures, so a\n * `JSON.stringify` comparison is a safe stand-in for a real deep-equal. Used only to tell whether a\n * shopper's keystroke landed while a dispatch was in flight (Decision 6) — a false \"changed\" verdict\n * merely means the field is resubmitted needlessly, never data loss.\n */\nfunction valuesEqual(a: unknown, b: unknown): boolean {\n  return a === b || JSON.stringify(a) === JSON.stringify(b);\n}\n\n/**\n * Ceiling on one fieldset's `dispatch`. A dispatch that neither resolves nor rejects — a fetch to a\n * server that accepts the connection and never answers, for which browsers apply no default timeout —\n * would otherwise leave `onValid` awaiting forever, so the submit boundary's `finally` never runs and\n * the re-entrancy guard stays armed for the life of the page. This is not cancellation: the request\n * keeps running and may still reach the server, and the form stops waiting for it.\n *\n * The ceiling is per fieldset, not per submit: `onValid` visits dirty fieldsets one at a time, in\n * registration order, so a submit over *n* hung fieldsets takes up to *n* times this long to release.\n * That is measured and accepted, not overlooked (Decision 3) — the wait stays bounded and\n * self-releasing, since the submit boundary's `finally` always runs once the last ceiling fires.\n */\nexport const FORM_DISPATCH_TIMEOUT_MS = 30_000;\n\n/**\n * Resolves with the dispatch's own result, or rejects once `FORM_DISPATCH_TIMEOUT_MS` has elapsed,\n * whichever happens first. The no-op handler on `dispatch` is what stops a late rejection surfacing as\n * an unhandled rejection after the race has already been lost; the timer is cleared either way, so a\n * dispatch that settles normally leaves nothing pending.\n */\nfunction withDispatchTimeout(dispatch: Promise<readonly FormUserError[]>): Promise<readonly FormUserError[]> {\n  return new Promise((resolve, reject) => {\n    const timer = setTimeout(() => {\n      reject(new Error(`Dispatch exceeded FORM_DISPATCH_TIMEOUT_MS (${FORM_DISPATCH_TIMEOUT_MS}ms).`));\n    }, FORM_DISPATCH_TIMEOUT_MS);\n\n    dispatch.then(\n      (userErrors) => {\n        clearTimeout(timer);\n        resolve(userErrors);\n      },\n      (error) => {\n        clearTimeout(timer);\n        reject(error);\n      },\n    );\n  });\n}\n\n/**\n * The HTML spec's text-entry `<input>` types — the ones that block implicit submission for anything\n * other than the field a shopper is typing in. An `<input>` with no `type` attribute reports\n * `type === 'text'`, so it is covered without a separate case.\n */\nconst TEXT_ENTRY_INPUT_TYPES = new Set([\n  'text',\n  'search',\n  'url',\n  'tel',\n  'email',\n  'password',\n  'number',\n  'date',\n  'month',\n  'week',\n  'time',\n  'datetime-local',\n]);\n\n// ---------------------------------------------------------------------------\n// Prop types\n// ---------------------------------------------------------------------------\n\nexport type FormRootProps = Omit<\n  ComponentPropsWithRef<'form'>,\n  'onSubmit' | 'action' | 'method' | 'target' | 'encType' | 'dangerouslySetInnerHTML'\n>;\nexport type FormSubmitProps = { className?: string; label?: string; children?: ReactNode };\nexport type FormClearProps = { className?: string; label?: string; children?: ReactNode };\nexport type FormResetProps = { className?: string; label?: string; children?: ReactNode };\nexport type FormErrorProps = { className?: string; fallbackMessage?: string };\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const FormRootDefinition = defineComponent<FormRootProps>({\n  name: 'FormRoot',\n  importPath: '@vtex/faststore/components',\n  component: FormRoot,\n  providesContext: 'form',\n  editor: { label: 'Form', category: 'action' },\n  schema: {},\n  guideline:\n    \"The only <form> its own fieldset registry dispatches from — a composed CartCouponForm, ShippingSimulatorForm or RegionForm renders its own, and a submit-origin check keeps theirs out of this one. Calls react-hook-form's useForm() once and holds the registry a submit dispatches in registration order. Compose FormSubmit/FormEnterSubmit/FormError/FormClear/FormReset anywhere inside it, and a fieldset as a descendant to give the submit something to persist — FormRoot itself declares no actions.\",\n});\n\nexport const FormSubmitDefinition = defineComponent<FormSubmitProps>({\n  name: 'FormSubmit',\n  importPath: '@vtex/faststore/components',\n  component: FormSubmit,\n  requiresContext: 'form',\n  editor: { label: 'Form Submit', category: 'action' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n  },\n  guideline:\n    'Submits every registered fieldset the shopper changed, in registration order, and disables itself while a write is in flight. Renders children, then label, then the message catalog (fs/form.submit) — never a hard-coded English default. A fieldset with nothing changed contributes no request; an invalid field blocks every dispatch and moves focus to it instead of submitting. Enter in a text input does not submit — see FormEnterSubmit for a form where it does.',\n});\n\nexport const FormEnterSubmitDefinition = defineComponent<FormSubmitProps>({\n  name: 'FormEnterSubmit',\n  importPath: '@vtex/faststore/components',\n  component: FormEnterSubmit,\n  requiresContext: 'form',\n  editor: { label: 'Form Enter Submit', category: 'action' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n  },\n  guideline:\n    'Renders the same button as FormSubmit, sharing its children/label/fs/form.submit resolution, and additionally allows Enter to submit this form from any text-entry input while mounted. The allowance is form-scoped: placed inside one fieldset of a multi-fieldset FormRoot, it allows Enter for every text input in the enclosing form, not only that fieldset. Enter that commits an IME candidate never submits.',\n});\n\nexport const FormErrorDefinition = defineComponent<FormErrorProps>({\n  name: 'FormError',\n  importPath: '@vtex/faststore/components',\n  component: FormError,\n  requiresContext: 'form',\n  editor: { label: 'Form Error', category: 'content' },\n  schema: {\n    fallbackMessage: { type: 'string', label: 'Fallback message' },\n  },\n  guideline:\n    \"Renders the last submit's write failures grouped by fieldset, or nothing when there were none. Set fallbackMessage for a fieldset whose write rejected rather than resolving with userErrors.\",\n});\n\nexport const FormClearDefinition = defineComponent<FormClearProps>({\n  name: 'FormClear',\n  importPath: '@vtex/faststore/components',\n  component: FormClear,\n  requiresContext: 'form',\n  editor: { label: 'Form Clear', category: 'action' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n  },\n  guideline:\n    'Empties every field registered by every fieldset inside the enclosing FormRoot, not only the nearest one, but marks dirty only the fields whose value actually changed — a field already empty stays clean. Renders children, then label, then the message catalog (fs/form.clear). The following submit dispatches a write for every fieldset that had something to clear, and nothing for one where clearing was a no-op. There is no way to scope it to a single fieldset; place it only where clearing the whole form is the intended action, not by analogy with a per-field clear.',\n});\n\nexport const FormResetDefinition = defineComponent<FormResetProps>({\n  name: 'FormReset',\n  importPath: '@vtex/faststore/components',\n  component: FormReset,\n  requiresContext: 'form',\n  editor: { label: 'Form Reset', category: 'action' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n  },\n  guideline:\n    \"Returns every registered field to react-hook-form's baseline for that name and clears its dirty/touched state. Renders children, then label, then the message catalog (fs/form.reset). Before a fieldset's first successful write, that baseline is whatever the field's own seed resolves to — not empty — so Reset reverts to the original value rather than clearing it; only after a successful submit does the baseline become what was last written.\",\n});\n\n// ---------------------------------------------------------------------------\n// Parts\n// ---------------------------------------------------------------------------\n\nexport function FormRoot({ className, children, onKeyDown, ...props }: FormRootProps): ReactNode {\n  const form = useForm();\n  const {\n    handleSubmit,\n    // `dirtyFields` is destructured here, in render, on purpose. React Hook Form keeps `dirtyFields`\n    // current whether or not anything reads it — the proxy on `formState` decides only whether a\n    // change here re-renders the subscriber, not whether the underlying store is kept. What the\n    // render-time read buys is freshness: the submit handler below closes over the copy from the\n    // render that defined it, and subscribing here is what keeps that copy current by the time a\n    // later submit reads it. (The per-fieldset check further down walks each mounted field's\n    // dot-path through this object rather than indexing it by a single key — see `isAnyFieldDirty`.)\n    formState: { dirtyFields, isSubmitting },\n    getValues,\n    resetField,\n  } = form;\n\n  const fieldsets = useRef(new Map<string, FieldsetRegistration>());\n  /**\n   * Insertion order of every namespace ever registered, independent of `fieldsets`' own Map order.\n   * A namespace's slot here is created once and never moved — re-registering it (the cleanup-then-\n   * effect cycle a changed dep triggers) deletes and re-adds the `fieldsets` entry, which would push\n   * a plain `Map` iteration to the tail; reading dispatch order through this array instead keeps a\n   * namespace in its original position across any number of re-registrations.\n   */\n  const order = useRef<string[]>([]);\n  const submitting = useRef(false);\n  const [failures, setFailures] = useState<readonly FormWriteFailure[]>([]);\n  /**\n   * One token per mounted part that allows implicit submission (Decision 1). A `Set`, not a boolean or\n   * a count: two mounted allowing parts must compose, unmounting one must leave the allowance held by\n   * the other in place, and a token's cleanup — including a double-invoked one under StrictMode — must\n   * be a no-op once already removed. `handleKeyDown` only ever reads `.size`; nothing renders from it.\n   */\n  const allowance = useRef(new Set<symbol>());\n\n  const registerFieldset = useCallback((registration: FieldsetRegistration) => {\n    const { namespace } = registration;\n\n    for (const existing of fieldsets.current.values()) {\n      if (namespacesCollide(namespace, existing.namespace)) {\n        throw new Error(\n          `FormRoot already has a fieldset registered under namespace \"${existing.namespace}\", which collides with \"${namespace}\". Two different fieldsets cannot share a namespace or nest one inside the other — re-registering the same namespace is only valid once its previous registration has been unregistered.`,\n        );\n      }\n    }\n\n    if (!order.current.includes(namespace)) {\n      order.current.push(namespace);\n    }\n    fieldsets.current.set(namespace, registration);\n\n    return () => {\n      if (fieldsets.current.get(namespace) === registration) {\n        fieldsets.current.delete(namespace);\n      }\n    };\n  }, []);\n\n  const getFieldsetSnapshot = useCallback(\n    () => order.current.flatMap((namespace) => fieldsets.current.get(namespace) ?? []),\n    [],\n  );\n\n  const registerAllowance = useCallback((token: symbol) => {\n    allowance.current.add(token);\n    return () => {\n      allowance.current.delete(token);\n    };\n  }, []);\n\n  const onValid = useCallback(async () => {\n    setFailures([]);\n    const collected: FormWriteFailure[] = [];\n    const snapshot = getFieldsetSnapshot();\n\n    for (const fieldset of snapshot) {\n      let preDispatchValues: ReadonlyArray<readonly [string, unknown]>;\n      let userErrors: readonly FormUserError[];\n      try {\n        const fieldNames = fieldset.getFieldNames();\n        if (!isAnyFieldDirty(dirtyFields, fieldNames)) continue;\n        preDispatchValues = fieldNames.map((name) => [name, getValues(name)] as const);\n        const payload = fieldset.toPayload(getValues(fieldset.namespace) ?? {});\n        userErrors = await withDispatchTimeout(fieldset.dispatch(payload));\n      } catch {\n        // Threw, timed out, or could not build its payload — collected as a failure either way, and\n        // the queue moves on: the next fieldset's dispatch never depends on this one's code being\n        // sound.\n        collected.push({ label: fieldset.label, userErrors: [] });\n        continue;\n      }\n\n      if (userErrors.length > 0) {\n        collected.push({ label: fieldset.label, userErrors });\n        continue;\n      }\n\n      // Reconcile against the values captured before the await, not the live ones (Decision 6).\n      // A name whose live value still matches what was captured is safe to reconcile: the write\n      // targeted exactly that value, so moving the baseline there is invisible. A name whose live\n      // value has since diverged means a keystroke landed mid-write — it is left untouched, so it\n      // stays dirty and is picked up, unsent, by the next submit.\n      //\n      // Deliberately outside the try above: the write already succeeded (no userErrors), so a\n      // `resetField` that throws here is a reconciliation fault, not a write fault, and must not be\n      // reported to the shopper as one.\n      for (const [name, capturedValue] of preDispatchValues) {\n        if (valuesEqual(getValues(name), capturedValue)) {\n          resetField(name, { defaultValue: capturedValue });\n        }\n      }\n    }\n\n    setFailures(collected);\n  }, [dirtyFields, getValues, resetField, getFieldsetSnapshot]);\n\n  const onInvalid = useCallback(() => {\n    setFailures([]);\n  }, []);\n\n  /**\n   * Ignores a submit event whose origin isn't this FormRoot's own <form>. Submit events bubble, so a\n   * nested <form>'s own submission — the shape CartCouponForm, ShippingSimulatorForm and RegionForm\n   * each render when composed inside a checkout FormRoot — reaches this handler too; without this\n   * check, that bubbled event would run react-hook-form's handleSubmit and commit an entity write the\n   * shopper never asked this FormRoot to make. Mirrors handleKeyDown's own origin check (there scoped\n   * by `target.form`), for the same reason: a nested form is never this one.\n   *\n   * Two properties of where this check sits are load-bearing. First, it reads `event.currentTarget`\n   * before any `await`: React nulls `currentTarget` once the synchronous part of a handler returns,\n   * so the same comparison placed after an await degrades to `event.target !== null` — always true —\n   * and rejects every submit, a permanently dead submit button with no error raised. It needs no test\n   * of its own: inserting an await above this check fails most of the tests in form.test.tsx, and\n   * moving it below the awaited `handleSubmit(...)` below fails the nested-form test in *Implicit\n   * submission*. Second, it runs before the re-entrancy check immediately below: while this form's own\n   * write is in flight, `submitting.current` is `true`, so a bubbled nested submit that reached the\n   * re-entrancy check first would call `event.preventDefault()` and cancel a nested form's own\n   * submission that this FormRoot never rendered. The last test in *Re-entrancy* pins that second\n   * property; nothing caught it before that test existed.\n   */\n  const handleFormSubmit = useCallback(\n    async (event: FormEvent<HTMLFormElement>) => {\n      if (event.target !== event.currentTarget) return;\n\n      if (submitting.current) {\n        event.preventDefault();\n        return;\n      }\n\n      submitting.current = true;\n      try {\n        await handleSubmit(onValid, onInvalid)(event);\n      } finally {\n        // Released after the awaited handler, not inside onValid: react-hook-form flips\n        // formState.isSubmitting to false in the statement immediately before its returned promise\n        // settles, so releasing here keeps the guard armed for a superset of the window in which\n        // isSubmitting is true. Releasing earlier — inside onValid's own finally, where this guard\n        // used to live — would open a sliver in which a third submit is accepted while isSubmitting\n        // is still true, reintroducing the defect this guard exists to close.\n        submitting.current = false;\n      }\n    },\n    [handleSubmit, onValid, onInvalid],\n  );\n\n  /**\n   * Cancels HTML implicit submission by default. A text input inside a form with a default button\n   * submits that form on Enter, which for an entity form means committing a write from a keystroke a\n   * shopper means as \"look this up\" or \"next field\" — before they have finished editing the rest of\n   * the sendable unit. That default is form-scoped and opt-in to override: mounting `FormEnterSubmit`\n   * anywhere inside this FormRoot allows Enter to submit from any of this form's own text-entry\n   * inputs, not only the fieldset the allowing part happens to sit in; a form composing only\n   * `FormSubmit` keeps today's cancelling behaviour. Enter that commits an IME candidate is cancelled\n   * either way, allowance or not, so choosing a word never submits a half-finished form. Submitting\n   * stays fully keyboard-operable either way, through a focusable native `FormSubmit`/`FormEnterSubmit`\n   * button, so no capability is removed (WCAG 2.1 SC 2.1.1). Scoped to text-entry inputs by target, so\n   * Enter on a button, a link, a `<textarea>`, a `contentEditable` region or a Base UI select trigger is\n   * untouched, and scoped to Enter, so typing is untouched. Also scoped to this form's own inputs by\n   * `target.form`: a keydown from a nested `<form>`'s own control bubbles up here too, and without that\n   * check this guard would cancel implicit submission for a form it never rendered. Composes rather\n   * than replaces an author-supplied `onKeyDown`: theirs runs first, unconditionally, before any of\n   * this guard's own checks — it can cancel Enter on an allowing form, but it cannot force Enter on a\n   * cancelling one, because this guard's own `preventDefault()` runs after it.\n   */\n  const handleKeyDown = useCallback(\n    (event: KeyboardEvent<HTMLFormElement>) => {\n      onKeyDown?.(event);\n      if (event.key !== 'Enter' || event.defaultPrevented) return;\n\n      const { target } = event;\n      if (!(target instanceof HTMLInputElement) || !TEXT_ENTRY_INPUT_TYPES.has(target.type)) return;\n      if (target.form !== event.currentTarget) return;\n      if (allowance.current.size > 0 && !event.nativeEvent.isComposing) return;\n\n      event.preventDefault();\n    },\n    [onKeyDown],\n  );\n\n  const registry = useMemo<FormRegistry>(() => ({ registerFieldset, failures }), [registerFieldset, failures]);\n\n  return (\n    <form\n      {...props}\n      noValidate\n      onSubmit={handleFormSubmit}\n      onKeyDown={handleKeyDown}\n      className={className}\n      data-fs-form=\"\"\n      data-fs-form-pending={isSubmitting ? '' : undefined}\n    >\n      <FormProvider {...form}>\n        <FormRegistryContext.Provider value={registry}>\n          <FieldsetSnapshotContext.Provider value={getFieldsetSnapshot}>\n            <ImplicitSubmissionContext.Provider value={registerAllowance}>\n              {children}\n            </ImplicitSubmissionContext.Provider>\n          </FieldsetSnapshotContext.Provider>\n        </FormRegistryContext.Provider>\n      </FormProvider>\n    </form>\n  );\n}\n\n/**\n * The shared render for both submit parts: same button, same hooks, same data-fs-form-submit hook.\n * Text resolves `children ?? label ?? formatMessage(...)` (RFC sketch) — never a hard-coded English\n * default — so an unauthored FormEnterSubmit reads correctly in every shipped locale, not only\n * en-US. One id, `fs/form.submit`, covers both parts: they render the same button, so a second id\n * for the Enter variant would only be a second translation of the same word.\n */\nfunction SubmitButton({ className, label, children }: FormSubmitProps): ReactNode {\n  const { isSubmitting } = useFormState();\n  const intl = useIntl();\n\n  return (\n    <Button\n      type=\"submit\"\n      disabled={isSubmitting}\n      className={className}\n      data-fs-form-submit=\"\"\n      data-fs-form-submit-pending={isSubmitting ? '' : undefined}\n    >\n      {children ?? label ?? intl.formatMessage({ id: 'fs/form.submit' })}\n    </Button>\n  );\n}\n\nexport function FormSubmit(props: FormSubmitProps): ReactNode {\n  useFormRegistry();\n  return <SubmitButton {...props} />;\n}\n\n/**\n * Renders the same button as `FormSubmit` and additionally allows Enter to submit this FormRoot's own\n * text-entry inputs while mounted — see `handleKeyDown`'s own doc for the form-scoped allowance and\n * the IME carve-out.\n */\nexport function FormEnterSubmit(props: FormSubmitProps): ReactNode {\n  useFormRegistry();\n  useAllowImplicitSubmission();\n  return <SubmitButton {...props} />;\n}\n\nexport function FormError({\n  className,\n  fallbackMessage = 'Something went wrong. Please try again.',\n}: FormErrorProps): ReactNode {\n  const { failures } = useFormRegistry();\n\n  if (failures.length === 0) return null;\n\n  return (\n    <div role=\"alert\" className={className} data-fs-form-error=\"\">\n      {failures.map((failure, failureIndex) => (\n        <ul key={`${failure.label}-${failureIndex}`} data-fs-form-error-item={failure.label}>\n          {failure.userErrors.length > 0 ? (\n            failure.userErrors.map((error, errorIndex) => (\n              <li key={`${failure.label}-${failureIndex}-${errorIndex}`}>{error.message}</li>\n            ))\n          ) : (\n            <li>{fallbackMessage}</li>\n          )}\n        </ul>\n      ))}\n    </div>\n  );\n}\n\nexport function FormClear({ className, label, children }: FormClearProps): ReactNode {\n  const getFieldsets = useFieldsetSnapshot();\n  const { control } = useFormContext();\n  const intl = useIntl();\n\n  // Empties every field registered by every fieldset — not `FormRoot` recognising a field's type\n  // (Invariant: it holds no field value and infers no field type). Each bound part registered its own\n  // clearer, keyed by its own name, when `useBoundField` mounted it (`particles/field/field.tsx`); a\n  // name with none registered — no bound part currently mounted for it — is left untouched.\n  function handleClear() {\n    for (const fieldset of getFieldsets()) {\n      for (const name of fieldset.getFieldNames()) {\n        clearBoundField(control, name);\n      }\n    }\n  }\n\n  return (\n    <Button type=\"button\" onClick={handleClear} className={className} data-fs-form-clear=\"\">\n      {children ?? label ?? intl.formatMessage({ id: 'fs/form.clear' })}\n    </Button>\n  );\n}\n\nexport function FormReset({ className, label, children }: FormResetProps): ReactNode {\n  const getFieldsets = useFieldsetSnapshot();\n  const { resetField } = useFormContext();\n  const intl = useIntl();\n\n  function handleReset() {\n    for (const fieldset of getFieldsets()) {\n      for (const name of fieldset.getFieldNames()) {\n        resetField(name);\n      }\n    }\n  }\n\n  return (\n    <Button type=\"button\" onClick={handleReset} className={className} data-fs-form-reset=\"\">\n      {children ?? label ?? intl.formatMessage({ id: 'fs/form.reset' })}\n    </Button>\n  );\n}\n\nexport const Form = {\n  Root: FormRoot,\n  Submit: FormSubmit,\n  EnterSubmit: FormEnterSubmit,\n  Error: FormError,\n  Clear: FormClear,\n  Reset: FormReset,\n};\n"],"mappings":"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"}