@vtex/faststore 0.0.4 → 0.0.6

package/dist/particles/field/field.js.map

@@ -1 +1 @@
-{"version":3,"file":"field.js","names":["BaseField","Field"],"sources":["../../../src/particles/field/field.tsx"],"sourcesContent":["'use client';\nimport type { FieldValidityState } from '@base-ui/react/field';\nimport { Field as BaseField } from '@base-ui/react/field';\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef, ReactNode } from 'react';\n\nexport type FieldRootProps = ComponentPropsWithRef<'div'> & {\n  disabled?: boolean;\n  invalid?: boolean;\n  name?: string;\n};\n\nexport type FieldLabelProps = ComponentPropsWithRef<'label'>;\n\nexport type FieldControlProps = Omit<ComponentPropsWithRef<'input'>, 'children'>;\n\nexport type FieldDescriptionProps = ComponentPropsWithRef<'p'>;\n\nexport type FieldErrorProps = ComponentPropsWithRef<'div'> & {\n  /**\n   * Controls when the error is shown. `true` always shows it (for externally/caller-driven\n   * validity, e.g. presence-only checks with no native constraint validation); a\n   * `ValidityState` key shows it only when that specific native validity flag is set. Omit to\n   * fall back to Base UI's default: shown whenever the field's tracked validity is invalid.\n   * Note `match={false}` does not suppress the error — it falls back to that default\n   * invalid-driven behavior; callers needing a boolean should use `invalid ? true : 'customError'`.\n   */\n  match?: boolean | keyof ValidityState;\n};\n\nexport type FieldValidityProps = {\n  children: (state: FieldValidityState) => ReactNode;\n};\n\nexport const FieldRootDefinition = defineComponent<FieldRootProps>({\n  name: 'FieldRoot',\n  importPath: '@vtex/faststore/components',\n  component: FieldRoot,\n  editor: { label: 'Field Root', category: 'layout' },\n  schema: {\n    disabled: { type: 'boolean', default: false, label: 'Disabled' },\n  },\n  guideline:\n    'Form field container that connects a label, input, and validation messages via ARIA. Use Field.Control as the input element, or place a compatible Base UI input (Input, Checkbox, Select) as a direct child. Set invalid=true to trigger Field.Error display.',\n});\n\nexport const FieldLabelDefinition = defineComponent<FieldLabelProps>({\n  name: 'FieldLabel',\n  importPath: '@vtex/faststore/components',\n  component: FieldLabel,\n  editor: { label: 'Field Label', category: 'layout' },\n  schema: {},\n  guideline:\n    \"Accessible label inside Field.Root. Automatically associated with Field.Control's input via ARIA. Place before Field.Control in the DOM.\",\n});\n\nexport const FieldControlDefinition = defineComponent<FieldControlProps>({\n  name: 'FieldControl',\n  importPath: '@vtex/faststore/components',\n  component: FieldControl,\n  editor: { label: 'Field Control', category: 'layout' },\n  schema: {},\n  guideline:\n    'Renders a native `<input>` element directly. It IS the input — do not place any child inside it. Pass input attributes (type, placeholder, required, etc.) directly as props. It is automatically linked to Field.Label and Field.Error via ARIA.',\n});\n\nexport const FieldDescriptionDefinition = defineComponent<FieldDescriptionProps>({\n  name: 'FieldDescription',\n  importPath: '@vtex/faststore/components',\n  component: FieldDescription,\n  editor: { label: 'Field Description', category: 'layout' },\n  schema: {},\n  guideline:\n    'Helper text inside Field.Root. Automatically linked to the control via aria-describedby. Always visible regardless of validation state.',\n});\n\nexport const FieldErrorDefinition = defineComponent<FieldErrorProps>({\n  name: 'FieldError',\n  importPath: '@vtex/faststore/components',\n  component: FieldError,\n  editor: { label: 'Field Error', category: 'layout' },\n  schema: {},\n  guideline:\n    'Validation error message inside Field.Root. Shown when the field is in an invalid state. Linked to the control via aria-describedby.',\n});\n\nexport const FieldValidityDefinition = defineComponent<FieldValidityProps>({\n  name: 'FieldValidity',\n  importPath: '@vtex/faststore/components',\n  component: FieldValidity,\n  editor: { label: 'Field Validity', category: 'layout' },\n  schema: {},\n  guideline:\n    \"Validation feedback slot using a render prop for custom messages derived from the field's validity state. Use for dynamic messages when Field.Error text is not fixed.\",\n});\n\nexport function FieldRoot({ disabled, invalid, name, className, children, ...props }: FieldRootProps) {\n  return (\n    <BaseField.Root\n      {...props}\n      disabled={disabled}\n      invalid={invalid}\n      name={name}\n      className={className}\n      data-fs-field-root=\"\"\n    >\n      {children}\n    </BaseField.Root>\n  );\n}\n\nexport function FieldLabel({ className, children, ...props }: FieldLabelProps) {\n  return (\n    <BaseField.Label {...props} className={className} data-fs-field-label=\"\">\n      {children}\n    </BaseField.Label>\n  );\n}\n\nexport function FieldControl({ className, ...props }: FieldControlProps) {\n  return <BaseField.Control {...props} className={className} data-fs-field-control=\"\" />;\n}\n\nexport function FieldDescription({ className, children, ...props }: FieldDescriptionProps) {\n  return (\n    <BaseField.Description {...props} className={className} data-fs-field-description=\"\">\n      {children}\n    </BaseField.Description>\n  );\n}\n\nexport function FieldError({ className, children, ...props }: FieldErrorProps) {\n  return (\n    <BaseField.Error {...props} className={className} data-fs-field-error=\"\">\n      {children}\n    </BaseField.Error>\n  );\n}\n\nexport function FieldValidity({ children }: FieldValidityProps) {\n  return <BaseField.Validity>{children}</BaseField.Validity>;\n}\n\nexport const Field = {\n  Root: FieldRoot,\n  Label: FieldLabel,\n  Control: FieldControl,\n  Description: FieldDescription,\n  Error: FieldError,\n  Validity: FieldValidity,\n};\n"],"mappings":";;;;;;AAkCA,MAAa,sBAAsB,gBAAgC;CACjE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAc,UAAU;CAAS;CAClD,QAAQ,EACN,UAAU;EAAE,MAAM;EAAW,SAAS;EAAO,OAAO;CAAW,EACjE;CACA,WACE;AACJ,CAAC;AAED,MAAa,uBAAuB,gBAAiC;CACnE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAe,UAAU;CAAS;CACnD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,yBAAyB,gBAAmC;CACvE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAiB,UAAU;CAAS;CACrD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,6BAA6B,gBAAuC;CAC/E,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAqB,UAAU;CAAS;CACzD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,uBAAuB,gBAAiC;CACnE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAe,UAAU;CAAS;CACnD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,0BAA0B,gBAAoC;CACzE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAkB,UAAU;CAAS;CACtD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,SAAgB,UAAU,EAAE,UAAU,SAAS,MAAM,WAAW,UAAU,GAAG,SAAyB;CACpG,OACE,oBAACA,MAAU,MAAX;EACE,GAAI;EACM;EACD;EACH;EACK;EACX,sBAAmB;EAElB;CACa,CAAA;AAEpB;AAEA,SAAgB,WAAW,EAAE,WAAW,UAAU,GAAG,SAA0B;CAC7E,OACE,oBAACA,MAAU,OAAX;EAAiB,GAAI;EAAkB;EAAW,uBAAoB;EACnE;CACc,CAAA;AAErB;AAEA,SAAgB,aAAa,EAAE,WAAW,GAAG,SAA4B;CACvE,OAAO,oBAACA,MAAU,SAAX;EAAmB,GAAI;EAAkB;EAAW,yBAAsB;CAAI,CAAA;AACvF;AAEA,SAAgB,iBAAiB,EAAE,WAAW,UAAU,GAAG,SAAgC;CACzF,OACE,oBAACA,MAAU,aAAX;EAAuB,GAAI;EAAkB;EAAW,6BAA0B;EAC/E;CACoB,CAAA;AAE3B;AAEA,SAAgB,WAAW,EAAE,WAAW,UAAU,GAAG,SAA0B;CAC7E,OACE,oBAACA,MAAU,OAAX;EAAiB,GAAI;EAAkB;EAAW,uBAAoB;EACnE;CACc,CAAA;AAErB;AAEA,SAAgB,cAAc,EAAE,YAAgC;CAC9D,OAAO,oBAACA,MAAU,UAAX,EAAqB,SAA6B,CAAA;AAC3D;AAEA,MAAaC,UAAQ;CACnB,MAAM;CACN,OAAO;CACP,SAAS;CACT,aAAa;CACb,OAAO;CACP,UAAU;AACZ"}
+{"version":3,"file":"field.js","names":["BaseField","Field"],"sources":["../../../src/particles/field/field.tsx"],"sourcesContent":["'use client';\nimport type { FieldValidityState } from '@base-ui/react/field';\nimport { Field as BaseField } from '@base-ui/react/field';\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef, ReactNode, RefCallback } from 'react';\nimport { createContext, useCallback, useContext, useEffect, useMemo, useRef } from 'react';\nimport type { Control, RegisterOptions } from 'react-hook-form';\nimport { useController, useFormContext, useFormState } from 'react-hook-form';\nimport { Checkbox } from '../checkbox/checkbox.js';\nimport { registerFieldClearer } from './bound-field-registry.js';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type FieldRootProps = ComponentPropsWithRef<'div'> & {\n  disabled?: boolean;\n  invalid?: boolean;\n  name?: string;\n};\n\nexport type FieldLabelProps = ComponentPropsWithRef<'label'>;\n\nexport type FieldControlProps = Omit<ComponentPropsWithRef<'input'>, 'children'>;\n\nexport type FieldDescriptionProps = ComponentPropsWithRef<'p'>;\n\nexport type FieldErrorProps = ComponentPropsWithRef<'div'> & {\n  /**\n   * Controls when the error is shown. `true` always shows it (for externally/caller-driven\n   * validity, e.g. presence-only checks with no native constraint validation); a\n   * `ValidityState` key shows it only when that specific native validity flag is set. Omit to\n   * fall back to Base UI's default: shown whenever the field's tracked validity is invalid.\n   * Note `match={false}` does not suppress the error — it falls back to that default\n   * invalid-driven behavior; callers needing a boolean should use `invalid ? true : 'customError'`.\n   * Only consulted on the unbound path — a bound `Field.Error` renders from the field contract's\n   * name and react-hook-form's error state instead.\n   */\n  match?: boolean | keyof ValidityState;\n};\n\nexport type FieldValidityProps = {\n  children: (state: FieldValidityState) => ReactNode;\n};\n\n/** One choice of a field whose value is picked from a list. Platform-owned; an author reorders the part, not the list. */\nexport type FieldOption = Readonly<{ value: string; label: string }>;\n\n/** A rule member constrained to `value`, carrying its own message — react-hook-form's own shape for\n * a constrained validation rule, declared here as our own type (Decision 5). */\nexport type FieldRuleConstraint<T> = Readonly<{ value: T; message: string }>;\n\n/** A field-level validator: reads the live value, returns `true` (valid), a message, or `false`. */\nexport type FieldValidator = (value: unknown) => boolean | string;\n\n/**\n * The fieldset's validation rule for this field, handed to `useBoundField` and mapped internally to\n * react-hook-form's `RegisterOptions` (`toRegisterOptions`) — nothing that imports this type from the\n * barrel ever names a react-hook-form type (RFC `Dependencies`).\n *\n * These seven members are a starting point measured against every rule this repository authors\n * today, not a closed contract: `RegisterOptions` carries more (`setValueAs`, `deps`, `valueAsNumber`,\n * …), and a member is added here the day a field actually needs it — this is not a deliberately closed\n * set to work around.\n */\nexport type FieldRule = Readonly<{\n  required?: boolean | string | FieldRuleConstraint<boolean>;\n  min?: number | string | FieldRuleConstraint<number | string>;\n  max?: number | string | FieldRuleConstraint<number | string>;\n  minLength?: number | FieldRuleConstraint<number>;\n  maxLength?: number | FieldRuleConstraint<number>;\n  pattern?: RegExp | FieldRuleConstraint<RegExp>;\n  validate?: FieldValidator | Readonly<Record<string, FieldValidator>>;\n}>;\n\n/**\n * The one place `RegisterOptions` is named as a value type. `FieldRule`'s members are declared\n * independently of react-hook-form's (Decision 5), but each already carries react-hook-form's own\n * runtime shape (a bare value, or `{ value, message }`), so this is an assertion, not a per-member\n * transform. `field-rule.type-test.tsx` pins the boundary from the other side: it fails to compile if\n * `FieldRule` ever widens back to a bare `RegisterOptions` alias.\n */\nfunction toRegisterOptions(rule: FieldRule | undefined): RegisterOptions | undefined {\n  return rule as RegisterOptions | undefined;\n}\n\n/**\n * A control's own bid to make its field required. A control raises; it never lowers — so `false` and\n * an absent raise are the same thing, no opinion, and a baseline that already says required survives\n * either. `message` is the copy the raise brings with it (`PhoneField`'s `errorRequired`), used only\n * when the raise is what carries the field to required.\n */\nexport type FieldRequirementRaise = Readonly<{\n  required?: boolean;\n  message?: string;\n}>;\n\n/**\n * One field's requiredness, resolved once and read everywhere: the announcement, the blank check and\n * the error copy all come from here, so they cannot disagree.\n */\nexport type ResolvedRequiredness = Readonly<{\n  /** `baselineRequired || authorRaise`. Spread into `aria-required` as `required || undefined`, so a\n   * field never announces `aria-required=\"false\"`. */\n  required: boolean;\n  /** What the blank check reports. Absent when neither side supplied copy. */\n  message?: string;\n  /** The rule to register with: the baseline, carrying the blank check when the field is required. */\n  rule: FieldRule | undefined;\n}>;\n\n/**\n * react-hook-form's own reading of `required`: `.value` for the object form\n * (`{ value: boolean; message: string }`), plain truthiness otherwise (a boolean or a message\n * string). A message string is itself the copy, which is why the two are read together.\n */\nfunction readBaseline(rule: FieldRule | undefined): { required: boolean; message?: string } {\n  const required = rule?.required;\n  if (typeof required === 'object' && required !== null) {\n    return { required: Boolean(required.value), message: required.value ? required.message : undefined };\n  }\n  if (typeof required === 'string') return { required: true, message: required };\n  return { required: Boolean(required) };\n}\n\n/** A `validate` member is either one function or a record of named ones; downstream only wants the record. */\nfunction normaliseValidators(validate: FieldRule['validate']): Record<string, FieldValidator> {\n  if (!validate) return {};\n  return typeof validate === 'function' ? { validate } : { ...validate };\n}\n\n/**\n * Composes `validator` into `rule` under `name`, alongside whatever the rule already validates —\n * never instead of it. The two composites reach for this to keep their own format check while a\n * fieldset-supplied validator stays in force; before it, both discarded their own validation whole\n * the moment the fieldset supplied any.\n */\nexport function mergeFieldValidator(rule: FieldRule | undefined, name: string, validator: FieldValidator): FieldRule {\n  return { ...rule, validate: { ...normaliseValidators(rule?.validate), [name]: validator } };\n}\n\n/**\n * The one resolution of `required = baselineRequired || authorRaise`. The fieldset's `FieldRule` is\n * the baseline; a control may raise a field to required and never lower one, so `raise.required`\n * only ever adds. Read-only deliberately plays no part: a field that is read-only and required stays\n * required, and an unsatisfiable form is the declared baseline's fault, not this function's.\n *\n * Baseline copy wins over the raise's, matching react-hook-form's own order — it evaluates `required`\n * before `validate`, so the fieldset's message was already the one a shopper saw whenever both existed.\n *\n * `required` catches an empty string but not a space-filled one (`inputValue === ''` is\n * react-hook-form's only emptiness test for a string), so the blank check goes in beside it. It is\n * installed last, so it cannot be displaced by a same-named validator from the rule.\n */\nexport function resolveRequiredness(rule: FieldRule | undefined, raise?: FieldRequirementRaise): ResolvedRequiredness {\n  const baseline = readBaseline(rule);\n  const required = baseline.required || Boolean(raise?.required);\n\n  if (!required) return { required: false, rule };\n\n  const message = baseline.message ?? (baseline.required ? undefined : raise?.message);\n  const notBlank: FieldValidator = (value) => String(value ?? '').trim().length > 0 || message || false;\n\n  return { required, message, rule: { ...mergeFieldValidator(rule, 'notBlank', notBlank), required: message ?? true } };\n}\n\n/**\n * One field's identity and its static facts: the argument list `useController` needs, hoisted out of\n * a prop-drill that composition made impossible. Not a mirror of state react-hook-form also holds —\n * it carries NO live value, so it never changes while the shopper types, and the parts subscribe to\n * react-hook-form for value, error, dirty and touched.\n */\nexport type FieldContract = Readonly<{\n  /** Full, namespaced react-hook-form field name, e.g. `shippingAddress.street`. */\n  name: string;\n  /** Resolved label text: the Control's `label` prop, else the platform's default. */\n  label?: string;\n  placeholder?: string;\n  /** Seed value, registered as react-hook-form's field-level `defaultValue`. */\n  defaultValue?: unknown;\n  rule?: FieldRule;\n  /** Only for a field whose value is picked from a list. Unread until `Field.Select` is added. */\n  options?: readonly FieldOption[];\n  disabled?: boolean;\n  readOnly?: boolean;\n  autoComplete?: string;\n  inputMode?: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';\n}>;\n\n/** Supplies the field contract to everything below it. Renders no DOM. Never catalogued. */\nexport type FieldBindingProps = FieldContract & {\n  children?: ReactNode;\n};\n\n/**\n * Provided by a fieldset. Declares the one namespace every name registered through it belongs to, and\n * registers a full field name, returning its unregister.\n */\nexport type FieldsetFieldRegistry = {\n  /**\n   * The namespace this fieldset owns — the prefix of every full name its own controls register. Declared\n   * by the provider, never inferred from a caller.\n   */\n  namespace: string;\n  /**\n   * Registers a full, namespaced field name and returns a release function. Refcounted by the provider,\n   * so two callers holding one name produce one entry, released when the last of them releases. The\n   * returned function releases at most once.\n   */\n  registerFieldName: (name: string) => () => void;\n};\n\n/** What `useFieldsetFieldNames` hands a fieldset: the value to provide, and the list to register. */\nexport type FieldsetFieldNames = Readonly<{\n  /** Referentially stable while `namespace` is unchanged. Goes straight into the context provider. */\n  registry: FieldsetFieldRegistry;\n  /** Every full field name currently held, in first-registration order. Stable identity. */\n  getFieldNames: () => readonly string[];\n}>;\n\n/** New bound part. Reads the contract, binds through useBoundField, drives Checkbox.Root. */\nexport type FieldCheckboxProps = {\n  readonly className?: string;\n  readonly children?: ReactNode;\n};\n\n// ---------------------------------------------------------------------------\n// Field contract context\n// ---------------------------------------------------------------------------\n\nconst FieldContext = createContext<FieldContract | null>(null);\n\n/** Reads the field contract. Returns null when no binding is above the caller. */\nexport function useField(): FieldContract | null {\n  return useContext(FieldContext);\n}\n\n/**\n * Per (control, field name), the seed the *fieldset supplied* for that name — `contract.defaultValue`\n * as handed down, not the value any one part narrowed it to before calling `resetField`. The\n * distinction only shows up where the RFC says two parts may bind one name (\"A fieldset registers\n * once, collecting the field names its own children mount, refcounted so that a part remounting, or\n * two parts binding one name, never unregisters a name still in use\"): a text part and a checkbox\n * part over the same name narrow one seed to two different types, so a ledger holding the narrowed\n * value disagrees with itself on every render — neither part's entry ever satisfies the other's\n * `seedsEqual` check, and the two reset each other forever. Keyed on what the fieldset supplied, both\n * parts read the same entry, the first to run adopts and the rest skip. The second part's own\n * `useController` registration still carries its own narrowing, so it reads dirty against a baseline\n * it did not set — the honest outcome, and better than a hang.\n *\n * Keyed by the `control` object itself rather than by any `FieldBinding` component instance. Adoption is a\n * property of the field name within this form, not of whichever component instance happens to be\n * mounted right now: a fieldset's own conditional control (the `documentType` gate on\n * `ClientProfileDocumentControl`, a country-descriptor swap in `ShippingAddressFieldset`) unmounts and\n * remounts its `FieldBinding` with a brand-new instance that remembers nothing, while the shopper's\n * edit survives the unmount in `control._formValues` — nothing in this codebase sets\n * `shouldUnregister`. A `useRef` latch scoped to the instance cannot see that history and re-adopts the\n * stale seed over the surviving edit; this ledger can, because it outlives the instance. A `WeakMap` so\n * a form that itself unmounts (a fresh `useForm()` call, a fresh `control`) starts over empty, exactly\n * as it should.\n *\n * A `Map` of seeds, not a `Set` of names: recording only that a name was adopted cannot distinguish a\n * seed already in force from a different one that supersedes it, so a later `defaultValue` could never\n * reach the form — that was the whole bug this ledger replaces. `has(name)` is read separately from\n * `get(name)` everywhere below, so \"never adopted\" and \"adopted `undefined`\" stay distinguishable\n * states.\n */\nconst adoptedSeeds = new WeakMap<Control, Map<string, unknown>>();\n\nfunction adoptedSeedsFor(control: Control): Map<string, unknown> {\n  let seeds = adoptedSeeds.get(control);\n  if (!seeds) {\n    seeds = new Map();\n    adoptedSeeds.set(control, seeds);\n  }\n  return seeds;\n}\n\n/**\n * Structural rather than referential equality between two seeds, mirroring `valuesEqual` in\n * `form.tsx:128-130` and its documented reasoning: a field's seed is a primitive or plain record a\n * bound Control's contract carries (a string, a boolean, a small object) — never a function or a\n * circular structure — so a `JSON.stringify` comparison is a safe stand-in for a real deep-equal.\n * Duplicated rather than imported: `field.tsx` imports nothing from `form.tsx`, and the particles are\n * deliberately independent modules.\n *\n * `Object.is` is rejected here even though neither shipped shape's `normalise` (`TEXT_FIELD_VALUE`,\n * `BOOLEAN_FIELD_VALUE`) can hand this function anything but a primitive today — this guard is\n * defensive against a shape that does not exist yet, not against a reachable path. The day a shape's\n * `normalise` returns a record or an array, a fieldset that hands out a freshly-allocated seed with\n * the same content on every render would fail `Object.is` against itself, and the\n * resetField → formState → render → resetField chain below would never terminate (measured: swapping\n * in `Object.is` hung the suite past 150 seconds, until a render ceiling was added that turns the same\n * mutation into a named failure in seconds). Do not remove this as dead code on the\n * grounds that no object-shaped seed reaches it today — the regression test that pins it is\n * `field.test.tsx`'s `'terminates when the seed is a fresh, structurally identical object literal on\n * every render'`, which exercises `useSeedAdoption` through a test-only shape precisely because no\n * shipped shape can.\n */\nfunction seedsEqual(a: unknown, b: unknown): boolean {\n  return a === b || JSON.stringify(a) === JSON.stringify(b);\n}\n\n/**\n * react-hook-form copies a per-field `defaultValue` into control._defaultValues only when\n * shouldUnregister is set, which nothing here sets — so without this, the pristine comparison for a\n * seeded field runs against `undefined` and any touched field stays dirty for good. Adopted once per\n * (control, name) for a given seed, tracked in `adoptedSeeds`, which survives this component instance\n * unmounting and remounting — so a remount with the same stale seed prop never overwrites a shopper's\n * live edit, and a later, *different* seed reaches a field the shopper has not touched without the\n * shopper having to reload the page.\n *\n * Called from `useBoundField`, not from `FieldBinding` (relocated, T57): the caller is now the very\n * part whose own `useController` call registers `name`. `useController` calls `control.register(name,\n * …)` from a `useRef` initialiser during the first render, and `register` adds to `_names.mount`\n * synchronously — before that render returns, let alone before this effect's first run. So the mount\n * guard below is satisfied on this effect's very first run for the caller's own name; the ordering\n * `FieldBinding` could not rely on (a descendant control mounting on a *later* commit than the binding\n * around it) no longer arises, because binder and adopter are now one and the same component instance.\n * The T-5 test (`field.test.tsx`, a control that shows up on a later render than its enclosing\n * `FieldBinding`) still passes — not because that race is still possible, but because nothing here\n * special-cases it away: the guard simply reads true the one time it is asked.\n *\n * No dependency array all the same: this effect must still re-run on every render, because the guards\n * below can otherwise miss their only remaining chance — the dirty-then-clean case. A seed arriving\n * while the field is dirty is skipped by the third guard and never recorded; the only later signal that\n * it can now be adopted is the field itself turning clean, which changes neither `name` nor the\n * normalised seed this hook receives, so a dependency array keyed to its own arguments would never\n * re-invoke it. Re-running on every render costs nothing extra here: every guard below but the\n * adopting one is a no-op, and useFormContext() already forces a re-render on every formState emission\n * regardless (Invariant 4 is violated in letter, not by this effect), so this adds no new re-render of\n * its own.\n *\n * The first guard below is what does termination, not just correctness: react-hook-form rebuilds\n * formState on every emission and FormProvider memoises its context value with formState in its own\n * dependency list, so useFormContext()'s return value changes identity after every resetField call.\n * Without that guard, that identity change would drive another render, which would call resetField\n * again, which would change formState again — an unbounded loop. Its early return breaks it: once the\n * ledger's recorded seed for this name is equal (by `seedsEqual`) to the current `defaultValue`, every\n * further run for that name exits before reaching resetField — which is also why it must be the first\n * check after the ledger lookup, ahead of even the mount guard.\n *\n * Precondition this re-seed relies on and does not itself enforce: `defaultValue` regressing to a\n * reactive fragment's incomplete-read fallback once the field has already adopted real data.\n * Probing this against `useReactiveEntity`'s fallback expression (`use-reactive-entity.ts:57`), mounting\n * a clean field over real, complete data and then trying to make `fragmentResult.complete` flip back to\n * false: measured as **reachable**, not merely suspected. Two of the three probes reproduced it —\n * evicting a field the fragment selects (`cache.evict({ id, fieldName })`, then `cache.gc()`) and\n * moving the root query's entity id to one never written to the cache (a session or orderForm change)\n * both regress the read, and this effect cannot tell that apart from a genuine, saved change: the\n * second probe blanked a clean control from \"Ada\" to \"\", and an independent audit reproduced it.\n * `client.clearStore()` on a still-mounted, still-referenced entity did not reproduce it. The\n * fieldsets close that gap above this hook: they withhold their controls until `useEntityDataResolved`\n * reports their entity resolved, so a regressed read never reaches this effect through a fieldset.\n */\nfunction useSeedAdoption(name: string, suppliedSeed: unknown, narrowedSeed: unknown): void {\n  const form = useFormContext();\n\n  useEffect(() => {\n    if (!form) return;\n    const seeds = adoptedSeedsFor(form.control);\n    if (seeds.has(name) && seedsEqual(seeds.get(name), suppliedSeed)) return;\n    if (!form.control._names.mount.has(name)) return;\n    if (seeds.has(name) && form.getFieldState(name).isDirty) return;\n    form.resetField(name, { defaultValue: narrowedSeed });\n    seeds.set(name, suppliedSeed);\n  });\n}\n\nexport function FieldBinding({\n  name,\n  label,\n  placeholder,\n  defaultValue,\n  rule,\n  options,\n  disabled,\n  readOnly,\n  autoComplete,\n  inputMode,\n  children,\n}: FieldBindingProps): ReactNode {\n  // No live value in the contract (Decision 1), so it is stable across a whole editing session as\n  // long as the caller's own props are stable — memoised here so an unrelated re-render of whatever\n  // renders this binding never produces a new object identity for subscribers.\n  const contract = useMemo<FieldContract>(\n    () => ({ name, label, placeholder, defaultValue, rule, options, disabled, readOnly, autoComplete, inputMode }),\n    [name, label, placeholder, defaultValue, rule, options, disabled, readOnly, autoComplete, inputMode],\n  );\n\n  return <FieldContext.Provider value={contract}>{children}</FieldContext.Provider>;\n}\n\n// ---------------------------------------------------------------------------\n// Bound part support — the empty value and seed narrowing a part owns (T57)\n// ---------------------------------------------------------------------------\n\n/**\n * What a bound part knows about its own value that `FieldBinding` does not (RFC `The rest of the\n * parts`): the value it holds when it holds nothing, and how to narrow an arbitrary seed to that\n * type. Each shape is the pair together, not two loose values, so a part cannot pair a boolean\n * `empty` with a string `normalise`.\n */\nexport type FieldValueShape<T> = Readonly<{\n  /** The value `useBoundField`'s registered clearer writes — this field's own type, not `''` by default. */\n  empty: T;\n  /** Narrows an arbitrary seed (`contract.defaultValue`) to this part's own value type. */\n  normalise: (seed: unknown) => T;\n}>;\n\n/** A text-shaped bound field: empty is `''`, and a non-string seed narrows to `''`. */\nexport const TEXT_FIELD_VALUE: FieldValueShape<string> = {\n  empty: '',\n  normalise: (seed) => (typeof seed === 'string' ? seed : ''),\n};\n\n/** A boolean-shaped bound field: empty is `false`, and any seed narrows through `Boolean(...)`. */\nexport const BOOLEAN_FIELD_VALUE: FieldValueShape<boolean> = {\n  empty: false,\n  normalise: (seed) => Boolean(seed),\n};\n\n/**\n * What `useBoundField` hands back: react-hook-form's own `field` object, reshaped into a type this\n * repository declares (Decision 6) — returning `useController`'s own `ControllerRenderProps` would put\n * a react-hook-form type back on the barrel the moment this hook is exported. `value: T`, not\n * `unknown`, because `BoundFieldControl` passes `field.value` straight into `BaseField.Control`, which\n * an `unknown` would reject. `ref` is a plain `RefCallback<HTMLElement>`, assignable to both\n * `Ref<HTMLInputElement>` and `Ref<HTMLButtonElement>`, so every existing `ref={field.ref}` site and\n * `useComposedRef` call keep compiling unchanged.\n */\nexport type BoundField<T> = Readonly<{\n  name: string;\n  value: T;\n  onChange: (...event: unknown[]) => void;\n  onBlur: () => void;\n  ref: RefCallback<HTMLElement>;\n  /** The resolved requiredness, so the control that renders the input announces the same value the\n   * registered rule enforces. Spread as `required || undefined` — a field never announces `false`. */\n  required: boolean;\n}>;\n\n/**\n * The only caller of `useController` in this package (I-1). Registers the field with react-hook-form,\n * adopts the same normalised seed as the dirty baseline (Decision 1), and registers a clearer that\n * writes the shape's own empty value for as long as the part stays mounted (FR-5) — three facts a\n * bound part previously scattered across its own call site, `FieldBinding` and `FormClear`.\n *\n * The effective rule is `rule ?? contract.rule`: a part with no rule of its own (`BoundFieldControl`,\n * `BoundFieldCheckbox`, `BoundFieldSelectRoot`) falls back to the contract's; `BoundPhoneField` and\n * `BoundDocumentField` pass their own `useMemo`-derived rule, which already merges the particle's\n * format check into `contract.rule` rather than replacing it.\n *\n * Requiredness resolves here rather than at each call site (FR: one chokepoint), so no bound control\n * can register a rule whose enforcement and announcement disagree, or forget the blank check. A\n * control that wants its field required passes a `raise`; only `FieldSelectTrigger`, which announces\n * from a different component than the one that binds, calls `resolveRequiredness` for itself.\n */\nexport function useBoundField<T>(\n  contract: FieldContract,\n  shape: FieldValueShape<T>,\n  rule?: FieldRule,\n  raise?: FieldRequirementRaise,\n): BoundField<T> {\n  const { control, setValue } = useFormContext();\n  // Memoised on the raise's two scalars, not on the raise object: callers build it inline, so a\n  // fresh identity every render would hand `useController` a fresh `rules` object every render.\n  const raiseRequired = raise?.required;\n  const raiseMessage = raise?.message;\n  const requiredness = useMemo(\n    () => resolveRequiredness(rule ?? contract.rule, { required: raiseRequired, message: raiseMessage }),\n    [rule, contract.rule, raiseRequired, raiseMessage],\n  );\n  // One named local, referenced by both useController's defaultValue and the adoption call below\n  // (AC-3) — registration and the dirty baseline must never drift apart by reading two independent\n  // normalise() calls.\n  const seed = shape.normalise(contract.defaultValue);\n\n  const { field } = useController({\n    name: contract.name,\n    rules: toRegisterOptions(requiredness.rule),\n    defaultValue: seed,\n  });\n\n  useSeedAdoption(contract.name, contract.defaultValue, seed);\n\n  useEffect(\n    () =>\n      registerFieldClearer(control, contract.name, () => setValue(contract.name, shape.empty, { shouldDirty: true })),\n    [control, contract.name, setValue, shape.empty],\n  );\n\n  return { ...field, required: requiredness.required };\n}\n\n// ---------------------------------------------------------------------------\n// Fieldset registration seam (provider ships from a later fieldset task)\n// ---------------------------------------------------------------------------\n\n/** Exported so those tasks import it rather than redefine it. */\nexport const FieldsetFieldContext = createContext<FieldsetFieldRegistry | null>(null);\n\n/** Unchanged: the registry above the caller, or null. Now carrying a namespace. */\nexport function useFieldsetContext(): FieldsetFieldRegistry | null {\n  return useContext(FieldsetFieldContext);\n}\n\n/**\n * Registers `${namespace}.${key}` with the enclosing fieldset while the caller is mounted, and returns\n * that full name. Throws during render when a registry is above the caller and declares a different\n * namespace. Registers nothing and throws nothing when no registry is above. Holds no state: the\n * refcount belongs to the provider.\n */\nexport function useFieldsetField(namespace: string, key: string): string {\n  const registry = useFieldsetContext();\n  const name = `${namespace}.${key}`;\n\n  if (registry && registry.namespace !== namespace) {\n    throw new Error(\n      `A control asked to register \"${name}\", but the fieldset registry above it owns the namespace \"${registry.namespace}\". A registry serves exactly one namespace, declared by the fieldset that provides it.`,\n    );\n  }\n\n  useEffect(() => {\n    if (!registry) return;\n    return registry.registerFieldName(name);\n  }, [registry, name]);\n\n  return name;\n}\n\n/**\n * The field-name bookkeeping a fieldset provides. Refcounted, so two callers of one name collapse to one\n * entry however they arrived — including a caller that reaches `registerFieldName` directly.\n */\nexport function useFieldsetFieldNames(namespace: string): FieldsetFieldNames {\n  // Own state, not module state: this ref lives on the fieldset's own component instance, so it\n  // survives every re-render regardless of whether the caller memoises the registry it hands out.\n  const counts = useRef(new Map<string, number>());\n\n  const registerFieldName = useCallback((name: string) => {\n    counts.current.set(name, (counts.current.get(name) ?? 0) + 1);\n\n    // One-shot: a counted Map, unlike the Set it replaces, is not idempotent on release. Without this\n    // latch a double-invoked unregister (StrictMode, or a defensive caller) would decrement past a\n    // second live holder and evict a name it still holds.\n    let released = false;\n    return () => {\n      if (released) return;\n      released = true;\n\n      const remaining = (counts.current.get(name) ?? 0) - 1;\n      if (remaining > 0) {\n        counts.current.set(name, remaining);\n      } else {\n        counts.current.delete(name);\n      }\n    };\n  }, []);\n\n  const getFieldNames = useCallback((): readonly string[] => Array.from(counts.current.keys()), []);\n\n  // Memoised on namespace: a fieldset that re-points at a different namespace produces a new registry\n  // object, so every mounted control re-registers under the new namespace in the same commit.\n  const registry = useMemo<FieldsetFieldRegistry>(\n    () => ({ namespace, registerFieldName }),\n    [namespace, registerFieldName],\n  );\n\n  return { registry, getFieldNames };\n}\n\n/**\n * Throws during render when an ancestor fieldset is already providing field registration for this\n * subtree. Every fieldset calls it in one line.\n */\nexport function useNoAncestorFieldset(componentName: string): void {\n  const ancestor = useFieldsetContext();\n\n  if (ancestor) {\n    throw new Error(\n      `${componentName} cannot be nested inside another fieldset. An ancestor fieldset owning the namespace \"${ancestor.namespace}\" already provides field registration for this subtree, so this fieldset's controls would register under that namespace instead of their own. Compose fieldsets as siblings under the same FormRoot instead of nesting them.`,\n    );\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const FieldRootDefinition = defineComponent<FieldRootProps>({\n  name: 'FieldRoot',\n  importPath: '@vtex/faststore/components',\n  component: FieldRoot,\n  providesContext: 'field',\n  editor: { label: 'Field Root', category: 'layout' },\n  schema: {\n    disabled: { type: 'boolean', default: false, label: 'Disabled' },\n  },\n  guideline:\n    'Form field container that connects a label, input, and validation messages via ARIA. Use Field.Control as the input element, or place a compatible Base UI input (Input, Checkbox, Select) as a direct child. Set invalid=true to trigger Field.Error display. Wrapping a bound Control feeds invalid/dirty/touched from react-hook-form automatically.',\n});\n\nexport const FieldLabelDefinition = defineComponent<FieldLabelProps>({\n  name: 'FieldLabel',\n  importPath: '@vtex/faststore/components',\n  component: FieldLabel,\n  requiresContext: 'field',\n  editor: { label: 'Field Label', category: 'layout' },\n  schema: {},\n  guideline:\n    \"Accessible label inside Field.Root. Automatically associated with Field.Control's input via ARIA. Place before Field.Control in the DOM. Under a bound Control, a childless Field.Label renders the field contract's label.\",\n});\n\nexport const FieldControlDefinition = defineComponent<FieldControlProps>({\n  name: 'FieldControl',\n  importPath: '@vtex/faststore/components',\n  component: FieldControl,\n  requiresContext: 'field',\n  editor: { label: 'Field Control', category: 'layout' },\n  schema: {},\n  guideline:\n    \"Renders a native `<input>` element directly. It IS the input — do not place any child inside it. Pass input attributes (type, placeholder, required, etc.) directly as props. It is automatically linked to Field.Label and Field.Error via ARIA. Under a bound Control, it registers with react-hook-form using the field contract's name, seed value, and validation rule.\",\n});\n\nexport const FieldDescriptionDefinition = defineComponent<FieldDescriptionProps>({\n  name: 'FieldDescription',\n  importPath: '@vtex/faststore/components',\n  component: FieldDescription,\n  requiresContext: 'field',\n  editor: { label: 'Field Description', category: 'layout' },\n  schema: {},\n  guideline:\n    'Helper text inside Field.Root. Automatically linked to the control via aria-describedby. Always visible regardless of validation state.',\n});\n\nexport const FieldErrorDefinition = defineComponent<FieldErrorProps>({\n  name: 'FieldError',\n  importPath: '@vtex/faststore/components',\n  component: FieldError,\n  requiresContext: 'field',\n  editor: { label: 'Field Error', category: 'layout' },\n  schema: {},\n  guideline:\n    \"Validation error message inside Field.Root. Shown when the field is in an invalid state. Linked to the control via aria-describedby. Under a bound Control, it renders react-hook-form's error message for the field contract's name.\",\n});\n\nexport const FieldValidityDefinition = defineComponent<FieldValidityProps>({\n  name: 'FieldValidity',\n  importPath: '@vtex/faststore/components',\n  component: FieldValidity,\n  requiresContext: 'field',\n  editor: { label: 'Field Validity', category: 'layout' },\n  schema: {},\n  guideline:\n    \"Validation feedback slot using a render prop for custom messages derived from the field's validity state. Use for dynamic messages when Field.Error text is not fixed.\",\n});\n\nexport const FieldCheckboxDefinition = defineComponent<FieldCheckboxProps>({\n  name: 'FieldCheckbox',\n  importPath: '@vtex/faststore/components',\n  component: FieldCheckbox,\n  requiresContext: 'field',\n  editor: { label: 'Field Checkbox', category: 'action' },\n  schema: {},\n  guideline:\n    'Bound boolean control over the shipped Checkbox particle: reads the enclosing field contract and drives Checkbox.Root through react-hook-form. Compose Checkbox.Indicator as a child for the visual check mark. Place inside Field.Root, the only ancestor that provides the field context it requires today — a bound Control will satisfy it too, once one ships.',\n});\n\n// ---------------------------------------------------------------------------\n// Parts\n// ---------------------------------------------------------------------------\n\nexport function FieldRoot({ disabled, invalid, name, className, children, ...props }: FieldRootProps) {\n  const contract = useField();\n  const formContext = useFormContext();\n\n  if (contract && formContext) {\n    return (\n      <BoundFieldRoot\n        {...props}\n        contract={contract}\n        disabled={disabled}\n        invalid={invalid}\n        name={name}\n        className={className}\n      >\n        {children}\n      </BoundFieldRoot>\n    );\n  }\n\n  return (\n    <BaseField.Root\n      {...props}\n      disabled={disabled}\n      invalid={invalid}\n      name={name}\n      className={className}\n      data-fs-field-root=\"\"\n    >\n      {children}\n    </BaseField.Root>\n  );\n}\n\ntype BoundFieldRootProps = FieldRootProps & { contract: FieldContract };\n\nfunction BoundFieldRoot({ contract, disabled, invalid, name, className, children, ...props }: BoundFieldRootProps) {\n  const { getFieldState, control } = useFormContext();\n  const {\n    invalid: rhfInvalid,\n    isDirty,\n    isTouched,\n  } = getFieldState(contract.name, useFormState({ name: contract.name }));\n\n  // Base UI's `FieldRoot` computes `dirty = dirtyProp ?? dirtyState`, and `setDirty` returns\n  // immediately once `dirtyProp !== undefined` (`FieldRoot.js:50-67`) — so passing `false`\n  // unconditionally disables Base UI's own fallback tracking exactly as hard as passing `true` did.\n  // That fallback is still needed for any name react-hook-form never registers (a raw Base UI control\n  // under a bound `Field.Root`), so the prop is three-state: `undefined` while the name is unmounted,\n  // then react-hook-form's own value once it registers — which always wins from then on, in both\n  // directions, closing the freeze-at-true latch the unconditional form reopened.\n  const isRegistered = control._names.mount.has(contract.name);\n\n  return (\n    <BaseField.Root\n      {...props}\n      name={name ?? contract.name}\n      disabled={disabled ?? contract.disabled}\n      invalid={invalid ?? rhfInvalid}\n      dirty={isRegistered ? isDirty : undefined}\n      touched={isRegistered ? isTouched : undefined}\n      className={className}\n      data-fs-field-root=\"\"\n    >\n      {children}\n    </BaseField.Root>\n  );\n}\n\nexport function FieldLabel({ className, children, ...props }: FieldLabelProps) {\n  const contract = useField();\n  const formContext = useFormContext();\n\n  if (contract && formContext) {\n    return (\n      <BoundFieldLabel {...props} contract={contract} className={className}>\n        {children}\n      </BoundFieldLabel>\n    );\n  }\n\n  return (\n    <BaseField.Label {...props} className={className} data-fs-field-label=\"\">\n      {children}\n    </BaseField.Label>\n  );\n}\n\ntype BoundFieldLabelProps = FieldLabelProps & { contract: FieldContract };\n\nfunction BoundFieldLabel({ contract, className, children, ...props }: BoundFieldLabelProps) {\n  return (\n    <BaseField.Label {...props} className={className} data-fs-field-label=\"\">\n      {children ?? contract.label}\n    </BaseField.Label>\n  );\n}\n\nexport function FieldControl({ className, ...props }: FieldControlProps) {\n  const contract = useField();\n  const formContext = useFormContext();\n\n  if (contract && formContext) {\n    return <BoundFieldControl {...props} contract={contract} className={className} />;\n  }\n\n  return <BaseField.Control {...props} className={className} data-fs-field-control=\"\" />;\n}\n\ntype BoundFieldControlProps = FieldControlProps & { contract: FieldContract };\n\nfunction BoundFieldControl({\n  contract,\n  placeholder,\n  disabled,\n  readOnly,\n  autoComplete,\n  inputMode,\n  className,\n  ...props\n}: BoundFieldControlProps) {\n  const field = useBoundField(contract, TEXT_FIELD_VALUE);\n\n  return (\n    <BaseField.Control\n      {...props}\n      name={field.name}\n      value={field.value}\n      onChange={field.onChange}\n      onBlur={field.onBlur}\n      ref={field.ref}\n      placeholder={placeholder ?? contract.placeholder}\n      disabled={disabled ?? contract.disabled}\n      readOnly={readOnly ?? contract.readOnly}\n      autoComplete={autoComplete ?? contract.autoComplete}\n      inputMode={inputMode ?? contract.inputMode}\n      aria-required={field.required || undefined}\n      className={className}\n      data-fs-field-control=\"\"\n    />\n  );\n}\n\nexport function FieldDescription({ className, children, ...props }: FieldDescriptionProps) {\n  return (\n    <BaseField.Description {...props} className={className} data-fs-field-description=\"\">\n      {children}\n    </BaseField.Description>\n  );\n}\n\nexport function FieldError({ className, children, ...props }: FieldErrorProps) {\n  const contract = useField();\n  const formContext = useFormContext();\n\n  if (contract && formContext) {\n    return (\n      <BoundFieldError {...props} contract={contract} className={className}>\n        {children}\n      </BoundFieldError>\n    );\n  }\n\n  return (\n    <BaseField.Error {...props} className={className} data-fs-field-error=\"\">\n      {children}\n    </BaseField.Error>\n  );\n}\n\ntype BoundFieldErrorProps = FieldErrorProps & { contract: FieldContract };\n\n// `match` is not destructured for use — its documented meaning applies to the unbound path only\n// (Decision: bound visibility is driven by react-hook-form's own error for the contract's name).\nfunction BoundFieldError({ contract, className, children, match: _match, ...props }: BoundFieldErrorProps) {\n  const { getFieldState } = useFormContext();\n  const { error } = getFieldState(contract.name, useFormState({ name: contract.name }));\n\n  if (!error) return null;\n  // A `validate` that reports failure with `false` rather than a string (e.g. DocumentField's\n  // check-digit validator when no `errorMessage` was authored) leaves react-hook-form's own\n  // `error.message` empty. Rendering in that case would put an empty `<div data-fs-field-error>` on\n  // the page where the field's own default (unbound) anatomy renders nothing at all — a divergence\n  // between the composed and default anatomies (finding F4). An author-supplied `children` still\n  // always renders regardless, since that text does not depend on react-hook-form's message.\n  if (!children && !error.message) return null;\n\n  return (\n    // `match` forces Base UI past its own native-constraint-validation gate: with no real HTML5\n    // constraint on the input, Field.Error's default (no `match`) visibility check reads native\n    // validity, not react-hook-form's. We have already decided to render from react-hook-form's\n    // error above, so `match` here only lets that decision take effect — it does not affect the\n    // message, which is our own `children` below and always wins over Base UI's own computed text.\n    <BaseField.Error {...props} match className={className} data-fs-field-error=\"\">\n      {children ?? error.message}\n    </BaseField.Error>\n  );\n}\n\nexport function FieldValidity({ children }: FieldValidityProps) {\n  return <BaseField.Validity>{children}</BaseField.Validity>;\n}\n\nexport function FieldCheckbox({ className, children }: FieldCheckboxProps): ReactNode {\n  const contract = useField();\n  const formContext = useFormContext();\n\n  if (contract && formContext) {\n    return (\n      <BoundFieldCheckbox contract={contract} className={className}>\n        {children}\n      </BoundFieldCheckbox>\n    );\n  }\n\n  return <Checkbox.Root className={className}>{children}</Checkbox.Root>;\n}\n\ntype BoundFieldCheckboxProps = FieldCheckboxProps & { contract: FieldContract };\n\nfunction BoundFieldCheckbox({ contract, className, children }: BoundFieldCheckboxProps) {\n  const field = useBoundField(contract, BOOLEAN_FIELD_VALUE);\n\n  return (\n    <Checkbox.Root\n      checked={field.value}\n      onCheckedChange={field.onChange}\n      onBlur={field.onBlur}\n      ref={field.ref}\n      disabled={contract.disabled}\n      className={className}\n      data-fs-field-checkbox=\"\"\n    >\n      {children}\n    </Checkbox.Root>\n  );\n}\n\nexport const Field = {\n  Root: FieldRoot,\n  Label: FieldLabel,\n  Control: FieldControl,\n  Description: FieldDescription,\n  Error: FieldError,\n  Validity: FieldValidity,\n  Checkbox: FieldCheckbox,\n};\n"],"mappings":"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"}

