@adia-ai/web-modules 0.8.36 → 0.8.37

package/dashboard/dashboard-layout/dashboard-layout.js

@@ -0,0 +1,289 @@
+/**
+ * <dashboard-layout-ui> — Module-tier dashboard-body composite.
+ *
+ * Crystallizes the recurring "toolbar + KPI grid + chart area + table"
+ * dashboard layout into four named regions:
+ *
+ *   <dashboard-layout-ui density="" kpi-columns="4" chart-split="2:1">
+ *     <row-ui slot="toolbar">…</row-ui>
+ *     <div slot="kpis">…<card-ui><stat-ui/></card-ui>…</div>
+ *     <div slot="charts">…<card-ui><chart-ui/></card-ui>…</div>
+ *     <card-ui slot="table">…<table-ui/>…</card-ui>
+ *     <card-ui slot="aside">…</card-ui>            <!-- optional -->
+ *   </dashboard-layout-ui>
+ *
+ * Per ADR-0033 (Light-DOM substrate) — slot= attributes are decorative
+ * metadata; CSS rules in dashboard-layout.css position bands via
+ * `:scope > [slot="X"]` selectors. The composite stamps no internal
+ * DOM (zero-parts strategy, same shape as <visually-hidden-ui> /
+ * <admin-page-body>); every rendered band is consumer-supplied.
+ *
+ * Per ADR-0027 — composites that programmatically reference primitives
+ * do NOT auto-import them. Consumer (or demo shell) must explicitly
+ * import <card-ui>, <grid-ui>, <stat-ui>, <chart-ui>, <table-ui>.
+ *
+ * SPEC: .claude/docs/specs/implementation-ready/SPEC-018-dashboard-layout.md.
+ */
+
+import { UIElement } from '@adia-ai/web-components/core/element';
+import { untracked } from '@adia-ai/web-components/core/signals';
+
+// ── Validation tables ────────────────────────────────────────────
+
+const VALID_DENSITIES   = new Set(['', 'comfortable', 'compact', 'spacious']);
+const VALID_KPI_COLUMNS = new Set(['2', '3', '4', '5', '6']);
+const VALID_CHART_SPLIT = new Set(['', '2', '2:1', '3:2', '3:1']);
+const REGION_SLOTS      = ['toolbar', 'kpis', 'charts', 'table', 'aside'];
+
+// ── UIDashboardLayout ────────────────────────────────────────────
+
+export class UIDashboardLayout extends UIElement {
+  static get properties() {
+    return {
+      density:       { type: String,  default: '',     reflect: true },
+      'kpi-columns': { type: String,  default: '4',    reflect: true, attribute: 'kpi-columns' },
+      'chart-split': { type: String,  default: '',     reflect: true, attribute: 'chart-split' },
+      loading:       { type: Boolean, default: false,  reflect: true },
+      gap:           { type: String,  default: '',     reflect: true },
+    };
+  }
+
+  // Zero-parts stamping strategy. The composite renders no internal
+  // DOM — all bands are consumer-supplied via named slots. Returning
+  // null prevents the base UIElement stamp() pipeline from running
+  // replaceChildren() and wiping the authored slotted children.
+  // Same pattern as <date-range-selector-ui> + <admin-page-body>.
+  static template = () => null;
+
+  // ── Internal state ──────────────────────────────────────────────
+
+  /** Tracks which regions had children at last observation. Used so
+   *  region-empty fires only on transition (had children → empty),
+   *  not on every mutation. */
+  #regionPopulated = { toolbar: false, kpis: false, charts: false, table: false, aside: false };
+
+  /** MutationObserver for descendant slot-change tracking. */
+  #observer = null;
+
+  /** Suppress nested attribute callbacks when the composite is doing
+   *  an internal property write (e.g. clamping an out-of-range
+   *  kpi-columns back to "4"). */
+  #internalUpdate = false;
+
+  // ── Public imperative API (SPEC §4 Methods) ─────────────────────
+
+  /**
+   * Programmatic equivalent of setting the [density] attribute.
+   * Fires `density-change` once with the new value.
+   *
+   * @param {string} value — '' | 'comfortable' | 'compact' | 'spacious'
+   */
+  setDensity(value) {
+    const next = VALID_DENSITIES.has(value) ? value : '';
+    if (this.density === next) return;
+    this.density = next;
+    // attributeChangedCallback below dispatches density-change.
+  }
+
+  /**
+   * Returns the immediate child element marked with the given slot, or
+   * null if no such child exists. The dashboard places each named slot
+   * via CSS grid-area, so consumers typically wrap multiple children
+   * in a single slot host (e.g. `<div slot="kpis">…N cards…</div>`).
+   *
+   * @param {string} name — toolbar | kpis | charts | table | aside
+   * @returns {HTMLElement | null}
+   */
+  getRegion(name) {
+    if (!REGION_SLOTS.includes(name)) return null;
+    return this.querySelector(`:scope > [slot="${name}"]`);
+  }
+
+  // ── Lifecycle ───────────────────────────────────────────────────
+
+  connected() {
+    // role="region" — the dashboard is a major landmark within the
+    // page main. Consumers supply aria-label (or aria-labelledby on
+    // an associated <admin-page-header heading>).
+    if (!this.hasAttribute('role')) {
+      this.setAttribute('role', 'region');
+    }
+
+    // Clamp out-of-range attributes to documented defaults so
+    // consumers using a2ui-generated markup don't end up with a
+    // misfiring container-query collapse on kpi-columns="8".
+    untracked(() => this.#clampProps());
+
+    // aria-busy mirrors [loading] for the first paint; subsequent
+    // changes flow through attributeChangedCallback below.
+    this.#syncAriaBusy();
+
+    // Apply the [gap] override → public token if set.
+    this.#applyGapAttr();
+
+    // Watch for region-empty transitions. Children are arbitrary
+    // (consumers might dynamically remove the last kpi card), so a
+    // MutationObserver on the host's childList captures structural
+    // changes regardless of which descendant fires.
+    this.#snapshotRegions();
+    // gh#285 — SSR DOM shims (linkedom) have no MutationObserver global.
+    if (typeof MutationObserver !== 'undefined') {
+      this.#observer = new MutationObserver((records) => this.#onMutate(records));
+      this.#observer.observe(this, { childList: true });
+    }
+  }
+
+  disconnected() {
+    if (this.#observer) {
+      this.#observer.disconnect();
+      this.#observer = null;
+    }
+  }
+
+  attributeChangedCallback(name, oldVal, newVal) {
+    super.attributeChangedCallback?.(name, oldVal, newVal);
+    if (this.#internalUpdate) return;
+
+    if (name === 'density' && oldVal !== newVal) {
+      // Clamp + emit density-change. attributeChangedCallback runs
+      // before connected() on declarative attributes, so guard the
+      // dispatch behind isConnected to keep first-paint quiet — the
+      // initial declarative value is just a starting state, not an
+      // event-worthy transition.
+      if (!VALID_DENSITIES.has(newVal)) {
+        this.#internalUpdate = true;
+        try { this.density = ''; } finally { this.#internalUpdate = false; }
+        return;
+      }
+      if (this.isConnected) {
+        this.dispatchEvent(new CustomEvent('density-change', {
+          bubbles: true,
+          detail: { density: newVal },
+        }));
+      }
+      return;
+    }
+
+    if (name === 'kpi-columns' && oldVal !== newVal) {
+      if (newVal != null && !VALID_KPI_COLUMNS.has(newVal)) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[dashboard-layout-ui] kpi-columns="${newVal}" out of range — falling back to "4". ` +
+          `Use one of: ${[...VALID_KPI_COLUMNS].join(', ')}.`,
+        );
+        this.#internalUpdate = true;
+        try { this['kpi-columns'] = '4'; } finally { this.#internalUpdate = false; }
+      }
+      return;
+    }
+
+    if (name === 'chart-split' && oldVal !== newVal) {
+      if (newVal != null && !VALID_CHART_SPLIT.has(newVal)) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[dashboard-layout-ui] chart-split="${newVal}" not in enum — falling back to "" (single column). ` +
+          `Use one of: "" (full), 2, 2:1, 3:2, 3:1.`,
+        );
+        this.#internalUpdate = true;
+        try { this['chart-split'] = ''; } finally { this.#internalUpdate = false; }
+      }
+      return;
+    }
+
+    if (name === 'loading' && oldVal !== newVal) {
+      this.#syncAriaBusy();
+      return;
+    }
+
+    if (name === 'gap' && oldVal !== newVal) {
+      this.#applyGapAttr();
+      return;
+    }
+  }
+
+  // ── Internal: prop clamping ─────────────────────────────────────
+
+  #clampProps() {
+    if (!VALID_DENSITIES.has(this.density)) {
+      this.#internalUpdate = true;
+      try { this.density = ''; } finally { this.#internalUpdate = false; }
+    }
+    if (!VALID_KPI_COLUMNS.has(this['kpi-columns'])) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[dashboard-layout-ui] kpi-columns="${this['kpi-columns']}" out of range — clamping to "4".`,
+      );
+      this.#internalUpdate = true;
+      try { this['kpi-columns'] = '4'; } finally { this.#internalUpdate = false; }
+    }
+    if (!VALID_CHART_SPLIT.has(this['chart-split'])) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[dashboard-layout-ui] chart-split="${this['chart-split']}" not in enum — clamping to "".`,
+      );
+      this.#internalUpdate = true;
+      try { this['chart-split'] = ''; } finally { this.#internalUpdate = false; }
+    }
+  }
+
+  // ── Internal: aria-busy + gap wiring ────────────────────────────
+
+  #syncAriaBusy() {
+    if (this.loading) {
+      this.setAttribute('aria-busy', 'true');
+    } else {
+      this.removeAttribute('aria-busy');
+    }
+  }
+
+  /**
+   * Map the [gap="N"] attribute to the public --dashboard-layout-gap
+   * custom property. The CSS reads `var(--dashboard-layout-gap, …)`
+   * so empty / unset falls back to the density-modulated default.
+   */
+  #applyGapAttr() {
+    const g = (this.gap || '').trim();
+    if (g === '') {
+      this.style.removeProperty('--dashboard-layout-gap');
+      return;
+    }
+    // Accept numeric 1..6 (mapped to --a-space-N) or pass through any
+    // explicit token-style value. Out-of-range numeric falls through
+    // to no-op so authors don't get a silent broken layout.
+    if (/^[1-6]$/.test(g)) {
+      this.style.setProperty('--dashboard-layout-gap', `var(--a-space-${g})`);
+    } else {
+      // Allow consumer to pass a literal var() / length; trust the input.
+      this.style.setProperty('--dashboard-layout-gap', g);
+    }
+  }
+
+  // ── Internal: region-empty transition tracking ──────────────────
+
+  #snapshotRegions() {
+    for (const slot of REGION_SLOTS) {
+      this.#regionPopulated[slot] = !!this.querySelector(`:scope > [slot="${slot}"]`);
+    }
+  }
+
+  #onMutate(_records) {
+    // Coarse-grained: re-check every region after any childList
+    // mutation. Cardinality is small (5 slots) and the operation is
+    // a single CSS selector lookup; cheap enough to avoid record diffing.
+    for (const slot of REGION_SLOTS) {
+      const hadContent = this.#regionPopulated[slot];
+      const hasContent = !!this.querySelector(`:scope > [slot="${slot}"]`);
+      if (hadContent && !hasContent) {
+        this.dispatchEvent(new CustomEvent('region-empty', {
+          bubbles: true,
+          detail: { region: slot },
+        }));
+      }
+      this.#regionPopulated[slot] = hasContent;
+    }
+  }
+}
+
+if (!customElements.get('dashboard-layout-ui')) {
+  customElements.define('dashboard-layout-ui', UIDashboardLayout);
+}

