@adia-ai/web-components 0.0.13 → 0.0.14

package/components/chart/chart.yaml

@@ -6,11 +6,13 @@ tag: chart-ui
 component: Chart
 category: agent
 version: 1
-description: Declarative SVG chart supporting bar, line, pie, donut, radar, sparkline, stacked-bar,
-  grouped-bar, and multi-line types.
+description: >-
+  Declarative SVG chart supporting 18 types: bar, line, pie, donut, radar,
+  sparkline, segments, area, scatter, radial-bar, gauge, stacked-bar,
+  grouped-bar, multi-line, funnel, treemap, sankey, and composed.
 props:
   type:
-    description: Chart type. Only 'bar' is built-in.
+    description: Chart type. All 18 enum values have dedicated render paths in chart.js.
     type: string
     default: bar
     enum:
@@ -20,11 +22,23 @@ props:
       - donut
       - radar
       - sparkline
+      - segments
+      - area
+      - scatter
+      - radial-bar
+      - gauge
       - stacked-bar
       - grouped-bar
       - multi-line
+      - funnel
+      - treemap
+      - sankey
+      - composed
   aspect:
-    description: Aspect ratio
+    description: >-
+      DEPRECATED (OD-CHART-02). Parents should size the chart directly
+      (width/height on the enclosing card or container). Still honored for
+      back-compat; emits a one-shot console.warn per instance when set.
     type: string
     default: std
     enum:
@@ -32,6 +46,22 @@ props:
       - wide
       - square
       - tall
+    deprecated: true
+  format:
+    description: >-
+      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.
+    type: string
+    default: abbr
+    enum:
+      - abbr
+      - decimal
+      - currency
+      - percent
+    reflect: true
   color:
     description: Color scheme
     type: string
@@ -74,10 +104,16 @@ props:
     type: number
     default: 0.4
   heading:
-    description: Chart heading text rendered above the canvas.
+    description: >-
+      DEPRECATED (OD-CHART-02). Place chart titles in an enclosing
+      card-ui's `<header><span slot="heading">...</span></header>`
+      instead. Still honored for back-compat; emits a one-shot
+      console.warn per instance when set. Used as the chart's
+      `aria-label` when no explicit label is provided.
     type: string
     default: ""
     reflect: true
+    deprecated: true
   x:
     description: Data key for x-axis (category) values
     type: string
@@ -86,15 +122,35 @@ props:
     description: Y-axis key(s), comma-separated for multi-series
     type: string
     default: ""
-events: {}
+events:
+  chart-hover:
+    description: >-
+      Fires when the pointer enters a datum (bar / dot / slice). Detail includes
+      {label, value, pct, series, slot, pointerX, pointerY}. Only re-fires when
+      the hovered datum changes — moving inside the same datum is quiet.
+  chart-leave:
+    description: Fires when the pointer leaves the plot area or a previously-hovered datum with no new one entering.
+  chart-select:
+    description: Fires on click of a datum with the same detail shape as chart-hover.
 slots:
   canvas:
     description: Chart rendering area
   title:
     description: Chart title element
+  empty:
+    description: >-
+      Shown in place of the SVG when `.data` is empty or missing. Typically an
+      `<empty-state-ui>` with icon + heading + description + optional action.
+      Visibility is CSS-toggled via `[data-has-data]` on the host — authors
+      don't need to manage it imperatively.
 states:
   - name: idle
     description: Default, ready for interaction.
