@adia-ai/web-modules 0.8.35 → 0.8.37

package/billing/billing-overview/billing-overview.css

@@ -0,0 +1,223 @@
+/* ═══════════════════════════════════════════════════════════════
+   <billing-overview-ui> — Module-tier billing dashboard composite.
+
+   Stamps a stacked column of dashboard regions:
+     [data-header]          plan title + status badge + actions
+     [data-kpis]            3-stat KPI strip (spend · seats · next)
+     [data-dunning]         alert-ui[pattern=dunning], conditional
+     [data-plan-picker]     plan-picker-ui section
+     [data-payment-methods] payment-method-list-ui section
+     [data-invoice-history] invoice-history-ui section
+     [data-empty]           default empty-state branch
+
+   SPEC: docs/specs/implementation-ready/SPEC-004-billing-overview.md
+   Two-block @scope pattern per docs/specs/component-token-contract.md.
+   Zero raw color values (repo hard rule); rem for sizes ≥ 3px.
+   ═══════════════════════════════════════════════════════════════ */
+
+/* ── Block 1: TOKEN DECLARATIONS ───────────────────────────────── */
+
+billing-overview-ui {
+  --billing-overview-bg:                       transparent;
+  --billing-overview-gap:                      var(--a-space-5);
+  --billing-overview-px:                       var(--a-space-5);
+  --billing-overview-py:                       var(--a-space-5);
+  --billing-overview-section-radius:           var(--a-radius-lg);
+
+  --billing-overview-header-gap:               var(--a-space-3);
+
+  --billing-overview-kpi-columns:              repeat(3, minmax(0, 1fr));
+  --billing-overview-kpi-gap:                  var(--a-space-3);
+
+  --billing-overview-section-heading-fg:       var(--md-sys-color-neutral-on-surface);
+  --billing-overview-section-heading-size:     var(--a-text-base, 1rem);
+  --billing-overview-section-heading-weight:   var(--a-weight-semibold, 600);
+
+  --billing-overview-title-size:               var(--a-text-2xl, 1.5rem);
+  --billing-overview-title-weight:             var(--a-weight-bold, 700);
+
+  --billing-overview-meta-fg:                  var(--a-fg-muted);
+  --billing-overview-meta-size:                var(--a-text-sm, 0.875rem);
+
+  --billing-overview-empty-fg:                 var(--a-fg-muted);
+}
+
+/* ── Block 2: SCOPED LAYOUT ────────────────────────────────────── */
+
+@scope (billing-overview-ui) {
+
+  /* Host — stack regions in a column, container for inner CQ. */
+  :scope {
+    display: flex;
+    flex-direction: column;
+    gap: var(--billing-overview-gap);
+    background: var(--billing-overview-bg);
+    padding-block: var(--billing-overview-py);
+    padding-inline: var(--billing-overview-px);
+    box-sizing: border-box;
+    container-type: inline-size;
+    container-name: billing-overview;
+  }
+
+  /* ── Header region ── card-ui owns layout; we just style inline content.
+     Per v1.7.1 wireframe re-author (2026-05-24): header is now <card-ui> with
+     <header> slot composition (icon | heading | description | action).
+     card-ui's @scope provides the layout; we only style descendants. */
+
+  :scope > [data-header] [data-billing-plan-name] {
+    margin: 0;
+    font-size: var(--billing-overview-title-size);
+    font-weight: var(--billing-overview-title-weight);
+    color: var(--md-sys-color-neutral-on-surface);
+    line-height: 1.2;
+  }
+
+  :scope > [data-header] [data-billing-plan-meta] {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--a-space-3);
+    font-size: var(--billing-overview-meta-size);
+    color: var(--billing-overview-meta-fg);
+  }
+
+  :scope > [data-header] [data-billing-plan-meta]:empty {
+    display: none;
+  }
+
+  :scope > [data-header] [data-billing-status] {
+    margin-inline-start: var(--a-space-2);
+    vertical-align: baseline;
+  }
+
+  :scope > [data-header] [data-billing-status][hidden] {
+    display: none;
+  }
+
+  :scope > [data-header] [data-header-actions] {
+    display: flex;
+    gap: var(--a-space-2);
+    justify-content: flex-end;
+    flex-wrap: wrap;
+    align-items: center;
+  }
+
+  :scope > [data-header] [data-header-actions]:empty {
+    display: none;
+  }
+
+  /* ── KPI strip ── card-ui × 3 wrapping stat-ui per canonical pattern.
+     Per v1.7.1 wireframe re-author: each KPI is now <card-ui><section><stat-ui>
+     instead of CSS-faked card chrome on raw stat-ui. */
+  :scope > [data-kpis] {
+    display: grid;
+    grid-template-columns: var(--billing-overview-kpi-columns);
+    gap: var(--billing-overview-kpi-gap);
+  }
+
+  /* card-ui chrome is provided by card-ui's own @scope; no fake card chrome here. */
+
+  /* ── Dunning banner ── */
+  :scope > [data-dunning] {
+    display: block;
+  }
+
+  :scope > [data-dunning][hidden] {
+    display: none;
+  }
+
+  /* ── Section host shape ── plan-picker, payment-methods, invoice-history */
+  :scope > [data-plan-picker],
+  :scope > [data-payment-methods],
+  :scope > [data-invoice-history] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--a-space-3);
+    background: var(--md-sys-color-neutral-background);
+    border: 1px solid var(--md-sys-color-neutral-outline-variant);
+    border-radius: var(--billing-overview-section-radius);
+    padding: var(--a-space-4);
+  }
+
+  :scope > [data-plan-picker][hidden],
+  :scope > [data-payment-methods][hidden],
+  :scope > [data-invoice-history][hidden] {
+    display: none;
+  }
+
+  :scope [data-section-heading] {
+    margin: 0;
+    font-size: var(--billing-overview-section-heading-size);
+    font-weight: var(--billing-overview-section-heading-weight);
+    color: var(--billing-overview-section-heading-fg);
+  }
+
+  /* ── Variant cascade ── */
+  /* compact + enterprise hide the plan-picker section (also gated in JS). */
+  :scope[variant="compact"] > [data-plan-picker],
+  :scope[variant="enterprise"] > [data-plan-picker] {
+    display: none;
+  }
+
+  /* ── Slot anchors ── */
+  :scope [data-before-plan-picker]:empty,
+  :scope [data-after-invoice-history]:empty {
+    display: none;
+  }
+
+  /* ── Empty + loading states ── */
+  :scope > [data-empty] {
+    display: none;
+    color: var(--billing-overview-empty-fg);
+    text-align: center;
+    padding-block: var(--a-space-6);
+  }
+
+  :scope[empty] > [data-empty] {
+    display: block;
+  }
+
+  :scope[empty] > [data-header],
+  :scope[empty] > [data-kpis],
+  :scope[empty] > [data-dunning],
+  :scope[empty] > [data-plan-picker],
+  :scope[empty] > [data-payment-methods],
+  :scope[empty] > [data-invoice-history] {
+    display: none;
+  }
+
+  :scope [data-empty-heading] {
+    margin: 0 0 var(--a-space-2) 0;
+    font-size: var(--a-text-base, 1rem);
+    font-weight: var(--a-weight-semibold, 600);
+    color: var(--md-sys-color-neutral-on-surface);
+  }
+
+  :scope [data-empty-description] {
+    margin: 0;
+    font-size: var(--a-text-sm, 0.875rem);
+  }
+
+  :scope[loading] {
+    opacity: 0.85;
+  }
+
+  /* ── Past-due emphasis ── */
+  /* The dunning banner already carries danger chrome; tint the header
+     status zone subtly. */
+  :scope[past-due] > [data-header] [data-billing-plan-meta] {
+    color: var(--a-danger-strong, var(--a-danger, var(--a-fg-muted)));
+  }
+
+  /* ── Container query — collapse KPI strip below ~640px ── */
+  @container billing-overview (max-width: 40rem) {
+    :scope > [data-kpis] {
+      grid-template-columns: 1fr;
+    }
+    :scope > [data-header] {
+      grid-template-columns: 1fr;
+    }
+    :scope > [data-header] [data-header-actions] {
+      justify-content: flex-start;
+    }
+  }
+}

