@vtex/faststore 0.0.10 → 0.0.12

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

@@ -1 +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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"}
+{"version":3,"file":"form.js","names":[],"sources":["../../../src/particles/form/form.tsx"],"sourcesContent":["'use client';\nimport { type ContentValue, defineComponent, defineContentType, type MessageLocaleProp } 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 { useMessageFormatter } from '../../sdk/i18n/use-message-formatter.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. Each resolved error's `message` is already\n   * worded from the fieldset's own `$content`, keyed on its `code`: `FormError` renders it as is.\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 `message` (the fieldset's own copy) or `FormError`'s\n   * `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 = MessageLocaleProp & {\n  $content?: ContentValue<typeof FormSubmitContent>;\n  className?: string;\n  children?: ReactNode;\n};\nexport type FormClearProps = MessageLocaleProp & {\n  $content?: ContentValue<typeof FormClearContent>;\n  className?: string;\n  children?: ReactNode;\n};\nexport type FormResetProps = MessageLocaleProp & {\n  $content?: ContentValue<typeof FormResetContent>;\n  className?: string;\n  children?: ReactNode;\n};\nexport type FormErrorProps = MessageLocaleProp & {\n  /** The message shown for a fieldset whose write rejected rather than resolving with userErrors. */\n  $content?: ContentValue<typeof FormErrorContent>;\n  className?: string;\n};\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 FormSubmitContent = defineContentType({\n  id: 'form-submit',\n  title: 'Form Submit',\n  description: 'Label of the button that submits the form.',\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    properties: {\n      label: { type: 'string', title: 'Label', format: 'icu-message', messageSource: 'Continue' },\n    },\n  },\n});\n\nexport const FormSubmitDefinition = defineComponent<FormSubmitProps>({\n  name: 'FormSubmit',\n  importPath: '@vtex/faststore/components',\n  component: FormSubmit,\n  content: FormSubmitContent,\n  requiresContext: 'form',\n  editor: { label: 'Form Submit', category: 'action' },\n  schema: {},\n  guideline:\n    'Submits every registered fieldset the shopper changed, in registration order, and disables itself while a write is in flight. Renders children, else its label message. 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  content: FormSubmitContent,\n  requiresContext: 'form',\n  editor: { label: 'Form Enter Submit', category: 'action' },\n  schema: {},\n  guideline:\n    'Renders the same button as FormSubmit, sharing its content type (form-submit) and children, 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 FormErrorContent = defineContentType({\n  id: 'form-error',\n  title: 'Form Error',\n  description: 'Message shown for a fieldset whose write failed without saying why.',\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    properties: {\n      fallbackMessage: {\n        type: 'string',\n        title: 'Fallback message',\n        format: 'icu-message',\n        messageSource: 'Something went wrong. Please try again.',\n      },\n    },\n  },\n});\n\nexport const FormErrorDefinition = defineComponent<FormErrorProps>({\n  name: 'FormError',\n  importPath: '@vtex/faststore/components',\n  component: FormError,\n  content: FormErrorContent,\n  requiresContext: 'form',\n  editor: { label: 'Form Error', category: 'content' },\n  schema: {},\n  guideline:\n    \"Renders the last submit's write failures grouped by fieldset, or nothing when there were none. The messages are the fieldsets' own copy: each fieldset words its refusals from its own $content, keyed on the error code. A fieldset whose write rejected rather than resolving with userErrors shows the fallbackMessage message.\",\n});\n\nexport const FormClearContent = defineContentType({\n  id: 'form-clear',\n  title: 'Form Clear',\n  description: \"Label of the button that empties the form's fields.\",\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    properties: {\n      label: { type: 'string', title: 'Label', format: 'icu-message', messageSource: 'Clear' },\n    },\n  },\n});\n\nexport const FormClearDefinition = defineComponent<FormClearProps>({\n  name: 'FormClear',\n  importPath: '@vtex/faststore/components',\n  component: FormClear,\n  content: FormClearContent,\n  requiresContext: 'form',\n  editor: { label: 'Form Clear', category: 'action' },\n  schema: {},\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, else its label message. 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 FormResetContent = defineContentType({\n  id: 'form-reset',\n  title: 'Form Reset',\n  description: \"Label of the button that returns the form's fields to their baseline.\",\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    properties: {\n      label: { type: 'string', title: 'Label', format: 'icu-message', messageSource: 'Reset' },\n    },\n  },\n});\n\nexport const FormResetDefinition = defineComponent<FormResetProps>({\n  name: 'FormReset',\n  importPath: '@vtex/faststore/components',\n  component: FormReset,\n  content: FormResetContent,\n  requiresContext: 'form',\n  editor: { label: 'Form Reset', category: 'action' },\n  schema: {},\n  guideline:\n    \"Returns every registered field to react-hook-form's baseline for that name and clears its dirty/touched state. Renders children, else its label message. 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 * Both read the `form-submit` content type: they render the same button.\n */\nfunction SubmitButton({ $content, className, children }: Readonly<FormSubmitProps>): ReactNode {\n  const { isSubmitting } = useFormState();\n  const { format } = useMessageFormatter(FormSubmitContent, $content);\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 ?? format('label')}\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({ $content, className }: FormErrorProps): ReactNode {\n  const { failures } = useFormRegistry();\n  const { format } = useMessageFormatter(FormErrorContent, $content);\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>{format('fallbackMessage')}</li>\n          )}\n        </ul>\n      ))}\n    </div>\n  );\n}\n\nexport function FormClear({ $content, className, children }: Readonly<FormClearProps>): ReactNode {\n  const getFieldsets = useFieldsetSnapshot();\n  const { control } = useFormContext();\n  const { format } = useMessageFormatter(FormClearContent, $content);\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 ?? format('label')}\n    </Button>\n  );\n}\n\nexport function FormReset({ $content, className, children }: Readonly<FormResetProps>): ReactNode {\n  const getFieldsets = useFieldsetSnapshot();\n  const { resetField } = useFormContext();\n  const { format } = useMessageFormatter(FormResetContent, $content);\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 ?? format('label')}\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":";;;;;;;;;;;AAuEA,MAAa,sBAAoD,cAAmC,IAAI;;AAGxG,SAAgB,kBAAgC;CAC9C,MAAM,WAAW,WAAW,mBAAmB;CAC/C,IAAI,CAAC,UAAU,MAAM,IAAI,MAAM,0CAA0C;CACzE,OAAO;AACT;;;;;;;;AASA,MAAM,0BAA0B,cAA8D,IAAI;AAElG,SAAS,sBAA6D;CACpE,MAAM,WAAW,WAAW,uBAAuB;CACnD,IAAI,CAAC,UAAU,MAAM,IAAI,MAAM,0CAA0C;CACzE,OAAO;AACT;;;;;;AAUA,MAAM,4BACJ,cAA8C,IAAI;;;;;;AAOpD,SAAS,6BAAmC;CAC1C,MAAM,QAAQ,WAAW,yBAAyB;CAGlD,MAAM,CAAC,SAAS,eAAe,OAAO,CAAC;CAEvC,gBAAgB;EACd,IAAI,CAAC,OAAO;EACZ,OAAO,MAAM,KAAK;CACpB,GAAG,CAAC,OAAO,KAAK,CAAC;CAIjB,IAAI,CAAC,OAAO,MAAM,IAAI,MAAM,0CAA0C;AACxE;;;;;;AAOA,SAAS,kBAAkB,GAAW,GAAoB;CACxD,IAAI,MAAM,GAAG,OAAO;CACpB,OAAO,EAAE,WAAW,GAAG,EAAE,EAAE,KAAK,EAAE,WAAW,GAAG,EAAE,EAAE;AACtD;;;;;;;;;;;;AAaA,SAAS,gBAAgB,aAAsC,OAAmC;CAChG,OAAO,MAAM,MAAM,SAAS;EAC1B,IAAI,OAAgB;EACpB,KAAK,MAAM,WAAW,KAAK,MAAM,GAAG,GAAG;GACrC,IAAI,OAAO,SAAS,YAAY,SAAS,MAAM,OAAO;GACtD,OAAQ,KAAiC;EAC3C;EACA,OAAO,QAAQ,IAAI;CACrB,CAAC;AACH;;;;;;;;AASA,SAAS,YAAY,GAAY,GAAqB;CACpD,OAAO,MAAM,KAAK,KAAK,UAAU,CAAC,MAAM,KAAK,UAAU,CAAC;AAC1D;;;;;;;;;;;;;AAcA,MAAa,2BAA2B;;;;;;;AAQxC,SAAS,oBAAoB,UAAgF;CAC3G,OAAO,IAAI,SAAS,SAAS,WAAW;EACtC,MAAM,QAAQ,iBAAiB;GAC7B,uBAAO,IAAI,MAAM,+CAA+C,yBAAyB,KAAK,CAAC;EACjG,GAAG,wBAAwB;EAE3B,SAAS,MACN,eAAe;GACd,aAAa,KAAK;GAClB,QAAQ,UAAU;EACpB,IACC,UAAU;GACT,aAAa,KAAK;GAClB,OAAO,KAAK;EACd,CACF;CACF,CAAC;AACH;;;;;;AAOA,MAAM,yCAAyB,IAAI,IAAI;CACrC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;AAmCD,MAAa,qBAAqB,gBAA+B;CAC/D,MAAM;CACN,YAAY;CACZ,WAAW;CACX,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAAQ,UAAU;CAAS;CAC5C,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,oBAAoB,kBAAkB;CACjD,IAAI;CACJ,OAAO;CACP,aAAa;CACb,QAAQ;EACN,MAAM;EACN,sBAAsB;EACtB,YAAY,EACV,OAAO;GAAE,MAAM;GAAU,OAAO;GAAS,QAAQ;GAAe,eAAe;EAAW,EAC5F;CACF;AACF,CAAC;AAED,MAAa,uBAAuB,gBAAiC;CACnE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,SAAS;CACT,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAAe,UAAU;CAAS;CACnD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,4BAA4B,gBAAiC;CACxE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,SAAS;CACT,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAAqB,UAAU;CAAS;CACzD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,mBAAmB,kBAAkB;CAChD,IAAI;CACJ,OAAO;CACP,aAAa;CACb,QAAQ;EACN,MAAM;EACN,sBAAsB;EACtB,YAAY,EACV,iBAAiB;GACf,MAAM;GACN,OAAO;GACP,QAAQ;GACR,eAAe;EACjB,EACF;CACF;AACF,CAAC;AAED,MAAa,sBAAsB,gBAAgC;CACjE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,SAAS;CACT,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAAc,UAAU;CAAU;CACnD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,mBAAmB,kBAAkB;CAChD,IAAI;CACJ,OAAO;CACP,aAAa;CACb,QAAQ;EACN,MAAM;EACN,sBAAsB;EACtB,YAAY,EACV,OAAO;GAAE,MAAM;GAAU,OAAO;GAAS,QAAQ;GAAe,eAAe;EAAQ,EACzF;CACF;AACF,CAAC;AAED,MAAa,sBAAsB,gBAAgC;CACjE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,SAAS;CACT,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAAc,UAAU;CAAS;CAClD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,mBAAmB,kBAAkB;CAChD,IAAI;CACJ,OAAO;CACP,aAAa;CACb,QAAQ;EACN,MAAM;EACN,sBAAsB;EACtB,YAAY,EACV,OAAO;GAAE,MAAM;GAAU,OAAO;GAAS,QAAQ;GAAe,eAAe;EAAQ,EACzF;CACF;AACF,CAAC;AAED,MAAa,sBAAsB,gBAAgC;CACjE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,SAAS;CACT,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAAc,UAAU;CAAS;CAClD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAMD,SAAgB,SAAS,EAAE,WAAW,UAAU,WAAW,GAAG,SAAmC;CAC/F,MAAM,OAAO,QAAQ;CACrB,MAAM,EACJ,cAQA,WAAW,EAAE,aAAa,gBAC1B,WACA,eACE;CAEJ,MAAM,YAAY,uBAAO,IAAI,IAAkC,CAAC;;;;;;;;CAQhE,MAAM,QAAQ,OAAiB,CAAC,CAAC;CACjC,MAAM,aAAa,OAAO,KAAK;CAC/B,MAAM,CAAC,UAAU,eAAe,SAAsC,CAAC,CAAC;;;;;;;CAOxE,MAAM,YAAY,uBAAO,IAAI,IAAY,CAAC;CAE1C,MAAM,mBAAmB,aAAa,iBAAuC;EAC3E,MAAM,EAAE,cAAc;EAEtB,KAAK,MAAM,YAAY,UAAU,QAAQ,OAAO,GAC9C,IAAI,kBAAkB,WAAW,SAAS,SAAS,GACjD,MAAM,IAAI,MACR,+DAA+D,SAAS,UAAU,0BAA0B,UAAU,yLACxH;EAIJ,IAAI,CAAC,MAAM,QAAQ,SAAS,SAAS,GACnC,MAAM,QAAQ,KAAK,SAAS;EAE9B,UAAU,QAAQ,IAAI,WAAW,YAAY;EAE7C,aAAa;GACX,IAAI,UAAU,QAAQ,IAAI,SAAS,MAAM,cACvC,UAAU,QAAQ,OAAO,SAAS;EAEtC;CACF,GAAG,CAAC,CAAC;CAEL,MAAM,sBAAsB,kBACpB,MAAM,QAAQ,SAAS,cAAc,UAAU,QAAQ,IAAI,SAAS,KAAK,CAAC,CAAC,GACjF,CAAC,CACH;CAEA,MAAM,oBAAoB,aAAa,UAAkB;EACvD,UAAU,QAAQ,IAAI,KAAK;EAC3B,aAAa;GACX,UAAU,QAAQ,OAAO,KAAK;EAChC;CACF,GAAG,CAAC,CAAC;CAEL,MAAM,UAAU,YAAY,YAAY;EACtC,YAAY,CAAC,CAAC;EACd,MAAM,YAAgC,CAAC;EACvC,MAAM,WAAW,oBAAoB;EAErC,KAAK,MAAM,YAAY,UAAU;GAC/B,IAAI;GACJ,IAAI;GACJ,IAAI;IACF,MAAM,aAAa,SAAS,cAAc;IAC1C,IAAI,CAAC,gBAAgB,aAAa,UAAU,GAAG;IAC/C,oBAAoB,WAAW,KAAK,SAAS,CAAC,MAAM,UAAU,IAAI,CAAC,CAAU;IAC7E,MAAM,UAAU,SAAS,UAAU,UAAU,SAAS,SAAS,KAAK,CAAC,CAAC;IACtE,aAAa,MAAM,oBAAoB,SAAS,SAAS,OAAO,CAAC;GACnE,QAAQ;IAIN,UAAU,KAAK;KAAE,OAAO,SAAS;KAAO,YAAY,CAAC;IAAE,CAAC;IACxD;GACF;GAEA,IAAI,WAAW,SAAS,GAAG;IACzB,UAAU,KAAK;KAAE,OAAO,SAAS;KAAO;IAAW,CAAC;IACpD;GACF;GAWA,KAAK,MAAM,CAAC,MAAM,kBAAkB,mBAClC,IAAI,YAAY,UAAU,IAAI,GAAG,aAAa,GAC5C,WAAW,MAAM,EAAE,cAAc,cAAc,CAAC;EAGtD;EAEA,YAAY,SAAS;CACvB,GAAG;EAAC;EAAa;EAAW;EAAY;CAAmB,CAAC;CAE5D,MAAM,YAAY,kBAAkB;EAClC,YAAY,CAAC,CAAC;CAChB,GAAG,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;CAsBL,MAAM,mBAAmB,YACvB,OAAO,UAAsC;EAC3C,IAAI,MAAM,WAAW,MAAM,eAAe;EAE1C,IAAI,WAAW,SAAS;GACtB,MAAM,eAAe;GACrB;EACF;EAEA,WAAW,UAAU;EACrB,IAAI;GACF,MAAM,aAAa,SAAS,SAAS,CAAC,CAAC,KAAK;EAC9C,UAAU;GAOR,WAAW,UAAU;EACvB;CACF,GACA;EAAC;EAAc;EAAS;CAAS,CACnC;;;;;;;;;;;;;;;;;;;;CAqBA,MAAM,gBAAgB,aACnB,UAA0C;EACzC,YAAY,KAAK;EACjB,IAAI,MAAM,QAAQ,WAAW,MAAM,kBAAkB;EAErD,MAAM,EAAE,WAAW;EACnB,IAAI,EAAE,kBAAkB,qBAAqB,CAAC,uBAAuB,IAAI,OAAO,IAAI,GAAG;EACvF,IAAI,OAAO,SAAS,MAAM,eAAe;EACzC,IAAI,UAAU,QAAQ,OAAO,KAAK,CAAC,MAAM,YAAY,aAAa;EAElE,MAAM,eAAe;CACvB,GACA,CAAC,SAAS,CACZ;CAEA,MAAM,WAAW,eAA6B;EAAE;EAAkB;CAAS,IAAI,CAAC,kBAAkB,QAAQ,CAAC;CAE3G,OACE,oBAAC,QAAD;EACE,GAAI;EACJ,YAAA;EACA,UAAU;EACV,WAAW;EACA;EACX,gBAAa;EACb,wBAAsB,eAAe,KAAK,KAAA;EAE1C,UAAA,oBAAC,cAAD;GAAc,GAAI;GAChB,UAAA,oBAAC,oBAAoB,UAArB;IAA8B,OAAO;IACnC,UAAA,oBAAC,wBAAwB,UAAzB;KAAkC,OAAO;KACvC,UAAA,oBAAC,0BAA0B,UAA3B;MAAoC,OAAO;MACxC;KACiC,CAAA;IACJ,CAAA;GACN,CAAA;EAClB,CAAA;CACV,CAAA;AAEV;;;;;AAMA,SAAS,aAAa,EAAE,UAAU,WAAW,YAAkD;CAC7F,MAAM,EAAE,iBAAiB,aAAa;CACtC,MAAM,EAAE,WAAW,oBAAoB,mBAAmB,QAAQ;CAElE,OACE,oBAAC,QAAD;EACE,MAAK;EACL,UAAU;EACC;EACX,uBAAoB;EACpB,+BAA6B,eAAe,KAAK,KAAA;EAEhD,UAAA,YAAY,OAAO,OAAO;CACrB,CAAA;AAEZ;AAEA,SAAgB,WAAW,OAAmC;CAC5D,gBAAgB;CAChB,OAAO,oBAAC,cAAD,EAAc,GAAI,MAAQ,CAAA;AACnC;;;;;;AAOA,SAAgB,gBAAgB,OAAmC;CACjE,gBAAgB;CAChB,2BAA2B;CAC3B,OAAO,oBAAC,cAAD,EAAc,GAAI,MAAQ,CAAA;AACnC;AAEA,SAAgB,UAAU,EAAE,UAAU,aAAwC;CAC5E,MAAM,EAAE,aAAa,gBAAgB;CACrC,MAAM,EAAE,WAAW,oBAAoB,kBAAkB,QAAQ;CAEjE,IAAI,SAAS,WAAW,GAAG,OAAO;CAElC,OACE,oBAAC,OAAD;EAAK,MAAK;EAAmB;EAAW,sBAAmB;EACxD,UAAA,SAAS,KAAK,SAAS,iBACtB,oBAAC,MAAD;GAA6C,2BAAyB,QAAQ;GAC3E,UAAA,QAAQ,WAAW,SAAS,IAC3B,QAAQ,WAAW,KAAK,OAAO,eAC7B,oBAAC,MAAD,EAAA,UAA4D,MAAM,QAAY,GAArE,GAAG,QAAQ,MAAM,GAAG,aAAa,GAAG,YAAiC,CAC/E,IAED,oBAAC,MAAD,EAAA,UAAK,OAAO,iBAAiB,EAAM,CAAA;EAEnC,GARK,GAAG,QAAQ,MAAM,GAAG,cAQzB,CACL;CACE,CAAA;AAET;AAEA,SAAgB,UAAU,EAAE,UAAU,WAAW,YAAiD;CAChG,MAAM,eAAe,oBAAoB;CACzC,MAAM,EAAE,YAAY,eAAe;CACnC,MAAM,EAAE,WAAW,oBAAoB,kBAAkB,QAAQ;CAMjE,SAAS,cAAc;EACrB,KAAK,MAAM,YAAY,aAAa,GAClC,KAAK,MAAM,QAAQ,SAAS,cAAc,GACxC,gBAAgB,SAAS,IAAI;CAGnC;CAEA,OACE,oBAAC,QAAD;EAAQ,MAAK;EAAS,SAAS;EAAwB;EAAW,sBAAmB;EAClF,UAAA,YAAY,OAAO,OAAO;CACrB,CAAA;AAEZ;AAEA,SAAgB,UAAU,EAAE,UAAU,WAAW,YAAiD;CAChG,MAAM,eAAe,oBAAoB;CACzC,MAAM,EAAE,eAAe,eAAe;CACtC,MAAM,EAAE,WAAW,oBAAoB,kBAAkB,QAAQ;CAEjE,SAAS,cAAc;EACrB,KAAK,MAAM,YAAY,aAAa,GAClC,KAAK,MAAM,QAAQ,SAAS,cAAc,GACxC,WAAW,IAAI;CAGrB;CAEA,OACE,oBAAC,QAAD;EAAQ,MAAK;EAAS,SAAS;EAAwB;EAAW,sBAAmB;EAClF,UAAA,YAAY,OAAO,OAAO;CACrB,CAAA;AAEZ;AAEA,MAAa,OAAO;CAClB,MAAM;CACN,QAAQ;CACR,aAAa;CACb,OAAO;CACP,OAAO;CACP,OAAO;AACT"}

package/dist/particles/gallery/gallery.d.ts

@@ -1,7 +1,122 @@
+import { ContentValue, MessageLocaleProp } from "../../core/dist/define-content-type.js";
 import { ComponentDefinition } from "../../core/dist/define-component.js";
 import "../../core/dist/index.js";
 import { ComponentPropsWithRef, ReactNode } from "react";
 //#region src/particles/gallery/gallery.d.ts
+export declare const GalleryOverflowCountContent: {
+  readonly id: "gallery-overflow-count";
+  readonly title: "Gallery Overflow Count";
+  readonly description: "Text and accessible name of the overflow indicator that opens the fullscreen gallery.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly template: {
+        readonly type: "string";
+        readonly title: "Text";
+        readonly description: "The count argument is the number of hidden media items.";
+        readonly format: "icu-message";
+        readonly messageSource: "+{count}";
+        readonly messageArguments: {
+          readonly type: "object";
+          readonly properties: {
+            readonly count: {
+              readonly type: "integer";
+            };
+          };
+        };
+        readonly messageExample: {
+          readonly count: 3;
+        };
+      };
+      readonly ariaLabel: {
+        readonly type: "string";
+        readonly title: "Accessible label";
+        readonly description: "The total argument is the number of media items in the gallery.";
+        readonly format: "icu-message";
+        readonly messageSource: "View all {total} images";
+        readonly messageArguments: {
+          readonly type: "object";
+          readonly properties: {
+            readonly total: {
+              readonly type: "integer";
+            };
+          };
+        };
+        readonly messageExample: {
+          readonly total: 8;
+        };
+      };
+    };
+  };
+};
+export declare const GalleryFullscreenContent: {
+  readonly id: "gallery-fullscreen";
+  readonly title: "Gallery Fullscreen";
+  readonly description: "Accessible name of the fullscreen dialog when no GalleryFullscreenTitle is composed.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly title: {
+        readonly type: "string";
+        readonly title: "Fallback title";
+        readonly format: "icu-message";
+        readonly messageSource: "Gallery";
+      };
+    };
+  };
+};
+export declare const GalleryFullscreenTitleContent: {
+  readonly id: "gallery-fullscreen-title";
+  readonly title: "Gallery Fullscreen Title";
+  readonly description: "Title of the fullscreen dialog, used when no children are composed.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Title";
+        readonly format: "icu-message";
+        readonly messageSource: "Gallery";
+      };
+    };
+  };
+};
+export declare const GalleryMediaCountContent: {
+  readonly id: "gallery-media-count";
+  readonly title: "Gallery Media Count";
+  readonly description: "Position of the selected media item in the gallery.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly template: {
+        readonly type: "string";
+        readonly title: "Text";
+        readonly description: "current is the 1-based position of the selected item; total is the item count.";
+        readonly format: "icu-message";
+        readonly messageSource: "{current} / {total}";
+        readonly messageArguments: {
+          readonly type: "object";
+          readonly properties: {
+            readonly current: {
+              readonly type: "integer";
+            };
+            readonly total: {
+              readonly type: "integer";
+            };
+          };
+        };
+        readonly messageExample: {
+          readonly current: 2;
+          readonly total: 8;
+        };
+      };
+    };
+  };
+};
 export type GalleryMediaType = 'image' | 'video';
 export type GalleryMediaItem = {
   type: GalleryMediaType;
@@ -86,9 +201,8 @@ export type GalleryThumbnailProps = ComponentPropsWithRef<'button'> & {
   objectFit?: 'contain' | 'cover' | 'fill' | 'none';
   aspectRatio?: string;
 };
-export type GalleryOverflowCountProps = ComponentPropsWithRef<'button'> & {
-  template?: string;
-  ariaLabel?: string;
+export type GalleryOverflowCountProps = ComponentPropsWithRef<'button'> & MessageLocaleProp & {
+  $content?: ContentValue<typeof GalleryOverflowCountContent>;
 };
 export type GalleryMediaProps = ComponentPropsWithRef<'div'> & {
   objectFit?: 'contain' | 'cover' | 'fill' | 'none';
@@ -103,10 +217,13 @@ export type GalleryZoomProps = ComponentPropsWithRef<'div'> & {
 };
 export type GalleryZoomLensProps = ComponentPropsWithRef<'div'>;
 export type GalleryZoomResultProps = ComponentPropsWithRef<'div'>;
-export type GalleryFullscreenProps = ComponentPropsWithRef<'div'> & {
+export type GalleryFullscreenProps = ComponentPropsWithRef<'div'> & MessageLocaleProp & {
   children?: ReactNode;
+  $content?: ContentValue<typeof GalleryFullscreenContent>;
+};
+export type GalleryFullscreenTitleProps = ComponentPropsWithRef<'h2'> & MessageLocaleProp & {
+  $content?: ContentValue<typeof GalleryFullscreenTitleContent>;
 };
-export type GalleryFullscreenTitleProps = ComponentPropsWithRef<'h2'>;
 export type GalleryFullscreenCloseProps = ComponentPropsWithRef<'button'> & {
   children?: ReactNode;
 };
@@ -118,8 +235,8 @@ export type GalleryNextProps = ComponentPropsWithRef<'button'> & {
   children?: ReactNode;
   wrap?: boolean;
 };
-export type GalleryMediaCountProps = ComponentPropsWithRef<'span'> & {
-  template?: string;
+export type GalleryMediaCountProps = ComponentPropsWithRef<'span'> & MessageLocaleProp & {
+  $content?: ContentValue<typeof GalleryMediaCountContent>;
 };
 export declare const GalleryItemContext: import("react").Context<GalleryItemContextValue | null>;
 export declare function useGallery(): GalleryContextValue;
@@ -136,7 +253,7 @@ export declare const GalleryZoomDefinition: ComponentDefinition<GalleryZoomProps
 export declare const GalleryZoomLensDefinition: ComponentDefinition<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>;
 export declare const GalleryZoomResultDefinition: ComponentDefinition<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>;
 export declare const GalleryFullscreenDefinition: ComponentDefinition<GalleryFullscreenProps>;
-export declare const GalleryFullscreenTitleDefinition: ComponentDefinition<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>>;
+export declare const GalleryFullscreenTitleDefinition: ComponentDefinition<GalleryFullscreenTitleProps>;
 export declare const GalleryFullscreenCloseDefinition: ComponentDefinition<GalleryFullscreenCloseProps>;
 export declare const GalleryPreviousDefinition: ComponentDefinition<GalleryPreviousProps>;
 export declare const GalleryNextDefinition: ComponentDefinition<GalleryNextProps>;
@@ -145,19 +262,19 @@ export declare function GalleryRoot({ media, defaultIndex, selectOnHover, thumbn
 export declare function GalleryMainMedia({ objectFit, aspectRatio, videoAutoPlay, videoControls, clickOpensFullscreen, style, ...props }: GalleryMainMediaProps): import("react/jsx-runtime").JSX.Element;
 export declare function GalleryThumbnails({ hideWhenSingle, ...rest }: GalleryThumbnailsProps): import("react/jsx-runtime").JSX.Element | null;
 export declare function GalleryThumbnail({ objectFit, aspectRatio, style, ...props }: GalleryThumbnailProps): import("react/jsx-runtime").JSX.Element;
-export declare function GalleryOverflowCount({ template, ariaLabel, ...props }: GalleryOverflowCountProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function GalleryOverflowCount({ $locale, $content, ...props }: GalleryOverflowCountProps): import("react/jsx-runtime").JSX.Element | null;
 export declare function GalleryMedia({ objectFit, aspectRatio, videoAutoPlay, videoControls, clickOpensFullscreen, style, ...props }: GalleryMediaProps): import("react/jsx-runtime").JSX.Element;
 export declare function GalleryZoom({ magnification, lensSize, children, ...props }: GalleryZoomProps): import("react/jsx-runtime").JSX.Element;
 export declare function GalleryZoomLens({ style, ...props }: GalleryZoomLensProps): import("react/jsx-runtime").JSX.Element | null;
 export declare function GalleryZoomResult({ style, ...props }: GalleryZoomResultProps): import("react/jsx-runtime").JSX.Element;
-export declare function GalleryFullscreen({ children, ...props }: GalleryFullscreenProps): import("react/jsx-runtime").JSX.Element;
-export declare function GalleryFullscreenTitle({ children, ...props }: GalleryFullscreenTitleProps): import("react/jsx-runtime").JSX.Element;
+export declare function GalleryFullscreen({ $locale, $content, children, ...props }: GalleryFullscreenProps): import("react/jsx-runtime").JSX.Element;
+export declare function GalleryFullscreenTitle({ $locale, $content, children, ...props }: GalleryFullscreenTitleProps): import("react/jsx-runtime").JSX.Element;
 export declare function GalleryFullscreenClose({ children, ...props }: GalleryFullscreenCloseProps): import("react/jsx-runtime").JSX.Element;
 export declare function GalleryPrevious({ children, wrap, ...props }: GalleryPreviousProps): import("react/jsx-runtime").JSX.Element;
 export declare function GalleryNext({ children, wrap, ...props }: GalleryNextProps): import("react/jsx-runtime").JSX.Element;
 export declare function GalleryThumbnailsPrevious({ step, children, ...props }: GalleryThumbnailsPreviousProps): import("react/jsx-runtime").JSX.Element;
 export declare function GalleryThumbnailsNext({ step, children, ...props }: GalleryThumbnailsNextProps): import("react/jsx-runtime").JSX.Element;
-export declare function GalleryMediaCount({ template, ...props }: GalleryMediaCountProps): import("react/jsx-runtime").JSX.Element;
+export declare function GalleryMediaCount({ $locale, $content, ...props }: GalleryMediaCountProps): import("react/jsx-runtime").JSX.Element;
 export declare const Gallery: {
   Root: typeof GalleryRoot;
   MainMedia: typeof GalleryMainMedia;