+  - name: empty
+    description: >-
+      No data — the empty slot (if provided) is rendered; otherwise the chart
+      area renders nothing. Host carries [data-has-data] only when data
+      is present.
 traits: []
 tokens: {}
 a2ui:

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

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ChartLegend.json",
+  "title": "ChartLegend",
+  "description": "Standalone legend primitive for the AdiaUI chart family. Renders a row of badge-ui chips (swatch + label) that are keyboard-focusable and click-toggleable. Composes with chart-ui via [for] id-ref (auto-mirror) or via explicit [items] JSON.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "items": {
+      "description": "JSON array of {key, label, slot?, pct?} legend items. Takes precedence over [for] when both are provided.",
+      "type": "string",
+      "default": ""
+    },
+    "component": {
+      "const": "ChartLegend"
+    },
+    "for": {
+      "description": "id-ref of a chart-ui / heatmap-ui to mirror series from.",
+      "type": "string",
+      "default": ""
+    },
+    "onToggle": {
+      "description": "Series-toggle mode emitted via legend-toggle event. `hide` removes the series from the render; `opacity` fades it. Wired via [for] on chart-ui.",
+      "type": "string",
+      "enum": [
+        "hide",
+        "opacity"
+      ],
+      "default": "hide"
+    },
+    "position": {
+      "description": "Layout hint — drives flex-direction. Actual placement follows DOM order.",
+      "type": "string",
+      "enum": [
+        "top",
+        "bottom",
+        "left",
+        "right"
+      ],
+      "default": "bottom"
+    },
+    "shape": {
+      "description": "Swatch shape. Maps to badge-ui's icon for dot/square variants.",
+      "type": "string",
+      "enum": [
+        "dot",
+        "square",
+        "line",
+        "dashed"
+      ],
+      "default": "dot"
+    },
+    "static": {
+      "description": "When set, rows are non-interactive <span>s (no click, no toggle).",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "agent",
+    "events": {
+      "legend-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."
+      }
+    },
+    "examples": [
+      {
+        "description": "Standalone legend with explicit items array.",
+        "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": "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]",
+        "name": "mirror-chart-by-id"
+      }
+    ],
+    "keywords": [
+      "legend",
+      "chart-legend",
+      "series",
+      "key",
+      "swatch",
+      "chart",
+      "graph",
+      "visualization"
+    ],
+    "name": "AdiaChartLegend",
+    "related": [
+      "chart",
+      "badge",
+      "heatmap"
+    ],
+    "slots": {
+      "default": {
+        "description": "Normally empty — the primitive renders its own rows. Authors who want fully custom markup can provide their own children with [data-row] and [data-key] attributes; the primitive won't wipe them if [items] is empty and [for] is unset."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "Rows are <button>s. Default unless [static].",
+        "name": "interactive"
+      },
+      {
+        "description": "Rows are <span>s. No click handler, no toggle affordance.",
+        "name": "static"
+      }
+    ],
+    "synonyms": {
+      "chart": [
+        "chart-legend",
+        "legend"
+      ],
+      "legend": [
+        "chart-legend"
+      ]
+    },
+    "tag": "chart-legend-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

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