package/billing/billing-overview/billing-overview.js

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

package/billing/billing-overview/billing-overview.yaml

@@ -0,0 +1,441 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIBillingOverview
+tag: billing-overview-ui
+status: experimental
+component: BillingOverview
+category: container
+version: 1
+description: |
+  Module-tier billing dashboard that stitches the seven Wave A+B
+  billing primitives into the canonical "all-billing-on-one-page"
+  surface — current plan + status header, a KPI strip (monthly
+  spend · seats · next invoice), an optional dunning banner when the
+  account is past-due, a plan-picker section for in-app plan changes,
+  a payment-method-list section, and an invoice-history section.
+
+  Data-driven via the `account` property — an aggregate snapshot of
+  the customer's billing state ({plan, status, billingCycle,
+  currentSpend, seats, nextInvoiceDate, paymentMethods[],
+  invoices[], dunning?}). The composite stamps a fixed five-region
+  skeleton once on first connect — header · kpis · dunning ·
+  plan-picker · payment-methods · invoice-history — then mutates
+  per-region nodes via id-keyed in-place diff on every property
+  change. Children primitives (plan-picker, payment-method-list,
+  invoice-history, alert-ui) are stamped as composed tags; this
+  composite owns the orchestration, not the row chrome.
+
+  Higher-level account-action event surfaces consumer-actionable
+  intents from descendant primitives. Children carrying
+  [data-account-action="X"] or descendant events
+  (`plan-action`, `payment-action`, `invoice-action`, `dunning-action`)
+  are normalised into a single `account-action` event with
+  `detail.action` ∈ {change-plan, add-payment-method, pay-now,
+  download-invoice, update-card, retry, custom}. The composite
+  does NOT mutate the data source; consumers wire `account-action`
+  against their billing backend.
+
+  Display surface. Extends UIElement, not UIFormElement — child
+  primitives are individually form-bearing (plan-picker,
+  payment-method-list) while the host is not.
+
+  Spec: .claude/docs/specs/implementation-ready/SPEC-004-billing-overview.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
+  - stat-ui
+  - tag-ui
+  - text-ui
+  - alert-ui
+  - plan-picker-ui
+  - payment-method-list-ui
+  - invoice-history-ui
+  - button-ui
+  - icon-ui
+
+props:
+  account:
+    description: |
+      Aggregate billing snapshot — source of truth for the whole
+      dashboard. Shape:
+        {plan: {id, name, price, cycle, currency, status},
+         status: "active" | "trialing" | "past_due" | "canceled" | "paused",
+         billingCycle: "month" | "year",
+         currentSpend: number,
+         seats: {used: number, total: number},
+         nextInvoiceDate: ISO 8601 date string,
+         paymentMethods: [...],          // forwarded to payment-method-list
+         invoices: [...],                // forwarded to invoice-history
+         plans?: [...],                  // forwarded to plan-picker; omitted when planSection is "hidden"
+         dunning?: {amount, currency, dueAt, cardLast4?, reason?}}
+      Null + no `data-stream-src` renders the empty state.
+    type: object
+    default: null
+    dynamic: true
+    required: true
+
+  variant:
+    description: |
+      Layout variant. `full` shows every section. `compact` collapses
+      the plan-picker section and renders only the KPI strip + payment
+      methods + invoice history (the canonical "settings billing"
+      shape). `enterprise` hides plan-picker entirely (no self-serve
+      plan changes) and keeps the rest.
+    type: string
+    default: "full"
+    enum:
+      - full
+      - compact
+      - enterprise
+    reflect: true
+
+  currency:
+    description: |
+      Default ISO 4217 currency for all amount formatting. Overridable
+      per-record (plan.currency, invoice.currency, etc.).
+    type: string
+    default: "USD"
+    reflect: true
+
+  locale:
+    description: |
+      Locale for Intl.NumberFormat (currency) and Intl.DateTimeFormat
+      (dates). Defaults to document.documentElement.lang (or "en-US"
+      when absent).
+    type: string
+    default: ""
+
+  loading:
+    description: |
+      Renders skeleton placeholders in the header + KPI strip while
+      data is fetching. Sets aria-busy on the host. Forwarded to
+      child composites that accept [loading] (plan-picker,
+      payment-method-list, invoice-history).
+    type: boolean
+    default: false
+    reflect: true
+    dynamic: true
+
+  data-stream-src:
+    description: |
+      Optional endpoint returning the full account snapshot. On
+      successful load, `account` is replaced and a `load` event fires;
+      on failure an `error` event fires.
+    type: string
+    default: ""
+    attribute: data-stream-src
+
+events:
+  account-action:
+    description: |
+      Unified account-action event — normalises every actionable
+      intent from descendant primitives into a single bubbling event.
+      Handler can act on `detail.action` without subscribing to four
+      different child event names. Bubbles.
+    detail:
+      action:
+        type: string
+        description: |
+          One of "change-plan" | "add-payment-method" | "pay-now" |
+          "download-invoice" | "update-card" | "retry" | "select-plan"
+          | "remove-payment-method" | "set-default-payment-method" |
+          or any consumer-defined value carried on a descendant
+          [data-account-action] attribute.
+      source:
+        type: string
+        description: |
+          The originating primitive — "plan-picker" | "payment-method-list"
+          | "invoice-history" | "alert-dunning" | "header" | "custom".
+      payload:
+        type: object
+        description: |
+          Forwarded detail from the originating event (e.g. the
+          invoice record, the plan id, the dunning amount). Shape
+          varies by source.
+
+  load:
+    description: |
+      Fired when `data-stream-src` finishes a successful fetch and
+      `account` is populated. Bubbles.
+    detail:
+      account:
+        type: object
+        description: The loaded account snapshot.
+
+  error:
+    description: |
+      Fired when a `data-stream-src` fetch fails. Bubbles.
+    detail:
+      reason:
+        type: string
+        description: One of `fetch-failed`.
+
+slots:
+  header-actions:
+    description: |
+      Optional action row in the dashboard header (top-right). Used
+      for consumer-authored "Contact sales", "Cancel subscription",
+      etc. The composite NEVER stamps a default toolbar.
+  before-plan-picker:
+    description: |
+      Optional content slotted above the plan-picker section (e.g. a
+      promo banner, an annual-savings callout).
+  after-invoice-history:
+    description: |
+      Optional content slotted below the invoice-history section
+      (e.g. tax-document download row, billing-contact form).
+  empty:
+    description: |
+      Custom empty-state content when there's no account snapshot
+      AND no data-stream-src. Falls back to a default empty-state
+      message.
+
+states:
+  - name: idle
+    description: Default — account rendered, ready for interaction.
+  - name: loading
+    description: A `data-stream-src` fetch is in flight or [loading] is set.
+    attribute: loading
+  - name: empty
+    description: No account snapshot + no data-stream-src.
+    attribute: empty
+  - name: past-due
+    description: |
+      Account is past-due (computed from `account.status === "past_due"`).
+      Stamps the dunning banner if `account.dunning` is present.
+    attribute: past-due
+  - name: trial
+    description: |
+      Account is trialing (computed from `account.status === "trialing"`).
+    attribute: trial
+  - name: error
+    description: Last `data-stream-src` fetch failed.
+    attribute: error
+
+traits: []
+
+tokens:
+  --billing-overview-bg:
+    description: Host page background. Defaults to transparent.
+    default: transparent
+  --billing-overview-gap:
+    description: Vertical gap between dashboard sections.
+    default: var(--a-space-5)
+  --billing-overview-px:
+    description: Horizontal padding around dashboard content.
+    default: var(--a-space-5)
+  --billing-overview-py:
+    description: Vertical padding around dashboard content.
+    default: var(--a-space-5)
+  --billing-overview-section-radius:
+    description: Section card corner radius.
+    default: var(--a-radius-lg)
+  --billing-overview-header-gap:
+    description: Gap between the plan title block and the status badge cluster.
+    default: var(--a-space-3)
+  --billing-overview-kpi-columns:
+    description: |
+      Grid column template for the KPI strip. Falls back to a 3-column
+      auto-fit when narrowed below 40rem (container query).
+    default: repeat(3, minmax(0, 1fr))
+  --billing-overview-kpi-gap:
+    description: Gap between KPI stat cards.
+    default: var(--a-space-3)
+  --billing-overview-section-heading-fg:
+    description: Foreground color for section heading labels.
+    default: var(--a-fg)
+  --billing-overview-section-heading-size:
+    description: Font size for section heading labels.
+    default: var(--a-text-base, 1rem)
+  --billing-overview-section-heading-weight:
+    description: Font weight for section heading labels.
+    default: var(--a-weight-semibold, 600)
+  --billing-overview-meta-fg:
+    description: Foreground color for secondary metadata in the header.
+    default: var(--a-fg-muted)
+
+requiredIcons:
+  - credit-card
+  - calendar
+  - users-three
+
+a2ui:
+  rules:
+    - >-
+      BillingOverview.account is REQUIRED. The composite is meaningless
+      without an account snapshot; emitting BillingOverview with null
+      account and no data-stream-src renders the empty state.
+    - >-
+      account.status MUST be one of `active` | `trialing` | `past_due`
+      | `canceled` | `paused`. Unknown values render neutral chrome.
+    - >-
+      account.dunning is REQUIRED when account.status is `past_due`
+      (otherwise the dunning banner cannot render). Shape:
+      `{amount, currency, dueAt, cardLast4?, reason?}`. The composite
+      stamps `<alert-ui pattern="dunning">` per SPEC-006.
+    - >-
+      account.plans is REQUIRED when [variant] is `full` (otherwise
+      the plan-picker section has nothing to render). Omit `plans`
+      when [variant] is `compact` or `enterprise` to skip the
+      plan-picker section.
+    - >-
+      account.paymentMethods is forwarded verbatim to
+      <payment-method-list-ui>; account.invoices is forwarded
+      verbatim to <invoice-history-ui>. Their shapes are owned by
+      SPEC-010 and SPEC-008 respectively.
+    - >-
+      BillingOverview MUST NOT be nested inside Modal or Drawer. The
+      dashboard is a route, not a modal — Modal traps focus + clips
+      on long content; this surface is designed for full-page layout.
+    - >-
+      Wire one listener to `account-action` instead of subscribing to
+      every child primitive's event. The composite normalises
+      plan-action / payment-action / invoice-action / dunning-action
+      into the single bubbling event.
+
+anti_patterns:
+  - wrong: |
+      {"component": "BillingOverview"}
+    why: |
+      Missing the required `account` prop. The composite renders the
+      empty state. A dashboard without data has nothing to show.
+    fix: |
+      {"component": "BillingOverview", "account":
+        {"plan": {"id":"p_pro","name":"Pro","price":48,"cycle":"month","currency":"USD","status":"active"},
+         "status": "active",
+         "billingCycle": "month",
+         "currentSpend": 48,
+         "seats": {"used": 4, "total": 10},
+         "nextInvoiceDate": "2026-06-01",
+         "paymentMethods": [...],
+         "invoices": [...]}}
+  - wrong: |
+      {"component": "Modal", "children":
+        [{"component": "BillingOverview", "account": {...}}]}
+    why: |
+      The dashboard is a route, not a modal. Modal traps focus + clips
+      content; the composite is designed for the full /billing page.
+    fix: |
+      Render the BillingOverview composite on its own route
+      (typically `/settings/billing` or `/billing`).
+  - wrong: |
+      <billing-overview-ui account='{"status":"past_due"}'></billing-overview-ui>
+    why: |
+      Past-due status without an `account.dunning` payload. The
+      composite cannot render the dunning banner (it needs amount +
+      due-at + currency to format the alert message).
+    fix: |
+      Provide a dunning object alongside the past_due status:
+      <billing-overview-ui account='{"status":"past_due","dunning":{"amount":48,"currency":"USD","dueAt":"2026-05-20"}}'></billing-overview-ui>
+  - wrong: |
+      <billing-overview-ui variant="full" account='{"plan":{...},"status":"active"}'></billing-overview-ui>
+    why: |
+      `variant=full` requires `account.plans` so the plan-picker
+      section has rows to render. Without plans, the section renders
+      its own empty-state and looks broken.
+    fix: |
+      Either pass `account.plans` OR set `variant="compact"` to hide
+      the plan-picker section entirely.
+
+examples:
+  - name: active-pro-account
+    description: Active Pro plan with 4 saved cards + 3 invoices.
+    a2ui: |
+      [
+        {
+          "id": "bo-pro",
+          "component": "BillingOverview",
+          "variant": "full",
+          "currency": "USD",
+          "account": {
+            "plan": {
+              "id": "p_pro",
+              "name": "Pro",
+              "price": 48,
+              "cycle": "month",
+              "currency": "USD",
+              "status": "active"
+            },
+            "status": "active",
+            "billingCycle": "month",
+            "currentSpend": 48,
+            "seats": {"used": 4, "total": 10},
+            "nextInvoiceDate": "2026-06-01",
+            "plans": [],
+            "paymentMethods": [],
+            "invoices": []
+          }
+        }
+      ]
+  - name: past-due-account
+    description: Past-due account with dunning banner above plan section.
+    a2ui: |
+      [
+        {
+          "id": "bo-past-due",
+          "component": "BillingOverview",
+          "variant": "full",
+          "currency": "USD",
+          "account": {
+            "plan": {
+              "id": "p_pro",
+              "name": "Pro",
+              "price": 48,
+              "cycle": "month",
+              "currency": "USD",
+              "status": "past_due"
+            },
+            "status": "past_due",
+            "billingCycle": "month",
+            "currentSpend": 48,
+            "seats": {"used": 4, "total": 10},
+            "nextInvoiceDate": "2026-05-20",
+            "dunning": {
+              "amount": 48,
+              "currency": "USD",
+              "dueAt": "2026-05-20",
+              "cardLast4": "4242",
+              "reason": "declined"
+            },
+            "plans": [],
+            "paymentMethods": [],
+            "invoices": []
+          }
+        }
+      ]
+
+keywords:
+  - billing
+  - overview
+  - dashboard
+  - account
+  - subscription
+  - plan
+  - invoice
+  - payment-method
+  - usage
+  - dunning
+  - past-due
+
+synonyms:
+  billing:
+    - subscription
+    - account-billing
+  overview:
+    - dashboard
+    - summary
+  account:
+    - subscription
+    - membership
+
+related:
+  - PlanPicker
+  - PaymentMethodList
+  - InvoiceHistory
+  - InvoiceDetail
+  - PaymentMethodForm
+  - Alert
+  - Stat

