@adia-ai/web-components 0.4.8 → 0.5.0

package/components/otp-input/otp-input.d.ts

@@ -12,6 +12,16 @@ export interface OtpInputEventDetail {
 }
 export type OtpInputEvent = CustomEvent<OtpInputEventDetail>;
 
+/**
+ * Detail payload for the `complete` event — fired exactly once when the
+ * user fills the last digit slot. `value` is the full combined string at
+ * the moment of completion.
+ */
+export interface OtpInputCompleteEventDetail {
+  value: string;
+}
+export type OtpInputCompleteEvent = CustomEvent<OtpInputCompleteEventDetail>;
+
 export class UIOtpInput extends UIFormElement {
   /** Number of digit slots. */
   length: number;
@@ -22,4 +32,5 @@ export class UIOtpInput extends UIFormElement {
     options?: boolean | AddEventListenerOptions,
   ): void;
   addEventListener(type: 'input', listener: (ev: OtpInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'complete', listener: (ev: OtpInputCompleteEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/otp-input/otp-input.yaml

@@ -25,9 +25,17 @@ props:
     default: ''
 events:
   complete:
-    description: Fired when all digits are filled. Detail contains { code }.
+    description: Fired exactly once when the user fills the last digit slot. detail.value is the combined string.
+    detail:
+      value:
+        type: string
+        description: Combined digits (e.g. "123456").
   input:
-    description: Fired on every digit change
+    description: Fired on every digit change. detail.value is the current combined string.
+    detail:
+      value:
+        type: string
+        description: Combined digits at the moment of the change.
 slots:
   field:
     description: Container for the digit input boxes and optional separator

package/components/pagination/pagination.a2ui.json

@@ -47,7 +47,13 @@
     "composes": [],
     "events": {
       "page-change": {
-        "description": "Fired when a page button is clicked. detail contains { page }."
+        "description": "Fired when a page button is clicked. detail contains { page }.",
+        "detail": {
+          "page": {
+            "description": "New page number.",
+            "type": "number"
+          }
+        }
       }
     },
     "examples": [

package/components/pagination/pagination.d.ts

@@ -12,7 +12,12 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type PaginationPageChangeEvent = CustomEvent<unknown>;
+export interface PaginationPageChangeEventDetail {
+  /** New page number. */
+  page: number;
+}
+
+export type PaginationPageChangeEvent = CustomEvent<PaginationPageChangeEventDetail>;
 
 export class UIPagination extends UIElement {
   /** Current active page number. */

package/components/pagination/pagination.yaml

@@ -27,6 +27,10 @@ props:
 events:
   page-change:
     description: Fired when a page button is clicked. detail contains { page }.
+    detail:
+      page:
+        type: number
+        description: New page number.
 slots: {}
 states:
   - name: idle

package/components/stream/stream.a2ui.json

@@ -45,7 +45,13 @@
         "description": "Fired when stream completes naturally"
       },
       "stream-error": {
-        "description": "Fired on stream error, detail: { error }"
+        "description": "Fired on stream error, detail: { error }",
+        "detail": {
+          "error": {
+            "description": "Error object or message.",
+            "type": "object"
+          }
+        }
       },
       "stream-start": {
         "description": "Fired when streaming begins"

package/components/stream/stream.d.ts

@@ -13,7 +13,12 @@
 import { UIElement } from '../../core/element.js';
 
 export type StreamEndEvent = CustomEvent<unknown>;
-export type StreamErrorEvent = CustomEvent<unknown>;
+export interface StreamErrorEventDetail {
+  /** Error object or message. */
+  error: Record<string, unknown>;
+}
+
+export type StreamErrorEvent = CustomEvent<StreamErrorEventDetail>;
 export type StreamStartEvent = CustomEvent<unknown>;
 
 export class UIStream extends UIElement {

package/components/stream/stream.yaml

@@ -25,6 +25,10 @@ events:
     description: Fired when stream completes naturally
   stream-error:
     description: "Fired on stream error, detail: { error }"
+    detail:
+      error:
+        type: object
+        description: Error object or message.
   stream-start:
     description: Fired when streaming begins
 slots:

package/components/swatch/class.js

@@ -19,59 +19,201 @@
  * theme-preview pill. Replaces docs-only `<span data-swatch>` usage and
  * the per-shape CSS that used to live inside chart-legend-ui.
  *
+ * v0.4.9 extends the primitive with the design-token-tile use case
+ * (FEEDBACK-04 #2): badge marker, second-line detail, copy-to-clipboard
+ * button, keyboard-selectable + reflected `[selected]` state.
+ *
  * Usage:
  *   <swatch-ui shape="dot" color="var(--a-data-0)" label="Revenue"></swatch-ui>
  *   <swatch-ui shape="block" size="lg" color="var(--a-neutral-50)" label="50"></swatch-ui>
  *   <swatch-ui shape="line" color="#0ea5e9">Forecast</swatch-ui>
  *
+ *   <!-- design-token tile with full feature set -->
+ *   <swatch-ui
+ *     shape="block" size="lg"
+ *     color="oklch(0.53 0.18 240)"
+ *     label="500"
+ *     detail="oklch(0.53 0.18 240)"
+ *     badge="apca-pass"
+ *     copyable
+ *     selectable
+ *   ></swatch-ui>
+ *
  * Attributes:
- *   shape  — block | dot | square | line | dashed (default square)
- *   size   — sm | md | lg (default md). lg is the 40px-tall token-scale block.
- *   color  — any CSS color (or var() ref). Sets --swatch-color internally.
- *   label  — optional text label rendered beside / below the swatch
+ *   shape       block | dot | square | line | dashed                (default square)
+ *   size        sm | md | lg                                         (default md)
+ *   color       any CSS color (or var() ref)
+ *   label       text label rendered beside / below the swatch
+ *   detail      secondary line of text (e.g. raw token value)
+ *   badge       out-of-gamut | p3-only | apca-pass | apca-fail       (optional marker)
+ *   copyable    boolean — render an inline copy button
+ *   copy-value  string — value to copy (defaults to [color] when copyable)
+ *   selectable  boolean — make the swatch focusable + clickable
+ *   selected    boolean — reflected visual selected state
+ *
+ * Events:
+ *   select      dispatched when a selectable swatch is activated
+ *                 (click / Enter / Space). detail: { value, color, label }.
  *
  * Slots:
- *   default — rich label content; takes precedence over [label] attr
+ *   default     rich label content; takes precedence over [label] attr
+ *
+ * Stamping is light-DOM with up to five children:
+ *   <span data-tile></span>            colored shape
+ *   <span data-badge></span>           gamut / contrast marker (optional)
+ *   <span data-label></span>           label text
+ *   <span data-detail></span>          secondary line (optional)
+ *   <button data-copy></button>        copy-to-clipboard (optional)
  *
- * Stamping is light-DOM with two children:
- *   <span data-tile></span>     — the colored shape
- *   <span data-label></span>    — the label text (omitted when no label/slot)
+ * Accessibility:
+ *   - When [selectable], host is role="button" + tabindex="0";
+ *     Enter / Space activate.
+ *   - When [selected], aria-pressed="true" reflects the state.
+ *   - The badge has aria-label (mapped per variant) so screen readers
+ *     surface "out of gamut", "P3-only", etc.
  */
 
 import { UIElement } from '../../core/element.js';
 
 const SHAPES = new Set(['block', 'dot', 'square', 'line', 'dashed']);
 const SIZES = new Set(['sm', 'md', 'lg']);
+const BADGE_VARIANTS = new Set(['out-of-gamut', 'p3-only', 'apca-pass', 'apca-fail']);
+
+const BADGE_SYMBOLS = {
+  'out-of-gamut': '△',
+  'p3-only':      '✦',
+  'apca-pass':    '✓',
+  'apca-fail':    '✗',
+};
+
+const BADGE_LABELS = {
+  'out-of-gamut': 'Outside sRGB gamut',
+  'p3-only':      'Display-P3 only',
+  'apca-pass':    'Contrast passes APCA',
+  'apca-fail':    'Contrast fails APCA',
+};
+
+/**
+ * Parse the [badge] attribute into a normalized array. Supports:
+ *   badge="apca-pass"                  → ['apca-pass']
+ *   badge="out-of-gamut, apca-fail"    → ['out-of-gamut', 'apca-fail']
+ *   badge="out-of-gamut apca-fail"     → ['out-of-gamut', 'apca-fail']
+ *   badge=""                           → []
+ * Drops unknown variants silently (consumer-typed-by-attr defense).
+ */
+function parseBadges(value) {
+  if (!value) return [];
+  return value
+    .split(/[\s,]+/)
+    .map((s) => s.trim())
+    .filter((s) => s && BADGE_VARIANTS.has(s));
+}
+
+/**
+ * Compute perceived lightness (OKLCH L, 0–1) of a CSS color string. Returns
+ * null when the color isn't a hex / oklch / rgb / named CSS color that we
+ * can parse. Used to pick a light vs dark label color for auto-contrast.
+ *
+ * Strategy: render the color into a temporary canvas, read the sRGB pixel,
+ * convert to linear-light sRGB → OKLab L. This is ~3x cheaper than parsing
+ * the CSS color string ourselves and handles every CSS color form the
+ * browser supports (oklch, hsl, named, hex, currentColor via fallback).
+ */
+let _lumProbeCtx = null;
+function colorLuminance(cssColor) {
+  if (!cssColor || typeof cssColor !== 'string') return null;
+  if (typeof document === 'undefined') return null;
+  try {
+    if (!_lumProbeCtx) {
+      const canvas = document.createElement('canvas');
+      canvas.width = 1;
+      canvas.height = 1;
+      _lumProbeCtx = canvas.getContext('2d');
+    }
+    _lumProbeCtx.fillStyle = '#000';
+    _lumProbeCtx.clearRect(0, 0, 1, 1);
+    _lumProbeCtx.fillStyle = cssColor;
+    _lumProbeCtx.fillRect(0, 0, 1, 1);
+    const [r, g, b] = _lumProbeCtx.getImageData(0, 0, 1, 1).data;
+    if (r === 0 && g === 0 && b === 0 && cssColor !== '#000' && cssColor !== 'black' && cssColor !== '#000000') {
+      // Canvas rejected the color string (e.g. var() that doesn't resolve in this context).
+      return null;
+    }
+    // sRGB → linear-light, then OKLab L (Björn Ottosson's approximation).
+    const lin = (c) => {
+      const x = c / 255;
+      return x <= 0.04045 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4);
+    };
+    const lr = lin(r), lg = lin(g), lb = lin(b);
+    const l_ = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+    const m_ = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+    const s_ = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+    return 0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_;
+  } catch {
+    return null;
+  }
+}
 
 export class UISwatch extends UIElement {
   static properties = {
-    shape: { type: String, default: 'square', reflect: true },
-    size:  { type: String, default: 'md',     reflect: true },
-    color: { type: String, default: '',       reflect: true },
-    label: { type: String, default: '',       reflect: true },
+    shape:        { type: String,  default: 'square', reflect: true },
+    size:         { type: String,  default: 'md',     reflect: true },
+    color:        { type: String,  default: '',       reflect: true },
+    label:        { type: String,  default: '',       reflect: true },
+    detail:       { type: String,  default: '',       reflect: true },
+    badge:        { type: String,  default: '',       reflect: true },
+    copyable:     { type: Boolean, default: false,    reflect: true },
+    copyValue:    { type: String,  default: '' },  // not reflected — long color strings as attrs read poorly
+    selectable:   { type: Boolean, default: false,    reflect: true },
+    selected:     { type: Boolean, default: false,    reflect: true },
+    autoContrast: { type: Boolean, default: false,    reflect: true },
   };
 
   static template = () => null;
 
   #tileEl = null;
   #labelEl = null;
+  #detailEl = null;
+  #badgeEl = null;
+  #copyEl = null;
   #stamped = false;
+  #lastColorForContrast = null;
+
+  // Bound handlers — held so we can remove them in disconnected().
+  #onHostClick = null;
+  #onHostKey = null;
+  #onCopyClick = null;
+  #copyResetTimer = null;
 
   connected() {
     this.#stamp();
+    this.#wireInteraction();
   }
 
   render() {
     this.#stamp();
-    this.#sync();
+    this.#syncCore();
+    this.#syncBadge();
+    this.#syncDetail();
+    this.#syncCopy();
+    this.#syncSelectable();
+    this.#syncAutoContrast();
   }
 
+  // ── Stamping ──────────────────────────────────────────────────────
+
   #stamp() {
     if (this.#stamped) return;
     // Capture pre-existing default-slot content so consumer-authored
     // children (e.g. <swatch-ui>Forecast</swatch-ui>) survive stamping.
     const slotted = Array.from(this.childNodes).filter(n =>
-      !(n.nodeType === 1 && (n.dataset?.tile !== undefined || n.dataset?.label !== undefined))
+      !(n.nodeType === 1 && n.dataset && (
+        n.dataset.tile !== undefined ||
+        n.dataset.label !== undefined ||
+        n.dataset.detail !== undefined ||
+        n.dataset.badge !== undefined ||
+        n.dataset.copy !== undefined
+      ))
     );
     this.innerHTML = '';
 
@@ -80,6 +222,13 @@ export class UISwatch extends UIElement {
     this.#tileEl.setAttribute('aria-hidden', 'true');
     this.appendChild(this.#tileEl);
 
+    // Badge container — holds one or more <span data-badge-variant="..."> children.
+    // Multi-badge support added in v0.4.9 §92 (FEEDBACK-04 follow-up).
+    this.#badgeEl = document.createElement('span');
+    this.#badgeEl.setAttribute('data-badge', '');
+    this.#badgeEl.setAttribute('hidden', '');
+    this.appendChild(this.#badgeEl);
+
     this.#labelEl = document.createElement('span');
     this.#labelEl.setAttribute('data-label', '');
     if (slotted.length) {
@@ -87,10 +236,25 @@ export class UISwatch extends UIElement {
     }
     this.appendChild(this.#labelEl);
 
+    this.#detailEl = document.createElement('span');
+    this.#detailEl.setAttribute('data-detail', '');
+    this.#detailEl.setAttribute('hidden', '');
+    this.appendChild(this.#detailEl);
+
+    this.#copyEl = document.createElement('button');
+    this.#copyEl.setAttribute('data-copy', '');
+    this.#copyEl.setAttribute('type', 'button');
+    this.#copyEl.setAttribute('aria-label', 'Copy value');
+    this.#copyEl.setAttribute('hidden', '');
+    this.#copyEl.textContent = '⧉';
+    this.appendChild(this.#copyEl);
+
     this.#stamped = true;
   }
 
-  #sync() {
+  // ── Sync ──────────────────────────────────────────────────────────
+
+  #syncCore() {
     if (!this.#tileEl || !this.#labelEl) return;
 
     // Normalize enum values; fall back silently when a consumer sets a typo.
@@ -123,9 +287,192 @@ export class UISwatch extends UIElement {
     this.#labelEl.toggleAttribute('hidden', !hasLabel);
   }
 
+  #syncBadge() {
+    if (!this.#badgeEl) return;
+    const badges = parseBadges(this.badge);
+    if (badges.length === 0) {
+      this.#badgeEl.setAttribute('hidden', '');
+      this.#badgeEl.replaceChildren();
+      return;
+    }
+    this.#badgeEl.removeAttribute('hidden');
+    // Diff against existing children — replace only if the variant set changed.
+    const declared = Array.from(this.#badgeEl.children).map((c) => c.dataset.badgeVariant);
+    const same = declared.length === badges.length && declared.every((v, i) => v === badges[i]);
+    if (same) return;
+    const frag = document.createDocumentFragment();
+    for (const variant of badges) {
+      const pip = document.createElement('span');
+      pip.setAttribute('data-badge-variant', variant);
+      pip.setAttribute('role', 'img');
+      pip.setAttribute('aria-label', BADGE_LABELS[variant]);
+      pip.textContent = BADGE_SYMBOLS[variant];
+      frag.appendChild(pip);
+    }
+    this.#badgeEl.replaceChildren(frag);
+  }
+
+  /**
+   * Auto-contrast — switch the label color between light/dark when the
+   * resolved swatch color crosses an OKLab L threshold. Uses a 1px canvas
+   * probe to handle any CSS color form (oklch / hex / hsl / named / var()).
+   * Pre-resolves currentColor by way of computed style so consumers can
+   * pass var() refs and get correct math.
+   */
+  #syncAutoContrast() {
+    if (!this.#labelEl) return;
+    if (!this.autoContrast) {
+      this.#labelEl.removeAttribute('data-on-light');
+      this.#labelEl.removeAttribute('data-on-dark');
+      this.#lastColorForContrast = null;
+      return;
+    }
+    // Resolve the actual rendered color. For var(...) refs the inline
+    // [color] attr is what was set; we read from computed style so that
+    // CSS-resolved tokens (e.g. var(--a-accent)) get their final value.
+    const probe = this.color || getComputedStyle(this).getPropertyValue('--swatch-color').trim();
+    if (probe === this.#lastColorForContrast) return;
+    this.#lastColorForContrast = probe;
+    const L = colorLuminance(probe);
+    if (L == null) {
+      this.#labelEl.removeAttribute('data-on-light');
+      this.#labelEl.removeAttribute('data-on-dark');
+      return;
+    }
+    // Threshold ~0.62 OKLab L matches WCAG-aligned light/dark text choice
+    // for sRGB. Adjust by --swatch-auto-contrast-threshold if needed.
+    const onDark = L < 0.62;
+    this.#labelEl.toggleAttribute('data-on-dark', onDark);
+    this.#labelEl.toggleAttribute('data-on-light', !onDark);
+  }
+
+  #syncDetail() {
+    if (!this.#detailEl) return;
+    const text = (this.detail || '').trim();
+    if (!text) {
+      this.#detailEl.setAttribute('hidden', '');
+      this.#detailEl.textContent = '';
+      return;
+    }
+    this.#detailEl.removeAttribute('hidden');
+    if (this.#detailEl.textContent !== text) this.#detailEl.textContent = text;
+  }
+
+  #syncCopy() {
+    if (!this.#copyEl) return;
+    if (!this.copyable) {
+      this.#copyEl.setAttribute('hidden', '');
+      return;
+    }
+    this.#copyEl.removeAttribute('hidden');
+    // aria-label reflects what will be copied so screen readers
+    // announce the target value.
+    const value = this.#copyTargetValue();
+    if (value) this.#copyEl.setAttribute('aria-label', `Copy ${value}`);
+    else this.#copyEl.setAttribute('aria-label', 'Copy value');
+  }
+
+  #syncSelectable() {
+    if (this.selectable) {
+      if (!this.hasAttribute('role')) this.setAttribute('role', 'button');
+      if (!this.hasAttribute('tabindex')) this.setAttribute('tabindex', '0');
+      this.setAttribute('aria-pressed', this.selected ? 'true' : 'false');
+    } else {
+      // Only remove ARIA we set; respect consumer-set roles.
+      if (this.getAttribute('role') === 'button') this.removeAttribute('role');
+      if (this.getAttribute('tabindex') === '0') this.removeAttribute('tabindex');
+      this.removeAttribute('aria-pressed');
+    }
+  }
+
+  // ── Interaction wiring ────────────────────────────────────────────
+
+  #wireInteraction() {
+    this.#onHostClick = (e) => {
+      if (!this.selectable) return;
+      // Ignore clicks that originated in the copy button — that's a
+      // separate affordance and should not also toggle selection.
+      const path = e.composedPath ? e.composedPath() : [];
+      if (path.includes(this.#copyEl)) return;
+      this.#activate();
+    };
+    this.#onHostKey = (e) => {
+      if (!this.selectable) return;
+      if (e.key !== 'Enter' && e.key !== ' ') return;
+      // Don't steal Space when focus is in the copy button.
+      if (e.target === this.#copyEl) return;
+      e.preventDefault();
+      this.#activate();
+    };
+    this.addEventListener('click', this.#onHostClick);
+    this.addEventListener('keydown', this.#onHostKey);
+
+    this.#onCopyClick = (e) => {
+      e.stopPropagation();
+      if (!this.copyable) return;
+      const value = this.#copyTargetValue();
+      if (!value) return;
+      this.#doCopy(value);
+    };
+    this.#copyEl.addEventListener('click', this.#onCopyClick);
+  }
+
+  #activate() {
+    this.dispatchEvent(new CustomEvent('select', {
+      bubbles: true,
+      detail: {
+        value: this.color || this.label,
+        color: this.color,
+        label: this.label,
+      },
+    }));
+  }
+
+  #copyTargetValue() {
+    if (this.copyValue) return this.copyValue;
+    if (this.color) return this.color;
+    return '';
+  }
+
+  async #doCopy(value) {
+    let ok = false;
+    try {
+      if (navigator?.clipboard?.writeText) {
+        await navigator.clipboard.writeText(value);
+        ok = true;
+      }
+    } catch { /* ignore — feedback below */ }
+    this.#flashCopyResult(ok);
+  }
+
+  #flashCopyResult(ok) {
+    if (!this.#copyEl) return;
+    if (this.#copyResetTimer != null) clearTimeout(this.#copyResetTimer);
+    this.#copyEl.setAttribute('data-copy-state', ok ? 'ok' : 'fail');
+    this.#copyEl.textContent = ok ? '✓' : '⚠';
+    this.#copyResetTimer = setTimeout(() => {
+      if (!this.#copyEl) return;
+      this.#copyEl.removeAttribute('data-copy-state');
+      this.#copyEl.textContent = '⧉';
+      this.#copyResetTimer = null;
+    }, 1200);
+  }
+
+  // ── Teardown ──────────────────────────────────────────────────────
+
   disconnected() {
+    if (this.#copyResetTimer != null) {
+      clearTimeout(this.#copyResetTimer);
+      this.#copyResetTimer = null;
+    }
+    if (this.#onHostClick) this.removeEventListener('click', this.#onHostClick);
+    if (this.#onHostKey)   this.removeEventListener('keydown', this.#onHostKey);
+    if (this.#copyEl && this.#onCopyClick) this.#copyEl.removeEventListener('click', this.#onCopyClick);
     this.#tileEl = null;
     this.#labelEl = null;
+    this.#detailEl = null;
+    this.#badgeEl = null;
+    this.#copyEl = null;
     this.#stamped = false;
   }
 }