@@ -0,0 +1,124 @@
+@scope (chart-legend-ui) {
+  :where(:scope) {
+    /* ── Layout ── */
+    --chart-legend-gap:         var(--a-space-2);
+    --chart-legend-row-gap:     var(--a-space-1);
+    --chart-legend-py:          var(--a-space-1);
+    --chart-legend-px:          0;
+
+    /* ── Swatch ── */
+    --chart-legend-swatch-size: var(--a-space-2-5);
+    --chart-legend-line-w:      2px;
+
+    /* ── Typography ── */
+    --chart-legend-font-size:   var(--a-ui-tiny);
+    --chart-legend-fg:          var(--a-fg-subtle);
+    --chart-legend-fg-inactive: var(--a-fg-muted);
+
+    /* ── Interaction ── */
+    --chart-legend-row-radius:  var(--a-radius-sm);
+    --chart-legend-row-hover:   var(--a-canvas-2);
+    --chart-legend-row-fg-hover: var(--a-fg);
+
+    /* ── Focus ── */
+    --chart-legend-focus-ring:  var(--a-focus-ring);
+  }
+
+  :scope {
+    box-sizing: border-box;
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--chart-legend-gap);
+    padding: var(--chart-legend-py) var(--chart-legend-px);
+    font-size: var(--chart-legend-font-size);
+    color: var(--chart-legend-fg);
+  }
+
+  /* Position variants — drive flex-direction. DOM placement still wins for
+     actual layout; these tune the internal row direction. */
+  :scope[position="top"],
+  :scope[position="bottom"] {
+    flex-direction: row;
+    justify-content: center;
+  }
+
+  :scope[position="left"],
+  :scope[position="right"] {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+
+  /* Rows — both <button> (interactive) and <span> (static) variants */
+  [data-row] {
+    all: unset;
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--chart-legend-row-gap);
+    padding: var(--chart-legend-py) var(--a-space-1);
+    border-radius: var(--chart-legend-row-radius);
+    cursor: pointer;
+    color: inherit;
+    line-height: 1.2;
+    transition: background var(--a-duration-fast) var(--a-easing),
+                color var(--a-duration-fast) var(--a-easing);
+  }
+
+  /* Static rows — no interaction */
+  :scope[static] [data-row] {
+    cursor: default;
+  }
+
+  button[data-row]:hover {
+    background: var(--chart-legend-row-hover);
+    color: var(--chart-legend-row-fg-hover);
+  }
+
+  button[data-row]:focus-visible {
+    outline: none;
+    box-shadow: var(--chart-legend-focus-ring);
+  }
+
+  /* Inactive (toggled-off) rows — dim the swatch + fade label */
+  [data-row]:not([data-active]) {
+    color: var(--chart-legend-fg-inactive);
+  }
+  [data-row]:not([data-active]) [data-swatch] {
+    opacity: 0.4;
+  }
+
+  /* Swatch — dedicated span per row, styled by the legend's [shape] attr.
+     --swatch-color is set inline per-row from --color-{key} with a
+     --chart-{slot} fallback; overrides cascade through atomically. */
+  [data-swatch] {
+    display: inline-block;
+    flex-shrink: 0;
+    background: var(--swatch-color, var(--chart-0));
+    line-height: 0;
+  }
+
+  :scope[shape="dot"] [data-swatch] {
+    width: var(--chart-legend-swatch-size);
+    height: var(--chart-legend-swatch-size);
+    border-radius: 50%;
+  }
+
+  :scope[shape="square"] [data-swatch] {
+    width: var(--chart-legend-swatch-size);
+    height: var(--chart-legend-swatch-size);
+    border-radius: var(--a-radius-sm);
+  }
+
+  :scope[shape="line"] [data-swatch] {
+    width: calc(var(--chart-legend-swatch-size) * 1.75);
+    height: var(--chart-legend-line-w);
+    border-radius: var(--chart-legend-line-w);
+  }
+
+  :scope[shape="dashed"] [data-swatch] {
+    width: calc(var(--chart-legend-swatch-size) * 1.75);
+    height: 0;
+    background: transparent;
+    border-top: var(--chart-legend-line-w) dashed var(--swatch-color, var(--chart-0));
+  }
+}

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

