@adia-ai/web-modules 0.8.35 → 0.8.37

package/billing/payment-method-form/payment-method-form.class.js

@@ -0,0 +1,886 @@
+/**
+ * <payment-method-form-ui> — Form-participating payment-method composite.
+ *
+ * Captures card number, expiry, CVC, name on card, billing address, and
+ * country through a grid of <field-ui> + <input-ui> + <select-ui>
+ * sub-controls. Per ADR-0025 the host IS the form-associated element —
+ * no native <input type=text> is wrapped at the composite tier; the
+ * leaf primitives carry their own ElementInternals.
+ *
+ * Card-number Luhn validation, MM/YY expiry parsing, CVC 3-4 digit
+ * length check, brand detection via small regex map (visa /
+ * mastercard / amex / discover / unknown). The form chrome + structured
+ * validation lives here; tokenization against a real processor is the
+ * consumer's responsibility (Stripe Elements, Braintree, Adyen).
+ *
+ * Form value is a synthetic opaque local-mode token written ONLY after
+ * tokenize() resolves; raw card digits never leak through `value`.
+ *
+ * SPEC: .claude/docs/specs/implementation-ready/SPEC-009-payment-method-form.md
+ * ADR: .brain/adrs/0025-no-native-form-controls.md
+ * ADR: .brain/adrs/0033-light-dom-substrate.md
+ *
+ * Architecture (light-DOM, ADR-0033):
+ *   Stamps a fixed skeleton once on first connect:
+ *     [data-alert] · [data-summary] · [data-grid > field rows] · [data-legal]
+ *   Mutates per-field state via reflected attributes on each sub-control.
+ *   No template rebuilds across renders — field nodes keep identity so
+ *   focus + IME composition state survive.
+ *
+ * Public API:
+ *   .tokenize()  — Promise resolving the normalized payload (or rejects).
+ *   .reset()     — Clear every field + the resolved token.
+ *   .checkValidity() / .reportValidity() — inherited from UIFormElement.
+ */
+
+import { UIFormElement } from '@adia-ai/web-components/core/form';
+import { untracked } from '@adia-ai/web-components/core/signals';
+
+// ── Brand detection ────────────────────────────────────────────────
+//
+// Order matters: Amex regex tested first (its prefix overlaps with
+// Mastercard's older range). Conservative regex — production
+// detection uses BIN tables, but a small map covers the brand
+// recognition the LLM corpus needs (visa / mastercard / amex /
+// discover).
+const BRAND_PATTERNS = [
+  { brand: 'amex',       re: /^3[47]/ },
+  { brand: 'visa',       re: /^4/ },
+  { brand: 'mastercard', re: /^(5[1-5]|2[2-7])/ },
+  { brand: 'discover',   re: /^6(011|5)/ },
+];
+
+/** Detect the card brand from a normalized digits-only PAN. */
+function detectBrand(digits) {
+  if (!digits) return 'unknown';
+  for (const { brand, re } of BRAND_PATTERNS) {
+    if (re.test(digits)) return brand;
+  }
+  return 'unknown';
+}
+
+/** Strip all non-digit characters; keep at most 19 digits (Maestro). */
+function digitsOnly(s) {
+  return String(s || '').replace(/\D+/g, '').slice(0, 19);
+}
+
+/** Format a PAN string with spaces every 4 digits (Amex uses 4-6-5). */
+function formatPan(digits, brand) {
+  if (!digits) return '';
+  if (brand === 'amex') {
+    return digits.replace(/^(\d{0,4})(\d{0,6})(\d{0,5}).*$/, (_, a, b, c) =>
+      [a, b, c].filter(Boolean).join(' '),
+    );
+  }
+  return digits.match(/.{1,4}/g)?.join(' ') ?? '';
+}
+
+/** Luhn check on a digits-only string. */
+function luhn(digits) {
+  if (!digits || digits.length < 12) return false;
+  let sum = 0;
+  let alt = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let n = digits.charCodeAt(i) - 48;
+    if (n < 0 || n > 9) return false;
+    if (alt) {
+      n *= 2;
+      if (n > 9) n -= 9;
+    }
+    sum += n;
+    alt = !alt;
+  }
+  return sum % 10 === 0;
+}
+
+/**
+ * Parse an MM/YY (or MM/YYYY) string into { month, year } where year
+ * is the 4-digit form. Returns null on parse failure. Accepts "12/27",
+ * "12 / 27", "12/2027". Does NOT bounds-check month/year sanity beyond
+ * the parse — that's the validation step's job.
+ */
+function parseExpiry(s) {
+  if (!s) return null;
+  const m = String(s).replace(/\s+/g, '').match(/^(\d{1,2})\/(\d{2}|\d{4})$/);
+  if (!m) return null;
+  const month = Number(m[1]);
+  let year = Number(m[2]);
+  if (year < 100) year += 2000;
+  if (!Number.isFinite(month) || !Number.isFinite(year)) return null;
+  return { month, year };
+}
+
+/** Validate an expiry. Returns null on OK, an error code otherwise. */
+function validateExpiry(s) {
+  const parsed = parseExpiry(s);
+  if (!parsed) return 'expiry-format';
+  const { month, year } = parsed;
+  if (month < 1 || month > 12) return 'expiry-month';
+  const now = new Date();
+  const nowYear = now.getFullYear();
+  const nowMonth = now.getMonth() + 1;
+  if (year < nowYear || (year === nowYear && month < nowMonth)) {
+    return 'expiry-past';
+  }
+  if (year > nowYear + 50) return 'expiry-far';
+  return null;
+}
+
+/** CVC validation — 3 digits for most brands, 4 for Amex. */
+function validateCvc(cvc, brand) {
+  const digits = String(cvc || '').replace(/\D+/g, '');
+  const wantLen = brand === 'amex' ? 4 : 3;
+  if (digits.length !== wantLen) return 'cvc-length';
+  return null;
+}
+
+/** Generate a synthetic opaque local-mode token. NOT a real PSP token. */
+function makeLocalToken(seed) {
+  // 32-char hex-ish opaque; sourced from Math.random + timestamp. Real
+  // processors mint real tokens; this is the local-mode placeholder so
+  // consumers can wire the event without a network round-trip.
+  const rnd = Math.random().toString(36).slice(2);
+  const ts  = Date.now().toString(36);
+  return `pm_local_${ts}_${rnd}_${String(seed).slice(0, 4)}`;
+}
+
+const DEFAULT_COUNTRIES = ['US', 'CA', 'GB', 'DE', 'FR', 'AU'];
+
+/** Map alpha-2 to a human-readable country name. Small built-in set. */
+const COUNTRY_NAMES = {
+  US: 'United States',
+  CA: 'Canada',
+  GB: 'United Kingdom',
+  DE: 'Germany',
+  FR: 'France',
+  AU: 'Australia',
+  JP: 'Japan',
+  ES: 'Spain',
+  IT: 'Italy',
+  NL: 'Netherlands',
+  SE: 'Sweden',
+  IE: 'Ireland',
+  SG: 'Singapore',
+  IN: 'India',
+  BR: 'Brazil',
+  MX: 'Mexico',
+};
+
+function countryName(code) {
+  return COUNTRY_NAMES[code] || code;
+}
+
+export class UIPaymentMethodForm extends UIFormElement {
+  // The host carries aria-label directly; per-control `label` deprecation
+  // doesn't apply at this tier (we don't expose a `label` prop).
+  static labelDeprecated = false;
+
+  static get properties() {
+    return {
+      ...UIFormElement.properties,
+      name:                   { type: String,  default: 'paymentMethod', reflect: true },
+      value:                  { type: String,  default: '', reflect: true },
+      prefill:                { type: String,  default: '', attribute: 'prefill' },
+      countries:              { type: Array,   default: [] },
+      defaultCountry:         { type: String,  default: 'US', reflect: true, attribute: 'default-country' },
+      requireBillingAddress:  { type: Boolean, default: false, reflect: true, attribute: 'require-billing-address' },
+      disabled:               { type: Boolean, default: false, reflect: true },
+      required:               { type: Boolean, default: false, reflect: true },
+      error:                  { type: String,  default: '', reflect: true },
+      autofocus:              { type: Boolean, default: false, reflect: true },
+      // gh#853: tokenize() below already reflects this via raw
+      // setAttribute/removeAttribute; declared here too so `el.tokenizing`
+      // (JS property reads/writes) stays in sync per audit:static-properties-vs-yaml
+      // (yaml `reflect: true` requires a matching static-properties entry).
+      tokenizing:             { type: Boolean, default: false, reflect: true },
+    };
+  }
+
+  // Stamp-nothing per plan-picker pattern — we mutate a fixed
+  // skeleton rather than re-running the template engine.
+  static template = () => null;
+
+  // ── Field refs ────────────────────────────────────────────────────
+  #stamped = false;
+  #cleanups = [];
+
+  #alertHost = null;       // <alert-ui data-alert>
+  #summaryHost = null;     // <div data-summary>
+  #editButton = null;      // <button-ui> inside summary
+  #gridHost = null;        // <div data-grid>
+
+  // Per-row <field-ui> hosts (keyed by field name).
+  #fields = {
+    name: null,
+    cardNumber: null,
+    expiry: null,
+    cvc: null,
+    country: null,
+    postalCode: null,
+    addressLine1: null,
+    addressLine2: null,
+  };
+
+  // Per-row <input-ui> / <select-ui> controls (keyed by field name).
+  #controls = {
+    name: null,
+    cardNumber: null,
+    expiry: null,
+    cvc: null,
+    country: null,
+    postalCode: null,
+    addressLine1: null,
+    addressLine2: null,
+  };
+
+  #brand = 'unknown';
+  #internalUpdate = false;
+  #legalHost = null;
+  #legalSlotProbe = null;
+  #tokenizing = false;
+
+  // ── Public imperative API ─────────────────────────────────────────
+
+  /**
+   * Validate every field + emit a resolved token. Resolves with the
+   * normalized payload on success; rejects with an Error carrying
+   * `code` + `field` on failure.
+   */
+  async tokenize() {
+    if (this.#tokenizing) return Promise.reject(new Error('tokenize-inflight'));
+    this.#tokenizing = true;
+    this.setAttribute('tokenizing', '');
+    try {
+      const result = this.#validateAll();
+      if (!result.ok) {
+        const err = new Error(result.message);
+        err.code = result.code;
+        err.field = result.field;
+        this.dispatchEvent(new CustomEvent('payment-method-error', {
+          bubbles: true,
+          detail: { message: result.message, code: result.code, field: result.field },
+        }));
+        // Set host-level error attr so the alert renders.
+        this.setAttribute('aria-invalid', 'true');
+        throw err;
+      }
+
+      const detail = result.detail;
+      // Resolve `value` to a synthetic local-mode token AFTER validation
+      // succeeds — raw digits never leak through.
+      this.#internalUpdate = true;
+      try {
+        this.value = makeLocalToken(detail.last4);
+      } finally {
+        this.#internalUpdate = false;
+      }
+      this.syncValue();
+      this.removeAttribute('aria-invalid');
+
+      const payload = { token: this.value, ...detail };
+      this.dispatchEvent(new CustomEvent('submit-payment-method', {
+        bubbles: true,
+        detail: payload,
+      }));
+      return payload;
+    } finally {
+      this.removeAttribute('tokenizing');
+      this.#tokenizing = false;
+    }
+  }
+
+  /** Clear every sub-field + resolved token. */
+  reset() {
+    untracked(() => {
+      for (const key of Object.keys(this.#controls)) {
+        const ctrl = this.#controls[key];
+        if (!ctrl) continue;
+        ctrl.value = '';
+        ctrl.removeAttribute('error');
+      }
+      if (this.#controls.country) {
+        this.#controls.country.value = this.defaultCountry || 'US';
+      }
+      this.#internalUpdate = true;
+      try {
+        this.value = '';
+        this.error = '';
+      } finally {
+        this.#internalUpdate = false;
+      }
+      this.syncValue();
+      this.#brand = 'unknown';
+      this.removeAttribute('aria-invalid');
+      this.removeAttribute('error');
+      this.#syncBrandSuffix();
+    });
+  }
+
+  // ── Form-bearing override ─────────────────────────────────────────
+
+  /** The form value is the resolved token (or empty). */
+  syncValue(_val) {
+    this.internals.setFormValue(this.value || '');
+    if (this.required && !this.value) {
+      this.internals.setValidity(
+        { valueMissing: true },
+        this.getAttribute('data-msg-required') || 'Payment method required.',
+        this,
+      );
+    } else {
+      this.internals.setValidity({});
+    }
+  }
+
+  // ── Lifecycle ─────────────────────────────────────────────────────
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'group');
+    if (!this.hasAttribute('aria-label') && !this.hasAttribute('aria-labelledby')) {
+      this.setAttribute('aria-label', 'Payment method form');
+    }
+
+    if (!this.#stamped) {
+      this.#stamp();
+      this.#wireListeners();
+      this.#stamped = true;
+    }
+
+    untracked(() => this.render());
+
+    // Autofocus the first sub-field after the registry has had a
+    // chance to upgrade child primitives.
+    if (this.autofocus) {
+      requestAnimationFrame(() => {
+        const nameCtrl = this.#controls.name;
+        nameCtrl?.focus?.();
+      });
+    }
+  }
+
+  disconnected() {
+    super.disconnected();
+    for (const fn of this.#cleanups) {
+      try { fn(); } catch { /* ignore stale */ }
+    }
+    this.#cleanups.length = 0;
+  }
+
+  attributeChangedCallback(name, oldVal, newVal) {
+    super.attributeChangedCallback?.(name, oldVal, newVal);
+    if (!this.#stamped || this.#internalUpdate) return;
+    if (name === 'prefill' && oldVal !== newVal) {
+      // re-render summary
+      this.render();
+    } else if (name === 'disabled' && oldVal !== newVal) {
+      this.#syncDisabled();
+    } else if (name === 'error' && oldVal !== newVal) {
+      this.#syncAlert();
+    } else if (name === 'require-billing-address' && oldVal !== newVal) {
+      this.#syncBillingRows();
+    } else if (name === 'default-country' && oldVal !== newVal) {
+      const sel = this.#controls.country;
+      if (sel && !sel.value) sel.value = newVal || 'US';
+    }
+  }
+
+  // ── Render — narrow; mutates per-region nodes only ────────────────
+
+  render() {
+    if (!this.#stamped) return;
+
+    this.#syncCountries();
+    this.#syncBillingRows();
+    this.#syncDisabled();
+    this.#syncAlert();
+    this.#syncSummary();
+    this.#syncBrandSuffix();
+  }
+
+  // ── Internal — DOM stamping ───────────────────────────────────────
+
+  #stamp() {
+    // Host-level alert region.
+    const alertHost = document.createElement('alert-ui');
+    alertHost.setAttribute('data-alert', '');
+    alertHost.setAttribute('variant', 'danger');
+    alertHost.setAttribute('icon', 'warning-circle');
+    alertHost.hidden = true;
+    this.appendChild(alertHost);
+    this.#alertHost = alertHost;
+
+    // Saved-card summary region.
+    const summary = document.createElement('div');
+    summary.setAttribute('data-summary', '');
+    summary.hidden = true;
+    const cardIcon = document.createElement('icon-ui');
+    cardIcon.setAttribute('name', 'credit-card');
+    cardIcon.setAttribute('aria-hidden', 'true');
+    cardIcon.setAttribute('data-summary-icon', '');
+    summary.appendChild(cardIcon);
+    const summaryText = document.createElement('div');
+    summaryText.setAttribute('data-summary-text', '');
+    summary.appendChild(summaryText);
+    const editBtn = document.createElement('button-ui');
+    editBtn.setAttribute('data-summary-edit', '');
+    editBtn.setAttribute('variant', 'ghost');
+    editBtn.setAttribute('size', 'sm');
+    editBtn.setAttribute('text', 'Edit card');
+    summary.appendChild(editBtn);
+    this.appendChild(summary);
+    this.#summaryHost = summary;
+    this.#editButton = editBtn;
+
+    // Grid host.
+    const grid = document.createElement('div');
+    grid.setAttribute('data-grid', '');
+    this.appendChild(grid);
+    this.#gridHost = grid;
+
+    // Stamp every row up-front. Rows are hidden via `[hidden]` when
+    // `require-billing-address` is unset so toggling that attribute is
+    // a no-DOM-mutation render.
+
+    this.#fields.name = this.#stampRow('name', {
+      label: 'Name on card',
+      required: true,
+      area: 'name',
+      input: {
+        autocomplete: 'cc-name',
+        placeholder: 'Pat Doe',
+      },
+    });
+    this.#controls.name = this.#fields.name.querySelector('input-ui');
+
+    this.#fields.cardNumber = this.#stampRow('cardNumber', {
+      label: 'Card number',
+      required: true,
+      area: 'card',
+      input: {
+        type: 'text',
+        inputmode: 'numeric',
+        autocomplete: 'cc-number',
+        placeholder: '1234 1234 1234 1234',
+        prefix: 'credit-card',
+        maxlength: 23, // 19 digits + 4 spaces (Maestro upper bound)
+      },
+    });
+    this.#controls.cardNumber = this.#fields.cardNumber.querySelector('input-ui');
+    // Suffix slot — brand badge stamped lazily by #syncBrandSuffix.
+    const brandSlot = document.createElement('span');
+    brandSlot.setAttribute('slot', 'trailing');
+    brandSlot.setAttribute('data-brand-badge', '');
+    this.#controls.cardNumber.appendChild(brandSlot);
+
+    this.#fields.expiry = this.#stampRow('expiry', {
+      label: 'Expiry',
+      required: true,
+      area: 'expiry',
+      input: {
+        type: 'text',
+        inputmode: 'numeric',
+        autocomplete: 'cc-exp',
+        placeholder: 'MM/YY',
+        maxlength: 7,
+      },
+    });
+    this.#controls.expiry = this.#fields.expiry.querySelector('input-ui');
+
+    this.#fields.cvc = this.#stampRow('cvc', {
+      label: 'CVC',
+      required: true,
+      area: 'cvc',
+      input: {
+        type: 'text',
+        inputmode: 'numeric',
+        autocomplete: 'cc-csc',
+        placeholder: '123',
+        maxlength: 4,
+      },
+    });
+    this.#controls.cvc = this.#fields.cvc.querySelector('input-ui');
+
+    // Country select — composed via <select-ui>. Options must be
+    // appended BEFORE the select-ui is added to the document, because
+    // <select-ui>.connected() parses declarative <option> children
+    // once on attach and discards them. After that we use the
+    // programmatic .options property to mutate the list.
+    this.#fields.country = this.#stampRow('country', {
+      label: 'Country',
+      required: true,
+      area: 'country',
+      kind: 'select',
+      input: {
+        autocomplete: 'country',
+      },
+      // Seed options from the resolved countries list at stamp time so
+      // select-ui's first parse sees them.
+      seedOptions: this.#resolveCountries(),
+      seedValue: this.defaultCountry || 'US',
+    });
+    this.#controls.country = this.#fields.country.querySelector('select-ui');
+
+    this.#fields.postalCode = this.#stampRow('postalCode', {
+      label: 'Postal code',
+      required: true,
+      area: 'postal',
+      input: {
+        type: 'text',
+        inputmode: 'text',
+        autocomplete: 'postal-code',
+        placeholder: '94105',
+        maxlength: 12,
+      },
+    });
+    this.#controls.postalCode = this.#fields.postalCode.querySelector('input-ui');
+
+    // Billing-address lines — stamped now, hidden until needed.
+    this.#fields.addressLine1 = this.#stampRow('addressLine1', {
+      label: 'Address line 1',
+      required: false,
+      area: 'address1',
+      input: {
+        type: 'text',
+        autocomplete: 'address-line1',
+        placeholder: '123 Main St',
+        maxlength: 100,
+      },
+    });
+    this.#controls.addressLine1 = this.#fields.addressLine1.querySelector('input-ui');
+    this.#fields.addressLine1.hidden = true;
+
+    this.#fields.addressLine2 = this.#stampRow('addressLine2', {
+      label: 'Address line 2 (optional)',
+      required: false,
+      area: 'address2',
+      input: {
+        type: 'text',
+        autocomplete: 'address-line2',
+        placeholder: 'Apt 4B',
+        maxlength: 100,
+      },
+    });
+    this.#controls.addressLine2 = this.#fields.addressLine2.querySelector('input-ui');
+    this.#fields.addressLine2.hidden = true;
+
+    // Legal slot probe — we don't stamp legal content; consumers slot
+    // their own. Stamp a wrapper so :scope > [data-legal] gates the
+    // CSS-controlled styling (color + size).
+    const legalHost = document.createElement('div');
+    legalHost.setAttribute('data-legal', '');
+    this.appendChild(legalHost);
+    this.#legalHost = legalHost;
+
+    // Promote any author-provided slot="legal" children into the
+    // [data-legal] region so the slot mechanism stays decorative.
+    for (const node of [...this.children]) {
+      if (node === legalHost) continue;
+      if (node.getAttribute && node.getAttribute('slot') === 'legal') {
+        legalHost.appendChild(node);
+      }
+    }
+  }
+
+  #stampRow(key, opts) {
+    const field = document.createElement('field-ui');
+    field.setAttribute('label', opts.label);
+    if (opts.required) field.setAttribute('required', '');
+    field.setAttribute('data-field', key);
+    field.style.gridArea = opts.area;
+
+    let ctrl;
+    if (opts.kind === 'select') {
+      ctrl = document.createElement('select-ui');
+      // Seed declarative <option> children BEFORE the element is added
+      // to the DOM so select-ui's connected() parse picks them up.
+      if (Array.isArray(opts.seedOptions)) {
+        for (const o of opts.seedOptions) {
+          const optEl = document.createElement('option');
+          optEl.value = o.value;
+          optEl.textContent = o.label;
+          if (opts.seedValue && o.value === opts.seedValue) optEl.setAttribute('selected', '');
+          ctrl.appendChild(optEl);
+        }
+      }
+    } else {
+      ctrl = document.createElement('input-ui');
+    }
+    ctrl.setAttribute('name', key);
+    ctrl.setAttribute('data-control', key);
+    if (opts.required) ctrl.setAttribute('required', '');
+    for (const [attr, val] of Object.entries(opts.input || {})) {
+      if (val == null || val === '') continue;
+      ctrl.setAttribute(attr, String(val));
+    }
+    field.appendChild(ctrl);
+
+    this.#gridHost.appendChild(field);
+    return field;
+  }
+
+  /** Resolve the active countries list (props || defaults). */
+  #resolveCountries() {
+    const list = Array.isArray(this.countries) && this.countries.length > 0
+      ? this.countries
+      : DEFAULT_COUNTRIES;
+    return list.map((code) => ({ value: code, label: countryName(code) }));
+  }
+
+  // ── Internal — wiring ─────────────────────────────────────────────
+
+  #wireListeners() {
+    // Card-number input → digit-only normalization + brand detect.
+    const onCardInput = (e) => {
+      if (!this.#controls.cardNumber || e.target !== this.#controls.cardNumber) return;
+      const raw = String(this.#controls.cardNumber.value || '');
+      const digits = digitsOnly(raw);
+      const brand = detectBrand(digits);
+      if (brand !== this.#brand) {
+        this.#brand = brand;
+        this.#syncBrandSuffix();
+      }
+      this.#emitChange();
+    };
+    this.addEventListener('input', onCardInput);
+    this.#cleanups.push(() => this.removeEventListener('input', onCardInput));
+
+    // Any field change → re-emit composite change. Guard against the
+    // self-re-fire: `#emitChange` dispatches a bubbling `change` on the
+    // host (so consumer `<form>` listeners fire); the host itself is
+    // also listening, which without this guard would recurse to stack
+    // overflow. Only react to events from DESCENDANT fields, never to
+    // our own re-dispatch. Caught 2026-05-24 by the test agent when
+    // simulated card-input recursed via #emitChange ↔ change listener.
+    const onAnyChange = (e) => {
+      if (e.target === this) return;
+      this.#emitChange();
+    };
+    this.addEventListener('change', onAnyChange);
+    this.#cleanups.push(() => this.removeEventListener('change', onAnyChange));
+
+    // Edit-card → return to full-form mode.
+    const onEditClick = () => {
+      if (this.disabled) return;
+      this.removeAttribute('prefilled');
+      // Don't clear `prefill` attr — consumer may still want it as a
+      // hydrator for the next render. We hide the summary via state.
+      if (this.#summaryHost) this.#summaryHost.hidden = true;
+      if (this.#gridHost)    this.#gridHost.hidden    = false;
+    };
+    this.#editButton.addEventListener('click', onEditClick);
+    this.#editButton.addEventListener('press', onEditClick);
+    this.#cleanups.push(() => {
+      this.#editButton.removeEventListener('click', onEditClick);
+      this.#editButton.removeEventListener('press', onEditClick);
+    });
+
+    // Outer-form submit → tokenize (if inside a <form>).
+    // We listen on the host for 'invalid' so we can short-circuit
+    // the browser's default-prevented submit path.
+    // tokenize() is the canonical commit; consumers wire their own
+    // submit handler that calls tokenize() (see anti_patterns example).
+  }
+
+  #emitChange() {
+    const cardDigits = digitsOnly(this.#controls.cardNumber?.value);
+    const brand = detectBrand(cardDigits);
+    const validity = this.#peekValidity();
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { valid: validity.ok, brand },
+    }));
+  }
+
+  // ── Internal — render-side syncs ──────────────────────────────────
+
+  #syncCountries() {
+    const sel = this.#controls.country;
+    if (!sel) return;
+
+    // <select-ui> parses native <option> children on its own connect.
+    // We seeded them at stamp time so the first render is a no-op here.
+    // On subsequent renders (when `countries` prop changes), bypass the
+    // children path entirely and set `.options` via the programmatic
+    // API — the property setter performs the rebuild + uses `untracked`
+    // to avoid reactivity feedback.
+    const next = this.#resolveCountries();
+    const same = Array.isArray(sel.options)
+      && sel.options.length === next.length
+      && sel.options.every((o, i) => o?.value === next[i].value && o?.label === next[i].label);
+    if (!same) sel.options = next;
+
+    if (!sel.value) {
+      sel.value = this.defaultCountry || next[0]?.value || 'US';
+    }
+  }
+
+  #syncBillingRows() {
+    const show = !!this.requireBillingAddress;
+    if (this.#fields.addressLine1) this.#fields.addressLine1.hidden = !show;
+    if (this.#fields.addressLine2) this.#fields.addressLine2.hidden = !show;
+  }
+
+  #syncDisabled() {
+    const dis = !!this.disabled;
+    for (const ctrl of Object.values(this.#controls)) {
+      if (!ctrl) continue;
+      if (dis) ctrl.setAttribute('disabled', '');
+      else ctrl.removeAttribute('disabled');
+    }
+  }
+
+  #syncAlert() {
+    if (!this.#alertHost) return;
+    const msg = this.error || '';
+    if (msg) {
+      this.#alertHost.setAttribute('text', msg);
+      this.#alertHost.hidden = false;
+      this.setAttribute('aria-invalid', 'true');
+    } else {
+      this.#alertHost.removeAttribute('text');
+      this.#alertHost.hidden = true;
+      this.removeAttribute('aria-invalid');
+    }
+  }
+
+  #syncSummary() {
+    if (!this.#summaryHost) return;
+    const prefill = this.#parsePrefill();
+    if (!prefill || this.hasAttribute('prefilled-dismissed')) {
+      this.#summaryHost.hidden = true;
+      if (this.#gridHost) this.#gridHost.hidden = false;
+      this.removeAttribute('prefilled');
+      return;
+    }
+    const text = this.#summaryHost.querySelector(':scope > [data-summary-text]');
+    if (text) {
+      const brand = (prefill.brand || 'Card').toUpperCase();
+      const last4 = prefill.last4 || '••••';
+      const exp = prefill.expMonth && prefill.expYear
+        ? ` · expires ${String(prefill.expMonth).padStart(2, '0')}/${String(prefill.expYear).slice(-2)}`
+        : '';
+      text.textContent = `${brand} ending in ${last4}${exp}`;
+    }
+    this.#summaryHost.hidden = false;
+    if (this.#gridHost) this.#gridHost.hidden = true;
+    this.setAttribute('prefilled', '');
+  }
+
+  #syncBrandSuffix() {
+    const ctrl = this.#controls.cardNumber;
+    if (!ctrl) return;
+    const slot = ctrl.querySelector(':scope > [data-brand-badge]');
+    if (!slot) return;
+    if (this.#brand === 'unknown' || !this.#brand) {
+      slot.replaceChildren();
+      return;
+    }
+    const existing = slot.querySelector(':scope > [data-brand]');
+    if (existing && existing.getAttribute('data-brand') === this.#brand) return;
+    slot.replaceChildren();
+    const badge = document.createElement('span');
+    badge.setAttribute('data-brand', this.#brand);
+    badge.textContent = this.#brand.toUpperCase();
+    slot.appendChild(badge);
+  }
+
+  // ── Internal — validation ─────────────────────────────────────────
+
+  /** Peek current validity for `change` events — no side-effects on fields. */
+  #peekValidity() {
+    const digits = digitsOnly(this.#controls.cardNumber?.value);
+    if (!digits) return { ok: false };
+    if (!luhn(digits)) return { ok: false };
+    if (validateExpiry(this.#controls.expiry?.value)) return { ok: false };
+    if (validateCvc(this.#controls.cvc?.value, detectBrand(digits))) return { ok: false };
+    if (!(this.#controls.name?.value || '').trim()) return { ok: false };
+    if (!(this.#controls.postalCode?.value || '').trim()) return { ok: false };
+    return { ok: true };
+  }
+
+  /** Validate every field, surface per-field error attrs, return result. */
+  #validateAll() {
+    // Clear previous per-field errors.
+    for (const ctrl of Object.values(this.#controls)) ctrl?.removeAttribute?.('error');
+
+    const name = String(this.#controls.name?.value || '').trim();
+    if (!name) {
+      this.#controls.name?.setAttribute('error', 'Name on card is required.');
+      return { ok: false, message: 'Name on card is required.', code: 'validation-failed', field: 'name' };
+    }
+
+    const rawCard = this.#controls.cardNumber?.value || '';
+    const digits = digitsOnly(rawCard);
+    if (!digits) {
+      this.#controls.cardNumber?.setAttribute('error', 'Card number is required.');
+      return { ok: false, message: 'Card number is required.', code: 'validation-failed', field: 'cardNumber' };
+    }
+    if (!luhn(digits)) {
+      this.#controls.cardNumber?.setAttribute('error', 'Card number is invalid.');
+      return { ok: false, message: 'Card number is invalid.', code: 'card-invalid', field: 'cardNumber' };
+    }
+
+    const expiryErr = validateExpiry(this.#controls.expiry?.value || '');
+    if (expiryErr) {
+      const msg =
+        expiryErr === 'expiry-past' ? 'Card has expired.' :
+        expiryErr === 'expiry-month' ? 'Expiry month must be 01-12.' :
+        expiryErr === 'expiry-far' ? 'Expiry year is too far in the future.' :
+        'Expiry must be MM/YY.';
+      this.#controls.expiry?.setAttribute('error', msg);
+      return { ok: false, message: msg, code: expiryErr === 'expiry-past' ? 'expired' : 'validation-failed', field: 'expiry' };
+    }
+
+    const brand = detectBrand(digits);
+    const cvcErr = validateCvc(this.#controls.cvc?.value || '', brand);
+    if (cvcErr) {
+      const wantLen = brand === 'amex' ? 4 : 3;
+      const msg = `CVC must be ${wantLen} digits.`;
+      this.#controls.cvc?.setAttribute('error', msg);
+      return { ok: false, message: msg, code: 'cvc-invalid', field: 'cvc' };
+    }
+
+    const country = String(this.#controls.country?.value || this.defaultCountry || 'US');
+    const postal = String(this.#controls.postalCode?.value || '').trim();
+    if (!postal) {
+      this.#controls.postalCode?.setAttribute('error', 'Postal code is required.');
+      return { ok: false, message: 'Postal code is required.', code: 'validation-failed', field: 'postalCode' };
+    }
+
+    if (this.requireBillingAddress) {
+      const line1 = String(this.#controls.addressLine1?.value || '').trim();
+      if (!line1) {
+        this.#controls.addressLine1?.setAttribute('error', 'Address is required.');
+        return { ok: false, message: 'Address is required.', code: 'validation-failed', field: 'addressLine1' };
+      }
+    }
+
+    const parsed = parseExpiry(this.#controls.expiry.value);
+    const last4 = digits.slice(-4);
+    const detail = {
+      last4,
+      brand,
+      expMonth: parsed.month,
+      expYear: parsed.year,
+      name,
+      country,
+    };
+    return { ok: true, detail };
+  }
+
+  // ── Internal — helpers ────────────────────────────────────────────
+
+  /** Parse the `prefill` JSON-encoded string, return null on failure. */
+  #parsePrefill() {
+    const raw = this.prefill || this.getAttribute('prefill') || '';
+    if (!raw) return null;
+    try {
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== 'object') return null;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+}