@adia-ai/web-components 0.8.43 → 0.8.44

package/components/chart/chart.css

@@ -130,7 +130,25 @@
      NOTE: size="sm|md|lg" used to cap max-width (25/50/100%) which was a bug:
      a chart in a 160px grid cell would be clamped to 40px wide. Size now
      only tunes typography/padding/density inside #dims(); layout is the
-     responsibility of the consumer. */
+     responsibility of the consumer.
+
+     ADR-0074 (Chart 2.0 ratio grammar, gh#1624 plan step 1) — [ratio]
+     PINS one of three named buckets (3:2|1:1|2:3), overriding whatever
+     height the box would otherwise get; unset auto-snaps by classifying
+     the chart's own live rendered aspect against two midpoint boundaries.
+     Because this primitive derives height in JS from a measured
+     clientWidth/clientHeight rather than from CSS layout (see the note
+     above — the SAME reason `size` stopped clamping max-width), the
+     ratified "CSS container query" mechanism is realized inside
+     chart.class.js's #dims() (the same measurement pass the pre-existing
+     ResizeObserver already drives), not as a literal `@container` rule
+     here: `container-type: size` (required to query aspect-ratio, not
+     just inline-size like the legend query below) would force block-size
+     containment on :scope, collapsing any chart with no explicit height
+     set today — the common case across this file's own demo gallery.
+     Same ratified grammar/snap-boundary/override contract either way;
+     `#dims()` reflects the resolved bucket onto the host as
+     `data-ratio-resolved` for later waves' per-type CSS to key off. */
 
   /* Debug resize handle */
   :scope[resize] {
@@ -158,6 +176,16 @@
     fill: none;
   }
 
+  /* REQ-R-007 (Chart 2.0 color-role plan) — "denser 1:1/2:3 layouts need a
+     quieter gridline than spacious 3:2": both buckets already thin the
+     gridline COUNT (#gridAndAxes' thinGrid, chart.class.js); this dims the
+     remaining lines' CONTRAST tier a step further rather than minting a
+     second gridline token. */
+  :scope[data-ratio-resolved="1:1"] [data-chart-grid],
+  :scope[data-ratio-resolved="2:3"] [data-chart-grid] {
+    opacity: 0.72;
+  }
+
   /* ── Y-axis labels ── */
 
   [data-y-label] {
@@ -387,6 +415,51 @@
     stroke: none;
   }
 
+  /* REQ-R-003 (pie, 1:1) — "legend as a ring of labels around the pie":
+     one label per slice, positioned OUTSIDE the ring (chart.class.js sizes
+     the pie itself smaller at 1:1 to leave this room). Sits on the plain
+     chart background, not on a colored slice fill, so it uses the ordinary
+     on-surface label token rather than treemap/donut's on-color token. */
+  [data-ring-label] {
+    fill: var(--chart-label);
+    font-weight: var(--a-weight-medium);
+    pointer-events: none;
+  }
+
+  /* REQ-R-003 (pie/donut, 1:1) — the ring of labels (pie) / maximized ring
+     + center-stat (donut) already function as the legend at 1:1, so the
+     always-visible inline `[data-legend]` block below the chart would
+     duplicate that information and compete for the same square footprint;
+     suppress it at 1:1 only. Tooltip-on-hover and (donut) the center-stat
+     text both stay unaffected either way.
+
+     REQ-R-003 (radial-bar, 1:1 "legend as ring") — same rationale, one
+     ring's worth of `[data-ring-label]` text already IS the legend at 1:1
+     (chart.class.js).
+
+     REQ-R-003 (multi-line, 3:2 "all series labeled inline at line end (no
+     legend needed)") — same rationale, inverted axis: multi-line's own
+     inline end-labels ([data-series-end-label]) only render at 3:2, so
+     THAT'S the ratio whose internal legend is redundant and suppressed;
+     1:1/2:3 drop the end-labels and rely on the ordinary legend instead
+     (unsuppressed there), matching the matrix's own progressive
+     de-emphasis for this type. */
+  :scope[type="pie"][data-ratio-resolved="1:1"] [data-legend],
+  :scope[type="donut"][data-ratio-resolved="1:1"] [data-legend],
+  :scope[type="radial-bar"][data-ratio-resolved="1:1"] [data-legend],
+  :scope[type="multi-line"][data-ratio-resolved="3:2"] [data-legend] {
+    display: none;
+  }
+
+  /* REQ-R-003 (multi-line, 3:2) — the inline end-of-line series label the
+     suppression rule above pairs with. Colored per-series via the same
+     `--color-{key}` fallback-chain hook every other series-keyed element
+     in this file uses (chart.class.js's `#seriesFill`). */
+  [data-series-end-label] {
+    font-weight: var(--a-weight-medium);
+    pointer-events: none;
+  }
+
   /* ── Donut center text ── */
 
   [data-donut-total] {
@@ -553,6 +626,15 @@
     fill: var(--chart-label);
   }
 
