@vtex/faststore 0.0.5 → 0.0.6

package/dist/matter/access-code-sign-in/access-code-sign-in.js

@@ -5,6 +5,7 @@ import { AccessCodeField } from "../../particles/access-code-field/access-code-f
 import { EmailField, isValidEmail } from "../../particles/email-field/email-field.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 { useSession } from "../session/session.js";
 import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -35,18 +36,18 @@ function useAccessCodeSignIn() {
 }
 function requestErrorMessage(error, props) {
 	switch (error.code) {
-		case "ACCESS_CODE_SEND_LIMIT": return props.sendLimitMessage ?? error.message;
-		case "BLOCKED": return props.blockedMessage ?? error.message;
-		case "NETWORK_ERROR": return props.networkErrorMessage ?? error.message;
+		case "ACCESS_CODE_SEND_LIMIT": return resolveAuthoredCopy(props.sendLimitMessage, error.message);
+		case "BLOCKED": return resolveAuthoredCopy(props.blockedMessage, error.message);
+		case "NETWORK_ERROR": return resolveAuthoredCopy(props.networkErrorMessage, error.message);
 		default: return error.message;
 	}
 }
 function validateErrorMessage(error, props) {
 	switch (error.code) {
-		case "INVALID_ACCESS_CODE": return props.invalidCodeMessage ?? error.message;
-		case "BLOCKED": return props.blockedMessage ?? error.message;
-		case "MISSING_AUTH_CONTEXT": return props.missingAuthContextMessage ?? error.message;
-		case "NETWORK_ERROR": return props.networkErrorMessage ?? error.message;
+		case "INVALID_ACCESS_CODE": return resolveAuthoredCopy(props.invalidCodeMessage, error.message);
+		case "BLOCKED": return resolveAuthoredCopy(props.blockedMessage, error.message);
+		case "MISSING_AUTH_CONTEXT": return resolveAuthoredCopy(props.missingAuthContextMessage, error.message);
+		case "NETWORK_ERROR": return resolveAuthoredCopy(props.networkErrorMessage, error.message);
 		default: return error.message;
 	}
 }
