@adia-ai/web-modules 0.8.39 → 0.8.41

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

@@ -19,11 +19,19 @@
  *   - stat-ui for the KPI strip
  *
  * Architecture (light-DOM, ADR-0033):
- *   Stamps a six-region skeleton once on first connect:
- *     [data-header]          — plan title + status tag + slotted actions
- *     [data-kpis]            — 3-stat KPI strip
+ *   Stamps a six-region skeleton once on first connect. Each region is
+ *   the canonical settings-section grammar from
+ *   apps/saas/app/billing/billing.contents.html (gh#1519):
+ *     <section> → <aside> label rail (h3 + p) → <col-ui> content column
+ *   The regions, in DOM order:
+ *     [data-header]          — current-plan card-ui (title + status tag
+ *                              + slotted actions) in a labeled section
+ *     [data-kpis]            — <grid-ui> of card-ui>section>stat-ui KPI
+ *                              cards + a seats <progress-ui> quota bar
  *     [data-dunning]         — alert-ui[pattern="dunning"], conditional
- *     [data-plan-picker]     — plan-picker-ui section, conditional
+ *     [data-plan-picker]     — plan-picker-ui (cycle-toggle on — the
+ *                              canonical field-ui billing-interval
+ *                              chain), conditional
  *     [data-payment-methods] — payment-method-list-ui section
  *     [data-invoice-history] — invoice-history-ui section
  *     [data-empty]           — default empty-state branch
@@ -138,6 +146,7 @@ export class UIBillingOverview extends UIElement {
   #kpisHost = null;
   #kpiSpend = null;
   #kpiSeats = null;
+  #kpiSeatsQuota = null;
   #kpiInvoice = null;
 
   // Dunning banner
@@ -148,6 +157,7 @@ export class UIBillingOverview extends UIElement {
   #planPickerHost = null;
   #planPickerHeading = null;
   #planPicker = null;
+  #forwardedCycle = '';
 
   // Payment-methods section
   #paymentMethodsHost = null;
@@ -322,15 +332,43 @@ export class UIBillingOverview extends UIElement {
     for (const n of nodes) target.appendChild(n);
   }
 
+  /**
+   * Stamp one region in the canonical settings-section grammar
+   * (apps/saas/app/billing/billing.contents.html): a <section> whose
+   * children are an <aside> label rail (h3 + p) and a <col-ui>
+   * content column. Returns [section, contentCol].
+   */
+  #stampRegion(marker, heading, description) {
+    const section = document.createElement('section');
+    section.setAttribute(marker, '');
+    const aside = document.createElement('aside');
+    const h3 = document.createElement('h3');
+    h3.setAttribute('data-section-heading', '');
+    h3.textContent = heading;
+    const p = document.createElement('p');
+    p.setAttribute('data-section-description', '');
+    p.textContent = description;
+    aside.append(h3, p);
+    const col = document.createElement('col-ui');
+    col.setAttribute('data-region-content', '');
+    col.setAttribute('gap', '3');
+    section.append(aside, col);
+    this.appendChild(section);
+    return [section, col];
+  }
+
   #stamp() {
     this.#headingId = `bo-h-${Math.random().toString(36).slice(2, 8)}`;
 
-    // ── Header region ── card-ui wrapping plan title + status tag + actions.
-    // Card chrome matches canonical billing.contents.html plan card pattern
-    // (apps/saas/app/billing/billing.contents.html lines 13-29). See
-    // .brain/findings/demos/billing-overview.wireframe.md §Level 5 tree.
+    // ── Header region ── canonical "Current plan" section: aside rail +
+    // col-ui column holding the card-ui plan card (billing.contents.html
+    // lines 26-62).
+    const [headerSection, headerCol] = this.#stampRegion(
+      'data-header', 'Current plan', 'Your active subscription and billing interval.',
+    );
+
     const headerCard = document.createElement('card-ui');
-    headerCard.setAttribute('data-header', '');
+    headerCard.setAttribute('data-plan-card', '');
 
     const header = document.createElement('header');
 
@@ -355,11 +393,13 @@ export class UIBillingOverview extends UIElement {
     statusBadge.setAttribute('size', 'md');
     headerHeadingSpan.appendChild(statusBadge);
 
-    // Description slot — plan price/cycle/next-invoice meta.
+    // Description slot — plan price/cycle meta as a row-ui cluster.
     const headerDescriptionSpan = document.createElement('span');
     headerDescriptionSpan.setAttribute('slot', 'description');
-    const subtitle = document.createElement('div');
+    const subtitle = document.createElement('row-ui');
     subtitle.setAttribute('data-billing-plan-meta', '');
+    subtitle.setAttribute('gap', '3');
+    subtitle.setAttribute('wrap', '');
     headerDescriptionSpan.appendChild(subtitle);
 
     // Action slot — change-plan + consumer-supplied actions.
@@ -371,9 +411,9 @@ export class UIBillingOverview extends UIElement {
 
     header.append(headerIconSpan, headerHeadingSpan, headerDescriptionSpan, headerActionSpan);
     headerCard.appendChild(header);
-    this.appendChild(headerCard);
+    headerCol.appendChild(headerCard);
 
-    this.#headerHost = headerCard;
+    this.#headerHost = headerSection;
     this.#headerTitle = title;
     this.#headerSubtitle = subtitle;
     this.#headerStatus = statusBadge;
@@ -382,16 +422,23 @@ export class UIBillingOverview extends UIElement {
     // Absorb consumer [slot="header-actions"] children.
     this.#absorbSlottedChildren('header-actions', headerActions);
 
-    // ── KPI strip ── card-ui × 3 wrapping stat-ui (currentSpend · seats · nextInvoice).
-    // Card chrome matches canonical KPI strip pattern from
-    // apps/saas/app/admin-dashboard/admin-dashboard.contents.html (card-ui +
-    // section + stat-ui). See wireframe Level 5 tree.
-    const kpis = document.createElement('section');
-    kpis.setAttribute('data-kpis', '');
+    // ── KPI strip ── canonical "Usage this cycle" section: a grid-ui of
+    // card-ui>section>stat-ui KPI cards (canonical stats grammar,
+    // billing.contents.html change-plan drawer) plus a seats
+    // progress-ui quota bar (canonical usage grammar, lines 78-83).
+    const [kpisSection, kpisCol] = this.#stampRegion(
+      'data-kpis', 'Usage this cycle', 'Spend, seats, and your next invoice.',
+    );
+
+    const kpiGrid = document.createElement('grid-ui');
+    kpiGrid.setAttribute('data-kpi-grid', '');
+    kpiGrid.setAttribute('columns', '3');
+    kpiGrid.setAttribute('gap', '3');
+    kpisCol.appendChild(kpiGrid);
 
     /**
      * Helper: wrap a stat-ui in <card-ui><section> per canonical KPI pattern.
-     * @returns {[HTMLElement, HTMLElement]} [cardWrapper, statElement]
+     * @returns {[HTMLElement, HTMLElement, HTMLElement]} [cardWrapper, statElement, cardSection]
      */
     const makeKpiCard = (kpiId, label, icon) => {
       const card = document.createElement('card-ui');
@@ -404,91 +451,92 @@ export class UIBillingOverview extends UIElement {
       stat.setAttribute('icon', icon);
       section.appendChild(stat);
       card.appendChild(section);
-      return [card, stat];
+      return [card, stat, section];
     };
 
     const [kpiSpendCard, kpiSpend] = makeKpiCard('spend', 'Current month', 'credit-card');
-    const [kpiSeatsCard, kpiSeats] = makeKpiCard('seats', 'Seats', 'users-three');
+    const [kpiSeatsCard, kpiSeats, kpiSeatsSection] = makeKpiCard('seats', 'Seats', 'users-three');
     const [kpiInvoiceCard, kpiInvoice] = makeKpiCard('next-invoice', 'Next invoice', 'calendar');
 
-    kpis.append(kpiSpendCard, kpiSeatsCard, kpiInvoiceCard);
-    this.appendChild(kpis);
-    this.#kpisHost = kpis;
+    // Seats quota bar — progress-ui[label][meta] per the canonical usage
+    // section; hidden until account.seats carries a usable used/total.
+    const seatsQuota = document.createElement('progress-ui');
+    seatsQuota.setAttribute('data-seats-quota', '');
+    seatsQuota.setAttribute('label', 'Seats used');
+    seatsQuota.setAttribute('hidden', '');
+    kpiSeatsSection.appendChild(seatsQuota);
+
+    kpiGrid.append(kpiSpendCard, kpiSeatsCard, kpiInvoiceCard);
+    this.#kpisHost = kpisSection;
     this.#kpiSpend = kpiSpend;
     this.#kpiSeats = kpiSeats;
+    this.#kpiSeatsQuota = seatsQuota;
     this.#kpiInvoice = kpiInvoice;
 
-    // ── Dunning banner ── alert-ui[pattern="dunning"], conditional.
-    const dunningHost = document.createElement('section');
-    dunningHost.setAttribute('data-dunning', '');
-    dunningHost.setAttribute('hidden', '');
+    // ── Dunning banner ── alert-ui[pattern="dunning"], conditional; the
+    // whole labeled section hides for non-past-due accounts.
+    const [dunningSection, dunningCol] = this.#stampRegion(
+      'data-dunning', 'Payment issue', 'Action needed to keep your subscription active.',
+    );
+    dunningSection.setAttribute('hidden', '');
     const dunningAlert = document.createElement('alert-ui');
     dunningAlert.setAttribute('pattern', 'dunning');
     dunningAlert.setAttribute('variant', 'danger');
-    dunningHost.appendChild(dunningAlert);
-    this.appendChild(dunningHost);
-    this.#dunningHost = dunningHost;
+    dunningCol.appendChild(dunningAlert);
+    this.#dunningHost = dunningSection;
     this.#dunningAlert = dunningAlert;
 
-    // ── Plan-picker section ── conditional on [variant=full].
-    const planPickerHost = document.createElement('section');
-    planPickerHost.setAttribute('data-plan-picker', '');
-    const planPickerHeading = document.createElement('h3');
-    planPickerHeading.setAttribute('data-section-heading', '');
-    planPickerHeading.textContent = 'Plan';
-    const planPicker = document.createElement('plan-picker-ui');
-    planPicker.setAttribute('data-billing-plan-picker', '');
-    planPicker.setAttribute('name', 'billing-overview-plan');
-    planPickerHost.append(planPickerHeading, planPicker);
-
-    // Optional before-plan-picker slot anchor sits before the plan picker
-    // section card. We absorb consumer-authored content into planPickerHost
-    // ahead of the heading.
-    this.appendChild(planPickerHost);
-    this.#planPickerHost = planPickerHost;
-    this.#planPickerHeading = planPickerHeading;
-    this.#planPicker = planPicker;
+    // ── Plan-picker section ── conditional on [variant=full]. The picker
+    // runs with [cycle-toggle] so its field-ui("Billing interval") +
+    // segmented-ui chain — the canonical current-plan region's interval
+    // switcher — renders inline.
+    const [planPickerSection, planPickerCol] = this.#stampRegion(
+      'data-plan-picker', 'Plan', 'Compare plans and switch anytime.',
+    );
 
-    // Absorb before-plan-picker slot content into the section
-    // ahead of the plan picker.
+    // Absorb before-plan-picker slot content ahead of the plan picker.
     const beforePlanPicker = document.createElement('div');
     beforePlanPicker.setAttribute('data-before-plan-picker', '');
-    planPickerHost.insertBefore(beforePlanPicker, planPickerHeading);
+    planPickerCol.appendChild(beforePlanPicker);
     this.#absorbSlottedChildren('before-plan-picker', beforePlanPicker);
 
+    const planPicker = document.createElement('plan-picker-ui');
+    planPicker.setAttribute('data-billing-plan-picker', '');
+    planPicker.setAttribute('name', 'billing-overview-plan');
+    planPicker.setAttribute('cycle-toggle', '');
+    planPickerCol.appendChild(planPicker);
+
+    this.#planPickerHost = planPickerSection;
+    this.#planPickerHeading = planPickerSection.querySelector('[data-section-heading]');
+    this.#planPicker = planPicker;
+
     // ── Payment-methods section ──
-    const paymentMethodsHost = document.createElement('section');
-    paymentMethodsHost.setAttribute('data-payment-methods', '');
-    const paymentMethodsHeading = document.createElement('h3');
-    paymentMethodsHeading.setAttribute('data-section-heading', '');
-    paymentMethodsHeading.textContent = 'Payment methods';
+    const [paymentMethodsSection, paymentMethodsCol] = this.#stampRegion(
+      'data-payment-methods', 'Payment methods', 'Cards and wallets on file for recurring charges.',
+    );
     const paymentMethods = document.createElement('payment-method-list-ui');
     paymentMethods.setAttribute('data-billing-payment-methods', '');
     paymentMethods.setAttribute('name', 'billing-overview-payment-method');
-    paymentMethodsHost.append(paymentMethodsHeading, paymentMethods);
-    this.appendChild(paymentMethodsHost);
-    this.#paymentMethodsHost = paymentMethodsHost;
-    this.#paymentMethodsHeading = paymentMethodsHeading;
+    paymentMethodsCol.appendChild(paymentMethods);
+    this.#paymentMethodsHost = paymentMethodsSection;
+    this.#paymentMethodsHeading = paymentMethodsSection.querySelector('[data-section-heading]');
     this.#paymentMethods = paymentMethods;
 
     // ── Invoice-history section ──
-    const invoiceHistoryHost = document.createElement('section');
-    invoiceHistoryHost.setAttribute('data-invoice-history', '');
-    const invoiceHistoryHeading = document.createElement('h3');
-    invoiceHistoryHeading.setAttribute('data-section-heading', '');
-    invoiceHistoryHeading.textContent = 'Invoice history';
+    const [invoiceHistorySection, invoiceHistoryCol] = this.#stampRegion(
+      'data-invoice-history', 'Invoice history', 'Download past invoices for accounting.',
+    );
     const invoiceHistory = document.createElement('invoice-history-ui');
     invoiceHistory.setAttribute('data-billing-invoice-history', '');
