@adia-ai/web-modules 0.8.36 → 0.8.37

package/billing/invoice-detail/invoice-detail.yaml

@@ -0,0 +1,411 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIInvoiceDetail
+tag: invoice-detail-ui
+status: experimental
+component: InvoiceDetail
+category: container
+version: 1
+description: |
+  Module-tier page composite that renders a single invoice — header
+  (number + status badge + dates), line-items table, totals block,
+  customer + remit-to blocks, and a slot-driven action toolbar.
+  The canonical invoice layout shared by billing-enabled products
+  so totals math, status-badge color mapping, and action-toolbar
+  order do not drift across surfaces.
+
+  Data-driven via the `invoice` property OR a `data-stream-src`
+  endpoint. The composite stamps a six-region skeleton once on
+  first connect — header · meta · parties · lines · totals ·
+  footer — then mutates per-region nodes via id-keyed in-place
+  diff on every property change. The status badge color maps
+  from `invoice.status` (paid → success, past-due → warning,
+  void → muted, open/draft → default). Action buttons are
+  consumer-slotted into `header-actions` per spec OD-002 (always
+  slot, never stamp a default toolbar).
+
+  Print-friendly: an internal `@media print` branch hides the
+  action toolbar + zeroes the page padding. The composite is a
+  display surface — extends UIElement, not UIFormElement.
+
+  Spec: .claude/docs/specs/implementation-ready/SPEC-007-invoice-detail-page.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:
+  - card-ui
+  - table-ui
+  - stat-ui
+  - tag-ui
+  - button-ui
+  - text-ui
+  - icon-ui
+  - empty-state-ui
+
+props:
+  invoice:
+    description: |
+      The invoice record. Source of truth for the rendered page.
+      Shape: {number, status, issuedAt, dueAt, customer:{name,email},
+      remitTo?:{name,address?}, lines:[{description,qty,unitAmount,
+      amount}], subtotal, tax, discount?, total, currency,
+      notes?:string}. Null + no data-stream-src renders the empty
+      state.
+    type: object
+    default: null
+    dynamic: true
+    required: true
+
+  status:
+    description: |
+      Mirrors invoice.status. Drives the status badge `variant`
+      mapping (paid → success, past-due → warning, void → muted,
+      open/draft → default). When set independently of `invoice`,
+      the host status reflection wins for CSS — useful when the
+      host wraps an invoice without a status field.
+    type: string
+    default: "draft"
+    enum:
+      - draft
+      - open
+      - paid
+      - past-due
+      - void
+    reflect: true
+    dynamic: true
+
+  currency:
+    description: |
+      ISO 4217 currency code for amount formatting via
+      Intl.NumberFormat. Overridable per-record via invoice.currency.
+    type: string
+    default: "USD"
+    reflect: true
+
+  density:
+    description: |
+      Line-items table row density. `compact` for tightly-packed
+      invoices with many line items; `standard` for typical invoices.
+      Forwarded to the embedded <table-ui density>.
+    type: string
+    default: "standard"
+    enum:
+      - compact
+      - standard
+    reflect: true
+
+  loading:
+    description: |
+      Renders skeleton placeholders for header + line-items + totals
+      while a data-stream-src fetch is in flight. Sets aria-busy
+      on the host. Data updates suppressed while [loading] is set.
+    type: boolean
+    default: false
+    reflect: true
+    dynamic: true
+
+  printable:
+    description: |
+      Includes the @media print branch — hides the action toolbar
+      and zeroes page padding so the printed output is invoice-only.
+      Set [printable] to false on screens where the invoice is
+      embedded inside a larger surface and printing should not be
+      a first-class action.
+    type: boolean
+    default: true
+    reflect: true
+
+  locale:
+    description: |
+      Locale for Intl.NumberFormat (amounts) and Intl.DateTimeFormat
+      (issued/due). Defaults to document.documentElement.lang (or
+      "en-US" when absent).
+    type: string
+    default: ""
+
+  data-stream-src:
+    description: |
+      Optional endpoint returning the invoice record (universal
+      data-stream-* trait). On successful load, `invoice` is
+      replaced and a `load` event fires; on failure an `error`
+      event fires.
+    type: string
+    default: ""
+    attribute: data-stream-src
+
+events:
+  invoice-action:
+    description: |
+      Fired when a header-action button carrying
+      [data-invoice-action] is activated. Consumers wire this to
+      download / send / pay / void flows. Bubbles.
+    detail:
+      action:
+        type: string
+        description: The data-invoice-action value (download, send, pay, etc.).
+      invoiceNumber:
+        type: string
+        description: invoice.number at the time of activation.
+
+  line-item-click:
+    description: |
+      Fired when a line-item row is clicked. Bubbles.
+    detail:
+      index:
+        type: integer
+        description: 0-based row index within invoice.lines.
+      lineItem:
+        type: object
+        description: The clicked invoice.lines[index] record.
+
+  load:
+    description: |
+      Fired when a data-stream-src fetch resolves and the invoice
+      record is populated. Bubbles.
+    detail:
+      invoiceNumber:
+        type: string
+        description: The loaded invoice.number.
+
+  error:
+    description: |
+      Fired when a data-stream-src fetch fails OR when the host is
+      asked to print but window.print is unavailable. Bubbles.
+    detail:
+      reason:
+        type: string
+        description: One of `fetch-failed`, `print-unavailable`.
+
+slots:
+  header-actions:
+    description: |
+      Action toolbar slotted into the top-right of the invoice
+      header — Download, Send, Pay, etc. Consumer-owned per
+      SPEC-007 OD-002 (the composite NEVER stamps a default
+      toolbar; action sets vary too much across products).
+      Buttons carrying [data-invoice-action] dispatch the host's
+      `invoice-action` event on activation.
+
+  customer-block:
+    description: |
+      Override the default customer block. When unset, the composite
+      renders a default block from invoice.customer.
+
+  remit-to-block:
+    description: |
+      Override the default remit-to block. When unset, the composite
+      renders a default block from invoice.remitTo if present.
+
+  footer:
+    description: |
+      Optional content below the totals — payment instructions,
+      terms, fine print.
+
+states:
+  - name: idle
+    description: Default — invoice rendered, ready for interaction.
+  - name: loading
+    description: A data-stream-src fetch is in flight.
+    attribute: loading
+  - name: empty
+    description: No invoice + no data-stream-src.
+    attribute: empty
+  - name: error
+    description: Last data-stream-src fetch failed.
+    attribute: error
+
+traits: []
+
+tokens:
+  --invoice-detail-bg:
+    description: Host page background. Defaults to transparent.
+    default: transparent
+  --invoice-detail-page-padding:
+    description: Inset around the invoice content area.
+    default: var(--a-space-5)
+  --invoice-detail-section-gap:
+    description: Vertical gap between header, parties, lines, totals.
+    default: var(--a-space-5)
+  --invoice-detail-totals-width:
+    description: |
+      Width of the right-aligned totals stack. Clamps to 100% on
+      narrow viewports.
+    default: min(360px, 100%)
+  --invoice-detail-status-badge-radius:
+    description: Status badge corner radius.
+    default: var(--a-radius-md)
+  --invoice-detail-meta-fg:
+    description: Color for the secondary header metadata (issued / due).
+    default: var(--a-fg-muted)
+  --invoice-detail-amount-fg:
+    description: Color for monetary amounts in the totals stack.
+    default: var(--a-fg)
+  --invoice-detail-total-size:
+    description: Font size for the grand total line.
+    default: var(--a-text-2xl, 1.5rem)
+  --invoice-detail-total-weight:
+    description: Font weight for the grand total line.
+    default: var(--a-weight-bold, 700)
+  --invoice-detail-line-amount-align:
+    description: |
+      Text-align for the rightmost amount column in the lines table.
+      `end` for typical right-aligned numerics.
+    default: end
+
+requiredIcons:
+  - receipt
+
+a2ui:
+  rules:
+    - >-
+      InvoiceDetail MUST set `invoice` OR `data-stream-src`. Neither
+      produces the empty state but cannot be the submission state for
+      a billing surface.
+    - >-
+      invoice.lines[] MUST contain at least one row with `description`,
+      `qty`, `unitAmount`, `amount`. Empty lines arrays render the
+      lines table empty-state row, not the host empty state.
+    - >-
+      invoice.total MUST equal subtotal + tax − (discount or 0). The
+      composite renders the host-supplied total verbatim; consumers
+      are authoritative on rounding rules per locale (SPEC-007 OD-001).
+    - >-
+      invoice.status MUST be one of draft / open / paid / past-due /
+      void. Unknown statuses render the default badge variant + a
+      one-shot console.warn.
+    - >-
+      InvoiceDetail MUST NOT be nested inside Modal or Drawer.
+      Invoices are routes, not modals — Modal traps focus + clips
+      on long content; the composite is designed for full-page
+      layout. Use `<a href="/invoices/{number}">` instead.
+    - >-
+      Slot ALL header actions explicitly via `slot="header-actions"`
+      — the composite NEVER stamps a default toolbar (SPEC-007
+      OD-002). Action sets vary across products; default is too
+      opinionated.
+
+anti_patterns:
+  - wrong: |
+      {"component": "InvoiceDetail", "lines": [...]}
+    why: |
+      Line items belong on `invoice.lines`, not the host. Without
+      the wrapping `invoice` object, totals + currency are unwired
+      and the composite renders the empty state.
+    fix: |
+      {"component": "InvoiceDetail", "invoice":
+        {"lines": [...], "subtotal": 24, "total": 24.5, "currency": "USD"}}
+  - wrong: |
+      {"component": "Modal", "children":
+        [{"component": "InvoiceDetail", "invoice": {...}}]}
+    why: |
+      Invoices are routes, not modals. Modal traps focus + clips
+      on long content; the composite is designed for full-page
+      layout.
+    fix: |
+      Open the invoice via <a href="/invoices/INV-001234"> route
+      navigation; render the InvoiceDetail composite on that route.
+  - wrong: |
+      <invoice-detail-ui status="settled"></invoice-detail-ui>
+    why: |
+      `settled` is not in the status enum. Unknown statuses fall
+      back to the default badge variant; the consumer surface
+      loses the semantic color mapping.
+    fix: |
+      <invoice-detail-ui status="paid"></invoice-detail-ui>
+
+examples:
+  - name: paid-invoice
+    description: A paid invoice with two line items + slotted actions.
+    a2ui: |
+      [
+        {
+          "id": "inv-paid",
+          "component": "InvoiceDetail",
+          "status": "paid",
+          "currency": "USD",
+          "invoice": {
+            "number": "INV-001234",
+            "status": "paid",
+            "issuedAt": "2026-05-01",
+            "dueAt": "2026-05-15",
+            "customer": {"name": "Acme Co.", "email": "billing@acme.test"},
+            "lines": [
+              {"description": "Pro plan — May", "qty": 1, "unitAmount": 24.00, "amount": 24.00},
+              {"description": "Add-on — Audit log retention", "qty": 1, "unitAmount": 0.50, "amount": 0.50}
+            ],
+            "subtotal": 24.50,
+            "tax": 0,
+            "total": 24.50,
+            "currency": "USD"
+          },
+          "children": ["btn-download"]
+        },
+        {"id": "btn-download", "component": "Button",
+         "text": "Download", "slot": "header-actions"}
+      ]
+  - name: open-invoice
+    description: Open invoice awaiting payment + Pay CTA.
+    a2ui: |
+      [
+        {
+          "id": "inv-open",
+          "component": "InvoiceDetail",
+          "status": "open",
+          "currency": "USD",
+          "invoice": {
+            "number": "INV-001235",
+            "status": "open",
+            "issuedAt": "2026-05-10",
+            "dueAt": "2026-05-24",
+            "customer": {"name": "Globex Corp.", "email": "ap@globex.test"},
+            "lines": [
+              {"description": "Team seats × 5", "qty": 5, "unitAmount": 10.00, "amount": 50.00}
+            ],
+            "subtotal": 50.00,
+            "tax": 5.00,
+            "total": 55.00,
+            "currency": "USD"
+          },
+          "children": ["btn-pay-open"]
+        },
+        {"id": "btn-pay-open", "component": "Button",
+         "text": "Pay $55", "variant": "primary",
+         "slot": "header-actions"}
+      ]
+
+keywords:
+  - invoice
+  - invoice-detail
+  - billing
+  - receipt
+  - bill
+  - statement
+  - payment
+  - line-items
+  - charges
+  - totals
+  - paid
+  - past-due
+  - void
+
+synonyms:
+  invoice:
+    - bill
+    - receipt
+    - statement
+  payment:
+    - charge
+    - billing
+  line-items:
+    - charges
+    - entries
+
+related:
+  - Card
+  - Table
+  - Stat
+  - Tag
+  - Button
+  - EmptyState
+  - PlanPicker