@adia-ai/web-modules 0.8.35 → 0.8.37

package/billing/invoice-history/invoice-history.class.js

@@ -0,0 +1,672 @@
+/**
+ * <invoice-history-ui> — Canonical billing-list composite.
+ *
+ * Pre-configures <table-ui> with invoice-shaped columns + status-badge
+ * cell renderer + currency formatter + row-click navigation, alongside
+ * an optional <table-toolbar-ui> for search/filter and a default
+ * "Export CSV" button. Wraps, does not fork, the underlying primitive.
+ *
+ * SPEC: .claude/docs/specs/implementation-ready/SPEC-008-invoice-history-table.md
+ * WAI-APG: https://www.w3.org/WAI/ARIA/apg/patterns/grid/ (inherited
+ *          from <table-ui>)
+ *
+ * Architecture (light-DOM, ADR-0033):
+ *   This composite stamps a three-region skeleton once on first connect:
+ *     [data-toolbar] (slot toolbar / default toolbar)
+ *     [data-table]   (the <table-ui>)
+ *     [data-empty]   (default <empty-state-ui> branch)
+ *   Then mutates the table's `.data` / `.columns` on every render. The
+ *   table primitive owns row stamping; this composite only wires its
+ *   inputs and converts cell renderers.
+ *
+ * Public API:
+ *   .invoices        — array of records (re-render on assign)
+ *   .currency        — default ISO 4217 code
+ *   .filter          — active status filter ('' = all)
+ *   .setFilter(s)    — set the filter programmatically; returns true on hit
+ *   .exportCsv()     — Blob of currently-visible rows
+ *   .getSelected()   — array of selected invoice records
+ *   .refresh()       — re-fetch from data-stream-src when configured
+ */
+
+import { UIElement } from '@adia-ai/web-components/core/element';
+import { untracked } from '@adia-ai/web-components/core/signals';
+
+const KNOWN_STATUSES = new Set(['draft', 'open', 'paid', 'past-due', 'void']);
+
+const STATUS_TO_VARIANT = {
+  paid:      'success',
+  open:      'info',
+  'past-due':'danger',
+};
+// `void` and `draft` are family-less badges (quiet chrome) — `variant="muted"`/
+// `"neutral"` retired (variant/color/tone convention cut, gh#873/874); the
+// status render() below sets `tone="muted"` for any status absent here.
+
+const STATUS_LABEL = {
+  paid:      'Paid',
+  open:      'Open',
+  'past-due':'Past due',
+  void:      'Void',
+  draft:     'Draft',
+};
+
+const FILTER_CHIPS = [
+  { value: '',         label: 'All' },
+  { value: 'paid',     label: 'Paid' },
+  { value: 'open',     label: 'Open' },
+  { value: 'past-due', label: 'Past due' },
+  { value: 'void',     label: 'Void' },
+  { value: 'draft',    label: 'Draft' },
+];
+
+const CSV_HEADERS = ['Number', 'Issued', 'Due', 'Amount', 'Currency', 'Status'];
+
+/**
+ * Format an amount via Intl.NumberFormat. Falls back to `${currency}${value}`
+ * on engine failure.
+ */
+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 a date string ("YYYY-MM-DD" or ISO) via Intl.DateTimeFormat
+ * with the medium style. Returns the raw string on failure.
+ */
+function formatDate(raw, locale) {
+  if (!raw) return '';
+  try {
+    const d = raw instanceof Date ? raw : new Date(raw);
+    if (Number.isNaN(d.getTime())) return String(raw);
+    return new Intl.DateTimeFormat(locale || undefined, {
+      year:  'numeric',
+      month: 'short',
+      day:   '2-digit',
+    }).format(d);
+  } catch {
+    return String(raw);
+  }
+}
+
+/**
+ * Resolve hrefPattern with invoice data — replaces `{number}` and
+ * `{id}` tokens. Other tokens fall through unchanged.
+ */
+function resolveHref(pattern, invoice) {
+  const tpl = pattern || '/invoices/{number}';
+  return tpl
+    .replace('{number}', encodeURIComponent(invoice?.number ?? ''))
+    .replace('{id}',     encodeURIComponent(invoice?.id ?? ''));
+}
+
+/**
+ * Escape a value for CSV output (Excel-friendly).
+ */
+function csvEscape(val) {
+  const str = String(val ?? '');
+  if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+    return '"' + str.replace(/"/g, '""') + '"';
+  }
+  return str;
+}
+
+export class InvoiceHistory extends UIElement {
+  static properties = {
+    invoices:    { type: Array,   default: [] },
+    currency:    { type: String,  default: 'USD',                   reflect: true },
+    density:     { type: String,  default: 'standard',              reflect: true },
+    loading:     { type: Boolean, default: false,                   reflect: true },
+    selectable:  { type: Boolean, default: false,                   reflect: true },
+    hrefPattern: { type: String,  default: '/invoices/{number}',    reflect: true, attribute: 'href-pattern' },
+    paginate:    { type: Number,  default: 25,                      reflect: true },
+    exportable:  { type: Boolean, default: true,                    reflect: true },
+    locale:      { type: String,  default: '' },
+    filter:      { type: String,  default: '',                      reflect: true },
+  };
+
+  // The composite stamps its own DOM (toolbar · table · empty) once on
+  // connect and mutates table inputs across renders — no html template.
+  static template = () => null;
+
+  static requiredIcons = ['download-simple', 'receipt', 'magnifying-glass'];
+
+  // ── Field refs ────────────────────────────────────────────────────
+  #stamped = false;
+  #cleanups = [];
+  #toolbarHost = null;       // <div data-toolbar>
+  #defaultToolbar = null;    // <table-toolbar-ui> (when no slot=toolbar provided)
+  #filterChipsHost = null;   // <div data-invoice-filter>
+  #exportBtn = null;         // <button-ui data-export>
+  #tableHost = null;         // <div data-table-host>
+  #table = null;             // <table-ui>
+  #emptyHost = null;         // <empty-state-ui data-empty>
+  #internalUpdate = false;
+  #loadCount = 0;            // monotonic guard against stale fetches
+  #warnedColumns = false;
+
+  // ── Public API ────────────────────────────────────────────────────
+
+  /** Set the active status filter. Returns true on hit. */
+  setFilter(value) {
+    const next = value || '';
+    if (next && !KNOWN_STATUSES.has(next)) return false;
+    return untracked(() => {
+      if (this.filter === next) return true;
+      const previous = this.filter;
+      this.filter = next;
+      this.dispatchEvent(new CustomEvent('invoice-filter-change', {
+        bubbles: true,
+        detail: { filter: next, previous },
+      }));
+      return true;
+    });
+  }
+
+  /** CSV blob of the currently-visible (filtered) rows. */
+  exportCsv() {
+    const rows = this.#visibleInvoices();
+    const lines = [CSV_HEADERS.join(',')];
+    for (const inv of rows) {
+      const cells = [
+        csvEscape(inv.number ?? ''),
+        csvEscape(inv.issuedAt ?? ''),
+        csvEscape(inv.dueAt ?? ''),
+        csvEscape(Number.isFinite(inv.amount) ? inv.amount : ''),
+        csvEscape(inv.currency || this.currency || 'USD'),
+        csvEscape(inv.status ?? ''),
+      ];
+      lines.push(cells.join(','));
+    }
+    const csv = lines.join('\r\n');
+    return new Blob([csv], { type: 'text/csv;charset=utf-8;' });
+  }
+
+  /** Array of selected invoice records (when `selectable` is set). */
+  getSelected() {
+    if (!this.#table) return [];
+    const indices = this.#table.selected || [];
+    const rows = this.#visibleInvoices();
+    return indices.map((i) => rows[i]).filter(Boolean);
+  }
+
+  /** Re-fetch invoices from `data-stream-src`. */
+  async refresh() {
+    const src = this.getAttribute('data-stream-src');
+    if (!src) return;
+    const tag = ++this.#loadCount;
+    this.setAttribute('loading', '');
+    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; // stale
+      this.removeAttribute('loading');
+      const list = Array.isArray(data)
+        ? data
+        : (Array.isArray(data?.invoices) ? data.invoices : []);
+      this.invoices = list;
+      this.dispatchEvent(new CustomEvent('load', {
+        bubbles: true,
+        detail: { count: list.length },
+      }));
+    } catch (err) {
+      if (tag !== this.#loadCount) return;
+      this.removeAttribute('loading');
+      this.setAttribute('error', '');
+      this.dispatchEvent(new CustomEvent('error', {
+        bubbles: true,
+        detail: { reason: 'fetch-failed', message: String(err?.message || err) },
+      }));
+    }
+  }
+
+  // ── Lifecycle ─────────────────────────────────────────────────────
+
+  connected() {
+    super.connected?.();
+    this.setAttribute('role', 'region');
+    if (!this.hasAttribute('aria-label') && !this.hasAttribute('aria-labelledby')) {
+      this.setAttribute('aria-label', 'Invoice history');
+    }
+
+    if (!this.#stamped) {
+      this.#absorbInlineInvoicesScript();
+      this.#stamp();
+      this.#wireListeners();
+      this.#stamped = true;
+    }
+
+    untracked(() => this.render());
+
+    if (this.getAttribute('data-stream-src')) {
+      this.refresh();
+    }
+  }
+
+  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 === 'data-stream-src' && oldVal !== newVal && newVal) {
+      this.refresh();
+    }
+  }
+
+  // ── Render — narrow; mutates per-region state ─────────────────────
+
+  render() {
+    if (!this.#stamped) return;
+
+    const list = Array.isArray(this.invoices) ? this.invoices : [];
+
+    // Empty / non-empty state attribute (CSS-gated reveal).
+    if (list.length === 0 && !this.loading) {
+      this.setAttribute('empty', '');
+    } else {
+      this.removeAttribute('empty');
+    }
+
+    // Refresh filter chip selection.
+    this.#renderFilterChips();
+
+    // Push columns + filtered data to the underlying table.
+    if (this.#table) {
+      this.#table.columns = this.#deriveColumns();
+      this.#table.data = this.#visibleInvoices();
+      // Forward forwarding-only props. Reading a signal-backed property on
+      // the CHILD (table-ui's own `density`/`loading`/`paginate`/`selectable`)
+      // while THIS element's own render effect is tracking would silently
+      // subscribe invoice-history's effect to table-ui's internal signals —
+      // this composite is a one-way source of truth for these forwarded
+      // props and must never react to the table's copies (gh#661). untracked()
+      // keeps the compare-before-write idempotent without leaking that
+      // cross-element subscription; invoice-detail.class.js avoids the same
+      // hazard by comparing via getAttribute() instead.
+      untracked(() => {
+        if (this.#table.density !== this.density) this.#table.density = this.density;
+        if (!!this.#table.loading !== !!this.loading) this.#table.loading = !!this.loading;
+        if (Number(this.#table.paginate || 0) !== Number(this.paginate || 0)) {
+          this.#table.paginate = Number(this.paginate || 0);
+        }
+        if (!!this.#table.selectable !== !!this.selectable) this.#table.selectable = !!this.selectable;
+      });
+    }
+
+    // Toolbar count: forward visible row count to default toolbar.
+    if (this.#defaultToolbar) {
+      this.#defaultToolbar.setAttribute('count', String(this.#visibleInvoices().length));
+    }
+
+    // Export button visibility tracks `exportable`.
+    if (this.#exportBtn) {
+      this.#exportBtn.hidden = !this.exportable;
+    }
+  }
+
+  // ── Internal — DOM stamping ───────────────────────────────────────
+
+  #absorbInlineInvoicesScript() {
+    const script = this.querySelector(':scope > script[type="application/json"][data-invoices]');
+    if (!script) return;
+    try {
+      const parsed = JSON.parse(script.textContent || '[]');
+      if (Array.isArray(parsed)) this.invoices = parsed;
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn('[invoice-history-ui] failed to parse <script data-invoices> JSON:', err?.message);
+    } finally {
+      script.remove();
+    }
+  }
+
+  #stamp() {
+    // ── Toolbar region ─────────────────────────────────────────────
+    const toolbar = document.createElement('div');
+    toolbar.setAttribute('data-toolbar', '');
+    this.appendChild(toolbar);
+    this.#toolbarHost = toolbar;
+
+    const userToolbar = this.querySelector(':scope > [slot="toolbar"]');
+    if (userToolbar) {
+      toolbar.appendChild(userToolbar);
+    } else {
+      // Default: <table-toolbar-ui> with title + count + filter chips +
+      // optional export button. The toolbar is wired by [for] when the
+      // table is stamped below.
+      const tt = document.createElement('table-toolbar-ui');
+      tt.setAttribute('data-default-toolbar', '');
+      tt.setAttribute('text', 'Invoices');
+      // Status-filter chips live in the [slot="actions"] region so they
+      // sit alongside the toolbar's title + search affordances.
+      const chips = document.createElement('div');
+      chips.setAttribute('data-invoice-filter', '');
+      chips.setAttribute('role', 'group');
+      chips.setAttribute('aria-label', 'Filter invoices by status');
+      chips.setAttribute('slot', 'actions');
+      tt.appendChild(chips);
+
+      const btn = document.createElement('button-ui');
+      btn.setAttribute('data-export', '');
+      btn.setAttribute('slot', 'actions');
+      btn.setAttribute('variant', 'outline');
+      btn.setAttribute('size', 'sm');
+      btn.setAttribute('text', 'Export CSV');
+      btn.setAttribute('icon', 'download-simple');
+      tt.appendChild(btn);
+
+      toolbar.appendChild(tt);
+      this.#defaultToolbar = tt;
+      this.#filterChipsHost = chips;
+      this.#exportBtn = btn;
+    }
+
+    // ── Table region ───────────────────────────────────────────────
+    const tableHost = document.createElement('div');
+    tableHost.setAttribute('data-table-host', '');
+    this.appendChild(tableHost);
+    this.#tableHost = tableHost;
+
+    const table = document.createElement('table-ui');
+    table.id = this.id ? `${this.id}__table` : `invoice-history-${Math.random().toString(36).slice(2, 8)}`;
+    table.setAttribute('data-invoice-table', '');
+    table.setAttribute('sortable', '');
+    tableHost.appendChild(table);
+    this.#table = table;
+
+    // Wire the default toolbar to this table by id.
+    if (this.#defaultToolbar) {
+      this.#defaultToolbar.setAttribute('for', table.id);
+    }
+
+    // ── Empty-state region ─────────────────────────────────────────
+    if (!this.querySelector(':scope > [slot="empty"]')) {
+      const empty = document.createElement('empty-state-ui');
+      empty.setAttribute('data-empty', '');
+      empty.setAttribute('icon', 'receipt');
+      empty.setAttribute('heading', 'No invoices yet');
+      empty.setAttribute('description', 'Invoices will appear here once issued.');
+      this.appendChild(empty);
+      this.#emptyHost = empty;
+    }
+  }
+
+  #renderFilterChips() {
+    if (!this.#filterChipsHost) return;
+    if (this.#filterChipsHost.children.length === 0) {
+      for (const chip of FILTER_CHIPS) {
+        const btn = document.createElement('button-ui');
+        btn.setAttribute('data-filter-chip', '');
+        btn.setAttribute('data-filter-value', chip.value);
+        btn.setAttribute('size', 'sm');
+        btn.setAttribute('text', chip.label);
+        this.#filterChipsHost.appendChild(btn);
+      }
+    }
+    // Sync `variant` to active state.
+    const active = this.filter || '';
+    for (const btn of this.#filterChipsHost.querySelectorAll('[data-filter-chip]')) {
+      const value = btn.getAttribute('data-filter-value') || '';
+      if (value === active) {
+        btn.setAttribute('variant', 'primary');
+        btn.setAttribute('aria-pressed', 'true');
+      } else {
+        btn.setAttribute('variant', 'ghost');
+        btn.setAttribute('aria-pressed', 'false');
+      }
+    }
+  }
+
+  // ── Derivation helpers ─────────────────────────────────────────────
+
+  #visibleInvoices() {
+    const list = Array.isArray(this.invoices) ? this.invoices : [];
+    const active = this.filter || '';
+    if (!active) return list;
+    return list.filter((inv) => (inv?.status || '') === active);
+  }
+
+  #deriveColumns() {
+    const locale = this.locale || (typeof document !== 'undefined' ? (document.documentElement?.lang || '') : '');
+    const defaultCurrency = this.currency || 'USD';
+
+    return [
+      {
+        key: 'number',
+        label: 'Invoice',
+        sortable: true,
+        wrap: false,
+      },
+      {
+        key: 'issuedAt',
+        label: 'Issued',
+        sortable: true,
+        format: (value) => formatDate(value, locale),
+      },
+      {
+        key: 'dueAt',
+        label: 'Due',
+        sortable: true,
+        format: (value) => formatDate(value, locale),
+      },
+      {
+        key: 'amount',
+        label: 'Amount',
+        sortable: true,
+        align: 'end',
+        render: (value, row, cell) => {
+          const currency = row?.currency || defaultCurrency;
+          const span = document.createElement('span');
+          span.setAttribute('data-invoice-amount', '');
+          span.textContent = formatAmount(value, currency, locale);
+          // Cell base alignment cue (also driven by CSS).
+          cell.dataset.align = 'end';
+          return span;
+        },
+        format: (value, row) => formatAmount(value, row?.currency || defaultCurrency, locale),
+      },
+      {
+        key: 'status',
+        label: 'Status',
+        sortable: true,
+        render: (value) => {
+          const key = String(value || '').toLowerCase();
+          const variant = STATUS_TO_VARIANT[key];
+          const label = STATUS_LABEL[key] || (value ? String(value) : '—');
+          const badge = document.createElement('badge-ui');
+          badge.setAttribute('data-invoice-status', '');
+          if (variant) {
+            badge.setAttribute('variant', variant);
+          } else {
+            badge.setAttribute('tone', 'muted');
+          }
+          badge.setAttribute('text', label);
+          badge.setAttribute('aria-label', label);
+          return badge;
+        },
+        format: (value) => STATUS_LABEL[String(value || '').toLowerCase()] || (value ? String(value) : ''),
+      },
+      {
+        key: 'actions',
+        label: '',
+        sortable: false,
+        align: 'end',
+        accessor: (row) => row,
+        render: (_value, row) => {
+          const wrap = document.createElement('span');
+          wrap.setAttribute('data-invoice-actions', '');
+
+          const viewBtn = document.createElement('button-ui');
+          viewBtn.setAttribute('data-invoice-action', 'view');
+          viewBtn.setAttribute('data-invoice-id', String(row?.id ?? row?.number ?? ''));
+          viewBtn.setAttribute('size', 'sm');
+          viewBtn.setAttribute('variant', 'ghost');
+          viewBtn.setAttribute('text', 'View');
+          wrap.appendChild(viewBtn);
+
+          const dlBtn = document.createElement('button-ui');
+          dlBtn.setAttribute('data-invoice-action', 'download');
+          dlBtn.setAttribute('data-invoice-id', String(row?.id ?? row?.number ?? ''));
+          dlBtn.setAttribute('size', 'sm');
+          dlBtn.setAttribute('variant', 'ghost');
+          dlBtn.setAttribute('icon', 'download-simple');
+          dlBtn.setAttribute('aria-label', `Download invoice ${row?.number ?? ''}`);
+          wrap.appendChild(dlBtn);
+
+          return wrap;
+        },
+      },
+    ];
+  }
+
+  // ── Listener wiring ────────────────────────────────────────────────
+
+  #wireListeners() {
+    // ── Filter chip clicks ──
+    const onChipClick = (e) => {
+      const chip = e.target?.closest?.('[data-filter-chip]');
+      if (!chip || !this.#filterChipsHost?.contains(chip)) return;
+      e.stopPropagation();
+      const value = chip.getAttribute('data-filter-value') || '';
+      this.setFilter(value);
+    };
+    this.addEventListener('press', onChipClick);
+    this.addEventListener('click', onChipClick);
+    this.#cleanups.push(() => this.removeEventListener('press', onChipClick));
+    this.#cleanups.push(() => this.removeEventListener('click', onChipClick));
+
+    // ── Row activation (cell-click excluding actions column) ──
+    const onCellClick = (e) => {
+      const detail = e?.detail;
+      if (!detail) return;
+      // Actions column has its own buttons — don't navigate when clicking them.
+      if (detail.key === 'actions') return;
+      const row = detail.row;
+      if (!row) return;
+      const href = resolveHref(this.hrefPattern, row);
+      const ev = new CustomEvent('invoice-row-click', {
+        bubbles: true,
+        cancelable: true,
+        detail: { invoice: row, href },
+      });
+      const proceed = this.dispatchEvent(ev);
+      if (proceed && typeof window !== 'undefined' && window.location?.assign) {
+        try { window.location.assign(href); } catch { /* test envs */ }
+      }
+    };
+    this.addEventListener('cell-click', onCellClick);
+    this.#cleanups.push(() => this.removeEventListener('cell-click', onCellClick));
+
+    // ── Per-row action buttons ──
+    const onActionClick = (e) => {
+      const btn = e.target?.closest?.('button-ui[data-invoice-action]');
+      if (!btn) return;
+      // Ensure we're inside our table region (not the toolbar or empty).
+      if (!this.#tableHost?.contains(btn)) return;
+      e.stopPropagation();
+      const action = btn.getAttribute('data-invoice-action');
+      const invoiceId = btn.getAttribute('data-invoice-id') || '';
+      const row = (this.invoices || []).find(
+        (r) => String(r?.id ?? r?.number ?? '') === invoiceId,
+      );
+      if (!row) return;
+      if (action === 'view') {
+        const href = resolveHref(this.hrefPattern, row);
+        const ev = new CustomEvent('invoice-row-click', {
+          bubbles: true,
+          cancelable: true,
+          detail: { invoice: row, href },
+        });
+        const proceed = this.dispatchEvent(ev);
+        if (proceed && typeof window !== 'undefined' && window.location?.assign) {
+          try { window.location.assign(href); } catch { /* test envs */ }
+        }
+      } else if (action === 'download') {
+        const blob = this.#exportSingleInvoiceCsv(row);
+        this.dispatchEvent(new CustomEvent('invoice-export', {
+          bubbles: true,
+          cancelable: true,
+          detail: { blob, rowCount: 1, invoice: row },
+        }));
+      }
+    };
+    this.addEventListener('press', onActionClick);
+    this.addEventListener('click', onActionClick);
+    this.#cleanups.push(() => this.removeEventListener('press', onActionClick));
+    this.#cleanups.push(() => this.removeEventListener('click', onActionClick));
+
+    // ── Export CSV button ──
+    const onExport = (e) => {
+      const btn = e.target?.closest?.('button-ui[data-export]');
+      if (!btn || !this.#toolbarHost?.contains(btn)) return;
+      e.stopPropagation();
+      const blob = this.exportCsv();
+      const ev = new CustomEvent('invoice-export', {
+        bubbles: true,
+        cancelable: true,
+        detail: { blob, rowCount: this.#visibleInvoices().length },
+      });
+      const proceed = this.dispatchEvent(ev);
+      if (proceed && typeof document !== 'undefined' && typeof URL !== 'undefined') {
+        try {
+          const url = URL.createObjectURL(blob);
+          const a = document.createElement('a');
+          a.href = url;
+          a.download = 'invoices.csv';
+          document.body.appendChild(a);
+          a.click();
+          a.remove();
+          setTimeout(() => URL.revokeObjectURL(url), 0);
+        } catch { /* download not available */ }
+      }
+    };
+    this.addEventListener('press', onExport);
+    this.addEventListener('click', onExport);
+    this.#cleanups.push(() => this.removeEventListener('press', onExport));
+    this.#cleanups.push(() => this.removeEventListener('click', onExport));
+
+    // ── Selection forwarding ──
+    const onSelect = (e) => {
+      if (e.target !== this.#table) return;
+      const selected = this.getSelected();
+      this.dispatchEvent(new CustomEvent('invoice-selection-change', {
+        bubbles: true,
+        detail: { selected },
+      }));
+    };
+    this.addEventListener('select', onSelect);
+    this.#cleanups.push(() => this.removeEventListener('select', onSelect));
+  }
+
+  #exportSingleInvoiceCsv(inv) {
+    const lines = [
+      CSV_HEADERS.join(','),
+      [
+        csvEscape(inv.number ?? ''),
+        csvEscape(inv.issuedAt ?? ''),
+        csvEscape(inv.dueAt ?? ''),
+        csvEscape(Number.isFinite(inv.amount) ? inv.amount : ''),
+        csvEscape(inv.currency || this.currency || 'USD'),
+        csvEscape(inv.status ?? ''),
+      ].join(','),
+    ];
+    return new Blob([lines.join('\r\n')], { type: 'text/csv;charset=utf-8;' });
+  }
+}