+  /* REQ-R-003 (funnel, 1:1) — "stage labels inline": placed inside the
+     colored trapezoid body instead of the plain chart background, so it
+     needs the on-color label token (same convention treemap's own
+     in-tile label already uses) rather than the ordinary chart-fg. */
+  [data-funnel-label-inline] {
+    fill: var(--a-canvas-0);
+    font-weight: var(--a-weight-semibold);
+  }
+
   /* ── Treemap ──
      Flat tiles — each rect filled by the data palette. Labels +
      values appear only on tiles large enough to fit them (size
@@ -625,6 +707,22 @@
     stroke-width: 2;
   }
 
+  /* REQ-R-003 (composed, 2:3) — the sparkline-inset backing + line. Quiet
+     container-low surface (REQ-R-007's own "quiet surfaces" role) so the
+     inset reads as a distinct panel without competing with the primary
+     bar series for visual weight. */
+  [data-composed-inset-bg] {
+    fill: var(--md-sys-color-neutral-container-low);
+  }
+  [data-composed-inset-line] {
+    fill: none;
+    stroke-width: calc(var(--chart-line-width) - 0.5);
+  }
+  [data-composed-inset-label] {
+    fill: var(--chart-label);
+    font-family: var(--chart-font);
+  }
+
   /* ── Sparkline container ──
      `height: 100%` fills an explicit parent height (e.g. when the
      containing section is a flex-grow item inside card-ui). Falls
@@ -640,6 +738,33 @@
   :scope[type="segments"] svg {
     height: 1.5rem;
   }
+
+  /* REQ-R-003 (segments, 2:3) — "tall vertical stacked bars": the
+     horizontal default's fixed-HEIGHT/fluid-WIDTH strip inverts to a
+     fixed-WIDTH/fluid-HEIGHT column — same technique every other type's
+     own base `svg { width: 100%; height: auto }` rule already uses
+     (a definite dimension on one axis, `auto` on the other so the SVG's
+     own intrinsic viewBox aspect ratio solves the rest), just with the
+     definite axis swapped. `height: 100%` was tried first and produces a
+     wrong render: chart-ui has no definite height of its own in ordinary
+     use for `height: 100%` to resolve against, and the actual resolved
+     value in testing came from an unrelated ancestor percentage chain —
+     visually correct-looking proportions by coincidence, but the wrong
+     mechanism (caught by a real browser probe, not the Vitest DOM
+     assertions above, which never render CSS at all). */
+  :scope[type="segments"][data-ratio-resolved="2:3"] svg {
+    width: 2rem;
+    height: auto;
+    margin-inline: auto;
+  }
+
+  /* REQ-R-003 (segments, 2:3) — "legend stacked": one item per line
+     instead of the default wrapped row, matching the vertical strip's own
+     tall/narrow footprint. */
+  :scope[type="segments"][data-ratio-resolved="2:3"] [data-legend] {
+    flex-direction: column;
+    align-items: flex-start;
+  }
   [data-sparkline] {
     display: block;
     width: 100%;
@@ -694,6 +819,31 @@
   [data-hit] { cursor: default; }
 }
 
