@vtex/faststore 0.0.4 → 0.0.6

package/dist/matter/payment/payment.js

@@ -0,0 +1,263 @@
+"use client";
+import { defineComponent } from "../../core/dist/define-component.js";
+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 { Fieldset } from "../../particles/fieldset/fieldset.js";
+import { RadioGroup, RadioIndicator, RadioRoot } from "../../particles/radio/radio.js";
+import { PaymentSubmissionProvider } from "../../sdk/payment/submission-registry.js";
+import { resolveCanRevealCardPayment, resolvePreselectionCandidateId, splitCardMethods, usePaymentMethodSelection } from "./use-payment-method-selection.js";
+import { PaymentCardCaptureProvider } from "./payment-card-capture.js";
+import { createContext, useContext, useId, useLayoutEffect, useMemo } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/matter/payment/payment.tsx
+/**
+* The `PaymentSection` matter root (specs/payment-section-root.md, T5 of the Credit Card epic;
+* docs/features/credit-card/rfc.md § D1). `PaymentSectionRoot` is the always-visible presentation
+* variant over the `Payment` entity T1 projects: it owns a thin `fragment` (the method list with its
+* server-driven validator config, plus the current selection), runs the shared
+* `usePaymentMethodSelection` engine, and provides the `payment` context its leaves read — the card
+* entry (T7), cardholder document (T8), installments (T9), save-card (T10), billing address (T11),
+* saved cards (T12), and place-order CTA (T14) — through the guarded `usePayment()` hook rather than
+* drilled props (ADR-0009). `PaymentSectionController` (payment-controller.tsx) is the second provider
+* of the same context for a collapsed overlay surface; ADR-0009 matches by contract identifier, so the
+* two substitute for one another with zero edits to any consumer.
+*
+* "Thin" means no `installmentOptions` (T9's own fragment), no `savedCards` (T12's), and no
+* `selectedInstallment` (T6's) — the heavy, optional, and iterated subtrees ADR-0011/ADR-0012 split out.
+* `methods[].validator` *is* selected here: it is a non-normalized value object off `Payment.methods`
+* that cannot be subscribed separately, and T7 tests every method's `numberRegex` to detect a network.
+*
+* `children` is the section composition, not a per-method template — the method picker is
+* `PaymentMethodList`, an independently placeable part with its own hooks.
+*/
+const fragment = `
+  fragment PaymentSectionData on Query {
+    payment {
+      __typename
+      id
+      methods {
+        __typename
+        id
+        name
+        groupName
+        validator {
+          __typename
+          numberMask
+          numberRegex
+          cvvMask
+          cvvRegex
+          cvvRequired
+          expirationRequired
+          holderNameRequired
+          billingAddressRequired
+          documentDisplayable
+          documentRequired
+        }
+      }
+      selectedMethodId
+      selectedAccountId
+      selectedBin
+    }
+    cart {
+      __typename
+      id
+      total {
+        __typename
+        amount
+        currencyCode
+      }
+    }
+  }
+`;
+const DEFAULT_METHOD_GROUP = ["creditCardPaymentGroup", "debitCardPaymentGroup"];
+const PAYMENT_CONTEXT_UNSET = Symbol("PaymentContextUnset");
+const PaymentContextInternal = createContext(PAYMENT_CONTEXT_UNSET);
+/** The provider both section roots render. Exported for `PaymentSectionController`. */
+const PaymentContext = PaymentContextInternal;
+/**
+* Read the payment section's selection state, draft, and overlay disclosure from the nearest
+* `PaymentSectionRoot` or `PaymentSectionController`. Throws outside either subtree — a misplaced
+* consumer is a composition bug the author should see immediately, not a silent degrade to an empty
+* selection — mirroring `useSession()` / `useDeliveryOptions()`. ADR-0009's compiler check catches the
+* same mistake before emission for schema-authored pages; this is the defense-in-depth layer for
+* Storybook, tests, and hand-written JSX.
+*/
+function usePayment() {
+	const ctx = useContext(PaymentContextInternal);
+	if (ctx === PAYMENT_CONTEXT_UNSET) throw new Error("usePayment() must be used inside a <PaymentSectionRoot> or <PaymentSectionController> subtree.");
+	return ctx;
+}
+const NO_DISCLOSURE = () => {};
+const PaymentSectionRootDefinition = defineComponent({
+	name: "PaymentSectionRoot",
+	importPath: "@vtex/faststore/components",
+	component: PaymentSectionRoot,
+	fragment,
+	fetchStrategy: "reactive",
+	actions: {
+		payment: ["setMethod", "sendPayments"],
+		analytics: ["track"]
+	},
+	providesContext: ["payment", "card-capture"],
+	editor: {
+		label: "Payment Section",
+		category: "commerce"
+	},
+	schema: { group: {
+		type: "array",
+		default: ["creditCardPaymentGroup", "debitCardPaymentGroup"],
+		label: "Payment method group"
+	} },
+	guideline: "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."
+});
+const PaymentMethodListDefinition = defineComponent({
+	name: "PaymentMethodList",
+	importPath: "@vtex/faststore/components",
+	component: PaymentMethodList,
+	requiresContext: "payment",
+	editor: {
+		label: "Payment Method List",
+		category: "commerce"
+	},
+	schema: {
+		legend: {
+			type: "string",
+			default: "Payment method",
+			label: "Legend"
+		},
+		cardLabel: {
+			type: "string",
+			default: "Pay with Credit / Debit Card",
+			label: "Card option label"
+		}
+	},
+	guideline: "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."
+});
+function PaymentSectionRoot({ group = DEFAULT_METHOD_GROUP, $data: $dataProp, $actions: $actionsProp, className, children, ...props }) {
+	const $data = useDataOverride($dataProp);
+	const $actions = useActionsOverride($actionsProp);
+	const selection = usePaymentMethodSelection({
+		group,
+		$data: $data?.payment ?? null,
+		$actions
+	});
+	const payment = useMemo(() => ({
+		...selection,
+		open: true,
+		setOpen: NO_DISCLOSURE
+	}), [selection]);
+	return /* @__PURE__ */ jsx(PaymentContextInternal, {
+		value: payment,
+		children: /* @__PURE__ */ jsx(PaymentSubmissionProvider, {
+			path: selection.draft.path,
+			children: /* @__PURE__ */ jsx(PaymentCardCaptureProvider, {
+				selection,
+				cart: $data?.cart,
+				$actions,
+				children: /* @__PURE__ */ jsx("div", {
+					...props,
+					className,
+					"data-fs-payment-section": "",
+					...selection.draft.path ? { "data-fs-payment-section-path": selection.draft.path } : {},
+					...selection.placing ? { "data-fs-payment-section-placing": "" } : {},
+					children
+				})
+			})
+		})
+	});
+}
+/**
+* The picker's presence state, always emitted so a swatch can surface a row-less container — otherwise
+* a zero-height element under any stacking swatch, and the "visible empty region" the section's
+* group-default risk is accepted on. `loading` (still resolving) and `empty` (resolved, nothing in
+* scope) stay distinct: one is a wait, the other a misconfiguration.
+*/
+function methodListState({ loading, count }) {
+	if (loading) return "loading";
+	if (count === 0) return "empty";
+	return "ready";
+}
+/**
+* The DOM value the collapsed card control carries inside the `RadioGroup`. Base UI requires every
+* radio root to have one, and this control stands for N methods, so there is no `method.id` it could
+* use.
+*
+* It is a radio-group value and nothing else — **never a method id** (INV-1, ADR-0023). It is never
+* dispatched: `handleValueChange` below maps it back to `resolvePreselectionCandidateId`'s answer
+* before calling `selectMethod`, and records card mode through `selectNewCard()`, which dispatches
+* nothing, when there is no candidate (T191, FR-6). The prefix keeps it from ever colliding with a
+* `PaymentMethod.id` a standalone row is bound to.
+*/
+const CARD_CONTROL_VALUE = "__fs-card-control";
+function PaymentMethodList({ legend, cardLabel, className, ...props }) {
+	const { methods, allMethods, persistedMethodId, selectedMethodId, selectionError, selectMethod, selectNewCard, cardModeActive, loading, placing, setMethodListMounted } = usePayment();
+	const { collapsedCardMethods, standaloneMethods } = useMemo(() => splitCardMethods({
+		methods,
+		allMethods
+	}), [methods, allMethods]);
+	const cardCandidateId = useMemo(() => resolvePreselectionCandidateId(methods), [methods]);
+	const canRevealCardPayment = resolveCanRevealCardPayment({
+		collapsedCardMethods,
+		standaloneMethods
+	});
+	const cardControlChecked = collapsedCardMethods.length > 0 && (persistedMethodId === null || collapsedCardMethods.some((method) => method.id === selectedMethodId) || cardModeActive);
+	const instanceKey = useId();
+	useLayoutEffect(() => {
+		setMethodListMounted(instanceKey, canRevealCardPayment);
+		return () => setMethodListMounted(instanceKey, false);
+	}, [
+		instanceKey,
+		setMethodListMounted,
+		canRevealCardPayment
+	]);
+	function handleValueChange(value) {
+		if (value === CARD_CONTROL_VALUE) {
+			if (cardCandidateId !== null) selectMethod({ methodId: cardCandidateId });
+			else selectNewCard();
+			return;
+		}
+		selectMethod({ methodId: value });
+	}
+	return /* @__PURE__ */ jsxs("div", {
+		...props,
+		className,
+		inert: placing,
+		"aria-disabled": placing || void 0,
+		"data-fs-payment-method-list": "",
+		"data-fs-payment-method-list-state": methodListState({
+			loading,
+			count: methods.length
+		}),
+		...placing ? { "data-fs-payment-method-list-placing": "" } : {},
+		children: [selectionError ? /* @__PURE__ */ jsx("div", {
+			role: "alert",
+			"data-fs-payment-method-list-error": "",
+			children: selectionError
+		}) : null, methods.length > 0 ? /* @__PURE__ */ jsxs(Fieldset.Root, {
+			"data-fs-payment-method-list-fieldset": "",
+			children: [/* @__PURE__ */ jsx(Fieldset.Legend, { children: resolveAuthoredCopy(legend, "Payment method") }), /* @__PURE__ */ jsxs(RadioGroup, {
+				value: cardControlChecked ? CARD_CONTROL_VALUE : selectedMethodId ?? "",
+				onValueChange: handleValueChange,
+				children: [collapsedCardMethods.length > 0 ? /* @__PURE__ */ jsxs(RadioRoot, {
+					value: CARD_CONTROL_VALUE,
+					children: [/* @__PURE__ */ jsx(RadioIndicator, { "data-fs-payment-method-indicator": "" }), /* @__PURE__ */ jsx("span", {
+						"data-fs-payment-method-name": "",
+						children: resolveAuthoredCopy(cardLabel, "Pay with Credit / Debit Card")
+					})]
+				}) : null, standaloneMethods.map((method) => /* @__PURE__ */ jsxs(RadioRoot, {
+					value: method.id,
+					children: [/* @__PURE__ */ jsx(RadioIndicator, { "data-fs-payment-method-indicator": "" }), /* @__PURE__ */ jsx("span", {
+						"data-fs-payment-method-name": "",
+						children: method.name
+					})]
+				}, method.id))]
+			})]
+		}) : null]
+	});
+}
+//#endregion
+export { DEFAULT_METHOD_GROUP, PaymentContext, PaymentMethodList, PaymentMethodListDefinition, PaymentSectionRoot, PaymentSectionRootDefinition, usePayment };
+
+//# sourceMappingURL=payment.js.map

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

