@vtex/faststore 0.0.8 → 0.0.11

package/dist/matter/client-preferences/client-preferences-fieldset.js.map

@@ -1 +1 @@
-{"version":3,"file":"client-preferences-fieldset.js","names":[],"sources":["../../../src/matter/client-preferences/client-preferences-fieldset.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport {\n  type ComponentPropsWithRef,\n  createContext,\n  type ReactNode,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n} from 'react';\nimport { useFormContext } from 'react-hook-form';\nimport { Checkbox } from '../../particles/checkbox/checkbox.js';\nimport type { FieldRule } from '../../particles/field/field.js';\nimport {\n  Field,\n  FieldBinding,\n  FieldsetFieldContext,\n  useFieldsetField,\n  useFieldsetFieldNames,\n  useNoAncestorFieldset,\n} from '../../particles/field/field.js';\nimport { Fieldset } from '../../particles/fieldset/fieldset.js';\nimport { useFormRegistry } from '../../particles/form/form.js';\nimport { Icon } from '../../particles/icon/icon.js';\nimport { useActionsOverride } from '../../sdk/actions/actions-override-context.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { useEntityDataResolved } from '../../sdk/data/entity-resolution-context.js';\nimport { useReactiveDataSettled } from '../../sdk/data/use-reactive-data-settled.js';\nimport type { ClientPreferenceKey, ClientPreferencesUpdateInput } from '../../sdk/identity/operations.js';\nimport { useSession } from '../session/session.js';\n\n/**\n * `ClientPreferencesFieldset` — the composable, one-Save write of the `ClientPreferences` sibling\n * entity (RFC: Composable Entity Forms, `Proposal > Design > The fieldset`). It registers itself with\n * the enclosing `FormRoot` under the `clientPreferences` namespace and dispatches\n * `$actions.identity.clientPreferencesUpdate` for its own submit slot; it renders no `<form>` of its\n * own.\n *\n * `ClientPreferencesRoot` (`client-preferences.tsx`) already reads both flags and writes on toggle; this\n * fieldset is a second, batched write timing for the same two flags. To keep the two from compiling into\n * each other's container, the shipped self-persisting matter's context is renamed to\n * `client-preferences-toggle`, freeing `client-preferences` for this fieldset. Placing\n * `NewsletterOptInControl` inside this fieldset, or `ClientPreferencesNewsletterControl` inside\n * `ClientPreferencesRoot`, is therefore a build failure rather than a surprise write.\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — colocated on the fieldset, its own data root\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment ClientPreferencesFieldsetData on Query {\n    clientPreferences {\n      __typename\n      id\n      optinNewsLetter\n      savePersonalData\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** The `$data` slice forwarded by the reactive runtime — the ClientPreferences sibling entity, unwrapped. */\nexport type ClientPreferencesFieldsetData = {\n  optinNewsLetter?: boolean | null;\n  savePersonalData?: boolean | null;\n} | null;\n\n/** What the fieldset publishes to its controls. Carries no live value — react-hook-form owns those. */\ntype ClientPreferencesFieldsetContextValue = Readonly<{\n  namespace: 'clientPreferences';\n  /** Seeds, resolved from `$data`. `null` (not chosen yet) reads as unchecked, per the opt-in default. */\n  saved: Readonly<Record<ClientPreferenceKey, boolean>>;\n  /** True when the session reports `canEditData: false`. */\n  readOnly: boolean;\n  /** The fieldset's own validation rules, per key. Present and empty today (Decision 6). */\n  rules: Readonly<Partial<Record<ClientPreferenceKey, FieldRule>>>;\n}>;\n\n/** No control publishes a rule today (Decision 6) — kept as a stable empty object so the context\n * value's identity does not churn on every render. */\nconst NO_RULES: Readonly<Partial<Record<ClientPreferenceKey, FieldRule>>> = {};\n\n/**\n * Rows `ClientPreferencesFieldsetSkeleton` draws when nobody says otherwise: one per consent flag in\n * the full anatomy. It is a default and not a derivation, because the composed children are opaque\n * here. A page that composes only one control sets `skeletonCount` to 1, or the form jumps by a row\n * when the controls take the skeleton's place.\n */\nconst CLIENT_PREFERENCES_SKELETON_ROWS = 2;\n\nconst CLIENT_PREFERENCES_FIELDSET_UNSET = Symbol('ClientPreferencesFieldsetContextUnset');\n\nconst ClientPreferencesFieldsetContext = createContext<\n  ClientPreferencesFieldsetContextValue | typeof CLIENT_PREFERENCES_FIELDSET_UNSET\n>(CLIENT_PREFERENCES_FIELDSET_UNSET);\n\nfunction useClientPreferencesFieldsetContext(): ClientPreferencesFieldsetContextValue {\n  const ctx = useContext(ClientPreferencesFieldsetContext);\n  if (ctx === CLIENT_PREFERENCES_FIELDSET_UNSET) {\n    throw new Error('ClientPreferencesFieldset controls must be used inside ClientPreferencesFieldset.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Props\n// ---------------------------------------------------------------------------\n\nexport type ClientPreferencesFieldsetProps = {\n  /** Placeholder rows the loading skeleton draws. Set it to the number of controls composed here. */\n  skeletonCount?: number;\n  /** Announced politely while the preferences resolve. Blank means no announcement. */\n  loadingLabel?: string;\n  /** Announced politely once the controls mount. Blank means no announcement. */\n  loadedLabel?: string;\n  /** Accessible name of the `<fieldset>` group. Blank means no name is exposed. */\n  groupLabel?: string;\n  className?: string;\n  children?: ReactNode;\n  /** `ClientPreferencesFieldsetData` slice forwarded by the reactive runtime. */\n  $data?: ClientPreferencesFieldsetData;\n  /** Compiler-injected; carries `identity.clientPreferencesUpdate`. */\n  $actions?: ComponentActions;\n};\n\ntype PreferenceControlProps = { label?: string; className?: string; children?: ReactNode };\n\nexport type ClientPreferencesNewsletterControlProps = PreferenceControlProps;\nexport type ClientPreferencesSavePersonalDataControlProps = PreferenceControlProps;\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const ClientPreferencesFieldsetDefinition = defineComponent<ClientPreferencesFieldsetProps>({\n  name: 'ClientPreferencesFieldset',\n  importPath: '@vtex/faststore/components',\n  component: ClientPreferencesFieldset,\n  fragment,\n  fetchStrategy: 'reactive',\n  skeleton: ClientPreferencesFieldsetSkeleton,\n  requiresContext: ['form', 'session'],\n  providesContext: 'client-preferences',\n  actions: { identity: ['clientPreferencesUpdate'] },\n  editor: { label: 'Client Preferences Fieldset', category: 'identity' },\n  schema: {\n    skeletonCount: { type: 'number', default: 2, label: 'Skeleton rows' },\n    loadingLabel: { type: 'string', default: 'Loading your preferences', label: 'Loading announcement' },\n    loadedLabel: { type: 'string', default: 'Your preferences are ready', label: 'Loaded announcement' },\n    groupLabel: { type: 'string', default: 'Your preferences', label: 'Accessible group name' },\n  },\n  guideline:\n    \"Registers a batched write of the ClientPreferences entity with the enclosing FormRoot; renders one Fieldset.Root and no <form>. Distinct from ClientPreferencesRoot (matter/client-preferences), which writes on toggle and requires client-preferences-toggle — the two cannot compile into each other's container. Must be inside a FormRoot with a SessionRoot ancestor. Compose ClientPreferencesNewsletterControl and/or ClientPreferencesSavePersonalDataControl as children. The controls mount only once the preferences have resolved, with skeletonCount placeholder rows in their place until then — set it to the number of controls composed, or the form jumps by the difference. Style the announcement sr-only. Dispatches only the flags the shopper changed. groupLabel names the group as its accessible name; blank emits no aria-label, and a composed FieldsetLegend wins over it.\",\n});\n\nexport const ClientPreferencesNewsletterControlDefinition = defineComponent<ClientPreferencesNewsletterControlProps>({\n  name: 'ClientPreferencesNewsletterControl',\n  importPath: '@vtex/faststore/components',\n  component: ClientPreferencesNewsletterControl,\n  requiresContext: 'client-preferences',\n  providesContext: 'field',\n  editor: { label: 'Client Preferences Newsletter Control', category: 'identity' },\n  schema: {\n    // No default (Decision 1): absence means the platform's value, applied at render time by\n    // the control itself, not baked into the schema.\n    label: { type: 'string', label: 'Label' },\n  },\n  guideline:\n    \"The bound newsletter opt-in control; must be a descendant of ClientPreferencesFieldset. Renders Field.Root > Field.Label > Field.Checkbox by default, or the composed children in the author's own order. Defaults to unchecked.\",\n});\n\nexport const ClientPreferencesSavePersonalDataControlDefinition =\n  defineComponent<ClientPreferencesSavePersonalDataControlProps>({\n    name: 'ClientPreferencesSavePersonalDataControl',\n    importPath: '@vtex/faststore/components',\n    component: ClientPreferencesSavePersonalDataControl,\n    requiresContext: 'client-preferences',\n    providesContext: 'field',\n    editor: { label: 'Client Preferences Save Personal Data Control', category: 'identity' },\n    schema: {\n      // No default (Decision 1): absence means the platform's value, applied at render time by\n      // the control itself, not baked into the schema.\n      label: { type: 'string', label: 'Label' },\n    },\n    guideline:\n      \"The bound save-personal-data opt-in control; must be a descendant of ClientPreferencesFieldset. Renders Field.Root > Field.Label > Field.Checkbox by default, or the composed children in the author's own order. Defaults to unchecked.\",\n  });\n\n// ---------------------------------------------------------------------------\n// Fieldset root\n// ---------------------------------------------------------------------------\n\n/**\n * Registers a batched write of the `ClientPreferences` entity with the enclosing `FormRoot`\n * (`registerFieldset`, namespace `clientPreferences`) on mount, unconditionally — so this fieldset keeps\n * its original dispatch slot even while its own query is still resolving. Its children — the seed values\n * and the field-name registry its controls need — render only once the entity has resolved; until then\n * the `Fieldset.Root` carries `-pending` and renders `ClientPreferencesFieldsetSkeleton` (Decision 5).\n * `dispatch` and `toPayload` are `useCallback([])`-stable and read `$actions` through a ref, so the\n * registration effect runs exactly once per mount regardless of how often the parent re-renders.\n *\n * \"Resolved\" is two conditions, because `$data` alone cannot answer it. Under the reactive runtime the\n * slice is defined from the first render — `useReactiveEntity` hands down `fallbackData` while the cache\n * read is incomplete — so an empty server answer looks exactly like a resolved one, and the checkboxes\n * would mount seeded unchecked before the shopper's saved consent arrives. `useSeedAdoption` re-seeds a\n * clean checkbox with `defaultValue` on every render, but once it turns dirty no later seed ever\n * reaches it again: a shopper who toggles it before the real consent arrives locks that unchecked\n * seed in for good, and even a shopper who does not toggle it sees the checkbox flash to the saved\n * value. `useReactiveDataSettled` supplies\n * the missing half: the page query's own in-flight state, latched so it only ever goes pending →\n * settled. The `$data === undefined` half still carries trees with no reactive root above them, where\n * the slice arrives as a plain prop.\n *\n * Both ends of that wait are spoken: the fieldset carries `aria-busy` while it lasts and holds a polite\n * live region that announces `loadingLabel` and then `loadedLabel`. Style the region `sr-only` — it is\n * text meant for a screen reader, not for the page.\n */\nexport function ClientPreferencesFieldset({\n  skeletonCount = CLIENT_PREFERENCES_SKELETON_ROWS,\n  loadingLabel = 'Loading your preferences',\n  loadedLabel = 'Your preferences are ready',\n  groupLabel = 'Your preferences',\n  className,\n  children,\n  $data: $dataProp,\n  $actions: $actionsProp,\n}: ClientPreferencesFieldsetProps) {\n  // Nesting fieldsets has no legitimate use: useFieldsetField resolves the *nearest*\n  // FieldsetFieldContext, not the one owning a control's actual namespace, so a control nested two\n  // fieldsets deep would silently register under the wrong one and its write would be discarded on\n  // submit. Runtime registry integrity, mirroring the namespace-collision throw FormRoot already ships\n  // (form.tsx:280-288).\n  useNoAncestorFieldset('ClientPreferencesFieldset');\n\n  const $data = useDataOverride($dataProp);\n\n  const $actions = useActionsOverride($actionsProp);\n  // Three conditions, not two. `useReactiveDataSettled` latches one way and never re-arms, so on its\n  // own it answers \"has this page ever resolved\", not \"is what I am holding right now the server's\n  // answer\" — after the page query's entity ref moves to one this cache never stored, or its root is\n  // skipped for want of a variable, the slice silently regresses to `fallbackData` while the latch\n  // still reads settled. `useEntityDataResolved` is the per-entity half: unlatched, so it follows the\n  // slice back down and returns this fieldset to its skeleton instead of leaving live controls seeded\n  // from a placeholder.\n  const settled = useReactiveDataSettled();\n  const sliceResolved = useEntityDataResolved();\n  const resolved = settled && sliceResolved && $data !== undefined;\n  // Also enforces the SessionRoot ancestor: useSession() throws when rendered outside one.\n  const { canEditData } = useSession();\n  const readOnly = !canEditData;\n\n  // Runs before useFormContext() below: useFormRegistry() throws the friendly \"Form parts must be used\n  // inside FormRoot.\" error when no FormRoot is above, so a FormRoot-less render fails there rather than\n  // reaching the getFieldState destructure, which throws an unhelpful TypeError instead (useFormContext()\n  // resolves to null outside a FormRoot, and destructuring null throws).\n  const { registerFieldset } = useFormRegistry();\n\n  // Decision 3, as later narrowed: this fieldset still reads dirtiness imperatively, but the rule is no\n  // longer the form's. `FormRoot` subscribes `dirtyFields` in render and decides which fieldsets to\n  // dispatch from it, by the fields each one has mounted, on react-hook-form's documented contract.\n  //\n  // The imperative read survives here because it asks a different question in a different place: which\n  // of *this* fieldset's own fields changed, resolved inside `toPayload` at submit time, by full\n  // registered field name — the shape `getFieldState` documents. `useFormContext()` adds no\n  // `formState` subscription of its own; one is created only when a caller reads a formState key off\n  // the `useForm`/`useFormState` proxy (or hands that already-subscribed object to `getFieldState`'s\n  // second argument). Calling `getFieldState(name)` with no second argument reads the current internal\n  // state directly, so this fieldset root still does not re-render on a keystroke.\n  const { getFieldState } = useFormContext();\n\n  const latest = useRef({ $actions, readOnly, getFieldState });\n  useEffect(() => {\n    latest.current = { $actions, readOnly, getFieldState };\n  }, [$actions, readOnly, getFieldState]);\n\n  const { registry: fieldsetRegistry, getFieldNames } = useFieldsetFieldNames('clientPreferences');\n\n  const dispatch = useCallback(async (payload: Record<string, unknown>) => {\n    // Defence-in-depth: the UI disables every input while read-only, but `FormClear` sets values (and\n    // marks them dirty) on every registered field regardless of that disabled attribute — react-hook-\n    // form's own `useController` calls never receive a `disabled` registration option, so it has no\n    // notion of \"disabled\" of its own. Guarding here keeps the write from reaching the network even if\n    // some other composition dirties this fieldset while canEditData is false (the server also refuses,\n    // but a client-side guard should not depend on that).\n    if (latest.current.readOnly) {\n      throw new Error('ClientPreferencesFieldset cannot dispatch while the session is read-only.');\n    }\n    const update = latest.current.$actions?.identity?.clientPreferencesUpdate;\n    // Throwing is the contract's failure path: FormRoot catches it and records this fieldset's failure\n    // (form.tsx:264-266). Returning [] would report an unqualified success for a write that never\n    // happened.\n    if (!update) throw new Error('ClientPreferencesFieldset requires $actions.identity.clientPreferencesUpdate.');\n    return update(payload as ClientPreferencesUpdateInput);\n  }, []);\n\n  const toPayload = useCallback((values: Record<string, unknown>): Record<string, unknown> => {\n    const { getFieldState } = latest.current;\n    // FR-6: a flag is emitted only when the shopper actually toggled it. `getFieldState` is called\n    // with no second argument, which reads react-hook-form's current internal state without\n    // subscribing to it (Decision 3).\n    const isDirty = (key: ClientPreferenceKey) => getFieldState(`clientPreferences.${key}`).isDirty;\n    // Boolean() coercion is defence in depth: the bound checkbox part itself now writes its own\n    // field's typed empty value on Clear (false, not ''), but this fieldset should not depend on\n    // every caller writing a well-typed value.\n    const payload: Record<string, boolean> = {};\n    if ('optinNewsLetter' in values && isDirty('optinNewsLetter')) {\n      payload.optinNewsLetter = Boolean(values.optinNewsLetter);\n    }\n    if ('savePersonalData' in values && isDirty('savePersonalData')) {\n      payload.savePersonalData = Boolean(values.savePersonalData);\n    }\n    return payload;\n  }, []);\n\n  useEffect(\n    () =>\n      registerFieldset({\n        namespace: 'clientPreferences',\n        getFieldNames,\n        dispatch,\n        toPayload,\n        // Decision 1: the register is a machine identifier, the kebab-case ASCII rendering of this\n        // registration's own `namespace` (`clientPreferences` → `client-preferences`) — not authored\n        // per page (Decision 2).\n        label: 'client-preferences',\n      }),\n    [registerFieldset, getFieldNames, dispatch, toPayload],\n  );\n\n  const saved = useMemo<Readonly<Record<ClientPreferenceKey, boolean>>>(\n    () => ({\n      optinNewsLetter: Boolean($data?.optinNewsLetter ?? false),\n      savePersonalData: Boolean($data?.savePersonalData ?? false),\n    }),\n    [$data],\n  );\n\n  const contextValue = useMemo<ClientPreferencesFieldsetContextValue>(\n    () => ({ namespace: 'clientPreferences', saved, readOnly, rules: NO_RULES }),\n    [saved, readOnly],\n  );\n\n  // Assistive technology only reports a change inside a region that was already in the tree, so a\n  // region mounted together with its text announces nothing. The region therefore sits in both\n  // branches and starts empty, with the wait written on the pass after mount and replaced — not\n  // cleared — once the controls are up: the skeleton is `aria-hidden`, so without this second\n  // message the form would materialise in silence (WCAG 2.1 SC 4.1.3).\n  const [announcement, setAnnouncement] = useState('');\n  const announced = resolved ? loadedLabel : loadingLabel;\n  useEffect(() => {\n    setAnnouncement(announced);\n  }, [announced]);\n\n  return (\n    <Fieldset.Root\n      className={className}\n      disabled={readOnly}\n      aria-busy={resolved ? undefined : true}\n      // FR-12: blank (or whitespace-only) means no name is exposed, mirroring the loadingLabel/\n      // loadedLabel convention. On the root itself (FR-13), so it is identical whether the fieldset\n      // is pending or resolved; a page-composed FieldsetLegend still wins via aria-labelledby.\n      {...(groupLabel?.trim() ? { 'aria-label': groupLabel } : {})}\n      data-fs-client-preferences-fieldset=\"\"\n      {...(resolved ? {} : { 'data-fs-client-preferences-fieldset-pending': '' })}\n      {...(readOnly ? { 'data-fs-client-preferences-fieldset-readonly': '' } : {})}\n    >\n      {resolved ? (\n        <FieldsetFieldContext.Provider value={fieldsetRegistry}>\n          <ClientPreferencesFieldsetContext.Provider value={contextValue}>\n            {children}\n          </ClientPreferencesFieldsetContext.Provider>\n        </FieldsetFieldContext.Provider>\n      ) : (\n        <ClientPreferencesFieldsetSkeleton count={skeletonCount} />\n      )}\n      <output aria-live=\"polite\" data-fs-client-preferences-fieldset-announcement=\"\">\n        {announcement}\n      </output>\n    </Fieldset.Root>\n  );\n}\n\n/**\n * The loading state of the fieldset, rendered in place of the controls until the entity resolves and\n * declared as the definition's `skeleton`. Purely visual: the wait is spoken by the fieldset's own live\n * region, so this is hidden from assistive technology rather than announced twice.\n */\nexport function ClientPreferencesFieldsetSkeleton({\n  count = CLIENT_PREFERENCES_SKELETON_ROWS,\n  className,\n  ...props\n}: ComponentPropsWithRef<'div'> & { count?: number }) {\n  return (\n    <div {...props} className={className} data-fs-client-preferences-fieldset-skeleton=\"\" aria-hidden=\"true\">\n      {Array.from({ length: count }, (_, i) => (\n        <span key={i} data-fs-client-preferences-fieldset-skeleton-field=\"\" />\n      ))}\n    </div>\n  );\n}\n\nClientPreferencesFieldset.Skeleton = ClientPreferencesFieldsetSkeleton;\n\n// ---------------------------------------------------------------------------\n// Controls\n// ---------------------------------------------------------------------------\n\nfunction PreferenceControl({\n  fieldKey,\n  attr,\n  defaultLabel,\n  label,\n  className,\n  children,\n}: {\n  fieldKey: ClientPreferenceKey;\n  attr: string;\n  defaultLabel: string;\n  label?: string;\n  className?: string;\n  children?: ReactNode;\n}) {\n  const { namespace, saved, readOnly, rules } = useClientPreferencesFieldsetContext();\n  const name = useFieldsetField(namespace, fieldKey);\n  const resolvedLabel = label ?? defaultLabel;\n\n  return (\n    <FieldBinding\n      name={name}\n      label={resolvedLabel}\n      defaultValue={saved[fieldKey]}\n      rule={rules[fieldKey]}\n      disabled={readOnly}\n    >\n      <Field.Root className={className} data-fs-client-preferences-fieldset-field={attr}>\n        {children ?? (\n          <Field.Label>\n            <Field.Checkbox>\n              <Checkbox.Indicator>\n                <Icon name=\"checked\" />\n              </Checkbox.Indicator>\n            </Field.Checkbox>\n            {resolvedLabel}\n          </Field.Label>\n        )}\n      </Field.Root>\n    </FieldBinding>\n  );\n}\n\nexport function ClientPreferencesNewsletterControl({\n  label,\n  className,\n  children,\n}: ClientPreferencesNewsletterControlProps) {\n  return (\n    <PreferenceControl\n      fieldKey=\"optinNewsLetter\"\n      attr=\"newsletter\"\n      defaultLabel=\"Email me with news and offers\"\n      label={label}\n      className={className}\n    >\n      {children}\n    </PreferenceControl>\n  );\n}\n\nexport function ClientPreferencesSavePersonalDataControl({\n  label,\n  className,\n  children,\n}: ClientPreferencesSavePersonalDataControlProps) {\n  return (\n    <PreferenceControl\n      fieldKey=\"savePersonalData\"\n      attr=\"save-personal-data\"\n      defaultLabel=\"Save my information for next time\"\n      label={label}\n      className={className}\n    >\n      {children}\n    </PreferenceControl>\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"client-preferences-fieldset.js","names":[],"sources":["../../../src/matter/client-preferences/client-preferences-fieldset.tsx"],"sourcesContent":["'use client';\n\nimport {\n  type ContentTypeDefinition,\n  type ContentValue,\n  defineComponent,\n  defineContentType,\n  type MessageFieldName,\n  type MessageLocaleProp,\n} from '@vtex/fs-core';\nimport {\n  type ComponentPropsWithRef,\n  createContext,\n  type ReactNode,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n} from 'react';\nimport { useFormContext } from 'react-hook-form';\nimport { Checkbox } from '../../particles/checkbox/checkbox.js';\nimport type { FieldRule } from '../../particles/field/field.js';\nimport {\n  Field,\n  FieldBinding,\n  FieldsetFieldContext,\n  useFieldsetField,\n  useFieldsetFieldNames,\n  useNoAncestorFieldset,\n} from '../../particles/field/field.js';\nimport { Fieldset } from '../../particles/fieldset/fieldset.js';\nimport { type FormUserError, useFormRegistry } from '../../particles/form/form.js';\nimport { Icon } from '../../particles/icon/icon.js';\nimport { useActionsOverride } from '../../sdk/actions/actions-override-context.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { useEntityDataResolved } from '../../sdk/data/entity-resolution-context.js';\nimport { useReactiveDataSettled } from '../../sdk/data/use-reactive-data-settled.js';\nimport { formatErrorCode } from '../../sdk/i18n/format-error-code.js';\nimport type { MessageFormatter } from '../../sdk/i18n/message-formatter.js';\nimport { useMessageFormatter } from '../../sdk/i18n/use-message-formatter.js';\nimport type {\n  ClientPreferenceKey,\n  ClientPreferencesUpdateInput,\n  ClientProfileUserError,\n} from '../../sdk/identity/operations.js';\nimport { useSession } from '../session/session.js';\n\n/**\n * `ClientPreferencesFieldset` — the composable, one-Save write of the `ClientPreferences` sibling\n * entity (RFC: Composable Entity Forms, `Proposal > Design > The fieldset`). It registers itself with\n * the enclosing `FormRoot` under the `clientPreferences` namespace and dispatches\n * `$actions.identity.clientPreferencesUpdate` for its own submit slot; it renders no `<form>` of its\n * own.\n *\n * `ClientPreferencesRoot` (`client-preferences.tsx`) already reads both flags and writes on toggle; this\n * fieldset is a second, batched write timing for the same two flags. To keep the two from compiling into\n * each other's container, the shipped self-persisting matter's context is renamed to\n * `client-preferences-toggle`, freeing `client-preferences` for this fieldset. Placing\n * `NewsletterOptInControl` inside this fieldset, or `ClientPreferencesNewsletterControl` inside\n * `ClientPreferencesRoot`, is therefore a build failure rather than a surprise write.\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — colocated on the fieldset, its own data root\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment ClientPreferencesFieldsetData on Query {\n    clientPreferences {\n      __typename\n      id\n      optinNewsLetter\n      savePersonalData\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Content model\n// ---------------------------------------------------------------------------\n\nexport const ClientPreferencesFieldsetContent = defineContentType({\n  id: 'client-preferences-fieldset',\n  title: 'Client Preferences Fieldset',\n  description: \"The preferences fieldset's loading and loaded announcements and its accessible group name.\",\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    properties: {\n      loadingLabel: {\n        type: 'string',\n        title: 'Loading announcement',\n        format: 'icu-message',\n        messageSource: 'Loading your preferences',\n      },\n      loadedLabel: {\n        type: 'string',\n        title: 'Loaded announcement',\n        format: 'icu-message',\n        messageSource: 'Your preferences are ready',\n      },\n      groupLabel: {\n        type: 'string',\n        title: 'Accessible group name',\n        format: 'icu-message',\n        messageSource: 'Your preferences',\n        messageOptional: true,\n      },\n      genericErrorMessage: {\n        type: 'string',\n        title: 'Generic error message',\n        description: 'Shown by FormError when the preferences could not be saved.',\n        format: 'icu-message',\n        messageSource: 'Unable to save your preferences. Please try again.',\n      },\n    },\n  },\n});\n\ntype ClientPreferencesUpdateErrorCode = 'MISSING_CART_CONTEXT' | 'CART_NOT_FOUND' | 'NO_PREFERENCE_PROVIDED';\n\n/**\n * The message for each refusal of the preferences write: every `ClientPreferencesUpdateErrorCode` plus\n * the client-minted transport failure. None is a fault the shopper can fix, so all share one message.\n * `dispatch` hands `FormError` this copy, and genericErrorMessage for an unknown code.\n */\nexport const CLIENT_PREFERENCES_FIELDSET_ERROR_FIELDS = {\n  MISSING_CART_CONTEXT: 'genericErrorMessage',\n  CART_NOT_FOUND: 'genericErrorMessage',\n  NO_PREFERENCE_PROVIDED: 'genericErrorMessage',\n  NETWORK_ERROR: 'genericErrorMessage',\n} as const satisfies Record<\n  ClientPreferencesUpdateErrorCode | 'NETWORK_ERROR',\n  MessageFieldName<typeof ClientPreferencesFieldsetContent>\n>;\n\nfunction wordClientPreferencesError(\n  error: ClientProfileUserError,\n  { format }: MessageFormatter<typeof ClientPreferencesFieldsetContent>,\n): FormUserError {\n  return {\n    code: error.code,\n    message: formatErrorCode(\n      ClientPreferencesFieldsetContent,\n      CLIENT_PREFERENCES_FIELDSET_ERROR_FIELDS,\n      error,\n      format,\n      'genericErrorMessage',\n    ),\n  };\n}\n\nexport const ClientPreferencesNewsletterControlContent = defineContentType({\n  id: 'client-preferences-newsletter',\n  title: 'Client Preferences Newsletter Control',\n  description: \"The newsletter opt-in's label.\",\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    properties: {\n      label: { type: 'string', title: 'Label', format: 'icu-message', messageSource: 'Email me with news and offers' },\n    },\n  },\n});\n\nexport const ClientPreferencesSavePersonalDataControlContent = defineContentType({\n  id: 'client-preferences-save-data',\n  title: 'Client Preferences Save Personal Data Control',\n  description: \"The save-personal-data opt-in's label.\",\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    properties: {\n      label: {\n        type: 'string',\n        title: 'Label',\n        format: 'icu-message',\n        messageSource: 'Save my information for next time',\n      },\n    },\n  },\n});\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** The `$data` slice forwarded by the reactive runtime — the ClientPreferences sibling entity, unwrapped. */\nexport type ClientPreferencesFieldsetData = {\n  optinNewsLetter?: boolean | null;\n  savePersonalData?: boolean | null;\n} | null;\n\n/** What the fieldset publishes to its controls. Carries no live value — react-hook-form owns those. */\ntype ClientPreferencesFieldsetContextValue = Readonly<{\n  namespace: 'clientPreferences';\n  /** Seeds, resolved from `$data`. `null` (not chosen yet) reads as unchecked, per the opt-in default. */\n  saved: Readonly<Record<ClientPreferenceKey, boolean>>;\n  /** True when the session reports `canEditData: false`. */\n  readOnly: boolean;\n  /** The fieldset's own validation rules, per key. Present and empty today (Decision 6). */\n  rules: Readonly<Partial<Record<ClientPreferenceKey, FieldRule>>>;\n}>;\n\n/** No control publishes a rule today (Decision 6) — kept as a stable empty object so the context\n * value's identity does not churn on every render. */\nconst NO_RULES: Readonly<Partial<Record<ClientPreferenceKey, FieldRule>>> = {};\n\n/**\n * Rows `ClientPreferencesFieldsetSkeleton` draws when nobody says otherwise: one per consent flag in\n * the full anatomy. It is a default and not a derivation, because the composed children are opaque\n * here. A page that composes only one control sets `skeletonCount` to 1, or the form jumps by a row\n * when the controls take the skeleton's place.\n */\nconst CLIENT_PREFERENCES_SKELETON_ROWS = 2;\n\nconst CLIENT_PREFERENCES_FIELDSET_UNSET = Symbol('ClientPreferencesFieldsetContextUnset');\n\nconst ClientPreferencesFieldsetContext = createContext<\n  ClientPreferencesFieldsetContextValue | typeof CLIENT_PREFERENCES_FIELDSET_UNSET\n>(CLIENT_PREFERENCES_FIELDSET_UNSET);\n\nfunction useClientPreferencesFieldsetContext(): ClientPreferencesFieldsetContextValue {\n  const ctx = useContext(ClientPreferencesFieldsetContext);\n  if (ctx === CLIENT_PREFERENCES_FIELDSET_UNSET) {\n    throw new Error('ClientPreferencesFieldset controls must be used inside ClientPreferencesFieldset.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Props\n// ---------------------------------------------------------------------------\n\nexport type ClientPreferencesFieldsetProps = MessageLocaleProp & {\n  /** Placeholder rows the loading skeleton draws. Set it to the number of controls composed here. */\n  skeletonCount?: number;\n  /** The loading and loaded announcements and the accessible group name. */\n  $content?: ContentValue<typeof ClientPreferencesFieldsetContent>;\n  className?: string;\n  children?: ReactNode;\n  /** `ClientPreferencesFieldsetData` slice forwarded by the reactive runtime. */\n  $data?: ClientPreferencesFieldsetData;\n  /** Compiler-injected; carries `identity.clientPreferencesUpdate`. */\n  $actions?: ComponentActions;\n};\n\ntype PreferenceControlProps<T extends ContentTypeDefinition> = MessageLocaleProp & {\n  /** The control's label. */\n  $content?: ContentValue<T>;\n  className?: string;\n  children?: ReactNode;\n};\n\nexport type ClientPreferencesNewsletterControlProps = PreferenceControlProps<\n  typeof ClientPreferencesNewsletterControlContent\n>;\nexport type ClientPreferencesSavePersonalDataControlProps = PreferenceControlProps<\n  typeof ClientPreferencesSavePersonalDataControlContent\n>;\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const ClientPreferencesFieldsetDefinition = defineComponent<ClientPreferencesFieldsetProps>({\n  name: 'ClientPreferencesFieldset',\n  importPath: '@vtex/faststore/components',\n  component: ClientPreferencesFieldset,\n  content: ClientPreferencesFieldsetContent,\n  fragment,\n  fetchStrategy: 'reactive',\n  skeleton: ClientPreferencesFieldsetSkeleton,\n  requiresContext: ['form', 'session'],\n  providesContext: 'client-preferences',\n  actions: { identity: ['clientPreferencesUpdate'] },\n  editor: { label: 'Client Preferences Fieldset', category: 'identity' },\n  schema: {\n    skeletonCount: { type: 'number', default: 2, label: 'Skeleton rows' },\n  },\n  guideline:\n    \"Registers a batched write of the ClientPreferences entity with the enclosing FormRoot; renders one Fieldset.Root and no <form>. Distinct from ClientPreferencesRoot (matter/client-preferences), which writes on toggle and requires client-preferences-toggle — the two cannot compile into each other's container. Must be inside a FormRoot with a SessionRoot ancestor. Compose ClientPreferencesNewsletterControl and/or ClientPreferencesSavePersonalDataControl as children. The controls mount only once the preferences have resolved, with skeletonCount placeholder rows in their place until then — set it to the number of controls composed, or the form jumps by the difference. Style the announcement sr-only; it reads the $content fields loadingLabel and loadedLabel. Dispatches only the flags the shopper changed. The $content field groupLabel names the group as its accessible name; an unauthored one emits no aria-label, and a composed FieldsetLegend wins over it.\",\n});\n\nexport const ClientPreferencesNewsletterControlDefinition = defineComponent<ClientPreferencesNewsletterControlProps>({\n  name: 'ClientPreferencesNewsletterControl',\n  importPath: '@vtex/faststore/components',\n  component: ClientPreferencesNewsletterControl,\n  content: ClientPreferencesNewsletterControlContent,\n  requiresContext: 'client-preferences',\n  providesContext: 'field',\n  editor: { label: 'Client Preferences Newsletter Control', category: 'identity' },\n  schema: {},\n  guideline:\n    \"The bound newsletter opt-in control, labelled by the $content field label; must be a descendant of ClientPreferencesFieldset. Renders Field.Root > Field.Label > Field.Checkbox by default, or the composed children in the author's own order. Defaults to unchecked.\",\n});\n\nexport const ClientPreferencesSavePersonalDataControlDefinition =\n  defineComponent<ClientPreferencesSavePersonalDataControlProps>({\n    name: 'ClientPreferencesSavePersonalDataControl',\n    importPath: '@vtex/faststore/components',\n    component: ClientPreferencesSavePersonalDataControl,\n    content: ClientPreferencesSavePersonalDataControlContent,\n    requiresContext: 'client-preferences',\n    providesContext: 'field',\n    editor: { label: 'Client Preferences Save Personal Data Control', category: 'identity' },\n    schema: {},\n    guideline:\n      \"The bound save-personal-data opt-in control, labelled by the $content field label; must be a descendant of ClientPreferencesFieldset. Renders Field.Root > Field.Label > Field.Checkbox by default, or the composed children in the author's own order. Defaults to unchecked.\",\n  });\n\n// ---------------------------------------------------------------------------\n// Fieldset root\n// ---------------------------------------------------------------------------\n\n/**\n * Registers a batched write of the `ClientPreferences` entity with the enclosing `FormRoot`\n * (`registerFieldset`, namespace `clientPreferences`) on mount, unconditionally — so this fieldset keeps\n * its original dispatch slot even while its own query is still resolving. Its children — the seed values\n * and the field-name registry its controls need — render only once the entity has resolved; until then\n * the `Fieldset.Root` carries `-pending` and renders `ClientPreferencesFieldsetSkeleton` (Decision 5).\n * `dispatch` and `toPayload` are `useCallback([])`-stable and read `$actions` through a ref, so the\n * registration effect runs exactly once per mount regardless of how often the parent re-renders.\n *\n * \"Resolved\" is two conditions, because `$data` alone cannot answer it. Under the reactive runtime the\n * slice is defined from the first render — `useReactiveEntity` hands down `fallbackData` while the cache\n * read is incomplete — so an empty server answer looks exactly like a resolved one, and the checkboxes\n * would mount seeded unchecked before the shopper's saved consent arrives. `useSeedAdoption` re-seeds a\n * clean checkbox with `defaultValue` on every render, but once it turns dirty no later seed ever\n * reaches it again: a shopper who toggles it before the real consent arrives locks that unchecked\n * seed in for good, and even a shopper who does not toggle it sees the checkbox flash to the saved\n * value. `useReactiveDataSettled` supplies\n * the missing half: the page query's own in-flight state, latched so it only ever goes pending →\n * settled. The `$data === undefined` half still carries trees with no reactive root above them, where\n * the slice arrives as a plain prop.\n *\n * Both ends of that wait are spoken: the fieldset carries `aria-busy` while it lasts and holds a polite\n * live region that announces the `loadingLabel` and then the `loadedLabel` message. Style the region `sr-only` — it is\n * text meant for a screen reader, not for the page.\n */\nexport function ClientPreferencesFieldset({\n  skeletonCount = CLIENT_PREFERENCES_SKELETON_ROWS,\n  $content,\n  $locale,\n  className,\n  children,\n  $data: $dataProp,\n  $actions: $actionsProp,\n}: ClientPreferencesFieldsetProps) {\n  // Nesting fieldsets has no legitimate use: useFieldsetField resolves the *nearest*\n  // FieldsetFieldContext, not the one owning a control's actual namespace, so a control nested two\n  // fieldsets deep would silently register under the wrong one and its write would be discarded on\n  // submit. Runtime registry integrity, mirroring the namespace-collision throw FormRoot already ships\n  // (form.tsx:280-288).\n  useNoAncestorFieldset('ClientPreferencesFieldset');\n\n  const $data = useDataOverride($dataProp);\n\n  const $actions = useActionsOverride($actionsProp);\n  const messages = useMessageFormatter(ClientPreferencesFieldsetContent, $content);\n  const { format } = messages;\n  const groupLabel = format('groupLabel');\n  // Three conditions, not two. `useReactiveDataSettled` latches one way and never re-arms, so on its\n  // own it answers \"has this page ever resolved\", not \"is what I am holding right now the server's\n  // answer\" — after the page query's entity ref moves to one this cache never stored, or its root is\n  // skipped for want of a variable, the slice silently regresses to `fallbackData` while the latch\n  // still reads settled. `useEntityDataResolved` is the per-entity half: unlatched, so it follows the\n  // slice back down and returns this fieldset to its skeleton instead of leaving live controls seeded\n  // from a placeholder.\n  const settled = useReactiveDataSettled();\n  const sliceResolved = useEntityDataResolved();\n  const resolved = settled && sliceResolved && $data !== undefined;\n  // Also enforces the SessionRoot ancestor: useSession() throws when rendered outside one.\n  const { canEditData } = useSession();\n  const readOnly = !canEditData;\n\n  // Runs before useFormContext() below: useFormRegistry() throws the friendly \"Form parts must be used\n  // inside FormRoot.\" error when no FormRoot is above, so a FormRoot-less render fails there rather than\n  // reaching the getFieldState destructure, which throws an unhelpful TypeError instead (useFormContext()\n  // resolves to null outside a FormRoot, and destructuring null throws).\n  const { registerFieldset } = useFormRegistry();\n\n  // Decision 3, as later narrowed: this fieldset still reads dirtiness imperatively, but the rule is no\n  // longer the form's. `FormRoot` subscribes `dirtyFields` in render and decides which fieldsets to\n  // dispatch from it, by the fields each one has mounted, on react-hook-form's documented contract.\n  //\n  // The imperative read survives here because it asks a different question in a different place: which\n  // of *this* fieldset's own fields changed, resolved inside `toPayload` at submit time, by full\n  // registered field name — the shape `getFieldState` documents. `useFormContext()` adds no\n  // `formState` subscription of its own; one is created only when a caller reads a formState key off\n  // the `useForm`/`useFormState` proxy (or hands that already-subscribed object to `getFieldState`'s\n  // second argument). Calling `getFieldState(name)` with no second argument reads the current internal\n  // state directly, so this fieldset root still does not re-render on a keystroke.\n  const { getFieldState } = useFormContext();\n\n  const latest = useRef({ $actions, readOnly, getFieldState, messages });\n  useEffect(() => {\n    latest.current = { $actions, readOnly, getFieldState, messages };\n  }, [$actions, readOnly, getFieldState, messages]);\n\n  const { registry: fieldsetRegistry, getFieldNames } = useFieldsetFieldNames('clientPreferences');\n\n  const dispatch = useCallback(async (payload: Record<string, unknown>) => {\n    // Defence-in-depth: the UI disables every input while read-only, but `FormClear` sets values (and\n    // marks them dirty) on every registered field regardless of that disabled attribute — react-hook-\n    // form's own `useController` calls never receive a `disabled` registration option, so it has no\n    // notion of \"disabled\" of its own. Guarding here keeps the write from reaching the network even if\n    // some other composition dirties this fieldset while canEditData is false (the server also refuses,\n    // but a client-side guard should not depend on that).\n    if (latest.current.readOnly) {\n      throw new Error('ClientPreferencesFieldset cannot dispatch while the session is read-only.');\n    }\n    const update = latest.current.$actions?.identity?.clientPreferencesUpdate;\n    // Throwing is the contract's failure path: FormRoot catches it and records this fieldset's failure\n    // (form.tsx:264-266). Returning [] would report an unqualified success for a write that never\n    // happened.\n    if (!update) throw new Error('ClientPreferencesFieldset requires $actions.identity.clientPreferencesUpdate.');\n    const userErrors = await update(payload as ClientPreferencesUpdateInput);\n    return userErrors.map((error) => wordClientPreferencesError(error, latest.current.messages));\n  }, []);\n\n  const toPayload = useCallback((values: Record<string, unknown>): Record<string, unknown> => {\n    const { getFieldState } = latest.current;\n    // FR-6: a flag is emitted only when the shopper actually toggled it. `getFieldState` is called\n    // with no second argument, which reads react-hook-form's current internal state without\n    // subscribing to it (Decision 3).\n    const isDirty = (key: ClientPreferenceKey) => getFieldState(`clientPreferences.${key}`).isDirty;\n    // Boolean() coercion is defence in depth: the bound checkbox part itself now writes its own\n    // field's typed empty value on Clear (false, not ''), but this fieldset should not depend on\n    // every caller writing a well-typed value.\n    const payload: Record<string, boolean> = {};\n    if ('optinNewsLetter' in values && isDirty('optinNewsLetter')) {\n      payload.optinNewsLetter = Boolean(values.optinNewsLetter);\n    }\n    if ('savePersonalData' in values && isDirty('savePersonalData')) {\n      payload.savePersonalData = Boolean(values.savePersonalData);\n    }\n    return payload;\n  }, []);\n\n  useEffect(\n    () =>\n      registerFieldset({\n        namespace: 'clientPreferences',\n        getFieldNames,\n        dispatch,\n        toPayload,\n        // Decision 1: the register is a machine identifier, the kebab-case ASCII rendering of this\n        // registration's own `namespace` (`clientPreferences` → `client-preferences`) — not authored\n        // per page (Decision 2).\n        label: 'client-preferences',\n      }),\n    [registerFieldset, getFieldNames, dispatch, toPayload],\n  );\n\n  const saved = useMemo<Readonly<Record<ClientPreferenceKey, boolean>>>(\n    () => ({\n      optinNewsLetter: Boolean($data?.optinNewsLetter ?? false),\n      savePersonalData: Boolean($data?.savePersonalData ?? false),\n    }),\n    [$data],\n  );\n\n  const contextValue = useMemo<ClientPreferencesFieldsetContextValue>(\n    () => ({ namespace: 'clientPreferences', saved, readOnly, rules: NO_RULES }),\n    [saved, readOnly],\n  );\n\n  // Assistive technology only reports a change inside a region that was already in the tree, so a\n  // region mounted together with its text announces nothing. The region therefore sits in both\n  // branches and starts empty, with the wait written on the pass after mount and replaced — not\n  // cleared — once the controls are up: the skeleton is `aria-hidden`, so without this second\n  // message the form would materialise in silence (WCAG 2.1 SC 4.1.3).\n  const [announcement, setAnnouncement] = useState('');\n  const announced = format(resolved ? 'loadedLabel' : 'loadingLabel');\n  useEffect(() => {\n    setAnnouncement(announced);\n  }, [announced]);\n\n  return (\n    <Fieldset.Root\n      className={className}\n      disabled={readOnly}\n      aria-busy={resolved ? undefined : true}\n      // FR-12: a missing message means no name is exposed. On the root itself (FR-13), so it is identical whether the fieldset\n      // is pending or resolved; a page-composed FieldsetLegend still wins via aria-labelledby.\n      {...(groupLabel.trim() ? { 'aria-label': groupLabel } : {})}\n      data-fs-client-preferences-fieldset=\"\"\n      {...(resolved ? {} : { 'data-fs-client-preferences-fieldset-pending': '' })}\n      {...(readOnly ? { 'data-fs-client-preferences-fieldset-readonly': '' } : {})}\n    >\n      {resolved ? (\n        <FieldsetFieldContext.Provider value={fieldsetRegistry}>\n          <ClientPreferencesFieldsetContext.Provider value={contextValue}>\n            {children}\n          </ClientPreferencesFieldsetContext.Provider>\n        </FieldsetFieldContext.Provider>\n      ) : (\n        <ClientPreferencesFieldsetSkeleton count={skeletonCount} />\n      )}\n      <output aria-live=\"polite\" data-fs-client-preferences-fieldset-announcement=\"\">\n        {announcement}\n      </output>\n    </Fieldset.Root>\n  );\n}\n\n/**\n * The loading state of the fieldset, rendered in place of the controls until the entity resolves and\n * declared as the definition's `skeleton`. Purely visual: the wait is spoken by the fieldset's own live\n * region, so this is hidden from assistive technology rather than announced twice.\n */\nexport function ClientPreferencesFieldsetSkeleton({\n  count = CLIENT_PREFERENCES_SKELETON_ROWS,\n  className,\n  ...props\n}: ComponentPropsWithRef<'div'> & { count?: number }) {\n  return (\n    <div {...props} className={className} data-fs-client-preferences-fieldset-skeleton=\"\" aria-hidden=\"true\">\n      {Array.from({ length: count }, (_, i) => (\n        <span key={i} data-fs-client-preferences-fieldset-skeleton-field=\"\" />\n      ))}\n    </div>\n  );\n}\n\nClientPreferencesFieldset.Skeleton = ClientPreferencesFieldsetSkeleton;\n\n// ---------------------------------------------------------------------------\n// Controls\n// ---------------------------------------------------------------------------\n\nfunction PreferenceControl({\n  fieldKey,\n  attr,\n  label,\n  className,\n  children,\n}: Readonly<{\n  fieldKey: ClientPreferenceKey;\n  attr: string;\n  /** Formatted by the owning control. */\n  label: string;\n  className?: string;\n  children?: ReactNode;\n}>) {\n  const { namespace, saved, readOnly, rules } = useClientPreferencesFieldsetContext();\n  const name = useFieldsetField(namespace, fieldKey);\n\n  return (\n    <FieldBinding name={name} label={label} defaultValue={saved[fieldKey]} rule={rules[fieldKey]} disabled={readOnly}>\n      <Field.Root className={className} data-fs-client-preferences-fieldset-field={attr}>\n        {children ?? (\n          <Field.Label>\n            <Field.Checkbox>\n              <Checkbox.Indicator>\n                <Icon name=\"checked\" />\n              </Checkbox.Indicator>\n            </Field.Checkbox>\n            {label}\n          </Field.Label>\n        )}\n      </Field.Root>\n    </FieldBinding>\n  );\n}\n\nexport function ClientPreferencesNewsletterControl({\n  $content,\n  $locale,\n  className,\n  children,\n}: ClientPreferencesNewsletterControlProps) {\n  const { format } = useMessageFormatter(ClientPreferencesNewsletterControlContent, $content);\n  return (\n    <PreferenceControl fieldKey=\"optinNewsLetter\" attr=\"newsletter\" label={format('label')} className={className}>\n      {children}\n    </PreferenceControl>\n  );\n}\n\nexport function ClientPreferencesSavePersonalDataControl({\n  $content,\n  $locale,\n  className,\n  children,\n}: ClientPreferencesSavePersonalDataControlProps) {\n  const { format } = useMessageFormatter(ClientPreferencesSavePersonalDataControlContent, $content);\n  return (\n    <PreferenceControl\n      fieldKey=\"savePersonalData\"\n      attr=\"save-personal-data\"\n      label={format('label')}\n      className={className}\n    >\n      {children}\n    </PreferenceControl>\n  );\n}\n"],"mappings":"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"}

