@vtex/faststore 0.0.10 → 0.0.11

package/dist/matter/payment/payment.js.map

@@ -1 +1 @@
-{"version":3,"file":"payment.js","names":[],"sources":["../../../src/matter/payment/payment.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport { type ComponentPropsWithRef, createContext, useContext, useId, useLayoutEffect, useMemo } 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 { PaymentSubmissionProvider } from '../../sdk/payment/submission-registry.js';\nimport { resolveAuthoredCopy } from '../../utils/resolve-authored-copy.js';\nimport { PaymentCardCaptureProvider, type PaymentCartData } from './payment-card-capture.js';\nimport {\n  type PaymentMethodSelection,\n  type PaymentSectionData,\n  resolveCanRevealCardPayment,\n  resolvePreselectionCandidateId,\n  splitCardMethods,\n  usePaymentMethodSelection,\n} from './use-payment-method-selection.js';\n\n/**\n * The `PaymentSection` matter root (specs/payment-section-root.md, T5 of the Credit Card epic;\n * docs/features/credit-card/rfc.md § D1). `PaymentSectionRoot` is the always-visible presentation\n * variant over the `Payment` entity T1 projects: it owns a thin `fragment` (the method list with its\n * server-driven validator config, plus the current selection), runs the shared\n * `usePaymentMethodSelection` engine, and provides the `payment` context its leaves read — the card\n * entry (T7), cardholder document (T8), installments (T9), save-card (T10), billing address (T11),\n * saved cards (T12), and place-order CTA (T14) — through the guarded `usePayment()` hook rather than\n * drilled props (ADR-0009). `PaymentSectionController` (payment-controller.tsx) is the second provider\n * of the same context for a collapsed overlay surface; ADR-0009 matches by contract identifier, so the\n * two substitute for one another with zero edits to any consumer.\n *\n * \"Thin\" means no `installmentOptions` (T9's own fragment), no `savedCards` (T12's), and no\n * `selectedInstallment` (T6's) — the heavy, optional, and iterated subtrees ADR-0011/ADR-0012 split out.\n * `methods[].validator` *is* selected here: it is a non-normalized value object off `Payment.methods`\n * that cannot be subscribed separately, and T7 tests every method's `numberRegex` to detect a network.\n *\n * `children` is the section composition, not a per-method template — the method picker is\n * `PaymentMethodList`, an independently placeable part with its own hooks.\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — raw template literal, matching the merged `payment-summary` sibling. The codegen\n// `documents` glob does not scan `src/matter/payment*`, so the typed `graphql()` factory is\n// unavailable here; `data-component-contract.test.ts` validates this fragment against the real schema.\n//\n// Selects `payment { id }` so Apollo's InMemoryCache normalizes `Payment` by id — required for the\n// `Payment` entity that `paymentMethodSelect` echoes back to update the same cache entity this\n// fragment reads. `fetchStrategy: 'reactive'`'s no-refetch guarantee holds only if both sides\n// normalize to one entity.\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment PaymentSectionData on Query {\n    payment {\n      __typename\n      id\n      methods {\n        __typename\n        id\n        name\n        groupName\n        validator {\n          __typename\n          numberMask\n          numberRegex\n          cvvMask\n          cvvRegex\n          cvvRequired\n          expirationRequired\n          holderNameRequired\n          billingAddressRequired\n          documentDisplayable\n          documentRequired\n        }\n      }\n      selectedMethodId\n      selectedAccountId\n      selectedBin\n      storeCountryCode\n      countries {\n        __typename\n        countryCode\n        documents {\n          __typename\n          type\n          displayable\n          required\n        }\n      }\n    }\n    cart {\n      __typename\n      id\n      total {\n        __typename\n        amount\n        currencyCode\n      }\n    }\n  }\n`;\n\n/**\n * The default payment-group scope: credit and debit (T140, FR-2, Decision 2). Both strings are\n * store-configured, so a store whose groups differ must set `group` explicitly; `group: ''` scopes\n * nothing (specs/payment-section-root.md § Documentation Gaps item 1). Widened from a single string to\n * a set (Decision 1) — a public API break for any consumer importing it directly (Interfaces).\n */\n/**\n * The roots' keyed `$data` (ADR-0015, arity 2): the `Payment` slice the selection engine reads, and the\n * cart total `add_payment_info` needs (moved here from `CardEntry`, which reads no cart).\n */\nexport type PaymentSectionRootData = {\n  payment?: PaymentSectionData;\n  cart?: PaymentCartData;\n} | null;\n\nexport const DEFAULT_METHOD_GROUP: readonly string[] = ['creditCardPaymentGroup', 'debitCardPaymentGroup'];\n\n// ---------------------------------------------------------------------------\n// Payment context — provided by both section roots, read by every leaf\n// ---------------------------------------------------------------------------\n\n/**\n * The `payment` context contract, normative for T7–T12 and T14. Everything the selection engine\n * resolves, plus the overlay disclosure. What is deliberately absent is part of the contract too: no\n * card number, CVV, expiration, or holder name (RFC D13 — they live only in the card entry's local\n * state); no submission channel for the place-order sequence, which is the separate, narrow\n * `PaymentSubmissionProvider` below (T13) precisely so no card-shaped value ever joins this contract;\n * no `installmentOptions` / `savedCards` / `selectedInstallment` (their owners' fragments); and no\n * optimistic mirror of the persisted selection.\n */\nexport type PaymentContextValue = Readonly<\n  PaymentMethodSelection & {\n    /** The collapsed surface's disclosure state. Always `true` under `PaymentSectionRoot`. */\n    open: boolean;\n    /**\n     * Drives the collapsed surface. A no-op under `PaymentSectionRoot`, so a leaf written for the\n     * overlay composes unchanged inline. Selecting a method never closes the surface on its own — the\n     * shopper still has a card to type — so closing is the composition's call (Decision 5).\n     */\n    setOpen: (open: boolean) => void;\n  }\n>;\n\nconst PAYMENT_CONTEXT_UNSET = Symbol('PaymentContextUnset');\n\nconst PaymentContextInternal = createContext<PaymentContextValue | typeof PAYMENT_CONTEXT_UNSET>(PAYMENT_CONTEXT_UNSET);\n\n/** The provider both section roots render. Exported for `PaymentSectionController`. */\nexport const PaymentContext = PaymentContextInternal as React.Context<PaymentContextValue>;\n\n/**\n * Read the payment section's selection state, draft, and overlay disclosure from the nearest\n * `PaymentSectionRoot` or `PaymentSectionController`. Throws outside either subtree — a misplaced\n * consumer is a composition bug the author should see immediately, not a silent degrade to an empty\n * selection — mirroring `useSession()` / `useDeliveryOptions()`. ADR-0009's compiler check catches the\n * same mistake before emission for schema-authored pages; this is the defense-in-depth layer for\n * Storybook, tests, and hand-written JSX.\n */\nexport function usePayment(): PaymentContextValue {\n  const ctx = useContext(PaymentContextInternal);\n  if (ctx === PAYMENT_CONTEXT_UNSET) {\n    throw new Error('usePayment() must be used inside a <PaymentSectionRoot> or <PaymentSectionController> subtree.');\n  }\n  return ctx;\n}\n\nconst NO_DISCLOSURE = () => {};\n\n// ---------------------------------------------------------------------------\n// Props\n// ---------------------------------------------------------------------------\n\nexport type PaymentSectionRootProps = ComponentPropsWithRef<'div'> & {\n  /**\n   * Scopes the method list to a **set** of `PaymentMethod.groupName` values — a method is in scope\n   * when its `groupName` is a member (T140, FR-1, Decision 1). A single string is still accepted and\n   * scopes to exactly that one group (FR-4, US-3). T1's read model is method-agnostic and assigns the\n   * narrowing to the consumer; this prop supplies no method, label, or ordering — the list itself is\n   * fragment data. An empty string scopes nothing.\n   */\n  group?: string | readonly string[];\n  /** Keyed `{ payment, cart }` forwarded by the reactive runtime (arity-2 fragment, ADR-0015). */\n  $data?: PaymentSectionRootData;\n  /** Compiler-injected action surface; carries `payment.setMethod`, `payment.sendPayments`, and `analytics.track`. */\n  $actions?: ComponentActions;\n};\n\n/** Renders its own controls from the context's method list — `children` would have nothing to template. */\nexport type PaymentMethodListProps = Omit<ComponentPropsWithRef<'div'>, 'children'> & {\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   * The single card control's name (T171, Decision 8). The control stands for every in-scope\n   * credit/debit method at once, so it cannot take its name from one of their `method.name` values the\n   * way a per-network row did — it is authored copy instead, defaulting to the PRD's own string.\n   * Resolved through `resolveAuthoredCopy` exactly as `legend` is, so an authored empty or\n   * whitespace-only string falls back rather than rendering a nameless control.\n   */\n  cardLabel?: string;\n};\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const PaymentSectionRootDefinition = defineComponent<PaymentSectionRootProps>({\n  name: 'PaymentSectionRoot',\n  importPath: '@vtex/faststore/components',\n  component: PaymentSectionRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  actions: { payment: ['setMethod', 'sendPayments'], analytics: ['track'] },\n  providesContext: ['payment', 'card-capture'],\n  hardened: true,\n  editor: { label: 'Payment Section', category: 'commerce' },\n  schema: {\n    // A literal, not `DEFAULT_METHOD_GROUP`: the native catalog builder extracts `schema` statically\n    // and silently drops an identifier-valued default, so the built entry would carry no default and\n    // the compiler would emit the section unscoped. `payment.test.tsx` asserts the literal matches the\n    // constant, and that the built catalog kept the default.\n    // T140, Decision 2/OQ-6: `type: 'array'` — no code path in packages/sukima/crates/sukima-core/\n    // validates an authored prop's JSON value against this declared type, so a store's existing bare\n    // string keeps compiling. No `items`: an enum would validate against a closed set of group names,\n    // which is wrong for a store that renamed its group (OQ-3) — the exact fragility Decision 1 closes.\n    group: {\n      type: 'array',\n      default: ['creditCardPaymentGroup', 'debitCardPaymentGroup'],\n      label: 'Payment method group',\n    },\n  },\n  guideline:\n    \"Root of the checkout payment section: reads the payment methods and the current selection from the order form and provides the 'payment' context every payment leaf needs and the 'card-capture' context CardEntry needs, so place CardEntry, CardholderDocument, Installments, SaveCard, BillingAddress, SavedCards, PlaceOrder, and PaymentMethodList as its children — none of them render without a payment root ancestor. Renders one container div and no chrome or copy of its own; headings and layout belong to the composition. Selecting a payment option dispatches $actions.payment.setMethod and every subscriber re-renders from the cache with no refetch — and for a card it is the number the shopper types that decides the network, not an option they pick, so PaymentMethodList shows every in-scope credit and debit method as ONE card option. Which methods exist is always real data — never author them as props; group only scopes the list by the store's payment group(s) — defaults to credit and debit together, accepts one group name or a set of them, and set it to \\\"\\\" to show every method, one option each, with no card option. Use PaymentSectionController instead when the section should live in a drawer or modal. See payment.md.\",\n});\n\nexport const PaymentMethodListDefinition = defineComponent<PaymentMethodListProps>({\n  name: 'PaymentMethodList',\n  importPath: '@vtex/faststore/components',\n  component: PaymentMethodList,\n  requiresContext: 'payment',\n  editor: { label: 'Payment Method List', category: 'commerce' },\n  schema: {\n    // T38/T171: inline literals, never identifiers — the native catalog builder extracts `schema`\n    // statically and silently drops an identifier-valued default (INV-8).\n    legend: { type: 'string', default: 'Payment method', label: 'Legend' },\n    cardLabel: { type: 'string', default: 'Pay with Credit / Debit Card', label: 'Card option label' },\n  },\n  guideline:\n    'The payment-method picker: a radio group of the payment options the order form offers, plus the inline selection error (role=\"alert\"). Every in-scope credit and debit method is ONE option — the network comes from the card number the shopper types, never from a row they pick — and any other in-scope method (e.g. Pix) keeps a row of its own; set group to \"\" on the root to switch that off and get one row per method. Selecting an option dispatches the method selection. Selecting a non-card option hides the card form, and the card option brings it back. Place it inside a PaymentSectionRoot, or inside the DialogPopup/DrawerPopup of a PaymentSectionController. It renders its own options from real data, so it takes no children and no method props; author the card option\\'s wording with cardLabel. Keep it composed: it is the only element that surfaces a rejected selection, and the only control that can recover a selection this section does not serve — omit it and a shopper whose persisted method sits outside group has no reachable way back. Must be inside a payment root.',\n});\n\n// ---------------------------------------------------------------------------\n// Implementations\n// ---------------------------------------------------------------------------\n\nexport function PaymentSectionRoot({\n  group = DEFAULT_METHOD_GROUP,\n  $data: $dataProp,\n  $actions: $actionsProp,\n  className,\n  children,\n  ...props\n}: PaymentSectionRootProps) {\n  const $data = useDataOverride($dataProp);\n  const $actions = useActionsOverride($actionsProp);\n  const selection = usePaymentMethodSelection({ group, $data: $data?.payment ?? null, $actions });\n  const payment = useMemo<PaymentContextValue>(\n    () => ({ ...selection, open: true, setOpen: NO_DISCLOSURE }),\n    [selection],\n  );\n\n  return (\n    <PaymentContextInternal value={payment}>\n      <PaymentSubmissionProvider path={selection.draft.path}>\n        <PaymentCardCaptureProvider selection={selection} cart={$data?.cart} $actions={$actions}>\n          <div\n            {...props}\n            className={className}\n            data-fs-payment-section=\"\"\n            {...(selection.draft.path ? { 'data-fs-payment-section-path': selection.draft.path } : {})}\n            // T28, Decision 5: presence attribute only, deliberately never `inert` — `PlaceOrder` composes\n            // as a child of this same container (FR-6), so making it inert here would swallow the CTA's\n            // own role=\"alert\"/role=\"status\" regions, the shopper's only channel for the outcome.\n            {...(selection.placing ? { 'data-fs-payment-section-placing': '' } : {})}\n          >\n            {children}\n          </div>\n        </PaymentCardCaptureProvider>\n      </PaymentSubmissionProvider>\n    </PaymentContextInternal>\n  );\n}\n\n/**\n * The picker's presence state, always emitted so a swatch can surface a row-less container — otherwise\n * a zero-height element under any stacking swatch, and the \"visible empty region\" the section's\n * group-default risk is accepted on. `loading` (still resolving) and `empty` (resolved, nothing in\n * scope) stay distinct: one is a wait, the other a misconfiguration.\n */\nfunction methodListState({ 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 DOM value the collapsed card control carries inside the `RadioGroup`. Base UI requires every\n * radio root to have one, and this control stands for N methods, so there is no `method.id` it could\n * use.\n *\n * It is a radio-group value and nothing else — **never a method id** (INV-1, ADR-0023). It is never\n * dispatched: `handleValueChange` below maps it back to `resolvePreselectionCandidateId`'s answer\n * before calling `selectMethod`, and records card mode through `selectNewCard()`, which dispatches\n * nothing, when there is no candidate (T191, FR-6). The prefix keeps it from ever colliding with a\n * `PaymentMethod.id` a standalone row is bound to.\n */\nconst CARD_CONTROL_VALUE = '__fs-card-control';\n\nexport function PaymentMethodList({ legend, cardLabel, className, ...props }: PaymentMethodListProps) {\n  const {\n    methods,\n    allMethods,\n    persistedMethodId,\n    selectedMethodId,\n    selectionError,\n    selectMethod,\n    selectNewCard,\n    cardModeActive,\n    loading,\n    placing,\n    setMethodListMounted,\n  } = usePayment();\n\n  // T171, FR-1/FR-2: one control for the in-scope card methods, one row for every other in-scope\n  // method. Memoized off the two lists only (NFR-5) — nothing here may widen what re-creates the\n  // `payment` context value, which a keystroke already churns enough.\n  const { collapsedCardMethods, standaloneMethods } = useMemo(\n    () => splitCardMethods({ methods, allMethods }),\n    [methods, allMethods],\n  );\n  // Decision 3: the collapsed control dispatches the *shared* preselection candidate, so the escape\n  // hatch and the preselection can never disagree about whether an id is available.\n  const cardCandidateId = useMemo(() => resolvePreselectionCandidateId(methods), [methods]);\n  const canRevealCardPayment = resolveCanRevealCardPayment({ collapsedCardMethods, standaloneMethods });\n\n  // Decision 2: derived, never bound to one `method.id` — a control standing for N methods has none.\n  // Checked when the persisted selection resolves inside the collapsed set, and when nothing is\n  // persisted at all (PRD REQ-02's \"the card payment option is selected by default\"). The second arm\n  // is a deliberate divergence from the pre-T171 bound-to-`$data` behaviour: the control can read\n  // checked while `$data.selectedMethodId` is still null, having dispatched nothing. `persistedMethodId`\n  // is the raw, unscoped fact on purpose — a persisted method this section does not serve must leave the\n  // control unchecked, which is what keeps it activatable as US-5's way back. T191 (FR-6): card mode is\n  // the third arm, the card option chosen over such a selection or over a non-card one.\n  const cardControlChecked =\n    collapsedCardMethods.length > 0 &&\n    (persistedMethodId === null ||\n      collapsedCardMethods.some((method) => method.id === selectedMethodId) ||\n      cardModeActive);\n\n  // Fix pass, finding R2: registers this instance with the shared engine so the card leaves know an\n  // escape hatch exists before they ever collapse — a section composed with no `PaymentMethodList` at\n  // all must never hide the only remaining way to change the method (typing a new card number).\n  // Retracted unconditionally on unmount, unlike `setPlacing`'s own \"leave it if still placing\"\n  // carve-out: there is no in-flight sequence here for an abandoned instance to still be part of.\n  //\n  // T191, Decision 5 (after T171's Decision 4): what is registered is `canRevealCardPayment`, not the\n  // bare fact of being mounted — whether this list can bring the card form back. A rendered card\n  // option always can, since card mode needs no method id; without one, only a row bound to a card\n  // method can. See `resolveCanRevealCardPayment`'s own doc comment. The dependency list carries it,\n  // so the registration re-runs when the method list resolves.\n  //\n  // Fix pass round 2 (flash regression): `useLayoutEffect`, not `useEffect` — mirroring\n  // `place-order.tsx`'s own `setPlacing` registration, the structurally identical precedent for\n  // publishing a ref-counted fact to this shared engine from a leaf's mount. A passive effect runs\n  // after the browser has already painted, so a root whose persisted selection is genuinely out of\n  // scope committed one real frame with `methodListMounted` still `false` — the collapse (then\n  // `selectionOutOfScope && methodListMounted`, now `cardPaymentCollapsed`) computed `false` for that\n  // frame, painting the card form visible, focusable, and with its security code not yet cleared,\n  // before the registration ever landed and a second commit hid it. A layout effect's own state update\n  // is guaranteed to flush synchronously before the browser paints, so the very first frame a shopper\n  // can ever see already reflects `methodListMounted`. The card leaves read it purely at render time,\n  // not from an effect of their own, so this reorders nothing on that side: whichever commit this\n  // layout effect's own update produces is the one their next render (still pre-paint) sees.\n  const instanceKey = useId();\n  useLayoutEffect(() => {\n    setMethodListMounted(instanceKey, canRevealCardPayment);\n    return () => setMethodListMounted(instanceKey, false);\n  }, [instanceKey, setMethodListMounted, canRevealCardPayment]);\n\n  // INV-1: only an id the read model supplied is ever dispatched. A standalone row's value *is* its own\n  // `method.id`; the collapsed control's value is a DOM value with no method behind it, so it routes\n  // through the shared candidate instead (FR-4). With no candidate to name it records card mode, which\n  // brings the card form back and sends nothing (T191, FR-6, Decision 6).\n  function handleValueChange(value: string) {\n    if (value === CARD_CONTROL_VALUE) {\n      if (cardCandidateId !== null) {\n        selectMethod({ methodId: cardCandidateId });\n      } else {\n        selectNewCard();\n      }\n      return;\n    }\n    selectMethod({ methodId: value });\n  }\n\n  return (\n    <div\n      {...props}\n      className={className}\n      inert={placing}\n      aria-disabled={placing || undefined}\n      data-fs-payment-method-list=\"\"\n      data-fs-payment-method-list-state={methodListState({ loading, count: methods.length })}\n      {...(placing ? { 'data-fs-payment-method-list-placing': '' } : {})}\n    >\n      {selectionError ? (\n        <div role=\"alert\" data-fs-payment-method-list-error=\"\">\n          {selectionError}\n        </div>\n      ) : null}\n      {methods.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-payment-method-list-fieldset=\"\">\n          <Fieldset.Legend>{resolveAuthoredCopy(legend, 'Payment method')}</Fieldset.Legend>\n          <RadioGroup\n            value={cardControlChecked ? CARD_CONTROL_VALUE : (selectedMethodId ?? '')}\n            onValueChange={handleValueChange}\n          >\n            {collapsedCardMethods.length > 0 ? (\n              // One control for every in-scope credit and debit method (FR-1, Decision 1). Both\n              // styling hooks stay exactly where a per-network row carried them — `payment.md`'s\n              // styling table documents them, so a store's swatch keeps its selectors.\n              <RadioRoot value={CARD_CONTROL_VALUE}>\n                <RadioIndicator data-fs-payment-method-indicator=\"\" />\n                <span data-fs-payment-method-name=\"\">\n                  {resolveAuthoredCopy(cardLabel, 'Pay with Credit / Debit Card')}\n                </span>\n              </RadioRoot>\n            ) : null}\n            {standaloneMethods.map((method) => (\n              <RadioRoot key={method.id} value={method.id}>\n                <RadioIndicator data-fs-payment-method-indicator=\"\" />\n                <span data-fs-payment-method-name=\"\">{method.name}</span>\n              </RadioRoot>\n            ))}\n          </RadioGroup>\n        </Fieldset.Root>\n      ) : null}\n    </div>\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"payment.js","names":[],"sources":["../../../src/matter/payment/payment.tsx"],"sourcesContent":["'use client';\n\nimport {\n  type ContentValue,\n  defineComponent,\n  defineContentType,\n  type MessageFieldName,\n  type MessageLocaleProp,\n} from '@vtex/fs-core';\nimport { type ComponentPropsWithRef, createContext, useContext, useId, useLayoutEffect, useMemo } 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 { formatErrorCode } from '../../sdk/i18n/format-error-code.js';\nimport { useMessageFormatter } from '../../sdk/i18n/use-message-formatter.js';\nimport { PaymentSubmissionProvider } from '../../sdk/payment/submission-registry.js';\nimport { PaymentCardCaptureProvider, type PaymentCartData } from './payment-card-capture.js';\nimport {\n  orderMethodListRows,\n  type PaymentMethodSelectErrorCode,\n  type PaymentMethodSelection,\n  type PaymentSectionData,\n  resolveCanRevealCardPayment,\n  resolvePreselectionCandidateId,\n  splitCardMethods,\n  usePaymentMethodSelection,\n} from './use-payment-method-selection.js';\n\n/**\n * The `PaymentSection` matter root (specs/payment-section-root.md, T5 of the Credit Card epic;\n * docs/features/credit-card/rfc.md § D1). `PaymentSectionRoot` is the always-visible presentation\n * variant over the `Payment` entity T1 projects: it owns a thin `fragment` (the method list with its\n * server-driven validator config, plus the current selection), runs the shared\n * `usePaymentMethodSelection` engine, and provides the `payment` context its leaves read — the card\n * entry (T7), cardholder document (T8), installments (T9), save-card (T10), billing address (T11),\n * saved cards (T12), and place-order CTA (T14) — through the guarded `usePayment()` hook rather than\n * drilled props (ADR-0009). `PaymentSectionController` (payment-controller.tsx) is the second provider\n * of the same context for a collapsed overlay surface; ADR-0009 matches by contract identifier, so the\n * two substitute for one another with zero edits to any consumer.\n *\n * \"Thin\" means no `installmentOptions` (T9's own fragment), no `savedCards` (T12's), and no\n * `selectedInstallment` (T6's) — the heavy, optional, and iterated subtrees ADR-0011/ADR-0012 split out.\n * `methods[].validator` *is* selected here: it is a non-normalized value object off `Payment.methods`\n * that cannot be subscribed separately, and T7 tests every method's `numberRegex` to detect a network.\n *\n * `children` is the section composition, not a per-method template — the method picker is\n * `PaymentMethodList`, an independently placeable part with its own hooks.\n */\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment — raw template literal, matching the merged `payment-summary` sibling. The codegen\n// `documents` glob does not scan `src/matter/payment*`, so the typed `graphql()` factory is\n// unavailable here; `data-component-contract.test.ts` validates this fragment against the real schema.\n//\n// Selects `payment { id }` so Apollo's InMemoryCache normalizes `Payment` by id — required for the\n// `Payment` entity that `paymentMethodSelect` echoes back to update the same cache entity this\n// fragment reads. `fetchStrategy: 'reactive'`'s no-refetch guarantee holds only if both sides\n// normalize to one entity.\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment PaymentSectionData on Query {\n    payment {\n      __typename\n      id\n      methods {\n        __typename\n        id\n        name\n        type\n        groupName\n        validator {\n          __typename\n          numberMask\n          numberRegex\n          cvvMask\n          cvvRegex\n          cvvRequired\n          expirationRequired\n          holderNameRequired\n          billingAddressRequired\n          documentDisplayable\n          documentRequired\n        }\n      }\n      selectedMethodId\n      selectedAccountId\n      selectedBin\n      storeCountryCode\n      countries {\n        __typename\n        countryCode\n        documents {\n          __typename\n          type\n          displayable\n          required\n        }\n      }\n    }\n    cart {\n      __typename\n      id\n      total {\n        __typename\n        amount\n        currencyCode\n      }\n    }\n    clientProfile {\n      __typename\n      id\n      firstName\n      lastName\n      phone\n    }\n  }\n`;\n\n/**\n * The default payment-group scope: credit and debit (T140, FR-2, Decision 2). Both strings are\n * store-configured, so a store whose groups differ must set `group` explicitly; `group: ''` scopes\n * nothing (specs/payment-section-root.md § Documentation Gaps item 1). Widened from a single string to\n * a set (Decision 1) — a public API break for any consumer importing it directly (Interfaces).\n */\n/**\n * The cart's contact profile as the submit gate reads it. Only the three fields VTEX refuses an order\n * for; the profile's `document` is never selected, so no cardholder-document value reaches this contract.\n */\nexport type PaymentClientProfile = Readonly<{\n  firstName?: string | null;\n  lastName?: string | null;\n  phone?: string | null;\n}>;\n\n/**\n * The roots' keyed `$data` (ADR-0015, arity 3): the `Payment` slice the selection engine reads, the\n * cart total `add_payment_info` needs (moved here from `CardEntry`, which reads no cart), and the cart's\n * profile, which the submit gate checks before a transaction opens.\n */\nexport type PaymentSectionRootData = {\n  payment?: PaymentSectionData;\n  cart?: PaymentCartData;\n  clientProfile?: PaymentClientProfile | null;\n} | null;\n\nexport const DEFAULT_METHOD_GROUP: readonly string[] = ['creditCardPaymentGroup', 'debitCardPaymentGroup'];\n\n// ---------------------------------------------------------------------------\n// Payment context — provided by both section roots, read by every leaf\n// ---------------------------------------------------------------------------\n\n/**\n * The `payment` context contract, normative for T7–T12 and T14. Everything the selection engine\n * resolves, plus the overlay disclosure. What is deliberately absent is part of the contract too: no\n * card number, CVV, expiration, or holder name (RFC D13 — they live only in the card entry's local\n * state); no submission channel for the place-order sequence, which is the separate, narrow\n * `PaymentSubmissionProvider` below (T13) precisely so no card-shaped value ever joins this contract;\n * no `installmentOptions` / `savedCards` / `selectedInstallment` (their owners' fragments); and no\n * optimistic mirror of the persisted selection.\n */\nexport type PaymentContextValue = Readonly<\n  PaymentMethodSelection & {\n    /** The collapsed surface's disclosure state. Always `true` under `PaymentSectionRoot`. */\n    open: boolean;\n    /**\n     * Drives the collapsed surface. A no-op under `PaymentSectionRoot`, so a leaf written for the\n     * overlay composes unchanged inline. Selecting a method never closes the surface on its own — the\n     * shopper still has a card to type — so closing is the composition's call (Decision 5).\n     */\n    setOpen: (open: boolean) => void;\n    /**\n     * The cart's profile when the roots' `$data` carried one. `undefined` or `null` means it was not\n     * read (still resolving, or a `$data` that omits it), which the submit gate never refuses on; a\n     * present object counts as read even when every field is `null`.\n     */\n    clientProfile?: PaymentClientProfile | null;\n  }\n>;\n\nconst PAYMENT_CONTEXT_UNSET = Symbol('PaymentContextUnset');\n\nconst PaymentContextInternal = createContext<PaymentContextValue | typeof PAYMENT_CONTEXT_UNSET>(PAYMENT_CONTEXT_UNSET);\n\n/** The provider both section roots render. Exported for `PaymentSectionController`. */\nexport const PaymentContext = PaymentContextInternal as React.Context<PaymentContextValue>;\n\n/**\n * Read the payment section's selection state, draft, and overlay disclosure from the nearest\n * `PaymentSectionRoot` or `PaymentSectionController`. Throws outside either subtree — a misplaced\n * consumer is a composition bug the author should see immediately, not a silent degrade to an empty\n * selection — mirroring `useSession()` / `useDeliveryOptions()`. ADR-0009's compiler check catches the\n * same mistake before emission for schema-authored pages; this is the defense-in-depth layer for\n * Storybook, tests, and hand-written JSX.\n */\nexport function usePayment(): PaymentContextValue {\n  const ctx = useContext(PaymentContextInternal);\n  if (ctx === PAYMENT_CONTEXT_UNSET) {\n    throw new Error('usePayment() must be used inside a <PaymentSectionRoot> or <PaymentSectionController> subtree.');\n  }\n  return ctx;\n}\n\nconst NO_DISCLOSURE = () => {};\n\n// ---------------------------------------------------------------------------\n// Props\n// ---------------------------------------------------------------------------\n\nexport type PaymentSectionRootProps = ComponentPropsWithRef<'div'> & {\n  /**\n   * Scopes the method list to a **set** of `PaymentMethod.groupName` values — a method is in scope\n   * when its `groupName` is a member (T140, FR-1, Decision 1). A single string is still accepted and\n   * scopes to exactly that one group (FR-4, US-3). T1's read model is method-agnostic and assigns the\n   * narrowing to the consumer; this prop supplies no method, label, or ordering — the list itself is\n   * fragment data. An empty string scopes nothing.\n   */\n  group?: string | readonly string[];\n  /**\n   * The order of the method list, as a list of `PaymentMethod.groupName` values (T199): a method row\n   * sits at its group's position, and the single card control at the first of its groups the list\n   * names. It only orders — a group the list leaves out still shows, after the named ones in the order\n   * form's order, and a name no method holds is ignored. Names match exactly. Unset or empty keeps the\n   * order form's order, the card control first.\n   */\n  groupOrder?: string | readonly string[];\n  /** Keyed `{ payment, cart, clientProfile }` forwarded by the reactive runtime (arity-3 fragment, ADR-0015). */\n  $data?: PaymentSectionRootData;\n  /** Compiler-injected action surface; carries `payment.setMethod`, `payment.sendPayments`, and `analytics.track`. */\n  $actions?: ComponentActions;\n};\n\nexport const PaymentMethodListContent = defineContentType({\n  id: 'payment-method-list',\n  title: 'Payment Method List',\n  description: 'Copy for the payment method group legend, the single card option and a refused selection.',\n  schema: {\n    type: 'object',\n    additionalProperties: false,\n    properties: {\n      legend: {\n        type: 'string',\n        title: 'Legend',\n        description: \"The radio group's visible accessible name.\",\n        format: 'icu-message',\n        messageSource: 'Payment method',\n      },\n      cardLabel: {\n        type: 'string',\n        title: 'Card option label',\n        description: 'Names the one option that stands for every in-scope credit and debit method.',\n        format: 'icu-message',\n        messageSource: 'Pay with Credit / Debit Card',\n      },\n      genericErrorMessage: {\n        type: 'string',\n        title: 'Selection failure message',\n        description: 'Shown when a method selection fails: a network failure or a fault the shopper cannot fix.',\n        format: 'icu-message',\n        messageSource: 'Unable to select the payment method. Please try again.',\n      },\n    },\n  },\n});\n\n/**\n * The message for each code a method selection can return. The list is not where a saved card is picked,\n * so no code is one its shopper can act on here; every code, and one this map does not know, shows\n * genericErrorMessage.\n */\nexport const PAYMENT_METHOD_LIST_ERROR_FIELDS = {\n  MISSING_CART_CONTEXT: 'genericErrorMessage',\n  CART_NOT_FOUND: 'genericErrorMessage',\n  INVALID_METHOD_ID: 'genericErrorMessage',\n  INVALID_SAVED_CARD_ACCOUNT_ID: 'genericErrorMessage',\n  MISMATCHED_BIN_FOR_SAVED_CARD: 'genericErrorMessage',\n  INVALID_BIN_FORMAT: 'genericErrorMessage',\n  CONFLICTING_BIN_AND_ACCOUNT_ID: 'genericErrorMessage',\n  NETWORK_ERROR: 'genericErrorMessage',\n} as const satisfies Record<PaymentMethodSelectErrorCode, MessageFieldName<typeof PaymentMethodListContent>>;\n\n/** Renders its own controls from the context's method list — `children` would have nothing to template. */\nexport type PaymentMethodListProps = Omit<ComponentPropsWithRef<'div'>, 'children'> &\n  MessageLocaleProp & {\n    /**\n     * Merchant-authored copy: the group legend (T38) and the single card control's name (T171). The card\n     * control stands for every in-scope credit/debit method at once, so it cannot take its name from one\n     * of their `method.name` values.\n     */\n    $content?: ContentValue<typeof PaymentMethodListContent>;\n  };\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const PaymentSectionRootDefinition = defineComponent<PaymentSectionRootProps>({\n  name: 'PaymentSectionRoot',\n  importPath: '@vtex/faststore/components',\n  component: PaymentSectionRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  actions: { payment: ['setMethod', 'sendPayments'], analytics: ['track'] },\n  providesContext: ['payment', 'card-capture'],\n  hardened: true,\n  editor: { label: 'Payment Section', category: 'commerce' },\n  schema: {\n    // A literal, not `DEFAULT_METHOD_GROUP`: the native catalog builder extracts `schema` statically\n    // and silently drops an identifier-valued default, so the built entry would carry no default and\n    // the compiler would emit the section unscoped. `payment.test.tsx` asserts the literal matches the\n    // constant, and that the built catalog kept the default.\n    // T140, Decision 2/OQ-6: `type: 'array'` — no code path in packages/sukima/crates/sukima-core/\n    // validates an authored prop's JSON value against this declared type, so a store's existing bare\n    // string keeps compiling. No `items`: an enum would validate against a closed set of group names,\n    // which is wrong for a store that renamed its group (OQ-3) — the exact fragility Decision 1 closes.\n    group: {\n      type: 'array',\n      default: ['creditCardPaymentGroup', 'debitCardPaymentGroup'],\n      label: 'Payment method group',\n    },\n    // T199, Decision 2: no `default` — absent means the order form's order, and the catalog builder\n    // drops an identifier default, so a default would have to be a literal `[]` the compiler would emit\n    // into every generated section for no effect. No `items`, for the same reason `group` has none.\n    groupOrder: {\n      type: 'array',\n      label: 'Payment method group order',\n    },\n  },\n  guideline:\n    \"Root of the checkout payment section: reads the payment methods and the current selection from the order form and provides the 'payment' context every payment leaf needs and the 'card-capture' context CardEntry needs, so place CardEntry, CardholderDocument, Installments, SaveCard, BillingAddress, SavedCards, PlaceOrder, and PaymentMethodList as its children — none of them render without a payment root ancestor. Renders one container div and no chrome or copy of its own; headings and layout belong to the composition. Selecting a payment option dispatches $actions.payment.setMethod and every subscriber re-renders from the cache with no refetch — and for a card it is the number the shopper types that decides the network, not an option they pick, so PaymentMethodList shows every in-scope credit and debit method as ONE card option. Which methods exist is always real data — never author them as props; group only scopes the list by the store's payment group(s) — defaults to credit and debit together, accepts one group name or a set of them, and set it to \\\"\\\" to show every method, one option each, with no card option. groupOrder only orders the list — a list of the store's payment group names, copied from its own data, that puts each option at its group's position and the card option at the first of its groups the list names; it never hides, adds or renames an option, a group it leaves out still shows after the named ones, and a name no method holds is ignored. Use PaymentSectionController instead when the section should live in a drawer or modal. See payment.md.\",\n});\n\nexport const PaymentMethodListDefinition = defineComponent<PaymentMethodListProps>({\n  name: 'PaymentMethodList',\n  importPath: '@vtex/faststore/components',\n  component: PaymentMethodList,\n  requiresContext: 'payment',\n  content: PaymentMethodListContent,\n  editor: { label: 'Payment Method List', category: 'commerce' },\n  schema: {},\n  guideline:\n    'The payment-method picker: a radio group of the payment options the order form offers, plus the inline selection error (role=\"alert\"). Every in-scope credit and debit method is ONE option — the network comes from the card number the shopper types, never from a row they pick — and any other in-scope method (e.g. Pix) keeps a row of its own; set group to \"\" on the root to switch that off and get one row per method. Selecting an option dispatches the method selection. Selecting a non-card option hides the card form, and the card option brings it back. Place it inside a PaymentSectionRoot, or inside the DialogPopup/DrawerPopup of a PaymentSectionController. It renders its own options from real data, so it takes no children and no method props; its legend and the card option\\'s wording come from the $content fields legend and cardLabel, and a refused selection shows genericErrorMessage. Keep it composed: it is the only element that surfaces a rejected selection, and the only control that can recover a selection this section does not serve — omit it and a shopper whose persisted method sits outside group has no reachable way back. Must be inside a payment root.',\n});\n\n// ---------------------------------------------------------------------------\n// Implementations\n// ---------------------------------------------------------------------------\n\nexport function PaymentSectionRoot({\n  group = DEFAULT_METHOD_GROUP,\n  groupOrder,\n  $data: $dataProp,\n  $actions: $actionsProp,\n  className,\n  children,\n  ...props\n}: PaymentSectionRootProps) {\n  const $data = useDataOverride($dataProp);\n  const $actions = useActionsOverride($actionsProp);\n  const selection = usePaymentMethodSelection({ group, groupOrder, $data: $data?.payment ?? null, $actions });\n  const clientProfile = $data?.clientProfile;\n  const payment = useMemo<PaymentContextValue>(\n    () => ({ ...selection, open: true, setOpen: NO_DISCLOSURE, clientProfile }),\n    [selection, clientProfile],\n  );\n\n  return (\n    <PaymentContextInternal value={payment}>\n      <PaymentSubmissionProvider path={selection.draft.path}>\n        <PaymentCardCaptureProvider selection={selection} cart={$data?.cart} $actions={$actions}>\n          <div\n            {...props}\n            className={className}\n            data-fs-payment-section=\"\"\n            {...(selection.draft.path ? { 'data-fs-payment-section-path': selection.draft.path } : {})}\n            // T28, Decision 5: presence attribute only, deliberately never `inert` — `PlaceOrder` composes\n            // as a child of this same container (FR-6), so making it inert here would swallow the CTA's\n            // own role=\"alert\"/role=\"status\" regions, the shopper's only channel for the outcome.\n            {...(selection.placing ? { 'data-fs-payment-section-placing': '' } : {})}\n          >\n            {children}\n          </div>\n        </PaymentCardCaptureProvider>\n      </PaymentSubmissionProvider>\n    </PaymentContextInternal>\n  );\n}\n\n/**\n * The picker's presence state, always emitted so a swatch can surface a row-less container — otherwise\n * a zero-height element under any stacking swatch, and the \"visible empty region\" the section's\n * group-default risk is accepted on. `loading` (still resolving) and `empty` (resolved, nothing in\n * scope) stay distinct: one is a wait, the other a misconfiguration.\n */\nfunction methodListState({ 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 DOM value the collapsed card control carries inside the `RadioGroup`. Base UI requires every\n * radio root to have one, and this control stands for N methods, so there is no `method.id` it could\n * use.\n *\n * It is a radio-group value and nothing else — **never a method id** (INV-1, ADR-0023). It is never\n * dispatched: `handleValueChange` below maps it back to `resolvePreselectionCandidateId`'s answer\n * before calling `selectMethod`, and records card mode through `selectNewCard()`, which dispatches\n * nothing, when there is no candidate (T191, FR-6). The prefix keeps it from ever colliding with a\n * `PaymentMethod.id` a standalone row is bound to.\n */\nconst CARD_CONTROL_VALUE = '__fs-card-control';\n\nexport function PaymentMethodList({ $content, $locale, className, ...props }: PaymentMethodListProps) {\n  const { format } = useMessageFormatter(PaymentMethodListContent, $content);\n  const {\n    methods,\n    allMethods,\n    groupOrder,\n    persistedMethodId,\n    selectedMethodId,\n    selectionError,\n    selectMethod,\n    selectNewCard,\n    cardModeActive,\n    loading,\n    placing,\n    setMethodListMounted,\n  } = usePayment();\n\n  // T171, FR-1/FR-2: one control for the in-scope card methods, one row for every other in-scope\n  // method. Memoized off the two lists only (NFR-5) — nothing here may widen what re-creates the\n  // `payment` context value, which a keystroke already churns enough.\n  const { collapsedCardMethods, standaloneMethods } = useMemo(\n    () => splitCardMethods({ methods, allMethods }),\n    [methods, allMethods],\n  );\n  // T199: the merchant's order is applied here, to the rows alone — `methods` keeps the order form's\n  // order, because a typed card number resolves against it.\n  const rows = useMemo(\n    () => orderMethodListRows({ collapsedCardMethods, standaloneMethods, groupOrder }),\n    [collapsedCardMethods, standaloneMethods, groupOrder],\n  );\n  // Decision 3: the collapsed control dispatches the *shared* preselection candidate, so the escape\n  // hatch and the preselection can never disagree about whether an id is available.\n  const cardCandidateId = useMemo(() => resolvePreselectionCandidateId(methods), [methods]);\n  const canRevealCardPayment = resolveCanRevealCardPayment({ collapsedCardMethods, standaloneMethods });\n\n  // Decision 2: derived, never bound to one `method.id` — a control standing for N methods has none.\n  // Checked when the persisted selection resolves inside the collapsed set, and when nothing is\n  // persisted at all (PRD REQ-02's \"the card payment option is selected by default\"). The second arm\n  // is a deliberate divergence from the pre-T171 bound-to-`$data` behaviour: the control can read\n  // checked while `$data.selectedMethodId` is still null, having dispatched nothing. `persistedMethodId`\n  // is the raw, unscoped fact on purpose — a persisted method this section does not serve must leave the\n  // control unchecked, which is what keeps it activatable as US-5's way back. T191 (FR-6): card mode is\n  // the third arm, the card option chosen over such a selection or over a non-card one.\n  const cardControlChecked =\n    collapsedCardMethods.length > 0 &&\n    (persistedMethodId === null ||\n      collapsedCardMethods.some((method) => method.id === selectedMethodId) ||\n      cardModeActive);\n\n  // Fix pass, finding R2: registers this instance with the shared engine so the card leaves know an\n  // escape hatch exists before they ever collapse — a section composed with no `PaymentMethodList` at\n  // all must never hide the only remaining way to change the method (typing a new card number).\n  // Retracted unconditionally on unmount, unlike `setPlacing`'s own \"leave it if still placing\"\n  // carve-out: there is no in-flight sequence here for an abandoned instance to still be part of.\n  //\n  // T191, Decision 5 (after T171's Decision 4): what is registered is `canRevealCardPayment`, not the\n  // bare fact of being mounted — whether this list can bring the card form back. A rendered card\n  // option always can, since card mode needs no method id; without one, only a row bound to a card\n  // method can. See `resolveCanRevealCardPayment`'s own doc comment. The dependency list carries it,\n  // so the registration re-runs when the method list resolves.\n  //\n  // Fix pass round 2 (flash regression): `useLayoutEffect`, not `useEffect` — mirroring\n  // `place-order.tsx`'s own `setPlacing` registration, the structurally identical precedent for\n  // publishing a ref-counted fact to this shared engine from a leaf's mount. A passive effect runs\n  // after the browser has already painted, so a root whose persisted selection is genuinely out of\n  // scope committed one real frame with `methodListMounted` still `false` — the collapse (then\n  // `selectionOutOfScope && methodListMounted`, now `cardPaymentCollapsed`) computed `false` for that\n  // frame, painting the card form visible, focusable, and with its security code not yet cleared,\n  // before the registration ever landed and a second commit hid it. A layout effect's own state update\n  // is guaranteed to flush synchronously before the browser paints, so the very first frame a shopper\n  // can ever see already reflects `methodListMounted`. The card leaves read it purely at render time,\n  // not from an effect of their own, so this reorders nothing on that side: whichever commit this\n  // layout effect's own update produces is the one their next render (still pre-paint) sees.\n  const instanceKey = useId();\n  useLayoutEffect(() => {\n    setMethodListMounted(instanceKey, canRevealCardPayment);\n    return () => setMethodListMounted(instanceKey, false);\n  }, [instanceKey, setMethodListMounted, canRevealCardPayment]);\n\n  // INV-1: only an id the read model supplied is ever dispatched. A standalone row's value *is* its own\n  // `method.id`; the collapsed control's value is a DOM value with no method behind it, so it routes\n  // through the shared candidate instead (FR-4). With no candidate to name it records card mode, which\n  // brings the card form back and sends nothing (T191, FR-6, Decision 6).\n  function handleValueChange(value: string) {\n    if (value === CARD_CONTROL_VALUE) {\n      if (cardCandidateId !== null) {\n        selectMethod({ methodId: cardCandidateId });\n      } else {\n        selectNewCard();\n      }\n      return;\n    }\n    selectMethod({ methodId: value });\n  }\n\n  return (\n    <div\n      {...props}\n      className={className}\n      inert={placing}\n      aria-disabled={placing || undefined}\n      data-fs-payment-method-list=\"\"\n      data-fs-payment-method-list-state={methodListState({ loading, count: methods.length })}\n      {...(placing ? { 'data-fs-payment-method-list-placing': '' } : {})}\n    >\n      {selectionError ? (\n        <div role=\"alert\" data-fs-payment-method-list-error=\"\">\n          {formatErrorCode(\n            PaymentMethodListContent,\n            PAYMENT_METHOD_LIST_ERROR_FIELDS,\n            selectionError,\n            format,\n            'genericErrorMessage',\n          )}\n        </div>\n      ) : null}\n      {methods.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-payment-method-list-fieldset=\"\">\n          <Fieldset.Legend>{format('legend')}</Fieldset.Legend>\n          <RadioGroup\n            value={cardControlChecked ? CARD_CONTROL_VALUE : (selectedMethodId ?? '')}\n            onValueChange={handleValueChange}\n          >\n            {rows.map((row) =>\n              row.kind === 'card' ? (\n                // One control for every in-scope credit and debit method (FR-1, Decision 1). Both\n                // styling hooks stay exactly where a per-network row carried them — `payment.md`'s\n                // styling table documents them, so a store's swatch keeps its selectors.\n                <RadioRoot key={CARD_CONTROL_VALUE} value={CARD_CONTROL_VALUE}>\n                  <RadioIndicator data-fs-payment-method-indicator=\"\" />\n                  <span data-fs-payment-method-name=\"\">{format('cardLabel')}</span>\n                </RadioRoot>\n              ) : (\n                <RadioRoot key={row.method.id} value={row.method.id}>\n                  <RadioIndicator data-fs-payment-method-indicator=\"\" />\n                  <span data-fs-payment-method-name=\"\">{row.method.name}</span>\n                </RadioRoot>\n              ),\n            )}\n          </RadioGroup>\n        </Fieldset.Root>\n      ) : null}\n    </div>\n  );\n}\n"],"mappings":"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"}

package/dist/matter/payment/use-payment-method-selection.d.ts

@@ -1,4 +1,5 @@
-import { PaymentMethodSelectInput } from "../../sdk/payment/operations.js";
+import { PaymentType } from "../../sdk/generated/graphql.js";
+import { PaymentMethodSelectInput, PaymentUserError } from "../../sdk/payment/operations.js";
 import "../../sdk/actions/types.js";
 import { PaymentSubmissionPath } from "../../sdk/payment/submission-registry.js";
 import { DocumentType } from "../../particles/document-field/document-field.js";
@@ -33,6 +34,11 @@ export type PaymentSectionValidator = Readonly<{
 export type PaymentSectionMethod = Readonly<{
   id: string;
   name: string;
+  /**
+   * The vendor-neutral kind (`PaymentMethod.type`, T230). The card classifiers read this. `groupName`
+   * stays the open-ended vendor string: the `group` scope, `groupOrder` and the gateway body read it.
+   */
+  type: PaymentType;
   groupName: string;
   validator: PaymentSectionValidator;
 }>;
@@ -107,6 +113,12 @@ export type PaymentDraft = Readonly<{
    * literal must carry it.
    */
   billingAddressUnsaved: boolean | null;
+  /**
+   * The card entry passes length, Luhn, expiration and security code: a boolean, never the card. `false`
+   * until `CardEntry` says otherwise, and again whenever it unmounts. The installment selector reads it
+   * (with `path`) to decide whether it renders at all.
+   */
+  entryValid: boolean;
 }>;
 /**
  * Whether the BIN the server has persisted agrees with the client's current `draft.bin`.
@@ -148,6 +160,13 @@ export type PaymentMethodSelection = {
    * risk `methods` exists to guard against (T71, Decision 1).
    */
   allMethods: readonly PaymentSectionMethod[];
+  /**
+   * The merchant-authored order of the method list, normalized (`normalizeGroupOrder`): group names, `[]`
+   * when unset (T199). Read only by `PaymentMethodList`, which orders its own rows by it. `methods` and
+   * `allMethods` keep the order form's order: a typed card number resolves against `methods` in order, so
+   * the order here is display-only. Keeps its identity across renders while its content is equal.
+   */
+  groupOrder: readonly string[];
   /**
    * The raw persisted method id, unfiltered by `group` — the exact value `$data.selectedMethodId`
    * carries. Unscoped for the same reason `allMethods` is: `usePaymentSubmitGate` must resolve the
@@ -235,8 +254,8 @@ export type PaymentMethodSelection = {
   draft: PaymentDraft;
   /** True until the `Payment` entity resolves. */
   loading: boolean;
-  /** Message of the first `userError` from the latest selection, or `null`. */
-  selectionError: string | null;
+  /** The first `userError` from the latest selection, or `null`. Its readers word it by `code`. */
+  selectionError: PaymentUserError | null;
   /**
    * Dispatches `payment.setMethod` with T4's exact input, request-sequenced so only the latest call
    * owns the error state. Records **only the draft facts the input carries**: an `accountId` is the
@@ -251,13 +270,15 @@ export type PaymentMethodSelection = {
    * no method is known until card entry detects one, so there is nothing to select yet (US-4).
    */
   selectNewCard: () => void;
-  /** Publishes or clears the detected BIN with no write, for per-keystroke detection. */
+  /** Publishes or clears the detected BIN with no write, once the field holds a complete BIN. */
   setDraftBin: (bin: string | null) => void;
   /**
    * Publishes or clears the save-card flag (T10). A bare `useState` passthrough — no validation, no
    * dispatch. Nothing in this round calls it; it exists for T10 to consume.
    */
   setDraftSaveCard: (saveCard: boolean | null) => void;
+  /** Publishes whether the card entry is valid (`PaymentDraft.entryValid`). Bare passthrough, local state, no dispatch. */
+  setDraftEntryValid: (valid: boolean) => void;
   /** Publishes or clears the saved-card label (T10). Bare passthrough, mirroring `setDraftSaveCard`. */
   setDraftCardLabel: (cardLabel: string | null) => void;
   /** Publishes or clears the cardholder document (T8). Bare passthrough, mirroring `setDraftSaveCard`. */

package/dist/matter/payment/use-payment-method-selection.js

@@ -1,4 +1,5 @@
 "use client";
+import { PAYMENT_NETWORK_ERROR_CODE } from "../../sdk/payment/operations.js";
 import { resolveCountryDocumentType } from "./cardholder-document-rule.js";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 //#region src/matter/payment/use-payment-method-selection.ts
@@ -40,14 +41,16 @@ function isSelectionOutOfScope({ persistedMethodId, selectedMethod, methodsReada
 	return methodsReadable && persistedMethodId !== null && selectedMethod === null;
 }
 /**
-* The credit-card payment group, named separately from `payment.tsx`'s own `DEFAULT_METHOD_GROUP`
-* (T140, Decision 3): once that constant widens to the whole default *set*, it can no longer double as
-* "the credit group's identifier," and reading "the first member of the set" would make preselection
-* depend on prop authoring order — reintroducing the position-dependence the T79 ruling closed.
-* Declared here, not in `payment.tsx`: the import runs `payment.tsx` -> `use-payment-method-selection.js`
-* (`payment.tsx:8-12`) and never the other way, so the reverse would be a cycle.
+* The credit-card kind, named separately from `payment.tsx`'s own `DEFAULT_METHOD_GROUP` (T140,
+* Decision 3): that constant is the default *authored scope* over `groupName`, a set a store may
+* override, so it cannot double as "the credit kind's identifier," and reading "the first member of
+* the set" would make preselection depend on prop authoring order — reintroducing the position-
+* dependence the T79 ruling closed. Since T230 the classifiers read `PaymentMethod.type`, the closed
+* vendor-neutral kind, not the open-ended `groupName`. Declared here, not in `payment.tsx`: the import
+* runs `payment.tsx` -> `use-payment-method-selection.js` (`payment.tsx:8-12`) and never the other way,
+* so the reverse would be a cycle.
 */
-const CREDIT_CARD_PAYMENT_GROUP = "creditCardPaymentGroup";
+const CREDIT_CARD_TYPE = "CREDIT_CARD";
 /**
 * The one method identity a length-1 list offers, or `null` for any other length. Building block for
 * `resolvePreselectionCandidateId` below, which applies it twice — once to the whole scoped list, once
@@ -62,7 +65,7 @@ function soleMethodId(methods) {
 }
 /**
 * The whole preselection candidate rule (T140, FR-6a, Decision 3): the sole in-scope method when the
-* scoped list holds exactly one, or — when it does not — the sole method in the credit group, so a
+* scoped list holds exactly one, or — when it does not — the sole credit-card method, so a
 * store offering one credit and one debit method keeps the preselection it had before debit was
 * admitted. `null` when neither tier yields a single identity. Keyed on identity, never position, the
 * same property `soleMethodId` already had (the T79 ruling).
@@ -74,26 +77,27 @@ function soleMethodId(methods) {
 function resolvePreselectionCandidateId(methods) {
 	const soleId = soleMethodId(methods);
 	if (soleId !== null) return soleId;
-	return soleMethodId(methods.filter((method) => method.groupName === CREDIT_CARD_PAYMENT_GROUP));
+	return soleMethodId(methods.filter((method) => method.type === CREDIT_CARD_TYPE));
 }
 /**
-* The payment groups `PaymentMethodList` treats as card-shaped and collapses into one control (T171,
-* FR-1, Decision 6).
+* The payment kinds `PaymentMethodList` treats as card-shaped and collapses into one control (T171,
+* FR-1, Decision 6; read off `PaymentMethod.type` since T230, which maps the vendor groups the API knows
+* to the closed `PaymentType`).
 *
-* Deliberately a **second** constant beside `payment.tsx`'s `DEFAULT_METHOD_GROUP`, whose members
-* happen to be the same two strings today: that one is the default *authored scope*, which a store may
-* override with its own group names, while this one is what the section treats as a card group.
-* Collapsing on the authored scope instead would collapse a store's Pix method the moment it authored
-* `group: ['pixPaymentGroup']`.
+* Deliberately a **second** constant beside `payment.tsx`'s `DEFAULT_METHOD_GROUP`: that one is the
+* default *authored scope* over `groupName`, which a store may override with its own group names, while
+* this one is what the section treats as a card. Collapsing on the authored scope instead would collapse
+* a store's Pix method the moment it authored `group: ['pixPaymentGroup']`.
 *
-* The list's one card control is built from these groups alone. The section's card expression is
-* `isCardMethod` below, these groups or a card-number pattern, which the engineer ruled on 2026-09-29
-* and ADR-0023 records (T191, OQ-3). A store that renamed its card groups gets no card control at all,
-* only one row per method, which is the pre-T171 rendering: a safe degrade, never a wrong dispatch.
+* The list's one card control is built from these kinds alone. The section's card expression is
+* `isCardMethod` below, these kinds or a card-number pattern, which the engineer ruled on 2026-09-29
+* and ADR-0023 records (T191, OQ-3). A store-specific group the API maps to `OTHER` gets no card
+* control, only one row per method, which is the pre-T171 rendering: a safe degrade, never a wrong
+* dispatch.
 */
-const CARD_METHOD_GROUPS = [CREDIT_CARD_PAYMENT_GROUP, "debitCardPaymentGroup"];
+const CARD_METHOD_TYPES = [CREDIT_CARD_TYPE, "DEBIT_CARD"];
 /**
-* Whether `method` is a card (T191, FR-1, Decision 1): its group is one of `CARD_METHOD_GROUPS`, or its
+* Whether `method` is a card (T191, FR-1, Decision 1): its kind is one of `CARD_METHOD_TYPES`, or its
 * validator carries a card-number pattern. It decides the card-payment collapse, whether a list row can
 * bring the card form back, `CardEntry`'s refusal to post under a method that is not a card, and whether
 * a persisted method's own installment options apply. The list's fold keeps its group-only rule (OQ-3).
@@ -105,7 +109,7 @@ const CARD_METHOD_GROUPS = [CREDIT_CARD_PAYMENT_GROUP, "debitCardPaymentGroup"];
 * is detected as that method itself.
 */
 function isCardMethod(method) {
-	return CARD_METHOD_GROUPS.includes(method.groupName) || Boolean(method.validator.numberRegex);
+	return CARD_METHOD_TYPES.includes(method.type) || Boolean(method.validator.numberRegex);
 }
 /**
 * Splits a scoped method list the way `PaymentMethodList` renders it (T171, FR-1/FR-2/FR-7,
@@ -131,11 +135,58 @@ function splitCardMethods({ methods, allMethods }) {
 		standaloneMethods: methods
 	};
 	return {
-		collapsedCardMethods: methods.filter((method) => CARD_METHOD_GROUPS.includes(method.groupName)),
-		standaloneMethods: methods.filter((method) => !CARD_METHOD_GROUPS.includes(method.groupName))
+		collapsedCardMethods: methods.filter((method) => CARD_METHOD_TYPES.includes(method.type)),
+		standaloneMethods: methods.filter((method) => !CARD_METHOD_TYPES.includes(method.type))
 	};
 }
 /**
+* Reads the merchant-authored `groupOrder` prop into a clean list of group names (T199, FR-2). A
+* non-empty string is a one-member list; an array keeps only its non-empty string members, a repeated
+* name at its first position; anything else is `[]`. No validator checks an authored prop's JSON value
+* against its declared `type: 'array'`, so a hand-written page can hand this a number or `null`, and the
+* order must degrade to "no order" rather than throw. Names are matched exactly and case-sensitively
+* against `PaymentMethod.groupName`, so nothing is trimmed.
+*/
+function normalizeGroupOrder(value) {
+	if (typeof value === "string") return value === "" ? EMPTY_GROUP_ORDER : [value];
+	if (!Array.isArray(value)) return EMPTY_GROUP_ORDER;
+	const names = value.filter((name) => typeof name === "string" && name !== "");
+	return [...new Set(names)];
+}
+const EMPTY_GROUP_ORDER = [];
+/**
+* Orders the rows of `PaymentMethodList` by the merchant's `groupOrder` (T199, FR-4). Rows start in R1's
+* order, the card control and then `standaloneMethods`, and a stable sort moves them: a method row's key
+* is the index of its `groupName` in `groupOrder`; the card control's key is the smallest index of any
+* `groupName` a member of `collapsedCardMethods` holds, so a named card group nobody sells cannot pull it
+* up (Decision 3); a row with no key is unlisted and sorts after every listed row, keeping R1's order.
+*
+* Sorts a copy and never reaches `methods`: a typed card number resolves to the first matching method in
+* `methods` order, so the order here is display-only and cannot change which method an order is charged
+* under (RFC D15). Never adds or drops a row, so the order cannot hide a method.
+*/
+function orderMethodListRows({ collapsedCardMethods, standaloneMethods, groupOrder }) {
+	const positionOf = (groupName) => {
+		const index = groupOrder.indexOf(groupName);
+		return index === -1 ? Number.POSITIVE_INFINITY : index;
+	};
+	const rows = [...collapsedCardMethods.length > 0 ? [{
+		row: { kind: "card" },
+		position: Math.min(...collapsedCardMethods.map((method) => positionOf(method.groupName)))
+	}] : [], ...standaloneMethods.map((method) => ({
+		row: {
+			kind: "method",
+			method
+		},
+		position: positionOf(method.groupName)
+	}))];
+	rows.sort((a, b) => {
+		if (a.position === b.position) return 0;
+		return a.position < b.position ? -1 : 1;
+	});
+	return rows.map(({ row }) => row);
+}
+/**
 * Whether a rendered `PaymentMethodList` can bring the card form back — the fact it registers as
 * `methodListMounted` (T191, FR-4, Decision 5; before it, T171's "can dispatch an in-scope id").
 *
@@ -194,8 +245,8 @@ function resolveMethodPreselection({ loading, methods, persistedMethodId, select
 }
 const EMPTY_PLACING_STATE = { placingKeys: /* @__PURE__ */ new Set() };
 const EMPTY_METHOD_LIST_PRESENCE_STATE = { mountedKeys: /* @__PURE__ */ new Set() };
-/** `$data` is the payment slice the root has already unwrapped from its keyed `{ payment, cart }`. */
-function usePaymentMethodSelection({ group, $data, $actions }) {
+/** `$data` is the payment slice the root has already unwrapped from its keyed `{ payment, cart, clientProfile }`. */
+function usePaymentMethodSelection({ group, groupOrder: groupOrderProp, $data, $actions }) {
 	const loading = $data == null;
 	const methodsReadable = $data?.methods !== void 0;
 	const allMethods = $data?.methods ?? EMPTY_METHODS;
@@ -212,6 +263,8 @@ function usePaymentMethodSelection({ group, $data, $actions }) {
 		const groups = typeof group === "string" ? [group] : group;
 		return allMethods.filter((method) => groups.includes(method.groupName));
 	}, [allMethods, group]);
+	const groupOrderKey = JSON.stringify(normalizeGroupOrder(groupOrderProp));
+	const groupOrder = useMemo(() => JSON.parse(groupOrderKey), [groupOrderKey]);
 	const selectedMethod = useMemo(() => methods.find((method) => method.id === persistedMethodId) ?? null, [methods, persistedMethodId]);
 	const selectedMethodId = selectedMethod?.id ?? null;
 	const selectionOutOfScope = isSelectionOutOfScope({
@@ -236,6 +289,7 @@ function usePaymentMethodSelection({ group, $data, $actions }) {
 	const [draftSaveCard, setDraftSaveCard] = useState(null);
 	const [draftCardLabel, setDraftCardLabel] = useState(null);
 	const [draftDocument, setDraftDocument] = useState(null);
+	const [draftEntryValid, setDraftEntryValid] = useState(false);
 	const [draftBillingAddressDifferent, setDraftBillingAddressDifferent] = useState(null);
 	const [billingAddressUnsavedState, setBillingAddressUnsavedState] = useState(EMPTY_BILLING_ADDRESS_UNSAVED_STATE);
 	const [placingState, setPlacingState] = useState(EMPTY_PLACING_STATE);
@@ -278,7 +332,7 @@ function usePaymentMethodSelection({ group, $data, $actions }) {
 			setSelectMethodPending(false);
 			const [firstError] = userErrors;
 			if (firstError) {
-				if (surfaceError) setSelectionError(firstError.message);
+				if (surfaceError) setSelectionError(firstError);
 				else console.error("[usePaymentMethodSelection] preselection rejected", firstError.code);
 				revertDraft?.();
 			} else if (plainPick) {
@@ -288,7 +342,10 @@ function usePaymentMethodSelection({ group, $data, $actions }) {
 		}).catch(() => {
 			if (selectionToken.current !== token) return;
 			setSelectMethodPending(false);
-			if (surfaceError) setSelectionError("Unable to select the payment method. Try again.");
+			if (surfaceError) setSelectionError({
+				code: PAYMENT_NETWORK_ERROR_CODE,
+				message: "Unable to select the payment method. Try again."
+			});
 			else console.error("[usePaymentMethodSelection] preselection request failed");
 			revertDraft?.();
 		});
@@ -399,7 +456,8 @@ function usePaymentMethodSelection({ group, $data, $actions }) {
 		cardLabel: draftCardLabel,
 		document: draftDocument,
 		billingAddressDifferent: draftBillingAddressDifferent,
-		billingAddressUnsaved: billingAddressUnsavedState.everPublished ? billingAddressUnsavedState.unsavedKeys.size > 0 : null
+		billingAddressUnsaved: billingAddressUnsavedState.everPublished ? billingAddressUnsavedState.unsavedKeys.size > 0 : null,
+		entryValid: draftEntryValid
 	}), [
 		draftPath,
 		selectedAccountId,
@@ -408,7 +466,8 @@ function usePaymentMethodSelection({ group, $data, $actions }) {
 		draftCardLabel,
 		draftDocument,
 		draftBillingAddressDifferent,
-		billingAddressUnsavedState
+		billingAddressUnsavedState,
+		draftEntryValid
 	]);
 	const binConfirmation = useMemo(() => resolveBinConfirmation({
 		selectedBin: $data?.selectedBin,
@@ -422,6 +481,7 @@ function usePaymentMethodSelection({ group, $data, $actions }) {
 	return useMemo(() => ({
 		methods,
 		allMethods,
+		groupOrder,
 		persistedMethodId,
 		countryDocumentType,
 		selectedMethodId,
@@ -441,6 +501,7 @@ function usePaymentMethodSelection({ group, $data, $actions }) {
 		selectNewCard,
 		setDraftBin: writeDraftBin,
 		setDraftSaveCard,
+		setDraftEntryValid,
 		setDraftCardLabel,
 		setDraftDocument,
 		setDraftBillingAddressDifferent,
@@ -454,6 +515,7 @@ function usePaymentMethodSelection({ group, $data, $actions }) {
 	}), [
 		methods,
 		allMethods,
+		groupOrder,
 		persistedMethodId,
 		countryDocumentType,
 		selectedMethodId,
@@ -481,6 +543,6 @@ function usePaymentMethodSelection({ group, $data, $actions }) {
 	]);
 }
 //#endregion
-export { CARD_METHOD_GROUPS, isCardMethod, isSelectionOutOfScope, resolveBinConfirmation, resolveCanRevealCardPayment, resolveCardPaymentCollapsed, resolveMethodPreselection, resolvePreselectionCandidateId, splitCardMethods, usePaymentMethodSelection };
+export { CARD_METHOD_TYPES, isCardMethod, isSelectionOutOfScope, normalizeGroupOrder, orderMethodListRows, resolveBinConfirmation, resolveCanRevealCardPayment, resolveCardPaymentCollapsed, resolveMethodPreselection, resolvePreselectionCandidateId, splitCardMethods, usePaymentMethodSelection };
 
 //# sourceMappingURL=use-payment-method-selection.js.map