@adia-ai/web-modules 0.8.35 → 0.8.37

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

@@ -0,0 +1,705 @@
+/**
+ * <payment-method-list-ui> — Form-participating list of saved payment methods.
+ *
+ * Renders the user's saved cards, bank accounts, and wallets as a
+ * vertical list with one row designated as the default. Each row is a
+ * <card-ui size="sm"> with a brand mark, last-4 / identifier, expiry,
+ * a "Default" tag (on the default row), and per-row actions (set-
+ * default / edit / remove). A trailing "Add payment method" CTA emits
+ * `add` so the consumer can route the consumer-driven add flow.
+ *
+ * SPEC: .claude/docs/specs/implementation-ready/SPEC-010-payment-method-list.md
+ * Sibling: <plan-picker-ui> (same id-keyed-diff pattern)
+ *
+ * Architecture (light-DOM, ADR-0033):
+ *   This composite stamps a three-region skeleton once on first
+ *   connect:
+ *     [data-rows] · [data-empty] · [data-add]
+ *   Then mutates per-row DOM by id-keyed in-place diff on every
+ *   `methods` / `value` write. The diff preserves identity across
+ *   re-renders (id-keyed map) so focus survives unrelated row updates.
+ *
+ * Form participation:
+ *   Extends UIFormElement. The current default id serializes under
+ *   `name` via ElementInternals. Default is a strict 1-of-N — exactly
+ *   one row carries the default state when methods is non-empty.
+ *
+ * Mutations are events, not props:
+ *   - `change` — default method changed
+ *   - `add`    — user clicked the add CTA
+ *   - `remove` — user clicked a row's remove button
+ *   - `select` — user clicked a row's edit button (no default change)
+ *
+ * The primitive does NOT write to the data source; the consumer
+ * applies the side effect (network round-trip) and either passes the
+ * new `methods` array back or calls .add() / .remove() / .setDefault().
+ *
+ * Per ADR-0027 — the composed primitives (card-ui / button-ui /
+ * tag-ui / icon-ui / empty-state-ui) are NOT auto-imported. The
+ * consumer (or the demo .html shell) must import them explicitly.
+ */
+
+import { UIFormElement } from '@adia-ai/web-components/core/form';
+import { untracked } from '@adia-ai/web-components/core/signals';
+
+const KNOWN_BRANDS = new Set([
+  'visa', 'mastercard', 'amex', 'discover', 'jcb', 'unionpay', 'diners',
+  'paypal', 'apple-pay', 'google-pay', 'ach', 'sepa',
+]);
+
+const KNOWN_TYPES = new Set(['card', 'bank', 'wallet']);
+
+// Phosphor icons that have brand-adjacent renderings.
+const BRAND_ICON = {
+  paypal: 'paypal-logo',
+  'apple-pay': 'apple-logo',
+  ach: 'bank',
+  sepa: 'bank',
+};
+
+// Fallback icon by record type. Cards (including unknown brands) get
+// the generic credit-card mark; bank gets the bank icon; wallets get
+// the credit-card mark by default unless brand maps elsewhere.
+const TYPE_FALLBACK_ICON = {
+  card: 'credit-card',
+  bank: 'bank',
+  wallet: 'credit-card',
+};
+
+/** Brand label for the row's accessible name. */
+const BRAND_LABEL = {
+  visa: 'Visa',
+  mastercard: 'Mastercard',
+  amex: 'American Express',
+  discover: 'Discover',
+  jcb: 'JCB',
+  unionpay: 'UnionPay',
+  diners: 'Diners Club',
+  paypal: 'PayPal',
+  'apple-pay': 'Apple Pay',
+  'google-pay': 'Google Pay',
+  ach: 'Bank account',
+  sepa: 'SEPA',
+};
+
+function brandIconFor(method) {
+  const brand = (method?.brand || '').toLowerCase();
+  if (BRAND_ICON[brand]) return BRAND_ICON[brand];
+  const type = (method?.type || 'card').toLowerCase();
+  return TYPE_FALLBACK_ICON[type] || 'credit-card';
+}
+
+function brandLabelFor(method) {
+  const brand = (method?.brand || '').toLowerCase();
+  if (BRAND_LABEL[brand]) return BRAND_LABEL[brand];
+  const type = (method?.type || 'card').toLowerCase();
+  if (type === 'bank') return 'Bank account';
+  if (type === 'wallet') return 'Wallet';
+  return 'Card';
+}
+
+/**
+ * Render the user-visible primary line for a row.
+ * Cards: "Visa •• 4242"
+ * Wallets w/o last4: "PayPal"
+ * Banks w/ holder: "Chase ••6789"
+ */
+function primaryLineFor(method) {
+  const last4 = (method?.last4 || '').trim();
+  const holder = (method?.holder || '').trim();
+  const brand = brandLabelFor(method);
+  const type = (method?.type || 'card').toLowerCase();
+
+  if (type === 'bank' && holder) return holder;
+  if (last4) return `${brand} ···· ${last4}`;
+  if (holder) return `${brand} — ${holder}`;
+  return brand;
+}
+
+/** "Expires 05/27" string for the secondary line; empty when no expiry. */
+function expiryLineFor(method) {
+  const raw = (method?.expiry || '').trim();
+  if (!raw) return '';
+  // Accept "MM/YY", "MM/YYYY", or "YYYY-MM-DD".
+  let mm = '';
+  let yy = '';
+  const mmYy = raw.match(/^(\d{1,2})\/(\d{2}|\d{4})$/);
+  if (mmYy) {
+    mm = mmYy[1].padStart(2, '0');
+    yy = mmYy[2].length === 4 ? mmYy[2].slice(-2) : mmYy[2];
+  } else {
+    const iso = raw.match(/^(\d{4})-(\d{2})-\d{2}$/);
+    if (iso) {
+      yy = iso[1].slice(-2);
+      mm = iso[2];
+    }
+  }
+  if (!mm || !yy) return '';
+  return `Expires ${mm}/${yy}`;
+}
+
+export class PaymentMethodList extends UIFormElement {
+  static get properties() {
+    return {
+      ...UIFormElement.properties,
+      // `methods` is the source of truth — array via prop OR JSON child.
+      methods:     { type: Array,   default: [] },
+      // Current default id mirrors UIFormElement.value.
+      value:       { type: String,  default: '', reflect: true },
+      'add-label': { type: String,  default: 'Add payment method', attribute: 'add-label' },
+      'add-icon':  { type: String,  default: 'plus',               attribute: 'add-icon' },
+      'no-add':    { type: Boolean, default: false, reflect: true, attribute: 'no-add' },
+      'no-remove': { type: Boolean, default: false, reflect: true, attribute: 'no-remove' },
+      disabled:    { type: Boolean, default: false, reflect: true },
+    };
+  }
+
+  // No template — we stamp a fixed three-region skeleton once and
+  // mutate per-region children on render. Returning html`` would
+  // trigger stamp() → replaceChildren() and wipe authored slot kids.
+  static template = () => null;
+
+  // ── Field refs ────────────────────────────────────────────────────
+  #stamped = false;
+  #cleanups = [];
+  #rowsHost = null;           // <div data-rows role=presentation>
+  #emptyHost = null;          // <empty-state-ui data-empty>
+  #addHost = null;            // <div data-add>
+  #addButton = null;          // <button-ui> inside #addHost
+  #rowsById = new Map();      // id → <card-ui>
+  #internalUpdate = false;
+
+  // ── Public imperative API (SPEC §4 Methods) ───────────────────────
+
+  /** Mark a method id as default. Returns true on hit. */
+  setDefault(id) {
+    if (!id) return false;
+    return untracked(() => {
+      const found = (this.methods || []).find((m) => m.id === id);
+      if (!found) return false;
+      if (this.value === id) return true;
+      const previous = this.value || '';
+      this.#internalUpdate = true;
+      try { this.value = id; } finally { this.#internalUpdate = false; }
+      this.syncValue();
+      this.#emitChange(id, previous, found);
+      return true;
+    });
+  }
+
+  /** Remove a method by id from internal state and re-render. */
+  remove(id) {
+    if (!id) return false;
+    return untracked(() => {
+      const list = Array.isArray(this.methods) ? this.methods.slice() : [];
+      const idx = list.findIndex((m) => m.id === id);
+      if (idx < 0) return false;
+      list.splice(idx, 1);
+      this.methods = list;
+      // If we removed the current default, promote the new first row
+      // (preserves the 1-of-N invariant when the list is non-empty).
+      if (this.value === id) {
+        const next = list[0]?.id || '';
+        this.#internalUpdate = true;
+        try { this.value = next; } finally { this.#internalUpdate = false; }
+        this.syncValue();
+      }
+      return true;
+    });
+  }
+
+  /** Insert a new method record (typically called after add flow returns). */
+  add(method) {
+    if (!method || !method.id) return;
+    untracked(() => {
+      const list = Array.isArray(this.methods) ? this.methods.slice() : [];
+      // Replace existing record by id if already present.
+      const idx = list.findIndex((m) => m.id === method.id);
+      if (idx >= 0) list[idx] = method;
+      else list.push(method);
+      this.methods = list;
+      if (method.default) {
+        const previous = this.value || '';
+        this.#internalUpdate = true;
+        try { this.value = method.id; } finally { this.#internalUpdate = false; }
+        this.syncValue();
+        if (previous !== method.id) this.#emitChange(method.id, previous, method);
+      }
+    });
+  }
+
+  // ── Lifecycle ─────────────────────────────────────────────────────
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'radiogroup');
+    if (!this.hasAttribute('aria-label') && !this.hasAttribute('aria-labelledby')) {
+      this.setAttribute('aria-label', 'Payment methods');
+    }
+
+    if (!this.#stamped) {
+      // Absorb a <script type="application/json" data-methods> child
+      // before stamping wipes the host's children.
+      this.#absorbInlineMethodsScript();
+      this.#stamp();
+      this.#wireListeners();
+      this.#stamped = true;
+    }
+
+    // Trigger first render after composed primitives upgrade.
+    untracked(() => this.render());
+  }
+
+  disconnected() {
+    super.disconnected?.();
+    for (const fn of this.#cleanups) {
+      try { fn(); } catch { /* ignore stale */ }
+    }
+    this.#cleanups.length = 0;
+  }
+
+  // ── Form participation ────────────────────────────────────────────
+
+  /** Selected default id is the form value. */
+  syncValue(_val) {
+    this.internals.setFormValue(this.value || '');
+  }
+
+  // ── Render — narrow; mutates per-region nodes only ────────────────
+
+  render() {
+    if (!this.#stamped) return;
+
+    const methods = Array.isArray(this.methods) ? this.methods : [];
+
+    // Reconcile default — value wins; otherwise first record with
+    // default:true; otherwise the first row.
+    const defaultId = this.#resolveDefaultId(methods);
+    if (defaultId && this.value !== defaultId) {
+      this.#internalUpdate = true;
+      try { this.value = defaultId; } finally { this.#internalUpdate = false; }
+      this.syncValue();
+    }
+
+    // Empty-state attribute reflection (CSS-gated reveal).
+    if (methods.length === 0) {
+      this.setAttribute('empty', '');
+    } else {
+      this.removeAttribute('empty');
+    }
+
+    // Add-CTA visibility.
+    if (this.#addHost) {
+      this.#addHost.hidden = !!this['no-add'];
+    }
+    if (this.#addButton) {
+      this.#addButton.setAttribute('text', this['add-label'] || 'Add payment method');
+      const icon = this['add-icon'] || 'plus';
+      if (icon) this.#addButton.setAttribute('icon', icon);
+      else this.#addButton.removeAttribute('icon');
+      if (this.disabled) this.#addButton.setAttribute('disabled', '');
+      else this.#addButton.removeAttribute('disabled');
+    }
+
+    this.#renderRows(methods);
+  }
+
+  // ── Internal — DOM stamping ───────────────────────────────────────
+
+  #resolveDefaultId(methods) {
+    if (!methods.length) return '';
+    // 1) explicit `value` wins if it matches a row
+    if (this.value && methods.some((m) => m.id === this.value)) return this.value;
+    // 2) first record carrying default:true
+    const flagged = methods.find((m) => m.default);
+    if (flagged) return flagged.id;
+    // 3) fall back to first row
+    return methods[0].id || '';
+  }
+
+  #absorbInlineMethodsScript() {
+    const script = this.querySelector(':scope > script[type="application/json"][data-methods]');
+    if (!script) return;
+    try {
+      const parsed = JSON.parse(script.textContent || '[]');
+      if (Array.isArray(parsed)) this.methods = parsed;
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn('[payment-method-list-ui] failed to parse <script data-methods> JSON:', err?.message);
+    } finally {
+      script.remove();
+    }
+  }
+
+  #stamp() {
+    // Rows host — the radiogroup container for the method cards.
+    // role="presentation" because the outer host carries radiogroup.
+    const rows = document.createElement('div');
+    rows.setAttribute('data-rows', '');
+    rows.setAttribute('role', 'presentation');
+    this.appendChild(rows);
+    this.#rowsHost = rows;
+
+    // Default empty-state — overridable via slot="empty".
+    if (!this.querySelector(':scope > [slot="empty"]')) {
+      const empty = document.createElement('empty-state-ui');
+      empty.setAttribute('data-empty', '');
+      empty.setAttribute('icon', 'credit-card');
+      empty.setAttribute('heading', 'No payment methods');
+      empty.setAttribute('description', 'Add a method to get started.');
+      this.appendChild(empty);
+      this.#emptyHost = empty;
+    }
+
+    // Add CTA host — overridable via slot="add".
+    const addHost = document.createElement('div');
+    addHost.setAttribute('data-add', '');
+    this.appendChild(addHost);
+    this.#addHost = addHost;
+
+    if (!this.querySelector(':scope > [slot="add"]')) {
+      const btn = document.createElement('button-ui');
+      btn.setAttribute('data-add-cta', '');
+      btn.setAttribute('variant', 'outline');
+      btn.setAttribute('icon', this['add-icon'] || 'plus');
+      btn.setAttribute('text', this['add-label'] || 'Add payment method');
+      addHost.appendChild(btn);
+      this.#addButton = btn;
+    }
+  }
+
+  #renderRows(methods) {
+    if (!this.#rowsHost) return;
+
+    const next = new Map();
+
+    for (const method of methods) {
+      if (!method?.id) continue;
+      let row = this.#rowsById.get(method.id);
+      if (!row) {
+        row = this.#buildRow(method);
+        this.#rowsHost.appendChild(row);
+      }
+      this.#decorateRow(row, method);
+      next.set(method.id, row);
+    }
+
+    // Remove dropped rows.
+    for (const [id, row] of this.#rowsById) {
+      if (!next.has(id)) {
+        try { row.remove(); } catch { /* ignore */ }
+      }
+    }
+
+    // Reorder DOM to match the input array (in-place move).
+    for (const method of methods) {
+      const row = next.get(method.id);
+      if (row) this.#rowsHost.appendChild(row);
+    }
+
+    this.#rowsById = next;
+  }
+
+  #buildRow(method) {
+    // Canonical card-ui composition grammar (card.css §header):
+    // <card-ui data-row data-id=... role="radio">
+    //   <header>
+    //     <span slot="icon"><icon-ui aria-hidden="true"></icon-ui></span>
+    //     <span slot="heading">
+    //       <span data-primary>Visa ···· 4242</span>
+    //       <tag-ui data-default-tag text="Default" variant="success" size="sm" hidden></tag-ui>
+    //     </span>
+    //     <p slot="description" data-secondary>Expires 05/27</p>
+    //     <span slot="action">
+    //       <button-ui data-action="set-default" variant="ghost" size="sm" text="Set default" hidden></button-ui>
+    //       <button-ui data-action="edit"        variant="ghost" size="sm" icon="pencil"></button-ui>
+    //       <button-ui data-action="remove"      variant="ghost" size="sm" icon="trash"></button-ui>
+    //     </span>
+    //   </header>
+    // </card-ui>
+    //
+    // card-ui's @scope rules own the 3-column grid (icon | heading | action),
+    // heading-slot inline-flex (badges), description placement, and action-slot
+    // flex layout. We do NOT re-implement any of that here.
+    const row = document.createElement('card-ui');
+    row.setAttribute('data-row', '');
+    row.setAttribute('role', 'radio');
+    row.setAttribute('tabindex', '0');
+
+    const header = document.createElement('header');
+
+    // Icon slot — first column, max-content; card-ui aligns vertically.
+    const iconSlot = document.createElement('span');
+    iconSlot.setAttribute('slot', 'icon');
+    iconSlot.setAttribute('data-pml-icon', ''); // internal hook — this composite's CSS centers it (gh#1079) without claiming card-ui's slot vocab in its own yaml (FB-62)
+    const icon = document.createElement('icon-ui');
+    icon.setAttribute('aria-hidden', 'true');
+    iconSlot.appendChild(icon);
+
+    // Heading slot — flex container (card.css L229-233); inline tag-ui fits naturally.
+    const headingSlot = document.createElement('span');
+    headingSlot.setAttribute('slot', 'heading');
+    const primary = document.createElement('span');
+    primary.setAttribute('data-primary', '');
+    const defaultTag = document.createElement('tag-ui');
+    defaultTag.setAttribute('data-default-tag', '');
+    defaultTag.setAttribute('text', 'Default');
+    defaultTag.setAttribute('variant', 'success');
+    defaultTag.setAttribute('size', 'sm');
+    defaultTag.setAttribute('hidden', '');
+    headingSlot.appendChild(primary);
+    headingSlot.appendChild(defaultTag);
+
+    // Description slot — row 2, spans heading + action columns (card.css L237-244).
+    const description = document.createElement('p');
+    description.setAttribute('slot', 'description');
+    description.setAttribute('data-secondary', '');
+
+    // Action slot — last column, flex row (card.css L246-257).
+    const actionSlot = document.createElement('span');
+    actionSlot.setAttribute('slot', 'action');
+    actionSlot.setAttribute('data-pml-action', ''); // internal hook, same as data-pml-icon
+
+    const setDefaultBtn = document.createElement('button-ui');
+    setDefaultBtn.setAttribute('data-action', 'set-default');
+    setDefaultBtn.setAttribute('variant', 'ghost');
+    setDefaultBtn.setAttribute('size', 'sm');
+    setDefaultBtn.setAttribute('text', 'Set default');
+
+    const editBtn = document.createElement('button-ui');
+    editBtn.setAttribute('data-action', 'edit');
+    editBtn.setAttribute('variant', 'ghost');
+    editBtn.setAttribute('size', 'sm');
+    editBtn.setAttribute('icon', 'pencil');
+    editBtn.setAttribute('aria-label', 'Edit payment method');
+
+    const removeBtn = document.createElement('button-ui');
+    removeBtn.setAttribute('data-action', 'remove');
+    removeBtn.setAttribute('variant', 'ghost');
+    removeBtn.setAttribute('size', 'sm');
+    removeBtn.setAttribute('icon', 'trash');
+    removeBtn.setAttribute('aria-label', 'Remove payment method');
+
+    actionSlot.appendChild(setDefaultBtn);
+    actionSlot.appendChild(editBtn);
+    actionSlot.appendChild(removeBtn);
+
+    header.appendChild(iconSlot);
+    header.appendChild(headingSlot);
+    header.appendChild(description);
+    header.appendChild(actionSlot);
+    row.appendChild(header);
+
+    return row;
+  }
+
+  #decorateRow(row, method) {
+    row.setAttribute('data-id', method.id);
+
+    const brand = (method?.brand || '').toLowerCase();
+    if (brand) row.setAttribute('data-brand-key', brand);
+    else row.removeAttribute('data-brand-key');
+
+    const type = (method?.type || 'card').toLowerCase();
+    if (KNOWN_TYPES.has(type)) row.setAttribute('data-type', type);
+
+    const isDefault = method.id === this.value;
+    if (isDefault) {
+      row.setAttribute('data-default', '');
+      row.setAttribute('aria-checked', 'true');
+      row.setAttribute('tabindex', '0');
+    } else {
+      row.removeAttribute('data-default');
+      row.setAttribute('aria-checked', 'false');
+      row.setAttribute('tabindex', '-1');
+    }
+
+    if (this.disabled) {
+      row.setAttribute('aria-disabled', 'true');
+    } else {
+      row.removeAttribute('aria-disabled');
+    }
+
+    // Brand-icon update (icon lives in slot=icon inside header).
+    const iconEl = row.querySelector(':scope > header > [slot="icon"] > icon-ui');
+    if (iconEl) {
+      const iconName = brandIconFor(method);
+      if (iconEl.getAttribute('name') !== iconName) {
+        iconEl.setAttribute('name', iconName);
+      }
+    }
+
+    // Primary text (inside slot=heading).
+    const primary = row.querySelector(':scope > header > [slot="heading"] > [data-primary]');
+    if (primary) primary.textContent = primaryLineFor(method);
+
+    // Secondary text (slot=description).
+    const secondary = row.querySelector(':scope > header > [data-secondary][slot="description"]');
+    if (secondary) {
+      const expiry = expiryLineFor(method);
+      secondary.textContent = expiry;
+      if (expiry) secondary.removeAttribute('hidden');
+      else secondary.setAttribute('hidden', '');
+    }
+
+    // Default tag — toggle visibility (inline inside slot=heading).
+    const defaultTag = row.querySelector(':scope > header > [slot="heading"] > [data-default-tag]');
+    if (defaultTag) {
+      if (isDefault) defaultTag.removeAttribute('hidden');
+      else defaultTag.setAttribute('hidden', '');
+    }
+
+    // Accessible row name (composed brand + identifier + state).
+    const expiryText = expiryLineFor(method);
+    const parts = [primaryLineFor(method)];
+    if (expiryText) parts.push(expiryText);
+    if (isDefault) parts.push('default');
+    row.setAttribute('aria-label', parts.join(', '));
+
+    // Per-row action visibility (action slot inside header).
+    const setDefaultBtn = row.querySelector(':scope > header > [slot="action"] > [data-action="set-default"]');
+    if (setDefaultBtn) {
+      // Hide "Set default" on the current default row.
+      if (isDefault) setDefaultBtn.setAttribute('hidden', '');
+      else setDefaultBtn.removeAttribute('hidden');
+      if (this.disabled) setDefaultBtn.setAttribute('disabled', '');
+      else setDefaultBtn.removeAttribute('disabled');
+    }
+
+    const editBtn = row.querySelector(':scope > header > [slot="action"] > [data-action="edit"]');
+    if (editBtn) {
+      if (this.disabled) editBtn.setAttribute('disabled', '');
+      else editBtn.removeAttribute('disabled');
+    }
+
+    const removeBtn = row.querySelector(':scope > header > [slot="action"] > [data-action="remove"]');
+    if (removeBtn) {
+      if (this['no-remove']) removeBtn.setAttribute('hidden', '');
+      else removeBtn.removeAttribute('hidden');
+      if (this.disabled) removeBtn.setAttribute('disabled', '');
+      else removeBtn.removeAttribute('disabled');
+    }
+  }
+
+  #wireListeners() {
+    // Delegate per-row action button presses (button-ui + happy-dom click).
+    const onAction = (e) => {
+      const btn = e.target?.closest?.('button-ui[data-action]');
+      if (btn && this.#rowsHost.contains(btn)) {
+        const row = btn.closest('[data-row]');
+        if (!row) return;
+        const id = row.getAttribute('data-id') || '';
+        if (!id) return;
+        if (this.disabled || btn.hasAttribute('disabled')) {
+          e.stopPropagation();
+          return;
+        }
+        const method = (this.methods || []).find((m) => m.id === id);
+        if (!method) return;
+        const action = btn.getAttribute('data-action');
+        e.stopPropagation();
+
+        if (action === 'set-default') {
+          this.setDefault(id);
+        } else if (action === 'remove') {
+          this.dispatchEvent(new CustomEvent('remove', {
+            bubbles: true,
+            detail: { id, method },
+          }));
+        } else if (action === 'edit') {
+          this.dispatchEvent(new CustomEvent('select', {
+            bubbles: true,
+            detail: { id, method },
+          }));
+        }
+        return;
+      }
+
+      // Add CTA.
+      const addBtn = e.target?.closest?.('button-ui[data-add-cta]');
+      if (addBtn && this.#addHost?.contains(addBtn)) {
+        if (this.disabled || addBtn.hasAttribute('disabled')) {
+          e.stopPropagation();
+          return;
+        }
+        e.stopPropagation();
+        this.dispatchEvent(new CustomEvent('add', {
+          bubbles: true,
+          detail: {},
+        }));
+      }
+    };
+    // Listen for both `press` (button-ui's custom event) and `click`
+    // (covers happy-dom paths in tests).
+    this.addEventListener('press', onAction);
+    this.addEventListener('click', onAction);
+    this.#cleanups.push(() => this.removeEventListener('press', onAction));
+    this.#cleanups.push(() => this.removeEventListener('click', onAction));
+
+    // Row activation — clicking the card body (outside an action
+    // button) sets that row as default.
+    const onRowActivate = (e) => {
+      // Bail if the press came from an action button (handled above).
+      if (e.target?.closest?.('button-ui[data-action]')) return;
+      if (e.target?.closest?.('button-ui[data-add-cta]')) return;
+      const row = e.target?.closest?.('[data-row]');
+      if (!row || !this.#rowsHost.contains(row)) return;
+      const id = row.getAttribute('data-id') || '';
+      if (!id) return;
+      if (this.disabled) return;
+      this.setDefault(id);
+    };
+    this.#rowsHost.addEventListener('click', onRowActivate);
+    this.#cleanups.push(() => this.#rowsHost.removeEventListener('click', onRowActivate));
+
+    // Radiogroup keyboard model — Arrow Down / Up / Home / End move
+    // focus within the group; Space / Enter set default on the focused row.
+    const onKey = (e) => {
+      const focused = document.activeElement;
+      const row = focused?.closest?.('[data-row]');
+      if (!row || !this.#rowsHost.contains(row)) return;
+      const rows = Array.from(this.#rowsHost.querySelectorAll(':scope > [data-row]'));
+      const idx = rows.indexOf(row);
+      if (idx < 0) return;
+
+      if (e.key === 'ArrowDown' || e.key === 'ArrowRight') {
+        e.preventDefault();
+        const target = rows[(idx + 1) % rows.length];
+        target?.focus?.();
+      } else if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') {
+        e.preventDefault();
+        const target = rows[(idx - 1 + rows.length) % rows.length];
+        target?.focus?.();
+      } else if (e.key === 'Home') {
+        e.preventDefault();
+        rows[0]?.focus?.();
+      } else if (e.key === 'End') {
+        e.preventDefault();
+        rows[rows.length - 1]?.focus?.();
+      } else if (e.key === ' ' || e.key === 'Enter') {
+        e.preventDefault();
+        const id = row.getAttribute('data-id') || '';
+        if (id && !this.disabled) this.setDefault(id);
+      }
+    };
+    this.#rowsHost.addEventListener('keydown', onKey);
+    this.#cleanups.push(() => this.#rowsHost.removeEventListener('keydown', onKey));
+  }
+
+  #emitChange(value, previous, method) {
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { value, previous, method },
+    }));
+  }
+}
+
+// Re-export helpers for tests.
+export {
+  KNOWN_BRANDS,
+  KNOWN_TYPES,
+  brandIconFor,
+  brandLabelFor,
+  primaryLineFor,
+  expiryLineFor,
+};