-    invoiceHistoryHost.append(invoiceHistoryHeading, invoiceHistory);
-    this.appendChild(invoiceHistoryHost);
-    this.#invoiceHistoryHost = invoiceHistoryHost;
-    this.#invoiceHistoryHeading = invoiceHistoryHeading;
+    invoiceHistoryCol.appendChild(invoiceHistory);
+    this.#invoiceHistoryHost = invoiceHistorySection;
+    this.#invoiceHistoryHeading = invoiceHistorySection.querySelector('[data-section-heading]');
     this.#invoiceHistory = invoiceHistory;
 
     // After-invoice-history slot anchor.
     const afterInvoiceHistory = document.createElement('div');
     afterInvoiceHistory.setAttribute('data-after-invoice-history', '');
-    invoiceHistoryHost.appendChild(afterInvoiceHistory);
+    invoiceHistoryCol.appendChild(afterInvoiceHistory);
     this.#absorbSlottedChildren('after-invoice-history', afterInvoiceHistory);
 
     // ── Empty state ──
@@ -582,7 +630,8 @@ export class UIBillingOverview extends UIElement {
       this.#kpiSpend.setAttribute('value', '—');
     }
 
-    // KPI 2 — seats (used / total).
+    // KPI 2 — seats (used / total) + the seats quota bar (canonical
+    // usage-section progress-ui[label][meta] grammar).
     if (account?.seats && Number.isFinite(account.seats.used)) {
       const used = account.seats.used;
       const total = Number.isFinite(account.seats.total) ? account.seats.total : null;
@@ -590,8 +639,19 @@ export class UIBillingOverview extends UIElement {
         'value',
         total != null ? `${used} / ${total}` : String(used),
       );
+      if (this.#kpiSeatsQuota) {
+        if (total != null && total > 0) {
+          const pct = Math.max(0, Math.min(100, Math.round((used / total) * 100)));
+          this.#kpiSeatsQuota.setAttribute('value', String(pct));
+          this.#kpiSeatsQuota.setAttribute('meta', `${used} / ${total}`);
+          this.#kpiSeatsQuota.removeAttribute('hidden');
+        } else {
+          this.#kpiSeatsQuota.setAttribute('hidden', '');
+        }
+      }
     } else {
       this.#kpiSeats.setAttribute('value', '—');
+      if (this.#kpiSeatsQuota) this.#kpiSeatsQuota.setAttribute('hidden', '');
     }
 
     // KPI 3 — next invoice date.
@@ -683,6 +743,15 @@ export class UIBillingOverview extends UIElement {
       this.#planPicker.setAttribute('current', String(account.plan.id));
     }
 
+    // Seed the picker's billing cycle from account.billingCycle — only
+    // when the ACCOUNT's cycle changes, so a user toggle inside the
+    // picker isn't clobbered by unrelated re-renders (loading flips).
+    const cycle = account?.billingCycle === 'year' ? 'annual' : 'monthly';
+    if (this.#forwardedCycle !== cycle) {
+      this.#forwardedCycle = cycle;
+      this.#planPicker.setAttribute('cycle', cycle);
+    }
+
     if (this.loading) this.#planPicker.setAttribute('loading', '');
     else this.#planPicker.removeAttribute('loading');
   }

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

