@adia-ai/web-modules 0.8.35 → 0.8.37

package/billing/invoice-detail/invoice-detail.a2ui.json

@@ -0,0 +1,276 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/InvoiceDetail.json",
+  "title": "InvoiceDetail",
+  "description": "Module-tier page composite that renders a single invoice — header\n(number + status badge + dates), line-items table, totals block,\ncustomer + remit-to blocks, and a slot-driven action toolbar.\nThe canonical invoice layout shared by billing-enabled products\nso totals math, status-badge color mapping, and action-toolbar\norder do not drift across surfaces.\n\nData-driven via the `invoice` property OR a `data-stream-src`\nendpoint. The composite stamps a six-region skeleton once on\nfirst connect — header · meta · parties · lines · totals ·\nfooter — then mutates per-region nodes via id-keyed in-place\ndiff on every property change. The status badge color maps\nfrom `invoice.status` (paid → success, past-due → warning,\nvoid → muted, open/draft → default). Action buttons are\nconsumer-slotted into `header-actions` per spec OD-002 (always\nslot, never stamp a default toolbar).\n\nPrint-friendly: an internal `@media print` branch hides the\naction toolbar + zeroes the page padding. The composite is a\ndisplay surface — extends UIElement, not UIFormElement.\n\nSpec: .claude/docs/specs/implementation-ready/SPEC-007-invoice-detail-page.md.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "InvoiceDetail"
+    },
+    "currency": {
+      "description": "ISO 4217 currency code for amount formatting via\nIntl.NumberFormat. Overridable per-record via invoice.currency.\n",
+      "type": "string",
+      "default": "USD"
+    },
+    "data-stream-src": {
+      "description": "Optional endpoint returning the invoice record (universal\ndata-stream-* trait). On successful load, `invoice` is\nreplaced and a `load` event fires; on failure an `error`\nevent fires.\n",
+      "type": "string",
+      "default": ""
+    },
+    "density": {
+      "description": "Line-items table row density. `compact` for tightly-packed\ninvoices with many line items; `standard` for typical invoices.\nForwarded to the embedded <table-ui density>.\n",
+      "type": "string",
+      "enum": [
+        "compact",
+        "standard"
+      ],
+      "default": "standard"
+    },
+    "invoice": {
+      "description": "The invoice record. Source of truth for the rendered page.\nShape: {number, status, issuedAt, dueAt, customer:{name,email},\nremitTo?:{name,address?}, lines:[{description,qty,unitAmount,\namount}], subtotal, tax, discount?, total, currency,\nnotes?:string}. Null + no data-stream-src renders the empty\nstate.\n",
+      "type": "object",
+      "default": null
+    },
+    "loading": {
+      "description": "Renders skeleton placeholders for header + line-items + totals\nwhile a data-stream-src fetch is in flight. Sets aria-busy\non the host. Data updates suppressed while [loading] is set.\n",
+      "$ref": "common_types.json#/$defs/DynamicBoolean"
+    },
+    "locale": {
+      "description": "Locale for Intl.NumberFormat (amounts) and Intl.DateTimeFormat\n(issued/due). Defaults to document.documentElement.lang (or\n\"en-US\" when absent).\n",
+      "type": "string",
+      "default": ""
+    },
+    "printable": {
+      "description": "Includes the @media print branch — hides the action toolbar\nand zeroes page padding so the printed output is invoice-only.\nSet [printable] to false on screens where the invoice is\nembedded inside a larger surface and printing should not be\na first-class action.\n",
+      "type": "boolean",
+      "default": true
+    },
+    "status": {
+      "description": "Mirrors invoice.status. Drives the status badge `variant`\nmapping (paid → success, past-due → warning, void → muted,\nopen/draft → default). When set independently of `invoice`,\nthe host status reflection wins for CSS — useful when the\nhost wraps an invoice without a status field.\n",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    }
+  },
+  "required": [
+    "component",
+    "invoice"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "{\"component\": \"InvoiceDetail\", \"invoice\":\n  {\"lines\": [...], \"subtotal\": 24, \"total\": 24.5, \"currency\": \"USD\"}}\n",
+        "why": "Line items belong on `invoice.lines`, not the host. Without\nthe wrapping `invoice` object, totals + currency are unwired\nand the composite renders the empty state.\n",
+        "wrong": "{\"component\": \"InvoiceDetail\", \"lines\": [...]}\n"
+      },
+      {
+        "fix": "Open the invoice via <a href=\"/invoices/INV-001234\"> route\nnavigation; render the InvoiceDetail composite on that route.\n",
+        "why": "Invoices are routes, not modals. Modal traps focus + clips\non long content; the composite is designed for full-page\nlayout.\n",
+        "wrong": "{\"component\": \"Modal\", \"children\":\n  [{\"component\": \"InvoiceDetail\", \"invoice\": {...}}]}\n"
+      },
+      {
+        "fix": "<invoice-detail-ui status=\"paid\"></invoice-detail-ui>\n",
+        "why": "`settled` is not in the status enum. Unknown statuses fall\nback to the default badge variant; the consumer surface\nloses the semantic color mapping.\n",
+        "wrong": "<invoice-detail-ui status=\"settled\"></invoice-detail-ui>\n"
+      }
+    ],
+    "category": "container",
+    "composes": [
+      "card-ui",
+      "table-ui",
+      "stat-ui",
+      "tag-ui",
+      "button-ui",
+      "text-ui",
+      "icon-ui",
+      "empty-state-ui"
+    ],
+    "events": {
+      "error": {
+        "description": "Fired when a data-stream-src fetch fails OR when the host is\nasked to print but window.print is unavailable. Bubbles.\n",
+        "detail": {
+          "reason": {
+            "description": "One of `fetch-failed`, `print-unavailable`.",
+            "type": "string"
+          }
+        }
+      },
+      "invoice-action": {
+        "description": "Fired when a header-action button carrying\n[data-invoice-action] is activated. Consumers wire this to\ndownload / send / pay / void flows. Bubbles.\n",
+        "detail": {
+          "action": {
+            "description": "The data-invoice-action value (download, send, pay, etc.).",
+            "type": "string"
+          },
+          "invoiceNumber": {
+            "description": "invoice.number at the time of activation.",
+            "type": "string"
+          }
+        }
+      },
+      "line-item-click": {
+        "description": "Fired when a line-item row is clicked. Bubbles.\n",
+        "detail": {
+          "index": {
+            "description": "0-based row index within invoice.lines.",
+            "type": "integer"
+          },
+          "lineItem": {
+            "description": "The clicked invoice.lines[index] record.",
+            "type": "object"
+          }
+        }
+      },
+      "load": {
+        "description": "Fired when a data-stream-src fetch resolves and the invoice\nrecord is populated. Bubbles.\n",
+        "detail": {
+          "invoiceNumber": {
+            "description": "The loaded invoice.number.",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "A paid invoice with two line items + slotted actions.",
+        "a2ui": "[\n  {\n    \"id\": \"inv-paid\",\n    \"component\": \"InvoiceDetail\",\n    \"status\": \"paid\",\n    \"currency\": \"USD\",\n    \"invoice\": {\n      \"number\": \"INV-001234\",\n      \"status\": \"paid\",\n      \"issuedAt\": \"2026-05-01\",\n      \"dueAt\": \"2026-05-15\",\n      \"customer\": {\"name\": \"Acme Co.\", \"email\": \"billing@acme.test\"},\n      \"lines\": [\n        {\"description\": \"Pro plan — May\", \"qty\": 1, \"unitAmount\": 24.00, \"amount\": 24.00},\n        {\"description\": \"Add-on — Audit log retention\", \"qty\": 1, \"unitAmount\": 0.50, \"amount\": 0.50}\n      ],\n      \"subtotal\": 24.50,\n      \"tax\": 0,\n      \"total\": 24.50,\n      \"currency\": \"USD\"\n    },\n    \"children\": [\"btn-download\"]\n  },\n  {\"id\": \"btn-download\", \"component\": \"Button\",\n   \"text\": \"Download\", \"slot\": \"header-actions\"}\n]\n",
+        "name": "paid-invoice"
+      },
+      {
+        "description": "Open invoice awaiting payment + Pay CTA.",
+        "a2ui": "[\n  {\n    \"id\": \"inv-open\",\n    \"component\": \"InvoiceDetail\",\n    \"status\": \"open\",\n    \"currency\": \"USD\",\n    \"invoice\": {\n      \"number\": \"INV-001235\",\n      \"status\": \"open\",\n      \"issuedAt\": \"2026-05-10\",\n      \"dueAt\": \"2026-05-24\",\n      \"customer\": {\"name\": \"Globex Corp.\", \"email\": \"ap@globex.test\"},\n      \"lines\": [\n        {\"description\": \"Team seats × 5\", \"qty\": 5, \"unitAmount\": 10.00, \"amount\": 50.00}\n      ],\n      \"subtotal\": 50.00,\n      \"tax\": 5.00,\n      \"total\": 55.00,\n      \"currency\": \"USD\"\n    },\n    \"children\": [\"btn-pay-open\"]\n  },\n  {\"id\": \"btn-pay-open\", \"component\": \"Button\",\n   \"text\": \"Pay $55\", \"variant\": \"primary\",\n   \"slot\": \"header-actions\"}\n]\n",
+        "name": "open-invoice"
+      }
+    ],
+    "keywords": [
+      "invoice",
+      "invoice-detail",
+      "billing",
+      "receipt",
+      "bill",
+      "statement",
+      "payment",
+      "line-items",
+      "charges",
+      "totals",
+      "paid",
+      "past-due",
+      "void"
+    ],
+    "name": "UIInvoiceDetail",
+    "related": [
+      "Card",
+      "Table",
+      "Stat",
+      "Tag",
+      "Button",
+      "EmptyState",
+      "PlanPicker"
+    ],
+    "slots": {
+      "customer-block": {
+        "description": "Override the default customer block. When unset, the composite\nrenders a default block from invoice.customer.\n"
+      },
+      "footer": {
+        "description": "Optional content below the totals — payment instructions,\nterms, fine print.\n"
+      },
+      "header-actions": {
+        "description": "Action toolbar slotted into the top-right of the invoice\nheader — Download, Send, Pay, etc. Consumer-owned per\nSPEC-007 OD-002 (the composite NEVER stamps a default\ntoolbar; action sets vary too much across products).\nButtons carrying [data-invoice-action] dispatch the host's\n`invoice-action` event on activation.\n"
+      },
+      "remit-to-block": {
+        "description": "Override the default remit-to block. When unset, the composite\nrenders a default block from invoice.remitTo if present.\n"
+      }
+    },
+    "states": [
+      {
+        "description": "Default — invoice rendered, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "A data-stream-src fetch is in flight.",
+        "attribute": "loading",
+        "name": "loading"
+      },
+      {
+        "description": "No invoice + no data-stream-src.",
+        "attribute": "empty",
+        "name": "empty"
+      },
+      {
+        "description": "Last data-stream-src fetch failed.",
+        "attribute": "error",
+        "name": "error"
+      }
+    ],
+    "status": "experimental",
+    "synonyms": {
+      "invoice": [
+        "bill",
+        "receipt",
+        "statement"
+      ],
+      "line-items": [
+        "charges",
+        "entries"
+      ],
+      "payment": [
+        "charge",
+        "billing"
+      ]
+    },
+    "tag": "invoice-detail-ui",
+    "tokens": {
+      "--invoice-detail-amount-fg": {
+        "description": "Color for monetary amounts in the totals stack.",
+        "default": "var(--a-fg)"
+      },
+      "--invoice-detail-bg": {
+        "description": "Host page background. Defaults to transparent.",
+        "default": "transparent"
+      },
+      "--invoice-detail-line-amount-align": {
+        "description": "Text-align for the rightmost amount column in the lines table.\n`end` for typical right-aligned numerics.\n",
+        "default": "end"
+      },
+      "--invoice-detail-meta-fg": {
+        "description": "Color for the secondary header metadata (issued / due).",
+        "default": "var(--a-fg-muted)"
+      },
+      "--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-status-badge-radius": {
+        "description": "Status badge corner radius.",
+        "default": "var(--a-radius-md)"
+      },
+      "--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-totals-width": {
+        "description": "Width of the right-aligned totals stack. Clamps to 100% on\nnarrow viewports.\n",
+        "default": "min(360px, 100%)"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}