package/dashboard/dashboard-layout/dashboard-layout.yaml

@@ -0,0 +1,374 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIDashboardLayout
+tag: dashboard-layout-ui
+status: experimental
+component: DashboardLayout
+category: layout
+version: 1
+description: |
+  Module-tier dashboard-body composite. Crystallizes the recurring
+  "toolbar + KPI grid + chart area + table" dashboard layout into a
+  single primitive with four named regions (toolbar / kpis / charts /
+  table) plus an optional aside column. Each region is filled by
+  consumer-supplied <card-ui>s; the composite owns band sizing,
+  responsive breakpoints, and a [density] knob that propagates to
+  every descendant primitive via the parametric --a-density cascade.
+
+  Sits inside an <admin-page-body>; replaces the hand-rolled
+  <col-ui gap="4"> + nested <grid-ui> + <card-ui> chains every
+  analytics consumer reinvents today. Per ADR-0033 (Light-DOM
+  substrate) — slot= attributes are decorative metadata; CSS rules
+  match `:scope > [slot="X"]` to position bands in DOM order.
+
+  Spec: .claude/docs/specs/implementation-ready/SPEC-018-dashboard-layout.md.
+
+# Per ADR-0027 — composites that programmatically create primitives
+# do NOT auto-import them. The consumer (app shell or demo page) must
+# explicitly import each composed primitive.
+composes:
+  - card-ui
+  - grid-ui
+  - row-ui
+  - stat-ui
+  - chart-ui
+  - table-ui
+
+props:
+  density:
+    description: |
+      Spacing scale — propagates --a-density to descendant primitives
+      via CSS custom-property cascade. Empty string inherits whatever
+      density is in effect on an ancestor (the default — respects an
+      app-level density theme). `compact` / `comfortable` / `spacious`
+      explicitly override.
+    type: string
+    default: ""
+    enum:
+      - ""
+      - comfortable
+      - compact
+      - spacious
+    reflect: true
+
+  kpi-columns:
+    description: |
+      Target column count for the KPI band at desktop width. Range 2-6;
+      out-of-range values fall back to 4. Container-query collapse
+      reduces this at narrower widths (≤48em → 2; ≤32em → 1).
+    type: string
+    default: "4"
+    enum:
+      - "2"
+      - "3"
+      - "4"
+      - "5"
+      - "6"
+    reflect: true
+
+  chart-split:
+    description: |
+      Chart-band column split. Empty string = single full-width chart;
+      `2` = two equal columns; `2:1` / `3:2` / `3:1` = asymmetric
+      ratios. Collapses to single column at narrow widths (≤48em).
+    type: string
+    default: ""
+    enum:
+      - ""
+      - "2"
+      - "2:1"
+      - "3:2"
+      - "3:1"
+    reflect: true
+
+  loading:
+    description: |
+      Marks the composite as data-loading. Sets aria-busy=true on the
+      host and dims slotted children to 60% opacity with pointer-events
+      suppressed. Skeletons inside slotted cards continue to render
+      normally; the dim is on top of them.
+    type: boolean
+    default: false
+    reflect: true
+
+  gap:
+    description: |
+      Override band-to-band vertical gap. Empty string = the
+      density-modulated default (--a-space-4 at comfortable). Numeric
+      `1`..`6` selects the corresponding --a-space-N step.
+    type: string
+    default: ""
+    reflect: true
+
+events:
+  density-change:
+    description: |
+      Fired when [density] changes (programmatic or via setDensity()).
+      Bubbles; detail.density carries the new value.
+    detail:
+      density:
+        type: string
+        description: The new density value (comfortable / compact / spacious).
+
+  region-empty:
+    description: |
+      Fired when a slot transitions from having content to being empty
+      (consumer-driven removal of the last child for that slot).
+      Useful for parent-level adjust-layout logic.
+    detail:
+      region:
+        type: string
+        description: The slot name that became empty (toolbar / kpis / charts / table / aside).
+
+slots:
+  toolbar:
+    description: |
+      Top band — filter chips, segmented date range, global controls.
+      Typically a single <row-ui> or <date-range-selector-ui> (SPEC-019).
+      Collapses when empty (no row reserved).
+
+  kpis:
+    description: |
+      KPI band — typically a wrapper element containing N <card-ui>
+      instances each with one <stat-ui>. The composite drives the
+      grid template via [kpi-columns]. Collapses when empty.
+
+  charts:
+    description: |
+      Chart band — wrapper containing 1-3 <card-ui> with <chart-ui>.
+      [chart-split] drives the grid columns. Collapses when empty.
+
+  table:
+    description: |
+      Table band — typically a single <card-ui slot="table"> containing
+      <table-ui> and optional <pagination-ui> in the footer. Full-bleed
+      across the main column. Collapses when empty.
+
+  aside:
+    description: |
+      Optional right-side panel (e.g., live activity feed). When set,
+      promotes the host to a 2-column grid with the aside as a sticky
+      right column on desktop. Collapses when empty.
+
+states:
+  - name: idle
+    description: Default; all regions interactive.
+  - name: loading
+    description: Data fetch in progress; aria-busy=true; content dimmed.
+    attribute: loading
+  - name: compact
+    description: Compact-density variant; tighter band gaps + density cascade.
+    attribute: density
+  - name: spacious
+    description: Spacious-density variant; looser band gaps + density cascade.
+    attribute: density
+
+traits: []
+
+tokens:
+  --dashboard-layout-gap:
+    description: Band-to-band vertical gap.
+    default: var(--a-space-4)
+  --dashboard-layout-kpi-gap:
+    description: Inter-card gap inside the KPI band.
+    default: var(--a-space-2)
+  --dashboard-layout-chart-gap:
+    description: Inter-card gap inside the chart band.
+    default: var(--a-space-4)
+  --dashboard-layout-aside-width:
+    description: Aside column width when [slot="aside"] is present.
+    default: 20em
+  --dashboard-layout-padding:
+    description: Outer padding around the composite.
+    default: "0"
+
+requiredIcons: []
+
+a2ui:
+  rules:
+    - rule: |
+        DashboardLayout MUST receive children via the four named slots
+        (toolbar / kpis / charts / table) plus the optional aside.
+        Children without a [slot] attribute will not render in any band.
+      reason: Named-region slot contract.
+    - rule: |
+        DashboardLayout[kpi-columns] MUST be 2-6. Out-of-range values
+        fall back to the default 4. Eight cards in a row is too narrow
+        to be legible at typical container widths; container queries
+        collapse the band to 2 columns ≤48em and 1 column ≤32em.
+      reason: KPI-column range contract.
+    - rule: |
+        DashboardLayout[chart-split] MUST be one of the documented
+        enum strings — "" (full-width) / 2 / 2:1 / 3:2 / 3:1.
+      reason: Chart-split enum contract.
+    - rule: |
+        A DashboardLayout SHOULD sit inside AdminPageBody for the
+        canonical chrome stack. Top-level placement is allowed for
+        surface-only demos but not the production shape.
+      reason: Canonical composition.
+    - rule: |
+        A DashboardLayout MUST NOT contain another DashboardLayout as
+        a descendant. Two parametric-density containers fight over the
+        --a-density cascade. For nested dashboards use sibling
+        DashboardLayouts switched by Tabs.
+      reason: No-nesting invariant.
+
+anti_patterns:
+  - description: |
+      Child without a [slot] attribute. Lands in the implicit default
+      region and breaks the band layout. Every direct child MUST
+      declare its slot — toolbar / kpis / charts / table / aside.
+    wrong: |
+      <dashboard-layout-ui>
+        <card-ui><!-- no slot -->...</card-ui>
+      </dashboard-layout-ui>
+    right: |
+      <dashboard-layout-ui>
+        <card-ui slot="kpis">...</card-ui>
+      </dashboard-layout-ui>
+    rule: |
+      Every direct child of dashboard-layout-ui declares its slot.
+
+  - description: |
+      Nested DashboardLayout. Two density containers fight over the
+      --a-density cascade. The inner one re-creates a 2-column layout
+      inside a charts band, which is incoherent.
+    wrong: |
+      <dashboard-layout-ui>
+        <dashboard-layout-ui slot="charts">...</dashboard-layout-ui>
+      </dashboard-layout-ui>
+    right: |
+      <tabs-ui>
+        <tab-panel-ui><dashboard-layout-ui>...</dashboard-layout-ui></tab-panel-ui>
+        <tab-panel-ui><dashboard-layout-ui>...</dashboard-layout-ui></tab-panel-ui>
+      </tabs-ui>
+    rule: |
+      For nested dashboards, use sibling DashboardLayouts switched by
+      Tabs — not DashboardLayout inside DashboardLayout.
+
+  - description: |
+      kpi-columns out of range. Eight cards in a row is too narrow
+      to be legible at typical container widths; the container-query
+      collapse (≤48em → 2 cols, ≤32em → 1 col) won't help when N is
+      already that large at desktop.
+    wrong: |
+      <dashboard-layout-ui kpi-columns="8">...</dashboard-layout-ui>
+    right: |
+      <dashboard-layout-ui kpi-columns="4">...</dashboard-layout-ui>
+    rule: |
+      kpi-columns ∈ {2,3,4,5,6}. Split into 2 rows of 4 by composing
+      2 DashboardLayouts vertically if 8 cards are truly necessary.
+
+examples:
+  - name: canonical-analytics-dashboard
+    description: |
+      KPI-strip + 2:1 chart split + table band inside an admin page.
+    a2ui: |
+      [
+        {
+          "id": "dash-1",
+          "component": "DashboardLayout",
+          "density": "",
+          "kpiColumns": "4",
+          "chartSplit": "2:1",
+          "children": ["dash-toolbar", "dash-kpis", "dash-charts", "dash-table"]
+        },
+        {
+          "id": "dash-toolbar",
+          "component": "Row",
+          "slot": "toolbar"
+        },
+        {
+          "id": "dash-kpis",
+          "component": "Group",
+          "slot": "kpis"
+        },
+        {
+          "id": "dash-charts",
+          "component": "Group",
+          "slot": "charts"
+        },
+        {
+          "id": "dash-table",
+          "component": "Card",
+          "slot": "table"
+        }
+      ]
+
+  - name: compact-six-kpi
+    description: |
+      Six-KPI dashboard at compact density (power-user view).
+    a2ui: |
+      [
+        {
+          "id": "dash-2",
+          "component": "DashboardLayout",
+          "density": "compact",
+          "kpiColumns": "6"
+        }
+      ]
+
+  - name: with-aside-feed
+    description: |
+      Dashboard with a sticky aside column carrying a live activity feed.
+    a2ui: |
+      [
+        {
+          "id": "dash-3",
+          "component": "DashboardLayout",
+          "chartSplit": "2",
+          "children": ["d3-aside"]
+        },
+        {
+          "id": "d3-aside",
+          "component": "Card",
+          "slot": "aside"
+        }
+      ]
+
+keywords:
+  - dashboard
+  - dashboard-layout
+  - analytics
+  - kpi-grid
+  - chart-area
+  - dashboard-body
+  - admin-dashboard
+  - reporting
+  - metrics-page
+  - layout-container
+
+synonyms:
+  dashboard:
+    - analytics
+    - report
+    - overview
+    - metrics
+  layout:
+    - container
+    - grid
+    - frame
+    - shell
+  kpi:
+    - metric
+    - stat
+    - measure
+  charts:
+    - chart-area
+    - viz
+    - graphs
+  tags:
+    - DashboardLayout
+    - Dashboard
+    - AnalyticsDashboard
+    - MetricsDashboard
+
+related:
+  - AdminPageBody
+  - AdminPage
+  - Card
+  - Grid
+  - Stat
+  - Chart
+  - Table
+  - DateRangeSelector