@@ -1,16 +1,21 @@
 /* ═══════════════════════════════════════════════════════════════
    <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)
+   Stamps a stacked column of dashboard regions, each in the canonical
+   settings-section grammar from apps/saas/app/billing/billing.contents.html
+   (gh#1519): <section> → <aside> label rail (h3 + p) → <col-ui> content.
+     [data-header]          current-plan card (title + status + actions)
+     [data-kpis]            grid-ui of card>section>stat KPI cards +
+                            seats progress-ui quota bar
      [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
+   Layout primitives (col-ui / row-ui / grid-ui) own the stack/row/grid
+   geometry; this file styles only the region grid, the aside rail, and
+   text chrome. 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.
    ═══════════════════════════════════════════════════════════════ */
@@ -22,7 +27,9 @@ billing-overview-ui {
   --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-rail-w:                   14rem;
+  --billing-overview-rail-gap:                 var(--a-space-4);
 
   --billing-overview-header-gap:               var(--a-space-3);
 
@@ -33,6 +40,9 @@ billing-overview-ui {
   --billing-overview-section-heading-size:     var(--a-text-base, 1rem);
   --billing-overview-section-heading-weight:   var(--a-weight-semibold, 600);
 
+  --billing-overview-section-description-fg:   var(--a-fg-muted);
+  --billing-overview-section-description-size: var(--a-text-sm, 0.875rem);
+
   --billing-overview-title-size:               var(--a-text-2xl, 1.5rem);
   --billing-overview-title-weight:             var(--a-weight-bold, 700);
 
@@ -59,11 +69,46 @@ billing-overview-ui {
     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. */
+  /* ── Region grammar ── every region section is an <aside> label rail
+     beside a <col-ui> content column (the canonical [data-section]
+     aside + data-col shape). */
+  :scope > section {
+    display: grid;
+    grid-template-columns: minmax(0, var(--billing-overview-rail-w)) minmax(0, 1fr);
+    column-gap: var(--billing-overview-gap);
+    row-gap: var(--billing-overview-rail-gap);
+    align-items: start;
+  }
+
+  :scope > section[hidden] {
+    display: none;
+  }
 
+  :scope > section > aside {
+    display: flex;
+    flex-direction: column;
+    gap: var(--a-space-1);
+  }
+
+  :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);
+  }
+
+  :scope [data-section-description] {
+    margin: 0;
+    font-size: var(--billing-overview-section-description-size);
+    color: var(--billing-overview-section-description-fg);
+  }
+
+  :scope > section > [data-region-content] {
+    min-width: 0;
+  }
+
+  /* ── Header region ── card-ui owns the card layout; we style only the
+     inline heading/meta content. */
   :scope > [data-header] [data-billing-plan-name] {
     margin: 0;
     font-size: var(--billing-overview-title-size);
@@ -72,10 +117,8 @@ billing-overview-ui {
     line-height: 1.2;
   }
 
+  /* Plan meta — a <row-ui wrap>; row-ui owns the flex geometry. */
   :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);
   }
