@vtex/faststore 0.0.6 → 0.0.8

package/dist/matter/saved-cards/saved-cards.js

@@ -4,15 +4,15 @@ import "../../core/dist/index.js";
 import { useActionsOverride } from "../../sdk/actions/actions-override-context.js";
 import { useDataOverride } from "../../sdk/data/data-override-context.js";
 import { resolveAuthoredCopy } from "../../utils/resolve-authored-copy.js";
+import { ListItemRefContext } from "../../sdk/data/list-item-ref-context.js";
 import { Fieldset } from "../../particles/fieldset/fieldset.js";
 import { RadioGroup, RadioIndicator, RadioRoot } from "../../particles/radio/radio.js";
 import { useRegisterPaymentSubmission } from "../../sdk/payment/submission-registry.js";
 import { PAYMENT_NETWORK_ERROR_CODE } from "../../sdk/payment/operations.js";
 import { usePayment } from "../payment/payment.js";
 import { SECURITY_CODE_MASK_STYLE, isSecurityCodeComplete } from "../../sdk/payment/security-code-mask.js";
-import { ListItemRefContext } from "../../sdk/data/list-item-ref-context.js";
 import { createContext, useCallback, useContext, useId, useRef, useState } from "react";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 //#region src/matter/saved-cards/saved-cards.tsx
 /**
 * Pick a saved card and enter only the CVV (specs/saved-cards.md, T12 of the Credit Card epic;
@@ -123,6 +123,7 @@ const SavedCardCvvFieldDefinition = defineComponent({
 	component: SavedCardCvvField,
 	requiresContext: "saved-card-data",
 	actions: { payment: ["sendPayments"] },
+	hardened: true,
 	editor: {
 		label: "Saved Card CVV Field",
 		category: "commerce"
@@ -162,7 +163,8 @@ function resolveEffectiveSelectedAccountId(selectedAccountId, draftPath) {
 }
 function SavedCards({ $data: $dataProp, legend, className, children, ...props }) {
 	const $data = useDataOverride($dataProp);
-	const { selectedAccountId, selectMethod, selectionError, draft, placing, cardPaymentCollapsed } = usePayment();
+	const { selectedAccountId, selectMethod, selectionError, draft, placing: placingNow, attempt, cardPaymentCollapsed } = usePayment();
+	const placing = placingNow || attempt?.phase === "sent" || attempt?.phase === "unresolved";
 	const loading = $data == null;
 	const savedCards = $data?.savedCards ?? [];
 	const effectiveSelectedAccountId = resolveEffectiveSelectedAccountId(selectedAccountId, draft.path);
@@ -324,17 +326,27 @@ function SavedCardCvvInput({ accountId, bin, securityCodeLabel, securityCodeDesc
 	}, [cvv]);
 	const submit = useCallback(async (transaction) => {
 		const refusals = checkCvv();
-		if (refusals.length > 0) return refusals;
-		if (!sendPayments) return [MISSING_ACTION_ERROR];
-		return sendPayments({
-			transaction,
-			card: {
-				kind: "saved",
-				accountId,
-				bin,
-				securityCode: cvv
-			}
-		});
+		if (refusals.length > 0) return {
+			reachedGateway: false,
+			userErrors: refusals
+		};
+		try {
+			if (!sendPayments) return {
+				reachedGateway: false,
+				userErrors: [MISSING_ACTION_ERROR]
+			};
+			return await sendPayments({
+				transaction,
+				card: {
+					kind: "saved",
+					accountId,
+					bin,
+					securityCode: cvv
+				}
+			});
+		} finally {
+			setCvv("");
+		}
 	}, [
 		checkCvv,
 		sendPayments,
@@ -348,7 +360,7 @@ function SavedCardCvvInput({ accountId, bin, securityCodeLabel, securityCodeDesc
 		...props.style,
 		...SECURITY_CODE_MASK_STYLE
 	} : props.style;
-	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("input", {
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("input", {
 		...props,
 		ref: setInputRef,
 		type: "text",

package/dist/matter/saved-cards/saved-cards.js.map

@@ -1 +1 @@
-{"version":3,"file":"saved-cards.js","names":[],"sources":["../../../src/matter/saved-cards/saved-cards.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  useId,\n  useRef,\n  useState,\n} from 'react';\nimport { Fieldset } from '../../particles/fieldset/fieldset.js';\nimport { RadioGroup, RadioIndicator, RadioRoot } from '../../particles/radio/radio.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 { ListItemRefContext } from '../../sdk/data/list-item-ref-context.js';\nimport { PAYMENT_NETWORK_ERROR_CODE, type PaymentUserError } from '../../sdk/payment/operations.js';\nimport { isSecurityCodeComplete, SECURITY_CODE_MASK_STYLE } from '../../sdk/payment/security-code-mask.js';\nimport {\n  type PaymentPreflightCheck,\n  type PaymentSubmission,\n  useRegisterPaymentSubmission,\n} from '../../sdk/payment/submission-registry.js';\nimport { resolveAuthoredCopy } from '../../utils/resolve-authored-copy.js';\nimport { usePayment } from '../payment/payment.js';\n\n/**\n * Pick a saved card and enter only the CVV (specs/saved-cards.md, T12 of the Credit Card epic;\n * docs/features/credit-card/rfc.md § D7). Three components, split by data-fetch role rather than by\n * visual grouping (ADR-0012 Option B, per `SavedCard`'s own schema doc comment):\n *\n * - `SavedCards` — the list root. Owns the minimal `{ id, accountId, methodId }` selection needed to\n *   iterate and to dispatch selection; publishes each row's entity ref via `ListItemRefContext`,\n *   mirroring `CartList`.\n * - `SavedCardOption` — the per-row template. Independently subscribes to its own `SavedCard:<id>`\n *   cache entity through the shipped `reactive-list-item` runtime, mirroring `CartItemRoot`.\n * - `SavedCardCvvField` — the one PCI-bearing, action-dispatching leaf. Declares no `fetchStrategy` of\n *   its own; it reads its row through `SavedCardOption`'s plain context, mirroring `CartItemRemove`'s\n *   split from `CartItemRoot` (spec Decision 1).\n *\n * The submission continuation is the PCI-critical core (epic § \"The card-data submission channel\"):\n * `SavedCardCvvField` (via its internal `SavedCardCvvInput`) registers the `'saved-card'` continuation\n * on T5's submission registry, closing over the re-entered CVV and the account reference, and calls\n * `$actions.payment.sendPayments` itself. T13's `usePlaceOrder` resolves and invokes it; this module\n * never returns the CVV, only `userErrors`.\n *\n * Selecting a row dispatches `usePayment().selectMethod({ methodId, accountId, bin })` — the\n * `bin` is this row's own projected BIN, never `usePayment().draft.bin`. The epic's and the RFC's\n * own text says the saved-card continuation closes over \"the account id and BIN\", which conflates\n * two different calls: `paymentMethodSelect` (this dispatch) sends the saved card's own BIN alongside\n * `accountId` — a `bin` that does not match the saved card's own BIN is rejected with\n * `MISMATCHED_BIN_FOR_SAVED_CARD`, verified against\n * `apps/storefront-api-core/src/graphql/modules/checkout/index.ts`. The gateway send (inside\n * `SavedCardCvvInput`, below) legitimately carries both, because it is a different wire contract\n * (spec Decision 2 has the full correction).\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragments — raw template literals, matching the `payment.tsx` sibling: the codegen\n// `documents` glob does not scan `src/matter/saved-cards*`. Both fragments drill the identical\n// `payment.savedCards` path and merge at compile time (ADR-0011/ADR-0012); `data-component-contract.\n// test.ts` validates each against the real schema.\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment SavedCardsListData on Query {\n    payment {\n      __typename\n      id\n      savedCards {\n        __typename\n        id\n        accountId\n        methodId\n        bin\n      }\n    }\n  }\n`;\n\nconst optionFragment = /* GraphQL */ `\n  fragment SavedCardOptionData on Query {\n    payment {\n      savedCards {\n        __typename\n        id\n        accountId\n        methodId\n        network\n        lastFourDigits\n        bin\n        label\n        expired\n        cvvRequired\n      }\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** The minimal per-row identifiers `SavedCards` needs to iterate and to dispatch selection. */\nexport type SavedCardsListEntry = Readonly<{\n  id: string;\n  accountId: string;\n  methodId: string;\n  bin: string;\n}>;\n\nexport type SavedCardsData = {\n  savedCards?: readonly SavedCardsListEntry[];\n} | null;\n\nexport type SavedCardsProps = ComponentPropsWithRef<'div'> & {\n  /** Unwrapped `payment` value from the reactive runtime (arity-1 fragment, ADR-0015); `null` until resolved. */\n  $data?: SavedCardsData;\n  /** The per-row template, typically one `SavedCardOption`, repeated once per saved card. */\n  children?: ReactNode;\n  /**\n   * The radio group's accessible name, rendered as a visible `Fieldset.Legend` (T38, Decision 1).\n   * Resolved through `resolveAuthoredCopy`: an authored empty or whitespace-only string falls back to\n   * the default rather than rendering a nameless group.\n   */\n  legend?: string;\n};\n\n/** The full per-row slice `SavedCardOption` independently resolves via `reactive-list-item`. */\nexport type SavedCardOptionSlice = Readonly<{\n  accountId: string;\n  methodId: string;\n  network: string;\n  lastFourDigits: string;\n  bin: string;\n  label: string | null;\n  expired: boolean;\n  cvvRequired: boolean;\n}>;\n\nexport type SavedCardOptionProps = ComponentPropsWithRef<'div'> & {\n  /** Per-row slice from the reactive-list-item runtime; injected/overridden by the wrapper, or passed directly in tests. */\n  $data?: SavedCardOptionSlice | null;\n  /** Typically a `SavedCardCvvField`. */\n  children?: ReactNode;\n};\n\nexport type SavedCardCvvFieldProps = ComponentPropsWithRef<'input'> & {\n  /** Compiler-injected action surface; carries `payment.sendPayments`. */\n  $actions?: ComponentActions;\n  /**\n   * Accessible name for the CVV input. No visible `<label>` renders (Accessibility Contract), so this\n   * is the input's only accessible name — authorable rather than a hardcoded English string.\n   */\n  securityCodeLabel?: string;\n  /**\n   * Helper copy rendered as a sibling `<p>` and linked to the input via `aria-describedby` (this\n   * component's root is the input itself, so there is no `Field.Root` to host a `Field.Description` —\n   * saved-cards.md Decision 3). An empty string renders nothing. Copy configuration only — never the\n   * security code itself.\n   */\n  securityCodeDescription?: string;\n};\n\n// ---------------------------------------------------------------------------\n// Saved-card-data context — provided by SavedCardOption, read only by SavedCardCvvField. A plain\n// React context, not a data-fetch strategy: SavedCardCvvField has no fragment of its own (Decision 1).\n// ---------------------------------------------------------------------------\n\nconst SavedCardDataContext = createContext<SavedCardOptionSlice | null>(null);\n\nfunction useSavedCardData(): SavedCardOptionSlice {\n  const data = useContext(SavedCardDataContext);\n  if (!data) {\n    throw new Error('SavedCardCvvField must be used inside a <SavedCardOption> subtree.');\n  }\n  return data;\n}\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const SavedCardsDefinition = defineComponent<SavedCardsProps>({\n  name: 'SavedCards',\n  importPath: '@vtex/faststore/components',\n  component: SavedCards,\n  fragment,\n  fetchStrategy: 'reactive',\n  requiresContext: 'payment',\n  providesContext: 'saved-card',\n  editor: { label: 'Saved Cards', category: 'commerce' },\n  schema: {\n    // T38: an inline literal, never an identifier — the native catalog builder extracts `schema`\n    // statically and silently drops an identifier-valued default (INV-8).\n    legend: { type: 'string', default: 'Saved cards', label: 'Legend' },\n  },\n  guideline:\n    'Radio list of the shopper\\'s saved cards (network, last four, label); expired cards render present but disabled, never selectable. Place a SavedCardOption inside as the per-card template, itself wrapping a SavedCardCvvField so the shopper can complete payment with a stored card — omitting the CVV field means a shopper can select a card but never pay with it. Picking a row dispatches the payment method selection by methodId and accountId only, never a card number or BIN, plus the inline selection error (role=\"alert\") if the server rejects it. \"Use a new card\" is CardEntry composed as a sibling, not a control inside this list. Renders one container div and no chrome of its own; always carries a loading/empty/ready state hook. Must be inside a PaymentSectionRoot or PaymentSectionController. See saved-cards.md.',\n});\n\nexport const SavedCardOptionDefinition = defineComponent<SavedCardOptionProps>({\n  name: 'SavedCardOption',\n  importPath: '@vtex/faststore/components',\n  component: SavedCardOption,\n  fragment: optionFragment,\n  fetchStrategy: 'reactive-list-item',\n  requiresContext: 'saved-card',\n  providesContext: 'saved-card-data',\n  editor: { label: 'Saved Card Option', category: 'commerce' },\n  schema: {},\n  guideline:\n    'One saved card as a radio row: network, masked last four, and its label when set; disabled when expired. Place a SavedCardCvvField inside so the CVV appears once this row is selected. Must be inside SavedCards.',\n});\n\nexport const SavedCardCvvFieldDefinition = defineComponent<SavedCardCvvFieldProps>({\n  name: 'SavedCardCvvField',\n  importPath: '@vtex/faststore/components',\n  component: SavedCardCvvField,\n  requiresContext: 'saved-card-data',\n  actions: { payment: ['sendPayments'] },\n  editor: { label: 'Saved Card CVV Field', category: 'commerce' },\n  schema: {\n    securityCodeLabel: { type: 'string', default: 'Security code', label: 'Security code label' },\n    // en-US, per requirement 12.27's own quoted copy (spec mask-the-security-code-field-and.md,\n    // OQ-1 Option B) — matches this component's existing en-US securityCodeLabel default.\n    securityCodeDescription: {\n      type: 'string',\n      default: 'The 3-4 digit number on your card',\n      label: 'Security code description',\n    },\n  },\n  guideline:\n    \"The CVV re-entry field for its saved card row; renders nothing until that row is selected and requires a CVV. Registers the direct-to-gateway submission for the saved-card path on selection — the CVV never transits our backend, only the gateway leg's userErrors return. Must be inside SavedCardOption.\",\n});\n\n// ---------------------------------------------------------------------------\n// Implementations\n// ---------------------------------------------------------------------------\n\n/** Mirrors `PaymentMethodList`'s own state hook, so an empty or loading region stays swatch-targetable. */\nfunction savedCardsState({ loading, count }: { loading: boolean; count: number }): 'loading' | 'empty' | 'ready' {\n  if (loading) return 'loading';\n  if (count === 0) return 'empty';\n  return 'ready';\n}\n\n/**\n * The account a row should treat as \"the current selection.\" `selectedAccountId` is server state that\n * `selectNewCard()` never clears — only `draft.path` flips to `'new-card'` (`use-payment-method-\n * selection.ts`) — so reading `selectedAccountId` alone leaves the previously picked row wedged\n * checked, with its CVV field still mounted and registered, after the shopper picks \"use a new card\"\n * instead. Every read site in this module goes through this one function — the radio group's own\n * `value`, a row's `-selected` state, and the CVV field's visibility gate — so the three can never\n * drift out of sync with each other. Reads only `draft.path`, never `draft.bin`: that stays a fully\n * separate concern (Decision 2) that no call site in this module touches.\n */\nfunction resolveEffectiveSelectedAccountId(selectedAccountId: string | null, draftPath: string | null): string | null {\n  return draftPath === 'new-card' ? null : selectedAccountId;\n}\n\nexport function SavedCards({ $data: $dataProp, legend, className, children, ...props }: SavedCardsProps) {\n  const $data = useDataOverride($dataProp);\n  // `draft` here only for `.path`, to resolve the effective selection below — never `.bin`. The\n  // dispatch in handleValueChange still never reads `draft` at all; see its own comment.\n  const { selectedAccountId, selectMethod, selectionError, draft, placing, cardPaymentCollapsed } = usePayment();\n  const loading = $data == null;\n  const savedCards = $data?.savedCards ?? [];\n  const effectiveSelectedAccountId = resolveEffectiveSelectedAccountId(selectedAccountId, draft.path);\n\n  const handleValueChange = useCallback(\n    (accountId: string) => {\n      const card = savedCards.find((entry) => entry.accountId === accountId);\n      if (!card) return;\n      // methodId, accountId, and this row's own bin — from this list's own read model, never\n      // usePayment().draft.bin. draft.bin can be non-null on the saved-card path too (e.g.\n      // Installments calling setDraftBin for its own BIN-keyed lookup; use-payment-method-selection.ts\n      // does not clear it on this transition), but the bin sent here must be the saved card's own\n      // so paymentMethodSelect can persist a BIN-precise selection. A bin that does not match the\n      // saved card's own BIN is rejected with MISMATCHED_BIN_FOR_SAVED_CARD (spec Decision 2). The\n      // gateway send (SavedCardCvvInput, below) is the different call that legitimately carries both\n      // bin and accountId, reading bin from this row's own resolved slice, never the draft.\n      selectMethod({\n        methodId: card.methodId,\n        accountId: card.accountId,\n        ...(card.bin ? { bin: card.bin } : {}),\n      });\n    },\n    [savedCards, selectMethod],\n  );\n\n  // T191 (FR-7, Decision 3): nothing renders while the card payment is collapsed — the card option brings\n  // the list back. Returned after the last hook, so this instance stays mounted.\n  if (cardPaymentCollapsed) return null;\n\n  return (\n    <div\n      {...props}\n      className={className}\n      inert={placing}\n      aria-disabled={placing || undefined}\n      data-fs-saved-cards=\"\"\n      data-fs-saved-cards-state={savedCardsState({ loading, count: savedCards.length })}\n      {...(placing ? { 'data-fs-saved-cards-placing': '' } : {})}\n    >\n      {selectionError ? (\n        <div role=\"alert\" data-fs-saved-cards-error=\"\">\n          {selectionError}\n        </div>\n      ) : null}\n      {savedCards.length > 0 ? (\n        // T38, Decision 1: Fieldset.Root + Fieldset.Legend, exactly what card-entry.tsx:1101-1112\n        // already ships — Base UI propagates the legend's id as aria-labelledby onto the descendant\n        // RadioGroup, so this one wrapper names both the fieldset and the radiogroup (measured).\n        <Fieldset.Root data-fs-saved-cards-fieldset=\"\">\n          <Fieldset.Legend>{resolveAuthoredCopy(legend, 'Saved cards')}</Fieldset.Legend>\n          <RadioGroup value={effectiveSelectedAccountId ?? ''} onValueChange={handleValueChange}>\n            {savedCards.map((card) => (\n              <ListItemRefContext\n                key={card.id}\n                // No fallback slice: this list's own fragment selects only { id, accountId, methodId }\n                // (Decision 3), so it has no complete row to fall back to. An incomplete cache slice\n                // should render nothing until it resolves, not a partial, silently-wrong row.\n                value={{ __typename: 'SavedCard', id: card.id, fallbackData: undefined }}\n              >\n                {children}\n              </ListItemRefContext>\n            ))}\n          </RadioGroup>\n        </Fieldset.Root>\n      ) : null}\n    </div>\n  );\n}\n\nexport function SavedCardOption({ $data: $dataProp, className, children, ...props }: SavedCardOptionProps) {\n  // Delivery-agnostic: the slice arrives through the DataOverrideContext seam the reactive-list-item\n  // wrapper publishes (or via $data in tests); this component calls no data hook of its own.\n  const slice = useDataOverride<SavedCardOptionSlice | null | undefined>($dataProp) ?? null;\n  const { selectedAccountId, draft } = usePayment();\n\n  if (!slice) return null;\n\n  // Path-aware, not just account-aware — see resolveEffectiveSelectedAccountId's own comment: without\n  // this, a row that was picked before \"use a new card\" stays marked selected forever.\n  const isSelected = slice.accountId === resolveEffectiveSelectedAccountId(selectedAccountId, draft.path);\n\n  return (\n    <SavedCardDataContext value={slice}>\n      <div\n        {...props}\n        className={className}\n        data-fs-saved-card-option=\"\"\n        {...(isSelected ? { 'data-fs-saved-card-option-selected': '' } : {})}\n        {...(slice.expired ? { 'data-fs-saved-card-option-expired': '' } : {})}\n      >\n        <RadioRoot value={slice.accountId} disabled={slice.expired}>\n          <RadioIndicator data-fs-saved-card-option-indicator=\"\" />\n          <span data-fs-saved-card-option-network=\"\">{slice.network}</span>\n          <span data-fs-saved-card-option-last-four=\"\">{`•••• ${slice.lastFourDigits}`}</span>\n          {slice.label ? <span data-fs-saved-card-option-label=\"\">{slice.label}</span> : null}\n        </RadioRoot>\n        {children}\n      </div>\n    </SavedCardDataContext>\n  );\n}\n\nconst MISSING_ACTION_ERROR: PaymentUserError = {\n  code: PAYMENT_NETWORK_ERROR_CODE,\n  message: 'Unable to complete the request. Please try again.',\n};\n\n/**\n * The saved-card path's own client-synthesized refusal (T27, specs/place-order-preflight-card-\n * validation.md FR-11/FR-12; Decision 8). Distinct from `card-entry`'s `INVALID_CARD_DATA` (a\n * different path, a different set of fields, and importing it here would be a matter → matter\n * dependency) and from the gateway's own codes.\n *\n * Never name this constant, or its string value, inside `sdk/payment/use-place-order.ts`: it contains\n * `security` and would fail `CARD_FIELD_PATTERN`. The pre-flight only ever handles the opaque\n * `PaymentUserError` (spec NFR-1, Risk R9).\n */\nexport const SAVED_CARD_INVALID_SECURITY_CODE = 'INVALID_SECURITY_CODE';\n\nconst INVALID_SECURITY_CODE_ERROR: PaymentUserError = {\n  code: SAVED_CARD_INVALID_SECURITY_CODE,\n  message: 'Enter a valid security code before placing the order.',\n};\n\n/** VTEX's own CVV upper bound across the networks this codebase's masks cover (Decision 4). */\nconst CVV_MAX_LENGTH = 4;\n\nfunction sanitizeCvv(value: string): string {\n  return value.replace(/\\D/g, '').slice(0, CVV_MAX_LENGTH);\n}\n\n/**\n * Three or four digits (T27, FR-11). `sanitizeCvv` already strips non-digits and caps at\n * `CVV_MAX_LENGTH`, so the only rule left is the floor — and three-or-four is `card-entry`'s own\n * fallback for a method that declares no `cvvRegex` (its `isValidCvv`, `/^\\d{3,4}$/`). Requiredness is\n * not checked here: `SavedCardCvvInput` renders only when the row is selected and `cvvRequired` is\n * true, so its presence *is* the requiredness signal.\n */\nconst SAVED_CARD_CVV_PATTERN = /^\\d{3,4}$/;\n\n/**\n * The length at which this field's security code counts as fully typed, and the mask engages (T173,\n * specs/mask-the-cvv-only-once-it.md, FR-3). Three — the floor of `SAVED_CARD_CVV_PATTERN` above,\n * for the same reason that pattern accepts either length: a saved card carries no per-network CVV\n * length. Its slice exposes a display `network` string, not a `cvvMask`, so nothing here tells a\n * 3-digit network apart from Amex's 4 the way `CardEntry` can, and inferring one from the display\n * name would hardcode a network table this package deliberately does not own.\n *\n * Masking at the floor is the side to err on: a complete code is never left legible on either kind\n * of card, and a 4-digit code is simply already masked when its last digit arrives.\n */\nconst SAVED_CARD_CVV_COMPLETE_LENGTH = 3;\n\ntype SavedCardCvvInputProps = ComponentPropsWithRef<'input'> & {\n  /** `SavedCard.accountId` from this row's own resolved slice — never `usePayment().draft`. */\n  accountId: string;\n  /**\n   * `SavedCard.bin` from this row's own resolved slice — the one this row is actually being paid\n   * with. Deliberately **not** `usePayment().draft.bin`: that field can be populated on the\n   * saved-card path too (e.g. Installments calling `setDraftBin` for its own BIN-keyed lookup;\n   * `use-payment-method-selection.ts` does not clear it on this transition), so it can carry a\n   * different card's BIN, or a stale one, at the moment this continuation runs. Forwarding it here\n   * instead of the row's own field would be the same class of bug Decision 2 already closed for the\n   * `selectMethod` dispatch — undetectable by type-checking, since both are plain `string`.\n   */\n  bin: string;\n  /** Accessible name applied verbatim as `aria-label` — see `SavedCardCvvFieldProps`'s own doc comment. */\n  securityCodeLabel: string;\n  /** Helper copy rendered as a sibling `<p>` — see `SavedCardCvvFieldProps`'s own doc comment. Threaded\n   * through exactly like `securityCodeLabel`. An empty string renders nothing. */\n  securityCodeDescription: string;\n  $actions?: ComponentActions;\n};\n\n/** Merges a caller-forwarded `aria-describedby` (from `...props`) with the description `<p>`'s own\n * id, rather than clobbering it — the accessibility wiring `Field.Root` would otherwise provide for\n * free (saved-cards.md Decision 3). */\nfunction mergeDescribedBy(existing: string | undefined, id: string): string {\n  return existing ? `${existing} ${id}` : id;\n}\n\n/**\n * The stateful, registering half of the CVV field — split out from `SavedCardCvvField` so this row's\n * conditional visibility never skips a hook call (spec Decision 5). This component mounts wholesale\n * when its row is selected and requires a CVV, and unmounts wholesale otherwise, so its own hooks\n * always run the same number of times across its own lifetime; only its *presence* is conditional,\n * decided by its caller.\n */\nfunction SavedCardCvvInput({\n  accountId,\n  bin,\n  securityCodeLabel,\n  securityCodeDescription,\n  $actions,\n  ref: forwardedRef,\n  ...props\n}: SavedCardCvvInputProps) {\n  const [cvv, setCvv] = useState('');\n  const inputRef = useRef<HTMLInputElement>(null);\n  const sendPayments = $actions?.payment?.sendPayments;\n  const descriptionId = useId();\n\n  // Attaches both this component's own ref (needed to focus the field on refusal, in checkCvv below)\n  // and whatever ref a caller already forwarded onto SavedCardCvvField/SavedCardCvvInput — `props`\n  // spreads onto the element below and `SavedCardCvvInputProps` is `ComponentPropsWithRef<'input'>`, so\n  // writing `ref={inputRef}` after the spread would silently drop a caller-forwarded ref instead.\n  const setInputRef = useCallback(\n    (node: HTMLInputElement | null) => {\n      inputRef.current = node;\n\n      if (typeof forwardedRef !== 'function') {\n        if (forwardedRef) forwardedRef.current = node;\n        return;\n      }\n\n      // React 19: a ref callback may itself return a cleanup function instead of being re-invoked\n      // with `null` on detach. Preserve whichever form the caller used — never call a React-19\n      // cleanup-style ref with `null`, a value that form is documented never to receive (fix pass,\n      // review F2). A caller using the legacy form (no returned cleanup) keeps today's behaviour:\n      // this callback returns nothing either, so React re-invokes it with `null` on detach, which\n      // falls into this same branch and calls `forwardedRef(null)`, exactly as before.\n      const cleanup = forwardedRef(node);\n      if (typeof cleanup === 'function') {\n        return () => {\n          inputRef.current = null;\n          cleanup();\n        };\n      }\n      return;\n    },\n    [forwardedRef],\n  );\n\n  // The saved-card check (T27, FR-11/FR-12; Decision 8). Three-or-four digits — see\n  // SAVED_CARD_CVV_PATTERN's own doc comment for why nothing narrower is checkable and nothing wider\n  // is safe. The only field on this path, so there is no ordering rule and no inline error node to\n  // fill (FR-12) — the message reaches the shopper through PlaceOrder's existing role=\"alert\".\n  const checkCvv = useCallback<PaymentPreflightCheck>(() => {\n    if (SAVED_CARD_CVV_PATTERN.test(cvv)) return [];\n    inputRef.current?.focus();\n    return [INVALID_SECURITY_CODE_ERROR];\n  }, [cvv]);\n\n  const submit = useCallback<PaymentSubmission>(\n    async (transaction) => {\n      // Same function the pre-flight calls (FR-3, applied to this path) — the two moments cannot\n      // diverge here either.\n      const refusals = checkCvv();\n      if (refusals.length > 0) return refusals;\n      if (!sendPayments) return [MISSING_ACTION_ERROR];\n      // `bin` here is always the `accountId`/`bin` pair from this row's own props — see their doc\n      // comments above for why `usePayment().draft.bin` must never substitute for either.\n      return sendPayments({ transaction, card: { kind: 'saved', accountId, bin, securityCode: cvv } });\n    },\n    [checkCvv, sendPayments, accountId, bin, cvv],\n  );\n\n  useRegisterPaymentSubmission('saved-card', submit, checkCvv);\n\n  // Merges with a caller-forwarded aria-describedby rather than clobbering it — mirrors the ref\n  // merge above (setInputRef) for the same \"don't drop what a caller already passed\" reason.\n  const ariaDescribedBy = securityCodeDescription\n    ? mergeDescribedBy(props['aria-describedby'], descriptionId)\n    : props['aria-describedby'];\n\n  // T101 — the mask merges *over* a caller-forwarded style, inverted from this repo's usual\n  // `...props.style`-last idiom (cart-item.tsx, product-list.tsx): deliberately, so a caller can\n  // never remove the security-code mask. See security-code-mask.ts.\n  //\n  // T173 — that merge now happens from the keystroke that completes the code, not from the first\n  // one, so a shopper can read back what they typed while they type it. Below the trigger the\n  // caller's own style passes through untouched, which is the same thing it did before this field\n  // ever had a mask; the guarantee above is about what a caller cannot do once the code is complete.\n  const inputStyle = isSecurityCodeComplete(cvv, SAVED_CARD_CVV_COMPLETE_LENGTH)\n    ? { ...props.style, ...SECURITY_CODE_MASK_STYLE }\n    : props.style;\n\n  return (\n    <>\n      <input\n        {...props}\n        ref={setInputRef}\n        type=\"text\"\n        inputMode=\"numeric\"\n        autoComplete=\"off\"\n        aria-label={securityCodeLabel}\n        aria-describedby={ariaDescribedBy}\n        value={cvv}\n        onChange={(event) => setCvv(sanitizeCvv(event.target.value))}\n        data-fs-saved-card-cvv-field=\"\"\n        style={inputStyle}\n      />\n      {securityCodeDescription ? (\n        <p id={descriptionId} data-fs-saved-card-cvv-description=\"\">\n          {securityCodeDescription}\n        </p>\n      ) : null}\n    </>\n  );\n}\n\nexport function SavedCardCvvField({\n  $actions: $actionsProp,\n  securityCodeLabel = 'Security code',\n  securityCodeDescription = 'The 3-4 digit number on your card',\n  className,\n  ...props\n}: SavedCardCvvFieldProps) {\n  const $actions = useActionsOverride($actionsProp);\n  const { accountId, bin, cvvRequired } = useSavedCardData();\n  const { selectedAccountId, draft } = usePayment();\n\n  // Path-aware, matching SavedCardOption's own isSelected — otherwise this field stays mounted and\n  // registered after \"use a new card\", with selectedAccountId still equal to this row's own accountId.\n  if (accountId !== resolveEffectiveSelectedAccountId(selectedAccountId, draft.path) || !cvvRequired) {\n    return null;\n  }\n\n  return (\n    <SavedCardCvvInput\n      {...props}\n      className={className}\n      accountId={accountId}\n      bin={bin}\n      securityCodeLabel={securityCodeLabel}\n      securityCodeDescription={securityCodeDescription}\n      $actions={$actions}\n    />\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"saved-cards.js","names":[],"sources":["../../../src/matter/saved-cards/saved-cards.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  useId,\n  useRef,\n  useState,\n} from 'react';\nimport { Fieldset } from '../../particles/fieldset/fieldset.js';\nimport { RadioGroup, RadioIndicator, RadioRoot } from '../../particles/radio/radio.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 { ListItemRefContext } from '../../sdk/data/list-item-ref-context.js';\nimport { PAYMENT_NETWORK_ERROR_CODE, type PaymentUserError } from '../../sdk/payment/operations.js';\nimport { isSecurityCodeComplete, SECURITY_CODE_MASK_STYLE } from '../../sdk/payment/security-code-mask.js';\nimport {\n  type PaymentPreflightCheck,\n  type PaymentSubmission,\n  useRegisterPaymentSubmission,\n} from '../../sdk/payment/submission-registry.js';\nimport { resolveAuthoredCopy } from '../../utils/resolve-authored-copy.js';\nimport { usePayment } from '../payment/payment.js';\n\n/**\n * Pick a saved card and enter only the CVV (specs/saved-cards.md, T12 of the Credit Card epic;\n * docs/features/credit-card/rfc.md § D7). Three components, split by data-fetch role rather than by\n * visual grouping (ADR-0012 Option B, per `SavedCard`'s own schema doc comment):\n *\n * - `SavedCards` — the list root. Owns the minimal `{ id, accountId, methodId }` selection needed to\n *   iterate and to dispatch selection; publishes each row's entity ref via `ListItemRefContext`,\n *   mirroring `CartList`.\n * - `SavedCardOption` — the per-row template. Independently subscribes to its own `SavedCard:<id>`\n *   cache entity through the shipped `reactive-list-item` runtime, mirroring `CartItemRoot`.\n * - `SavedCardCvvField` — the one PCI-bearing, action-dispatching leaf. Declares no `fetchStrategy` of\n *   its own; it reads its row through `SavedCardOption`'s plain context, mirroring `CartItemRemove`'s\n *   split from `CartItemRoot` (spec Decision 1).\n *\n * The submission continuation is the PCI-critical core (epic § \"The card-data submission channel\"):\n * `SavedCardCvvField` (via its internal `SavedCardCvvInput`) registers the `'saved-card'` continuation\n * on T5's submission registry, closing over the re-entered CVV and the account reference, and calls\n * `$actions.payment.sendPayments` itself. T13's `usePlaceOrder` resolves and invokes it; this module\n * never returns the CVV, only `userErrors`.\n *\n * Selecting a row dispatches `usePayment().selectMethod({ methodId, accountId, bin })` — the\n * `bin` is this row's own projected BIN, never `usePayment().draft.bin`. The epic's and the RFC's\n * own text says the saved-card continuation closes over \"the account id and BIN\", which conflates\n * two different calls: `paymentMethodSelect` (this dispatch) sends the saved card's own BIN alongside\n * `accountId` — a `bin` that does not match the saved card's own BIN is rejected with\n * `MISMATCHED_BIN_FOR_SAVED_CARD`, verified against\n * `apps/storefront-api-core/src/graphql/modules/checkout/index.ts`. The gateway send (inside\n * `SavedCardCvvInput`, below) legitimately carries both, because it is a different wire contract\n * (spec Decision 2 has the full correction).\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragments — raw template literals, matching the `payment.tsx` sibling: the codegen\n// `documents` glob does not scan `src/matter/saved-cards*`. Both fragments drill the identical\n// `payment.savedCards` path and merge at compile time (ADR-0011/ADR-0012); `data-component-contract.\n// test.ts` validates each against the real schema.\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment SavedCardsListData on Query {\n    payment {\n      __typename\n      id\n      savedCards {\n        __typename\n        id\n        accountId\n        methodId\n        bin\n      }\n    }\n  }\n`;\n\nconst optionFragment = /* GraphQL */ `\n  fragment SavedCardOptionData on Query {\n    payment {\n      savedCards {\n        __typename\n        id\n        accountId\n        methodId\n        network\n        lastFourDigits\n        bin\n        label\n        expired\n        cvvRequired\n      }\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** The minimal per-row identifiers `SavedCards` needs to iterate and to dispatch selection. */\nexport type SavedCardsListEntry = Readonly<{\n  id: string;\n  accountId: string;\n  methodId: string;\n  bin: string;\n}>;\n\nexport type SavedCardsData = {\n  savedCards?: readonly SavedCardsListEntry[];\n} | null;\n\nexport type SavedCardsProps = ComponentPropsWithRef<'div'> & {\n  /** Unwrapped `payment` value from the reactive runtime (arity-1 fragment, ADR-0015); `null` until resolved. */\n  $data?: SavedCardsData;\n  /** The per-row template, typically one `SavedCardOption`, repeated once per saved card. */\n  children?: ReactNode;\n  /**\n   * The radio group's accessible name, rendered as a visible `Fieldset.Legend` (T38, Decision 1).\n   * Resolved through `resolveAuthoredCopy`: an authored empty or whitespace-only string falls back to\n   * the default rather than rendering a nameless group.\n   */\n  legend?: string;\n};\n\n/** The full per-row slice `SavedCardOption` independently resolves via `reactive-list-item`. */\nexport type SavedCardOptionSlice = Readonly<{\n  accountId: string;\n  methodId: string;\n  network: string;\n  lastFourDigits: string;\n  bin: string;\n  label: string | null;\n  expired: boolean;\n  cvvRequired: boolean;\n}>;\n\nexport type SavedCardOptionProps = ComponentPropsWithRef<'div'> & {\n  /** Per-row slice from the reactive-list-item runtime; injected/overridden by the wrapper, or passed directly in tests. */\n  $data?: SavedCardOptionSlice | null;\n  /** Typically a `SavedCardCvvField`. */\n  children?: ReactNode;\n};\n\nexport type SavedCardCvvFieldProps = ComponentPropsWithRef<'input'> & {\n  /** Compiler-injected action surface; carries `payment.sendPayments`. */\n  $actions?: ComponentActions;\n  /**\n   * Accessible name for the CVV input. No visible `<label>` renders (Accessibility Contract), so this\n   * is the input's only accessible name — authorable rather than a hardcoded English string.\n   */\n  securityCodeLabel?: string;\n  /**\n   * Helper copy rendered as a sibling `<p>` and linked to the input via `aria-describedby` (this\n   * component's root is the input itself, so there is no `Field.Root` to host a `Field.Description` —\n   * saved-cards.md Decision 3). An empty string renders nothing. Copy configuration only — never the\n   * security code itself.\n   */\n  securityCodeDescription?: string;\n};\n\n// ---------------------------------------------------------------------------\n// Saved-card-data context — provided by SavedCardOption, read only by SavedCardCvvField. A plain\n// React context, not a data-fetch strategy: SavedCardCvvField has no fragment of its own (Decision 1).\n// ---------------------------------------------------------------------------\n\nconst SavedCardDataContext = createContext<SavedCardOptionSlice | null>(null);\n\nfunction useSavedCardData(): SavedCardOptionSlice {\n  const data = useContext(SavedCardDataContext);\n  if (!data) {\n    throw new Error('SavedCardCvvField must be used inside a <SavedCardOption> subtree.');\n  }\n  return data;\n}\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const SavedCardsDefinition = defineComponent<SavedCardsProps>({\n  name: 'SavedCards',\n  importPath: '@vtex/faststore/components',\n  component: SavedCards,\n  fragment,\n  fetchStrategy: 'reactive',\n  requiresContext: 'payment',\n  providesContext: 'saved-card',\n  editor: { label: 'Saved Cards', category: 'commerce' },\n  schema: {\n    // T38: an inline literal, never an identifier — the native catalog builder extracts `schema`\n    // statically and silently drops an identifier-valued default (INV-8).\n    legend: { type: 'string', default: 'Saved cards', label: 'Legend' },\n  },\n  guideline:\n    'Radio list of the shopper\\'s saved cards (network, last four, label); expired cards render present but disabled, never selectable. Place a SavedCardOption inside as the per-card template, itself wrapping a SavedCardCvvField so the shopper can complete payment with a stored card — omitting the CVV field means a shopper can select a card but never pay with it. Picking a row dispatches the payment method selection by methodId and accountId only, never a card number or BIN, plus the inline selection error (role=\"alert\") if the server rejects it. \"Use a new card\" is CardEntry composed as a sibling, not a control inside this list. Renders one container div and no chrome of its own; always carries a loading/empty/ready state hook. Must be inside a PaymentSectionRoot or PaymentSectionController. See saved-cards.md.',\n});\n\nexport const SavedCardOptionDefinition = defineComponent<SavedCardOptionProps>({\n  name: 'SavedCardOption',\n  importPath: '@vtex/faststore/components',\n  component: SavedCardOption,\n  fragment: optionFragment,\n  fetchStrategy: 'reactive-list-item',\n  requiresContext: 'saved-card',\n  providesContext: 'saved-card-data',\n  editor: { label: 'Saved Card Option', category: 'commerce' },\n  schema: {},\n  guideline:\n    'One saved card as a radio row: network, masked last four, and its label when set; disabled when expired. Place a SavedCardCvvField inside so the CVV appears once this row is selected. Must be inside SavedCards.',\n});\n\nexport const SavedCardCvvFieldDefinition = defineComponent<SavedCardCvvFieldProps>({\n  name: 'SavedCardCvvField',\n  importPath: '@vtex/faststore/components',\n  component: SavedCardCvvField,\n  requiresContext: 'saved-card-data',\n  actions: { payment: ['sendPayments'] },\n  hardened: true,\n  editor: { label: 'Saved Card CVV Field', category: 'commerce' },\n  schema: {\n    securityCodeLabel: { type: 'string', default: 'Security code', label: 'Security code label' },\n    // en-US, per requirement 12.27's own quoted copy (spec mask-the-security-code-field-and.md,\n    // OQ-1 Option B) — matches this component's existing en-US securityCodeLabel default.\n    securityCodeDescription: {\n      type: 'string',\n      default: 'The 3-4 digit number on your card',\n      label: 'Security code description',\n    },\n  },\n  guideline:\n    \"The CVV re-entry field for its saved card row; renders nothing until that row is selected and requires a CVV. Registers the direct-to-gateway submission for the saved-card path on selection — the CVV never transits our backend, only the gateway leg's userErrors return. Must be inside SavedCardOption.\",\n});\n\n// ---------------------------------------------------------------------------\n// Implementations\n// ---------------------------------------------------------------------------\n\n/** Mirrors `PaymentMethodList`'s own state hook, so an empty or loading region stays swatch-targetable. */\nfunction savedCardsState({ loading, count }: { loading: boolean; count: number }): 'loading' | 'empty' | 'ready' {\n  if (loading) return 'loading';\n  if (count === 0) return 'empty';\n  return 'ready';\n}\n\n/**\n * The account a row should treat as \"the current selection.\" `selectedAccountId` is server state that\n * `selectNewCard()` never clears — only `draft.path` flips to `'new-card'` (`use-payment-method-\n * selection.ts`) — so reading `selectedAccountId` alone leaves the previously picked row wedged\n * checked, with its CVV field still mounted and registered, after the shopper picks \"use a new card\"\n * instead. Every read site in this module goes through this one function — the radio group's own\n * `value`, a row's `-selected` state, and the CVV field's visibility gate — so the three can never\n * drift out of sync with each other. Reads only `draft.path`, never `draft.bin`: that stays a fully\n * separate concern (Decision 2) that no call site in this module touches.\n */\nfunction resolveEffectiveSelectedAccountId(selectedAccountId: string | null, draftPath: string | null): string | null {\n  return draftPath === 'new-card' ? null : selectedAccountId;\n}\n\nexport function SavedCards({ $data: $dataProp, legend, className, children, ...props }: SavedCardsProps) {\n  const $data = useDataOverride($dataProp);\n  // `draft` here only for `.path`, to resolve the effective selection below — never `.bin`. The\n  // dispatch in handleValueChange still never reads `draft` at all; see its own comment.\n  const {\n    selectedAccountId,\n    selectMethod,\n    selectionError,\n    draft,\n    placing: placingNow,\n    attempt,\n    cardPaymentCollapsed,\n  } = usePayment();\n  // T202: frozen while the order attempt is resume-only too (`sent` / `unresolved`): the card may already have\n  // been sent and `placeOrder` only resumes, so a security code typed here would never be submitted or cleared.\n  const placing = placingNow || attempt?.phase === 'sent' || attempt?.phase === 'unresolved';\n  const loading = $data == null;\n  const savedCards = $data?.savedCards ?? [];\n  const effectiveSelectedAccountId = resolveEffectiveSelectedAccountId(selectedAccountId, draft.path);\n\n  const handleValueChange = useCallback(\n    (accountId: string) => {\n      const card = savedCards.find((entry) => entry.accountId === accountId);\n      if (!card) return;\n      // methodId, accountId, and this row's own bin — from this list's own read model, never\n      // usePayment().draft.bin. draft.bin can be non-null on the saved-card path too (e.g.\n      // Installments calling setDraftBin for its own BIN-keyed lookup; use-payment-method-selection.ts\n      // does not clear it on this transition), but the bin sent here must be the saved card's own\n      // so paymentMethodSelect can persist a BIN-precise selection. A bin that does not match the\n      // saved card's own BIN is rejected with MISMATCHED_BIN_FOR_SAVED_CARD (spec Decision 2). The\n      // gateway send (SavedCardCvvInput, below) is the different call that legitimately carries both\n      // bin and accountId, reading bin from this row's own resolved slice, never the draft.\n      selectMethod({\n        methodId: card.methodId,\n        accountId: card.accountId,\n        ...(card.bin ? { bin: card.bin } : {}),\n      });\n    },\n    [savedCards, selectMethod],\n  );\n\n  // T191 (FR-7, Decision 3): nothing renders while the card payment is collapsed — the card option brings\n  // the list back. Returned after the last hook, so this instance stays mounted.\n  if (cardPaymentCollapsed) return null;\n\n  return (\n    <div\n      {...props}\n      className={className}\n      inert={placing}\n      aria-disabled={placing || undefined}\n      data-fs-saved-cards=\"\"\n      data-fs-saved-cards-state={savedCardsState({ loading, count: savedCards.length })}\n      {...(placing ? { 'data-fs-saved-cards-placing': '' } : {})}\n    >\n      {selectionError ? (\n        <div role=\"alert\" data-fs-saved-cards-error=\"\">\n          {selectionError}\n        </div>\n      ) : null}\n      {savedCards.length > 0 ? (\n        // T38, Decision 1: Fieldset.Root + Fieldset.Legend, exactly what card-entry.tsx:1101-1112\n        // already ships — Base UI propagates the legend's id as aria-labelledby onto the descendant\n        // RadioGroup, so this one wrapper names both the fieldset and the radiogroup (measured).\n        <Fieldset.Root data-fs-saved-cards-fieldset=\"\">\n          <Fieldset.Legend>{resolveAuthoredCopy(legend, 'Saved cards')}</Fieldset.Legend>\n          <RadioGroup value={effectiveSelectedAccountId ?? ''} onValueChange={handleValueChange}>\n            {savedCards.map((card) => (\n              <ListItemRefContext\n                key={card.id}\n                // No fallback slice: this list's own fragment selects only { id, accountId, methodId }\n                // (Decision 3), so it has no complete row to fall back to. An incomplete cache slice\n                // should render nothing until it resolves, not a partial, silently-wrong row.\n                value={{ __typename: 'SavedCard', id: card.id, fallbackData: undefined }}\n              >\n                {children}\n              </ListItemRefContext>\n            ))}\n          </RadioGroup>\n        </Fieldset.Root>\n      ) : null}\n    </div>\n  );\n}\n\nexport function SavedCardOption({ $data: $dataProp, className, children, ...props }: SavedCardOptionProps) {\n  // Delivery-agnostic: the slice arrives through the DataOverrideContext seam the reactive-list-item\n  // wrapper publishes (or via $data in tests); this component calls no data hook of its own.\n  const slice = useDataOverride<SavedCardOptionSlice | null | undefined>($dataProp) ?? null;\n  const { selectedAccountId, draft } = usePayment();\n\n  if (!slice) return null;\n\n  // Path-aware, not just account-aware — see resolveEffectiveSelectedAccountId's own comment: without\n  // this, a row that was picked before \"use a new card\" stays marked selected forever.\n  const isSelected = slice.accountId === resolveEffectiveSelectedAccountId(selectedAccountId, draft.path);\n\n  return (\n    <SavedCardDataContext value={slice}>\n      <div\n        {...props}\n        className={className}\n        data-fs-saved-card-option=\"\"\n        {...(isSelected ? { 'data-fs-saved-card-option-selected': '' } : {})}\n        {...(slice.expired ? { 'data-fs-saved-card-option-expired': '' } : {})}\n      >\n        <RadioRoot value={slice.accountId} disabled={slice.expired}>\n          <RadioIndicator data-fs-saved-card-option-indicator=\"\" />\n          <span data-fs-saved-card-option-network=\"\">{slice.network}</span>\n          <span data-fs-saved-card-option-last-four=\"\">{`•••• ${slice.lastFourDigits}`}</span>\n          {slice.label ? <span data-fs-saved-card-option-label=\"\">{slice.label}</span> : null}\n        </RadioRoot>\n        {children}\n      </div>\n    </SavedCardDataContext>\n  );\n}\n\nconst MISSING_ACTION_ERROR: PaymentUserError = {\n  code: PAYMENT_NETWORK_ERROR_CODE,\n  message: 'Unable to complete the request. Please try again.',\n};\n\n/**\n * The saved-card path's own client-synthesized refusal (T27, specs/place-order-preflight-card-\n * validation.md FR-11/FR-12; Decision 8). Distinct from `card-entry`'s `INVALID_CARD_DATA` (a\n * different path, a different set of fields, and importing it here would be a matter → matter\n * dependency) and from the gateway's own codes.\n *\n * Never name this constant, or its string value, inside `sdk/payment/use-place-order.ts`: it contains\n * `security` and would fail `CARD_FIELD_PATTERN`. The pre-flight only ever handles the opaque\n * `PaymentUserError` (spec NFR-1, Risk R9).\n */\nexport const SAVED_CARD_INVALID_SECURITY_CODE = 'INVALID_SECURITY_CODE';\n\nconst INVALID_SECURITY_CODE_ERROR: PaymentUserError = {\n  code: SAVED_CARD_INVALID_SECURITY_CODE,\n  message: 'Enter a valid security code before placing the order.',\n};\n\n/** VTEX's own CVV upper bound across the networks this codebase's masks cover (Decision 4). */\nconst CVV_MAX_LENGTH = 4;\n\nfunction sanitizeCvv(value: string): string {\n  return value.replace(/\\D/g, '').slice(0, CVV_MAX_LENGTH);\n}\n\n/**\n * Three or four digits (T27, FR-11). `sanitizeCvv` already strips non-digits and caps at\n * `CVV_MAX_LENGTH`, so the only rule left is the floor — and three-or-four is `card-entry`'s own\n * fallback for a method that declares no `cvvRegex` (its `isValidCvv`, `/^\\d{3,4}$/`). Requiredness is\n * not checked here: `SavedCardCvvInput` renders only when the row is selected and `cvvRequired` is\n * true, so its presence *is* the requiredness signal.\n */\nconst SAVED_CARD_CVV_PATTERN = /^\\d{3,4}$/;\n\n/**\n * The length at which this field's security code counts as fully typed, and the mask engages (T173,\n * specs/mask-the-cvv-only-once-it.md, FR-3). Three — the floor of `SAVED_CARD_CVV_PATTERN` above,\n * for the same reason that pattern accepts either length: a saved card carries no per-network CVV\n * length. Its slice exposes a display `network` string, not a `cvvMask`, so nothing here tells a\n * 3-digit network apart from Amex's 4 the way `CardEntry` can, and inferring one from the display\n * name would hardcode a network table this package deliberately does not own.\n *\n * Masking at the floor is the side to err on: a complete code is never left legible on either kind\n * of card, and a 4-digit code is simply already masked when its last digit arrives.\n */\nconst SAVED_CARD_CVV_COMPLETE_LENGTH = 3;\n\ntype SavedCardCvvInputProps = ComponentPropsWithRef<'input'> & {\n  /** `SavedCard.accountId` from this row's own resolved slice — never `usePayment().draft`. */\n  accountId: string;\n  /**\n   * `SavedCard.bin` from this row's own resolved slice — the one this row is actually being paid\n   * with. Deliberately **not** `usePayment().draft.bin`: that field can be populated on the\n   * saved-card path too (e.g. Installments calling `setDraftBin` for its own BIN-keyed lookup;\n   * `use-payment-method-selection.ts` does not clear it on this transition), so it can carry a\n   * different card's BIN, or a stale one, at the moment this continuation runs. Forwarding it here\n   * instead of the row's own field would be the same class of bug Decision 2 already closed for the\n   * `selectMethod` dispatch — undetectable by type-checking, since both are plain `string`.\n   */\n  bin: string;\n  /** Accessible name applied verbatim as `aria-label` — see `SavedCardCvvFieldProps`'s own doc comment. */\n  securityCodeLabel: string;\n  /** Helper copy rendered as a sibling `<p>` — see `SavedCardCvvFieldProps`'s own doc comment. Threaded\n   * through exactly like `securityCodeLabel`. An empty string renders nothing. */\n  securityCodeDescription: string;\n  $actions?: ComponentActions;\n};\n\n/** Merges a caller-forwarded `aria-describedby` (from `...props`) with the description `<p>`'s own\n * id, rather than clobbering it — the accessibility wiring `Field.Root` would otherwise provide for\n * free (saved-cards.md Decision 3). */\nfunction mergeDescribedBy(existing: string | undefined, id: string): string {\n  return existing ? `${existing} ${id}` : id;\n}\n\n/**\n * The stateful, registering half of the CVV field — split out from `SavedCardCvvField` so this row's\n * conditional visibility never skips a hook call (spec Decision 5). This component mounts wholesale\n * when its row is selected and requires a CVV, and unmounts wholesale otherwise, so its own hooks\n * always run the same number of times across its own lifetime; only its *presence* is conditional,\n * decided by its caller.\n */\nfunction SavedCardCvvInput({\n  accountId,\n  bin,\n  securityCodeLabel,\n  securityCodeDescription,\n  $actions,\n  ref: forwardedRef,\n  ...props\n}: SavedCardCvvInputProps) {\n  const [cvv, setCvv] = useState('');\n  const inputRef = useRef<HTMLInputElement>(null);\n  const sendPayments = $actions?.payment?.sendPayments;\n  const descriptionId = useId();\n\n  // Attaches both this component's own ref (needed to focus the field on refusal, in checkCvv below)\n  // and whatever ref a caller already forwarded onto SavedCardCvvField/SavedCardCvvInput — `props`\n  // spreads onto the element below and `SavedCardCvvInputProps` is `ComponentPropsWithRef<'input'>`, so\n  // writing `ref={inputRef}` after the spread would silently drop a caller-forwarded ref instead.\n  const setInputRef = useCallback(\n    (node: HTMLInputElement | null) => {\n      inputRef.current = node;\n\n      if (typeof forwardedRef !== 'function') {\n        if (forwardedRef) forwardedRef.current = node;\n        return;\n      }\n\n      // React 19: a ref callback may itself return a cleanup function instead of being re-invoked\n      // with `null` on detach. Preserve whichever form the caller used — never call a React-19\n      // cleanup-style ref with `null`, a value that form is documented never to receive (fix pass,\n      // review F2). A caller using the legacy form (no returned cleanup) keeps today's behaviour:\n      // this callback returns nothing either, so React re-invokes it with `null` on detach, which\n      // falls into this same branch and calls `forwardedRef(null)`, exactly as before.\n      const cleanup = forwardedRef(node);\n      if (typeof cleanup === 'function') {\n        return () => {\n          inputRef.current = null;\n          cleanup();\n        };\n      }\n      return;\n    },\n    [forwardedRef],\n  );\n\n  // The saved-card check (T27, FR-11/FR-12; Decision 8). Three-or-four digits — see\n  // SAVED_CARD_CVV_PATTERN's own doc comment for why nothing narrower is checkable and nothing wider\n  // is safe. The only field on this path, so there is no ordering rule and no inline error node to\n  // fill (FR-12) — the message reaches the shopper through PlaceOrder's existing role=\"alert\".\n  const checkCvv = useCallback<PaymentPreflightCheck>(() => {\n    if (SAVED_CARD_CVV_PATTERN.test(cvv)) return [];\n    inputRef.current?.focus();\n    return [INVALID_SECURITY_CODE_ERROR];\n  }, [cvv]);\n\n  const submit = useCallback<PaymentSubmission>(\n    async (transaction) => {\n      // Same function the pre-flight calls (FR-3, applied to this path) — the two moments cannot\n      // diverge here either.\n      // Both refusals precede any request, so each reports `reachedGateway: false` (T112): the attempt is\n      // freed rather than left resume-only on a card that was never sent.\n      const refusals = checkCvv();\n      if (refusals.length > 0) return { reachedGateway: false, userErrors: refusals };\n      // T202: past the field's own check the code is not needed again, whatever the outcome. A throw is\n      // re-thrown untouched; the `finally` is the one place certain to run.\n      try {\n        if (!sendPayments) return { reachedGateway: false, userErrors: [MISSING_ACTION_ERROR] };\n        // `bin` here is always the `accountId`/`bin` pair from this row's own props — see their doc\n        // comments above for why `usePayment().draft.bin` must never substitute for either.\n        return await sendPayments({ transaction, card: { kind: 'saved', accountId, bin, securityCode: cvv } });\n      } finally {\n        setCvv('');\n      }\n    },\n    [checkCvv, sendPayments, accountId, bin, cvv],\n  );\n\n  useRegisterPaymentSubmission('saved-card', submit, checkCvv);\n\n  // Merges with a caller-forwarded aria-describedby rather than clobbering it — mirrors the ref\n  // merge above (setInputRef) for the same \"don't drop what a caller already passed\" reason.\n  const ariaDescribedBy = securityCodeDescription\n    ? mergeDescribedBy(props['aria-describedby'], descriptionId)\n    : props['aria-describedby'];\n\n  // T101 — the mask merges *over* a caller-forwarded style, inverted from this repo's usual\n  // `...props.style`-last idiom (cart-item.tsx, product-list.tsx): deliberately, so a caller can\n  // never remove the security-code mask. See security-code-mask.ts.\n  //\n  // T173 — that merge now happens from the keystroke that completes the code, not from the first\n  // one, so a shopper can read back what they typed while they type it. Below the trigger the\n  // caller's own style passes through untouched, which is the same thing it did before this field\n  // ever had a mask; the guarantee above is about what a caller cannot do once the code is complete.\n  const inputStyle = isSecurityCodeComplete(cvv, SAVED_CARD_CVV_COMPLETE_LENGTH)\n    ? { ...props.style, ...SECURITY_CODE_MASK_STYLE }\n    : props.style;\n\n  return (\n    <>\n      <input\n        {...props}\n        ref={setInputRef}\n        type=\"text\"\n        inputMode=\"numeric\"\n        autoComplete=\"off\"\n        aria-label={securityCodeLabel}\n        aria-describedby={ariaDescribedBy}\n        value={cvv}\n        onChange={(event) => setCvv(sanitizeCvv(event.target.value))}\n        data-fs-saved-card-cvv-field=\"\"\n        style={inputStyle}\n      />\n      {securityCodeDescription ? (\n        <p id={descriptionId} data-fs-saved-card-cvv-description=\"\">\n          {securityCodeDescription}\n        </p>\n      ) : null}\n    </>\n  );\n}\n\nexport function SavedCardCvvField({\n  $actions: $actionsProp,\n  securityCodeLabel = 'Security code',\n  securityCodeDescription = 'The 3-4 digit number on your card',\n  className,\n  ...props\n}: SavedCardCvvFieldProps) {\n  const $actions = useActionsOverride($actionsProp);\n  const { accountId, bin, cvvRequired } = useSavedCardData();\n  const { selectedAccountId, draft } = usePayment();\n\n  // Path-aware, matching SavedCardOption's own isSelected — otherwise this field stays mounted and\n  // registered after \"use a new card\", with selectedAccountId still equal to this row's own accountId.\n  if (accountId !== resolveEffectiveSelectedAccountId(selectedAccountId, draft.path) || !cvvRequired) {\n    return null;\n  }\n\n  return (\n    <SavedCardCvvInput\n      {...props}\n      className={className}\n      accountId={accountId}\n      bin={bin}\n      securityCodeLabel={securityCodeLabel}\n      securityCodeDescription={securityCodeDescription}\n      $actions={$actions}\n    />\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmEA,MAAM,WAAyB;;;;;;;;;;;;;;;AAgB/B,MAAM,iBAA+B;;;;;;;;;;;;;;;;;;AAyFrC,MAAM,uBAAuB,cAA2C,IAAI;AAE5E,SAAS,mBAAyC;CAChD,MAAM,OAAO,WAAW,oBAAoB;CAC5C,IAAI,CAAC,MACH,MAAM,IAAI,MAAM,oEAAoE;CAEtF,OAAO;AACT;AAMA,MAAa,uBAAuB,gBAAiC;CACnE,MAAM;CACN,YAAY;CACZ,WAAW;CACX;CACA,eAAe;CACf,iBAAiB;CACjB,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAAe,UAAU;CAAW;CACrD,QAAQ,EAGN,QAAQ;EAAE,MAAM;EAAU,SAAS;EAAe,OAAO;CAAS,EACpE;CACA,WACE;AACJ,CAAC;AAED,MAAa,4BAA4B,gBAAsC;CAC7E,MAAM;CACN,YAAY;CACZ,WAAW;CACX,UAAU;CACV,eAAe;CACf,iBAAiB;CACjB,iBAAiB;CACjB,QAAQ;EAAE,OAAO;EAAqB,UAAU;CAAW;CAC3D,QAAQ,CAAC;CACT,WACE;AACJ,CAAC;AAED,MAAa,8BAA8B,gBAAwC;CACjF,MAAM;CACN,YAAY;CACZ,WAAW;CACX,iBAAiB;CACjB,SAAS,EAAE,SAAS,CAAC,cAAc,EAAE;CACrC,UAAU;CACV,QAAQ;EAAE,OAAO;EAAwB,UAAU;CAAW;CAC9D,QAAQ;EACN,mBAAmB;GAAE,MAAM;GAAU,SAAS;GAAiB,OAAO;EAAsB;EAG5F,yBAAyB;GACvB,MAAM;GACN,SAAS;GACT,OAAO;EACT;CACF;CACA,WACE;AACJ,CAAC;;AAOD,SAAS,gBAAgB,EAAE,SAAS,SAA6E;CAC/G,IAAI,SAAS,OAAO;CACpB,IAAI,UAAU,GAAG,OAAO;CACxB,OAAO;AACT;;;;;;;;;;;AAYA,SAAS,kCAAkC,mBAAkC,WAAyC;CACpH,OAAO,cAAc,aAAa,OAAO;AAC3C;AAEA,SAAgB,WAAW,EAAE,OAAO,WAAW,QAAQ,WAAW,UAAU,GAAG,SAA0B;CACvG,MAAM,QAAQ,gBAAgB,SAAS;CAGvC,MAAM,EACJ,mBACA,cACA,gBACA,OACA,SAAS,YACT,SACA,yBACE,WAAW;CAGf,MAAM,UAAU,cAAc,SAAS,UAAU,UAAU,SAAS,UAAU;CAC9E,MAAM,UAAU,SAAS;CACzB,MAAM,aAAa,OAAO,cAAc,CAAC;CACzC,MAAM,6BAA6B,kCAAkC,mBAAmB,MAAM,IAAI;CAElG,MAAM,oBAAoB,aACvB,cAAsB;EACrB,MAAM,OAAO,WAAW,MAAM,UAAU,MAAM,cAAc,SAAS;EACrE,IAAI,CAAC,MAAM;EASX,aAAa;GACX,UAAU,KAAK;GACf,WAAW,KAAK;GAChB,GAAI,KAAK,MAAM,EAAE,KAAK,KAAK,IAAI,IAAI,CAAC;EACtC,CAAC;CACH,GACA,CAAC,YAAY,YAAY,CAC3B;CAIA,IAAI,sBAAsB,OAAO;CAEjC,OACE,qBAAC,OAAD;EACE,GAAI;EACO;EACX,OAAO;EACP,iBAAe,WAAW,KAAA;EAC1B,uBAAoB;EACpB,6BAA2B,gBAAgB;GAAE;GAAS,OAAO,WAAW;EAAO,CAAC;EAChF,GAAK,UAAU,EAAE,+BAA+B,GAAG,IAAI,CAAC;EAP1D,UAAA,CASG,iBACC,oBAAC,OAAD;GAAK,MAAK;GAAQ,6BAA0B;GACzC,UAAA;EACE,CAAA,IACH,MACH,WAAW,SAAS,IAInB,qBAAC,SAAS,MAAV;GAAe,gCAA6B;GAA5C,UAAA,CACE,oBAAC,SAAS,QAAV,EAAA,UAAkB,oBAAoB,QAAQ,aAAa,EAAmB,CAAA,GAC9E,oBAAC,YAAD;IAAY,OAAO,8BAA8B;IAAI,eAAe;IACjE,UAAA,WAAW,KAAK,SACf,oBAAC,oBAAD;KAKE,OAAO;MAAE,YAAY;MAAa,IAAI,KAAK;MAAI,cAAc,KAAA;KAAU;KAEtE;IACiB,GAPb,KAAK,EAOQ,CACrB;GACS,CAAA,CACC;EACb,CAAA,IAAA,IACD;;AAET;AAEA,SAAgB,gBAAgB,EAAE,OAAO,WAAW,WAAW,UAAU,GAAG,SAA+B;CAGzG,MAAM,QAAQ,gBAAyD,SAAS,KAAK;CACrF,MAAM,EAAE,mBAAmB,UAAU,WAAW;CAEhD,IAAI,CAAC,OAAO,OAAO;CAInB,MAAM,aAAa,MAAM,cAAc,kCAAkC,mBAAmB,MAAM,IAAI;CAEtG,OACE,oBAAC,sBAAD;EAAsB,OAAO;EAC3B,UAAA,qBAAC,OAAD;GACE,GAAI;GACO;GACX,6BAA0B;GAC1B,GAAK,aAAa,EAAE,sCAAsC,GAAG,IAAI,CAAC;GAClE,GAAK,MAAM,UAAU,EAAE,qCAAqC,GAAG,IAAI,CAAC;GALtE,UAAA,CAOE,qBAAC,WAAD;IAAW,OAAO,MAAM;IAAW,UAAU,MAAM;IAAnD,UAAA;KACE,oBAAC,gBAAD,EAAgB,uCAAoC,GAAI,CAAA;KACxD,oBAAC,QAAD;MAAM,qCAAkC;MAAI,UAAA,MAAM;KAAc,CAAA;KAChE,oBAAC,QAAD;MAAM,uCAAoC;MAAI,UAAA,QAAQ,MAAM;KAAuB,CAAA;KAClF,MAAM,QAAQ,oBAAC,QAAD;MAAM,mCAAgC;MAAI,UAAA,MAAM;KAAY,CAAA,IAAI;IACtE;GACV,CAAA,GAAA,QACE;;CACe,CAAA;AAE1B;AAEA,MAAM,uBAAyC;CAC7C,MAAM;CACN,SAAS;AACX;;;;;;;;;;;AAYA,MAAa,mCAAmC;AAEhD,MAAM,8BAAgD;CACpD,MAAM;CACN,SAAS;AACX;;AAGA,MAAM,iBAAiB;AAEvB,SAAS,YAAY,OAAuB;CAC1C,OAAO,MAAM,QAAQ,OAAO,EAAE,CAAC,CAAC,MAAM,GAAG,cAAc;AACzD;;;;;;;;AASA,MAAM,yBAAyB;;;;;;;;;;;;AAa/B,MAAM,iCAAiC;;;;AA0BvC,SAAS,iBAAiB,UAA8B,IAAoB;CAC1E,OAAO,WAAW,GAAG,SAAS,GAAG,OAAO;AAC1C;;;;;;;;AASA,SAAS,kBAAkB,EACzB,WACA,KACA,mBACA,yBACA,UACA,KAAK,cACL,GAAG,SACsB;CACzB,MAAM,CAAC,KAAK,UAAU,SAAS,EAAE;CACjC,MAAM,WAAW,OAAyB,IAAI;CAC9C,MAAM,eAAe,UAAU,SAAS;CACxC,MAAM,gBAAgB,MAAM;CAM5B,MAAM,cAAc,aACjB,SAAkC;EACjC,SAAS,UAAU;EAEnB,IAAI,OAAO,iBAAiB,YAAY;GACtC,IAAI,cAAc,aAAa,UAAU;GACzC;EACF;EAQA,MAAM,UAAU,aAAa,IAAI;EACjC,IAAI,OAAO,YAAY,YACrB,aAAa;GACX,SAAS,UAAU;GACnB,QAAQ;EACV;CAGJ,GACA,CAAC,YAAY,CACf;CAMA,MAAM,WAAW,kBAAyC;EACxD,IAAI,uBAAuB,KAAK,GAAG,GAAG,OAAO,CAAC;EAC9C,SAAS,SAAS,MAAM;EACxB,OAAO,CAAC,2BAA2B;CACrC,GAAG,CAAC,GAAG,CAAC;CAER,MAAM,SAAS,YACb,OAAO,gBAAgB;EAKrB,MAAM,WAAW,SAAS;EAC1B,IAAI,SAAS,SAAS,GAAG,OAAO;GAAE,gBAAgB;GAAO,YAAY;EAAS;EAG9E,IAAI;GACF,IAAI,CAAC,cAAc,OAAO;IAAE,gBAAgB;IAAO,YAAY,CAAC,oBAAoB;GAAE;GAGtF,OAAO,MAAM,aAAa;IAAE;IAAa,MAAM;KAAE,MAAM;KAAS;KAAW;KAAK,cAAc;IAAI;GAAE,CAAC;EACvG,UAAU;GACR,OAAO,EAAE;EACX;CACF,GACA;EAAC;EAAU;EAAc;EAAW;EAAK;CAAG,CAC9C;CAEA,6BAA6B,cAAc,QAAQ,QAAQ;CAI3D,MAAM,kBAAkB,0BACpB,iBAAiB,MAAM,qBAAqB,aAAa,IACzD,MAAM;CAUV,MAAM,aAAa,uBAAuB,KAAK,8BAA8B,IACzE;EAAE,GAAG,MAAM;EAAO,GAAG;CAAyB,IAC9C,MAAM;CAEV,OACE,qBAAA,YAAA,EAAA,UAAA,CACE,oBAAC,SAAD;EACE,GAAI;EACJ,KAAK;EACL,MAAK;EACL,WAAU;EACV,cAAa;EACb,cAAY;EACZ,oBAAkB;EAClB,OAAO;EACP,WAAW,UAAU,OAAO,YAAY,MAAM,OAAO,KAAK,CAAC;EAC3D,gCAA6B;EAC7B,OAAO;CACR,CAAA,GACA,0BACC,oBAAC,KAAD;EAAG,IAAI;EAAe,sCAAmC;EACtD,UAAA;CACA,CAAA,IACD,IACJ,EAAA,CAAA;AAEN;AAEA,SAAgB,kBAAkB,EAChC,UAAU,cACV,oBAAoB,iBACpB,0BAA0B,qCAC1B,WACA,GAAG,SACsB;CACzB,MAAM,WAAW,mBAAmB,YAAY;CAChD,MAAM,EAAE,WAAW,KAAK,gBAAgB,iBAAiB;CACzD,MAAM,EAAE,mBAAmB,UAAU,WAAW;CAIhD,IAAI,cAAc,kCAAkC,mBAAmB,MAAM,IAAI,KAAK,CAAC,aACrF,OAAO;CAGT,OACE,oBAAC,mBAAD;EACE,GAAI;EACO;EACA;EACN;EACc;EACM;EACf;CACX,CAAA;AAEL"}