@@ -0,0 +1,185 @@
+/**
+ * <chart-legend-ui shape="dot" position="bottom" items='[{"key":"revenue","label":"Revenue"},{"key":"users","label":"Users"}]'></chart-legend-ui>
+ *
+ * Standalone legend primitive for the AdiaUI chart family. Renders a row
+ * of badge-ui chips (swatch + label) that are keyboard-focusable and
+ * click-toggleable — clicking emits a `legend-toggle` event that consumers
+ * (or chart-ui via [for]) wire to series visibility.
+ *
+ * Attributes:
+ *   for        — id-ref of a chart-ui / heatmap-ui to mirror. When set, the
+ *                legend reads series data from that element's `.legendData`
+ *                property and subscribes to its `legend-update` event.
+ *                (Auto-mirror ships behind [for] — explicit items still
+ *                override when both are provided.)
+ *   items      — JSON array of {key, label, slot?, pct?} legend items.
+ *                Takes precedence over [for] if both are provided.
+ *   shape      — dot | square | line | dashed. Default: dot. Maps to
+ *                badge-ui's icon slot (dot = phosphor 'dot', square =
+ *                'square-fill', line/dashed = custom CSS swatches).
+ *   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 <span>s. Default
+ *                is interactive <button>s that toggle.
+ *   on-toggle  — hide | opacity. Default hide. Escape hatch per OD-CHART-09.
+ *                Reported via legend-toggle event detail; chart-ui reads it
+ *                when wired via [for].
+ *
+ * Events:
+ *   legend-toggle — detail: {key, active, mode}. Fires on row click when
+ *                   not [static]. `active` is the new state (true=visible).
+ */
+
+import { AdiaElement } from '../../core/element.js';
+
+class AdiaChartLegend extends AdiaElement {
+  static properties = {
+    for:      { type: String,  default: '',       reflect: true },
+    items:    { type: String,  default: '',       reflect: false },
+    shape:    { type: String,  default: 'dot',    reflect: true },
+    position: { type: String,  default: 'bottom', reflect: true },
+    static:   { type: Boolean, default: false,    reflect: true },
+    onToggle: { type: String,  default: 'hide',   reflect: true, attribute: 'on-toggle' },
+  };
+
+  static template = () => null;
+
+  #target = null;
+  #targetListener = null;
+  #hiddenKeys = new Set();
+
+  connected() {
+    this.setAttribute('role', 'list');
+    this.#resolveTarget();
+    this.#paint();
+  }
+
+  disconnected() {
+    this.#detachTarget();
+  }
+
+  render() {
+    this.#resolveTarget();
+    this.#paint();
+  }
+
+  /* ── Target resolution ──────────────────────────────────────────── */
+
+  #resolveTarget() {
+    this.#detachTarget();
+    if (!this.for) return;
+    const el = this.getRootNode()?.getElementById?.(this.for)
+      || document.getElementById(this.for);
+    if (!el) {
+      // Warn once per (element × id) pair
+      if (!AdiaChartLegend._warned) AdiaChartLegend._warned = new WeakSet();
+      const marker = { el: this, id: this.for };
+      if (!AdiaChartLegend._warned.has(this)) {
+        console.warn(`[chart-legend-ui] [for="${this.for}"] did not resolve to an element.`);
+        AdiaChartLegend._warned.add(this);
+      }
+      return;
+    }
+    this.#target = el;
+    this.#targetListener = () => this.#paint();
+    el.addEventListener('legend-update', this.#targetListener);
+  }
+
+  #detachTarget() {
+    if (this.#target && this.#targetListener) {
+      this.#target.removeEventListener('legend-update', this.#targetListener);
+    }
+    this.#target = null;
+    this.#targetListener = null;
+  }
+
+  /* ── Item source ────────────────────────────────────────────────── */
+
+  #resolveItems() {
+    /* Explicit items prop wins. */
+    if (this.items) {
+      try {
+        const parsed = JSON.parse(this.items);
+        if (Array.isArray(parsed)) return parsed;
+      } catch (_) { /* fall through */ }
+    }
+    /* Mirror from [for] target when present. */
+    if (this.#target && Array.isArray(this.#target.legendData)) {
+      return this.#target.legendData;
+    }
+    return [];
+  }
+
+  /* ── Render ─────────────────────────────────────────────────────── */
+
+  #paint() {
+    const items = this.#resolveItems();
+    this.innerHTML = '';
+    if (!items.length) return;
+
+    for (const item of items) {
+      const key = item.key ?? item.label ?? '';
+      const label = item.label ?? key;
+      const slot = item.slot != null ? item.slot : 0;
+      const active = !this.#hiddenKeys.has(key);
+
+      const row = this.static
+        ? document.createElement('span')
+        : document.createElement('button');
+
+      row.setAttribute('data-row', '');
+      row.setAttribute('role', 'listitem');
+      if (key) row.setAttribute('data-key', key);
+      if (active) row.setAttribute('data-active', '');
+      if (!this.static) row.setAttribute('type', 'button');
+
+      /* Swatch + label. A dedicated `[data-swatch]` span lets shape-specific
+         CSS handle dot/square/line/dashed variants without fighting badge-
+         ui's icon slot (which is shadow-DOM-less and doesn't expose an
+         `icon` part — previous badge-ui compose produced visual artifacts
+         for line/dashed shapes). Color resolves via --color-{key} with a
+         chart-{slot} fallback, mirroring chart-ui's per-series CSS var
+         injection so ancestor overrides cascade through atomically. */
+      const swatch = document.createElement('span');
+      swatch.setAttribute('data-swatch', '');
+      const swatchColor = key
+        ? `var(--color-${key}, var(--chart-${slot}))`
+        : `var(--chart-${slot})`;
+      swatch.style.setProperty('--swatch-color', swatchColor);
+      row.appendChild(swatch);
+
+      const labelEl = document.createElement('span');
+      labelEl.setAttribute('data-label', '');
+      labelEl.textContent = label;
+      row.appendChild(labelEl);
+
+      if (!this.static) {
+        row.addEventListener('click', (e) => this.#onRowClick(e, key));
+      }
+
+      this.appendChild(row);
+    }
+  }
+
+  #onRowClick(e, key) {
+    if (!key) return;
+    const currentlyActive = !this.#hiddenKeys.has(key);
+    const newActive = !currentlyActive;
+    if (newActive) this.#hiddenKeys.delete(key);
+    else this.#hiddenKeys.add(key);
+
+    const row = e.currentTarget;
+    if (newActive) row.setAttribute('data-active', '');
+    else row.removeAttribute('data-active');
+
+    this.dispatchEvent(new CustomEvent('legend-toggle', {
+      bubbles: true,
+      detail: { key, active: newActive, mode: this.onToggle || 'hide' },
+    }));
+  }
+}
+
+customElements.define('chart-legend-ui', AdiaChartLegend);
+
+export { AdiaChartLegend };

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