@@ -105,52 +148,27 @@ billing-overview-ui {
     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;
+  /* ── KPI strip ── a <grid-ui data-kpi-grid> of card-ui>section>stat-ui
+     cards; forward this composite's column/gap tokens into the grid. */
+  :scope grid-ui[data-kpi-grid] {
     grid-template-columns: var(--billing-overview-kpi-columns);
-    gap: var(--billing-overview-kpi-gap);
+    --grid-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;
+  /* Seats quota bar under the seats stat (canonical usage grammar). */
+  :scope [data-seats-quota] {
+    margin-block-start: var(--a-space-2);
   }
-
-  :scope > [data-dunning][hidden] {
+  :scope [data-seats-quota][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] {
+  /* ── Slot anchors ── */
+  :scope [data-before-plan-picker]:empty,
+  :scope [data-after-invoice-history]:empty {
     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],
@@ -158,12 +176,6 @@ billing-overview-ui {
     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;
@@ -208,12 +220,13 @@ billing-overview-ui {
     color: var(--a-danger-strong, var(--a-danger, var(--a-fg-muted)));
   }
 
-  /* ── Container query — collapse KPI strip below ~640px ── */
+  /* ── Container query — stack region rails + collapse the KPI grid
+     below ~640px ── */
   @container billing-overview (max-width: 40rem) {
-    :scope > [data-kpis] {
+    :scope > section {
       grid-template-columns: 1fr;
     }
-    :scope > [data-header] {
+    :scope grid-ui[data-kpi-grid] {
       grid-template-columns: 1fr;
     }
     :scope > [data-header] [data-header-actions] {

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

@@ -50,6 +50,11 @@ composes:
   - tag-ui
   - text-ui
   - alert-ui
+  - avatar-ui
+  - col-ui
+  - row-ui
+  - grid-ui
+  - progress-ui
   - plan-picker-ui
   - payment-method-list-ui
   - invoice-history-ui

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

@@ -27,17 +27,21 @@
       "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",
+      "description": "Line-items table row density. `compact` for tightly-packed\ninvoices with many line items; unset (default) for typical\ninvoices. Forwarded to the embedded <table-ui density>.\nConverged onto the global `[density]` Enum·preset vocabulary\n(gh#1335) — `standard` retired (it was never a real state; the\nforwarding logic already treated it as unset) and `spacious`\nadded for parity with the global grammar.\n",
       "type": "string",
       "enum": [
+        "",
         "compact",
-        "standard"
+        "spacious"
       ],
-      "default": "standard"
+      "default": ""
     },
     "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",
+      "type": [
+        "object",
+        "null"
+      ],
       "default": null
     },
     "loading": {
@@ -167,6 +171,7 @@
       "void"
     ],
     "name": "UIInvoiceDetail",
+    "parts": {},
     "related": [
       "Card",
       "Table",

package/billing/invoice-detail/invoice-detail.class.js

@@ -91,6 +91,17 @@ function formatDate(iso, locale) {
   }
 }
 
+/**
+ * Translate invoice-detail-ui's own `density` onto table-ui's global
+ * [density] grammar (ADR-0054). gh#1335 — the vocabulary now IS the
+ * global one (compact/spacious/unset), so this is an identity passthrough
+ * for a real value; "" (or anything unrecognized) is the absent attribute.
+ * Returns null for "no attribute".
+ */
+function mapDensity(density) {
+  return density === 'compact' || density === 'spacious' ? density : null;
+}
+
 export class UIInvoiceDetail extends UIElement {
   static get properties() {
     return {
@@ -98,7 +109,7 @@ export class UIInvoiceDetail extends UIElement {
       invoice: { type: Object, default: null },
       status: { type: String, default: 'draft', reflect: true },
       currency: { type: String, default: 'USD', reflect: true },
-      density: { type: String, default: 'standard', reflect: true },
+      density: { type: String, default: '', reflect: true },
       loading: { type: Boolean, default: false, reflect: true },
       printable: { type: Boolean, default: true, reflect: true },
       locale: { type: String, default: '' },
@@ -423,7 +434,10 @@ export class UIInvoiceDetail extends UIElement {
 
     const table = document.createElement('table-ui');
     table.setAttribute('data-lines-table', '');
-    table.setAttribute('density', this.density || 'standard');
+    // table-ui has no local `density` prop (ADR-0054) — forward via the
+    // global attribute, translated through mapDensity().
+    const initialDensity = mapDensity(this.density);
+    if (initialDensity) table.setAttribute('density', initialDensity);
     linesBody.appendChild(table);
 
     lines.appendChild(linesCard);
@@ -599,9 +613,12 @@ export class UIInvoiceDetail extends UIElement {
       unitAmount: line?.unitAmount ?? 0,
       amount: line?.amount ?? 0,
     }));
-    // Mirror density.
-    if (this.#linesTable.getAttribute('density') !== this.density) {
-      this.#linesTable.setAttribute('density', this.density || 'standard');
+    // Mirror density — table-ui has no local `density` prop (ADR-0054);
+    // forward via the global attribute, translated through mapDensity().
+    const mirroredDensity = mapDensity(this.density);
+    if (this.#linesTable.getAttribute('density') !== mirroredDensity) {
+      if (mirroredDensity) this.#linesTable.setAttribute('density', mirroredDensity);
+      else this.#linesTable.removeAttribute('density');
     }
   }