package/dist/particles/fieldset/fieldset.js

@@ -13,7 +13,7 @@ const FieldsetRootDefinition = defineComponent({
 		category: "layout"
 	},
 	schema: {},
-	guideline: "Root of an accessible fieldset for grouping related form controls. Compose as: FieldsetRoot > FieldsetLegend + [form controls]. Set disabled on the root to disable all contained inputs."
+	guideline: "Root of an accessible fieldset for grouping related form controls. Compose as: FieldsetRoot > FieldsetLegend + [form controls]. `disabled` marks the group with `data-disabled` and disables Field-family descendants through context — it does not set the native `fieldset[disabled]` attribute, so plain inputs, `CheckboxRoot` and `RadioGroup` inside it stay interactive."
 });
 const FieldsetLegendDefinition = defineComponent({
 	name: "FieldsetLegend",
@@ -24,7 +24,7 @@ const FieldsetLegendDefinition = defineComponent({
 		category: "layout"
 	},
 	schema: {},
-	guideline: "Visible title for a Fieldset.Root. Renders as a styled <legend> element."
+	guideline: "Visible title for a `FieldsetRoot`. Renders a `div` — not a native `<legend>` — and names the enclosing fieldset through `aria-labelledby`, so it must sit inside a `FieldsetRoot` to label anything; when two are composed, the last one wins."
 });
 function FieldsetRoot({ className, children, ...props }) {
 	return /* @__PURE__ */ jsx(Fieldset.Root, {

package/dist/particles/fieldset/fieldset.js.map

@@ -1 +1 @@
-{"version":3,"file":"fieldset.js","names":["BaseFieldset","Fieldset"],"sources":["../../../src/particles/fieldset/fieldset.tsx"],"sourcesContent":["'use client';\nimport { Fieldset as BaseFieldset } from '@base-ui/react/fieldset';\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef } from 'react';\n\nexport type FieldsetRootProps = ComponentPropsWithRef<'fieldset'>;\n\nexport type FieldsetLegendProps = ComponentPropsWithRef<'div'>;\n\nexport const FieldsetRootDefinition = defineComponent<FieldsetRootProps>({\n  name: 'FieldsetRoot',\n  importPath: '@vtex/faststore/components',\n  component: FieldsetRoot,\n  editor: { label: 'Fieldset Root', category: 'layout' },\n  schema: {},\n  guideline:\n    'Root of an accessible fieldset for grouping related form controls. Compose as: FieldsetRoot > FieldsetLegend + [form controls]. Set disabled on the root to disable all contained inputs.',\n});\n\nexport const FieldsetLegendDefinition = defineComponent<FieldsetLegendProps>({\n  name: 'FieldsetLegend',\n  importPath: '@vtex/faststore/components',\n  component: FieldsetLegend,\n  editor: { label: 'Fieldset Legend', category: 'layout' },\n  schema: {},\n  guideline: 'Visible title for a Fieldset.Root. Renders as a styled <legend> element.',\n});\n\nexport function FieldsetRoot({ className, children, ...props }: FieldsetRootProps) {\n  return (\n    <BaseFieldset.Root {...props} className={className} data-fs-fieldset-root=\"\">\n      {children}\n    </BaseFieldset.Root>\n  );\n}\n\nexport function FieldsetLegend({ className, children, ...props }: FieldsetLegendProps) {\n  return (\n    <BaseFieldset.Legend {...props} className={className} data-fs-fieldset-legend=\"\">\n      {children}\n    </BaseFieldset.Legend>\n  );\n}\n\nexport const Fieldset = {\n  Root: FieldsetRoot,\n  Legend: FieldsetLegend,\n};\n"],"mappings":";;;;;;AASA,MAAa,yBAAyB,gBAAmC;CACvE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAiB,UAAU;CAAS;CACrD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,2BAA2B,gBAAqC;CAC3E,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAmB,UAAU;CAAS;CACvD,QAAQ,CAAC;CACT,WAAW;AACb,CAAC;AAED,SAAgB,aAAa,EAAE,WAAW,UAAU,GAAG,SAA4B;CACjF,OACE,oBAACA,SAAa,MAAd;EAAmB,GAAI;EAAkB;EAAW,yBAAsB;EACvE;CACgB,CAAA;AAEvB;AAEA,SAAgB,eAAe,EAAE,WAAW,UAAU,GAAG,SAA8B;CACrF,OACE,oBAACA,SAAa,QAAd;EAAqB,GAAI;EAAkB;EAAW,2BAAwB;EAC3E;CACkB,CAAA;AAEzB;AAEA,MAAaC,aAAW;CACtB,MAAM;CACN,QAAQ;AACV"}
+{"version":3,"file":"fieldset.js","names":["BaseFieldset","Fieldset"],"sources":["../../../src/particles/fieldset/fieldset.tsx"],"sourcesContent":["'use client';\nimport { Fieldset as BaseFieldset } from '@base-ui/react/fieldset';\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef } from 'react';\n\nexport type FieldsetRootProps = ComponentPropsWithRef<'fieldset'>;\n\nexport type FieldsetLegendProps = ComponentPropsWithRef<'div'>;\n\nexport const FieldsetRootDefinition = defineComponent<FieldsetRootProps>({\n  name: 'FieldsetRoot',\n  importPath: '@vtex/faststore/components',\n  component: FieldsetRoot,\n  editor: { label: 'Fieldset Root', category: 'layout' },\n  schema: {},\n  guideline:\n    'Root of an accessible fieldset for grouping related form controls. Compose as: FieldsetRoot > FieldsetLegend + [form controls]. `disabled` marks the group with `data-disabled` and disables Field-family descendants through context — it does not set the native `fieldset[disabled]` attribute, so plain inputs, `CheckboxRoot` and `RadioGroup` inside it stay interactive.',\n});\n\nexport const FieldsetLegendDefinition = defineComponent<FieldsetLegendProps>({\n  name: 'FieldsetLegend',\n  importPath: '@vtex/faststore/components',\n  component: FieldsetLegend,\n  editor: { label: 'Fieldset Legend', category: 'layout' },\n  schema: {},\n  guideline:\n    'Visible title for a `FieldsetRoot`. Renders a `div` — not a native `<legend>` — and names the enclosing fieldset through `aria-labelledby`, so it must sit inside a `FieldsetRoot` to label anything; when two are composed, the last one wins.',\n});\n\nexport function FieldsetRoot({ className, children, ...props }: FieldsetRootProps) {\n  return (\n    <BaseFieldset.Root {...props} className={className} data-fs-fieldset-root=\"\">\n      {children}\n    </BaseFieldset.Root>\n  );\n}\n\nexport function FieldsetLegend({ className, children, ...props }: FieldsetLegendProps) {\n  return (\n    <BaseFieldset.Legend {...props} className={className} data-fs-fieldset-legend=\"\">\n      {children}\n    </BaseFieldset.Legend>\n  );\n}\n\nexport const Fieldset = {\n  Root: FieldsetRoot,\n  Legend: FieldsetLegend,\n};\n"],"mappings":";;;;;;AASA,MAAa,yBAAyB,gBAAmC;CACvE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAiB,UAAU;CAAS;CACrD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,2BAA2B,gBAAqC;CAC3E,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAmB,UAAU;CAAS;CACvD,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,SAAgB,aAAa,EAAE,WAAW,UAAU,GAAG,SAA4B;CACjF,OACE,oBAACA,SAAa,MAAd;EAAmB,GAAI;EAAkB;EAAW,yBAAsB;EACvE;CACgB,CAAA;AAEvB;AAEA,SAAgB,eAAe,EAAE,WAAW,UAAU,GAAG,SAA8B;CACrF,OACE,oBAACA,SAAa,QAAd;EAAqB,GAAI;EAAkB;EAAW,2BAAwB;EAC3E;CACkB,CAAA;AAEzB;AAEA,MAAaC,aAAW;CACtB,MAAM;CACN,QAAQ;AACV"}

package/dist/particles/footer-social/footer-social.js

@@ -1,9 +1,9 @@
 import { defineComponent } from "../../core/dist/define-component.js";
 import { defineContentType } from "../../core/dist/define-content-type.js";
 import "../../core/dist/index.js";
-import { Icon } from "../icon/icon.js";
 import { resolveSafeHref } from "../../utils/safe-href.js";
 import { NavigationLink } from "../navigation-link/navigation-link.js";
+import { Icon } from "../icon/icon.js";
 import { Image } from "../image/image.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/particles/footer-social/footer-social.tsx

package/dist/particles/form/form.d.ts

@@ -0,0 +1,104 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentPropsWithRef, ReactNode } from "react";
+//#region src/particles/form/form.d.ts
+/**
+ * The structural minimum every SDK user-error type satisfies. `code` is optional so that every
+ * shipped shape is assignable, including `RegionUserError`, the one that declares it optional;
+ * `ShippingAddressUpdateErrorEntity`, `ClientProfileUserError`, `CartUserError` and
+ * `SessionUserError` all declare `Readonly<{ code: string; message: string }>`. There is no shared
+ * user-error type in the SDK to reuse.
+ */
+export type FormUserError = Readonly<{
+  code?: string;
+  message: string;
+}>;
+/** What one fieldset hands the form. The form learns nothing else about it. */
+export type FieldsetRegistration = Readonly<{
+  /** Matches the field-name prefix every one of this fieldset's controls registers under. */
+  namespace: string;
+  /** Every full, namespaced field name this fieldset currently has mounted. */
+  getFieldNames: () => readonly string[];
+  /**
+   * Closes over the fieldset's own injected `$actions`. Rejecting is allowed; the form catches it.
+   * Must settle: the form gives up on a dispatch still pending after `FORM_DISPATCH_TIMEOUT_MS` and
+   * reports it as a failed write. Must also be idempotent: giving up on a dispatch does not cancel it,
+   * so a timed-out write may already be landing on the server, and the same payload is re-dispatched on
+   * the shopper's next submit while the field stays dirty.
+   */
+  dispatch: (payload: Record<string, unknown>) => Promise<readonly FormUserError[]>;
+  /** Shapes react-hook-form's raw values into the mutation's payload, including type coercion. */
+  toPayload: (values: Record<string, unknown>) => Record<string, unknown>;
+  /**
+   * Machine identifier for this fieldset's write. `FormError` renders it as the
+   * `data-fs-form-error-item` attribute value and uses it in two React keys; it is never displayed,
+   * because the visible text is each `userError`'s own `message` or `FormError`'s `fallbackMessage`.
+   * Its value is the kebab-case ASCII rendering of this registration's own `namespace`
+   * (`shippingAddress` → `shipping-address`), so a stylesheet selecting
+   * `[data-fs-form-error-item="…"]` needs one predictable shape and no diacritics.
+   */
+  label: string;
+}>;
+/**
+ * One fieldset's write that did not land. An empty `userErrors` means the dispatch rejected or never
+ * settled within `FORM_DISPATCH_TIMEOUT_MS`; either way `FormError` renders `fallbackMessage`.
+ */
+export type FormWriteFailure = Readonly<{
+  label: string;
+  userErrors: readonly FormUserError[];
+}>;
+export type FormRegistry = Readonly<{
+  /** Stable for the life of the FormRoot. Returns the unregister function. */
+  registerFieldset: (registration: FieldsetRegistration) => () => void;
+  /** The last submit's failures, in dispatch order. */
+  failures: readonly FormWriteFailure[];
+}>;
+/** Throws when no FormRoot is above the caller. */
+export declare function useFormRegistry(): FormRegistry;
+export type FormRootProps = Omit<ComponentPropsWithRef<'form'>, 'onSubmit' | 'action' | 'method' | 'target' | 'encType' | 'dangerouslySetInnerHTML'>;
+export type FormSubmitProps = {
+  className?: string;
+  label?: string;
+  children?: ReactNode;
+};
+export type FormClearProps = {
+  className?: string;
+  label?: string;
+  children?: ReactNode;
+};
+export type FormResetProps = {
+  className?: string;
+  label?: string;
+  children?: ReactNode;
+};
+export type FormErrorProps = {
+  className?: string;
+  fallbackMessage?: string;
+};
+export declare const FormRootDefinition: ComponentDefinition<FormRootProps>;
+export declare const FormSubmitDefinition: ComponentDefinition<FormSubmitProps>;
+export declare const FormEnterSubmitDefinition: ComponentDefinition<FormSubmitProps>;
+export declare const FormErrorDefinition: ComponentDefinition<FormErrorProps>;
+export declare const FormClearDefinition: ComponentDefinition<FormClearProps>;
+export declare const FormResetDefinition: ComponentDefinition<FormResetProps>;
+export declare function FormRoot({ className, children, onKeyDown, ...props }: FormRootProps): ReactNode;
+export declare function FormSubmit(props: FormSubmitProps): ReactNode;
+/**
+ * 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.
+ */
+export declare function FormEnterSubmit(props: FormSubmitProps): ReactNode;
+export declare function FormError({ className, fallbackMessage }: FormErrorProps): ReactNode;
+export declare function FormClear({ className, label, children }: FormClearProps): ReactNode;
+export declare function FormReset({ className, label, children }: FormResetProps): ReactNode;
+export declare const Form: {
+  Root: typeof FormRoot;
+  Submit: typeof FormSubmit;
+  EnterSubmit: typeof FormEnterSubmit;
+  Error: typeof FormError;
+  Clear: typeof FormClear;
+  Reset: typeof FormReset;
+};
+//#endregion
+//# sourceMappingURL=form.d.ts.map