@adia-ai/web-components 0.8.42 → 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

@@ -30,20 +30,16 @@ export class UIChart extends UIElement {
   dots: 'all' | 'none' | 'hover' | 'last';
   /** Number-format mode applied to axis labels + value overlays + donut total + gauge value + treemap value + funnel value + internal tooltip. `abbr` is the legacy 1.2K / 3M format; `decimal` fixes 2 decimals; `currency` prefixes via `--chart-currency-prefix` token (default "$"); `percent` multiplies × 100 and adds a % suffix. */
   format: 'abbr' | 'decimal' | 'currency' | 'percent';
-  /** DEPRECATED (ADR-0063, gh#1563) — use `noAverage` instead. Same meaning, same default; kept working as a dual-read compat shim (one- time console.warn when it's the name that resolves). Removed in 0.9.0. */
-  hideAverage: boolean;
-  /** DEPRECATED (ADR-0063, gh#1563) — use `noGrid` instead. Same meaning, same default; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0. */
-  hideGrid: boolean;
-  /** DEPRECATED (ADR-0063, gh#1563) — use `noValues` instead. Same meaning, same default; kept working as a dual-read compat shim (one- time console.warn when it's the name that resolves). Removed in 0.9.0. */
-  hideValues: boolean;
   /** Show a skeleton placeholder instead of the chart body. Set to true while data is being fetched; clear once data arrives. Preserves the element's aspect-ratio dimensions so the skeleton occupies the same space the chart will fill. Parity with stat-ui[loading] and table-ui[loading] (§FB-12, v0.6.27). */
   loading: boolean;
-  /** When true, suppress the overlaid average line. Canonical spelling (ADR-0063, gh#1563) replacing `hideAverage`. */
+  /** When true, suppress the overlaid average line. Canonical spelling (ADR-0063, gh#1563) — the deprecated `hideAverage` dual-read shim was cut in 0.8.43 (gh#1617). */
   noAverage: boolean;
-  /** Hide gridlines. Canonical spelling (ADR-0063, gh#1563) replacing `hideGrid`. */
+  /** Hide gridlines. Canonical spelling (ADR-0063, gh#1563) — the deprecated `hideGrid` dual-read shim was cut in 0.8.43 (gh#1617). */
   noGrid: boolean;
-  /** Hide value labels. Canonical spelling (ADR-0063, gh#1563) replacing `hideValues`. */
+  /** 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 */
@@ -54,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

@@ -61,50 +61,25 @@ props:
       - warning
       - danger
       - info
-  hideAverage:
-    description: >-
-      DEPRECATED (ADR-0063, gh#1563) — use `noAverage` instead. Same
-      meaning, same default; kept working as a dual-read compat shim (one-
-      time console.warn when it's the name that resolves). Removed in
-      0.9.0.
-    type: boolean
-    default: false
-    attribute: hide-average
   noAverage:
     description: >-
       When true, suppress the overlaid average line. Canonical spelling
-      (ADR-0063, gh#1563) replacing `hideAverage`.
+      (ADR-0063, gh#1563) — the deprecated `hideAverage` dual-read shim
+      was cut in 0.8.43 (gh#1617).
     type: boolean
     default: false
     attribute: no-average
-  hideGrid:
-    description: >-
-      DEPRECATED (ADR-0063, gh#1563) — use `noGrid` instead. Same meaning,
-      same default; kept working as a dual-read compat shim (one-time
-      console.warn when it's the name that resolves). Removed in 0.9.0.
-    type: boolean
-    default: false
-    attribute: hide-grid
   noGrid:
     description: >-
-      Hide gridlines. Canonical spelling (ADR-0063, gh#1563) replacing
-      `hideGrid`.
+      Hide gridlines. Canonical spelling (ADR-0063, gh#1563) — the
+      deprecated `hideGrid` dual-read shim was cut in 0.8.43 (gh#1617).
     type: boolean
     default: false
     attribute: no-grid
-  hideValues:
-    description: >-
-      DEPRECATED (ADR-0063, gh#1563) — use `noValues` instead. Same
-      meaning, same default; kept working as a dual-read compat shim (one-
-      time console.warn when it's the name that resolves). Removed in
-      0.9.0.
-    type: boolean
-    default: false
-    attribute: hide-values
   noValues:
     description: >-
-      Hide value labels. Canonical spelling (ADR-0063, gh#1563) replacing
-      `hideValues`.
+      Hide value labels. Canonical spelling (ADR-0063, gh#1563) — the
+      deprecated `hideValues` dual-read shim was cut in 0.8.43 (gh#1617).
     type: boolean
     default: false
     attribute: no-values
@@ -121,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
@@ -163,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": ""
     },
@@ -27,7 +27,7 @@
       "default": ""
     },
     "interactive": {
-      "description": "Canonical opt-in spelling (ADR-0063, gh#1563) replacing `static`'s opt-out polarity. Rows are interactive <button>-role badges by default — this default stays `true` in 0.8.42 (deliberately NOT flipped yet; the 0.9.0 cut inverts it to `false` after a full consumer scan of every `<chart-legend-ui>` tag per the ADR).",
+      "description": "Canonical opt-in spelling (ADR-0063, gh#1563) — the deprecated `static` opt-out alias was cut in 0.8.43 (gh#1617). Rows are interactive <button>-role badges by default — this default stays `true` (deliberately NOT flipped yet; the 0.9.0 cut inverts it to `false` after a full consumer scan of every `<chart-legend-ui>` tag per the ADR).",
       "type": "boolean",
       "default": true
     },
@@ -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",
@@ -61,11 +71,6 @@
         "dashed"
       ],
       "default": "dot"
-    },
-    "static": {
-      "description": "DEPRECATED (ADR-0063, gh#1563) — use `interactive` instead. When set (and `interactive` is absent), rows are non-interactive <span>s (no click, no toggle). Kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0.",
-      "type": "boolean",
-      "default": false
     }
   },
   "required": [
@@ -81,7 +86,7 @@
     ],
     "events": {
       "toggle": {
-        "description": "Fires on row click (non-static). Detail: {key, active, mode}. `active` is the new state (true=visible). Consumers (or chart-ui via [for]) wire this to series visibility.",
+        "description": "Fires on row click when interactive. Detail: {key, active, mode}. `active` is the new state (true=visible). Consumers (or chart-ui via [for]) wire this to series visibility.",
         "detail": {
           "active": {
             "description": "New visibility state (true = visible).",
@@ -104,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]",
@@ -138,12 +148,8 @@
         "name": "idle"
       },
       {
-        "description": "Rows are <button>s. Default unless [static].",
+        "description": "Rows are <button>s (the default). When false, rows are <span>s — no click handler, no toggle affordance.",
         "name": "interactive"
-      },
-      {
-        "description": "Rows are <span>s. No click handler, no toggle affordance.",
-        "name": "static"
       }
     ],
     "status": "stable",

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

@@ -34,22 +34,47 @@
  *                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
- *                cut. `static` is a deprecated opt-out alias — when set
- *                (and [interactive] is absent), rows render as
- *                non-interactive badges (no role/tabindex/handlers).
+ *                cut. The deprecated `static` opt-out alias was cut in
+ *                0.8.43 (gh#1617).
  *   on-toggle  — hide | opacity. Default hide. Escape hatch per OD-CHART-09.
  *                Reported via the `toggle` event detail; chart-ui reads it
  *                when wired via [for].
  *
  * Events:
  *   toggle — detail: {key, active, mode}. Fires on row click when
- *            not [static]. `active` is the new state (true=visible).
+ *            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 {
@@ -61,67 +86,27 @@ 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-0063 (gh#1563) — `static` (opt-out) is DEPRECATED; `interactive`
-    // (opt-in) is the canonical positively-named boolean. `static` stays
-    // declared (dual-read compat, 0.8.42). Deliberately does NOT flip the
-    // default here: `interactive` defaults `true` so a consumer naming
-    // NEITHER attribute keeps today's behavior (rows interactive)
-    // unchanged — the real default-inversion (interactive defaulting to
-    // `false`) is scheduled for 0.9.0 per the ADR's own consumer-scan
-    // requirement (every `<chart-legend-ui>` tag needs review first).
-    static:   { type: Boolean, default: false,    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:
+    // the real default-inversion (interactive defaulting to `false`) is
+    // still scheduled for 0.9.0 per the ADR's own consumer-scan
+    // requirement (every `<chart-legend-ui>` tag needs review first) —
+    // out of this ticket's scope, which only cuts the `static` alias.
     interactive: { type: Boolean, default: true,  reflect: true },
     onToggle: { type: String,  default: 'hide',   reflect: true, attribute: 'on-toggle' },
   };
 
   static template = () => null;
 
-  // ADR-0063 (gh#1563) one-shot-per-class deprecation warn for [static].
-  static #warnedStatic = false;
-
   #target = null;
   #targetListener = null;
   #hiddenKeys = new Set();
 
-  // ADR-0063 (gh#1563) — captured by overriding `connectedCallback()` to run
-  // BEFORE calling `super.connectedCallback()`. `interactive` defaults
-  // `true` (a reflected Boolean), and UIElement's own connectedCallback
-  // pre-sync loop stamps the attribute for any reflected Boolean prop whose
-  // value is already `true` and whose attribute is absent (gh#961) — that
-  // stamp happens INSIDE `super.connectedCallback()`, so a check made from
-  // `connected()` (which UIElement invokes AFTER its pre-sync loop) would
-  // see `[interactive]` present even when the author never wrote it.
-  // Capturing here, before the super call, reads only the AUTHORED markup —
-  // the constructor is too early (elements are constructed attribute-less
-  // then have each attribute set individually as the parser processes them;
-  // by connectedCallback time every authored attribute has already landed).
-  #authoredInteractive = false;
-  #authoredStatic = false;
-
-  connectedCallback() {
-    this.#authoredInteractive = this.hasAttribute('interactive');
-    this.#authoredStatic = this.hasAttribute('static');
-    super.connectedCallback();
-  }
-
   connected() {
-    // ADR-0063 (gh#1563) compat shim — resolve BEFORE the first render/paint
-    // so there's no wrong-then-right flash. New-name precedence: [interactive]
-    // wins outright when present, regardless of [static]; only fall back to
-    // (and mirror) [static] when [interactive] is absent from markup.
-    if (!this.#authoredInteractive && this.#authoredStatic) {
-      this.interactive = false;
-      if (!UIChartLegend.#warnedStatic) {
-        UIChartLegend.#warnedStatic = true;
-        // eslint-disable-next-line no-console
-        console.warn(
-          '[AdiaUI] <chart-legend-ui [static]> is deprecated — use ' +
-          '[interactive] instead (ADR-0063, gh#1563). Note: [interactive] ' +
-          'still defaults to true until the 0.9.0 default-inversion cut. ' +
-          'Kept working as-is; no behavior change.',
-        );
-      }
-    }
     this.setAttribute('role', 'list');
     this.#resolveTarget();
     this.#paint();
@@ -166,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() {
@@ -186,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;
@@ -209,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');
@@ -228,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);