+/* ─────────────────────────────────────────────────────────────────
+   REQ-R-001/R-007 (Chart 2.0 full-bleed anatomy + color-role plan) —
+   full-bleed background depth.
+
+   Deliberately OUTSIDE `@scope (chart-ui)`: the rule needs to match an
+   ANCESTOR (`card-ui[padding="none"]`) of the scoping root, which a
+   selector inside the scope block can't express against :scope itself.
+   card-ui's own `padding="none"` already zeroes its inset (`--card-inset:
+   0`, card.css) — a chart filling that slot at 100%×100% was already
+   edge-to-edge (REQ-R-001's two pre-existing mechanisms), but with a fully
+   transparent background it read as "no background" rather than a
+   deliberate flush surface. This tints it with a quiet container-low role
+   (ADR-0064/0073's ladder) — REQ-P-002's own opt-in requirement is what
+   the `card-ui[padding="none"]` ancestor gate enforces: a chart in a
+   normal-padding card never matches this selector, so its rendering is
+   unchanged (additive, not a new default). --md-sys-color-neutral-
+   container-low was chosen over -surface-dim (the SPEC's other named
+   option) for a closer value-step to the ambient canvas so the categorical
+   series data stays the visual foreground.
+   ───────────────────────────────────────────────────────────────── */
+card-ui[padding="none"] chart-ui {
+  background: var(--md-sys-color-neutral-container-low);
+  border-radius: inherit;
+}
+
 /* ─────────────────────────────────────────────────────────────────
    Chart tooltip (top-layer, outside @scope)
 

package/components/chart/chart.d.ts

@@ -38,6 +38,8 @@ export class UIChart extends UIElement {
   noGrid: boolean;
   /** Hide value labels. Canonical spelling (ADR-0063, gh#1563) — the deprecated `hideValues` dual-read shim was cut in 0.8.43 (gh#1617). */
   noValues: boolean;
+  /** Chart 2.0 aspect-ratio bucket (ADR-0074). Unset (default) auto-snaps to the nearest of the three studied ratios by comparing the chart's own live box aspect against two midpoint boundaries (5:4 between 3:2/1:1, 4:5 between 1:1/2:3) — never interpolated; the resolved bucket reflects onto the host as `data-ratio-resolved`. Setting `ratio` explicitly pins that bucket regardless of the box's actual aspect, overriding the auto-snap. Orthogonal to `size` (overall scale) and `type`/`color` (ADR-0064's family axis) — this attribute lands the grammar + snap plumbing only; per-type studied renderings per bucket are later waves (gh#1624 plan steps 2-4). */
+  ratio: '3:2' | '1:1' | '2:3';
   /** Multi-line only. Names one series key (matching a `y` key) to render at full strength — area fill + full-opacity line. Every other series drops its area fill and renders line-only at --chart-deemphasized-opacity. Empty (default) applies full treatment to every series, unchanged from pre-gh#561 behavior. */
   seriesEmphasis: string;
   /** Chart size */