@@ -0,0 +1,133 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: AdiaChartLegend
+tag: chart-legend-ui
+component: ChartLegend
+category: agent
+version: 1
+description: >-
+  Standalone legend primitive for the AdiaUI chart family. Renders a row of
+  badge-ui chips (swatch + label) that are keyboard-focusable and
+  click-toggleable. Composes with chart-ui via [for] id-ref (auto-mirror) or
+  via explicit [items] JSON.
+props:
+  for:
+    description: id-ref of a chart-ui / heatmap-ui to mirror series from.
+    type: string
+    default: ''
+    reflect: true
+  items:
+    description: >-
+      JSON array of {key, label, slot?, pct?} legend items. Takes precedence
+      over [for] when both are provided.
+    type: string
+    default: ''
+  shape:
+    description: Swatch shape. Maps to badge-ui's icon for dot/square variants.
+    type: string
+    default: dot
+    enum:
+      - dot
+      - square
+      - line
+      - dashed
+    reflect: true
+  position:
+    description: Layout hint — drives flex-direction. Actual placement follows DOM order.
+    type: string
+    default: bottom
+    enum:
+      - top
+      - bottom
+      - left
+      - right
+    reflect: true
+  static:
+    description: When set, rows are non-interactive <span>s (no click, no toggle).
+    type: boolean
+    default: false
+    reflect: true
+  onToggle:
+    description: >-
+      Series-toggle mode emitted via legend-toggle event. `hide` removes the
+      series from the render; `opacity` fades it. Wired via [for] on chart-ui.
+    type: string
+    default: hide
+    enum:
+      - hide
+      - opacity
+    reflect: true
+    attribute: on-toggle
+events:
+  legend-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.
+slots:
+  default:
+    description: >-
+      Normally empty — the primitive renders its own rows. Authors who want
+      fully custom markup can provide their own children with [data-row] and
+      [data-key] attributes; the primitive won't wipe them if [items] is empty
+      and [for] is unset.
+states:
+  - name: idle
+    description: Default, ready for interaction.
+  - name: interactive
+    description: Rows are <button>s. Default unless [static].
+  - name: static
+    description: Rows are <span>s. No click handler, no toggle affordance.
+traits: []
+tokens: {}
+a2ui:
+  rules: []
+anti_patterns: []
+examples:
+  - name: standalone-with-items
+    description: Standalone legend with explicit items array.
+    a2ui: >-
+      [
+        {
+          "id": "legend", "component": "ChartLegend",
+          "shape": "dot",
+          "items": "[{\"key\":\"revenue\",\"label\":\"Revenue\",\"slot\":0},{\"key\":\"users\",\"label\":\"Users\",\"slot\":1}]"
+        }
+      ]
+  - name: mirror-chart-by-id
+    description: Legend mirrors a named chart's series data.
+    a2ui: >-
+      [
+        {
+          "id": "root", "component": "Column",
+          "children": ["chart", "legend"]
+        },
+        {
+          "id": "chart", "component": "Chart",
+          "type": "multi-line", "x": "month", "y": "revenue,users"
+        },
+        {
+          "id": "legend", "component": "ChartLegend",
+          "for": "chart",
+          "shape": "line",
+          "position": "bottom"
+        }
+      ]
+keywords:
+  - legend
+  - chart-legend
+  - series
+  - key
+  - swatch
+  - chart
+  - graph
+  - visualization
+synonyms:
+  chart:
+    - chart-legend
+    - legend
+  legend:
+    - chart-legend
+related:
+  - chart
+  - badge
+  - heatmap