package/billing/index.js

@@ -0,0 +1,21 @@
+/**
+ * @adia-ai/web-modules/billing — cluster barrel.
+ *
+ * Composite billing-surface primitives that compose substrate
+ * primitives and pre-stamp the canonical shape for plan choice,
+ * pricing display, invoice list/detail, saved-payment-method flows,
+ * and card-capture forms.
+ *
+ * SPEC-004 — billing-overview-ui (module-tier billing dashboard).
+ * SPEC-007 — invoice-detail-ui (full-page invoice composite).
+ * SPEC-008 — invoice-history-ui (canonical billing-list composite).
+ * SPEC-009 — payment-method-form-ui (card capture + structured validation).
+ * SPEC-010 — payment-method-list-ui (saved payment methods with default radio).
+ * SPEC-011 — plan-picker-ui (one-of-N plan chooser, in-app + marketing).
+ */
+export { UIBillingOverview } from './billing-overview/billing-overview.js';
+export { InvoiceHistory } from './invoice-history/invoice-history.js';
+export { UIInvoiceDetail } from './invoice-detail/invoice-detail.js';
+export { UIPaymentMethodForm } from './payment-method-form/payment-method-form.js';
+export { PaymentMethodList } from './payment-method-list/payment-method-list.js';
+export { PlanPicker } from './plan-picker/plan-picker.js';