package/dist/matter/client-preferences/client-preferences.d.ts

@@ -1,8 +1,45 @@
+import { ContentValue, MessageLocaleProp } from "../../core/dist/define-content-type.js";
 import { ComponentDefinition } from "../../core/dist/define-component.js";
 import "../../core/dist/index.js";
 import { ComponentActions } from "../../sdk/actions/types.js";
 import { ReactNode } from "react";
 //#region src/matter/client-preferences/client-preferences.d.ts
+export declare const NewsletterOptInControlContent: {
+  readonly id: "newsletter-opt-in-control";
+  readonly title: "Newsletter Opt-In Control";
+  readonly description: "The inline message shown when saving the newsletter opt-in fails.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly genericErrorMessage: {
+        readonly type: "string";
+        readonly title: "Save failure message";
+        readonly description: "Shown for a network failure and for any refusal the shopper cannot act on.";
+        readonly format: "icu-message";
+        readonly messageSource: "Unable to save your preference. Please try again.";
+      };
+    };
+  };
+};
+export declare const SavePersonalDataOptInControlContent: {
+  readonly id: "save-personal-data-opt-in-control";
+  readonly title: "Save Personal Data Opt-In Control";
+  readonly description: "The inline message shown when saving the save-personal-data opt-in fails.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly genericErrorMessage: {
+        readonly type: "string";
+        readonly title: "Save failure message";
+        readonly description: "Shown for a network failure and for any refusal the shopper cannot act on.";
+        readonly format: "icu-message";
+        readonly messageSource: "Unable to save your preference. Please try again.";
+      };
+    };
+  };
+};
 /** The `$data` slice forwarded by the reactive runtime — the `ClientPreferences` sibling entity, unwrapped. */
 export type ClientPreferencesData = {
   optinNewsLetter?: boolean | null;
@@ -14,17 +51,23 @@ export type ClientPreferencesRootProps = {
   className?: string;
   children?: ReactNode;
 };
-export type ClientPreferencesControlProps = {
+export type ClientPreferencesControlProps = MessageLocaleProp & {
   label: string;
   className?: string;
   /** Injected by the compiler from `actions: { identity: ['clientPreferencesUpdate'] }`; the write surface. */
   $actions?: ComponentActions;
 };
-export type NewsletterOptInControlProps = ClientPreferencesControlProps;
-export type SavePersonalDataOptInControlProps = ClientPreferencesControlProps;
+export type NewsletterOptInControlProps = ClientPreferencesControlProps & {
+  /** The inline message for a refused save. */
+  $content?: ContentValue<typeof NewsletterOptInControlContent>;
+};
+export type SavePersonalDataOptInControlProps = ClientPreferencesControlProps & {
+  /** The inline message for a refused save. */
+  $content?: ContentValue<typeof SavePersonalDataOptInControlContent>;
+};
 export declare const ClientPreferencesRootDefinition: ComponentDefinition<ClientPreferencesRootProps>;
-export declare const NewsletterOptInControlDefinition: ComponentDefinition<ClientPreferencesControlProps>;
-export declare const SavePersonalDataOptInControlDefinition: ComponentDefinition<ClientPreferencesControlProps>;
+export declare const NewsletterOptInControlDefinition: ComponentDefinition<NewsletterOptInControlProps>;
+export declare const SavePersonalDataOptInControlDefinition: ComponentDefinition<SavePersonalDataOptInControlProps>;
 /**
  * Renders the client-preferences section Root: reads `$data` (the `ClientPreferences` sibling entity),
  * reads `useSession()` (which also enforces the `SessionRoot` ancestor, mirroring
@@ -37,8 +80,8 @@ export declare const SavePersonalDataOptInControlDefinition: ComponentDefinition
  * `data-fs-*` attribute, mirroring `EmailIdentificationControl`.
  */
 export declare function ClientPreferencesRoot({ $data: $dataProp, className, children }: ClientPreferencesRootProps): import("react/jsx-runtime").JSX.Element;
-export declare function NewsletterOptInControl(props: NewsletterOptInControlProps): import("react/jsx-runtime").JSX.Element;
-export declare function SavePersonalDataOptInControl(props: SavePersonalDataOptInControlProps): import("react/jsx-runtime").JSX.Element;
+export declare function NewsletterOptInControl({ $locale, ...props }: NewsletterOptInControlProps): import("react/jsx-runtime").JSX.Element;
+export declare function SavePersonalDataOptInControl({ $locale, ...props }: SavePersonalDataOptInControlProps): import("react/jsx-runtime").JSX.Element;
 export declare const ClientPreferences: {
   Root: typeof ClientPreferencesRoot;
   NewsletterOptInControl: typeof NewsletterOptInControl;

package/dist/matter/client-preferences/client-preferences.js

@@ -1,19 +1,31 @@
 "use client";
 import { defineComponent } from "../../core/dist/define-component.js";
+import { defineContentType } from "../../core/dist/define-content-type.js";
 import "../../core/dist/index.js";
+import { useMessageFormatter } from "../../sdk/i18n/use-message-formatter.js";
 import { Checkbox } from "../../particles/checkbox/checkbox.js";
 import { Field } from "../../particles/field/field.js";
 import { useActionsOverride } from "../../sdk/actions/actions-override-context.js";
+import { formatErrorCode } from "../../sdk/i18n/format-error-code.js";
 import { useDataOverride } from "../../sdk/data/data-override-context.js";
 import { useSession } from "../session/session.js";
 import { Icon } from "../../particles/icon/icon.js";
 import { createContext, useCallback, useContext, useMemo, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
-const ClientPreferencesRootDefinition = defineComponent({
-	name: "ClientPreferencesRoot",
-	importPath: "@vtex/faststore/components",
-	component: ClientPreferencesRoot,
-	fragment: `
+//#region src/matter/client-preferences/client-preferences.tsx
+/**
+* The `client-preferences` section matter (per ADR-0011: a matter is decomposed by DATA OWNERSHIP,
+* not per field). Both opt-ins — newsletter (`optinNewsLetter`) and save-personal-data
+* (`savePersonalData`) — are light booleans owned by the User Identity `ClientPreferences` entity
+* (a SIBLING of `Cart`, not nested under it, per the identity RFC), so they live under ONE
+* `ClientPreferencesRoot` that declares a single section fragment on `Query` selecting both fields.
+* The two merchant-facing Controls consume that one section context (ADR-0011 governs data
+* ownership, not the editor palette) and share one internal `OptInControl` implementation: the
+* section context, the `$data` → values seeding, the per-field pending/error tracking, the inlined
+* `Checkbox` + `Field` Control render, and dispatch via `$actions.identity.clientPreferencesUpdate`
+* (mirrors the `email-identification` matter; reads/writes follow ADR-0006 / ADR-0010 / ADR-0011).
+*/
+const fragment = `
   fragment ClientPreferencesData on Query {
     clientPreferences {
       __typename
@@ -22,7 +34,55 @@ const ClientPreferencesRootDefinition = defineComponent({
       savePersonalData
     }
   }
-`,
+`;
+const NewsletterOptInControlContent = defineContentType({
+	id: "newsletter-opt-in-control",
+	title: "Newsletter Opt-In Control",
+	description: "The inline message shown when saving the newsletter opt-in fails.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { genericErrorMessage: {
+			type: "string",
+			title: "Save failure message",
+			description: "Shown for a network failure and for any refusal the shopper cannot act on.",
+			format: "icu-message",
+			messageSource: "Unable to save your preference. Please try again."
+		} }
+	}
+});
+const SavePersonalDataOptInControlContent = defineContentType({
+	id: "save-personal-data-opt-in-control",
+	title: "Save Personal Data Opt-In Control",
+	description: "The inline message shown when saving the save-personal-data opt-in fails.",
+	schema: {
+		type: "object",
+		additionalProperties: false,
+		properties: { genericErrorMessage: {
+			type: "string",
+			title: "Save failure message",
+			description: "Shown for a network failure and for any refusal the shopper cannot act on.",
+			format: "icu-message",
+			messageSource: "Unable to save your preference. Please try again."
+		} }
+	}
+});
+/**
+* `ClientPreferencesUpdateErrorCode` of API Core's schema plus the client-minted transport failure. None
+* is something the shopper can fix by toggling again, so all share the generic message.
+*/
+const NEWSLETTER_OPT_IN_ERROR_FIELDS = {
+	MISSING_CART_CONTEXT: "genericErrorMessage",
+	CART_NOT_FOUND: "genericErrorMessage",
+	NO_PREFERENCE_PROVIDED: "genericErrorMessage",
+	NETWORK_ERROR: "genericErrorMessage"
+};
+const SAVE_PERSONAL_DATA_OPT_IN_ERROR_FIELDS = { ...NEWSLETTER_OPT_IN_ERROR_FIELDS };
+const ClientPreferencesRootDefinition = defineComponent({
+	name: "ClientPreferencesRoot",
+	importPath: "@vtex/faststore/components",
+	component: ClientPreferencesRoot,
+	fragment,
 	fetchStrategy: "reactive",
 	providesContext: "client-preferences-toggle",
 	requiresContext: "session",
@@ -37,6 +97,7 @@ const NewsletterOptInControlDefinition = defineComponent({
 	name: "NewsletterOptInControl",
 	importPath: "@vtex/faststore/components",
 	component: NewsletterOptInControl,
+	content: NewsletterOptInControlContent,
 	requiresContext: "client-preferences-toggle",
 	actions: { identity: ["clientPreferencesUpdate"] },
 	editor: {
@@ -47,12 +108,13 @@ const NewsletterOptInControlDefinition = defineComponent({
 		type: "string",
 		label: "Label"
 	} },
-	guideline: "The bound newsletter opt-in checkbox; must be a descendant of ClientPreferencesRoot. Toggling writes the optinNewsLetter preference via $actions.identity.clientPreferencesUpdate. Defaults to unchecked."
+	guideline: "The bound newsletter opt-in checkbox; must be a descendant of ClientPreferencesRoot. Toggling writes the optinNewsLetter preference via $actions.identity.clientPreferencesUpdate; a refused save shows the $content field genericErrorMessage. Defaults to unchecked."
 });
 const SavePersonalDataOptInControlDefinition = defineComponent({
 	name: "SavePersonalDataOptInControl",
 	importPath: "@vtex/faststore/components",
 	component: SavePersonalDataOptInControl,
+	content: SavePersonalDataOptInControlContent,
 	requiresContext: "client-preferences-toggle",
 	actions: { identity: ["clientPreferencesUpdate"] },
 	editor: {
@@ -63,7 +125,7 @@ const SavePersonalDataOptInControlDefinition = defineComponent({
 		type: "string",
 		label: "Label"
 	} },
-	guideline: "The bound save-personal-data opt-in checkbox; must be a descendant of ClientPreferencesRoot. Toggling writes the savePersonalData preference via $actions.identity.clientPreferencesUpdate. Defaults to unchecked."
+	guideline: "The bound save-personal-data opt-in checkbox; must be a descendant of ClientPreferencesRoot. Toggling writes the savePersonalData preference via $actions.identity.clientPreferencesUpdate; a refused save shows the $content field genericErrorMessage. Defaults to unchecked."
 });
 const CLIENT_PREFERENCES_UNSET = Symbol("ClientPreferencesContextUnset");
 const ClientPreferencesContext = createContext(CLIENT_PREFERENCES_UNSET);
@@ -141,11 +203,14 @@ function ClientPreferencesRoot({ $data: $dataProp, className, children }) {
 * particle). Reads ITS field's value, pending, and error from the section context and dispatches the
 * write through `$actions.identity.clientPreferencesUpdate({ [key]: value })`, handing the promise to
 * the section so the in-flight key and returned userErrors are tracked per field. The `fieldKey`,
-* `dataAttr`, `pendingAttr`, and `readonlyAttr` are fixed by each registered Control; only
-* `label`/`className` are merchant-configurable.
+* `dataAttr`, `pendingAttr`, `readonlyAttr`, content type and error map are fixed by each registered
+* Control; only `label`/`className` and the `$content` message are merchant-configurable. A refusal is
+* worded by the Control's message for its code; a code the map does not know shows the Control's
+* genericErrorMessage.
 */
-function OptInControl({ fieldKey, dataAttr, pendingAttr, readonlyAttr, label, className, $actions: $actionsProp }) {
+function OptInControl({ fieldKey, dataAttr, pendingAttr, readonlyAttr, contentType, errorFields, label, className, $content, $actions: $actionsProp }) {
 	const $actions = useActionsOverride($actionsProp);
+	const { format } = useMessageFormatter(contentType, $content);
 	const { values, trackWrite, pendingKeys, errorByKey, readOnly } = useClientPreferencesContext();
 	const fieldErrors = errorByKey[fieldKey] ?? [];
 	const value = values[fieldKey];
@@ -174,23 +239,27 @@ function OptInControl({ fieldKey, dataAttr, pendingAttr, readonlyAttr, label, cl
 				children: /* @__PURE__ */ jsx(Checkbox.Indicator, { children: /* @__PURE__ */ jsx(Icon, { name: "checked" }) })
 			}), label] }), invalid && firstError ? /* @__PURE__ */ jsx(Field.Error, {
 				match: true,
-				children: firstError.message
+				children: formatErrorCode(contentType, errorFields, firstError, format, "genericErrorMessage")
 			}) : null]
 		})
 	});
 }
-function NewsletterOptInControl(props) {
+function NewsletterOptInControl({ $locale, ...props }) {
 	return /* @__PURE__ */ jsx(OptInControl, {
 		...props,
+		contentType: NewsletterOptInControlContent,
+		errorFields: NEWSLETTER_OPT_IN_ERROR_FIELDS,
 		fieldKey: "optinNewsLetter",
 		dataAttr: "data-fs-newsletter-opt-in",
 		pendingAttr: "data-fs-newsletter-opt-in-pending",
 		readonlyAttr: "data-fs-newsletter-opt-in-readonly"
 	});
 }
-function SavePersonalDataOptInControl(props) {
+function SavePersonalDataOptInControl({ $locale, ...props }) {
 	return /* @__PURE__ */ jsx(OptInControl, {
 		...props,
+		contentType: SavePersonalDataOptInControlContent,
+		errorFields: SAVE_PERSONAL_DATA_OPT_IN_ERROR_FIELDS,
 		fieldKey: "savePersonalData",
 		dataAttr: "data-fs-save-personal-data-opt-in",
 		pendingAttr: "data-fs-save-personal-data-opt-in-pending",
@@ -203,6 +272,6 @@ const ClientPreferences = {
 	SavePersonalDataOptInControl
 };
 //#endregion
-export { ClientPreferences, ClientPreferencesRoot, ClientPreferencesRootDefinition, NewsletterOptInControl, NewsletterOptInControlDefinition, SavePersonalDataOptInControl, SavePersonalDataOptInControlDefinition };
+export { ClientPreferences, ClientPreferencesRoot, ClientPreferencesRootDefinition, NEWSLETTER_OPT_IN_ERROR_FIELDS, NewsletterOptInControl, NewsletterOptInControlContent, NewsletterOptInControlDefinition, SAVE_PERSONAL_DATA_OPT_IN_ERROR_FIELDS, SavePersonalDataOptInControl, SavePersonalDataOptInControlContent, SavePersonalDataOptInControlDefinition };
 
 //# sourceMappingURL=client-preferences.js.map

package/dist/matter/client-preferences/client-preferences.js.map

@@ -1 +1 @@
-{"version":3,"file":"client-preferences.js","names":[],"sources":["../../../src/matter/client-preferences/client-preferences.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport { createContext, type ReactNode, useCallback, useContext, useMemo, useState } from 'react';\nimport { Checkbox } from '../../particles/checkbox/checkbox.js';\nimport { Field } from '../../particles/field/field.js';\nimport { Icon } from '../../particles/icon/icon.js';\nimport { useActionsOverride } from '../../sdk/actions/actions-override-context.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport type { ClientPreferenceKey, ClientProfileUserError } from '../../sdk/identity/operations.js';\nimport { useSession } from '../session/session.js';\n\n/**\n * The `client-preferences` section matter (per ADR-0011: a matter is decomposed by DATA OWNERSHIP,\n * not per field). Both opt-ins — newsletter (`optinNewsLetter`) and save-personal-data\n * (`savePersonalData`) — are light booleans owned by the User Identity `ClientPreferences` entity\n * (a SIBLING of `Cart`, not nested under it, per the identity RFC), so they live under ONE\n * `ClientPreferencesRoot` that declares a single section fragment on `Query` selecting both fields.\n * The two merchant-facing Controls consume that one section context (ADR-0011 governs data\n * ownership, not the editor palette) and share one internal `OptInControl` implementation: the\n * section context, the `$data` → values seeding, the per-field pending/error tracking, the inlined\n * `Checkbox` + `Field` Control render, and dispatch via `$actions.identity.clientPreferencesUpdate`\n * (mirrors the `email-identification` matter; reads/writes follow ADR-0006 / ADR-0010 / ADR-0011).\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — colocated (ADR-0011), reads the ClientPreferences sibling\n// entity via Query. Authored as a raw string (not the codegen graphql() factory),\n// mirroring the EmailIdentification matter: the compiler derives the entity fragment\n// on `clientPreferences` and subscribes reactively. One section fragment owns both\n// opt-in fields (ADR-0011).\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment ClientPreferencesData on Query {\n    clientPreferences {\n      __typename\n      id\n      optinNewsLetter\n      savePersonalData\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** The `$data` slice forwarded by the reactive runtime — the `ClientPreferences` sibling entity, unwrapped. */\nexport type ClientPreferencesData = {\n  optinNewsLetter?: boolean | null;\n  savePersonalData?: boolean | null;\n} | null;\n\nexport type ClientPreferencesRootProps = {\n  /** `Query` slice forwarded by the reactive runtime (value of the section fragment). */\n  $data?: ClientPreferencesData;\n  className?: string;\n  children?: ReactNode;\n};\n\nexport type ClientPreferencesControlProps = {\n  label: string;\n  className?: string;\n  /** Injected by the compiler from `actions: { identity: ['clientPreferencesUpdate'] }`; the write surface. */\n  $actions?: ComponentActions;\n};\n\nexport type NewsletterOptInControlProps = ClientPreferencesControlProps;\nexport type SavePersonalDataOptInControlProps = ClientPreferencesControlProps;\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const ClientPreferencesRootDefinition = defineComponent<ClientPreferencesRootProps>({\n  name: 'ClientPreferencesRoot',\n  importPath: '@vtex/faststore/components',\n  component: ClientPreferencesRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  providesContext: 'client-preferences-toggle',\n  requiresContext: 'session',\n  editor: { label: 'Client Preferences Root', category: 'identity' },\n  schema: {},\n  guideline:\n    'Binding provider for the consent opt-in section; reads both opt-in values (optinNewsLetter, savePersonalData) from the ClientPreferences identity entity (a sibling of Cart, via Query.clientPreferences) and exposes them to its Controls. Reads session state from useSession(); must be inside SessionRoot. Writes flow through $actions.identity.clientPreferencesUpdate. Wrap a NewsletterOptInControl and/or a SavePersonalDataOptInControl.',\n});\n\nexport const NewsletterOptInControlDefinition = defineComponent<NewsletterOptInControlProps>({\n  name: 'NewsletterOptInControl',\n  importPath: '@vtex/faststore/components',\n  component: NewsletterOptInControl,\n  requiresContext: 'client-preferences-toggle',\n  actions: { identity: ['clientPreferencesUpdate'] },\n  editor: { label: 'Newsletter Opt-In Control', category: 'identity' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n  },\n  guideline:\n    'The bound newsletter opt-in checkbox; must be a descendant of ClientPreferencesRoot. Toggling writes the optinNewsLetter preference via $actions.identity.clientPreferencesUpdate. Defaults to unchecked.',\n});\n\nexport const SavePersonalDataOptInControlDefinition = defineComponent<SavePersonalDataOptInControlProps>({\n  name: 'SavePersonalDataOptInControl',\n  importPath: '@vtex/faststore/components',\n  component: SavePersonalDataOptInControl,\n  requiresContext: 'client-preferences-toggle',\n  actions: { identity: ['clientPreferencesUpdate'] },\n  editor: { label: 'Save Personal Data Opt-In Control', category: 'identity' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n  },\n  guideline:\n    'The bound save-personal-data opt-in checkbox; must be a descendant of ClientPreferencesRoot. Toggling writes the savePersonalData preference via $actions.identity.clientPreferencesUpdate. Defaults to unchecked.',\n});\n\n// ---------------------------------------------------------------------------\n// Context\n// ---------------------------------------------------------------------------\n\ntype ClientPreferencesContextValue = Readonly<{\n  /** Current value of each opt-in, seeded from the query response (null → unchecked). */\n  values: Readonly<Record<ClientPreferenceKey, boolean>>;\n  /**\n   * Records that a write for `key` is in flight and stores its returned userErrors under that key so\n   * each Control surfaces ITS OWN pending/error. The Control owns the actual dispatch (it holds\n   * `$actions`); it hands the resulting promise here for the section to track.\n   */\n  trackWrite: (key: ClientPreferenceKey, write: Promise<readonly ClientProfileUserError[]>) => void;\n  /**\n   * The fields whose writes are currently in flight. A per-key set, not a single slot: concurrent\n   * writes on different fields must each keep their own Control disabled until THEIR write settles.\n   */\n  pendingKeys: ReadonlySet<ClientPreferenceKey>;\n  /** The userErrors returned by the most recent write, keyed by the field that produced them. */\n  errorByKey: Readonly<Partial<Record<ClientPreferenceKey, readonly ClientProfileUserError[]>>>;\n  /**\n   * True when the session reports `canEditData: false` — VTEX refuses profile-data edits for an\n   * identified-but-unauthenticated claimed profile, so the Controls render disabled instead of\n   * accepting writes that are doomed server-side (mirrors the email control).\n   */\n  readOnly: boolean;\n}>;\n\nconst CLIENT_PREFERENCES_UNSET = Symbol('ClientPreferencesContextUnset');\n\nconst ClientPreferencesContext = createContext<ClientPreferencesContextValue | typeof CLIENT_PREFERENCES_UNSET>(\n  CLIENT_PREFERENCES_UNSET,\n);\n\nfunction useClientPreferencesContext(): ClientPreferencesContextValue {\n  const ctx = useContext(ClientPreferencesContext);\n  if (ctx === CLIENT_PREFERENCES_UNSET) {\n    throw new Error('A client-preferences Control must be used inside a ClientPreferencesRoot.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Root\n// ---------------------------------------------------------------------------\n\n/**\n * Renders the client-preferences section Root: reads `$data` (the `ClientPreferences` sibling entity),\n * reads `useSession()` (which also enforces the `SessionRoot` ancestor, mirroring\n * `EmailIdentificationControl`), seeds both opt-in values from the section fragment, and publishes a\n * section context exposing both values plus per-field pending/error tracking. The write itself flows\n * through the Control's `$actions.identity.clientPreferencesUpdate` (ADR-0010); this Root tracks which\n * keys are in flight and stores the returned userErrors under each key so each Control surfaces ITS OWN\n * pending/error. When the session reports `canEditData: false` (identified but unauthenticated claimed\n * profile — VTEX refuses the write server-side) every Control renders disabled with its readonly\n * `data-fs-*` attribute, mirroring `EmailIdentificationControl`.\n */\nexport function ClientPreferencesRoot({ $data: $dataProp, className, children }: ClientPreferencesRootProps) {\n  const $data = useDataOverride($dataProp);\n  // Also enforces the SessionRoot ancestor: useSession() throws when rendered outside one.\n  const { canEditData } = useSession();\n  const readOnly = !canEditData;\n\n  const optinNewsLetter = Boolean($data?.optinNewsLetter ?? false);\n  const savePersonalData = Boolean($data?.savePersonalData ?? false);\n\n  const [pendingKeys, setPendingKeys] = useState<ReadonlySet<ClientPreferenceKey>>(new Set());\n  const [errorByKey, setErrorByKey] = useState<Partial<Record<ClientPreferenceKey, readonly ClientProfileUserError[]>>>(\n    {},\n  );\n\n  const trackWrite = useCallback((key: ClientPreferenceKey, write: Promise<readonly ClientProfileUserError[]>) => {\n    // Clear the key's stale error at the start of a retry (parity with the email control clearing\n    // its serverError on a new write).\n    setErrorByKey((prev) => ({ ...prev, [key]: [] }));\n    setPendingKeys((prev) => new Set(prev).add(key));\n    void write\n      .then((userErrors) => {\n        setErrorByKey((prev) => ({ ...prev, [key]: userErrors }));\n      })\n      .finally(() => {\n        setPendingKeys((prev) => {\n          const next = new Set(prev);\n          next.delete(key);\n          return next;\n        });\n      });\n  }, []);\n\n  const values = useMemo(() => ({ optinNewsLetter, savePersonalData }) as const, [optinNewsLetter, savePersonalData]);\n\n  const contextValue = useMemo<ClientPreferencesContextValue>(\n    () => ({ values, trackWrite, pendingKeys, errorByKey, readOnly }),\n    [values, trackWrite, pendingKeys, errorByKey, readOnly],\n  );\n\n  return (\n    <ClientPreferencesContext value={contextValue}>\n      <div className={className} data-fs-client-preferences-root=\"\">\n        {children}\n      </div>\n    </ClientPreferencesContext>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Controls\n// ---------------------------------------------------------------------------\n\n/**\n * Renders one bound opt-in checkbox by inlining `Field` + `Checkbox` + `Icon` (no `CheckboxField`\n * particle). Reads ITS field's value, pending, and error from the section context and dispatches the\n * write through `$actions.identity.clientPreferencesUpdate({ [key]: value })`, handing the promise to\n * the section so the in-flight key and returned userErrors are tracked per field. The `fieldKey`,\n * `dataAttr`, `pendingAttr`, and `readonlyAttr` are fixed by each registered Control; only\n * `label`/`className` are merchant-configurable.\n */\nfunction OptInControl({\n  fieldKey,\n  dataAttr,\n  pendingAttr,\n  readonlyAttr,\n  label,\n  className,\n  $actions: $actionsProp,\n}: ClientPreferencesControlProps & {\n  fieldKey: ClientPreferenceKey;\n  dataAttr: string;\n  pendingAttr: string;\n  readonlyAttr: string;\n}) {\n  const $actions = useActionsOverride($actionsProp);\n  const { values, trackWrite, pendingKeys, errorByKey, readOnly } = useClientPreferencesContext();\n  const fieldErrors = errorByKey[fieldKey] ?? [];\n  const value = values[fieldKey];\n  const pending = pendingKeys.has(fieldKey);\n  const disabled = pending || readOnly;\n  const [firstError] = fieldErrors;\n  const invalid = Boolean(firstError);\n\n  function handleCheckedChange(checked: boolean) {\n    const update = $actions?.identity?.clientPreferencesUpdate;\n    if (!update) return;\n    trackWrite(fieldKey, update({ [fieldKey]: checked }));\n  }\n\n  return (\n    <div\n      className={className}\n      {...{ [dataAttr]: '' }}\n      {...(pending ? { [pendingAttr]: '' } : {})}\n      {...(readOnly ? { [readonlyAttr]: '' } : {})}\n    >\n      <Field.Root invalid={invalid} disabled={disabled} data-fs-field-root=\"\">\n        <Field.Label>\n          <Checkbox.Root checked={value} onCheckedChange={handleCheckedChange} disabled={disabled}>\n            <Checkbox.Indicator>\n              <Icon name=\"checked\" />\n            </Checkbox.Indicator>\n          </Checkbox.Root>\n          {label}\n        </Field.Label>\n        {invalid && firstError ? <Field.Error match>{firstError.message}</Field.Error> : null}\n      </Field.Root>\n    </div>\n  );\n}\n\nexport function NewsletterOptInControl(props: NewsletterOptInControlProps) {\n  return (\n    <OptInControl\n      {...props}\n      fieldKey=\"optinNewsLetter\"\n      dataAttr=\"data-fs-newsletter-opt-in\"\n      pendingAttr=\"data-fs-newsletter-opt-in-pending\"\n      readonlyAttr=\"data-fs-newsletter-opt-in-readonly\"\n    />\n  );\n}\n\nexport function SavePersonalDataOptInControl(props: SavePersonalDataOptInControlProps) {\n  return (\n    <OptInControl\n      {...props}\n      fieldKey=\"savePersonalData\"\n      dataAttr=\"data-fs-save-personal-data-opt-in\"\n      pendingAttr=\"data-fs-save-personal-data-opt-in-pending\"\n      readonlyAttr=\"data-fs-save-personal-data-opt-in-readonly\"\n    />\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Namespace export\n// ---------------------------------------------------------------------------\n\nexport const ClientPreferences = {\n  Root: ClientPreferencesRoot,\n  NewsletterOptInControl,\n  SavePersonalDataOptInControl,\n};\n"],"mappings":"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"}
+{"version":3,"file":"client-preferences.js","names":[],"sources":["../../../src/matter/client-preferences/client-preferences.tsx"],"sourcesContent":["'use client';\n\nimport {\n  type ContentValue,\n  defineComponent,\n  defineContentType,\n  type MessageFieldName,\n  type MessageLocaleProp,\n} from '@vtex/fs-core';\nimport { createContext, type ReactNode, useCallback, useContext, useMemo, useState } from 'react';\nimport { Checkbox } from '../../particles/checkbox/checkbox.js';\nimport { Field } from '../../particles/field/field.js';\nimport { Icon } from '../../particles/icon/icon.js';\nimport { useActionsOverride } from '../../sdk/actions/actions-override-context.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { formatErrorCode } from '../../sdk/i18n/format-error-code.js';\nimport { useMessageFormatter } from '../../sdk/i18n/use-message-formatter.js';\nimport type { ClientPreferenceKey, ClientProfileUserError } from '../../sdk/identity/operations.js';\nimport { useSession } from '../session/session.js';\n\n/**\n * The `client-preferences` section matter (per ADR-0011: a matter is decomposed by DATA OWNERSHIP,\n * not per field). Both opt-ins — newsletter (`optinNewsLetter`) and save-personal-data\n * (`savePersonalData`) — are light booleans owned by the User Identity `ClientPreferences` entity\n * (a SIBLING of `Cart`, not nested under it, per the identity RFC), so they live under ONE\n * `ClientPreferencesRoot` that declares a single section fragment on `Query` selecting both fields.\n * The two merchant-facing Controls consume that one section context (ADR-0011 governs data\n * ownership, not the editor palette) and share one internal `OptInControl` implementation: the\n * section context, the `$data` → values seeding, the per-field pending/error tracking, the inlined\n * `Checkbox` + `Field` Control render, and dispatch via `$actions.identity.clientPreferencesUpdate`\n * (mirrors the `email-identification` matter; reads/writes follow ADR-0006 / ADR-0010 / ADR-0011).\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — colocated (ADR-0011), reads the ClientPreferences sibling\n// entity via Query. Authored as a raw string (not the codegen graphql() factory),\n// mirroring the EmailIdentification matter: the compiler derives the entity fragment\n// on `clientPreferences` and subscribes reactively. One section fragment owns both\n// opt-in fields (ADR-0011).\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment ClientPreferencesData on Query {\n    clientPreferences {\n      __typename\n      id\n      optinNewsLetter\n      savePersonalData\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Content models\n// ---------------------------------------------------------------------------\n\nexport const NewsletterOptInControlContent = defineContentType({\n  id: 'newsletter-opt-in-control',\n  title: 'Newsletter Opt-In Control',\n  description: 'The inline message shown when saving the newsletter opt-in fails.',\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    properties: {\n      genericErrorMessage: {\n        type: 'string',\n        title: 'Save failure message',\n        description: 'Shown for a network failure and for any refusal the shopper cannot act on.',\n        format: 'icu-message',\n        messageSource: 'Unable to save your preference. Please try again.',\n      },\n    },\n  },\n});\n\nexport const SavePersonalDataOptInControlContent = defineContentType({\n  id: 'save-personal-data-opt-in-control',\n  title: 'Save Personal Data Opt-In Control',\n  description: 'The inline message shown when saving the save-personal-data opt-in fails.',\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    properties: {\n      genericErrorMessage: {\n        type: 'string',\n        title: 'Save failure message',\n        description: 'Shown for a network failure and for any refusal the shopper cannot act on.',\n        format: 'icu-message',\n        messageSource: 'Unable to save your preference. Please try again.',\n      },\n    },\n  },\n});\n\n/**\n * `ClientPreferencesUpdateErrorCode` of API Core's schema plus the client-minted transport failure. None\n * is something the shopper can fix by toggling again, so all share the generic message.\n */\nexport const NEWSLETTER_OPT_IN_ERROR_FIELDS = {\n  MISSING_CART_CONTEXT: 'genericErrorMessage',\n  CART_NOT_FOUND: 'genericErrorMessage',\n  NO_PREFERENCE_PROVIDED: 'genericErrorMessage',\n  NETWORK_ERROR: 'genericErrorMessage',\n} as const satisfies Record<string, MessageFieldName<typeof NewsletterOptInControlContent>>;\n\nexport const SAVE_PERSONAL_DATA_OPT_IN_ERROR_FIELDS = {\n  ...NEWSLETTER_OPT_IN_ERROR_FIELDS,\n} as const satisfies Record<string, MessageFieldName<typeof SavePersonalDataOptInControlContent>>;\n\ntype OptInErrorFields = typeof NEWSLETTER_OPT_IN_ERROR_FIELDS;\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** The `$data` slice forwarded by the reactive runtime — the `ClientPreferences` sibling entity, unwrapped. */\nexport type ClientPreferencesData = {\n  optinNewsLetter?: boolean | null;\n  savePersonalData?: boolean | null;\n} | null;\n\nexport type ClientPreferencesRootProps = {\n  /** `Query` slice forwarded by the reactive runtime (value of the section fragment). */\n  $data?: ClientPreferencesData;\n  className?: string;\n  children?: ReactNode;\n};\n\nexport type ClientPreferencesControlProps = MessageLocaleProp & {\n  label: string;\n  className?: string;\n  /** Injected by the compiler from `actions: { identity: ['clientPreferencesUpdate'] }`; the write surface. */\n  $actions?: ComponentActions;\n};\n\nexport type NewsletterOptInControlProps = ClientPreferencesControlProps & {\n  /** The inline message for a refused save. */\n  $content?: ContentValue<typeof NewsletterOptInControlContent>;\n};\nexport type SavePersonalDataOptInControlProps = ClientPreferencesControlProps & {\n  /** The inline message for a refused save. */\n  $content?: ContentValue<typeof SavePersonalDataOptInControlContent>;\n};\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const ClientPreferencesRootDefinition = defineComponent<ClientPreferencesRootProps>({\n  name: 'ClientPreferencesRoot',\n  importPath: '@vtex/faststore/components',\n  component: ClientPreferencesRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  providesContext: 'client-preferences-toggle',\n  requiresContext: 'session',\n  editor: { label: 'Client Preferences Root', category: 'identity' },\n  schema: {},\n  guideline:\n    'Binding provider for the consent opt-in section; reads both opt-in values (optinNewsLetter, savePersonalData) from the ClientPreferences identity entity (a sibling of Cart, via Query.clientPreferences) and exposes them to its Controls. Reads session state from useSession(); must be inside SessionRoot. Writes flow through $actions.identity.clientPreferencesUpdate. Wrap a NewsletterOptInControl and/or a SavePersonalDataOptInControl.',\n});\n\nexport const NewsletterOptInControlDefinition = defineComponent<NewsletterOptInControlProps>({\n  name: 'NewsletterOptInControl',\n  importPath: '@vtex/faststore/components',\n  component: NewsletterOptInControl,\n  content: NewsletterOptInControlContent,\n  requiresContext: 'client-preferences-toggle',\n  actions: { identity: ['clientPreferencesUpdate'] },\n  editor: { label: 'Newsletter Opt-In Control', category: 'identity' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n  },\n  guideline:\n    'The bound newsletter opt-in checkbox; must be a descendant of ClientPreferencesRoot. Toggling writes the optinNewsLetter preference via $actions.identity.clientPreferencesUpdate; a refused save shows the $content field genericErrorMessage. Defaults to unchecked.',\n});\n\nexport const SavePersonalDataOptInControlDefinition = defineComponent<SavePersonalDataOptInControlProps>({\n  name: 'SavePersonalDataOptInControl',\n  importPath: '@vtex/faststore/components',\n  component: SavePersonalDataOptInControl,\n  content: SavePersonalDataOptInControlContent,\n  requiresContext: 'client-preferences-toggle',\n  actions: { identity: ['clientPreferencesUpdate'] },\n  editor: { label: 'Save Personal Data Opt-In Control', category: 'identity' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n  },\n  guideline:\n    'The bound save-personal-data opt-in checkbox; must be a descendant of ClientPreferencesRoot. Toggling writes the savePersonalData preference via $actions.identity.clientPreferencesUpdate; a refused save shows the $content field genericErrorMessage. Defaults to unchecked.',\n});\n\n// ---------------------------------------------------------------------------\n// Context\n// ---------------------------------------------------------------------------\n\ntype ClientPreferencesContextValue = Readonly<{\n  /** Current value of each opt-in, seeded from the query response (null → unchecked). */\n  values: Readonly<Record<ClientPreferenceKey, boolean>>;\n  /**\n   * Records that a write for `key` is in flight and stores its returned userErrors under that key so\n   * each Control surfaces ITS OWN pending/error. The Control owns the actual dispatch (it holds\n   * `$actions`); it hands the resulting promise here for the section to track.\n   */\n  trackWrite: (key: ClientPreferenceKey, write: Promise<readonly ClientProfileUserError[]>) => void;\n  /**\n   * The fields whose writes are currently in flight. A per-key set, not a single slot: concurrent\n   * writes on different fields must each keep their own Control disabled until THEIR write settles.\n   */\n  pendingKeys: ReadonlySet<ClientPreferenceKey>;\n  /** The userErrors returned by the most recent write, keyed by the field that produced them. */\n  errorByKey: Readonly<Partial<Record<ClientPreferenceKey, readonly ClientProfileUserError[]>>>;\n  /**\n   * True when the session reports `canEditData: false` — VTEX refuses profile-data edits for an\n   * identified-but-unauthenticated claimed profile, so the Controls render disabled instead of\n   * accepting writes that are doomed server-side (mirrors the email control).\n   */\n  readOnly: boolean;\n}>;\n\nconst CLIENT_PREFERENCES_UNSET = Symbol('ClientPreferencesContextUnset');\n\nconst ClientPreferencesContext = createContext<ClientPreferencesContextValue | typeof CLIENT_PREFERENCES_UNSET>(\n  CLIENT_PREFERENCES_UNSET,\n);\n\nfunction useClientPreferencesContext(): ClientPreferencesContextValue {\n  const ctx = useContext(ClientPreferencesContext);\n  if (ctx === CLIENT_PREFERENCES_UNSET) {\n    throw new Error('A client-preferences Control must be used inside a ClientPreferencesRoot.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Root\n// ---------------------------------------------------------------------------\n\n/**\n * Renders the client-preferences section Root: reads `$data` (the `ClientPreferences` sibling entity),\n * reads `useSession()` (which also enforces the `SessionRoot` ancestor, mirroring\n * `EmailIdentificationControl`), seeds both opt-in values from the section fragment, and publishes a\n * section context exposing both values plus per-field pending/error tracking. The write itself flows\n * through the Control's `$actions.identity.clientPreferencesUpdate` (ADR-0010); this Root tracks which\n * keys are in flight and stores the returned userErrors under each key so each Control surfaces ITS OWN\n * pending/error. When the session reports `canEditData: false` (identified but unauthenticated claimed\n * profile — VTEX refuses the write server-side) every Control renders disabled with its readonly\n * `data-fs-*` attribute, mirroring `EmailIdentificationControl`.\n */\nexport function ClientPreferencesRoot({ $data: $dataProp, className, children }: ClientPreferencesRootProps) {\n  const $data = useDataOverride($dataProp);\n  // Also enforces the SessionRoot ancestor: useSession() throws when rendered outside one.\n  const { canEditData } = useSession();\n  const readOnly = !canEditData;\n\n  const optinNewsLetter = Boolean($data?.optinNewsLetter ?? false);\n  const savePersonalData = Boolean($data?.savePersonalData ?? false);\n\n  const [pendingKeys, setPendingKeys] = useState<ReadonlySet<ClientPreferenceKey>>(new Set());\n  const [errorByKey, setErrorByKey] = useState<Partial<Record<ClientPreferenceKey, readonly ClientProfileUserError[]>>>(\n    {},\n  );\n\n  const trackWrite = useCallback((key: ClientPreferenceKey, write: Promise<readonly ClientProfileUserError[]>) => {\n    // Clear the key's stale error at the start of a retry (parity with the email control clearing\n    // its serverError on a new write).\n    setErrorByKey((prev) => ({ ...prev, [key]: [] }));\n    setPendingKeys((prev) => new Set(prev).add(key));\n    void write\n      .then((userErrors) => {\n        setErrorByKey((prev) => ({ ...prev, [key]: userErrors }));\n      })\n      .finally(() => {\n        setPendingKeys((prev) => {\n          const next = new Set(prev);\n          next.delete(key);\n          return next;\n        });\n      });\n  }, []);\n\n  const values = useMemo(() => ({ optinNewsLetter, savePersonalData }) as const, [optinNewsLetter, savePersonalData]);\n\n  const contextValue = useMemo<ClientPreferencesContextValue>(\n    () => ({ values, trackWrite, pendingKeys, errorByKey, readOnly }),\n    [values, trackWrite, pendingKeys, errorByKey, readOnly],\n  );\n\n  return (\n    <ClientPreferencesContext value={contextValue}>\n      <div className={className} data-fs-client-preferences-root=\"\">\n        {children}\n      </div>\n    </ClientPreferencesContext>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Controls\n// ---------------------------------------------------------------------------\n\n/**\n * Renders one bound opt-in checkbox by inlining `Field` + `Checkbox` + `Icon` (no `CheckboxField`\n * particle). Reads ITS field's value, pending, and error from the section context and dispatches the\n * write through `$actions.identity.clientPreferencesUpdate({ [key]: value })`, handing the promise to\n * the section so the in-flight key and returned userErrors are tracked per field. The `fieldKey`,\n * `dataAttr`, `pendingAttr`, `readonlyAttr`, content type and error map are fixed by each registered\n * Control; only `label`/`className` and the `$content` message are merchant-configurable. A refusal is\n * worded by the Control's message for its code; a code the map does not know shows the Control's\n * genericErrorMessage.\n */\nfunction OptInControl({\n  fieldKey,\n  dataAttr,\n  pendingAttr,\n  readonlyAttr,\n  contentType,\n  errorFields,\n  label,\n  className,\n  $content,\n  $actions: $actionsProp,\n}: ClientPreferencesControlProps & {\n  fieldKey: ClientPreferenceKey;\n  dataAttr: string;\n  pendingAttr: string;\n  readonlyAttr: string;\n  contentType: typeof NewsletterOptInControlContent | typeof SavePersonalDataOptInControlContent;\n  errorFields: OptInErrorFields;\n  $content?: ContentValue<typeof NewsletterOptInControlContent>;\n}) {\n  const $actions = useActionsOverride($actionsProp);\n  // Both content types declare the same field, so one type serves either control's formatter.\n  const { format } = useMessageFormatter(contentType as typeof NewsletterOptInControlContent, $content);\n  const { values, trackWrite, pendingKeys, errorByKey, readOnly } = useClientPreferencesContext();\n  const fieldErrors = errorByKey[fieldKey] ?? [];\n  const value = values[fieldKey];\n  const pending = pendingKeys.has(fieldKey);\n  const disabled = pending || readOnly;\n  const [firstError] = fieldErrors;\n  const invalid = Boolean(firstError);\n\n  function handleCheckedChange(checked: boolean) {\n    const update = $actions?.identity?.clientPreferencesUpdate;\n    if (!update) return;\n    trackWrite(fieldKey, update({ [fieldKey]: checked }));\n  }\n\n  return (\n    <div\n      className={className}\n      {...{ [dataAttr]: '' }}\n      {...(pending ? { [pendingAttr]: '' } : {})}\n      {...(readOnly ? { [readonlyAttr]: '' } : {})}\n    >\n      <Field.Root invalid={invalid} disabled={disabled} data-fs-field-root=\"\">\n        <Field.Label>\n          <Checkbox.Root checked={value} onCheckedChange={handleCheckedChange} disabled={disabled}>\n            <Checkbox.Indicator>\n              <Icon name=\"checked\" />\n            </Checkbox.Indicator>\n          </Checkbox.Root>\n          {label}\n        </Field.Label>\n        {invalid && firstError ? (\n          <Field.Error match>\n            {formatErrorCode(contentType, errorFields, firstError, format, 'genericErrorMessage')}\n          </Field.Error>\n        ) : null}\n      </Field.Root>\n    </div>\n  );\n}\n\nexport function NewsletterOptInControl({ $locale, ...props }: NewsletterOptInControlProps) {\n  return (\n    <OptInControl\n      {...props}\n      contentType={NewsletterOptInControlContent}\n      errorFields={NEWSLETTER_OPT_IN_ERROR_FIELDS}\n      fieldKey=\"optinNewsLetter\"\n      dataAttr=\"data-fs-newsletter-opt-in\"\n      pendingAttr=\"data-fs-newsletter-opt-in-pending\"\n      readonlyAttr=\"data-fs-newsletter-opt-in-readonly\"\n    />\n  );\n}\n\nexport function SavePersonalDataOptInControl({ $locale, ...props }: SavePersonalDataOptInControlProps) {\n  return (\n    <OptInControl\n      {...props}\n      contentType={SavePersonalDataOptInControlContent}\n      errorFields={SAVE_PERSONAL_DATA_OPT_IN_ERROR_FIELDS}\n      fieldKey=\"savePersonalData\"\n      dataAttr=\"data-fs-save-personal-data-opt-in\"\n      pendingAttr=\"data-fs-save-personal-data-opt-in-pending\"\n      readonlyAttr=\"data-fs-save-personal-data-opt-in-readonly\"\n    />\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Namespace export\n// ---------------------------------------------------------------------------\n\nexport const ClientPreferences = {\n  Root: ClientPreferencesRoot,\n  NewsletterOptInControl,\n  SavePersonalDataOptInControl,\n};\n"],"mappings":"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"}

package/dist/matter/client-profile/client-profile.d.ts

@@ -1,3 +1,4 @@
+import { ContentValue, MessageLocaleProp } from "../../core/dist/define-content-type.js";
 import { ComponentDefinition } from "../../core/dist/define-component.js";
 import "../../core/dist/index.js";
 import { ComponentActions } from "../../sdk/actions/types.js";
@@ -23,17 +24,50 @@ export declare const ClientProfileRootDefinition: ComponentDefinition<ClientProf
  */
 export declare function ClientProfileRoot({ $data: $dataProp, className, children }: ClientProfileRootProps): import("react/jsx-runtime").JSX.Element;
 type PhoneFieldRequirement = 'mandatory' | 'optional';
-export type ClientProfilePhoneControlProps = {
-  /** Visible field label. */
-  label?: string;
+export declare const ClientProfilePhoneControlContent: {
+  readonly id: "client-profile-phone-control";
+  readonly title: "Client Profile Phone Control";
+  readonly description: "The phone field's label, its validation messages and the message for a refused save.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly label: {
+        readonly type: "string";
+        readonly title: "Label";
+        readonly format: "icu-message";
+        readonly messageSource: "Phone";
+      };
+      readonly errorInvalid: {
+        readonly type: "string";
+        readonly title: "Invalid error message";
+        readonly format: "icu-message";
+        readonly messageSource: "Invalid phone number";
+      };
+      readonly errorRequired: {
+        readonly type: "string";
+        readonly title: "Required error message";
+        readonly format: "icu-message";
+        readonly messageSource: "Phone number is required";
+      };
+      readonly genericErrorMessage: {
+        readonly type: "string";
+        readonly title: "Save failure message";
+        readonly description: "Shown for a network failure and for any refusal the shopper cannot act on.";
+        readonly format: "icu-message";
+        readonly messageSource: "Unable to save your details. Please try again.";
+      };
+    };
+  };
+};
+export type ClientProfilePhoneControlProps = MessageLocaleProp & {
   /** Selects the phone mask and validation rule. */
   country?: PhoneCountry;
   /** Controls required validation. */
   requirement?: PhoneFieldRequirement;
-  /** Error string shown when the input format is invalid. */
-  errorInvalid?: string;
-  /** Error string shown when the mandatory field is left empty. */
-  errorRequired?: string;
+  /** The visible label, the messages for an invalid format and a mandatory field left empty, and the
+   * message for a refused save. */
+  $content?: ContentValue<typeof ClientProfilePhoneControlContent>;
   className?: string;
   /** Injected by the compiler from `actions: { identity: ['clientProfileUpdate'] }`; the write surface. */
   $actions?: ComponentActions;
@@ -46,9 +80,10 @@ export declare const ClientProfilePhoneControlDefinition: ComponentDefinition<Cl
  * mirroring `EmailIdentificationControl`). While the write is in flight the field is disabled and
  * `data-fs-client-profile-phone-pending` is present so a checkout-CTA guard can block. When the
  * session reports `canEditData: false` the field renders disabled with
- * `data-fs-client-profile-phone-readonly`. Server `userErrors` are surfaced inline.
+ * `data-fs-client-profile-phone-readonly`. Server `userErrors` are surfaced inline, worded by the
+ * `$content` field for their code (genericErrorMessage for a code it does not know).
  */
-export declare function ClientProfilePhoneControl({ label, country, requirement, errorInvalid, errorRequired, className, $actions: $actionsProp }: Readonly<ClientProfilePhoneControlProps>): import("react/jsx-runtime").JSX.Element;
+export declare function ClientProfilePhoneControl({ country, requirement, $content, $locale, className, $actions: $actionsProp }: Readonly<ClientProfilePhoneControlProps>): import("react/jsx-runtime").JSX.Element;
 export declare const ClientProfile: {
   Root: typeof ClientProfileRoot;
   PhoneControl: typeof ClientProfilePhoneControl;