package/dist/matter/session/session.js

@@ -4,7 +4,7 @@ import "../../core/dist/index.js";
 import { graphql } from "../../sdk/generated/gql.js";
 import { useDataOverride } from "../../sdk/data/data-override-context.js";
 import { createContext, useContext, useMemo } from "react";
-import { Fragment, jsx } from "react/jsx-runtime";
+import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
 //#region src/matter/session/session.tsx
 const fragment = graphql(`
   fragment SessionData on Query {
@@ -100,7 +100,7 @@ function SessionRoot({ $data: $dataProp, children }) {
 function SessionGuard({ when, children }) {
 	const { state } = useSession();
 	if (!when?.includes(state)) return null;
-	return /* @__PURE__ */ jsx(Fragment, { children });
+	return /* @__PURE__ */ jsx(Fragment$1, { children });
 }
 const Session = {
 	Root: SessionRoot,

package/dist/matter/session/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","names":[],"sources":["../../../src/matter/session/session.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport { createContext, type ReactNode, useContext, useMemo } from 'react';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { graphql } from '../../sdk/generated/gql.js';\nimport type { SessionEntity } from '../../sdk/session/operations.js';\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — typed via @graphql-codegen client-preset\n// ---------------------------------------------------------------------------\n\nconst fragment = graphql(`\n  fragment SessionData on Query {\n    session {\n      ...SessionFragment\n    }\n  }\n`);\n\n// ---------------------------------------------------------------------------\n// Tri-state derivation — the single home of the truth table (Decision 2).\n// ---------------------------------------------------------------------------\n\nexport type SessionState = 'anonymous' | 'identified' | 'loggedIn';\n\n/**\n * Derive the identity tri-state from the two raw session flags. `loggedIn` takes precedence: an\n * authenticated shopper is always `loggedIn` regardless of `isIdentified`.\n */\nexport function deriveSessionState({\n  loggedIn,\n  isIdentified,\n}: {\n  loggedIn: boolean;\n  isIdentified: boolean;\n}): SessionState {\n  if (loggedIn) return 'loggedIn';\n  if (isIdentified) return 'identified';\n  return 'anonymous';\n}\n\n// ---------------------------------------------------------------------------\n// Session context (read-only derived state + raw flags)\n// ---------------------------------------------------------------------------\n\nexport type SessionContextValue = Readonly<{\n  /** Derived tri-state: anonymous | identified | loggedIn. */\n  state: SessionState;\n  /** Raw authenticated-session flag from `session.loggedIn`. */\n  loggedIn: boolean;\n  /** Raw edit-permission flag from `session.canEditData`; lets Controls render editable vs. masked. */\n  canEditData: boolean;\n  /** True while the Session entity has not yet resolved. */\n  loading: boolean;\n}>;\n\nconst SESSION_DATA_UNSET = Symbol('SessionContextUnset');\n\nconst SessionContextInternal = createContext<SessionContextValue | typeof SESSION_DATA_UNSET>(SESSION_DATA_UNSET);\n\nexport const SessionContext = SessionContextInternal as React.Context<SessionContextValue>;\n\n/**\n * Read the derived session state and raw flags from the nearest `SessionRoot`. Throws when called\n * outside a `SessionRoot` subtree (a misplaced `useSession()` is a composition bug the author should\n * see immediately, not a silent degrade to anonymous), mirroring `useCart()` (Decision 6).\n *\n * While the Session entity is unresolved the context carries `loading: true` and `state:\n * 'anonymous'` (the least-privileged default); consumers that must not flash gate on `loading`.\n */\nexport function useSession(): SessionContextValue {\n  const ctx = useContext(SessionContextInternal);\n  if (ctx === SESSION_DATA_UNSET) {\n    throw new Error('useSession() must be used inside a <SessionRoot> subtree.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type SessionRootProps = {\n  /**\n   * Session entity slice forwarded by the reactive runtime (`ReactiveDataProvider`) — the value of\n   * the `session` top-level field on `SessionData on Query`, not the wrapping `{ session: … }` shape.\n   * Receives `null` while the entity has not yet resolved.\n   */\n  $data?: SessionEntity | null;\n  children?: ReactNode;\n};\n\nexport type SessionGuardProps = {\n  /** The session states under which the children render. Renders nothing for any other state. */\n  when?: SessionState[];\n  children?: ReactNode;\n};\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const SessionRootDefinition = defineComponent<SessionRootProps>({\n  name: 'SessionRoot',\n  importPath: '@vtex/faststore/components',\n  component: SessionRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  editor: { label: 'Session Root', category: 'identity' },\n  schema: {},\n  providesContext: 'session',\n  guideline:\n    'Read-only identity-state provider, normally the root of the shared layout so the header and every page it serves resolve the same session: reads the Session and broadcasts the anonymous/identified/logged-in tri-state plus the raw loggedIn and canEditData flags. Layout scope fetches once client-side and reuses the cache across navigation; page scope fetches fresh server-side on every request. Exactly one per rendered tree — a page must not add its own when the layout already hosts one. See session.md.',\n});\n\nexport const SessionGuardDefinition = defineComponent<SessionGuardProps>({\n  name: 'SessionGuard',\n  importPath: '@vtex/faststore/components',\n  component: SessionGuard,\n  editor: { label: 'Session Guard', category: 'identity' },\n  schema: {\n    when: { type: 'array', items: ['anonymous', 'identified', 'loggedIn'] as const, label: 'When State' },\n  },\n  requiresContext: 'session',\n  guideline:\n    'Declarative gate: renders its children only when the current session state is one of the values in `when` (e.g. {\"when\":[\"identified\",\"loggedIn\"]}), else renders nothing. Use it in page or layout JSON to show or hide an identity subtree by state without writing the gate into a component. Must be inside SessionRoot, which may be hosted by the page or by its layout.',\n});\n\n// ---------------------------------------------------------------------------\n// Implementations\n// ---------------------------------------------------------------------------\n\nexport function SessionRoot({ $data: $dataProp, children }: SessionRootProps) {\n  const $data = useDataOverride($dataProp);\n  const session = $data ?? null;\n  const loading = session == null;\n\n  const value: SessionContextValue = useMemo(() => {\n    const loggedIn = session?.loggedIn ?? false;\n    const isIdentified = session?.isIdentified ?? false;\n    return {\n      state: deriveSessionState({ loggedIn, isIdentified }),\n      loggedIn,\n      canEditData: session?.canEditData ?? false,\n      loading,\n    };\n  }, [session?.loggedIn, session?.isIdentified, session?.canEditData, loading]);\n\n  return <SessionContextInternal value={value}>{children}</SessionContextInternal>;\n}\n\nexport function SessionGuard({ when, children }: SessionGuardProps) {\n  const { state } = useSession();\n  if (!when?.includes(state)) return null;\n  return <>{children}</>;\n}\n\n// ---------------------------------------------------------------------------\n// Namespace export\n// ---------------------------------------------------------------------------\n\nexport const Session = {\n  Root: SessionRoot,\n  Guard: SessionGuard,\n};\n"],"mappings":";;;;;;;;AAYA,MAAM,WAAW,QAAQ;;;;;;CAMxB;;;;;AAYD,SAAgB,mBAAmB,EACjC,UACA,gBAIe;CACf,IAAI,UAAU,OAAO;CACrB,IAAI,cAAc,OAAO;CACzB,OAAO;AACT;AAiBA,MAAM,qBAAqB,OAAO,qBAAqB;AAEvD,MAAM,yBAAyB,cAA+D,kBAAkB;AAEhH,MAAa,iBAAiB;;;;;;;;;AAU9B,SAAgB,aAAkC;CAChD,MAAM,MAAM,WAAW,sBAAsB;CAC7C,IAAI,QAAQ,oBACV,MAAM,IAAI,MAAM,2DAA2D;CAE7E,OAAO;AACT;AA0BA,MAAa,wBAAwB,gBAAkC;CACrE,MAAM;CACN,YAAY;CACZ,WAAW;CACX;CACA,eAAe;CACf,QAAQ;EAAE,OAAO;EAAgB,UAAU;CAAW;CACtD,QAAQ,CAAC;CACT,iBAAiB;CACjB,WACE;AACJ,CAAC;AAED,MAAa,yBAAyB,gBAAmC;CACvE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAiB,UAAU;CAAW;CACvD,QAAQ,EACN,MAAM;EAAE,MAAM;EAAS,OAAO;GAAC;GAAa;GAAc;EAAU;EAAY,OAAO;CAAa,EACtG;CACA,iBAAiB;CACjB,WACE;AACJ,CAAC;AAMD,SAAgB,YAAY,EAAE,OAAO,WAAW,YAA8B;CAE5E,MAAM,UADQ,gBAAgB,SACV,KAAK;CACzB,MAAM,UAAU,WAAW;CAE3B,MAAM,QAA6B,cAAc;EAC/C,MAAM,WAAW,SAAS,YAAY;EAEtC,OAAO;GACL,OAAO,mBAAmB;IAAE;IAAU,cAFnB,SAAS,gBAAgB;GAEO,CAAC;GACpD;GACA,aAAa,SAAS,eAAe;GACrC;EACF;CACF,GAAG;EAAC,SAAS;EAAU,SAAS;EAAc,SAAS;EAAa;CAAO,CAAC;CAE5E,OAAO,oBAAC,wBAAD;EAA+B;EAAQ;CAAiC,CAAA;AACjF;AAEA,SAAgB,aAAa,EAAE,MAAM,YAA+B;CAClE,MAAM,EAAE,UAAU,WAAW;CAC7B,IAAI,CAAC,MAAM,SAAS,KAAK,GAAG,OAAO;CACnC,OAAO,oBAAA,UAAA,EAAG,SAAW,CAAA;AACvB;AAMA,MAAa,UAAU;CACrB,MAAM;CACN,OAAO;AACT"}
+{"version":3,"file":"session.js","names":[],"sources":["../../../src/matter/session/session.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport { createContext, type ReactNode, useContext, useMemo } from 'react';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport { graphql } from '../../sdk/generated/gql.js';\nimport type { SessionEntity } from '../../sdk/session/operations.js';\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — typed via @graphql-codegen client-preset\n// ---------------------------------------------------------------------------\n\nconst fragment = graphql(`\n  fragment SessionData on Query {\n    session {\n      ...SessionFragment\n    }\n  }\n`);\n\n// ---------------------------------------------------------------------------\n// Tri-state derivation — the single home of the truth table (Decision 2).\n// ---------------------------------------------------------------------------\n\nexport type SessionState = 'anonymous' | 'identified' | 'loggedIn';\n\n/**\n * Derive the identity tri-state from the two raw session flags. `loggedIn` takes precedence: an\n * authenticated shopper is always `loggedIn` regardless of `isIdentified`.\n */\nexport function deriveSessionState({\n  loggedIn,\n  isIdentified,\n}: {\n  loggedIn: boolean;\n  isIdentified: boolean;\n}): SessionState {\n  if (loggedIn) return 'loggedIn';\n  if (isIdentified) return 'identified';\n  return 'anonymous';\n}\n\n// ---------------------------------------------------------------------------\n// Session context (read-only derived state + raw flags)\n// ---------------------------------------------------------------------------\n\nexport type SessionContextValue = Readonly<{\n  /** Derived tri-state: anonymous | identified | loggedIn. */\n  state: SessionState;\n  /** Raw authenticated-session flag from `session.loggedIn`. */\n  loggedIn: boolean;\n  /** Raw edit-permission flag from `session.canEditData`; lets Controls render editable vs. masked. */\n  canEditData: boolean;\n  /** True while the Session entity has not yet resolved. */\n  loading: boolean;\n}>;\n\nconst SESSION_DATA_UNSET = Symbol('SessionContextUnset');\n\nconst SessionContextInternal = createContext<SessionContextValue | typeof SESSION_DATA_UNSET>(SESSION_DATA_UNSET);\n\nexport const SessionContext = SessionContextInternal as React.Context<SessionContextValue>;\n\n/**\n * Read the derived session state and raw flags from the nearest `SessionRoot`. Throws when called\n * outside a `SessionRoot` subtree (a misplaced `useSession()` is a composition bug the author should\n * see immediately, not a silent degrade to anonymous), mirroring `useCart()` (Decision 6).\n *\n * While the Session entity is unresolved the context carries `loading: true` and `state:\n * 'anonymous'` (the least-privileged default); consumers that must not flash gate on `loading`.\n */\nexport function useSession(): SessionContextValue {\n  const ctx = useContext(SessionContextInternal);\n  if (ctx === SESSION_DATA_UNSET) {\n    throw new Error('useSession() must be used inside a <SessionRoot> subtree.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type SessionRootProps = {\n  /**\n   * Session entity slice forwarded by the reactive runtime (`ReactiveDataProvider`) — the value of\n   * the `session` top-level field on `SessionData on Query`, not the wrapping `{ session: … }` shape.\n   * Receives `null` while the entity has not yet resolved.\n   */\n  $data?: SessionEntity | null;\n  children?: ReactNode;\n};\n\nexport type SessionGuardProps = {\n  /** The session states under which the children render. Renders nothing for any other state. */\n  when?: SessionState[];\n  children?: ReactNode;\n};\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const SessionRootDefinition = defineComponent<SessionRootProps>({\n  name: 'SessionRoot',\n  importPath: '@vtex/faststore/components',\n  component: SessionRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  editor: { label: 'Session Root', category: 'identity' },\n  schema: {},\n  providesContext: 'session',\n  guideline:\n    'Read-only identity-state provider, normally the root of the shared layout so the header and every page it serves resolve the same session: reads the Session and broadcasts the anonymous/identified/logged-in tri-state plus the raw loggedIn and canEditData flags. Layout scope fetches once client-side and reuses the cache across navigation; page scope fetches fresh server-side on every request. Exactly one per rendered tree — a page must not add its own when the layout already hosts one. See session.md.',\n});\n\nexport const SessionGuardDefinition = defineComponent<SessionGuardProps>({\n  name: 'SessionGuard',\n  importPath: '@vtex/faststore/components',\n  component: SessionGuard,\n  editor: { label: 'Session Guard', category: 'identity' },\n  schema: {\n    when: { type: 'array', items: ['anonymous', 'identified', 'loggedIn'] as const, label: 'When State' },\n  },\n  requiresContext: 'session',\n  guideline:\n    'Declarative gate: renders its children only when the current session state is one of the values in `when` (e.g. {\"when\":[\"identified\",\"loggedIn\"]}), else renders nothing. Use it in page or layout JSON to show or hide an identity subtree by state without writing the gate into a component. Must be inside SessionRoot, which may be hosted by the page or by its layout.',\n});\n\n// ---------------------------------------------------------------------------\n// Implementations\n// ---------------------------------------------------------------------------\n\nexport function SessionRoot({ $data: $dataProp, children }: SessionRootProps) {\n  const $data = useDataOverride($dataProp);\n  const session = $data ?? null;\n  const loading = session == null;\n\n  const value: SessionContextValue = useMemo(() => {\n    const loggedIn = session?.loggedIn ?? false;\n    const isIdentified = session?.isIdentified ?? false;\n    return {\n      state: deriveSessionState({ loggedIn, isIdentified }),\n      loggedIn,\n      canEditData: session?.canEditData ?? false,\n      loading,\n    };\n  }, [session?.loggedIn, session?.isIdentified, session?.canEditData, loading]);\n\n  return <SessionContextInternal value={value}>{children}</SessionContextInternal>;\n}\n\nexport function SessionGuard({ when, children }: SessionGuardProps) {\n  const { state } = useSession();\n  if (!when?.includes(state)) return null;\n  return <>{children}</>;\n}\n\n// ---------------------------------------------------------------------------\n// Namespace export\n// ---------------------------------------------------------------------------\n\nexport const Session = {\n  Root: SessionRoot,\n  Guard: SessionGuard,\n};\n"],"mappings":";;;;;;;;AAYA,MAAM,WAAW,QAAQ;;;;;;CAMxB;;;;;AAYD,SAAgB,mBAAmB,EACjC,UACA,gBAIe;CACf,IAAI,UAAU,OAAO;CACrB,IAAI,cAAc,OAAO;CACzB,OAAO;AACT;AAiBA,MAAM,qBAAqB,OAAO,qBAAqB;AAEvD,MAAM,yBAAyB,cAA+D,kBAAkB;AAEhH,MAAa,iBAAiB;;;;;;;;;AAU9B,SAAgB,aAAkC;CAChD,MAAM,MAAM,WAAW,sBAAsB;CAC7C,IAAI,QAAQ,oBACV,MAAM,IAAI,MAAM,2DAA2D;CAE7E,OAAO;AACT;AA0BA,MAAa,wBAAwB,gBAAkC;CACrE,MAAM;CACN,YAAY;CACZ,WAAW;CACX;CACA,eAAe;CACf,QAAQ;EAAE,OAAO;EAAgB,UAAU;CAAW;CACtD,QAAQ,CAAC;CACT,iBAAiB;CACjB,WACE;AACJ,CAAC;AAED,MAAa,yBAAyB,gBAAmC;CACvE,MAAM;CACN,YAAY;CACZ,WAAW;CACX,QAAQ;EAAE,OAAO;EAAiB,UAAU;CAAW;CACvD,QAAQ,EACN,MAAM;EAAE,MAAM;EAAS,OAAO;GAAC;GAAa;GAAc;EAAU;EAAY,OAAO;CAAa,EACtG;CACA,iBAAiB;CACjB,WACE;AACJ,CAAC;AAMD,SAAgB,YAAY,EAAE,OAAO,WAAW,YAA8B;CAE5E,MAAM,UADQ,gBAAgB,SACV,KAAK;CACzB,MAAM,UAAU,WAAW;CAE3B,MAAM,QAA6B,cAAc;EAC/C,MAAM,WAAW,SAAS,YAAY;EAEtC,OAAO;GACL,OAAO,mBAAmB;IAAE;IAAU,cAFnB,SAAS,gBAAgB;GAEO,CAAC;GACpD;GACA,aAAa,SAAS,eAAe;GACrC;EACF;CACF,GAAG;EAAC,SAAS;EAAU,SAAS;EAAc,SAAS;EAAa;CAAO,CAAC;CAE5E,OAAO,oBAAC,wBAAD;EAA+B;EAAQ;CAAiC,CAAA;AACjF;AAEA,SAAgB,aAAa,EAAE,MAAM,YAA+B;CAClE,MAAM,EAAE,UAAU,WAAW;CAC7B,IAAI,CAAC,MAAM,SAAS,KAAK,GAAG,OAAO;CACnC,OAAO,oBAAA,YAAA,EAAG,SAAW,CAAA;AACvB;AAMA,MAAa,UAAU;CACrB,MAAM;CACN,OAAO;AACT"}

package/dist/matter/shipping-address/country-descriptors.d.ts

@@ -0,0 +1 @@
+import "../../particles/field/field.js";

package/dist/matter/shipping-address/country-descriptors.js

@@ -1,3 +1,21 @@
+//#region src/matter/shipping-address/country-descriptors.ts
+/**
+* Whether `value` satisfies the field's declared `rule.pattern`. A field with no pattern, or a blank
+* value (empty or whitespace-only: blankness is the required rule's business, and a form that trims
+* before judging, as `BillingAddress` does, reads such a value as required, never as a format failure),
+* satisfies it. A non-blank value is tested raw, equivalent to the predicate react-hook-form applies
+* (`value.match(regex) !== null`), so both forms agree on every non-blank value. Blank values are the
+* one deliberate divergence: react-hook-form skips the pattern only for `''`, so for `'   '` the
+* delivery form runs the pattern and reports the format, while this helper reports it satisfied and
+* leaves the verdict to the required rule. A caller that needs react-hook-form's exact verdict on a
+* blank value must not rely on this helper alone. `search` ignores a global regex's `lastIndex`, so
+* the descriptor's shared regex is never written to.
+*/
+function satisfiesFieldPattern(field, value) {
+	const pattern = field.rule?.pattern;
+	if (!pattern || value.trim() === "") return true;
+	return value.search(pattern.value) !== -1;
+}
 /**
 * All available country descriptors, keyed by ISO alpha-3 code.
 *
@@ -8,6 +26,8 @@ const countryDescriptors = {
 	BRA: {
 		iso: "BRA",
 		label: "Brasil",
+		countryLabel: "país",
+		requiredSuffix: "é obrigatório",
 		fields: [
 			{
 				name: "recipientName",
@@ -51,6 +71,8 @@ const countryDescriptors = {
 	USA: {
 		iso: "USA",
 		label: "United States",
+		countryLabel: "country",
+		requiredSuffix: "is required",
 		fields: [
 			{
 				name: "recipientName",
@@ -106,6 +128,6 @@ function getCountryDescriptor(iso) {
 	return countryDescriptors[iso];
 }
 //#endregion
-export { countryDescriptors, getAvailableCountries, getCountryDescriptor };
+export { countryDescriptors, getAvailableCountries, getCountryDescriptor, satisfiesFieldPattern };
 
 //# sourceMappingURL=country-descriptors.js.map

package/dist/matter/shipping-address/country-descriptors.js.map

@@ -1 +1 @@
-{"version":3,"file":"country-descriptors.js","names":[],"sources":["../../../src/matter/shipping-address/country-descriptors.ts"],"sourcesContent":["/**\n * Country-adaptive shipping address form descriptors.\n *\n * Each descriptor declares the form shape (field set, order, and labels) for a specific country.\n * Descriptors are primarily data — field set, order, and labels — but a `FieldDescriptor` may also\n * carry `required` and `rule`, the two validation facts a country varies. `ShippingAddressFieldset`\n * is the only reader of either (specs/shipping-address-fieldset.md, Decision 3): a field whose\n * descriptor entry is absent is never rendered, so it can carry no requiredness at all.\n * Country adaptation is data-driven; adding a country is a data-only change (a new descriptor entry).\n *\n * Canonical field names must be shared/consistent across descriptors for fields both countries have\n * (recipientName, postalCode, street, number, complement, city, state), so that switching countries\n * preserves shared field values in the batched draft state (Decision 1/Invariant).\n *\n * Per Decision 2, this narrows the RFC's descriptor scope to form shape plus two per-field validation\n * facts: the non-blank recipient name and, per country, the postal code's format. Both descriptors'\n * `postalCode` entry carries a `pattern` rule matching that country's CEP or ZIP shape; every other\n * field's `rule` stays undefined. There is no server-side postal-code validation to fall back on:\n * `shippingAddressUpdate` types `postalCode` as a plain `z.string()`, forwards it verbatim with\n * `clearAddressIfPostalCodeNotFound: false`, and has no try/catch around the upstream call, so a\n * malformed value still returns HTTP 200 with an empty `userErrors` array. This client-side rule is\n * the only postal-code guard in the system today; per-field blur validation and a future\n * @vtex/country-forms adoption remain deferred.\n */\n\nimport type { FieldRule } from '../../particles/field/field.js';\n\n/**\n * Describes a single form field within a country descriptor.\n *\n * @property name - Canonical field name (e.g., \"recipientName\", \"street\", \"neighborhood\").\n *                  Shared field names across descriptors enable draft state preservation on country switch.\n * @property label - Human-readable label for the field. Named `label` (not a key) to allow future\n *                   swapping with i18n keys once the codebase adopts an i18n layer.\n */\nexport type FieldDescriptor = Readonly<{\n  name: string;\n  label: string;\n  /**\n   * Whether the fieldset requires a non-blank value. Read only by ShippingAddressFieldset, which\n   * turns it into the field contract's `rule`. A field whose descriptor entry is absent is not\n   * rendered, so it can carry no requiredness at all — that is the point (Decision 3).\n   */\n  required?: boolean;\n  /**\n   * Extra react-hook-form rules for this field in this country: pattern, minLength, and so on.\n   * Merged under the generated `required`. Only `postalCode` carries one today.\n   */\n  rule?: FieldRule;\n}>;\n\n/**\n * Describes the form shape for a single country.\n *\n * @property iso - ISO 3166-1 alpha-3 country code (e.g., \"BRA\", \"USA\"). Must be a valid 3-letter code\n *                 matching the Address.country field type (plain String!, ISO alpha-3 by convention).\n * @property label - Human-readable country name for the country selector (e.g., \"Brazil\", \"United States\").\n *                   Named `label` (not a key) to allow future swapping with i18n keys.\n * @property fields - Ordered field set for this country. Order defines the visual order in the form.\n *                    Only fields this country uses are listed; absent fields are not rendered.\n */\nexport type CountryDescriptor = Readonly<{\n  iso: string;\n  label: string;\n  fields: readonly FieldDescriptor[];\n}>;\n\n/**\n * Brazil (BRA) address form descriptor.\n *\n * Field order:\n * 1. recipientName — recipient of the package\n * 2. street — street name\n * 3. number — street number\n * 4. complement — apartment, suite, etc. (optional per GraphQL but no form-level validation)\n * 5. neighborhood — bairro (BR-specific, not in US form)\n * 6. city — city name\n * 7. state — state/UF code (canonical name shared with US, though US calls it state abbreviation)\n * 8. postalCode — CEP format, client-validated via `rule` (8 digits, hyphen after the fifth optional)\n */\nconst brDescriptor: CountryDescriptor = {\n  iso: 'BRA',\n  label: 'Brasil',\n  fields: [\n    { name: 'recipientName', label: 'nome do destinatário', required: true },\n    { name: 'street', label: 'rua' },\n    { name: 'number', label: 'número' },\n    { name: 'complement', label: 'complemento (opcional)' },\n    { name: 'neighborhood', label: 'bairro' },\n    { name: 'city', label: 'cidade' },\n    { name: 'state', label: 'estado' },\n    {\n      name: 'postalCode',\n      label: 'cep',\n      rule: { pattern: { value: /^\\d{5}-?\\d{3}$/, message: 'cep inválido' } },\n    },\n  ],\n};\n\n/**\n * United States (USA) address form descriptor.\n *\n * Field order:\n * 1. recipientName — recipient of the package\n * 2. street — street name\n * 3. number — street number\n * 4. complement — apartment, suite, etc. (optional per GraphQL but no form-level validation)\n * 5. city — city name\n * 6. state — state abbreviation (canonical name shared with BR for draft preservation)\n * 7. postalCode — ZIP/ZIP+4 format, client-validated via `rule` (5 digits, optional 4-digit\n *    extension, hyphen before it optional either way — accepts both `02101-1234` and `021011234`)\n *\n * Note: neighborhood is not included in the US v1 form. If the shopper switches from BR to US,\n * the neighborhood value is retained in the draft but hidden (descriptor controls visibility only);\n * switching back to BR resurfaces it.\n */\nconst usaDescriptor: CountryDescriptor = {\n  iso: 'USA',\n  label: 'United States',\n  fields: [\n    { name: 'recipientName', label: 'recipient name', required: true },\n    { name: 'street', label: 'street' },\n    { name: 'number', label: 'number' },\n    { name: 'complement', label: 'apartment, suite, etc. (optional)' },\n    { name: 'city', label: 'city' },\n    { name: 'state', label: 'state' },\n    {\n      name: 'postalCode',\n      label: 'zip code',\n      rule: { pattern: { value: /^\\d{5}(-?\\d{4})?$/, message: 'invalid zip code' } },\n    },\n  ],\n};\n\n/**\n * All available country descriptors, keyed by ISO alpha-3 code.\n *\n * The country selector lists only countries with a descriptor; a descriptor-less country is unreachable.\n * Adding a country is a data-only change: add a new CountryDescriptor entry here.\n */\nexport const countryDescriptors: Readonly<Record<string, CountryDescriptor>> = {\n  BRA: brDescriptor,\n  USA: usaDescriptor,\n};\n\n/**\n * Returns an ordered list of available country ISO codes (those with a descriptor).\n *\n * @returns ISO alpha-3 codes of all implemented countries, in definition order.\n */\nexport function getAvailableCountries(): readonly string[] {\n  return Object.keys(countryDescriptors);\n}\n\n/**\n * Retrieves the descriptor for a given country.\n *\n * @param iso - ISO 3166-1 alpha-3 country code (e.g., \"BRA\", \"USA\")\n * @returns The CountryDescriptor for the country, or undefined if not implemented.\n */\nexport function getCountryDescriptor(iso: string): CountryDescriptor | undefined {\n  return countryDescriptors[iso];\n}\n"],"mappings":";;;;;;AA4IA,MAAa,qBAAkE;CAC7E,KAAK;EA5DL,KAAK;EACL,OAAO;EACP,QAAQ;GACN;IAAE,MAAM;IAAiB,OAAO;IAAwB,UAAU;GAAK;GACvE;IAAE,MAAM;IAAU,OAAO;GAAM;GAC/B;IAAE,MAAM;IAAU,OAAO;GAAS;GAClC;IAAE,MAAM;IAAc,OAAO;GAAyB;GACtD;IAAE,MAAM;IAAgB,OAAO;GAAS;GACxC;IAAE,MAAM;IAAQ,OAAO;GAAS;GAChC;IAAE,MAAM;IAAS,OAAO;GAAS;GACjC;IACE,MAAM;IACN,OAAO;IACP,MAAM,EAAE,SAAS;KAAE,OAAO;KAAkB,SAAS;IAAe,EAAE;GACxE;EACF;CA6CK;CACL,KAAK;EAzBL,KAAK;EACL,OAAO;EACP,QAAQ;GACN;IAAE,MAAM;IAAiB,OAAO;IAAkB,UAAU;GAAK;GACjE;IAAE,MAAM;IAAU,OAAO;GAAS;GAClC;IAAE,MAAM;IAAU,OAAO;GAAS;GAClC;IAAE,MAAM;IAAc,OAAO;GAAoC;GACjE;IAAE,MAAM;IAAQ,OAAO;GAAO;GAC9B;IAAE,MAAM;IAAS,OAAO;GAAQ;GAChC;IACE,MAAM;IACN,OAAO;IACP,MAAM,EAAE,SAAS;KAAE,OAAO;KAAqB,SAAS;IAAmB,EAAE;GAC/E;EACF;CAWK;AACP;;;;;;AAOA,SAAgB,wBAA2C;CACzD,OAAO,OAAO,KAAK,kBAAkB;AACvC;;;;;;;AAQA,SAAgB,qBAAqB,KAA4C;CAC/E,OAAO,mBAAmB;AAC5B"}
+{"version":3,"file":"country-descriptors.js","names":[],"sources":["../../../src/matter/shipping-address/country-descriptors.ts"],"sourcesContent":["/**\n * Country-adaptive shipping address form descriptors.\n *\n * Each descriptor declares the form shape (field set, order, and labels) for a specific country.\n * Descriptors are primarily data — field set, order, and labels — but a `FieldDescriptor` may also\n * carry `required` and `rule`, the two validation facts a country varies. `ShippingAddressFieldset`\n * is the only reader of `required` (specs/shipping-address-fieldset.md, Decision 3): a field whose\n * descriptor entry is absent is never rendered, so it can carry no requiredness at all. `rule.pattern`\n * has two readers: the fieldset, through react-hook-form, and `satisfiesFieldPattern` below, which\n * `BillingAddress` applies to its own submit gate and field errors. A descriptor also carries the two\n * strings a country's form speaks for itself — the Country label and the required-message suffix — so\n * no copy of the delivery form is hardcoded in the fieldset.\n * Country adaptation is data-driven; adding a country is a data-only change (a new descriptor entry).\n *\n * Canonical field names must be shared/consistent across descriptors for fields both countries have\n * (recipientName, postalCode, street, number, complement, city, state), so that switching countries\n * preserves shared field values in the batched draft state (Decision 1/Invariant).\n *\n * Per Decision 2, this narrows the RFC's descriptor scope to form shape plus two per-field validation\n * facts: the non-blank recipient name and, per country, the postal code's format. Both descriptors'\n * `postalCode` entry carries a `pattern` rule matching that country's CEP or ZIP shape; every other\n * field's `rule` stays undefined. There is no server-side postal-code validation to fall back on:\n * `shippingAddressUpdate` types `postalCode` as a plain `z.string()`, forwards it verbatim with\n * `clearAddressIfPostalCodeNotFound: false`, and has no try/catch around the upstream call, so a\n * malformed value still returns HTTP 200 with an empty `userErrors` array. This client-side rule is\n * the only postal-code guard in the system today. The two forms apply it on different triggers: the\n * billing form judges a touched field on every render (through `getFieldIssue`, which reads\n * `satisfiesFieldPattern`), touching it on blur or when a refused submit focuses it, while the\n * delivery form's react-hook-form rule runs on submit and re-validates after it. A future\n * @vtex/country-forms adoption remains deferred.\n */\n\nimport type { FieldRule, FieldRuleConstraint } from '../../particles/field/field.js';\n\n/**\n * A descriptor's validation rule: a `FieldRule` whose `pattern` always carries the message a failing value\n * shows. A bare `RegExp` is not accepted, so both forms of a country's address read the one message for\n * one rule and no consumer needs a fallback string of its own.\n */\nexport type FieldDescriptorRule = Omit<FieldRule, 'pattern'> &\n  Readonly<{\n    pattern?: FieldRuleConstraint<RegExp>;\n  }>;\n\n/**\n * Describes a single form field within a country descriptor.\n *\n * @property name - Canonical field name (e.g., \"recipientName\", \"street\", \"neighborhood\").\n *                  Shared field names across descriptors enable draft state preservation on country switch.\n * @property label - Human-readable label for the field. Named `label` (not a key) to allow future\n *                   swapping with i18n keys once the codebase adopts an i18n layer.\n */\nexport type FieldDescriptor = Readonly<{\n  name: string;\n  label: string;\n  /**\n   * Whether the fieldset requires a non-blank value. Read only by ShippingAddressFieldset, which\n   * turns it into the field contract's `rule`. A field whose descriptor entry is absent is not\n   * rendered, so it can carry no requiredness at all — that is the point (Decision 3).\n   */\n  required?: boolean;\n  /**\n   * Extra react-hook-form rules for this field in this country: pattern, minLength, and so on.\n   * Merged under the generated `required`. Only `postalCode` carries one today. `pattern` is also read\n   * by `satisfiesFieldPattern`, for forms that are not built on react-hook-form, and its `message` is the\n   * copy every form shows for it.\n   */\n  rule?: FieldDescriptorRule;\n}>;\n\n/**\n * Describes the form shape for a single country.\n *\n * @property iso - ISO 3166-1 alpha-3 country code (e.g., \"BRA\", \"USA\"). Must be a valid 3-letter code\n *                 matching the Address.country field type (plain String!, ISO alpha-3 by convention).\n * @property label - Human-readable country name for the country selector (e.g., \"Brazil\", \"United States\").\n *                   Named `label` (not a key) to allow future swapping with i18n keys.\n * @property countryLabel - Default label of the country selector on this country's form, in the language of\n *                          the form's other copy. An authored `label` on the control wins.\n * @property requiredSuffix - Ends a required field's message (`${label} ${requiredSuffix}`), in the same\n *                            language as the field labels.\n * @property fields - Ordered field set for this country. Order defines the visual order in the form.\n *                    Only fields this country uses are listed; absent fields are not rendered.\n */\nexport type CountryDescriptor = Readonly<{\n  iso: string;\n  label: string;\n  /** Default label of the country selector on this country's form; an authored `label` wins. */\n  countryLabel: string;\n  /** Closes a required field's message: `${label} ${requiredSuffix}`. */\n  requiredSuffix: string;\n  fields: readonly FieldDescriptor[];\n}>;\n\n/**\n * Whether `value` satisfies the field's declared `rule.pattern`. A field with no pattern, or a blank\n * value (empty or whitespace-only: blankness is the required rule's business, and a form that trims\n * before judging, as `BillingAddress` does, reads such a value as required, never as a format failure),\n * satisfies it. A non-blank value is tested raw, equivalent to the predicate react-hook-form applies\n * (`value.match(regex) !== null`), so both forms agree on every non-blank value. Blank values are the\n * one deliberate divergence: react-hook-form skips the pattern only for `''`, so for `'   '` the\n * delivery form runs the pattern and reports the format, while this helper reports it satisfied and\n * leaves the verdict to the required rule. A caller that needs react-hook-form's exact verdict on a\n * blank value must not rely on this helper alone. `search` ignores a global regex's `lastIndex`, so\n * the descriptor's shared regex is never written to.\n */\nexport function satisfiesFieldPattern(field: FieldDescriptor, value: string): boolean {\n  const pattern = field.rule?.pattern;\n  if (!pattern || value.trim() === '') return true;\n  return value.search(pattern.value) !== -1;\n}\n\n/**\n * Brazil (BRA) address form descriptor.\n *\n * Field order:\n * 1. recipientName — recipient of the package\n * 2. street — street name\n * 3. number — street number\n * 4. complement — apartment, suite, etc. (optional per GraphQL but no form-level validation)\n * 5. neighborhood — bairro (BR-specific, not in US form)\n * 6. city — city name\n * 7. state — state/UF code (canonical name shared with US, though US calls it state abbreviation)\n * 8. postalCode — CEP format, client-validated via `rule` (8 digits, hyphen after the fifth optional)\n */\nconst brDescriptor: CountryDescriptor = {\n  iso: 'BRA',\n  label: 'Brasil',\n  countryLabel: 'país',\n  requiredSuffix: 'é obrigatório',\n  fields: [\n    { name: 'recipientName', label: 'nome do destinatário', required: true },\n    { name: 'street', label: 'rua' },\n    { name: 'number', label: 'número' },\n    { name: 'complement', label: 'complemento (opcional)' },\n    { name: 'neighborhood', label: 'bairro' },\n    { name: 'city', label: 'cidade' },\n    { name: 'state', label: 'estado' },\n    {\n      name: 'postalCode',\n      label: 'cep',\n      rule: { pattern: { value: /^\\d{5}-?\\d{3}$/, message: 'cep inválido' } },\n    },\n  ],\n};\n\n/**\n * United States (USA) address form descriptor.\n *\n * Field order:\n * 1. recipientName — recipient of the package\n * 2. street — street name\n * 3. number — street number\n * 4. complement — apartment, suite, etc. (optional per GraphQL but no form-level validation)\n * 5. city — city name\n * 6. state — state abbreviation (canonical name shared with BR for draft preservation)\n * 7. postalCode — ZIP/ZIP+4 format, client-validated via `rule` (5 digits, optional 4-digit\n *    extension, hyphen before it optional either way — accepts both `02101-1234` and `021011234`)\n *\n * Note: neighborhood is not included in the US v1 form. If the shopper switches from BR to US,\n * the neighborhood value is retained in the draft but hidden (descriptor controls visibility only);\n * switching back to BR resurfaces it.\n */\nconst usaDescriptor: CountryDescriptor = {\n  iso: 'USA',\n  label: 'United States',\n  countryLabel: 'country',\n  requiredSuffix: 'is required',\n  fields: [\n    { name: 'recipientName', label: 'recipient name', required: true },\n    { name: 'street', label: 'street' },\n    { name: 'number', label: 'number' },\n    { name: 'complement', label: 'apartment, suite, etc. (optional)' },\n    { name: 'city', label: 'city' },\n    { name: 'state', label: 'state' },\n    {\n      name: 'postalCode',\n      label: 'zip code',\n      rule: { pattern: { value: /^\\d{5}(-?\\d{4})?$/, message: 'invalid zip code' } },\n    },\n  ],\n};\n\n/**\n * All available country descriptors, keyed by ISO alpha-3 code.\n *\n * The country selector lists only countries with a descriptor; a descriptor-less country is unreachable.\n * Adding a country is a data-only change: add a new CountryDescriptor entry here.\n */\nexport const countryDescriptors: Readonly<Record<string, CountryDescriptor>> = {\n  BRA: brDescriptor,\n  USA: usaDescriptor,\n};\n\n/**\n * Returns an ordered list of available country ISO codes (those with a descriptor).\n *\n * @returns ISO alpha-3 codes of all implemented countries, in definition order.\n */\nexport function getAvailableCountries(): readonly string[] {\n  return Object.keys(countryDescriptors);\n}\n\n/**\n * Retrieves the descriptor for a given country.\n *\n * @param iso - ISO 3166-1 alpha-3 country code (e.g., \"BRA\", \"USA\")\n * @returns The CountryDescriptor for the country, or undefined if not implemented.\n */\nexport function getCountryDescriptor(iso: string): CountryDescriptor | undefined {\n  return countryDescriptors[iso];\n}\n"],"mappings":";;;;;;;;;;;;;AA0GA,SAAgB,sBAAsB,OAAwB,OAAwB;CACpF,MAAM,UAAU,MAAM,MAAM;CAC5B,IAAI,CAAC,WAAW,MAAM,KAAK,MAAM,IAAI,OAAO;CAC5C,OAAO,MAAM,OAAO,QAAQ,KAAK,MAAM;AACzC;;;;;;;AA+EA,MAAa,qBAAkE;CAC7E,KAAK;EAhEL,KAAK;EACL,OAAO;EACP,cAAc;EACd,gBAAgB;EAChB,QAAQ;GACN;IAAE,MAAM;IAAiB,OAAO;IAAwB,UAAU;GAAK;GACvE;IAAE,MAAM;IAAU,OAAO;GAAM;GAC/B;IAAE,MAAM;IAAU,OAAO;GAAS;GAClC;IAAE,MAAM;IAAc,OAAO;GAAyB;GACtD;IAAE,MAAM;IAAgB,OAAO;GAAS;GACxC;IAAE,MAAM;IAAQ,OAAO;GAAS;GAChC;IAAE,MAAM;IAAS,OAAO;GAAS;GACjC;IACE,MAAM;IACN,OAAO;IACP,MAAM,EAAE,SAAS;KAAE,OAAO;KAAkB,SAAS;IAAe,EAAE;GACxE;EACF;CA+CK;CACL,KAAK;EA3BL,KAAK;EACL,OAAO;EACP,cAAc;EACd,gBAAgB;EAChB,QAAQ;GACN;IAAE,MAAM;IAAiB,OAAO;IAAkB,UAAU;GAAK;GACjE;IAAE,MAAM;IAAU,OAAO;GAAS;GAClC;IAAE,MAAM;IAAU,OAAO;GAAS;GAClC;IAAE,MAAM;IAAc,OAAO;GAAoC;GACjE;IAAE,MAAM;IAAQ,OAAO;GAAO;GAC9B;IAAE,MAAM;IAAS,OAAO;GAAQ;GAChC;IACE,MAAM;IACN,OAAO;IACP,MAAM,EAAE,SAAS;KAAE,OAAO;KAAqB,SAAS;IAAmB,EAAE;GAC/E;EACF;CAWK;AACP;;;;;;AAOA,SAAgB,wBAA2C;CACzD,OAAO,OAAO,KAAK,kBAAkB;AACvC;;;;;;;AAQA,SAAgB,qBAAqB,KAA4C;CAC/E,OAAO,mBAAmB;AAC5B"}

package/dist/matter/shipping-address/shipping-address.js

@@ -1,18 +1,19 @@
 "use client";
 import { defineComponent } from "../../core/dist/define-component.js";
 import "../../core/dist/index.js";
-import { Field, FieldBinding, FieldsetFieldContext, useFieldsetField, useFieldsetFieldNames, useNoAncestorFieldset } from "../../particles/field/field.js";
+import { Field, FieldBinding, FieldsetFieldContext, readBaseline, useFieldsetField, useFieldsetFieldNames, useNoAncestorFieldset } from "../../particles/field/field.js";
 import { useActionsOverride } from "../../sdk/actions/actions-override-context.js";
 import { useDataOverride } from "../../sdk/data/data-override-context.js";
-import { Fieldset } from "../../particles/fieldset/fieldset.js";
-import { getAvailableCountries, getCountryDescriptor } from "./country-descriptors.js";
+import { resolveAuthoredCopy } from "../../utils/resolve-authored-copy.js";
 import { useFormRegistry } from "../../particles/form/form.js";
 import { useEntityDataResolved } from "../../sdk/data/entity-resolution-context.js";
 import { useReactiveDataSettled } from "../../sdk/data/use-reactive-data-settled.js";
+import { Fieldset } from "../../particles/fieldset/fieldset.js";
+import { getAvailableCountries, getCountryDescriptor } from "./country-descriptors.js";
 import { FieldSelect } from "../../particles/select/field-select.js";
 import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { useWatch } from "react-hook-form";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { useFormContext, useWatch } from "react-hook-form";
 //#region src/matter/shipping-address/shipping-address.tsx
 /**
 * Shipping address step (T2 — Enter and save the delivery address).
@@ -97,11 +98,11 @@ const FIELD_AUTOCOMPLETE = {
 * declaration of the baseline. The blank check it used to hand-write alongside lives in
 * `resolveRequiredness` now, installed for every bound control rather than only for this one.
 */
-function buildRule(field, label) {
+function buildRule(field, label, requiredSuffix) {
 	if (!field.required) return field.rule;
 	return {
 		...field.rule,
-		required: `${label} é obrigatório`
+		required: `${label} ${requiredSuffix}`
 	};
 }
 /** Keeps only the AddressDraft keys `values` actually defines — a field no control composed is absent, not `undefined`. */
@@ -349,6 +350,49 @@ const ShippingAddressCountryControlDefinition = defineComponent({
 	} },
 	guideline: "Country selector; lists only countries with an implemented descriptor. Must be a descendant of ShippingAddressFieldset, which provides the shipping-address context this control requires. Recomposable: compose Field.Label, FieldSelect.Root and Field.Error as children, in any order; a childless composition keeps the default label-select-error order."
 });
+/** The message a constrained rule member carries; a bare value (or a bare `RegExp`) carries none. */
+function messageOf(constraint) {
+	return typeof constraint === "object" && !(constraint instanceof RegExp) ? constraint.message : "";
+}
+/**
+* Every static message a rule carries, in a fixed order: the `required` copy in any of its three shapes,
+* then the message of each constrained member. A `validate` record has no static copy, so it adds none.
+*/
+function messagesOf(rule) {
+	return [
+		readBaseline(rule).message ?? "",
+		messageOf(rule?.pattern),
+		messageOf(rule?.min),
+		messageOf(rule?.max),
+		messageOf(rule?.minLength),
+		messageOf(rule?.maxLength)
+	];
+}
+/**
+* An error already on screen keeps the message of the rule that raised it, so a country switch would
+* leave "é obrigatório" under a USA form until the shopper edits or submits again. A bound control
+* therefore revalidates itself when the copy of its own rule changes while it carries an error: that
+* re-words it from the new rule without newly flagging a field the shopper has not reached.
+*
+* It runs inside the control, as an effect of the component that renders the field's own subtree, so it
+* always fires after that field's registration — `useController` re-registers `rules` during render, and
+* descendants' effects precede their parent's — and never validates against the previous rule, whichever
+* of the two the registration becomes. The first run counts as a change too: a field that remounts after
+* a country without it keeps its error across the unmount (`shouldUnregister` being false) and comes
+* back carrying the old wording.
+*/
+function useRewordErroredField(name, rule) {
+	const { getFieldState, trigger } = useFormContext();
+	const copy = messagesOf(rule).join("\n");
+	useEffect(() => {
+		if (getFieldState(name).error) trigger(name);
+	}, [
+		copy,
+		name,
+		getFieldState,
+		trigger
+	]);
+}
 /**
 * ShippingAddressFieldset — this entity's root: same data, same action as a page-level submit
 * would use, dispatched at form-submit time instead of through a button of its own. Registers one
@@ -408,12 +452,13 @@ function ShippingAddressFieldset({ defaultCountry = "BRA", skeletonCount = SHIPP
 	});
 	const activeCountry = typeof watchedCountry === "string" && watchedCountry || seed.country;
 	const descriptor = getCountryDescriptor(activeCountry);
+	const requiredSuffix = descriptor?.requiredSuffix ?? "";
 	const fieldFor = useCallback((key) => descriptor?.fields.find((f) => f.name === key), [descriptor]);
 	const seedFor = useCallback((key) => seed[key], [seed]);
 	const ruleFor = useCallback((key, label) => {
 		const field = fieldFor(key);
-		return field ? buildRule(field, label ?? field.label) : void 0;
-	}, [fieldFor]);
+		return field ? buildRule(field, label, requiredSuffix) : void 0;
+	}, [fieldFor, requiredSuffix]);
 	const countryOptions = useMemo(() => getAvailableCountries().map((iso) => ({
 		value: iso,
 		label: getCountryDescriptor(iso)?.label ?? iso
@@ -510,18 +555,20 @@ function ShippingAddressFieldsetSkeleton({ count = SHIPPING_ADDRESS_SKELETON_ROW
 ShippingAddressFieldset.Skeleton = ShippingAddressFieldsetSkeleton;
 function BoundAddressTextField({ fieldKey, slug, className, label, placeholder, children, fieldsetCtx, fieldDescriptor }) {
 	const name = useFieldsetField(SHIPPING_ADDRESS_NAMESPACE, fieldKey);
-	const resolvedLabel = label ?? fieldDescriptor.label;
+	const resolvedLabel = resolveAuthoredCopy(label, fieldDescriptor.label);
+	const rule = fieldsetCtx.ruleFor(fieldKey, resolvedLabel);
+	useRewordErroredField(name, rule);
 	return /* @__PURE__ */ jsx(FieldBinding, {
 		name,
 		label: resolvedLabel,
 		placeholder,
 		defaultValue: fieldsetCtx.seedFor(fieldKey),
-		rule: fieldsetCtx.ruleFor(fieldKey, resolvedLabel),
+		rule,
 		autoComplete: FIELD_AUTOCOMPLETE[fieldKey],
 		children: /* @__PURE__ */ jsx(Field.Root, {
 			className,
 			"data-fs-shipping-address-field": slug,
-			children: children ?? /* @__PURE__ */ jsxs(Fragment, { children: [
+			children: children ?? /* @__PURE__ */ jsxs(Fragment$1, { children: [
 				/* @__PURE__ */ jsx(Field.Label, {}),
 				/* @__PURE__ */ jsx(Field.Control, {}),
 				/* @__PURE__ */ jsx(Field.Error, {})
@@ -673,16 +720,17 @@ function ShippingAddressCountryControl({ className, label, placeholder, children
 	return /* @__PURE__ */ jsx(BoundShippingAddressCountryControl, {
 		className,
 		label,
+		defaultLabel: fieldsetCtx.descriptor.countryLabel,
 		placeholder,
 		fieldsetCtx,
 		children
 	});
 }
-function BoundShippingAddressCountryControl({ className, label, placeholder, children, fieldsetCtx }) {
+function BoundShippingAddressCountryControl({ className, label, defaultLabel, placeholder, children, fieldsetCtx }) {
 	const name = useFieldsetField(SHIPPING_ADDRESS_NAMESPACE, "country");
 	return /* @__PURE__ */ jsx(FieldBinding, {
 		name,
-		label: label ?? "país",
+		label: resolveAuthoredCopy(label, defaultLabel),
 		placeholder: placeholder ?? fieldsetCtx.descriptor?.label,
 		defaultValue: fieldsetCtx.seedFor("country"),
 		options: fieldsetCtx.countryOptions,
@@ -690,7 +738,7 @@ function BoundShippingAddressCountryControl({ className, label, placeholder, chi
 		children: /* @__PURE__ */ jsx(Field.Root, {
 			className,
 			"data-fs-shipping-address-field": "country",
-			children: children ?? /* @__PURE__ */ jsxs(Fragment, { children: [
+			children: children ?? /* @__PURE__ */ jsxs(Fragment$1, { children: [
 				/* @__PURE__ */ jsx(Field.Label, {}),
 				/* @__PURE__ */ jsx(FieldSelect.Root, {}),
 				/* @__PURE__ */ jsx(Field.Error, {})