@adia-ai/web-modules 0.8.35 → 0.8.37

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

@@ -0,0 +1,315 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/InvoiceHistory.json",
+  "title": "InvoiceHistory",
+  "description": "Canonical billing-list composite — a pre-configured <table-ui> with\ninvoice-shaped columns (number, issued, due, amount, status, actions),\nstatus-badge cell renderer (paid/open/past-due/void/draft → semantic\nbadge variant), currency cell renderer, optional search + filter\nchips via <table-toolbar-ui>, and a row-click that navigates to the\ninvoice detail page.\n\nWraps <table-ui> with billing-shaped columns + cell renderers + a\nCSV-export toolbar. Consumer passes invoices[]; the composite owns\ncolumn shape, status-to-badge mapping, currency formatting, date\nformatting, and navigation. Sibling to SPEC-007 (invoice detail).\n\nEach invoice record: {id, number, status, issuedAt, dueAt, amount,\ncurrency}. status MUST be one of \"draft\" | \"open\" | \"paid\" |\n\"past-due\" | \"void\"; unknown values fall back to a neutral badge.\n\nSpec: .claude/docs/specs/implementation-ready/SPEC-008-invoice-history-table.md.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "InvoiceHistory"
+    },
+    "currency": {
+      "description": "Default ISO 4217 currency code for amount formatting. Overridable\nper-row via invoices[].currency.\n",
+      "type": "string",
+      "default": "USD"
+    },
+    "data-stream-src": {
+      "description": "Optional endpoint returning the `invoices` array (universal\ndata-stream-* trait). On successful load, `invoices` is replaced\nand a `load` event fires; on failure an `error` event fires.\n",
+      "type": "string",
+      "default": ""
+    },
+    "density": {
+      "description": "Row density, forwarded to <table-ui>. `compact` for dense lists,\n`standard` for default rows, `comfortable` for spacious rows.\n",
+      "type": "string",
+      "enum": [
+        "compact",
+        "standard",
+        "comfortable"
+      ],
+      "default": "standard"
+    },
+    "exportable": {
+      "description": "When set, the default toolbar carries an \"Export CSV\" button.\nConsumers overriding the toolbar via slot=\"toolbar\" can omit\nthis and stamp their own export affordance.\n",
+      "type": "boolean",
+      "default": true
+    },
+    "filter": {
+      "description": "Active status filter — narrows visible rows to a single status\nbucket. Empty string = show all. Mirrors the toolbar chip-group\nselection state.\n",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    },
+    "hrefPattern": {
+      "description": "URL template for row-click navigation. The literal `{number}` is\nreplaced with the invoice's number on click. Defaults to\n`/invoices/{number}`.\n",
+      "type": "string",
+      "default": "/invoices/{number}"
+    },
+    "invoices": {
+      "description": "Array of invoice records. Source of truth for the rendered rows.\nShape per record: {id, number, status, issuedAt, dueAt, amount,\ncurrency?}. status must be one of \"draft\" | \"open\" | \"paid\" |\n\"past-due\" | \"void\". Empty array renders the empty-state.\n",
+      "$ref": "common_types.json#/$defs/DynamicStringList"
+    },
+    "loading": {
+      "description": "Forwarded to <table-ui> — renders skeleton rows instead of data\nwhile a fetch is in flight.\n",
+      "$ref": "common_types.json#/$defs/DynamicBoolean"
+    },
+    "locale": {
+      "description": "Locale for Intl.NumberFormat (amount) and Intl.DateTimeFormat\n(issuedAt / dueAt). Defaults to document.documentElement.lang\n(or \"en-US\" when absent).\n",
+      "type": "string",
+      "default": ""
+    },
+    "paginate": {
+      "description": "Rows per page, forwarded to <table-ui>. 0 = show all rows.\n",
+      "type": "number",
+      "default": 25
+    },
+    "selectable": {
+      "description": "When set, enables row selection via a leading checkbox column on\nthe underlying <table-ui> (bulk-action surface).\n",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": [
+    "component",
+    "invoices"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "<invoice-history-ui .invoices=\"${rows}\"></invoice-history-ui>\n",
+        "why": "Hand-rolled billing list. Reinvents the canonical composite,\ndrifts on status-badge mapping, currency formatting, and\ndate format.\n",
+        "wrong": "<table-ui sortable>\n  <col-def key=\"number\" label=\"Invoice\"></col-def>\n  <col-def key=\"status\" label=\"Status\"></col-def>\n</table-ui>\n"
+      },
+      {
+        "fix": "<invoice-history-ui .invoices=\"${rows}\"></invoice-history-ui>\n",
+        "why": "Columns are owned by the composite. Custom columns belong on a\ndifferent <table-ui> composition.\n",
+        "wrong": "<invoice-history-ui .columns=\"${customColumns}\"\n                    .invoices=\"${rows}\"></invoice-history-ui>\n"
+      }
+    ],
+    "category": "display",
+    "composes": [
+      "table-ui",
+      "table-toolbar-ui",
+      "badge-ui",
+      "button-ui",
+      "empty-state-ui",
+      "pagination-ui"
+    ],
+    "events": {
+      "error": {
+        "description": "Fired when a `data-stream-src` fetch fails. Bubbles.\n",
+        "detail": {
+          "reason": {
+            "description": "One of `fetch-failed`.",
+            "type": "string"
+          }
+        }
+      },
+      "invoice-export": {
+        "description": "Fired when the default \"Export CSV\" toolbar button is pressed.\nDetail carries the generated blob; consumers may preventDefault\nto suppress the default download. Bubbles.\n",
+        "detail": {
+          "blob": {
+            "description": "The generated text/csv Blob.",
+            "type": "object"
+          },
+          "rowCount": {
+            "description": "Number of rows in the export.",
+            "type": "integer"
+          }
+        }
+      },
+      "invoice-filter-change": {
+        "description": "Fired when the status filter changes via the toolbar chip group.\nBubbles.\n",
+        "detail": {
+          "filter": {
+            "description": "New status filter value (empty string = all).",
+            "type": "string",
+            "enum": [
+              "",
+              "draft",
+              "open",
+              "paid",
+              "past-due",
+              "void"
+            ]
+          },
+          "previous": {
+            "description": "Previous filter value.",
+            "type": "string"
+          }
+        }
+      },
+      "invoice-row-click": {
+        "description": "Fired when an invoice row is activated (mouse click or keyboard\nEnter / Space). Listener can preventDefault() to suppress the\ndefault `window.location.assign(href)` navigation. Bubbles.\n",
+        "detail": {
+          "href": {
+            "description": "Resolved navigation URL.",
+            "type": "string"
+          },
+          "invoice": {
+            "description": "The invoice record under the clicked row.",
+            "type": "object"
+          }
+        }
+      },
+      "invoice-selection-change": {
+        "description": "Fired when row selection changes (only when `selectable` is set).\nBubbles.\n",
+        "detail": {
+          "selected": {
+            "description": "Array of selected invoice records.",
+            "type": "array"
+          }
+        }
+      },
+      "load": {
+        "description": "Fired when `data-stream-src` finishes a successful fetch and\n`invoices` is populated. Bubbles.\n",
+        "detail": {
+          "count": {
+            "description": "Number of invoices loaded.",
+            "type": "integer"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "6-column billing list with status badges, currency formatting, and pagination.",
+        "a2ui": "[\n  {\n    \"id\": \"inv-hist-1\",\n    \"component\": \"InvoiceHistory\",\n    \"currency\": \"USD\",\n    \"paginate\": 25,\n    \"invoices\": [\n      {\"id\":\"i1\",\"number\":\"INV-001234\",\"status\":\"paid\",\"issuedAt\":\"2026-05-01\",\"dueAt\":\"2026-05-15\",\"amount\":24.50},\n      {\"id\":\"i2\",\"number\":\"INV-001235\",\"status\":\"open\",\"issuedAt\":\"2026-05-08\",\"dueAt\":\"2026-05-22\",\"amount\":24.50},\n      {\"id\":\"i3\",\"number\":\"INV-001236\",\"status\":\"past-due\",\"issuedAt\":\"2026-04-15\",\"dueAt\":\"2026-04-29\",\"amount\":24.50}\n    ]\n  }\n]\n",
+        "name": "canonical"
+      },
+      {
+        "description": "Server-streamed invoices via data-stream-src.",
+        "a2ui": "[\n  {\n    \"id\": \"inv-hist-stream\",\n    \"component\": \"InvoiceHistory\",\n    \"data-stream-src\": \"/api/invoices\",\n    \"currency\": \"USD\",\n    \"paginate\": 50\n  }\n]\n",
+        "name": "streamed"
+      }
+    ],
+    "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"
+    ],
+    "name": "InvoiceHistory",
+    "related": [
+      "Table",
+      "TableToolbar",
+      "Badge",
+      "Button",
+      "EmptyState",
+      "Pagination"
+    ],
+    "slots": {
+      "empty": {
+        "description": "Custom empty-state content when `invoices` is empty. Falls back\nto a default <empty-state-ui icon=\"receipt\"> when omitted.\n"
+      },
+      "toolbar": {
+        "description": "Optional pre-table action toolbar — overrides the default\n<table-toolbar-ui> + export button stamp. Use when the host\nsurface needs custom actions (e.g. \"New invoice\", \"Reconcile\").\n"
+      }
+    },
+    "states": [
+      {
+        "description": "Default — rows rendered, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "A `data-stream-src` fetch is in flight.",
+        "attribute": "loading",
+        "name": "loading"
+      },
+      {
+        "description": "No invoices to render (computed from invoices.length).",
+        "attribute": "empty",
+        "name": "empty"
+      },
+      {
+        "description": "Last `data-stream-src` fetch failed.",
+        "attribute": "error",
+        "name": "error"
+      }
+    ],
+    "status": "experimental",
+    "synonyms": {
+      "billing": [
+        "invoice",
+        "payment",
+        "subscription"
+      ],
+      "history": [
+        "log",
+        "audit",
+        "record",
+        "timeline"
+      ],
+      "invoice": [
+        "bill",
+        "statement",
+        "receipt"
+      ],
+      "receipts": [
+        "invoices",
+        "billing"
+      ],
+      "statement": [
+        "invoice",
+        "bill"
+      ]
+    },
+    "tag": "invoice-history-ui",
+    "tokens": {
+      "--invoice-history-amount-fg": {
+        "description": "Amount cell foreground.",
+        "default": "var(--a-fg-strong, var(--a-fg))"
+      },
+      "--invoice-history-amount-font": {
+        "description": "Font family for tabular amounts; defaults to the mono stack.",
+        "default": "var(--a-font-mono)"
+      },
+      "--invoice-history-bg": {
+        "description": "Host background. Defaults to transparent.",
+        "default": "transparent"
+      },
+      "--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)"
+      },
+      "--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)"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}