@adia-ai/web-components 0.8.41 → 0.8.42

package/components/chart/chart.class.js

@@ -21,10 +21,11 @@
  *   type         — chart type (default: 'bar')
  *   x            — key for X-axis data
  *   y            — key(s) for Y-axis, comma-separated for multi-series
- *   hide-average — suppress the overlaid average line on bar/line (default: false — line shown)
+ *   no-average   — suppress the overlaid average line on bar/line (default: false — line shown).
+ *                  `hide-average` is a deprecated dual-read alias (ADR-0063, gh#1563).
  *   color        — accent/success/warning/danger/info
- *   hide-grid    — hide gridlines
- *   hide-values  — hide value labels
+ *   no-grid      — hide gridlines. `hide-grid` is a deprecated dual-read alias (ADR-0063, gh#1563).
+ *   no-values    — hide value labels. `hide-values` is a deprecated dual-read alias (ADR-0063, gh#1563).
  *   corner-radius — bar corner radius in px (default: null, falls back to --a-radius)
  *   dots         — line/multi-line marker visibility: all|none|hover|last (default: all)
  *   series-emphasis — multi-line: series key that keeps full area+line treatment; others render line-only, dimmed
@@ -215,10 +216,19 @@ export class UIChart extends UIElement {
     type:        { type: String,  default: 'bar',    reflect: true },
     x:           { type: String,  default: '',       reflect: true },
     y:           { type: String,  default: '',       reflect: true },
+    // ADR-0063 (gh#1563) — `no-*` is the ratified negation prefix; `hide-*`
+    // retires. `hideAverage`/`hideGrid`/`hideValues` stay declared (dual-
+    // read compat, 0.8.42) so old markup keeps reflecting; `#resolveNoAttr()`
+    // (called from connected()) mirrors an old-only value onto the new prop
+    // + warns once per attribute. Every internal render usage reads the
+    // canonical `noAverage`/`noGrid`/`noValues` below.
     hideAverage: { type: Boolean, default: false,    reflect: true, attribute: 'hide-average' },
+    noAverage:   { type: Boolean, default: false,    reflect: true, attribute: 'no-average' },
     color:       { type: String,  default: '',       reflect: true },
     hideGrid:    { type: Boolean, default: false,    reflect: true, attribute: 'hide-grid' },
+    noGrid:      { type: Boolean, default: false,    reflect: true, attribute: 'no-grid' },
     hideValues:  { type: Boolean, default: false,    reflect: true, attribute: 'hide-values' },
+    noValues:    { type: Boolean, default: false,    reflect: true, attribute: 'no-values' },
     cornerRadius: { type: Number, default: null,     reflect: true, attribute: 'corner-radius' },
     smooth:      { type: Number,  default: 0.4,      reflect: true },
     size:        { type: String,  default: '',       reflect: true },
@@ -241,6 +251,32 @@ export class UIChart extends UIElement {
 
   static template = () => null;
 
+  // ADR-0063 (gh#1563) compat-shim warn-once flags — one per renamed
+  // attribute (not collapsed into one flag; each fires independently the
+  // first time its own old attribute resolves). Per-class, matching
+  // toggle-group.class.js's #deprecationWarned idiom.
+  static #warned = { hideAverage: false, hideGrid: false, hideValues: false };
+
+  /** Dual-read resolution for one `hide-*` → `no-*` rename (ADR-0063).
+   *  New-name precedence: if `newAttr` is present, the old attribute is
+   *  ignored outright (no mirror, no warn) — the new prop already reflects
+   *  its own attribute normally. Otherwise, when only the old attribute is
+   *  present, mirror its (always-true, boolean-presence) value onto the
+   *  new prop and warn once per class. */
+  #resolveNoAttr(oldAttr, newAttr, newProp, warnKey) {
+    if (this.hasAttribute(newAttr)) return;
+    if (!this.hasAttribute(oldAttr)) return;
+    this[newProp] = true;
+    if (!UIChart.#warned[warnKey]) {
+      UIChart.#warned[warnKey] = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[AdiaUI] <chart-ui [${oldAttr}]> is deprecated — use [${newAttr}] ` +
+        `instead (ADR-0063, gh#1563). Kept working as-is; no behavior change.`,
+      );
+    }
+  }
+
   #data = [];
   #shapeWarned = false;  // FEEDBACK-24: one-shot wrong-.data-shape warning
   #resizeObs = null;
@@ -317,6 +353,12 @@ export class UIChart extends UIElement {
   }
 
   connected() {
+    // ADR-0063 (gh#1563) compat shims — resolve BEFORE the first render so
+    // there's no wrong-then-right flash; see #resolveNoAttr() above.
+    this.#resolveNoAttr('hide-average', 'no-average', 'noAverage', 'hideAverage');
+    this.#resolveNoAttr('hide-grid',    'no-grid',    'noGrid',    'hideGrid');
+    this.#resolveNoAttr('hide-values',  'no-values',  'noValues',  'hideValues');
+
     if (!this.hasAttribute('role'))       this.setAttribute('role', 'img');
     if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', `${this.type} chart`);
 
@@ -439,13 +481,13 @@ export class UIChart extends UIElement {
     // When the grid is hidden (in-card sparkline-like use) we can zero
     // out the Y-axis label gutter entirely — otherwise the plot area
     // collapses at small sizes.
-    const hideGrid = this.hideGrid;
-    const yLabelW = hideGrid ? 0 : fontSize * 3.2;
+    const noGrid = this.noGrid;
+    const yLabelW = noGrid ? 0 : fontSize * 3.2;
     const hasXLabels = !!this.x;
     const pad = {
-      top:    hideGrid ? 2 : fontSize * 1.6,
-      right:  hideGrid ? 2 : fontSize * 1.2,
-      bottom: !hasXLabels || hideGrid ? 2 : fontSize * 2.2,
+      top:    noGrid ? 2 : fontSize * 1.6,
+      right:  noGrid ? 2 : fontSize * 1.2,
+      bottom: !hasXLabels || noGrid ? 2 : fontSize * 2.2,
       left:   yLabelW,
     };
 
@@ -1035,11 +1077,11 @@ export class UIChart extends UIElement {
       displayTicks = ticks.filter((_, i) => i % 2 === 0 || i === ticks.length - 1);
     }
 
-    // hideGrid suppresses both gridlines AND axis labels — callers who
-    // want labels without gridlines can omit hide-grid and rely on token
+    // noGrid suppresses both gridlines AND axis labels — callers who
+    // want labels without gridlines can omit no-grid and rely on token
     // overrides to make gridlines transparent. This keeps compact in-card
     // charts visually clean.
-    if (!this.hideGrid) {
+    if (!this.noGrid) {
       const tickRange = ticks[ticks.length - 1] - ticks[0];
       const safeRange = tickRange || 1; // Prevent division by zero
       for (const t of displayTicks) {
@@ -1094,8 +1136,8 @@ export class UIChart extends UIElement {
     let svg = this.#gridAndAxes(width, height, ticks, labels, pad, dims);
 
     // At sm auto-hide value labels (they overlap at narrow widths).
-    const showValues = !this.hideValues && dims.sizeClass !== 'sm';
-    const showAverage = !this.hideAverage && vals.length > 1 && dims.sizeClass !== 'sm' && !this.hideGrid;
+    const showValues = !this.noValues && dims.sizeClass !== 'sm';
+    const showAverage = !this.noAverage && vals.length > 1 && dims.sizeClass !== 'sm' && !this.noGrid;
 
     for (let i = 0; i < data.length; i++) {
       const v = vals[i];
@@ -1155,8 +1197,8 @@ export class UIChart extends UIElement {
     const isSm = dims.sizeClass === 'sm';
     const dotR = isSm ? 1.5 : 3;
     const hitR = Math.max(dotR, 10);  // invisible hit-target for tooltip
-    const showValues = !this.hideValues && !isSm;
-    const showAverage = !this.hideAverage && vals.length > 1 && !isSm && !this.hideGrid;
+    const showValues = !this.noValues && !isSm;
+    const showAverage = !this.noAverage && vals.length > 1 && !isSm && !this.noGrid;
 
     points.forEach((p, i) => {
       if (this.#shouldRenderDot(i, points.length)) {
@@ -2108,7 +2150,7 @@ export class UIChart extends UIElement {
         const by = pad.top + plotH - barH;
         svg += `<path${this.#seriesFill(k % 10, keys[k])}${tip({ label: labels[i], value: v, series: keys[k] })} d="${topRoundedBarPath(bx, by, subBarW, barH, this.#resolveRadius())}"/>`;
 
-        if (!this.hideValues) {
+        if (!this.noValues) {
           svg += `<text data-value x="${bx + subBarW / 2}" y="${by - 4}" text-anchor="middle" font-size="${dims.valueSize}">${this.#fmtValue(v)}</text>`;
         }
       }

package/components/chart/chart.d.ts

@@ -30,14 +30,20 @@ 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';
-  /** When true, suppress the overlaid average line */
+  /** 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;
-  /** Hide gridlines */
+  /** 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;
-  /** Hide value labels */
+  /** 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`. */
+  noAverage: boolean;
+  /** Hide gridlines. Canonical spelling (ADR-0063, gh#1563) replacing `hideGrid`. */
+  noGrid: boolean;
+  /** Hide value labels. Canonical spelling (ADR-0063, gh#1563) replacing `hideValues`. */
+  noValues: boolean;
   /** 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 */

package/components/chart/chart.yaml

@@ -62,20 +62,52 @@ props:
       - danger
       - info
   hideAverage:
-    description: When true, suppress the overlaid average line
+    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`.
+    type: boolean
+    default: false
+    attribute: no-average
   hideGrid:
-    description: Hide gridlines
+    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`.
+    type: boolean
+    default: false
+    attribute: no-grid
   hideValues:
-    description: Hide value labels
+    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`.
+    type: boolean
+    default: false
+    attribute: no-values
   cornerRadius:
     description: Bar corner radius in px (null = let CSS tokens decide)
     type: number

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

@@ -26,6 +26,11 @@
       "type": "string",
       "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).",
+      "type": "boolean",
+      "default": true
+    },
     "onToggle": {
       "description": "Series-toggle mode emitted via the `toggle` event. `hide` removes the series from the render; `opacity` fades it. Wired via [for] on chart-ui.",
       "type": "string",
@@ -58,7 +63,7 @@
       "default": "dot"
     },
     "static": {
-      "description": "When set, rows are non-interactive <span>s (no click, no toggle).",
+      "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
     }

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

@@ -35,9 +35,12 @@
  *   position   — top | bottom | left | right. Layout hint; actual placement
  *                is where the element is placed in the DOM. Drives
  *                flex-direction.
- *   static     — when set, rows render as non-interactive badges (no
- *                role/tabindex/handlers). Default is interactive
- *                `role="button"` badges that toggle on click + Enter/Space.
+ *   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).
  *   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].
@@ -58,17 +61,67 @@ 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 },
+    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();
@@ -152,11 +205,11 @@ export class UIChartLegend extends UIElement {
          keyboard-operable without a wrapping <button>. */
       const row = document.createElement('badge-ui');
       row.setAttribute('data-row', '');
-      row.setAttribute('role', this.static ? 'listitem' : 'button');
+      row.setAttribute('role', this.interactive ? 'button' : 'listitem');
       row.setAttribute('text', label);
       if (key) row.setAttribute('data-key', key);
       if (active) row.setAttribute('data-active', '');
-      if (!this.static) {
+      if (this.interactive) {
         row.setAttribute('tabindex', '0');
         row.setAttribute('aria-pressed', active ? 'true' : 'false');
       }
@@ -181,7 +234,7 @@ export class UIChartLegend extends UIElement {
       swatch.style.setProperty('--swatch-color', swatchColor);
       row.appendChild(swatch);
 
-      if (!this.static) {
+      if (this.interactive) {
         row.addEventListener('click', (e) => this.#onRowToggle(e, key));
         row.addEventListener('keydown', (e) => {
           if (e.key === 'Enter' || e.key === ' ') {

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

@@ -66,8 +66,11 @@
                 color var(--a-duration-fast) var(--a-easing);
   }
 
-  /* Static rows — no interaction */
-  :scope[static] badge-ui[data-row] {
+  /* Non-interactive rows. ADR-0063 (gh#1563): `:not([interactive])` covers
+     both today's opt-out spelling (`[static]` mirrors onto `[interactive]`
+     being removed, in chart-legend.class.js's connected()) and the eventual
+     0.9.0 default-inversion, in one selector. */
+  :scope:not([interactive]) badge-ui[data-row] {
     cursor: default;
   }
 

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

@@ -28,13 +28,15 @@ export class UIChartLegend extends UIElement {
   items: string;
   /** id-ref of a chart-ui / heatmap-ui to mirror series from. */
   for: string;
+  /** 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). */
+  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. */
   position: 'top' | 'bottom' | 'left' | 'right';
   /** Swatch shape. Maps to badge-ui's icon for dot/square variants. */
   shape: 'dot' | 'square' | 'line' | 'dashed';
-  /** When set, rows are non-interactive <span>s (no click, no toggle). */
+  /** 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. */
   static: boolean;
 
   addEventListener(type: 'toggle', listener: (ev: ChartLegendToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;

package/components/chart-legend/chart-legend.yaml

@@ -48,10 +48,24 @@ props:
       - right
     reflect: true
   static:
-    description: When set, rows are non-interactive <span>s (no click, no toggle).
+    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
     reflect: true
+  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).
+    type: boolean
+    default: true
+    reflect: true
   onToggle:
     description: >-
       Series-toggle mode emitted via the `toggle` event. `hide` removes the

package/components/color-area/color-area.a2ui.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ColorArea.json",
+  "title": "ColorArea",
+  "description": "OKLCH-native color picker with 2D area and H/C/L sliders. Form-associated input emitting OKLCH color strings; canonical color authoring surface in the AdiaUI token system. Use for color input in design tools or theming UIs; for simple color swatches use <swatch-ui> or <color-input-ui> instead. Renamed from `<color-picker-ui>` (ADR-0063, gh#1563 — `-picker` is reserved for the outer trigger + popover composite shape; this is the inline substrate, mirroring <calendar-grid-ui>'s naming precedent). `<color-picker-ui>` is now a thin deprecated alias subclassing this component.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "baseHue": {
+      "description": "Reference hue (degrees) for the [hue-drift-max] constraint. Default\nNaN — falls back to the picker's hue at first commit so the consumer\ncan pre-seed the picker and constrain drift from that initial value.\n",
+      "type": "number",
+      "default": "NaN"
+    },
+    "component": {
+      "const": "ColorArea"
+    },
+    "disabled": {
+      "description": "Disables all interaction",
+      "type": "boolean",
+      "default": false
+    },
+    "format": {
+      "description": "Output format for the value property",
+      "type": "string",
+      "enum": [
+        "hex",
+        "oklch"
+      ],
+      "default": "hex"
+    },
+    "hueDriftMax": {
+      "description": "Generation constraint — maximum allowed signed-shortest-path hue\ndeviation (degrees) from [base-hue] (or the first-committed hue\nif [base-hue] is unset). Default NaN (no constraint). Wrap-aware\nso a drift of 350 degrees resolves as -10.\n",
+      "type": "number",
+      "default": "NaN"
+    },
+    "maxChroma": {
+      "description": "Generation constraint (v0.4.9 §99h, FEEDBACK-02 #7) — clamp the\nOKLCH chroma channel to at most this value before commit. Out-of-\nbound mutations round-trip to the nearest in-bound equivalent +\nfire `constraint-clamp`. Default Infinity (no constraint).\n",
+      "type": "number",
+      "default": "Infinity"
+    },
+    "maxL": {
+      "description": "Generation constraint — clamp OKLCH lightness to at most this value (0..1). Default 1 (no constraint).",
+      "type": "number",
+      "default": 1
+    },
+    "minL": {
+      "description": "Generation constraint — clamp OKLCH lightness to at least this value (0..1). Default 0 (no constraint).",
+      "type": "number",
+      "default": 0
+    },
+    "name": {
+      "description": "Form field name",
+      "type": "string",
+      "default": ""
+    },
+    "value": {
+      "description": "Current color as hex string",
+      "type": "string",
+      "default": "#3b82f6"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "input",
+    "composes": [
+      "slider-ui"
+    ],
+    "events": {
+      "change": {
+        "description": "Fired on every color change"
+      },
+      "constraint-clamp": {
+        "description": "Fired immediately before `change` / `input` when one or more\nconsumer-declared constraints (max-chroma / max-l / min-l /\nhue-drift-max) clamped a channel away from the user-requested\nvalue. detail.clamps is an array of axis-specific clamp records.\n",
+        "detail": {
+          "clamps": {
+            "description": "Array of `{ axis, requested, clamped, reason }` objects. axis is\none of \"l\" / \"c\" / \"h\". reason names the triggering constraint\nprop. Empty arrays are never emitted.\n",
+            "type": "array"
+          }
+        }
+      },
+      "input": {
+        "description": "Fired during continuous interaction (drag)"
+      }
+    },
+    "examples": [
+      {
+        "description": "Color picker card with a color picker component for selecting colors with swatches.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\"\n    ]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"cp\"\n    ]\n  },\n  {\n    \"id\": \"cp\",\n    \"component\": \"ColorArea\",\n    \"value\": \"#6366f1\"\n  }\n]",
+        "name": "color-area-demo"
+      },
+      {
+        "description": "Color picker with swatch selection in a card.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\"\n    ]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"cp\"\n    ]\n  },\n  {\n    \"id\": \"cp\",\n    \"component\": \"ColorArea\",\n    \"value\": \"#3b82f6\"\n  }\n]",
+        "name": "color-area-panel"
+      }
+    ],
+    "keywords": [
+      "colorarea",
+      "color-area",
+      "colorpicker",
+      "color-picker",
+      "color",
+      "picker"
+    ],
+    "name": "UIColorArea",
+    "parts": {},
+    "related": [
+      "grid",
+      "button"
+    ],
+    "slots": {},
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "Non-interactive; dimmed.",
+        "attribute": "disabled",
+        "name": "disabled"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "color-area": [
+        "color-canvas",
+        "color-surface",
+        "swatch-picker",
+        "color-picker"
+      ]
+    },
+    "tag": "color-area-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}