@adia-ai/web-components 0.4.7 → 0.4.9

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;
   }
 }

package/components/swatch/swatch.a2ui.json

@@ -13,6 +13,16 @@
     }
   ],
   "properties": {
+    "autoContrast": {
+      "description": "When set, computes the swatch color's OKLab L and switches the label /\ndetail color between light + dark so it remains legible against the\ntile background. Only applies to shape=\"block\" (where the label sits\nON the tile). Uses a 1px canvas probe to handle any CSS color form\n(oklch / hex / hsl / named / var() references).\n",
+      "type": "boolean",
+      "default": false
+    },
+    "badge": {
+      "description": "Optional marker(s) rendered in the upper-right of the tile. Single value\nOR comma/space-separated list of variants (v0.4.9+ multi-badge support).\nVariants: out-of-gamut (△), p3-only (✦), apca-pass (✓), apca-fail (✗).\nEach pip carries an aria-label so screen readers surface the semantic\n(\"Outside sRGB gamut\", \"Contrast passes APCA\", etc.). Unknown variants\nare silently dropped.\n",
+      "type": "string",
+      "default": ""
+    },
     "color": {
       "description": "Swatch color. Accepts any CSS color value or var() reference. Sets the internal --swatch-color custom property; consumers can also set --swatch-color via inline style.",
       "type": "string",
@@ -21,11 +31,36 @@
     "component": {
       "const": "Swatch"
     },
+    "copyable": {
+      "description": "When set, renders an inline copy-to-clipboard button. Defaults to copying [color]; override via [copy-value].",
+      "type": "boolean",
+      "default": false
+    },
+    "copyValue": {
+      "description": "Override what gets copied when [copyable] is set. Defaults to [color]. Not reflected (color strings are long; attr round-tripping reads poorly).",
+      "type": "string",
+      "default": ""
+    },
+    "detail": {
+      "description": "Optional secondary line of text rendered below the label. Typically the raw token value (e.g. \"oklch(0.53 0.18 240)\") when the swatch represents a design-token step.",
+      "type": "string",
+      "default": ""
+    },
     "label": {
       "description": "Optional label rendered next to (or below, for shape=\"block\") the swatch. Use the default slot for richer content.",
       "type": "string",
       "default": ""
     },
+    "selectable": {
+      "description": "When set, makes the swatch keyboard-focusable + clickable. Sets role=\"button\" + tabindex=\"0\". Dispatches a \"select\" event on activation (click / Enter / Space).",
+      "type": "boolean",
+      "default": false
+    },
+    "selected": {
+      "description": "Reflected visual selected state. Pair with [selectable] to make the swatch behave like a radio-style picker. Sets aria-pressed.",
+      "type": "boolean",
+      "default": false
+    },
     "shape": {
       "description": "Visual shape — block (filled tile), dot (small circle), square (small filled square), line (solid hairline), dashed (dashed hairline).",
       "type": "string",
@@ -56,7 +91,26 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
-    "events": {},
+    "composes": [],
+    "events": {
+      "select": {
+        "description": "Fired when a selectable swatch is activated (click / Enter / Space). detail carries the swatch's value, color, and label.",
+        "detail": {
+          "color": {
+            "description": "The raw [color] attribute value.",
+            "type": "string"
+          },
+          "label": {
+            "description": "The [label] attribute value.",
+            "type": "string"
+          },
+          "value": {
+            "description": "The swatch's effective value — [color] when present, else [label].",
+            "type": "string"
+          }
+        }
+      }
+    },
     "examples": [
       {
         "description": "A single dot swatch with text label, e.g. as a chart-legend row.",
@@ -93,6 +147,11 @@
       {
         "description": "Default, ready for display.",
         "name": "idle"
+      },
+      {
+        "description": "Reflected when the swatch is in the selected state (pair with [selectable]).",
+        "attribute": "selected",
+        "name": "selected"
       }
     ],
     "synonyms": {
@@ -106,8 +165,17 @@
     },
     "tag": "swatch-ui",
     "tokens": {
+      "--swatch-badge-fg": {
+        "description": "Color of the badge symbol. Defaults to chrome-foreground; overridden per-badge variant."
+      },
       "--swatch-color": {
         "description": "Resolved color of the swatch fill / line. Wins over the [color] attr if set inline."
+      },
+      "--swatch-detail-fg": {
+        "description": "Color of the secondary detail line. Defaults to subtle-foreground."
+      },
+      "--swatch-select-ring": {
+        "description": "Color of the focus + selected ring when [selectable] is set."
       }
     },
     "traits": [],