@@ -0,0 +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    }\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  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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"}

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

@@ -0,0 +1,302 @@
+import { PaymentMethodSelectInput } from "../../sdk/payment/operations.js";
+import "../../sdk/actions/types.js";
+import { PaymentSubmissionPath } from "../../sdk/payment/submission-registry.js";
+import { PlaceOrderAttempt, SetPlaceOrderAttempt } from "../../sdk/payment/use-place-order.js";
+//#region src/matter/payment/use-payment-method-selection.d.ts
+/**
+ * The payment section's selection engine (specs/payment-section-root.md, T5 of the Credit Card epic).
+ * Single source of selection behavior behind both providers of the `payment` context —
+ * `PaymentSectionRoot` (always-visible) and `PaymentSectionController` (collapsed overlay) — so the two
+ * surfaces cannot drift (NFR-4), mirroring `useDeliveryOptionSelection`.
+ *
+ * It owns four things: group scoping of the method list (Decision 4), the client-only draft facts
+ * (Decision 3; widened by T7 with three absent-tolerant facts, specs/card-entry.md Decision 4), the
+ * request-sequenced `payment.setMethod` dispatch (ADR-0010), and the inline error state. It
+ * deliberately owns *no* mirror of `selectedMethodId` / `selectedAccountId` — both are read from
+ * `$data` on every render, which is `delivery-options`' "no local selection state" rule kept
+ * verbatim (FR-6).
+ */
+export type PaymentSectionValidator = Readonly<{
+  numberMask: string | null;
+  numberRegex: string | null;
+  cvvMask: string | null;
+  cvvRegex: string | null;
+  cvvRequired: boolean;
+  expirationRequired: boolean;
+  holderNameRequired: boolean;
+  billingAddressRequired: boolean;
+  documentDisplayable: boolean;
+  documentRequired: boolean;
+}>;
+export type PaymentSectionMethod = Readonly<{
+  id: string;
+  name: string;
+  groupName: string;
+  validator: PaymentSectionValidator;
+}>;
+export type PaymentSectionData = {
+  methods?: readonly PaymentSectionMethod[];
+  selectedMethodId?: string | null;
+  selectedAccountId?: string | null;
+  /** Persisted BIN off `payments[0]`. `undefined` while the entity resolves or when a hand-written slice omits it. */
+  selectedBin?: string | null;
+} | null;
+/**
+ * Which entry path the shopper is on. Aliases the submission channel's key type (T13), which the
+ * place-order sequence resolves a continuation by — one definition, so the draft fact and the
+ * registry key cannot drift apart.
+ */
+export type PaymentPath = PaymentSubmissionPath;
+/**
+ * The client-only half of the pending selection — the facts `Query.payment` cannot carry
+ * (Decision 3). Never the card number, CVV, expiration, or holder name: those live only in the card
+ * entry's local state (RFC D13).
+ *
+ * `saveCard`, `cardLabel`, and `document` are T7's widening (specs/card-entry.md, Decision 4): three
+ * non-sensitive facts T10 (save-card + label) and T8 (cardholder document) will eventually collect,
+ * which T7's submission continuation folds into the gateway card object without collecting them
+ * itself. Nullable rather than optional (`?:`), matching `path`/`bin`'s existing "always present,
+ * `null` means absent" idiom instead of introducing a second absence convention in the same type.
+ * T8/T10 have not landed, so all three are `null` in practice today — every reader must tolerate that.
+ */
+export type PaymentDraft = Readonly<{
+  /**
+   * `'new-card'` once the shopper leaves the saved-card path — a choice that precedes any server
+   * state, since there is no method to select until card entry detects one from the BIN. Falls back
+   * to `'saved-card'` while a saved card is the persisted selection, else `null`.
+   */
+  path: PaymentPath | null;
+  /** Detected leading digits, for installment lookup — never the full number. A successful plain pick clears it. */
+  bin: string | null;
+  /** Save-this-card flag (T10). `null` until T10 lands and calls `setDraftSaveCard`. */
+  saveCard: boolean | null;
+  /** Shopper-assigned saved-card label (T10). `null` until T10 lands and calls `setDraftCardLabel`. */
+  cardLabel: string | null;
+  /** Cardholder document, by country (T8). `null` until T8 lands and calls `setDraftDocument`. */
+  document: string | null;
+  /**
+   * Whether the billing address differs from delivery (T11). Mirrors the gateway transaction
+   * descriptor's own `billingAddressDifferent` field name (`sdk/payment/gateway.ts:81`) so the fact
+   * cannot drift between this publisher and its only consumer, T13's `usePlaceOrder`. `null` until
+   * T11's `BillingAddress` lands and calls `setDraftBillingAddressDifferent`.
+   */
+  billingAddressDifferent: boolean | null;
+  /**
+   * True while `BillingAddress` is on the custom-address path with nothing persisted — the exact
+   * window its own `role="status"` notice renders in (T24). Distinct from `billingAddressDifferent`,
+   * which says a different address *is* persisted (PR #544 N1) and is what the gateway descriptor
+   * reads. `null` and `false` are equivalent to the submit gate; `null` is the never-touched state, so
+   * an absent `BillingAddress` never blocks placement. Nullable, not optional — every `PaymentDraft`
+   * literal must carry it.
+   */
+  billingAddressUnsaved: boolean | null;
+}>;
+/**
+ * Whether the BIN the server has persisted agrees with the client's current `draft.bin`.
+ *
+ * - `'confirmed'` — safe to dispatch a BIN-matched write. Either the two agree with no
+ *   selection in flight, or `draft.bin` is null so the client asserts no BIN of its own.
+ * - `'pending'`   — a `payment.setMethod` is in flight, or the two disagree. A consumer
+ *   must hold any dispatch whose pricing depends on the BIN.
+ * - `'unknown'`   — the persisted BIN is not readable (the entity has not resolved, or the
+ *   slice omits the field). Consumers must NOT hold: absence is not evidence of a mismatch.
+ */
+export type PaymentBinConfirmation = 'unknown' | 'pending' | 'confirmed';
+/**
+ * Resolves the BIN confirmation signal from the persisted BIN, the client draft BIN,
+ * and whether a `payment.setMethod` is in flight. Exported for unit testing without
+ * rendering, mirroring how `findInstallmentOption` / `resolveInstallmentTiers` are
+ * exported from `installments.tsx`.
+ */
+export declare function resolveBinConfirmation({ selectedBin, draftBin, selectMethodPending }: {
+  selectedBin: string | null | undefined;
+  draftBin: string | null;
+  selectMethodPending: boolean;
+}): PaymentBinConfirmation;
+export type PaymentMethodSelection = {
+  /** Methods from the read model, scoped by `group`. Empty until the entity resolves. */
+  methods: readonly PaymentSectionMethod[];
+  /**
+   * Every method from the read model, unfiltered by `group` (fix pass, finding S1). Exposed so
+   * `usePaymentSubmitGate()` (`matter/payment/use-payment-submit-gate.ts`) can resolve
+   * `persistedMethodId` the same *unscoped* way `usePlaceOrder`'s own pre-flight does
+   * (`sdk/payment/use-place-order.ts`, off its own independent fragment slice — neither hook may read
+   * the other's module, Decision 2) — a method whose `groupName` sits outside this root's configured
+   * `group` must still gate a required document if `usePlaceOrder` is about to treat it as selected.
+   * `methods` remains the one every picker and rendering leaf reads from — with one documented
+   * exception: `PaymentMethodBadges` (`payment-method-badges.tsx`, T75) reads this unfiltered list
+   * instead, because its accepted-method strip is a statement about the store rather than the section,
+   * and a wallet method's `groupName` would otherwise never reach it. It detects nothing and renders
+   * from no single shared array the way `CardEntry` does, so it carries none of the detection-set
+   * risk `methods` exists to guard against (T71, Decision 1).
+   */
+  allMethods: readonly PaymentSectionMethod[];
+  /**
+   * 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
+   * method `usePlaceOrder`'s own independent by-id lookup would. Rendering leaves want
+   * `selectedMethodId` (T74, Decision 4/7).
+   */
+  persistedMethodId: string | null;
+  /**
+   * The persisted selection **as this section serves it** — `selectedMethod?.id ?? null`. `null` both
+   * when nothing is persisted and when what is persisted sits outside `group`; `persistedMethodId`
+   * tells those two apart (T74, Decision 4/7). Read straight off `$data` — never mirrored locally.
+   */
+  selectedMethodId: string | null;
+  /**
+   * The persisted selection is one this section does not serve. One of the two selection facts behind
+   * `cardPaymentCollapsed` (T74, FR-7; T191, FR-5). `false` whenever `persistedMethodId` is `null`
+   * (INV-5), and `false` whenever `methods` could not be read at all rather than genuinely resolving
+   * without the persisted id in it (fix pass, finding R1).
+   */
+  selectionOutOfScope: boolean;
+  /**
+   * Whether a mounted `PaymentMethodList` can bring the card form back (fix pass, finding R2; re-derived
+   * by T171, FR-6, and by T191, FR-4/Decision 5). `cardPaymentCollapsed` requires it: hiding the card
+   * form is only safe when something on the page can un-hide it. With no picker composed, the only way
+   * back is typing a new card number, which needs `CardEntry` to stay visible and interactive.
+   *
+   * The name is historical: it stood for "a picker is mounted" while every in-scope method had its own
+   * row, and for "a control can dispatch an in-scope id" from T171 on. `PaymentMethodList` registers the
+   * property itself rather than its own presence (`resolveCanRevealCardPayment`): a rendered card option
+   * always can, with or without a method it can name, and without one only a card row can.
+   *
+   * Ref-counted per instance key mirroring `placing`/`billingAddressUnsaved`, though in practice at
+   * most one `PaymentMethodList` is ever composed per root.
+   */
+  methodListMounted: boolean;
+  /**
+   * Registers (or retracts) one `PaymentMethodList` instance's ability to bring the card form back.
+   * Called by `PaymentMethodList` itself. Same signature as before T171; the boolean's meaning is what
+   * changed — see `methodListMounted` above.
+   */
+  setMethodListMounted: (key: string, mounted: boolean) => void;
+  /**
+   * Card mode is holding the card form open over a persisted selection that is not a card or that this
+   * section does not serve (T191, FR-3, Decision 4). `selectNewCard()` turns card mode on, and a plain
+   * pick of a method that is not a card turns it off once it succeeds. It counts only over such a
+   * selection, so it is `false` whenever nothing or an in-scope card method is persisted (INV-5). Local
+   * to this engine: nothing is sent to record it, and a reload forgets it.
+   */
+  cardModeActive: boolean;
+  /**
+   * The card payment is collapsed (T191, FR-5, Decision 2): the persisted selection is one this section
+   * does not serve or one that is not a card, `cardModeActive` is `false`, and `methodListMounted` is
+   * `true`. The one collapse fact every card leaf reads — `CardEntry` hides itself and stays mounted,
+   * the others render nothing — so no two leaves can disagree.
+   */
+  cardPaymentCollapsed: boolean;
+  /** The persisted saved-card account reference, read straight off `$data`. */
+  selectedAccountId: string | null;
+  /**
+   * The persisted BIN **as this section serves it** — `null` unless the persisted selection resolves
+   * inside the scoped `methods` list, mirroring `selectedMethodId` (fix pass, finding R3). Unscoped
+   * before this fix, `useInstallmentsSelection`'s own `draft.bin ?? selectedBin` fallback (its only
+   * consumer) could still resolve an out-of-scope method's installment tiers by BIN alone even once
+   * FR-9's methodId-arm fix landed — the methodId half of that lookup went `null` for an out-of-scope
+   * selection, but the BIN half never did. Never mirrored, like its sibling `selectedMethodId`.
+   *
+   * Carries the same `methodsReadable` guard as `isSelectionOutOfScope` (fix pass round 2): an absent
+   * `methods` forces `selectedMethod` to `null` the same way a genuine out-of-scope selection does, so
+   * without the guard this read `null` for the hand-written partial `$data` slice `methodsReadable`'s
+   * own doc comment describes as explicitly supported — even while `selectionOutOfScope` correctly
+   * stayed `false` for that same slice.
+   */
+  selectedBin: string | null;
+  /** Whether `draft.bin` has actually been persisted. See `PaymentBinConfirmation`. */
+  binConfirmation: PaymentBinConfirmation;
+  /** `selectedMethodId` resolved against the scoped list; carries the validator config leaves gate on. */
+  selectedMethod: PaymentSectionMethod | null;
+  /** The client-only facts the read model cannot carry. */
+  draft: PaymentDraft;
+  /** True until the `Payment` entity resolves. */
+  loading: boolean;
+  /** Message of the first `userError` from the latest selection, or `null`. */
+  selectionError: string | 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
+   * saved-card path, a `bin` is the new-card path, and an input with neither — a plain method pick —
+   * leaves both until it succeeds, then releases `draft.bin` and, for a method that is not a card, ends
+   * card mode (T191, FR-3). A no-op (no error, no throw) without the action.
+   */
+  selectMethod: (input: PaymentMethodSelectInput) => void;
+  /**
+   * Switches to the new-card path, clears the detected BIN, clears any selection error — the message
+   * described a picker the shopper has left — and turns card mode on (T191, FR-3). Dispatches nothing:
+   * 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. */
+  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 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`. */
+  setDraftDocument: (document: string | null) => void;
+  /**
+   * Publishes or clears the billing-address-differs flag (T11). Bare passthrough — no validation, no
+   * dispatch — mirroring `setDraftSaveCard`/`setDraftCardLabel`/`setDraftDocument`.
+   */
+  setDraftBillingAddressDifferent: (billingAddressDifferent: boolean | null) => void;
+  /**
+   * Publishes or clears whether `BillingAddress` is on the custom-address path with nothing persisted
+   * (T24) — **not** a bare passthrough like the setters above (fix pass, findings R2/S2). Takes a
+   * caller-owned, per-instance `key` (`billing-address.tsx`'s own `useId()`) because
+   * `billingAddressUnsaved` is a single fact shared by every `BillingAddress` mounted under this root —
+   * `billing-address.md` documents multiple instances as allowed — and an unconditional
+   * `setDraftBillingAddressUnsaved(false)` on one instance's unmount would silently clear a *second*,
+   * still-open, still-unsaved instance's own block while its own notice keeps rendering (measured:
+   * exactly this reproduction blocks placement in the UI and bills the declined address anyway). Each
+   * instance's own key is added to an internal set while `unsaved` is `true` and removed while it is
+   * `false` — on every call, not only cleanup — so an unmount only ever retracts *that* instance's own
+   * contribution. The published `PaymentDraft.billingAddressUnsaved` is `true` while the set is
+   * non-empty, `false` once every instance that has ever called this resolves to nothing outstanding,
+   * and `null` only before any instance has ever called it at all.
+   */
+  setDraftBillingAddressUnsaved: (key: string, unsaved: boolean) => void;
+  /**
+   * An order-placement sequence is in flight (T28, specs/place-order-blocking-state.md; REQ-08 s2).
+   * A top-level field beside `loading`, deliberately **not** on `draft`: a transition must not change
+   * `draft`'s identity, or every keystroke-memoized `draft` consumer would recompute on it (NFR-1).
+   * True from the moment the sequence opens a transaction until it settles — never for an attempt
+   * refused synchronously, because no sequence runs (FR-3).
+   */
+  placing: boolean;
+  /**
+   * Publishes one `PlaceOrder` instance's in-flight state. Ref-counted per `key`; a retraction only
+   * ever removes its own key. Bails out to the same state by reference when membership already
+   * matches, so an effect re-running on an unrelated dependency change does not re-render the section
+   * (NFR-2).
+   */
+  setPlacing: (key: string, placing: boolean) => void;
+  /**
+   * The current order-placement attempt (T29, specs/make-an-order-attempt-survive-a.md), or `null`
+   * when none has started under this root. Sits beside `placing` on this same contract for the
+   * identical reason `placing` does (T28): one fact, several leaves, must outlive an overlay's own
+   * mount — `PlaceOrder` publishes it, `usePlaceOrder` (sdk/payment) reads and writes it, and a remount
+   * reads the survivor rather than starting over.
+   */
+  attempt: PlaceOrderAttempt | null;
+  /**
+   * Records a phase transition. Unlike `setPlacing`, not ref-counted: only one attempt exists at a
+   * time under a root (the shared `placing` gate keeps a second sequence from ever opening — T28), so a
+   * single last-write-wins `useState` setter is enough. Identity is stable for the root's lifetime, so
+   * an in-flight `run()`/`resume()` closure (sdk/payment/use-place-order.ts) keeps writing after the
+   * CTA that started it unmounts (NFR-3) — the mechanism that makes the attempt outlive the mount at all.
+   *
+   * Widened past a plain value (fix pass, High finding in sdk/payment/use-place-order.ts): the raw
+   * `useState` setter this field is assigned below has always accepted an updater function too, so
+   * accepting `SetPlaceOrderAttempt` here merely lets a caller use a capability the setter already had
+   * — `usePlaceOrder`'s own staleness guard needs it to keep a losing racer's late write from
+   * clobbering a newer outcome.
+   */
+  setAttempt: SetPlaceOrderAttempt;
+};
+//#endregion
+//# sourceMappingURL=use-payment-method-selection.d.ts.map