@@ -295,7 +296,7 @@ function AccessCodeRequestControl({ label, pendingLabel, sendLimitMessage, block
 			"aria-busy": pending || void 0,
 			"data-fs-access-code-request-submit": "",
 			"data-fs-button": "",
-			children: pending ? pendingLabel ?? label : label
+			children: pending ? resolveAuthoredCopy(pendingLabel, label ?? "") : label
 		}), message ? /* @__PURE__ */ jsx("div", {
 			role: "alert",
 			"data-fs-access-code-request-error": "",

package/dist/matter/access-code-sign-in/access-code-sign-in.js.map

@@ -1 +1 @@
-{"version":3,"file":"access-code-sign-in.js","names":[],"sources":["../../../src/matter/access-code-sign-in/access-code-sign-in.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef, FormEvent } from 'react';\nimport { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';\nimport { AccessCodeField } from '../../particles/access-code-field/access-code-field.js';\nimport { EmailField, isValidEmail } from '../../particles/email-field/email-field.js';\nimport { useActionsOverride } from '../../sdk/actions/actions-override-context.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport type { SessionUserError } from '../../sdk/session/auth-operations.js';\nimport { useSession } from '../session/session.js';\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment (colocated, ADR-0011) — clientProfile.email seeds the draft email as a\n// convenience pre-fill for an already-identified shopper; sessionAuthProviders.accessKeyAuthentication\n// is the account gate. Authored as a raw string, mirroring EmailIdentificationControl/ShippingSimulator.\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment AccessCodeSignInData on Query {\n    clientProfile {\n      __typename\n      id\n      email\n    }\n    sessionAuthProviders {\n      accessKeyAuthentication\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Colocated fragment slice forwarded by the reactive runtime — `null` until both fields resolve. */\nexport type AccessCodeSignInSlice = {\n  clientProfile: { email: string | null } | null;\n  sessionAuthProviders: { accessKeyAuthentication: boolean } | null;\n};\n\nexport type AccessCodeSignInStep = 'request' | 'validate';\n\nexport type AccessCodeSignInContextValue = Readonly<{\n  /** The shopper's locally-typed draft email — never written to the cart; only ever an argument to\n   * requestAccessCode/validateAccessCode. Pre-fills from `clientProfile.email` when known, but a\n   * shopper edit is never persisted anywhere by this family. */\n  email: string;\n  /** Updates the draft email; marks it as shopper-touched so pre-fill no longer overwrites it. */\n  setEmail: (email: string) => void;\n  step: AccessCodeSignInStep;\n  /** Opaque token round-tripped from requestAccessCode into validateAccessCode. */\n  authenticationToken: string | null;\n  /** Called by AccessCodeRequestControl on a successful requestAccessCode. */\n  startValidation: (authenticationToken: string) => void;\n}>;\n\nexport type AccessCodeSignInRootProps = ComponentPropsWithRef<'div'> & {\n  $data?: AccessCodeSignInSlice | null;\n};\n\nexport type AccessCodeEmailControlProps = ComponentPropsWithRef<'div'> & {\n  label?: string;\n  placeholder?: string;\n  invalidEmailMessage?: string;\n};\n\nexport type AccessCodeRequestControlProps = ComponentPropsWithRef<'div'> & {\n  label?: string;\n  pendingLabel?: string;\n  sendLimitMessage?: string;\n  blockedMessage?: string;\n  networkErrorMessage?: string;\n  onRequested?: (authenticationToken: string) => void;\n  $actions?: ComponentActions;\n};\n\nexport type AccessCodeValidateControlProps = ComponentPropsWithRef<'div'> & {\n  label?: string;\n  placeholder?: string;\n  submitLabel?: string;\n  codeLength?: number;\n  invalidCodeMessage?: string;\n  blockedMessage?: string;\n  missingAuthContextMessage?: string;\n  networkErrorMessage?: string;\n  onValidated?: () => void;\n  $actions?: ComponentActions;\n};\n\n// ---------------------------------------------------------------------------\n// Context\n// ---------------------------------------------------------------------------\n\nconst ACCESS_CODE_SIGN_IN_CONTEXT_UNSET = Symbol('AccessCodeSignInContextUnset');\n\nconst AccessCodeSignInContext = createContext<AccessCodeSignInContextValue | typeof ACCESS_CODE_SIGN_IN_CONTEXT_UNSET>(\n  ACCESS_CODE_SIGN_IN_CONTEXT_UNSET,\n);\n\n/**\n * Read the stepper state (email, step, authenticationToken) from the nearest `AccessCodeSignInRoot`.\n * Throws when called outside that subtree — a misplaced control is a composition bug that should\n * surface immediately, mirroring `useShippingSimulator()`/`useSession()`.\n */\nfunction useAccessCodeSignIn(): AccessCodeSignInContextValue {\n  const ctx = useContext(AccessCodeSignInContext);\n  if (ctx === ACCESS_CODE_SIGN_IN_CONTEXT_UNSET) {\n    throw new Error('AccessCodeSignIn components must be used inside AccessCodeSignInRoot.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Error-code → message mapping — every failure surfaces inline, at the control that produced it;\n// an unmapped code falls back to the server-supplied message rather than being silent.\n// ---------------------------------------------------------------------------\n\nfunction requestErrorMessage(\n  error: SessionUserError,\n  props: Pick<AccessCodeRequestControlProps, 'sendLimitMessage' | 'blockedMessage' | 'networkErrorMessage'>,\n): string {\n  switch (error.code) {\n    case 'ACCESS_CODE_SEND_LIMIT':\n      return props.sendLimitMessage ?? error.message;\n    case 'BLOCKED':\n      return props.blockedMessage ?? error.message;\n    case 'NETWORK_ERROR':\n      return props.networkErrorMessage ?? error.message;\n    default:\n      return error.message;\n  }\n}\n\nfunction validateErrorMessage(\n  error: SessionUserError,\n  props: Pick<\n    AccessCodeValidateControlProps,\n    'invalidCodeMessage' | 'blockedMessage' | 'missingAuthContextMessage' | 'networkErrorMessage'\n  >,\n): string {\n  switch (error.code) {\n    case 'INVALID_ACCESS_CODE':\n      return props.invalidCodeMessage ?? error.message;\n    case 'BLOCKED':\n      return props.blockedMessage ?? error.message;\n    case 'MISSING_AUTH_CONTEXT':\n      return props.missingAuthContextMessage ?? error.message;\n    case 'NETWORK_ERROR':\n      return props.networkErrorMessage ?? error.message;\n    default:\n      return error.message;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const AccessCodeSignInRootDefinition = defineComponent<AccessCodeSignInRootProps>({\n  name: 'AccessCodeSignInRoot',\n  importPath: '@vtex/faststore/components',\n  component: AccessCodeSignInRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  requiresContext: 'session',\n  editor: { label: 'Access Code Sign-In', category: 'identity' },\n  schema: {},\n  guideline:\n    'Self-gating root of the anonymous-or-identified, email + access-code sign-in: renders nothing once loggedIn or when the account disables accessKeyAuthentication, but is available from the anonymous state onward. Owns a locally-typed draft email (never written to the cart) and the request/validate stepper. Must be inside SessionRoot. See access-code-sign-in.md.',\n});\n\nexport const AccessCodeEmailControlDefinition = defineComponent<AccessCodeEmailControlProps>({\n  name: 'AccessCodeEmailControl',\n  importPath: '@vtex/faststore/components',\n  component: AccessCodeEmailControl,\n  editor: { label: 'Access Code Email', category: 'identity' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n    placeholder: { type: 'string', label: 'Placeholder' },\n    invalidEmailMessage: { type: 'string', label: 'Invalid email message' },\n  },\n  guideline:\n    'The draft email input for the access-code flow: visible only at the request step, pre-fills from clientProfile.email when known but never persists an edit anywhere — it is purely the argument requestAccessCode/validateAccessCode dispatch with. Must be inside AccessCodeSignInRoot. See access-code-sign-in.md.',\n});\n\nexport const AccessCodeRequestControlDefinition = defineComponent<AccessCodeRequestControlProps>({\n  name: 'AccessCodeRequestControl',\n  importPath: '@vtex/faststore/components',\n  component: AccessCodeRequestControl,\n  actions: { session: ['requestAccessCode'] },\n  editor: { label: 'Access Code Request', category: 'identity' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n    sendLimitMessage: { type: 'string', label: 'Send-limit message' },\n    blockedMessage: { type: 'string', label: 'Blocked message' },\n    networkErrorMessage: { type: 'string', label: 'Network error message' },\n  },\n  guideline:\n    'Send-code step: disabled until the Root-owned draft email is a valid, non-empty address; dispatches $actions.session.requestAccessCode with it and advances the stepper on success. Failures render inline, never as a blocking error. Must be inside AccessCodeSignInRoot. See access-code-sign-in.md.',\n});\n\nexport const AccessCodeValidateControlDefinition = defineComponent<AccessCodeValidateControlProps>({\n  name: 'AccessCodeValidateControl',\n  importPath: '@vtex/faststore/components',\n  component: AccessCodeValidateControl,\n  actions: { session: ['validateAccessCode'] },\n  editor: { label: 'Access Code Validate', category: 'identity' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n    placeholder: { type: 'string', label: 'Placeholder' },\n    submitLabel: { type: 'string', label: 'Submit label' },\n    codeLength: { type: 'number', default: 6, label: 'Code length' },\n    invalidCodeMessage: { type: 'string', label: 'Invalid code message' },\n    blockedMessage: { type: 'string', label: 'Blocked message' },\n    networkErrorMessage: { type: 'string', label: 'Network error message' },\n  },\n  guideline:\n    'Code-entry step: composes AccessCodeField and dispatches $actions.session.validateAccessCode with the Root-owned email and authenticationToken; a successful validate flips the session reactively and hides the Root. Must be inside AccessCodeSignInRoot. See access-code-sign-in.md.',\n});\n\n// ---------------------------------------------------------------------------\n// Implementations\n// ---------------------------------------------------------------------------\n\n/**\n * Data-owning root of the access-code sign-in flow. Self-gates on two signals:\n * `useSession().state !== 'loggedIn'` (available from anonymous through identified; hides once\n * signed in) and `sessionAuthProviders.accessKeyAuthentication === true`. An unresolved fragment\n * read (`$data` still `null`) is treated as \"provider not enabled\" — the flow stays hidden rather\n * than flashing. Owns the `step`/`authenticationToken` stepper plus a locally-typed draft `email`\n * as local state, broadcasting all of it through context to its children. The draft email pre-fills\n * from `clientProfile.email` once (for an already-identified shopper) but a shopper edit is never\n * persisted anywhere by this family — it is purely the requestAccessCode/validateAccessCode\n * argument; the server sets clientProfileData.email as a side effect of a successful validate.\n * Reacts automatically once `useSession()` flips to `loggedIn` — no manual unmount call anywhere in\n * this family.\n */\nexport function AccessCodeSignInRoot({ $data: $dataProp, className, children, ...props }: AccessCodeSignInRootProps) {\n  const $data = useDataOverride($dataProp);\n  const { state } = useSession();\n\n  const [step, setStep] = useState<AccessCodeSignInStep>('request');\n  const [authenticationToken, setAuthenticationToken] = useState<string | null>(null);\n\n  const startValidation = useCallback((token: string) => {\n    setAuthenticationToken(token);\n    setStep('validate');\n  }, []);\n\n  const savedEmail = $data?.clientProfile?.email ?? '';\n  const [email, setEmailState] = useState('');\n  const [touched, setTouched] = useState(false);\n\n  // Pre-fill from the resolving/known profile email, but only while still at the request step and\n  // until the shopper edits the draft — mirrors ClientProfileForm's untouched-field re-seed, never\n  // clobbering an in-progress edit. Freezing the re-seed once the flow leaves 'request' keeps a\n  // mid-flow profile-cache change from diverging the email between requestAccessCode and\n  // validateAccessCode (the server rejects a validate whose email differs from the request).\n  useEffect(() => {\n    if (step === 'request' && !touched) setEmailState(savedEmail);\n  }, [savedEmail, touched, step]);\n\n  const setEmail = useCallback((next: string) => {\n    setTouched(true);\n    setEmailState(next);\n  }, []);\n\n  const providerEnabled = $data?.sessionAuthProviders?.accessKeyAuthentication ?? false;\n\n  const contextValue = useMemo<AccessCodeSignInContextValue>(\n    () => ({ email, setEmail, step, authenticationToken, startValidation }),\n    [email, setEmail, step, authenticationToken, startValidation],\n  );\n\n  const gated = state !== 'loggedIn' && providerEnabled;\n  if (!gated) return null;\n\n  return (\n    <AccessCodeSignInContext value={contextValue}>\n      <div {...props} className={className} data-fs-access-code-sign-in-root=\"\">\n        {children}\n      </div>\n    </AccessCodeSignInContext>\n  );\n}\n\n/**\n * The draft email input for the access-code flow. Renders only at the request step. Bound to the\n * Root's local `email`/`setEmail` — never a fragment, never a mutation of its own; typing here\n * never touches the cart. Format validation is `EmailField`'s own blur-triggered check (never\n * per-keystroke); `invalidEmailMessage` is only its fallback text, mirroring how\n * `EmailIdentificationControl` defers to the same particle for the same reason.\n */\nexport function AccessCodeEmailControl({\n  label,\n  placeholder,\n  invalidEmailMessage,\n  className,\n  ...props\n}: AccessCodeEmailControlProps) {\n  const { step, email, setEmail } = useAccessCodeSignIn();\n\n  if (step !== 'request') return null;\n\n  return (\n    <div {...props} className={className} data-fs-access-code-email-control=\"\">\n      <EmailField\n        label={label}\n        placeholder={placeholder}\n        value={email}\n        onValueChange={setEmail}\n        errorMessage={invalidEmailMessage}\n      />\n    </div>\n  );\n}\n\n/**\n * Renders only while the Root's stepper is at `step === 'request'`. Reads the draft email from\n * context and dispatches `$actions.session.requestAccessCode({ email })` once it is a valid,\n * non-empty address (no account-existence pre-check beyond that format gate). On a result with a\n * non-null token and no `userErrors`, advances the Root's stepper. Every `userErrors` entry renders\n * inline via a host-supplied, per-code message; the step never changes on error, so the shopper can\n * retry or abandon the method and continue as a guest.\n */\nexport function AccessCodeRequestControl({\n  label,\n  pendingLabel,\n  sendLimitMessage,\n  blockedMessage,\n  networkErrorMessage,\n  onRequested,\n  $actions: $actionsProp,\n  className,\n  ...props\n}: AccessCodeRequestControlProps) {\n  const $actions = useActionsOverride($actionsProp);\n  const { step, email, startValidation } = useAccessCodeSignIn();\n  const [pending, setPending] = useState(false);\n  const [error, setError] = useState<SessionUserError | null>(null);\n\n  if (step !== 'request') return null;\n\n  const canSubmit = !pending && isValidEmail(email);\n\n  async function handleClick() {\n    if (!canSubmit) return;\n    setPending(true);\n    setError(null);\n\n    try {\n      const result = (await $actions?.session?.requestAccessCode?.({ email })) ?? {\n        authenticationToken: null,\n        userErrors: [],\n      };\n\n      if (result.authenticationToken && result.userErrors.length === 0) {\n        startValidation(result.authenticationToken);\n        onRequested?.(result.authenticationToken);\n        return;\n      }\n\n      const [firstError] = result.userErrors;\n      if (firstError) setError(firstError);\n    } finally {\n      setPending(false);\n    }\n  }\n\n  const message = error ? requestErrorMessage(error, { sendLimitMessage, blockedMessage, networkErrorMessage }) : null;\n\n  return (\n    <div\n      {...props}\n      className={className}\n      data-fs-access-code-request-control=\"\"\n      {...(pending ? { 'data-fs-access-code-request-pending': '' } : {})}\n    >\n      <button\n        type=\"button\"\n        onClick={handleClick}\n        disabled={!canSubmit}\n        aria-busy={pending || undefined}\n        data-fs-access-code-request-submit=\"\"\n        data-fs-button=\"\"\n      >\n        {pending ? (pendingLabel ?? label) : label}\n      </button>\n      {message ? (\n        <div role=\"alert\" data-fs-access-code-request-error=\"\">\n          {message}\n        </div>\n      ) : null}\n    </div>\n  );\n}\n\n/**\n * Renders only while the Root's stepper is at `step === 'validate'`. Composes `AccessCodeField` for\n * the code value and a submit control, disabled below `codeLength` (a UX courtesy, never a\n * validity claim). Dispatches `$actions.session.validateAccessCode` with the email and\n * `authenticationToken` read from context. On a non-empty `userErrors` result, sets the field's\n * `invalid`/`errorMessage` from a host-supplied per-code message and retains the code/token so the\n * shopper can retry without re-requesting. On success it calls the optional `onValidated` and renders\n * no local \"success\" UI — `useSession()` flipping to `loggedIn` is what makes the whole Root\n * disappear.\n */\nexport function AccessCodeValidateControl({\n  label,\n  placeholder,\n  submitLabel,\n  codeLength = 6,\n  invalidCodeMessage,\n  blockedMessage,\n  missingAuthContextMessage,\n  networkErrorMessage,\n  onValidated,\n  $actions: $actionsProp,\n  className,\n  ...props\n}: AccessCodeValidateControlProps) {\n  const $actions = useActionsOverride($actionsProp);\n  const { step, email, authenticationToken } = useAccessCodeSignIn();\n  const [code, setCode] = useState('');\n  const [pending, setPending] = useState(false);\n  const [error, setError] = useState<SessionUserError | null>(null);\n\n  if (step !== 'validate') return null;\n\n  const canSubmit = !pending && code.length >= codeLength && authenticationToken != null;\n\n  async function handleSubmit(event: FormEvent<HTMLFormElement>) {\n    event.preventDefault();\n    if (!canSubmit || authenticationToken == null) return;\n\n    setPending(true);\n    setError(null);\n\n    try {\n      const errors =\n        (await $actions?.session?.validateAccessCode?.({ email, accessCode: code, authenticationToken })) ?? [];\n\n      const [firstError] = errors;\n      if (firstError) {\n        setError(firstError);\n        return;\n      }\n    } finally {\n      setPending(false);\n    }\n\n    onValidated?.();\n  }\n\n  function handleCodeChange(next: string) {\n    setCode(next);\n    if (error) setError(null);\n  }\n\n  const errorMessage = error\n    ? validateErrorMessage(error, {\n        invalidCodeMessage,\n        blockedMessage,\n        missingAuthContextMessage,\n        networkErrorMessage,\n      })\n    : undefined;\n\n  return (\n    <div\n      {...props}\n      className={className}\n      data-fs-access-code-validate-control=\"\"\n      {...(pending ? { 'data-fs-access-code-validate-pending': '' } : {})}\n    >\n      <form onSubmit={handleSubmit}>\n        <AccessCodeField\n          label={label}\n          placeholder={placeholder}\n          value={code}\n          maxLength={codeLength}\n          onValueChange={handleCodeChange}\n          disabled={pending}\n          invalid={error != null}\n          errorMessage={errorMessage}\n        />\n        <button\n          type=\"submit\"\n          disabled={!canSubmit}\n          aria-busy={pending || undefined}\n          data-fs-access-code-validate-submit=\"\"\n          data-fs-button=\"\"\n        >\n          {submitLabel}\n        </button>\n      </form>\n    </div>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Namespace export\n// ---------------------------------------------------------------------------\n\nexport const AccessCodeSignIn = {\n  Root: AccessCodeSignInRoot,\n  Email: AccessCodeEmailControl,\n  Request: AccessCodeRequestControl,\n  Validate: AccessCodeValidateControl,\n};\n"],"mappings":"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"}
+{"version":3,"file":"access-code-sign-in.js","names":[],"sources":["../../../src/matter/access-code-sign-in/access-code-sign-in.tsx"],"sourcesContent":["'use client';\n\nimport { defineComponent } from '@vtex/fs-core';\nimport type { ComponentPropsWithRef, FormEvent } from 'react';\nimport { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';\nimport { AccessCodeField } from '../../particles/access-code-field/access-code-field.js';\nimport { EmailField, isValidEmail } from '../../particles/email-field/email-field.js';\nimport { useActionsOverride } from '../../sdk/actions/actions-override-context.js';\nimport type { ComponentActions } from '../../sdk/actions/types.js';\nimport { useDataOverride } from '../../sdk/data/data-override-context.js';\nimport type { SessionUserError } from '../../sdk/session/auth-operations.js';\nimport { resolveAuthoredCopy } from '../../utils/resolve-authored-copy.js';\nimport { useSession } from '../session/session.js';\n\n// ---------------------------------------------------------------------------\n// GraphQL Fragment (colocated, ADR-0011) — clientProfile.email seeds the draft email as a\n// convenience pre-fill for an already-identified shopper; sessionAuthProviders.accessKeyAuthentication\n// is the account gate. Authored as a raw string, mirroring EmailIdentificationControl/ShippingSimulator.\n// ---------------------------------------------------------------------------\n\nconst fragment = /* GraphQL */ `\n  fragment AccessCodeSignInData on Query {\n    clientProfile {\n      __typename\n      id\n      email\n    }\n    sessionAuthProviders {\n      accessKeyAuthentication\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Colocated fragment slice forwarded by the reactive runtime — `null` until both fields resolve. */\nexport type AccessCodeSignInSlice = {\n  clientProfile: { email: string | null } | null;\n  sessionAuthProviders: { accessKeyAuthentication: boolean } | null;\n};\n\nexport type AccessCodeSignInStep = 'request' | 'validate';\n\nexport type AccessCodeSignInContextValue = Readonly<{\n  /** The shopper's locally-typed draft email — never written to the cart; only ever an argument to\n   * requestAccessCode/validateAccessCode. Pre-fills from `clientProfile.email` when known, but a\n   * shopper edit is never persisted anywhere by this family. */\n  email: string;\n  /** Updates the draft email; marks it as shopper-touched so pre-fill no longer overwrites it. */\n  setEmail: (email: string) => void;\n  step: AccessCodeSignInStep;\n  /** Opaque token round-tripped from requestAccessCode into validateAccessCode. */\n  authenticationToken: string | null;\n  /** Called by AccessCodeRequestControl on a successful requestAccessCode. */\n  startValidation: (authenticationToken: string) => void;\n}>;\n\nexport type AccessCodeSignInRootProps = ComponentPropsWithRef<'div'> & {\n  $data?: AccessCodeSignInSlice | null;\n};\n\nexport type AccessCodeEmailControlProps = ComponentPropsWithRef<'div'> & {\n  label?: string;\n  placeholder?: string;\n  invalidEmailMessage?: string;\n};\n\nexport type AccessCodeRequestControlProps = ComponentPropsWithRef<'div'> & {\n  label?: string;\n  pendingLabel?: string;\n  sendLimitMessage?: string;\n  blockedMessage?: string;\n  networkErrorMessage?: string;\n  onRequested?: (authenticationToken: string) => void;\n  $actions?: ComponentActions;\n};\n\nexport type AccessCodeValidateControlProps = ComponentPropsWithRef<'div'> & {\n  label?: string;\n  placeholder?: string;\n  submitLabel?: string;\n  codeLength?: number;\n  invalidCodeMessage?: string;\n  blockedMessage?: string;\n  missingAuthContextMessage?: string;\n  networkErrorMessage?: string;\n  onValidated?: () => void;\n  $actions?: ComponentActions;\n};\n\n// ---------------------------------------------------------------------------\n// Context\n// ---------------------------------------------------------------------------\n\nconst ACCESS_CODE_SIGN_IN_CONTEXT_UNSET = Symbol('AccessCodeSignInContextUnset');\n\nconst AccessCodeSignInContext = createContext<AccessCodeSignInContextValue | typeof ACCESS_CODE_SIGN_IN_CONTEXT_UNSET>(\n  ACCESS_CODE_SIGN_IN_CONTEXT_UNSET,\n);\n\n/**\n * Read the stepper state (email, step, authenticationToken) from the nearest `AccessCodeSignInRoot`.\n * Throws when called outside that subtree — a misplaced control is a composition bug that should\n * surface immediately, mirroring `useShippingSimulator()`/`useSession()`.\n */\nfunction useAccessCodeSignIn(): AccessCodeSignInContextValue {\n  const ctx = useContext(AccessCodeSignInContext);\n  if (ctx === ACCESS_CODE_SIGN_IN_CONTEXT_UNSET) {\n    throw new Error('AccessCodeSignIn components must be used inside AccessCodeSignInRoot.');\n  }\n  return ctx;\n}\n\n// ---------------------------------------------------------------------------\n// Error-code → message mapping — every failure surfaces inline, at the control that produced it;\n// an unmapped code falls back to the server-supplied message rather than being silent. Each mapped\n// case is resolved through `resolveAuthoredCopy` (T38, FR-5): an authored empty or whitespace-only\n// message falls back to the server-supplied `error.message` rather than rendering a blank alert.\n// ---------------------------------------------------------------------------\n\nfunction requestErrorMessage(\n  error: SessionUserError,\n  props: Pick<AccessCodeRequestControlProps, 'sendLimitMessage' | 'blockedMessage' | 'networkErrorMessage'>,\n): string {\n  switch (error.code) {\n    case 'ACCESS_CODE_SEND_LIMIT':\n      return resolveAuthoredCopy(props.sendLimitMessage, error.message);\n    case 'BLOCKED':\n      return resolveAuthoredCopy(props.blockedMessage, error.message);\n    case 'NETWORK_ERROR':\n      return resolveAuthoredCopy(props.networkErrorMessage, error.message);\n    default:\n      return error.message;\n  }\n}\n\nfunction validateErrorMessage(\n  error: SessionUserError,\n  props: Pick<\n    AccessCodeValidateControlProps,\n    'invalidCodeMessage' | 'blockedMessage' | 'missingAuthContextMessage' | 'networkErrorMessage'\n  >,\n): string {\n  switch (error.code) {\n    case 'INVALID_ACCESS_CODE':\n      return resolveAuthoredCopy(props.invalidCodeMessage, error.message);\n    case 'BLOCKED':\n      return resolveAuthoredCopy(props.blockedMessage, error.message);\n    case 'MISSING_AUTH_CONTEXT':\n      return resolveAuthoredCopy(props.missingAuthContextMessage, error.message);\n    case 'NETWORK_ERROR':\n      return resolveAuthoredCopy(props.networkErrorMessage, error.message);\n    default:\n      return error.message;\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Definitions\n// ---------------------------------------------------------------------------\n\nexport const AccessCodeSignInRootDefinition = defineComponent<AccessCodeSignInRootProps>({\n  name: 'AccessCodeSignInRoot',\n  importPath: '@vtex/faststore/components',\n  component: AccessCodeSignInRoot,\n  fragment,\n  fetchStrategy: 'reactive',\n  requiresContext: 'session',\n  editor: { label: 'Access Code Sign-In', category: 'identity' },\n  schema: {},\n  guideline:\n    'Self-gating root of the anonymous-or-identified, email + access-code sign-in: renders nothing once loggedIn or when the account disables accessKeyAuthentication, but is available from the anonymous state onward. Owns a locally-typed draft email (never written to the cart) and the request/validate stepper. Must be inside SessionRoot. See access-code-sign-in.md.',\n});\n\nexport const AccessCodeEmailControlDefinition = defineComponent<AccessCodeEmailControlProps>({\n  name: 'AccessCodeEmailControl',\n  importPath: '@vtex/faststore/components',\n  component: AccessCodeEmailControl,\n  editor: { label: 'Access Code Email', category: 'identity' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n    placeholder: { type: 'string', label: 'Placeholder' },\n    invalidEmailMessage: { type: 'string', label: 'Invalid email message' },\n  },\n  guideline:\n    'The draft email input for the access-code flow: visible only at the request step, pre-fills from clientProfile.email when known but never persists an edit anywhere — it is purely the argument requestAccessCode/validateAccessCode dispatch with. Must be inside AccessCodeSignInRoot. See access-code-sign-in.md.',\n});\n\nexport const AccessCodeRequestControlDefinition = defineComponent<AccessCodeRequestControlProps>({\n  name: 'AccessCodeRequestControl',\n  importPath: '@vtex/faststore/components',\n  component: AccessCodeRequestControl,\n  actions: { session: ['requestAccessCode'] },\n  editor: { label: 'Access Code Request', category: 'identity' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n    sendLimitMessage: { type: 'string', label: 'Send-limit message' },\n    blockedMessage: { type: 'string', label: 'Blocked message' },\n    networkErrorMessage: { type: 'string', label: 'Network error message' },\n  },\n  guideline:\n    'Send-code step: disabled until the Root-owned draft email is a valid, non-empty address; dispatches $actions.session.requestAccessCode with it and advances the stepper on success. Failures render inline, never as a blocking error. Must be inside AccessCodeSignInRoot. See access-code-sign-in.md.',\n});\n\nexport const AccessCodeValidateControlDefinition = defineComponent<AccessCodeValidateControlProps>({\n  name: 'AccessCodeValidateControl',\n  importPath: '@vtex/faststore/components',\n  component: AccessCodeValidateControl,\n  actions: { session: ['validateAccessCode'] },\n  editor: { label: 'Access Code Validate', category: 'identity' },\n  schema: {\n    label: { type: 'string', label: 'Label' },\n    placeholder: { type: 'string', label: 'Placeholder' },\n    submitLabel: { type: 'string', label: 'Submit label' },\n    codeLength: { type: 'number', default: 6, label: 'Code length' },\n    invalidCodeMessage: { type: 'string', label: 'Invalid code message' },\n    blockedMessage: { type: 'string', label: 'Blocked message' },\n    networkErrorMessage: { type: 'string', label: 'Network error message' },\n  },\n  guideline:\n    'Code-entry step: composes AccessCodeField and dispatches $actions.session.validateAccessCode with the Root-owned email and authenticationToken; a successful validate flips the session reactively and hides the Root. Must be inside AccessCodeSignInRoot. See access-code-sign-in.md.',\n});\n\n// ---------------------------------------------------------------------------\n// Implementations\n// ---------------------------------------------------------------------------\n\n/**\n * Data-owning root of the access-code sign-in flow. Self-gates on two signals:\n * `useSession().state !== 'loggedIn'` (available from anonymous through identified; hides once\n * signed in) and `sessionAuthProviders.accessKeyAuthentication === true`. An unresolved fragment\n * read (`$data` still `null`) is treated as \"provider not enabled\" — the flow stays hidden rather\n * than flashing. Owns the `step`/`authenticationToken` stepper plus a locally-typed draft `email`\n * as local state, broadcasting all of it through context to its children. The draft email pre-fills\n * from `clientProfile.email` once (for an already-identified shopper) but a shopper edit is never\n * persisted anywhere by this family — it is purely the requestAccessCode/validateAccessCode\n * argument; the server sets clientProfileData.email as a side effect of a successful validate.\n * Reacts automatically once `useSession()` flips to `loggedIn` — no manual unmount call anywhere in\n * this family.\n */\nexport function AccessCodeSignInRoot({ $data: $dataProp, className, children, ...props }: AccessCodeSignInRootProps) {\n  const $data = useDataOverride($dataProp);\n  const { state } = useSession();\n\n  const [step, setStep] = useState<AccessCodeSignInStep>('request');\n  const [authenticationToken, setAuthenticationToken] = useState<string | null>(null);\n\n  const startValidation = useCallback((token: string) => {\n    setAuthenticationToken(token);\n    setStep('validate');\n  }, []);\n\n  const savedEmail = $data?.clientProfile?.email ?? '';\n  const [email, setEmailState] = useState('');\n  const [touched, setTouched] = useState(false);\n\n  // Pre-fill from the resolving/known profile email, but only while still at the request step and\n  // until the shopper edits the draft — mirrors ClientProfileRoot's untouched-field re-seed, never\n  // clobbering an in-progress edit. Freezing the re-seed once the flow leaves 'request' keeps a\n  // mid-flow profile-cache change from diverging the email between requestAccessCode and\n  // validateAccessCode (the server rejects a validate whose email differs from the request).\n  useEffect(() => {\n    if (step === 'request' && !touched) setEmailState(savedEmail);\n  }, [savedEmail, touched, step]);\n\n  const setEmail = useCallback((next: string) => {\n    setTouched(true);\n    setEmailState(next);\n  }, []);\n\n  const providerEnabled = $data?.sessionAuthProviders?.accessKeyAuthentication ?? false;\n\n  const contextValue = useMemo<AccessCodeSignInContextValue>(\n    () => ({ email, setEmail, step, authenticationToken, startValidation }),\n    [email, setEmail, step, authenticationToken, startValidation],\n  );\n\n  const gated = state !== 'loggedIn' && providerEnabled;\n  if (!gated) return null;\n\n  return (\n    <AccessCodeSignInContext value={contextValue}>\n      <div {...props} className={className} data-fs-access-code-sign-in-root=\"\">\n        {children}\n      </div>\n    </AccessCodeSignInContext>\n  );\n}\n\n/**\n * The draft email input for the access-code flow. Renders only at the request step. Bound to the\n * Root's local `email`/`setEmail` — never a fragment, never a mutation of its own; typing here\n * never touches the cart. Format validation is `EmailField`'s own blur-triggered check (never\n * per-keystroke); `invalidEmailMessage` is only its fallback text, mirroring how\n * `EmailIdentificationControl` defers to the same particle for the same reason.\n */\nexport function AccessCodeEmailControl({\n  label,\n  placeholder,\n  invalidEmailMessage,\n  className,\n  ...props\n}: AccessCodeEmailControlProps) {\n  const { step, email, setEmail } = useAccessCodeSignIn();\n\n  if (step !== 'request') return null;\n\n  return (\n    <div {...props} className={className} data-fs-access-code-email-control=\"\">\n      <EmailField\n        label={label}\n        placeholder={placeholder}\n        value={email}\n        onValueChange={setEmail}\n        errorMessage={invalidEmailMessage}\n      />\n    </div>\n  );\n}\n\n/**\n * Renders only while the Root's stepper is at `step === 'request'`. Reads the draft email from\n * context and dispatches `$actions.session.requestAccessCode({ email })` once it is a valid,\n * non-empty address (no account-existence pre-check beyond that format gate). On a result with a\n * non-null token and no `userErrors`, advances the Root's stepper. Every `userErrors` entry renders\n * inline via a host-supplied, per-code message; the step never changes on error, so the shopper can\n * retry or abandon the method and continue as a guest.\n */\nexport function AccessCodeRequestControl({\n  label,\n  pendingLabel,\n  sendLimitMessage,\n  blockedMessage,\n  networkErrorMessage,\n  onRequested,\n  $actions: $actionsProp,\n  className,\n  ...props\n}: AccessCodeRequestControlProps) {\n  const $actions = useActionsOverride($actionsProp);\n  const { step, email, startValidation } = useAccessCodeSignIn();\n  const [pending, setPending] = useState(false);\n  const [error, setError] = useState<SessionUserError | null>(null);\n\n  if (step !== 'request') return null;\n\n  const canSubmit = !pending && isValidEmail(email);\n\n  async function handleClick() {\n    if (!canSubmit) return;\n    setPending(true);\n    setError(null);\n\n    try {\n      const result = (await $actions?.session?.requestAccessCode?.({ email })) ?? {\n        authenticationToken: null,\n        userErrors: [],\n      };\n\n      if (result.authenticationToken && result.userErrors.length === 0) {\n        startValidation(result.authenticationToken);\n        onRequested?.(result.authenticationToken);\n        return;\n      }\n\n      const [firstError] = result.userErrors;\n      if (firstError) setError(firstError);\n    } finally {\n      setPending(false);\n    }\n  }\n\n  const message = error ? requestErrorMessage(error, { sendLimitMessage, blockedMessage, networkErrorMessage }) : null;\n\n  return (\n    <div\n      {...props}\n      className={className}\n      data-fs-access-code-request-control=\"\"\n      {...(pending ? { 'data-fs-access-code-request-pending': '' } : {})}\n    >\n      <button\n        type=\"button\"\n        onClick={handleClick}\n        disabled={!canSubmit}\n        aria-busy={pending || undefined}\n        data-fs-access-code-request-submit=\"\"\n        data-fs-button=\"\"\n      >\n        {/* T38, FR-5: resolveAuthoredCopy so an authored empty/whitespace-only pendingLabel falls\n            back to `label` instead of blanking the button while the request is in flight. */}\n        {pending ? resolveAuthoredCopy(pendingLabel, label ?? '') : label}\n      </button>\n      {message ? (\n        <div role=\"alert\" data-fs-access-code-request-error=\"\">\n          {message}\n        </div>\n      ) : null}\n    </div>\n  );\n}\n\n/**\n * Renders only while the Root's stepper is at `step === 'validate'`. Composes `AccessCodeField` for\n * the code value and a submit control, disabled below `codeLength` (a UX courtesy, never a\n * validity claim). Dispatches `$actions.session.validateAccessCode` with the email and\n * `authenticationToken` read from context. On a non-empty `userErrors` result, sets the field's\n * `invalid`/`errorMessage` from a host-supplied per-code message and retains the code/token so the\n * shopper can retry without re-requesting. On success it calls the optional `onValidated` and renders\n * no local \"success\" UI — `useSession()` flipping to `loggedIn` is what makes the whole Root\n * disappear.\n */\nexport function AccessCodeValidateControl({\n  label,\n  placeholder,\n  submitLabel,\n  codeLength = 6,\n  invalidCodeMessage,\n  blockedMessage,\n  missingAuthContextMessage,\n  networkErrorMessage,\n  onValidated,\n  $actions: $actionsProp,\n  className,\n  ...props\n}: AccessCodeValidateControlProps) {\n  const $actions = useActionsOverride($actionsProp);\n  const { step, email, authenticationToken } = useAccessCodeSignIn();\n  const [code, setCode] = useState('');\n  const [pending, setPending] = useState(false);\n  const [error, setError] = useState<SessionUserError | null>(null);\n\n  if (step !== 'validate') return null;\n\n  const canSubmit = !pending && code.length >= codeLength && authenticationToken != null;\n\n  async function handleSubmit(event: FormEvent<HTMLFormElement>) {\n    event.preventDefault();\n    if (!canSubmit || authenticationToken == null) return;\n\n    setPending(true);\n    setError(null);\n\n    try {\n      const errors =\n        (await $actions?.session?.validateAccessCode?.({ email, accessCode: code, authenticationToken })) ?? [];\n\n      const [firstError] = errors;\n      if (firstError) {\n        setError(firstError);\n        return;\n      }\n    } finally {\n      setPending(false);\n    }\n\n    onValidated?.();\n  }\n\n  function handleCodeChange(next: string) {\n    setCode(next);\n    if (error) setError(null);\n  }\n\n  const errorMessage = error\n    ? validateErrorMessage(error, {\n        invalidCodeMessage,\n        blockedMessage,\n        missingAuthContextMessage,\n        networkErrorMessage,\n      })\n    : undefined;\n\n  return (\n    <div\n      {...props}\n      className={className}\n      data-fs-access-code-validate-control=\"\"\n      {...(pending ? { 'data-fs-access-code-validate-pending': '' } : {})}\n    >\n      <form onSubmit={handleSubmit}>\n        <AccessCodeField\n          label={label}\n          placeholder={placeholder}\n          value={code}\n          maxLength={codeLength}\n          onValueChange={handleCodeChange}\n          disabled={pending}\n          invalid={error != null}\n          errorMessage={errorMessage}\n        />\n        <button\n          type=\"submit\"\n          disabled={!canSubmit}\n          aria-busy={pending || undefined}\n          data-fs-access-code-validate-submit=\"\"\n          data-fs-button=\"\"\n        >\n          {submitLabel}\n        </button>\n      </form>\n    </div>\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Namespace export\n// ---------------------------------------------------------------------------\n\nexport const AccessCodeSignIn = {\n  Root: AccessCodeSignInRoot,\n  Email: AccessCodeEmailControl,\n  Request: AccessCodeRequestControl,\n  Validate: AccessCodeValidateControl,\n};\n"],"mappings":"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"}

package/dist/matter/billing-address/billing-address.d.ts

@@ -0,0 +1,165 @@
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentActions } from "../../sdk/actions/types.js";
+import { ComponentPropsWithRef } from "react";
+//#region src/matter/billing-address/billing-address.d.ts
+/**
+ * The `BillingAddress` matter (specs/billing-address.md, T11 of the Credit Card epic;
+ * docs/features/credit-card/rfc.md § D6). A "same as delivery" toggle (default on) plus, when off, a
+ * country-specific address form that persists via `$actions.payment.setBillingAddress`
+ * (already shipped by T4, zero consumers before this task).
+ *
+ * The shared `Address` composition RFC D6 names (shipping and billing as two control matters over
+ * one set of reusable particles) is DEFERRED — an implementation-time call the engineer resolved
+ * narrow (specs/billing-address.md Decision 1). This component builds its own controls and imports
+ * `countryDescriptors` from `../shipping-address/country-descriptors.js`; `matter/shipping-address/`
+ * is read, never modified — zero bytes of that directory change here.
+ *
+ * There is NO read-back path for a persisted billing address (specs/billing-address.md Decision 3):
+ * `type Payment` carries no `billingAddress` field, and `setBillingAddress` itself resolves only
+ * `userErrors`, discarding the mutation's own echo. This component declares no fragment and renders
+ * nothing below the toggle while "same as delivery" is checked, not even the delivery address
+ * (specs/stop-re-rendering-the-full-delivery.md, T175). The custom-address form always starts blank,
+ * and its own local state is the sole source of truth for what was typed.
+ *
+ * Only a boolean rides the shared `draft` (`billingAddressDifferent`, widened onto `PaymentDraft` by
+ * this task under sole ownership of `use-payment-method-selection.ts` — specs/billing-address.md
+ * Decision 5); the address itself is persisted server-side by this component's own action call, never
+ * passed through the draft. `setBillingAddress` is dispatched at exactly two points (Decision 9): the
+ * toggle's transition back to "same as delivery", and the custom form's explicit submit control —
+ * never on mount, never per keystroke.
+ *
+ * **`draft.billingAddressDifferent` only ever becomes `true` once `setBillingAddress` has actually
+ * persisted a different address (PR #544 N1).** Unchecking "same as delivery" opens the form
+ * (`formOpen`, local-only state below) but does not touch the draft — `gateway.ts`'s own doc comment
+ * ("`setBillingAddress` already persisted it … so the gateway reads it from there") is the contract
+ * this must not break: publishing `true` before anything is persisted would point the gateway at an
+ * `invoiceData` address nothing ever wrote. The engineer's own resolution for this (session of
+ * 2026-07-31): the new-address fields become required whenever "different" is selected, so this
+ * component's own submit blocks on an incomplete address (`isBillingAddressFormValid`) — but that
+ * alone cannot stop a shopper from declining "same as delivery" and clicking Place Order without ever
+ * opening the form's own submit control, which is why the draft write itself is gated on success, not
+ * merely the submit button.
+ *
+ * **The native `required` attribute below is cosmetic here, not an enforcement mechanism (PR #544
+ * N7).** This file renders no `aria-required` at all — only `required` (native HTML). There is no
+ * `<form>` in this render tree and the submit control is `type="button"`, so the browser's own
+ * constraint validation never runs — nothing in this file or its tests may claim this attribute itself
+ * prevents a shopper from placing an order with an unsaved address; the actual submit gate is
+ * `isBillingAddressFormValid`, read at the submit control's own `disabled` below. Since T38
+ * (specs/harden-and-verify-accessibility-across-the.md FR-6) each rendered field does carry a
+ * `Field.Error`, but it is driven by a local blur-tracked `touched` set and this same non-blank rule,
+ * never by `required`'s own native `ValidityState` — so this paragraph's point is unchanged: `required`
+ * itself still enforces nothing here. What this component owes, and
+ * does: make the gap **visible** — an inline `role="status"` notice while the form is open and nothing
+ * has been persisted yet — and publish that same fact (`setDraftBillingAddressUnsaved`) onto the
+ * shared draft, from the identical expression the notice renders from (T24,
+ * specs/cardholder-document-submit-gate.md FR-6). **The actual hard block lives elsewhere**: T24's
+ * `usePaymentSubmitGate()` reads that published fact and refuses Place Order client-side — this
+ * component's own job stops at publishing the fact and showing the notice, never at gating the CTA
+ * itself. See `specs/billing-address.md`'s Documentation Gaps #1 for the deferral this closes.
+ */
+/**
+ * Local-only values for the "different" address form, keyed by the country descriptor's own
+ * canonical field names — a plain string index signature, not a closed set of properties, so a future
+ * country descriptor introducing a new field name needs no type change here (mirrors
+ * `FieldDescriptor.name: string`'s own deliberately untyped choice; specs/billing-address.md
+ * Decision 7). `postalCode` and `country` are named explicitly because this component's own logic
+ * reads both directly. Never carries a `recipientName` key: `PaymentBillingAddressUpdateInput` has no
+ * such field (Decision 4) — the render loop filters it out of whatever the descriptor lists.
+ */
+export type BillingAddressFormDraft = Readonly<{
+  postalCode: string;
+  country: string;
+  [fieldName: string]: string;
+}>;
+export type BillingAddressProps = Omit<ComponentPropsWithRef<'div'>, 'children'> & {
+  /** The "same as delivery" toggle's own accessible label. */
+  sameAsDeliveryLabel?: string;
+  /** ISO 3166-1 alpha-3 default country for the custom-address form's country selector. */
+  defaultCountry?: string;
+  /** Label for the country selector inside the custom-address form. */
+  countryLabel?: string;
+  /** Label for the control that persists a custom billing address. */
+  submitLabel?: string;
+  /** Label on the submit control while the mutation is in flight. */
+  submitPendingLabel?: string;
+  /** Shown when the selected method's validator marks a billing address required. */
+  requiredNoticeLabel?: string;
+  /** Label for the recipient-name descriptor field. Not rendered by the custom-address form today
+   *  (`OMITTED_FORM_FIELD_NAMES` — the write contract has no matching input slot, Decision 4); kept
+   *  for parity with the other seven field labels this same map covers. */
+  recipientNameLabel?: string;
+  /** Label for the street descriptor field. */
+  streetLabel?: string;
+  /** Label for the street-number descriptor field. */
+  numberLabel?: string;
+  /** Label for the complement descriptor field. Its "(optional)" suffix is the only signal that the
+   *  field is not required — `OPTIONAL_FORM_FIELD_NAMES` drives the actual `required` attribute
+   *  independently, so authoring this without the suffix loses the optionality cue, not the behavior
+   *  (R7). */
+  complementLabel?: string;
+  /** Label for the neighborhood descriptor field. Unused when the active country's descriptor has no
+   *  `neighborhood` field (e.g. USA). */
+  neighborhoodLabel?: string;
+  /** Label for the city descriptor field. */
+  cityLabel?: string;
+  /** Label for the state descriptor field. */
+  stateLabel?: string;
+  /** Label for the postal-code descriptor field. */
+  postalCodeLabel?: string;
+  /** Shown while the form is open and no address has been persisted yet (PR #544 N7) — the shopper
+   * declined "same as delivery" but has not (or not yet again) had a submit succeed, so Place Order
+   * will bill the delivery address unless they save one first. Rendered `role="status"`, not
+   * `role="alert"`: it is a persistent, advisory condition of the form being open, not a one-off
+   * announcement reacting to a rejected action (see this file's own existing `-error` alert for that
+   * shape) — see `specs/billing-address.md`'s Accessibility Contract for the site count this choice is
+   * measured against. */
+  unsavedAddressNoticeLabel?: string;
+  /** Always-on billing-match disclaimer (requirement 12.20): tells the shopper their billing address
+   *  must match the one their card issuer or bank statement holds, so an AVS mismatch does not get the
+   *  order declined with no explanation on screen. Gated on this prop and `billingMatchNoticeVisible`
+   *  only — reads no `usePayment()` value, no local state, no `$data` (FR-4), unlike the two notices
+   *  above. */
+  billingMatchNoticeLabel?: string;
+  /** Switches the billing-match disclaimer above on or off. Defaults to `true` (Decision 5 — the
+   *  requirement's own intent); subordinate to `billingMatchNoticeLabel.trim()`, which alone can still
+   *  suppress an empty notice (FR-3) regardless of this prop's value. */
+  billingMatchNoticeVisible?: boolean;
+  /**
+   * Shown as a `Field.Error` under a required, blank, touched field (T38, FR-6/FR-7) — the same
+   * non-blank rule `isBillingAddressFormValid` already applies, except `complement`
+   * (`OPTIONAL_FORM_FIELD_NAMES`), which is never marked invalid. One prop, not one per field: every
+   * rendered field shares the same rule, so seven props would be seven ways to say the same sentence.
+   * Resolved through `resolveAuthoredCopy`.
+   */
+  fieldRequiredMessage?: string;
+  /** Disables the toggle, every form field, the country selector, and the submit control. */
+  disabled?: boolean;
+  /** Compiler-injected action surface; carries `payment.setBillingAddress`. */
+  $actions?: ComponentActions;
+};
+/**
+ * Whether the toggle reads as "same as delivery" — `true` whenever the published flag is `null`
+ * (never touched, the default) or `false` (explicitly reverted); only an explicit `true` means the
+ * shopper is on the custom-address path. Takes no closure over component state, so it is safe to call
+ * fresh on every render.
+ */
+export declare function resolveSameAsDelivery(billingAddressDifferent: boolean | null | undefined): boolean;
+/**
+ * Whether the custom-address form may be submitted. Stricter than the server's own
+ * `MISSING_BILLING_ADDRESS_FIELDS` floor ("sameAsDelivery is false but postalCode **or country** was
+ * omitted" [source: `core.graphql:2857-2858`]) — every field the active country's descriptor renders,
+ * except `complement` (`OPTIONAL_FORM_FIELD_NAMES`), must be non-blank (PR #544 N1 item 1: the
+ * engineer's own rule that the new-address fields are required once "different" is selected). Resolves
+ * the descriptor from `formDraft.country` itself rather than taking a second parameter, so this stays a
+ * single self-contained fact about one `BillingAddressFormDraft` value. `country` itself is not part of
+ * `descriptor.fields` (Decision 7) and is never checked here — it always carries a non-blank value from
+ * `defaultCountry` or the selector's own current value (review F12), so it can never be the field this
+ * gate would fail on.
+ */
+export declare function isBillingAddressFormValid(formDraft: BillingAddressFormDraft): boolean;
+export declare const BillingAddressDefinition: ComponentDefinition<BillingAddressProps>;
+export declare function BillingAddress({ sameAsDeliveryLabel, defaultCountry, countryLabel, submitLabel, submitPendingLabel, requiredNoticeLabel, unsavedAddressNoticeLabel, billingMatchNoticeLabel, billingMatchNoticeVisible, recipientNameLabel, streetLabel, numberLabel, complementLabel, neighborhoodLabel, cityLabel, stateLabel, postalCodeLabel, fieldRequiredMessage, disabled, className, $actions: $actionsProp, ...props }: BillingAddressProps): import("react/jsx-runtime").JSX.Element | null;
+//#endregion
+//# sourceMappingURL=billing-address.d.ts.map