@adia-ai/web-modules 0.8.35 → 0.8.37

package/billing/invoice-history/invoice-history.css

@@ -0,0 +1,130 @@
+/* ═══════════════════════════════════════════════════════════════
+   <invoice-history-ui> — Canonical billing-list composite.
+
+   Composite over <table-ui> + <table-toolbar-ui> + <badge-ui> +
+   <button-ui> + <empty-state-ui>. The host stacks three regions in
+   DOM order: toolbar · table · empty-state. Each row in the table
+   is owned by <table-ui>; this composite only styles its own
+   region scaffolding + cell-internal billing chrome (status badge,
+   amount alignment, action cluster).
+
+   SPEC: docs/specs/implementation-ready/SPEC-008-invoice-history-table.md
+   Two-block @scope pattern per docs/specs/component-token-contract.md.
+   Zero raw color values (repo hard rule); rem units for sizes ≥ 3px.
+   ═══════════════════════════════════════════════════════════════ */
+
+/* ── Block 1: TOKEN DECLARATIONS ───────────────────────────────── */
+
+invoice-history-ui {
+  --invoice-history-bg:               transparent;
+  --invoice-history-gap:              var(--a-space-3);
+  --invoice-history-row-min-height:   var(--table-row-h, 3rem);
+
+  --invoice-history-toolbar-gap:      var(--a-space-3);
+
+  --invoice-history-amount-font:      var(--a-font-mono);
+  --invoice-history-amount-fg:        var(--a-fg-strong, var(--md-sys-color-neutral-on-surface));
+  --invoice-history-date-fg:          var(--a-fg-muted);
+
+  --invoice-history-filter-gap:       var(--a-space-2);
+
+  --invoice-history-actions-gap:      var(--a-space-1);
+}
+
+/* ── Block 2: SCOPED LAYOUT ────────────────────────────────────── */
+
+@scope (invoice-history-ui) {
+
+  :scope {
+    display: block;
+    background: var(--invoice-history-bg);
+  }
+
+  /* ── Region stacking (toolbar · table · empty) ── */
+  :scope > [data-toolbar],
+  :scope > [data-table-host],
+  :scope > [data-empty] {
+    display: block;
+  }
+
+  :scope > [data-toolbar] {
+    margin-block-end: var(--invoice-history-gap);
+  }
+
+  /* Status-filter chip cluster lives in the toolbar's actions slot. */
+  :scope [data-invoice-filter] {
+    display: inline-flex;
+    flex-wrap: wrap;
+    gap: var(--invoice-history-filter-gap);
+    align-items: center;
+  }
+
+  /* ── Underlying table cascade ── */
+  /* Forward row-height token. Do NOT set `display:` — table-ui's own
+     @scope assigns `display: grid` + sets `grid-template-columns` via
+     JS; overriding the display collapses the grid into a single
+     column. (Caught in v0.6.34 dogfood-sweep visual probe.) */
+  :scope > [data-table-host] > table-ui {
+    --table-row-h: var(--invoice-history-row-min-height);
+    width: 100%;
+  }
+
+  /* ── Per-cell billing chrome ── */
+  /* Amount cell — tabular-nums, mono stack, end-aligned. */
+  :scope [data-invoice-amount] {
+    font-family: var(--invoice-history-amount-font);
+    font-variant-numeric: tabular-nums;
+    color: var(--invoice-history-amount-fg);
+    text-align: end;
+  }
+
+  /* Status badge — let badge-ui's own variant supply the chrome.
+     We only adjust the cell's display so the badge doesn't stretch. */
+  :scope [data-invoice-status] {
+    display: inline-flex;
+    align-items: center;
+  }
+
+  /* Per-row action cluster (View + Download). */
+  :scope [data-invoice-actions] {
+    display: inline-flex;
+    gap: var(--invoice-history-actions-gap);
+    align-items: center;
+    justify-content: flex-end;
+  }
+
+  /* ── Empty + loading state branches ──
+     Hide [data-empty] when host is NOT empty; do NOT set a display
+     value when shown (would clobber empty-state-ui's flex layout). */
+  :scope:not([empty]) > [data-empty] {
+    display: none;
+  }
+  :scope[empty] > [data-table-host] {
+    display: none;
+  }
+  :scope[loading] > [data-empty] {
+    display: none;
+  }
+
+  /* Hide the empty-state when the consumer provides a [slot="empty"]
+     override — the override is its own positioned block. */
+  :scope > [slot="empty"] {
+    display: none;
+  }
+  :scope[empty] > [slot="empty"] {
+    display: block;
+  }
+
+  /* ── Error state styling (data-stream-src fetch failed). ── */
+  :scope[error] > [data-empty] {
+    --empty-state-icon-fg: var(--a-danger-strong, var(--md-sys-color-danger));
+  }
+
+  /* ── Compact density forwards to the table primitive ── */
+  :scope[density="compact"] {
+    --invoice-history-row-min-height: var(--table-row-h-compact, 2.25rem);
+  }
+  :scope[density="comfortable"] {
+    --invoice-history-row-min-height: var(--table-row-h-comfortable, 3.5rem);
+  }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * `<invoice-history-ui>` — auto-registers the tag on import.
+ *
+ * For a non-side-effect class import (test isolation, tag override),
+ * use the class export from `./invoice-history.class.js`:
+ *
+ *   import { InvoiceHistory } from '@adia-ai/web-modules/billing/invoice-history/class';
+ */
+
+import { InvoiceHistory } from './invoice-history.class.js';
+
+if (!customElements.get('invoice-history-ui')) {
+  customElements.define('invoice-history-ui', InvoiceHistory);
+}
+
+export { InvoiceHistory };

package/billing/invoice-history/invoice-history.yaml

@@ -0,0 +1,398 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: InvoiceHistory
+tag: invoice-history-ui
+status: experimental
+component: InvoiceHistory
+category: display
+version: 1
+description: |
+  Canonical billing-list composite — a pre-configured <table-ui> with
+  invoice-shaped columns (number, issued, due, amount, status, actions),
+  status-badge cell renderer (paid/open/past-due/void/draft → semantic
+  badge variant), currency cell renderer, optional search + filter
+  chips via <table-toolbar-ui>, and a row-click that navigates to the
+  invoice detail page.
+
+  Wraps <table-ui> with billing-shaped columns + cell renderers + a
+  CSV-export toolbar. Consumer passes invoices[]; the composite owns
+  column shape, status-to-badge mapping, currency formatting, date
+  formatting, and navigation. Sibling to SPEC-007 (invoice detail).
+
+  Each invoice record: {id, number, status, issuedAt, dueAt, amount,
+  currency}. status MUST be one of "draft" | "open" | "paid" |
+  "past-due" | "void"; unknown values fall back to a neutral badge.
+
+  Spec: .claude/docs/specs/implementation-ready/SPEC-008-invoice-history-table.md.
+
+# Per ADR-0027 — composites do NOT auto-import the primitives they
+# stamp in connected()/render(). The consumer (or this primitive's
+# .html demo shell) must explicitly side-effect-import each one.
+composes:
+  - table-ui
+  - table-toolbar-ui
+  - badge-ui
+  - button-ui
+  - empty-state-ui
+  - pagination-ui
+
+props:
+  invoices:
+    description: |
+      Array of invoice records. Source of truth for the rendered rows.
+      Shape per record: {id, number, status, issuedAt, dueAt, amount,
+      currency?}. status must be one of "draft" | "open" | "paid" |
+      "past-due" | "void". Empty array renders the empty-state.
+    type: array
+    default: []
+    dynamic: true
+    required: true
+
+  currency:
+    description: |
+      Default ISO 4217 currency code for amount formatting. Overridable
+      per-row via invoices[].currency.
+    type: string
+    default: "USD"
+    reflect: true
+
+  density:
+    description: |
+      Row density, forwarded to <table-ui>. `compact` for dense lists,
+      `standard` for default rows, `comfortable` for spacious rows.
+    type: string
+    default: standard
+    enum:
+      - compact
+      - standard
+      - comfortable
+    reflect: true
+
+  loading:
+    description: |
+      Forwarded to <table-ui> — renders skeleton rows instead of data
+      while a fetch is in flight.
+    type: boolean
+    default: false
+    reflect: true
+    dynamic: true
+
+  selectable:
+    description: |
+      When set, enables row selection via a leading checkbox column on
+      the underlying <table-ui> (bulk-action surface).
+    type: boolean
+    default: false
+    reflect: true
+
+  hrefPattern:
+    description: |
+      URL template for row-click navigation. The literal `{number}` is
+      replaced with the invoice's number on click. Defaults to
+      `/invoices/{number}`.
+    type: string
+    default: "/invoices/{number}"
+    reflect: true
+    attribute: href-pattern
+
+  paginate:
+    description: |
+      Rows per page, forwarded to <table-ui>. 0 = show all rows.
+    type: number
+    default: 25
+    reflect: true
+
+  exportable:
+    description: |
+      When set, the default toolbar carries an "Export CSV" button.
+      Consumers overriding the toolbar via slot="toolbar" can omit
+      this and stamp their own export affordance.
+    type: boolean
+    default: true
+    reflect: true
+
+  locale:
+    description: |
+      Locale for Intl.NumberFormat (amount) and Intl.DateTimeFormat
+      (issuedAt / dueAt). Defaults to document.documentElement.lang
+      (or "en-US" when absent).
+    type: string
+    default: ""
+
+  filter:
+    description: |
+      Active status filter — narrows visible rows to a single status
+      bucket. Empty string = show all. Mirrors the toolbar chip-group
+      selection state.
+    type: string
+    default: ""
+    reflect: true
+    enum:
+      - ""
+      - draft
+      - open
+      - paid
+      - past-due
+      - void
+    dynamic: true
+
+  data-stream-src:
+    description: |
+      Optional endpoint returning the `invoices` array (universal
+      data-stream-* trait). On successful load, `invoices` is replaced
+      and a `load` event fires; on failure an `error` event fires.
+    type: string
+    default: ""
+    attribute: data-stream-src
+
+events:
+  invoice-row-click:
+    description: |
+      Fired when an invoice row is activated (mouse click or keyboard
+      Enter / Space). Listener can preventDefault() to suppress the
+      default `window.location.assign(href)` navigation. Bubbles.
+    detail:
+      invoice:
+        type: object
+        description: The invoice record under the clicked row.
+      href:
+        type: string
+        description: Resolved navigation URL.
+
+  invoice-selection-change:
+    description: |
+      Fired when row selection changes (only when `selectable` is set).
+      Bubbles.
+    detail:
+      selected:
+        type: array
+        description: Array of selected invoice records.
+
+  invoice-filter-change:
+    description: |
+      Fired when the status filter changes via the toolbar chip group.
+      Bubbles.
+    detail:
+      filter:
+        type: string
+        description: New status filter value (empty string = all).
+        enum:
+          - ""
+          - draft
+          - open
+          - paid
+          - past-due
+          - void
+      previous:
+        type: string
+        description: Previous filter value.
+
+  invoice-export:
+    description: |
+      Fired when the default "Export CSV" toolbar button is pressed.
+      Detail carries the generated blob; consumers may preventDefault
+      to suppress the default download. Bubbles.
+    detail:
+      blob:
+        type: object
+        description: The generated text/csv Blob.
+      rowCount:
+        type: integer
+        description: Number of rows in the export.
+
+  load:
+    description: |
+      Fired when `data-stream-src` finishes a successful fetch and
+      `invoices` is populated. Bubbles.
+    detail:
+      count:
+        type: integer
+        description: Number of invoices loaded.
+
+  error:
+    description: |
+      Fired when a `data-stream-src` fetch fails. Bubbles.
+    detail:
+      reason:
+        type: string
+        description: One of `fetch-failed`.
+
+slots:
+  toolbar:
+    description: |
+      Optional pre-table action toolbar — overrides the default
+      <table-toolbar-ui> + export button stamp. Use when the host
+      surface needs custom actions (e.g. "New invoice", "Reconcile").
+
+  empty:
+    description: |
+      Custom empty-state content when `invoices` is empty. Falls back
+      to a default <empty-state-ui icon="receipt"> when omitted.
+
+states:
+  - name: idle
+    description: Default — rows rendered, ready for interaction.
+  - name: loading
+    description: A `data-stream-src` fetch is in flight.
+    attribute: loading
+  - name: empty
+    description: No invoices to render (computed from invoices.length).
+    attribute: empty
+  - name: error
+    description: Last `data-stream-src` fetch failed.
+    attribute: error
+
+traits: []
+
+tokens:
+  --invoice-history-bg:
+    description: Host background. Defaults to transparent.
+    default: transparent
+  --invoice-history-gap:
+    description: Vertical gap between toolbar / table / pagination regions.
+    default: var(--a-space-3)
+  --invoice-history-row-min-height:
+    description: Forwarded as `--table-row-h` to <table-ui>; row minimum height.
+    default: var(--table-row-h, 3rem)
+  --invoice-history-toolbar-gap:
+    description: Gap between toolbar clusters (title · filter chips · export).
+    default: var(--a-space-3)
+  --invoice-history-amount-font:
+    description: Font family for tabular amounts; defaults to the mono stack.
+    default: var(--a-font-mono)
+  --invoice-history-amount-fg:
+    description: Amount cell foreground.
+    default: var(--a-fg-strong, var(--a-fg))
+  --invoice-history-date-fg:
+    description: Secondary metadata (issued / due dates) foreground.
+    default: var(--a-fg-muted)
+  --invoice-history-filter-gap:
+    description: Gap between status-filter chips.
+    default: var(--a-space-2)
+
+requiredIcons:
+  - download-simple
+  - receipt
+  - magnifying-glass
+
+a2ui:
+  rules:
+    - >-
+      InvoiceHistory.invoices MUST be a non-empty array on commit. Empty
+      arrays render the empty-state (no rows).
+    - >-
+      invoices[].status MUST be one of "draft" | "open" | "paid" |
+      "past-due" | "void". Unknown values fall back to a neutral
+      badge variant.
+    - >-
+      InvoiceHistory MUST NOT receive a `columns` prop — columns are
+      owned by the composite. Consumers needing custom columns should
+      compose <table-ui> directly with their own column array.
+    - >-
+      `hrefPattern` is a string template with `{number}` interpolation.
+      Consumers needing dynamic resolution (query-strings, function-
+      based routes) should preventDefault on `invoice-row-click` and
+      route themselves.
+    - >-
+      Pair with `InvoiceDetail` (SPEC-007) at the route resolved by
+      `hrefPattern` so the row-click destination exists.
+
+anti_patterns:
+  - wrong: |
+      <table-ui sortable>
+        <col-def key="number" label="Invoice"></col-def>
+        <col-def key="status" label="Status"></col-def>
+      </table-ui>
+    why: |
+      Hand-rolled billing list. Reinvents the canonical composite,
+      drifts on status-badge mapping, currency formatting, and
+      date format.
+    fix: |
+      <invoice-history-ui .invoices="${rows}"></invoice-history-ui>
+  - wrong: |
+      <invoice-history-ui .columns="${customColumns}"
+                          .invoices="${rows}"></invoice-history-ui>
+    why: |
+      Columns are owned by the composite. Custom columns belong on a
+      different <table-ui> composition.
+    fix: |
+      <invoice-history-ui .invoices="${rows}"></invoice-history-ui>
+
+examples:
+  - name: canonical
+    description: 6-column billing list with status badges, currency formatting, and pagination.
+    a2ui: |
+      [
+        {
+          "id": "inv-hist-1",
+          "component": "InvoiceHistory",
+          "currency": "USD",
+          "paginate": 25,
+          "invoices": [
+            {"id":"i1","number":"INV-001234","status":"paid","issuedAt":"2026-05-01","dueAt":"2026-05-15","amount":24.50},
+            {"id":"i2","number":"INV-001235","status":"open","issuedAt":"2026-05-08","dueAt":"2026-05-22","amount":24.50},
+            {"id":"i3","number":"INV-001236","status":"past-due","issuedAt":"2026-04-15","dueAt":"2026-04-29","amount":24.50}
+          ]
+        }
+      ]
+  - name: streamed
+    description: Server-streamed invoices via data-stream-src.
+    a2ui: |
+      [
+        {
+          "id": "inv-hist-stream",
+          "component": "InvoiceHistory",
+          "data-stream-src": "/api/invoices",
+          "currency": "USD",
+          "paginate": 50
+        }
+      ]
+
+keywords:
+  - invoice
+  - invoices
+  - billing
+  - invoice-history
+  - invoice-list
+  - payments-history
+  - receipt
+  - receipts
+  - statement
+  - statements
+  - subscription
+  - charges
+  - past-due
+  - paid
+  - billing-list
+  - billing-table
+  - download-invoice
+  - export-invoices
+
+synonyms:
+  invoice:
+    - bill
+    - statement
+    - receipt
+  billing:
+    - invoice
+    - payment
+    - subscription
+  statement:
+    - invoice
+    - bill
+  receipts:
+    - invoices
+    - billing
+  history:
+    - log
+    - audit
+    - record
+    - timeline
+
+related:
+  - Table
+  - TableToolbar
+  - Badge
+  - Button
+  - EmptyState
+  - Pagination