@@ -48,6 +50,10 @@ export class UIChart extends UIElement {
   x: string;
   /** Y-axis key(s), comma-separated for multi-series */
   y: string;
+  /** Pins the value-axis domain ceiling for cartesian types (bar, line, area, scatter, multi-line, stacked-bar, grouped-bar, composed). Unset (default, null) keeps today's auto-scale ceiling (the data max). Pairs with `yMin` to pin the full domain; either may be set alone. N/A for radial/part-to-whole types — see `yMin` (gh#1690). A datum outside the pinned domain is CLAMPED to the nearest edge for rendering (the value label/tooltip still shows the real value) rather than escaping the plot box. */
+  yMax: number | null;
+  /** Pins the value-axis domain floor for cartesian types (bar, line, area, scatter, multi-line, stacked-bar, grouped-bar, composed). Unset (default, null) already floors a positive series at 0 (the pre-1690 behavior, unchanged) — a migrating d3 consumer's own "pin the floor to 0" habit is the built-in default, not something to configure. Pin `y-min` explicitly for three OTHER cases: (1) zooming a narrow window — e.g. `y-min="0.9" y-max="1"` magnifies a percent series clustered near 92-95%, which reads flatter against the full auto-scaled [0,1] domain; (2) a mixed-sign series, where the unpinned floor never goes below 0 and negative values clip at the axis; (3) aligning two charts to one shared scale for a fair comparison. N/A for radial/part-to-whole types (pie, donut, radar, radial-bar, gauge, funnel, treemap, sankey, segments, sparkline) — those never read a shared linear value axis, so this prop is a no-op there (gh#1690). A datum outside the pinned domain is CLAMPED to the nearest edge for rendering (the value label/tooltip still shows the real value) rather than escaping the plot box. */
+  yMin: number | null;
 
   addEventListener(type: 'chart-hover', listener: (ev: ChartHoverEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'chart-leave', listener: (ev: ChartLeaveEvent) => unknown, options?: boolean | AddEventListenerOptions): void;

package/components/chart/chart.yaml

@@ -96,6 +96,25 @@ props:
       - sm
       - md
       - lg
+  ratio:
+    description: >-
+      Chart 2.0 aspect-ratio bucket (ADR-0074). Unset (default) auto-snaps
+      to the nearest of the three studied ratios by comparing the chart's
+      own live box aspect against two midpoint boundaries (5:4 between
+      3:2/1:1, 4:5 between 1:1/2:3) — never interpolated; the resolved
+      bucket reflects onto the host as `data-ratio-resolved`. Setting
+      `ratio` explicitly pins that bucket regardless of the box's actual
+      aspect, overriding the auto-snap. Orthogonal to `size` (overall
+      scale) and `type`/`color` (ADR-0064's family axis) — this attribute
+      lands the grammar + snap plumbing only; per-type studied renderings
+      per bucket are later waves (gh#1624 plan steps 2-4).
+    type: string
+    default: ""
+    enum:
+      - "3:2"
+      - "1:1"
+      - "2:3"
+    reflect: true
   smooth:
     description: Line smoothing factor
     type: number
@@ -138,6 +157,44 @@ props:
     type: boolean
     default: false
     reflect: true
+  yMin:
+    description: >-
+      Pins the value-axis domain floor for cartesian types (bar, line,
+      area, scatter, multi-line, stacked-bar, grouped-bar, composed).
+      Unset (default, null) already floors a positive series at 0 (the
+      pre-1690 behavior, unchanged) — a migrating d3 consumer's own
+      "pin the floor to 0" habit is the built-in default, not something
+      to configure. Pin `y-min` explicitly for three OTHER cases: (1)
+      zooming a narrow window — e.g. `y-min="0.9" y-max="1"` magnifies a
+      percent series clustered near 92-95%, which reads flatter against
+      the full auto-scaled [0,1] domain; (2) a mixed-sign series, where
+      the unpinned floor never goes below 0 and negative values clip at
+      the axis; (3) aligning two charts to one shared scale for a fair
+      comparison. N/A for radial/part-to-whole types (pie, donut, radar,
+      radial-bar, gauge, funnel, treemap, sankey, segments, sparkline) —
+      those never read a shared linear value axis, so this prop is a
+      no-op there (gh#1690).
+      A datum outside the pinned domain is CLAMPED to the nearest edge
+      for rendering (the value label/tooltip still shows the real value)
+      rather than escaping the plot box.
+    type: number
+    default: null
+    attribute: y-min
+    reflect: true
+  yMax:
+    description: >-
+      Pins the value-axis domain ceiling for cartesian types (bar, line,
+      area, scatter, multi-line, stacked-bar, grouped-bar, composed).
+      Unset (default, null) keeps today's auto-scale ceiling (the data
+      max). Pairs with `yMin` to pin the full domain; either may be set
+      alone. N/A for radial/part-to-whole types — see `yMin` (gh#1690).
+      A datum outside the pinned domain is CLAMPED to the nearest edge
+      for rendering (the value label/tooltip still shows the real value)
+      rather than escaping the plot box.
+    type: number
+    default: null
+    attribute: y-max
+    reflect: true
   x:
     description: Data key for x-axis (category) values
     type: string

package/components/chart-legend/chart-legend.a2ui.json

@@ -14,7 +14,7 @@
   ],
   "properties": {
     "items": {
-      "description": "JSON array of {key, label, slot?, pct?} legend items. Takes precedence over [for] when both are provided.",
+      "description": "JSON array of {key, label, slot?, pct?, deemphasized?} legend items. Takes precedence over [for] when both are provided. `deemphasized` (REQ-R-007) mutes the row's swatch/label to the same muted-neutral tier chart-ui's own internal legend uses for a de-emphasized series (e.g. `composed@1:1`'s secondary line) — mirrored automatically from a `[for]`-bound chart's own `.legendData`, or settable explicitly here.",
       "type": "string",
       "default": ""
     },
@@ -41,7 +41,7 @@
       "default": "hide"
     },
     "position": {
-      "description": "Layout hint — drives flex-direction. Actual placement follows DOM order.",
+      "description": "Layout hint — drives flex-direction. Actual placement follows DOM order. Superseded by a resolved `ratio` bucket (below) whenever one is in effect; this is the pre-ADR-0074 fallback for a legend with neither an explicit `ratio` nor a `[for]`-bound chart.",
       "type": "string",
       "enum": [
         "top",
@@ -51,6 +51,16 @@
       ],
       "default": "bottom"
     },
+    "ratio": {
+      "description": "Chart 2.0 legend layout bucket (ADR-0074, gh#1624 plan step 5, REQ-R-005): 3:2 renders a horizontal row, 1:1 a wrapped 2-column grid, 2:3 a vertical stacked list. An explicit value PINS the bucket regardless of any bound chart. Unset (default) auto-mirrors the `[for]`-bound chart's own resolved `data-ratio-resolved` bucket — the legend never runs its own container-query classification, since its own box is typically a thin strip with no studied aspect of its own. With neither a pin nor a bound chart, no bucket resolves and `position`'s flex-direction rules apply unchanged. The resolved bucket reflects read-only onto the host as `data-ratio-resolved`, mirroring chart-ui's own convention.",
+      "type": "string",
+      "enum": [
+        "3:2",
+        "1:1",
+        "2:3"
+      ],
+      "default": ""
+    },
     "shape": {
       "description": "Swatch shape. Maps to badge-ui's icon for dot/square variants.",
       "type": "string",
@@ -99,6 +109,11 @@
         "a2ui": "[\n  {\n    \"id\": \"legend\", \"component\": \"ChartLegend\",\n    \"shape\": \"dot\",\n    \"items\": \"[{\\\"key\\\":\\\"revenue\\\",\\\"label\\\":\\\"Revenue\\\",\\\"slot\\\":0},{\\\"key\\\":\\\"users\\\",\\\"label\\\":\\\"Users\\\",\\\"slot\\\":1}]\"\n  }\n]",
         "name": "standalone-with-items"
       },
+      {
+        "description": "Standalone legend pinned to the 1:1 (2-col grid) layout bucket.",
+        "a2ui": "[\n  {\n    \"id\": \"legend\", \"component\": \"ChartLegend\",\n    \"ratio\": \"1:1\",\n    \"items\": \"[{\\\"key\\\":\\\"revenue\\\",\\\"label\\\":\\\"Revenue\\\",\\\"slot\\\":0},{\\\"key\\\":\\\"users\\\",\\\"label\\\":\\\"Users\\\",\\\"slot\\\":1},{\\\"key\\\":\\\"churn\\\",\\\"label\\\":\\\"Churn\\\",\\\"slot\\\":2},{\\\"key\\\":\\\"nps\\\",\\\"label\\\":\\\"NPS\\\",\\\"slot\\\":3}]\"\n  }\n]",
+        "name": "ratio-pinned-grid"
+      },
       {
         "description": "Legend mirrors a named chart's series data.",
         "a2ui": "[\n  {\n    \"id\": \"root\", \"component\": \"Column\",\n    \"children\": [\"chart\", \"legend\"]\n  },\n  {\n    \"id\": \"chart\", \"component\": \"Chart\",\n    \"type\": \"multi-line\", \"x\": \"month\", \"y\": \"revenue,users\"\n  },\n  {\n    \"id\": \"legend\", \"component\": \"ChartLegend\",\n    \"for\": \"chart\",\n    \"shape\": \"line\",\n    \"position\": \"bottom\"\n  }\n]",

package/components/chart-legend/chart-legend.class.js

@@ -34,7 +34,27 @@
  *                aren't representable as icon glyphs.
  *   position   — top | bottom | left | right. Layout hint; actual placement
  *                is where the element is placed in the DOM. Drives
- *                flex-direction.
+ *                flex-direction. Superseded by a resolved `ratio` bucket
+ *                (below) whenever one is in effect — `position` is the
+ *                pre-ADR-0074 fallback for a legend with neither an
+ *                explicit `ratio` nor a `[for]`-bound chart.
+ *   ratio      — '' | 3:2 | 1:1 | 2:3 (ADR-0074, gh#1624 plan step 5).
+ *                Explicit value PINS the legend's own layout bucket
+ *                (row / 2-col grid / vertical list — REQ-R-005) regardless
+ *                of any bound chart. Unset (default) auto-mirrors the
+ *                `[for]`-bound chart's own resolved `data-ratio-resolved`
+ *                bucket — the legend does not run its own container-query
+ *                classification (REQ-R-005: "follows the per-type legend
+ *                position column rather than introducing a separate
+ *                legend-only ratio contract"); a legend's own box is
+ *                typically a thin strip whose aspect carries no studied
+ *                meaning of its own. With neither a pin nor a bound chart,
+ *                no bucket resolves and `position`'s pre-existing
+ *                flex-direction rules apply unchanged (zero regression for
+ *                standalone legends that predate this attribute). The
+ *                resolved bucket is reflected read-only as
+ *                `data-ratio-resolved`, mirroring chart-ui's own
+ *                convention.
  *   interactive — canonical opt-in spelling (ADR-0063, gh#1563). Rows
  *                default interactive (`role="button"` badges that toggle
  *                on click + Enter/Space) until the 0.9.0 default-inversion
@@ -49,6 +69,12 @@
  *            interactive. `active` is the new state (true=visible).
  */
 
+// ADR-0074's three ratified ratio buckets — same enum chart-ui pins/resolves
+// to (CHART_RATIOS in chart.class.js). Kept as a Set here rather than
+// re-importing chart.class.js: the legend must resolve standalone (no
+// chart-ui ancestor required, per its own "renders standalone" contract).
+const RATIO_BUCKETS = new Set(['3:2', '1:1', '2:3']);
+
 import { UIElement } from '../../core/element.js';
 
 export class UIChartLegend extends UIElement {
@@ -60,6 +86,9 @@ export class UIChartLegend extends UIElement {
     items:    { type: String,  default: '',       reflect: false },
     shape:    { type: String,  default: 'dot',    reflect: true },
     position: { type: String,  default: 'bottom', reflect: true },
+    // ADR-0074 (gh#1624 plan step 5) — explicit pin; see the class-doc
+    // comment above for the full pin > mirror > position-fallback chain.
+    ratio:    { type: String,  default: '',       reflect: true },
     // ADR-0063 (gh#1563) — `interactive` (opt-in) is the canonical
     // positively-named boolean; the deprecated `static` opt-out alias was
     // cut in 0.8.43 (gh#1617). Deliberately keeps its `true` default:
@@ -122,6 +151,25 @@ export class UIChartLegend extends UIElement {
     this.#targetListener = null;
   }
 
+  /* ── Ratio resolution (ADR-0074, gh#1624 plan step 5) ─────────────── */
+
+  /**
+   * Pin > mirror > none. A pinned `[ratio]` always wins; absent that, a
+   * `[for]`-bound chart's own `data-ratio-resolved` is mirrored (set by
+   * the SAME `#renderChart()` pass that fires the `legend-update` event
+   * this class already listens for — the mirror is always reading a
+   * value already fresh by the time `#paint()` runs). Neither present →
+   * '' (no bucket resolves; `position`'s pre-existing CSS applies).
+   */
+  #resolveRatio() {
+    if (RATIO_BUCKETS.has(this.ratio)) return this.ratio;
+    if (this.#target) {
+      const mirrored = this.#target.getAttribute('data-ratio-resolved');
+      if (RATIO_BUCKETS.has(mirrored)) return mirrored;
+    }
+    return '';
+  }
+
   /* ── Item source ────────────────────────────────────────────────── */
 
   #resolveItems() {
@@ -142,6 +190,15 @@ export class UIChartLegend extends UIElement {
   /* ── Render ─────────────────────────────────────────────────────── */
 
   #paint() {
+    const resolved = this.#resolveRatio();
+    if (resolved) {
+      if (this.getAttribute('data-ratio-resolved') !== resolved) {
+        this.setAttribute('data-ratio-resolved', resolved);
+      }
+    } else if (this.hasAttribute('data-ratio-resolved')) {
+      this.removeAttribute('data-ratio-resolved');
+    }
+
     const items = this.#resolveItems();
     this.innerHTML = '';
     if (!items.length) return;
@@ -165,6 +222,12 @@ export class UIChartLegend extends UIElement {
       row.setAttribute('text', label);
       if (key) row.setAttribute('data-key', key);
       if (active) row.setAttribute('data-active', '');
+      // REQ-R-007 (Chart 2.0 ratio-and-surface SPEC) — a de-emphasized
+      // series (e.g. composed@1:1's secondary line, Wave C) mutes the
+      // mirrored legend row the same way chart-ui's own internal legend
+      // already mutes its dot (chart.class.js #buildLegend): the muted
+      // neutral token, not the series' categorical color slot.
+      if (item.deemphasized) row.setAttribute('data-deemphasized', '');
       if (this.interactive) {
         row.setAttribute('tabindex', '0');
         row.setAttribute('aria-pressed', active ? 'true' : 'false');
@@ -184,9 +247,11 @@ export class UIChartLegend extends UIElement {
       const swatch = document.createElement('swatch-ui');
       swatch.setAttribute('shape', swatchShape);
       swatch.setAttribute('size', 'sm');
-      const swatchColor = key
-        ? `var(--color-${key}, var(--a-data-${slot}))`
-        : `var(--a-data-${slot})`;
+      const swatchColor = item.deemphasized
+        ? 'var(--md-sys-color-neutral-on-surface-variant)'
+        : key
+          ? `var(--color-${key}, var(--a-data-${slot}))`
+          : `var(--a-data-${slot})`;
       swatch.style.setProperty('--swatch-color', swatchColor);
       row.appendChild(swatch);
 

package/components/chart-legend/chart-legend.css

@@ -35,7 +35,11 @@
   }
 
   /* Position variants — drive flex-direction. DOM placement still wins for
-     actual layout; these tune the internal row direction. */
+     actual layout; these tune the internal row direction. Pre-ADR-0074
+     fallback: superseded below by a resolved [data-ratio-resolved] bucket
+     whenever one is in effect (an explicit [ratio] pin, or a [for]-bound
+     chart's own mirrored bucket) — a legend with neither keeps this exact
+     behavior, unchanged. */
   :scope[position="top"],
   :scope[position="bottom"] {
     flex-direction: row;
@@ -48,6 +52,32 @@
     align-items: flex-start;
   }
 
+  /* Ratio-resolved layout buckets (ADR-0074, gh#1624 plan step 5, REQ-R-005).
+     Same selector specificity as the [position] rules above — placed AFTER
+     them in source order so a resolved bucket always wins the cascade over
+     a stale/default [position] on the same element. */
+
+  /* 3:2 — horizontal row (beside/below the chart). */
+  :scope[data-ratio-resolved="3:2"] {
+    display: flex;
+    flex-direction: row;
+    justify-content: flex-start;
+  }
+
+  /* 1:1 — wrapped 2-column grid. */
+  :scope[data-ratio-resolved="1:1"] {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    align-items: start;
+  }
+
+  /* 2:3 — vertical stacked list. */
+  :scope[data-ratio-resolved="2:3"] {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
   /* Rows are <badge-ui> chips. We override badge-ui's default tokens
      to give them a quieter, click-to-toggle appearance — transparent
      bg by default (so they read as inline text not chips), highlighted
@@ -93,6 +123,16 @@
     opacity: 0.4;
   }
 
+  /* De-emphasized (REQ-R-007) rows — a mirrored chart's own muted series
+     (e.g. composed@1:1's secondary line). Distinct from :not([data-active])
+     above: this is the chart's OWN designed treatment for a still-visible
+     series, not a user-toggled-off one; the swatch color itself is set
+     inline per-row (matches the neutral token, not opacity) so only the
+     label's --badge-fg needs the muted tier here. */
+  badge-ui[data-row][data-deemphasized] {
+    --badge-fg: var(--chart-legend-fg-inactive);
+  }
+
   /* Swatch is composed via <swatch-ui shape="…">; per-shape styling
      lives in swatch.css. The legend just hands its [shape] attr through
      and writes --swatch-color inline. Pre-2026-05-01 this file owned a
@@ -101,3 +141,27 @@
      rule (cascade leak). Composing the primitive moves the styling to
      one place. */
 }
+
+/* ─────────────────────────────────────────────────────────────────
+   gh#1624 plan step 7 — full-bleed × legend horizontal breathing room.
+
+   Deliberately OUTSIDE `@scope (chart-legend-ui)`, same reason as
+   chart.css's own `card-ui[padding="none"] chart-ui` rule: this needs to
+   match an ANCESTOR of the scoping root. `--chart-legend-px` defaults to
+   0 because a legend normally sits inside a card section that already
+   supplies horizontal inset via `--card-inset` (card.css's own
+   margin-based section model); `card-ui[padding="none"]` zeroes that
+   inset CARD-WIDE (every section, not just the chart's), so a legend
+   paired with a full-bleed chart lost its own horizontal clearance too —
+   confirmed via browser probe: badge rows sat ~1px from the card's
+   rounded edge, at real risk of visual crowding against the corner-radius
+   `overflow: hidden` (card.css :scope). The chart itself doesn't need this
+   — its own internal plot margins (REQ-R-004) already supply clearance
+   regardless of the card's inset — but the legend's chip rows have no
+   equivalent internal margin of their own. Restoring `--chart-legend-px`
+   only (not `-py`, which the legend already carries unconditionally) is
+   the minimal fix: vertical spacing between the chart and legend sections
+   is unaffected, only the legend's own left/right clearance is restored. */
+card-ui[padding="none"] chart-legend-ui {
+  --chart-legend-px: var(--a-space-4);
+}

package/components/chart-legend/chart-legend.d.ts

@@ -24,7 +24,7 @@ export interface ChartLegendToggleEventDetail {
 export type ChartLegendToggleEvent = CustomEvent<ChartLegendToggleEventDetail>;
 
 export class UIChartLegend extends UIElement {
-  /** JSON array of {key, label, slot?, pct?} legend items. Takes precedence over [for] when both are provided. */
+  /** JSON array of {key, label, slot?, pct?, deemphasized?} legend items. Takes precedence over [for] when both are provided. `deemphasized` (REQ-R-007) mutes the row's swatch/label to the same muted-neutral tier chart-ui's own internal legend uses for a de-emphasized series (e.g. `composed@1:1`'s secondary line) — mirrored automatically from a `[for]`-bound chart's own `.legendData`, or settable explicitly here. */
   items: string;
   /** id-ref of a chart-ui / heatmap-ui to mirror series from. */
   for: string;
@@ -32,8 +32,10 @@ export class UIChartLegend extends UIElement {
   interactive: boolean;
   /** Series-toggle mode emitted via the `toggle` event. `hide` removes the series from the render; `opacity` fades it. Wired via [for] on chart-ui. */
   onToggle: 'hide' | 'opacity';
-  /** Layout hint — drives flex-direction. Actual placement follows DOM order. */
+  /** Layout hint — drives flex-direction. Actual placement follows DOM order. Superseded by a resolved `ratio` bucket (below) whenever one is in effect; this is the pre-ADR-0074 fallback for a legend with neither an explicit `ratio` nor a `[for]`-bound chart. */
   position: 'top' | 'bottom' | 'left' | 'right';
+  /** Chart 2.0 legend layout bucket (ADR-0074, gh#1624 plan step 5, REQ-R-005): 3:2 renders a horizontal row, 1:1 a wrapped 2-column grid, 2:3 a vertical stacked list. An explicit value PINS the bucket regardless of any bound chart. Unset (default) auto-mirrors the `[for]`-bound chart's own resolved `data-ratio-resolved` bucket — the legend never runs its own container-query classification, since its own box is typically a thin strip with no studied aspect of its own. With neither a pin nor a bound chart, no bucket resolves and `position`'s flex-direction rules apply unchanged. The resolved bucket reflects read-only onto the host as `data-ratio-resolved`, mirroring chart-ui's own convention. */
+  ratio: '3:2' | '1:1' | '2:3';
   /** Swatch shape. Maps to badge-ui's icon for dot/square variants. */
   shape: 'dot' | 'square' | 'line' | 'dashed';
 

package/components/chart-legend/chart-legend.examples.md

@@ -12,11 +12,11 @@
 <chart-legend-ui id="legend-bottom" shape="dot" position="bottom" items='[{"key":"a","label":"Series A","slot":0},{"key":"b","label":"Series B","slot":1},{"key":"c","label":"Series C","slot":2}]'></chart-legend-ui>
 ```
 
-## for — mirror a chart's legendData
+## ratio — mirrors a bound chart's resolved ratio (ADR-0074)
 
 ```html
-<div style="display:flex; flex-direction:column; gap:var(--a-space-2);">
-  <chart-ui id="demo-chart" type="multi-line" x="month" y="revenue,users,churn"></chart-ui>
-  <chart-legend-ui id="legend-for" for="demo-chart" shape="line"></chart-legend-ui>
+<div style="display:flex; flex-direction:column; gap:var(--a-space-2); width:360px;">
+  <chart-ui id="ratio-chart-32" type="multi-line" ratio="3:2" x="month" y="revenue,users,churn"></chart-ui>
+  <chart-legend-ui id="ratio-legend-32" for="ratio-chart-32" shape="line"></chart-legend-ui>
 </div>
 ```