@adia-ai/web-modules 0.8.35 → 0.8.37

package/billing/billing-overview/billing-overview.class.js

@@ -0,0 +1,838 @@
+/**
+ * <billing-overview-ui> — Module-tier billing dashboard composite.
+ *
+ * Stitches the Wave A+B billing primitives into a single dashboard
+ * surface — header (current plan + status badge) → KPI strip
+ * (current spend · seats · next invoice) → optional dunning banner
+ * (when past-due) → plan-picker section → payment-method-list section
+ * → invoice-history section. The composite owns the page-level
+ * layout, status-badge variant mapping, KPI formatting, and the
+ * unified `account-action` event surface. Each child primitive owns
+ * its own row chrome.
+ *
+ * SPEC: .claude/docs/specs/implementation-ready/SPEC-004-billing-overview.md
+ * Wave A+B siblings composed:
+ *   - SPEC-006 — alert-ui[pattern=dunning] for past-due state
+ *   - SPEC-008 — invoice-history-ui for the invoice list section
+ *   - SPEC-010 — payment-method-list-ui for the cards/wallets section
+ *   - SPEC-011 — plan-picker-ui for the in-app plan chooser
+ *   - stat-ui for the KPI strip
+ *
+ * Architecture (light-DOM, ADR-0033):
+ *   Stamps a six-region skeleton once on first connect:
+ *     [data-header]          — plan title + status tag + slotted actions
+ *     [data-kpis]            — 3-stat KPI strip
+ *     [data-dunning]         — alert-ui[pattern="dunning"], conditional
+ *     [data-plan-picker]     — plan-picker-ui section, conditional
+ *     [data-payment-methods] — payment-method-list-ui section
+ *     [data-invoice-history] — invoice-history-ui section
+ *     [data-empty]           — default empty-state branch
+ *   Then mutates per-region nodes via property assignment on every
+ *   `account` / `variant` / `currency` / `loading` change. Children
+ *   are real custom-element instances; the composite forwards data
+ *   into their `.plans` / `.methods` / `.invoices` properties.
+ *
+ * Form participation: none. Extends UIElement, not UIFormElement —
+ * the dashboard is a display surface. Child primitives (plan-picker,
+ * payment-method-list) are individually form-bearing.
+ *
+ * Per ADR-0027 composed primitives are NOT auto-imported. The
+ * consumer (or this composite's .html demo shell) must side-effect
+ * import each one explicitly.
+ */
+
+import { UIElement } from '@adia-ai/web-components/core/element';
+import { untracked } from '@adia-ai/web-components/core/signals';
+
+const KNOWN_STATUSES = new Set([
+  'active', 'trialing', 'past_due', 'canceled', 'paused',
+]);
+
+/** Map account.status → tag-ui variant (status badge in the header).
+ * `canceled` carries `tone="muted"` (family-less quiet chrome) instead —
+ * `variant="muted"` was never a valid tag-ui value (tag's `variant` enum is
+ * the semantic-family axis; `muted` only ever existed on `tone`, the fill-
+ * style axis) — a pre-existing bug, fixed while migrating the adjacent
+ * accent/muted vocabulary (variant/color/tone convention cut, gh#873/874). */
+const STATUS_TO_VARIANT = {
+  active:    'success',
+  trialing:  'info',
+  past_due:  'danger',
+  paused:    'warning',
+};
+
+const STATUS_LABEL = {
+  active:    'Active',
+  trialing:  'Trialing',
+  past_due:  'Past due',
+  canceled:  'Canceled',
+  paused:    'Paused',
+};
+
+/** Per-child event → unified `account-action.detail.action` mapping. */
+const DUNNING_INTENT = {
+  update: 'update-card',
+  retry:  'retry',
+};
+
+/** Format an amount via Intl.NumberFormat. */
+function formatAmount(amount, currency, locale) {
+  const value = Number.isFinite(amount) ? amount : 0;
+  try {
+    return new Intl.NumberFormat(locale || undefined, {
+      style: 'currency',
+      currency: currency || 'USD',
+      maximumFractionDigits: Number.isInteger(value) ? 0 : 2,
+    }).format(value);
+  } catch {
+    return `${currency || '$'}${value}`;
+  }
+}
+
+/** Format an ISO date via Intl.DateTimeFormat (medium style). */
+function formatDate(iso, locale) {
+  if (!iso) return '';
+  try {
+    const d = iso instanceof Date ? iso : new Date(iso);
+    if (Number.isNaN(d.getTime())) return String(iso);
+    return new Intl.DateTimeFormat(locale || undefined, {
+      year: 'numeric',
+      month: 'short',
+      day: '2-digit',
+    }).format(d);
+  } catch {
+    return String(iso);
+  }
+}
+
+export class UIBillingOverview extends UIElement {
+  static get properties() {
+    return {
+      account:  { type: Object,  default: null  },
+      variant:  { type: String,  default: 'full', reflect: true },
+      currency: { type: String,  default: 'USD',  reflect: true },
+      locale:   { type: String,  default: ''     },
+      loading:  { type: Boolean, default: false,  reflect: true },
+    };
+  }
+
+  // No template — composite stamps a fixed region skeleton once
+  // and mutates per-region nodes across renders. Returning html``
+  // would trigger stamp() → replaceChildren() and wipe authored
+  // slotted children + lose internal state inside the child
+  // composites (plan-picker, payment-method-list, invoice-history).
+  static template = () => null;
+
+  // ── Field refs ────────────────────────────────────────────────────
+  #stamped = false;
+  #cleanups = [];
+
+  // Header region
+  #headerHost = null;
+  #headerTitle = null;
+  #headerSubtitle = null;
+  #headerStatus = null;
+  #headerActions = null;
+
+  // KPI strip
+  #kpisHost = null;
+  #kpiSpend = null;
+  #kpiSeats = null;
+  #kpiInvoice = null;
+
+  // Dunning banner
+  #dunningHost = null;
+  #dunningAlert = null;
+
+  // Plan-picker section
+  #planPickerHost = null;
+  #planPickerHeading = null;
+  #planPicker = null;
+
+  // Payment-methods section
+  #paymentMethodsHost = null;
+  #paymentMethodsHeading = null;
+  #paymentMethods = null;
+
+  // Invoice-history section
+  #invoiceHistoryHost = null;
+  #invoiceHistoryHeading = null;
+  #invoiceHistory = null;
+
+  // Empty state
+  #emptyHost = null;
+
+  // Bookkeeping
+  #headingId = '';
+  #warnedStatus = false;
+  #loadCount = 0;
+
+  // ── Public imperative API ─────────────────────────────────────────
+
+  /** Re-fetch from `data-stream-src` when configured. */
+  async refresh() {
+    const src = this.getAttribute('data-stream-src');
+    if (!src) return;
+    const tag = ++this.#loadCount;
+    this.loading = true;
+    this.removeAttribute('error');
+    try {
+      const res = await fetch(src);
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const data = await res.json();
+      if (tag !== this.#loadCount) return;
+      this.loading = false;
+      const record = data && typeof data === 'object' && data.account
+        ? data.account
+        : data;
+      this.account = record;
+      this.dispatchEvent(new CustomEvent('load', {
+        bubbles: true,
+        detail: { account: record },
+      }));
+    } catch (err) {
+      if (tag !== this.#loadCount) return;
+      this.loading = false;
+      this.setAttribute('error', '');
+      this.dispatchEvent(new CustomEvent('error', {
+        bubbles: true,
+        detail: { reason: 'fetch-failed', message: String(err?.message || err) },
+      }));
+    }
+  }
+
+  // ── Lifecycle ─────────────────────────────────────────────────────
+
+  connected() {
+    this.setAttribute('role', 'region');
+
+    if (!this.#stamped) {
+      this.#absorbInlineAccountScript();
+      this.#stamp();
+      this.#wireListeners();
+      this.#stamped = true;
+    }
+
+    untracked(() => this.render());
+
+    if (this.getAttribute('data-stream-src')) {
+      this.refresh();
+    }
+  }
+
+  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) return;
+    if (name === 'data-stream-src' && oldVal !== newVal && newVal) {
+      this.refresh();
+    }
+  }
+
+  // ── Render — mutates per-region nodes only ────────────────────────
+
+  render() {
+    if (!this.#stamped) return;
+
+    const account = this.account;
+    const isEmpty = !account && !this.getAttribute('data-stream-src');
+
+    if (isEmpty) this.setAttribute('empty', '');
+    else this.removeAttribute('empty');
+
+    if (this.loading) this.setAttribute('aria-busy', 'true');
+    else this.removeAttribute('aria-busy');
+
+    // State attribute reflection (past-due / trial).
+    const status = account?.status || '';
+    if (status === 'past_due') this.setAttribute('past-due', '');
+    else this.removeAttribute('past-due');
+    if (status === 'trialing') this.setAttribute('trial', '');
+    else this.removeAttribute('trial');
+
+    if (status && !KNOWN_STATUSES.has(status) && !this.#warnedStatus) {
+      this.#warnedStatus = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[billing-overview-ui] unknown account.status "${status}" — rendering default chrome.`,
+      );
+    }
+
+    if (isEmpty) {
+      this.#renderHeader(null);
+      this.#renderAccessibleLabel(null);
+      return;
+    }
+
+    if (!account) {
+      // loading + no account yet — render header chrome only.
+      this.#renderHeader(null);
+      return;
+    }
+
+    this.#renderHeader(account);
+    this.#renderKpis(account);
+    this.#renderDunning(account);
+    this.#renderPlanPicker(account);
+    this.#renderPaymentMethods(account);
+    this.#renderInvoiceHistory(account);
+    this.#renderAccessibleLabel(account);
+  }
+
+  // ── Stamp — six-region skeleton ───────────────────────────────────
+
+  #absorbInlineAccountScript() {
+    const script = this.querySelector(
+      ':scope > script[type="application/json"][data-account]',
+    );
+    if (!script) return;
+    try {
+      const parsed = JSON.parse(script.textContent || '{}');
+      if (parsed && typeof parsed === 'object') {
+        const record = parsed.account && typeof parsed.account === 'object'
+          ? parsed.account
+          : parsed;
+        this.account = record;
+      }
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[billing-overview-ui] failed to parse <script data-account> JSON:',
+        err?.message,
+      );
+    } finally {
+      script.remove();
+    }
+  }
+
+  /**
+   * Move consumer-authored `[slot=...]` direct children into their
+   * target regions. Light-DOM substrate (ADR-0033) — `slot=` is
+   * decorative metadata; <slot> elements do NOT reparent children
+   * the way they do in shadow DOM.
+   */
+  #absorbSlottedChildren(slotName, target) {
+    const nodes = this.querySelectorAll(`:scope > [slot="${slotName}"]`);
+    for (const n of nodes) target.appendChild(n);
+  }
+
+  #stamp() {
+    this.#headingId = `bo-h-${Math.random().toString(36).slice(2, 8)}`;
+
+    // ── Header region ── card-ui wrapping plan title + status tag + actions.
+    // Card chrome matches canonical billing.contents.html plan card pattern
+    // (apps/saas/app/billing/billing.contents.html lines 13-29). See
+    // .brain/findings/demos/billing-overview.wireframe.md §Level 5 tree.
+    const headerCard = document.createElement('card-ui');
+    headerCard.setAttribute('data-header', '');
+
+    const header = document.createElement('header');
+
+    // Icon slot — avatar-ui per canonical convention (star/credit-card iconography).
+    const headerIconSpan = document.createElement('span');
+    headerIconSpan.setAttribute('slot', 'icon');
+    const headerAvatar = document.createElement('avatar-ui');
+    headerAvatar.setAttribute('icon', 'credit-card');
+    headerIconSpan.appendChild(headerAvatar);
+
+    // Heading slot — plan name + status badge.
+    const headerHeadingSpan = document.createElement('span');
+    headerHeadingSpan.setAttribute('slot', 'heading');
+
+    const title = document.createElement('h2');
+    title.id = this.#headingId;
+    title.setAttribute('data-billing-plan-name', '');
+    headerHeadingSpan.appendChild(title);
+
+    const statusBadge = document.createElement('tag-ui');
+    statusBadge.setAttribute('data-billing-status', '');
+    statusBadge.setAttribute('size', 'md');
+    headerHeadingSpan.appendChild(statusBadge);
+
+    // Description slot — plan price/cycle/next-invoice meta.
+    const headerDescriptionSpan = document.createElement('span');
+    headerDescriptionSpan.setAttribute('slot', 'description');
+    const subtitle = document.createElement('div');
+    subtitle.setAttribute('data-billing-plan-meta', '');
+    headerDescriptionSpan.appendChild(subtitle);
+
+    // Action slot — change-plan + consumer-supplied actions.
+    const headerActionSpan = document.createElement('span');
+    headerActionSpan.setAttribute('slot', 'action');
+    const headerActions = document.createElement('div');
+    headerActions.setAttribute('data-header-actions', '');
+    headerActionSpan.appendChild(headerActions);
+
+    header.append(headerIconSpan, headerHeadingSpan, headerDescriptionSpan, headerActionSpan);
+    headerCard.appendChild(header);
+    this.appendChild(headerCard);
+
+    this.#headerHost = headerCard;
+    this.#headerTitle = title;
+    this.#headerSubtitle = subtitle;
+    this.#headerStatus = statusBadge;
+    this.#headerActions = headerActions;
+
+    // Absorb consumer [slot="header-actions"] children.
+    this.#absorbSlottedChildren('header-actions', headerActions);
+
+    // ── KPI strip ── card-ui × 3 wrapping stat-ui (currentSpend · seats · nextInvoice).
+    // Card chrome matches canonical KPI strip pattern from
+    // apps/saas/app/admin-dashboard/admin-dashboard.contents.html (card-ui +
+    // section + stat-ui). See wireframe Level 5 tree.
+    const kpis = document.createElement('section');
+    kpis.setAttribute('data-kpis', '');
+
+    /**
+     * Helper: wrap a stat-ui in <card-ui><section> per canonical KPI pattern.
+     * @returns {[HTMLElement, HTMLElement]} [cardWrapper, statElement]
+     */
+    const makeKpiCard = (kpiId, label, icon) => {
+      const card = document.createElement('card-ui');
+      card.setAttribute('data-kpi-card', kpiId);
+      const section = document.createElement('section');
+      const stat = document.createElement('stat-ui');
+      stat.setAttribute('data-kpi', kpiId);
+      stat.setAttribute('label', label);
+      stat.setAttribute('value', '—');
+      stat.setAttribute('icon', icon);
+      section.appendChild(stat);
+      card.appendChild(section);
+      return [card, stat];
+    };
+
+    const [kpiSpendCard, kpiSpend] = makeKpiCard('spend', 'Current month', 'credit-card');
+    const [kpiSeatsCard, kpiSeats] = makeKpiCard('seats', 'Seats', 'users-three');
+    const [kpiInvoiceCard, kpiInvoice] = makeKpiCard('next-invoice', 'Next invoice', 'calendar');
+
+    kpis.append(kpiSpendCard, kpiSeatsCard, kpiInvoiceCard);
+    this.appendChild(kpis);
+    this.#kpisHost = kpis;
+    this.#kpiSpend = kpiSpend;
+    this.#kpiSeats = kpiSeats;
+    this.#kpiInvoice = kpiInvoice;
+
+    // ── Dunning banner ── alert-ui[pattern="dunning"], conditional.
+    const dunningHost = document.createElement('section');
+    dunningHost.setAttribute('data-dunning', '');
+    dunningHost.setAttribute('hidden', '');
+    const dunningAlert = document.createElement('alert-ui');
+    dunningAlert.setAttribute('pattern', 'dunning');
+    dunningAlert.setAttribute('variant', 'danger');
+    dunningHost.appendChild(dunningAlert);
+    this.appendChild(dunningHost);
+    this.#dunningHost = dunningHost;
+    this.#dunningAlert = dunningAlert;
+
+    // ── Plan-picker section ── conditional on [variant=full].
+    const planPickerHost = document.createElement('section');
+    planPickerHost.setAttribute('data-plan-picker', '');
+    const planPickerHeading = document.createElement('h3');
+    planPickerHeading.setAttribute('data-section-heading', '');
+    planPickerHeading.textContent = 'Plan';
+    const planPicker = document.createElement('plan-picker-ui');
+    planPicker.setAttribute('data-billing-plan-picker', '');
+    planPicker.setAttribute('name', 'billing-overview-plan');
+    planPickerHost.append(planPickerHeading, planPicker);
+
+    // Optional before-plan-picker slot anchor sits before the plan picker
+    // section card. We absorb consumer-authored content into planPickerHost
+    // ahead of the heading.
+    this.appendChild(planPickerHost);
+    this.#planPickerHost = planPickerHost;
+    this.#planPickerHeading = planPickerHeading;
+    this.#planPicker = planPicker;
+
+    // Absorb before-plan-picker slot content into the section
+    // ahead of the plan picker.
+    const beforePlanPicker = document.createElement('div');
+    beforePlanPicker.setAttribute('data-before-plan-picker', '');
+    planPickerHost.insertBefore(beforePlanPicker, planPickerHeading);
+    this.#absorbSlottedChildren('before-plan-picker', beforePlanPicker);
+
+    // ── Payment-methods section ──
+    const paymentMethodsHost = document.createElement('section');
+    paymentMethodsHost.setAttribute('data-payment-methods', '');
+    const paymentMethodsHeading = document.createElement('h3');
+    paymentMethodsHeading.setAttribute('data-section-heading', '');
+    paymentMethodsHeading.textContent = 'Payment methods';
+    const paymentMethods = document.createElement('payment-method-list-ui');
+    paymentMethods.setAttribute('data-billing-payment-methods', '');
+    paymentMethods.setAttribute('name', 'billing-overview-payment-method');
+    paymentMethodsHost.append(paymentMethodsHeading, paymentMethods);
+    this.appendChild(paymentMethodsHost);
+    this.#paymentMethodsHost = paymentMethodsHost;
+    this.#paymentMethodsHeading = paymentMethodsHeading;
+    this.#paymentMethods = paymentMethods;
+
+    // ── Invoice-history section ──
+    const invoiceHistoryHost = document.createElement('section');
+    invoiceHistoryHost.setAttribute('data-invoice-history', '');
+    const invoiceHistoryHeading = document.createElement('h3');
+    invoiceHistoryHeading.setAttribute('data-section-heading', '');
+    invoiceHistoryHeading.textContent = 'Invoice history';
+    const invoiceHistory = document.createElement('invoice-history-ui');
+    invoiceHistory.setAttribute('data-billing-invoice-history', '');
+    invoiceHistoryHost.append(invoiceHistoryHeading, invoiceHistory);
+    this.appendChild(invoiceHistoryHost);
+    this.#invoiceHistoryHost = invoiceHistoryHost;
+    this.#invoiceHistoryHeading = invoiceHistoryHeading;
+    this.#invoiceHistory = invoiceHistory;
+
+    // After-invoice-history slot anchor.
+    const afterInvoiceHistory = document.createElement('div');
+    afterInvoiceHistory.setAttribute('data-after-invoice-history', '');
+    invoiceHistoryHost.appendChild(afterInvoiceHistory);
+    this.#absorbSlottedChildren('after-invoice-history', afterInvoiceHistory);
+
+    // ── Empty state ──
+    const empty = document.createElement('div');
+    empty.setAttribute('data-empty', '');
+    const emptyHeading = document.createElement('p');
+    emptyHeading.setAttribute('data-empty-heading', '');
+    emptyHeading.textContent = 'No billing account loaded';
+    const emptyDescription = document.createElement('p');
+    emptyDescription.setAttribute('data-empty-description', '');
+    emptyDescription.textContent = 'Pass an `account` snapshot or `data-stream-src` to render the dashboard.';
+    empty.append(emptyHeading, emptyDescription);
+    this.appendChild(empty);
+    this.#emptyHost = empty;
+
+    // Absorb consumer-authored [slot="empty"] override.
+    this.#absorbSlottedChildren('empty', this);
+  }
+
+  // ── Region renderers ──────────────────────────────────────────────
+
+  #renderHeader(account) {
+    if (!this.#headerTitle || !this.#headerStatus || !this.#headerSubtitle) {
+      return;
+    }
+
+    const plan = account?.plan || null;
+    const name = plan?.name ? String(plan.name) : 'Billing overview';
+    if (this.#headerTitle.textContent !== name) {
+      this.#headerTitle.textContent = name;
+    }
+
+    // Subtitle — formatted price · cycle.
+    const subtitle = this.#headerSubtitle;
+    subtitle.replaceChildren();
+    if (plan && Number.isFinite(plan.price)) {
+      const currency = plan.currency || this.currency || 'USD';
+      const locale = this.#resolveLocale();
+      const cycle = plan.cycle === 'year' ? '/yr' : '/mo';
+      const priceEl = document.createElement('span');
+      priceEl.setAttribute('data-plan-price', '');
+      priceEl.textContent = `${formatAmount(plan.price, currency, locale)} ${cycle}`;
+      subtitle.appendChild(priceEl);
+    }
+    if (account?.billingCycle && account.billingCycle !== plan?.cycle) {
+      const cycleEl = document.createElement('span');
+      cycleEl.setAttribute('data-plan-billing-cycle', '');
+      cycleEl.textContent = `Billed ${account.billingCycle}ly`;
+      subtitle.appendChild(cycleEl);
+    }
+
+    // Status badge — variant + label from STATUS_TO_VARIANT.
+    const status = account?.status || '';
+    if (!status) {
+      this.#headerStatus.setAttribute('hidden', '');
+    } else {
+      this.#headerStatus.removeAttribute('hidden');
+      const variant = STATUS_TO_VARIANT[status];
+      const label = STATUS_LABEL[status] || status;
+      if (variant) {
+        if (this.#headerStatus.getAttribute('variant') !== variant) {
+          this.#headerStatus.setAttribute('variant', variant);
+        }
+        this.#headerStatus.removeAttribute('tone');
+      } else {
+        this.#headerStatus.removeAttribute('variant');
+        if (this.#headerStatus.getAttribute('tone') !== 'muted') {
+          this.#headerStatus.setAttribute('tone', 'muted');
+        }
+      }
+      if (this.#headerStatus.getAttribute('text') !== label) {
+        this.#headerStatus.setAttribute('text', label);
+      }
+      this.#headerStatus.setAttribute('aria-label', `Account status: ${label}`);
+    }
+  }
+
+  #renderKpis(account) {
+    if (!this.#kpiSpend || !this.#kpiSeats || !this.#kpiInvoice) return;
+
+    const currency = account?.plan?.currency || this.currency || 'USD';
+    const locale = this.#resolveLocale();
+
+    // KPI 1 — current month spend.
+    if (Number.isFinite(account?.currentSpend)) {
+      this.#kpiSpend.setAttribute(
+        'value',
+        formatAmount(account.currentSpend, currency, locale),
+      );
+    } else {
+      this.#kpiSpend.setAttribute('value', '—');
+    }
+
+    // KPI 2 — seats (used / total).
+    if (account?.seats && Number.isFinite(account.seats.used)) {
+      const used = account.seats.used;
+      const total = Number.isFinite(account.seats.total) ? account.seats.total : null;
+      this.#kpiSeats.setAttribute(
+        'value',
+        total != null ? `${used} / ${total}` : String(used),
+      );
+    } else {
+      this.#kpiSeats.setAttribute('value', '—');
+    }
+
+    // KPI 3 — next invoice date.
+    if (account?.nextInvoiceDate) {
+      this.#kpiInvoice.setAttribute(
+        'value',
+        formatDate(account.nextInvoiceDate, locale),
+      );
+    } else {
+      this.#kpiInvoice.setAttribute('value', '—');
+    }
+
+    // Forward [loading] to each stat.
+    for (const stat of [this.#kpiSpend, this.#kpiSeats, this.#kpiInvoice]) {
+      if (this.loading) stat.setAttribute('loading', '');
+      else stat.removeAttribute('loading');
+    }
+  }
+
+  #renderDunning(account) {
+    if (!this.#dunningHost || !this.#dunningAlert) return;
+
+    const dunning = account?.dunning || null;
+    const isPastDue = account?.status === 'past_due';
+
+    if (!isPastDue || !dunning) {
+      this.#dunningHost.setAttribute('hidden', '');
+      return;
+    }
+
+    this.#dunningHost.removeAttribute('hidden');
+
+    const amount = Number.isFinite(dunning.amount) ? dunning.amount : null;
+    const currency = dunning.currency || account?.plan?.currency || this.currency || 'USD';
+
+    if (amount != null) {
+      this.#dunningAlert.setAttribute('amount', String(amount));
+    } else {
+      this.#dunningAlert.removeAttribute('amount');
+    }
+    this.#dunningAlert.setAttribute('currency', currency);
+    if (dunning.dueAt) {
+      this.#dunningAlert.setAttribute('due-at', String(dunning.dueAt));
+    }
+    if (dunning.cardLast4) {
+      this.#dunningAlert.setAttribute('card-last4', String(dunning.cardLast4));
+    }
+    if (dunning.reason) {
+      this.#dunningAlert.setAttribute('reason', String(dunning.reason));
+    }
+
+    // Stamp dunning action buttons inside the alert's actions slot when
+    // none exist (consumer-overridable: any [slot=actions] descendant
+    // in the alert is preserved).
+    if (!this.#dunningAlert.querySelector(':scope > [slot="actions"]')) {
+      const updateBtn = document.createElement('button-ui');
+      updateBtn.setAttribute('slot', 'actions');
+      updateBtn.setAttribute('data-dunning-action', 'update');
+      updateBtn.setAttribute('variant', 'primary');
+      updateBtn.setAttribute('text', 'Update payment method');
+      this.#dunningAlert.appendChild(updateBtn);
+
+      const retryBtn = document.createElement('button-ui');
+      retryBtn.setAttribute('slot', 'actions');
+      retryBtn.setAttribute('data-dunning-action', 'retry');
+      retryBtn.setAttribute('variant', 'outline');
+      retryBtn.setAttribute('text', 'Retry charge');
+      this.#dunningAlert.appendChild(retryBtn);
+    }
+  }
+
+  #renderPlanPicker(account) {
+    if (!this.#planPickerHost || !this.#planPicker) return;
+
+    // Hide the section when variant != full OR when no plans were supplied.
+    const wants = this.variant === 'full';
+    const hasPlans = Array.isArray(account?.plans) && account.plans.length > 0;
+    const visible = wants && hasPlans;
+
+    if (!visible) {
+      this.#planPickerHost.setAttribute('hidden', '');
+      return;
+    }
+    this.#planPickerHost.removeAttribute('hidden');
+
+    // Forward plans + current plan id.
+    this.#planPicker.plans = account.plans;
+    if (account?.plan?.id) {
+      this.#planPicker.setAttribute('current', String(account.plan.id));
+    }
+
+    if (this.loading) this.#planPicker.setAttribute('loading', '');
+    else this.#planPicker.removeAttribute('loading');
+  }
+
+  #renderPaymentMethods(account) {
+    if (!this.#paymentMethods) return;
+
+    const methods = Array.isArray(account?.paymentMethods)
+      ? account.paymentMethods
+      : [];
+    this.#paymentMethods.methods = methods;
+
+    if (this.loading) this.#paymentMethods.setAttribute('loading', '');
+    else this.#paymentMethods.removeAttribute('loading');
+  }
+
+  #renderInvoiceHistory(account) {
+    if (!this.#invoiceHistory) return;
+
+    const invoices = Array.isArray(account?.invoices)
+      ? account.invoices
+      : [];
+    this.#invoiceHistory.invoices = invoices;
+    const currency = account?.plan?.currency || this.currency || 'USD';
+    this.#invoiceHistory.setAttribute('currency', currency);
+
+    if (this.loading) this.#invoiceHistory.setAttribute('loading', '');
+    else this.#invoiceHistory.removeAttribute('loading');
+  }
+
+  #renderAccessibleLabel(account) {
+    if (this.#headingId) {
+      this.setAttribute('aria-labelledby', this.#headingId);
+    }
+    if (!account && !this.hasAttribute('aria-label')) {
+      this.setAttribute('aria-label', 'No billing account loaded');
+    } else if (account) {
+      this.removeAttribute('aria-label');
+    }
+  }
+
+  #resolveLocale() {
+    if (this.locale) return this.locale;
+    if (typeof document !== 'undefined') {
+      return document.documentElement.lang || '';
+    }
+    return '';
+  }
+
+  // ── Event delegation — unified `account-action` ──────────────────
+
+  #wireListeners() {
+    // Generic [data-account-action] click → emit account-action.
+    const onActionClick = (e) => {
+      const target = e.target?.closest?.('[data-account-action]');
+      if (!target || !this.contains(target)) return;
+      const action = target.getAttribute('data-account-action') || '';
+      if (!action) return;
+      e.stopPropagation();
+      this.#emitAccountAction(action, 'header', { target });
+    };
+    this.addEventListener('press', onActionClick);
+    this.addEventListener('click', onActionClick);
+    this.#cleanups.push(() => this.removeEventListener('press', onActionClick));
+    this.#cleanups.push(() => this.removeEventListener('click', onActionClick));
+
+    // Dunning alert action → emit account-action.
+    const onDunning = (e) => {
+      const intent = e.detail?.action || '';
+      const action = DUNNING_INTENT[intent] || intent || 'dunning';
+      this.#emitAccountAction(action, 'alert-dunning', e.detail);
+    };
+    this.addEventListener('dunning-action', onDunning);
+    this.#cleanups.push(
+      () => this.removeEventListener('dunning-action', onDunning),
+    );
+
+    // Plan-picker child events → emit account-action.
+    const onPlanChange = (e) => {
+      const planId = e.detail?.value ?? e.detail?.plan?.id ?? '';
+      this.#emitAccountAction('select-plan', 'plan-picker', { planId, ...e.detail });
+    };
+    this.addEventListener('plan-change', onPlanChange);
+    this.#cleanups.push(
+      () => this.removeEventListener('plan-change', onPlanChange),
+    );
+    // plan-picker-ui fires `change` for value changes too — bridge it
+    // when the event originates from the embedded picker.
+    const onPlanPickerChange = (e) => {
+      if (!this.#planPicker || !this.#planPicker.contains(e.target)
+          && e.target !== this.#planPicker) {
+        return;
+      }
+      this.#emitAccountAction('select-plan', 'plan-picker', e.detail);
+    };
+    this.addEventListener('change', onPlanPickerChange);
+    this.#cleanups.push(
+      () => this.removeEventListener('change', onPlanPickerChange),
+    );
+
+    // Payment-method-list child events.
+    const onPaymentAdd = () => {
+      this.#emitAccountAction('add-payment-method', 'payment-method-list', null);
+    };
+    this.addEventListener('add', onPaymentAdd);
+    this.#cleanups.push(() => this.removeEventListener('add', onPaymentAdd));
+
+    const onPaymentRemove = (e) => {
+      this.#emitAccountAction('remove-payment-method', 'payment-method-list', e.detail);
+    };
+    this.addEventListener('remove', onPaymentRemove);
+    this.#cleanups.push(() => this.removeEventListener('remove', onPaymentRemove));
+
+    const onPaymentSelect = (e) => {
+      this.#emitAccountAction('set-default-payment-method', 'payment-method-list', e.detail);
+    };
+    this.addEventListener('select', onPaymentSelect);
+    this.#cleanups.push(() => this.removeEventListener('select', onPaymentSelect));
+
+    // Invoice-history child events.
+    const onInvoiceRowClick = (e) => {
+      this.#emitAccountAction('view-invoice', 'invoice-history', e.detail);
+    };
+    this.addEventListener('invoice-row-click', onInvoiceRowClick);
+    this.#cleanups.push(
+      () => this.removeEventListener('invoice-row-click', onInvoiceRowClick),
+    );
+
+    const onInvoiceExport = (e) => {
+      this.#emitAccountAction('download-invoice', 'invoice-history', e.detail);
+    };
+    this.addEventListener('invoice-export', onInvoiceExport);
+    this.#cleanups.push(
+      () => this.removeEventListener('invoice-export', onInvoiceExport),
+    );
+
+    const onInvoiceAction = (e) => {
+      const action = e.detail?.action || 'invoice';
+      this.#emitAccountAction(action, 'invoice-history', e.detail);
+    };
+    this.addEventListener('invoice-action', onInvoiceAction);
+    this.#cleanups.push(
+      () => this.removeEventListener('invoice-action', onInvoiceAction),
+    );
+  }
+
+  #emitAccountAction(action, source, payload) {
+    this.dispatchEvent(new CustomEvent('account-action', {
+      bubbles: true,
+      detail: { action, source, payload: payload || null },
+    }));
+  }
+}