@adia-ai/web-modules 0.8.36 → 0.8.38

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

@@ -0,0 +1,711 @@
+/**
+ * <invoice-detail-ui> — Page-level invoice composite (display only).
+ *
+ * Renders a single invoice — header (number + status badge + dates),
+ * customer + remit-to blocks, line-items table, right-aligned totals
+ * stack, and a slot-driven action toolbar. Composite, not primitive:
+ * the constituent primitives (card-ui, table-ui, stat-ui, tag-ui,
+ * button-ui) already exist; this module owns the canonical layout,
+ * status-badge variant mapping, totals math, and data-stream binding
+ * so billing-enabled products do not re-derive them.
+ *
+ * SPEC: .claude/docs/specs/implementation-ready/SPEC-007-invoice-detail-page.md
+ * WAI-APG: https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/
+ *
+ * Architecture (light-DOM, ADR-0033):
+ *   The composite stamps a six-region skeleton once on first connect:
+ *     [data-header] · [data-parties] · [data-lines] · [data-totals]
+ *     · [data-footer] · [data-empty]
+ *   Then mutates per-region nodes via id-keyed in-place diff on
+ *   every `invoice` / `status` / `currency` / `loading` change.
+ *
+ * Form participation: none. Extends UIElement, not UIFormElement —
+ * invoices are display surfaces (per SPEC-007 §8 Base class).
+ *
+ * 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(['draft', 'open', 'paid', 'past-due', 'void']);
+
+/**
+ * Map invoice.status to the tag-ui [variant] enum.
+ * Unknown statuses fall back to `default` and trigger a one-shot warn.
+ */
+const STATUS_TO_VARIANT = {
+  draft: 'default',
+  open: 'info',
+  paid: 'success',
+  'past-due': 'warning',
+  void: 'default',
+};
+
+const STATUS_LABEL = {
+  draft: 'Draft',
+  open: 'Open',
+  paid: 'Paid',
+  'past-due': 'Past due',
+  void: 'Void',
+};
+
+/**
+ * Format an amount with Intl.NumberFormat for the given currency + locale.
+ * Returns a string like "$24.50"; falls back to "{currency} {value}" on
+ * 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',
+      minimumFractionDigits: 2,
+      maximumFractionDigits: 2,
+    }).format(value);
+  } catch {
+    return `${currency || '$'}${value.toFixed(2)}`;
+  }
+}
+
+/**
+ * Format an ISO date string with Intl.DateTimeFormat.
+ * Returns the input verbatim on failure (the consumer's authored
+ * string is better than no string).
+ */
+function formatDate(iso, locale) {
+  if (!iso) return '';
+  try {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime())) return String(iso);
+    return new Intl.DateTimeFormat(locale || undefined, {
+      year: 'numeric',
+      month: 'short',
+      day: 'numeric',
+    }).format(d);
+  } catch {
+    return String(iso);
+  }
+}
+
+export class UIInvoiceDetail extends UIElement {
+  static get properties() {
+    return {
+      // The invoice record — source of truth for the rendered page.
+      invoice: { type: Object, default: null },
+      status: { type: String, default: 'draft', reflect: true },
+      currency: { type: String, default: 'USD', reflect: true },
+      density: { type: String, default: 'standard', reflect: true },
+      loading: { type: Boolean, default: false, reflect: true },
+      printable: { type: Boolean, default: true, reflect: true },
+      locale: { type: String, default: '' },
+    };
+  }
+
+  // No template — the 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 focus inside the lines table.
+  static template = () => null;
+
+  // ── Field refs ────────────────────────────────────────────────────
+  #stamped = false;
+  #cleanups = [];
+  #headerHost = null; // [data-header] — number + status + dates + actions
+  #headerNumber = null; // <h2> invoice number heading
+  #headerStatus = null; // <tag-ui> status badge
+  #headerMeta = null; // dates row
+  #headerActions = null; // slot region for header-actions
+  #partiesHost = null; // [data-parties] — customer + remit-to
+  #customerBlock = null; // default customer content
+  #remitToBlock = null; // default remit-to content
+  #linesHost = null; // [data-lines] — line-items table card
+  #linesTable = null; // <table-ui>
+  #totalsHost = null; // [data-totals] — totals stack
+  #footerHost = null; // [data-footer] — slot region for terms / notes
+  #emptyHost = null; // [data-empty] — empty-state-ui
+  #headingId = '';
+  #internalUpdate = false;
+  #warnedStatus = false;
+  #loadCount = 0;
+  #lastEmittedInvoiceNumber = '';
+
+  // ── Public imperative API (SPEC §4 Methods) ───────────────────────
+
+  /**
+   * Invoke window.print() with the invoice page as the print target.
+   * If window.print is unavailable, dispatches `error` with reason=
+   * print-unavailable.
+   */
+  print() {
+    if (typeof globalThis.window?.print === 'function') {
+      try {
+        globalThis.window.print();
+      } catch (err) {
+        this.dispatchEvent(new CustomEvent('error', {
+          bubbles: true,
+          detail: { reason: 'print-unavailable', message: String(err?.message || err) },
+        }));
+      }
+      return;
+    }
+    this.dispatchEvent(new CustomEvent('error', {
+      bubbles: true,
+      detail: { reason: 'print-unavailable' },
+    }));
+  }
+
+  /** Re-fetch the invoice from `data-stream-src`. */
+  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; // stale
+      this.loading = false;
+      // Allow either {invoice: {...}} envelope or the raw record.
+      const record = data && typeof data === 'object' && data.invoice
+        ? data.invoice
+        : data;
+      this.invoice = record;
+      // Mirror invoice.status into the reflected host status when present.
+      if (record?.status) {
+        this.#internalUpdate = true;
+        try { this.status = String(record.status); } finally { this.#internalUpdate = false; }
+      }
+      const number = record?.number || '';
+      this.dispatchEvent(new CustomEvent('load', {
+        bubbles: true,
+        detail: { invoiceNumber: number },
+      }));
+      this.#lastEmittedInvoiceNumber = number;
+    } 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) {
+      // Absorb a <script type="application/json" data-invoice> child
+      // before stamping wipes anything. Authors can declare the
+      // invoice declaratively this way (matches the in-band JSON
+      // pattern shared with table-ui / plan-picker-ui).
+      this.#absorbInlineInvoiceScript();
+      this.#stamp();
+      this.#wireListeners();
+      this.#stamped = true;
+    }
+
+    // Trigger first render after the registry has had a chance to
+    // upgrade the composed primitives.
+    untracked(() => this.render());
+
+    // Fetch on connect when configured.
+    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 || this.#internalUpdate) return;
+    if (name === 'data-stream-src' && oldVal !== newVal && newVal) {
+      this.refresh();
+    }
+  }
+
+  // ── Render — narrow; mutates per-region nodes only ────────────────
+
+  render() {
+    if (!this.#stamped) return;
+
+    const inv = this.invoice;
+    const isEmpty = !inv && !this.getAttribute('data-stream-src');
+    if (isEmpty) this.setAttribute('empty', ''); else this.removeAttribute('empty');
+
+    // aria-busy mirrors [loading].
+    if (this.loading) this.setAttribute('aria-busy', 'true');
+    else this.removeAttribute('aria-busy');
+
+    // Status resolution — invoice.status wins unless the host has been
+    // EXPLICITLY set to a different status (i.e. the host's `status`
+    // attribute was authored, overriding the data). We can't simply
+    // read `this.status` first because the reflected default 'draft'
+    // would mask any invoice.status. Use the attribute presence as
+    // the signal of an explicit host-side override.
+    const hostStatusOverride = this.hasAttribute('status')
+      ? this.getAttribute('status')
+      : '';
+    const status = hostStatusOverride || inv?.status || this.status || 'draft';
+    if (!KNOWN_STATUSES.has(status)) {
+      if (!this.#warnedStatus) {
+        this.#warnedStatus = true;
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[invoice-detail-ui] unknown status "${status}" — rendering default badge.`,
+        );
+      }
+    }
+
+    if (isEmpty) {
+      // Empty state is rendered (CSS-gated reveal); we still render
+      // the header chrome with an empty title so the host has a
+      // labelable region in screen-reader output.
+      this.#renderHeader(null, status);
+      // aria-label fallback for empty.
+      if (!this.hasAttribute('aria-label') && !this.hasAttribute('aria-labelledby')) {
+        this.setAttribute('aria-label', 'No invoice loaded');
+      }
+      return;
+    }
+
+    if (!inv) {
+      // loading without an invoice yet — show the empty placeholder
+      // (no header content to render).
+      this.#renderHeader(null, status);
+      return;
+    }
+
+    this.#renderHeader(inv, status);
+    this.#renderParties(inv);
+    this.#renderLines(inv);
+    this.#renderTotals(inv);
+    this.#renderAccessibleLabel(inv);
+  }
+
+  // ── Internal — DOM stamping ───────────────────────────────────────
+
+  #absorbInlineInvoiceScript() {
+    const script = this.querySelector(
+      ':scope > script[type="application/json"][data-invoice]',
+    );
+    if (!script) return;
+    try {
+      const parsed = JSON.parse(script.textContent || '{}');
+      if (parsed && typeof parsed === 'object') {
+        const record = parsed.invoice && typeof parsed.invoice === 'object'
+          ? parsed.invoice
+          : parsed;
+        this.invoice = record;
+        if (record?.status) {
+          this.#internalUpdate = true;
+          try { this.status = String(record.status); } finally { this.#internalUpdate = false; }
+        }
+      }
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[invoice-detail-ui] failed to parse <script data-invoice> 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. The composite physically moves
+   * the children into their target containers during stamping.
+   */
+  #absorbSlottedChildren(slotName, target) {
+    const nodes = this.querySelectorAll(`:scope > [slot="${slotName}"]`);
+    for (const n of nodes) target.appendChild(n);
+  }
+
+  #stamp() {
+    // Unique id for the invoice-number heading (drives aria-labelledby).
+    this.#headingId = `inv-h-${Math.random().toString(36).slice(2, 8)}`;
+
+    // ── Header region ── number + status + dates + slotted actions.
+    const header = document.createElement('header');
+    header.setAttribute('data-header', '');
+
+    const titleWrap = document.createElement('div');
+    titleWrap.setAttribute('data-header-title', '');
+
+    const number = document.createElement('h2');
+    number.id = this.#headingId;
+    number.setAttribute('data-invoice-number', '');
+    titleWrap.appendChild(number);
+
+    const status = document.createElement('tag-ui');
+    status.setAttribute('data-invoice-status', '');
+    status.setAttribute('size', 'md');
+    titleWrap.appendChild(status);
+
+    const meta = document.createElement('div');
+    meta.setAttribute('data-header-meta', '');
+
+    const actions = document.createElement('div');
+    actions.setAttribute('data-header-actions', '');
+    actions.setAttribute('data-invoice-actions', '');
+
+    header.append(titleWrap, meta, actions);
+    this.appendChild(header);
+    this.#headerHost = header;
+    this.#headerNumber = number;
+    this.#headerStatus = status;
+    this.#headerMeta = meta;
+    this.#headerActions = actions;
+
+    // Absorb consumer-authored [slot="header-actions"] children. Per
+    // SPEC-007 §13 OD-002 the composite never stamps a default
+    // toolbar; the actions container stays empty until consumers
+    // slot one or more buttons.
+    this.#absorbSlottedChildren('header-actions', actions);
+
+    // ── Parties region ── customer + remit-to blocks.
+    const parties = document.createElement('section');
+    parties.setAttribute('data-parties', '');
+
+    const customer = document.createElement('div');
+    customer.setAttribute('data-customer', '');
+    const customerDefault = document.createElement('div');
+    customerDefault.setAttribute('data-customer-default', '');
+    customer.appendChild(customerDefault);
+    this.#customerBlock = customerDefault;
+
+    const remitTo = document.createElement('div');
+    remitTo.setAttribute('data-remit-to', '');
+    const remitToDefault = document.createElement('div');
+    remitToDefault.setAttribute('data-remit-to-default', '');
+    remitTo.appendChild(remitToDefault);
+    this.#remitToBlock = remitToDefault;
+
+    parties.append(customer, remitTo);
+    this.appendChild(parties);
+    this.#partiesHost = parties;
+
+    // Absorb consumer overrides for the customer + remit-to blocks.
+    // When present, the default block stays empty and the CSS
+    // collapses it.
+    this.#absorbSlottedChildren('customer-block', customer);
+    this.#absorbSlottedChildren('remit-to-block', remitTo);
+
+    // ── Lines region ── card wrapping a table-ui of line items.
+    const lines = document.createElement('section');
+    lines.setAttribute('data-lines', '');
+
+    const linesCard = document.createElement('card-ui');
+    linesCard.setAttribute('data-lines-card', '');
+    linesCard.setAttribute('padding', 'none');
+    const linesBody = document.createElement('section');
+    linesBody.setAttribute('bleed', '');
+    linesCard.appendChild(linesBody);
+
+    const table = document.createElement('table-ui');
+    table.setAttribute('data-lines-table', '');
+    table.setAttribute('density', this.density || 'standard');
+    linesBody.appendChild(table);
+
+    lines.appendChild(linesCard);
+    this.appendChild(lines);
+    this.#linesHost = lines;
+    this.#linesTable = table;
+
+    // ── Totals region ── stat-ui rows for subtotal · tax · discount · total.
+    const totals = document.createElement('section');
+    totals.setAttribute('data-totals', '');
+    this.appendChild(totals);
+    this.#totalsHost = totals;
+
+    // ── Footer region ── slotted notes / terms.
+    const footer = document.createElement('footer');
+    footer.setAttribute('data-footer', '');
+    const footerNotes = document.createElement('div');
+    footerNotes.setAttribute('data-footer-notes', '');
+    footer.appendChild(footerNotes);
+    this.appendChild(footer);
+    this.#footerHost = footer;
+
+    // Absorb consumer-authored [slot="footer"] children. When the
+    // slot is empty AND footerNotes is empty, CSS collapses the
+    // footer.
+    this.#absorbSlottedChildren('footer', footer);
+
+    // ── Empty state ── overridable via the host wrapping its own
+    // empty-state, but we ship a default for the zero-config path.
+    const empty = document.createElement('empty-state-ui');
+    empty.setAttribute('data-empty', '');
+    empty.setAttribute('icon', 'receipt');
+    empty.setAttribute('heading', 'No invoice loaded');
+    empty.setAttribute(
+      'description',
+      'Pass an `invoice` record or `data-stream-src` to render an invoice.',
+    );
+    this.appendChild(empty);
+    this.#emptyHost = empty;
+  }
+
+  // ── Internal — region renderers (mutate existing nodes) ───────────
+
+  #renderHeader(inv, status) {
+    if (!this.#headerNumber || !this.#headerStatus || !this.#headerMeta) return;
+
+    // Invoice number heading.
+    const number = inv?.number ? String(inv.number) : '';
+    if (this.#headerNumber.textContent !== number) {
+      this.#headerNumber.textContent = number;
+    }
+
+    // Status badge — variant + text.
+    const variant = STATUS_TO_VARIANT[status] || 'default';
+    const label = STATUS_LABEL[status] || (status ? String(status) : 'Draft');
+    if (this.#headerStatus.getAttribute('variant') !== variant) {
+      this.#headerStatus.setAttribute('variant', variant);
+    }
+    if (this.#headerStatus.getAttribute('text') !== label) {
+      this.#headerStatus.setAttribute('text', label);
+    }
+    // aria-label for screen readers — match the variant intent.
+    this.#headerStatus.setAttribute('aria-label', `Status: ${label}`);
+
+    // Hide the badge entirely on the empty / pending state.
+    if (!inv) this.#headerStatus.setAttribute('hidden', '');
+    else this.#headerStatus.removeAttribute('hidden');
+
+    // Header meta — issued + due dates.
+    this.#headerMeta.replaceChildren();
+    if (!inv) return;
+    const locale = this.locale || (typeof document !== 'undefined'
+      ? document.documentElement.lang : '');
+    if (inv.issuedAt) {
+      const issued = document.createElement('span');
+      issued.setAttribute('data-issued', '');
+      issued.textContent = `Issued ${formatDate(inv.issuedAt, locale)}`;
+      this.#headerMeta.appendChild(issued);
+    }
+    if (inv.dueAt) {
+      const due = document.createElement('span');
+      due.setAttribute('data-due', '');
+      due.textContent = `Due ${formatDate(inv.dueAt, locale)}`;
+      this.#headerMeta.appendChild(due);
+    }
+  }
+
+  #renderParties(inv) {
+    if (!this.#customerBlock || !this.#remitToBlock) return;
+
+    // Customer block.
+    this.#customerBlock.replaceChildren();
+    if (inv?.customer) {
+      const heading = document.createElement('div');
+      heading.setAttribute('data-party-heading', '');
+      heading.textContent = 'Billed to';
+      this.#customerBlock.appendChild(heading);
+
+      if (inv.customer.name) {
+        const name = document.createElement('div');
+        name.setAttribute('data-party-name', '');
+        name.textContent = String(inv.customer.name);
+        this.#customerBlock.appendChild(name);
+      }
+      if (inv.customer.email) {
+        const email = document.createElement('div');
+        email.setAttribute('data-party-email', '');
+        email.textContent = String(inv.customer.email);
+        this.#customerBlock.appendChild(email);
+      }
+      if (inv.customer.address) {
+        const address = document.createElement('div');
+        address.setAttribute('data-party-address', '');
+        address.textContent = String(inv.customer.address);
+        this.#customerBlock.appendChild(address);
+      }
+    }
+
+    // Remit-to block (optional).
+    this.#remitToBlock.replaceChildren();
+    if (inv?.remitTo) {
+      const heading = document.createElement('div');
+      heading.setAttribute('data-party-heading', '');
+      heading.textContent = 'Remit to';
+      this.#remitToBlock.appendChild(heading);
+
+      if (inv.remitTo.name) {
+        const name = document.createElement('div');
+        name.setAttribute('data-party-name', '');
+        name.textContent = String(inv.remitTo.name);
+        this.#remitToBlock.appendChild(name);
+      }
+      if (inv.remitTo.address) {
+        const address = document.createElement('div');
+        address.setAttribute('data-party-address', '');
+        address.textContent = String(inv.remitTo.address);
+        this.#remitToBlock.appendChild(address);
+      }
+    }
+  }
+
+  #renderLines(inv) {
+    if (!this.#linesTable) return;
+
+    const currency = inv?.currency || this.currency || 'USD';
+    const locale = this.locale || (typeof document !== 'undefined'
+      ? document.documentElement.lang : '');
+
+    // Columns + data — handed to table-ui via JS props (the data
+    // lifecycle path documented in table.yaml).
+    this.#linesTable.columns = [
+      { key: 'description', label: 'Description', flex: 1 },
+      { key: 'qty', label: 'Qty', width: 80, format: (v) => String(v ?? '') },
+      {
+        key: 'unitAmount',
+        label: 'Unit',
+        width: 120,
+        format: (v) => formatAmount(v, currency, locale),
+      },
+      {
+        key: 'amount',
+        label: 'Amount',
+        width: 140,
+        format: (v) => formatAmount(v, currency, locale),
+      },
+    ];
+
+    const rows = Array.isArray(inv?.lines) ? inv.lines : [];
+    this.#linesTable.data = rows.map((line, i) => ({
+      __row: i,
+      description: line?.description ?? '',
+      qty: line?.qty ?? '',
+      unitAmount: line?.unitAmount ?? 0,
+      amount: line?.amount ?? 0,
+    }));
+    // Mirror density.
+    if (this.#linesTable.getAttribute('density') !== this.density) {
+      this.#linesTable.setAttribute('density', this.density || 'standard');
+    }
+  }
+
+  #renderTotals(inv) {
+    if (!this.#totalsHost) return;
+
+    const currency = inv?.currency || this.currency || 'USD';
+    const locale = this.locale || (typeof document !== 'undefined'
+      ? document.documentElement.lang : '');
+
+    this.#totalsHost.replaceChildren();
+    if (!inv) return;
+
+    const rows = [
+      { key: 'subtotal', label: 'Subtotal', value: inv.subtotal },
+      { key: 'tax', label: 'Tax', value: inv.tax },
+    ];
+    if (Number.isFinite(inv.discount) && inv.discount > 0) {
+      rows.push({ key: 'discount', label: 'Discount', value: -Math.abs(inv.discount) });
+    }
+    for (const row of rows) {
+      if (!Number.isFinite(row.value)) continue;
+      const line = document.createElement('div');
+      line.setAttribute('data-totals-row', '');
+      line.setAttribute('data-totals-key', row.key);
+      const labelEl = document.createElement('span');
+      labelEl.setAttribute('data-totals-label', '');
+      labelEl.textContent = row.label;
+      const valueEl = document.createElement('span');
+      valueEl.setAttribute('data-totals-value', '');
+      valueEl.textContent = formatAmount(row.value, currency, locale);
+      line.append(labelEl, valueEl);
+      this.#totalsHost.appendChild(line);
+    }
+
+    // Grand total — rendered prominently.
+    if (Number.isFinite(inv.total)) {
+      const line = document.createElement('div');
+      line.setAttribute('data-totals-row', '');
+      line.setAttribute('data-totals-key', 'total');
+      line.setAttribute('data-grand-total', '');
+      const labelEl = document.createElement('span');
+      labelEl.setAttribute('data-totals-label', '');
+      labelEl.textContent = 'Total';
+      const valueEl = document.createElement('span');
+      valueEl.setAttribute('data-totals-value', '');
+      valueEl.textContent = formatAmount(inv.total, currency, locale);
+      line.append(labelEl, valueEl);
+      this.#totalsHost.appendChild(line);
+    }
+  }
+
+  #renderAccessibleLabel(inv) {
+    if (!inv) return;
+    // aria-labelledby points at the invoice-number heading so screen
+    // readers announce the landmark with the invoice number as its
+    // name.
+    if (this.#headingId) {
+      this.setAttribute('aria-labelledby', this.#headingId);
+    }
+  }
+
+  // ── Event delegation ──────────────────────────────────────────────
+
+  #wireListeners() {
+    // Header-action activation — bubble `press` (button-ui) or `click`
+    // up from any [data-invoice-action] descendant slotted into the
+    // header-actions slot.
+    const onAction = (e) => {
+      const target = e.target?.closest?.('[data-invoice-action]');
+      if (!target || !this.contains(target)) return;
+      const action = target.getAttribute('data-invoice-action') || '';
+      if (!action) return;
+      const invoiceNumber = this.invoice?.number || '';
+      e.stopPropagation();
+      this.dispatchEvent(new CustomEvent('invoice-action', {
+        bubbles: true,
+        detail: { action, invoiceNumber },
+      }));
+    };
+    this.addEventListener('press', onAction);
+    this.addEventListener('click', onAction);
+    this.#cleanups.push(() => this.removeEventListener('press', onAction));
+    this.#cleanups.push(() => this.removeEventListener('click', onAction));
+
+    // Line-item click → emit `line-item-click`. Listens at the lines
+    // host and routes via the data-row attribute on the table-ui's
+    // row element (per table-ui's data lifecycle).
+    const onLineClick = (e) => {
+      if (!this.#linesHost) return;
+      const path = e.composedPath ? e.composedPath() : [];
+      const row = path.find((n) => n?.getAttribute && n.getAttribute('data-row') != null);
+      if (!row || !this.#linesHost.contains(row)) return;
+      const index = Number(row.getAttribute('data-row'));
+      const lineItem = Array.isArray(this.invoice?.lines)
+        ? this.invoice.lines[index]
+        : null;
+      if (!Number.isFinite(index) || lineItem == null) return;
+      this.dispatchEvent(new CustomEvent('line-item-click', {
+        bubbles: true,
+        detail: { index, lineItem },
+      }));
+    };
+    this.addEventListener('click', onLineClick);
+    this.#cleanups.push(() => this.removeEventListener('click', onLineClick));
+  }
+}