@profpowell/vb-design-system 0.1.0

package/src/utils/copy-init.js

@@ -0,0 +1,287 @@
+/**
+ * copy-init: Clipboard copy + paste via data attributes + programmatic helpers
+ *
+ * Enhances buttons with data-copy / data-copy-target / data-paste-target
+ * to interact with the clipboard. Also exports copyText(), copyRich(),
+ * and pasteFromClipboard() for components that need clipboard access
+ * with VB's standard a11y + feedback semantics.
+ *
+ * @attr {string} data-copy - Static text to copy
+ * @attr {string} data-copy-target - CSS selector for element whose textContent to copy
+ * @attr {string} data-copy-attr - When paired with data-copy-target, copy the named
+ *                                 attribute of the target instead of its textContent
+ * @attr {string} data-paste-target - CSS selector for element to receive pasted clipboard text
+ *
+ * @example Static text
+ * <button data-copy="npm install vanilla-breeze">Copy</button>
+ *
+ * @example Target element
+ * <button data-copy-target="#code-block">Copy code</button>
+ *
+ * @example Target attribute
+ * <output id="swatch" value="#3366cc">#3366cc</output>
+ * <button data-copy-target="#swatch" data-copy-attr="value">Copy hex</button>
+ *
+ * @example Paste into a target
+ * <input id="dest" type="text">
+ * <button data-paste-target="#dest">Paste</button>
+ *
+ * @example Programmatic
+ * import { copyText, copyRich, pasteFromClipboard } from '/src/utils/copy-init.js';
+ * await copyText('hello', { button: myButton });
+ * await copyRich({ text: '#3366cc', blob: pngBlob }, { button: myButton });
+ * await pasteFromClipboard(inputEl, { button: myButton });
+ */
+
+const COPIED_DURATION = 1500;
+const ANNOUNCE_DURATION = 1000;
+const SELECTOR = '[data-copy], [data-copy-target], [data-paste-target]';
+const DEFAULT_ANNOUNCE = 'Copied to clipboard';
+const DEFAULT_PASTE_ANNOUNCE = 'Pasted from clipboard';
+
+const resetTimers = new WeakMap();
+
+/**
+ * Copy text to the clipboard with VB's standard feedback semantics.
+ *
+ * Performs writeText, sets data-state="copied" on the button (if given),
+ * announces to screen readers, and dispatches a `copy` CustomEvent from
+ * the button. Safe to call when the Clipboard API is unavailable or
+ * permission is denied — returns false silently.
+ *
+ * @param {string} text - The text to copy.
+ * @param {object} [options]
+ * @param {HTMLElement} [options.button] - Button to receive data-state and dispatch the event.
+ * @param {string} [options.announceMessage] - Screen-reader message. Defaults to "Copied to clipboard".
+ * @param {number} [options.duration] - Milliseconds to hold data-state="copied". Defaults to 1500.
+ * @returns {Promise<boolean>} True if the write succeeded.
+ */
+async function copyText(text, options = {}) {
+  if (text == null || text === '') return false;
+  const { button, announceMessage = DEFAULT_ANNOUNCE, duration = COPIED_DURATION } = options;
+
+  try {
+    await navigator.clipboard.writeText(text);
+  } catch {
+    return false;
+  }
+
+  applyFeedback({ button, duration, announceMessage, eventDetail: { text } });
+  return true;
+}
+
+/**
+ * Copy a multi-format payload to the clipboard.
+ *
+ * Writes a ClipboardItem with any combination of text/plain, text/html,
+ * and a binary blob (typically image/png). When ClipboardItem is
+ * unsupported or the browser rejects the specific MIME types, falls
+ * back to text-only copy via copyText.
+ *
+ * Common use cases: copying a color as hex text + a swatch PNG so it
+ * can be pasted into design tools as an actual color, or copying a
+ * QR code as an image alongside its encoded URL.
+ *
+ * @param {object} payload
+ * @param {string} [payload.text] - text/plain content
+ * @param {string} [payload.html] - text/html content
+ * @param {Blob}   [payload.blob] - Arbitrary blob (e.g. image/png). MIME type comes from blob.type.
+ * @param {object} [options]
+ * @param {HTMLElement} [options.button]
+ * @param {string} [options.announceMessage]
+ * @param {number} [options.duration]
+ * @returns {Promise<boolean>} True if any clipboard write succeeded (rich or text fallback).
+ */
+async function copyRich(payload, options = {}) {
+  const { text, html, blob } = payload ?? {};
+  if (!text && !html && !blob) return false;
+  const { button, announceMessage = DEFAULT_ANNOUNCE, duration = COPIED_DURATION } = options;
+
+  const richSupported = typeof ClipboardItem !== 'undefined' && typeof navigator.clipboard?.write === 'function';
+
+  if (richSupported) {
+    /** @type {Record<string, Blob>} */
+    const items = {};
+    if (text) items['text/plain'] = new Blob([text], { type: 'text/plain' });
+    if (html) items['text/html'] = new Blob([html], { type: 'text/html' });
+    if (blob) items[blob.type] = blob;
+
+    try {
+      await navigator.clipboard.write([new ClipboardItem(items)]);
+      applyFeedback({ button, duration, announceMessage, eventDetail: { payload } });
+      return true;
+    } catch {
+      // Browser may support ClipboardItem but reject some MIME types
+      // (Safari historically restricts image types). Fall through to text.
+    }
+  }
+
+  if (text) return copyText(text, options);
+  return false;
+}
+
+/**
+ * Apply the VB-standard post-write feedback: data-state, screen-reader
+ * announce, and a CustomEvent from the button.
+ * @param {{ button?: HTMLElement, duration: number, announceMessage: string, eventDetail: object, state?: string, eventName?: string }} args
+ */
+function applyFeedback({ button, duration, announceMessage, eventDetail, state = 'copied', eventName = 'copy' }) {
+  if (button) {
+    button.dataset.state = state;
+    const prior = resetTimers.get(button);
+    if (prior) clearTimeout(prior);
+    resetTimers.set(button, setTimeout(() => {
+      delete button.dataset.state;
+      resetTimers.delete(button);
+    }, duration));
+
+    button.dispatchEvent(new CustomEvent(eventName, {
+      bubbles: true,
+      detail: eventDetail,
+    }));
+  }
+
+  announce(announceMessage, button ?? document.body);
+}
+
+/**
+ * Read text from the clipboard and write it into a target element.
+ *
+ * Form controls (input, textarea, select) receive `.value`; other
+ * elements receive `.textContent`. After writing, an `input` event
+ * is dispatched on the target so framework listeners notice the change.
+ * Sets data-state="pasted" on the button, announces to screen readers,
+ * and dispatches a `paste` CustomEvent from the button.
+ *
+ * Safe to call when the Clipboard API is unavailable or the user
+ * denies permission — returns null silently.
+ *
+ * @param {Element | null | undefined} target - Element to receive the pasted text.
+ * @param {object} [options]
+ * @param {HTMLElement} [options.button]
+ * @param {string} [options.announceMessage]
+ * @param {number} [options.duration]
+ * @returns {Promise<string | null>} The text that was pasted, or null on failure.
+ */
+async function pasteFromClipboard(target, options = {}) {
+  const { button, announceMessage = DEFAULT_PASTE_ANNOUNCE, duration = COPIED_DURATION } = options;
+
+  let text;
+  try {
+    text = await navigator.clipboard.readText();
+  } catch {
+    return null;
+  }
+
+  if (target) {
+    if ('value' in target && (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement)) {
+      target.value = text;
+    } else {
+      target.textContent = text;
+    }
+    target.dispatchEvent(new Event('input', { bubbles: true }));
+  }
+
+  applyFeedback({
+    button,
+    duration,
+    announceMessage,
+    eventDetail: { text },
+    state: 'pasted',
+    eventName: 'paste',
+  });
+  return text;
+}
+
+/**
+ * Initialize copy/paste buttons within a root element
+ * @param {Element|Document} root - Root element to search within
+ */
+function initCopyButtons(root = document) {
+  root.querySelectorAll(SELECTOR).forEach(enhanceButton);
+}
+
+/**
+ * Enhance a single button with copy or paste behavior
+ * @param {HTMLElement} button - The button element to enhance
+ */
+function enhanceButton(button) {
+  if (button.hasAttribute('data-copy-init')) return;
+  button.setAttribute('data-copy-init', '');
+
+  button.addEventListener('click', () => {
+    if (button.dataset.pasteTarget) {
+      const target = document.querySelector(button.dataset.pasteTarget);
+      if (!target) return;
+      pasteFromClipboard(target, { button });
+      return;
+    }
+
+    const text = getText(button);
+    if (!text) return;
+    copyText(text, { button });
+  });
+}
+
+/**
+ * Get text to copy from a button's data attributes
+ * @param {HTMLElement} button
+ * @returns {string}
+ */
+function getText(button) {
+  if (button.dataset.copy) return button.dataset.copy;
+
+  if (button.dataset.copyTarget) {
+    const target = document.querySelector(button.dataset.copyTarget);
+    if (!target) return '';
+    const attr = button.dataset.copyAttr;
+    if (attr) return target.getAttribute(attr) ?? '';
+    return target.textContent ?? '';
+  }
+
+  return '';
+}
+
+/**
+ * Announce a message to screen readers
+ * @param {string} message
+ * @param {Element} context - Element to append announcement to
+ */
+function announce(message, context) {
+  const el = document.createElement('div');
+  el.setAttribute('role', 'status');
+  el.setAttribute('aria-live', 'polite');
+  el.className = 'visually-hidden';
+  el.textContent = message;
+  context.appendChild(el);
+  setTimeout(() => el.remove(), ANNOUNCE_DURATION);
+}
+
+// Auto-init on DOMContentLoaded
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', () => initCopyButtons());
+} else {
+  initCopyButtons();
+}
+
+// Watch for dynamically added copy buttons
+const observer = new MutationObserver((mutations) => {
+  for (const mutation of mutations) {
+    for (const node of mutation.addedNodes) {
+      if (node.nodeType !== Node.ELEMENT_NODE) continue;
+
+      // Check the node itself
+      const el = /** @type {Element} */ (node);
+      if (el.matches(SELECTOR)) {
+        enhanceButton(/** @type {HTMLElement} */ (el));
+      }
+
+      // Check descendants
+      el.querySelectorAll(SELECTOR).forEach(child => enhanceButton(/** @type {HTMLElement} */ (child)));
+    }
+  }
+});
+
+observer.observe(document.documentElement, { childList: true, subtree: true });
+
+export { initCopyButtons, copyText, copyRich, pasteFromClipboard };

package/src/web-components/accessibility-specimen/api.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "accessibility-specimen",
+  "type": "web-component",
+  "description": "WCAG contrast-ratio table + a11y checklist for design-system docs. Default mode: tabular display of color pairs with computed contrast ratio + AA/AAA badges. Checklist mode: slot-driven WCAG checklist with status icons.",
+  "htmlvalidate": {
+    "flow": true,
+    "permittedContent": [
+      "@flow"
+    ]
+  },
+  "attributes": [
+    {
+      "name": "type",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "\"contrast\" (default) | \"checklist\""
+    }
+  ],
+  "events": [],
+  "childAttributes": [
+    {
+      "name": "data-fg",
+      "on": "button",
+      "type": "string",
+      "required": true,
+      "description": "Foreground color (hex / rgb() / named); contrast mode"
+    },
+    {
+      "name": "data-bg",
+      "on": "button",
+      "type": "string",
+      "required": true,
+      "description": "Background color (hex / rgb() / named); contrast mode"
+    },
+    {
+      "name": "data-label",
+      "on": "button",
+      "type": "string",
+      "description": "Display label for the pair; defaults to button text content"
+    },
+    {
+      "name": "data-status",
+      "on": "li",
+      "type": "string",
+      "description": "Checklist mode: pass | fail | warn | na (default: na)"
+    }
+  ],
+  "structure": []
+}

package/src/web-components/accessibility-specimen/logic.js

@@ -0,0 +1,232 @@
+/**
+ * accessibility-specimen: WCAG contrast-ratio table + a11y checklist
+ * for design-system docs.
+ *
+ * Two modes:
+ *   - "contrast" (default): tabular display of foreground / background
+ *     color pairs with computed WCAG 2.x contrast ratio + AA/AAA badges
+ *     for normal- and large-text. Author provides pairs as direct
+ *     `<button data-fg data-bg [data-label]>` children.
+ *   - "checklist": author authors a `<ul>` of items with `data-status=
+ *     pass|fail|warn|na` (or none → unset). Component normalizes the
+ *     visual styling and adds an icon per status.
+ *
+ * @attr {string} type - "contrast" (default) | "checklist"
+ *
+ * Distinct from:
+ *   - <semantic-palette> (palette colors with semantic roles, not pairs)
+ *   - <token-specimen> (token-scale display, single axis)
+ */
+
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+
+// ── Color parsing + WCAG 2.x contrast ─────────────────────────────────
+
+/**
+ * Parse a CSS color string into [r, g, b] (0-255). Supports #hex, #hex8,
+ * rgb()/rgba() and named colors (via a temporary canvas trick). Returns
+ * null on failure so the consumer can show a "?" badge.
+ * @returns {[number, number, number] | null}
+ */
+function parseColor(str) {
+  const s = String(str || '').trim();
+  if (!s) return null;
+  // Hex shorthand / full
+  let m = s.match(/^#([0-9a-f]{3,8})$/i);
+  if (m) {
+    const h = m[1];
+    if (h.length === 3) return [parseInt(h[0]+h[0],16), parseInt(h[1]+h[1],16), parseInt(h[2]+h[2],16)];
+    if (h.length === 4) return [parseInt(h[0]+h[0],16), parseInt(h[1]+h[1],16), parseInt(h[2]+h[2],16)];
+    if (h.length === 6) return [parseInt(h.slice(0,2),16), parseInt(h.slice(2,4),16), parseInt(h.slice(4,6),16)];
+    if (h.length === 8) return [parseInt(h.slice(0,2),16), parseInt(h.slice(2,4),16), parseInt(h.slice(4,6),16)];
+  }
+  // rgb / rgba
+  m = s.match(/^rgba?\s*\(\s*([0-9.]+)[\s,]+([0-9.]+)[\s,]+([0-9.]+)/i);
+  if (m) return [Math.round(+m[1]), Math.round(+m[2]), Math.round(+m[3])];
+  // Fall back to letting the browser resolve via getComputedStyle on a probe.
+  // (Handles named colors, oklch(), color-mix(), etc. — but loses alpha.)
+  if (typeof document !== 'undefined') {
+    const probe = document.createElement('span');
+    probe.style.color = s;
+    probe.style.display = 'none';
+    document.body.appendChild(probe);
+    const cs = getComputedStyle(probe).color;
+    probe.remove();
+    const rgb = cs.match(/^rgba?\s*\(\s*([0-9.]+)[\s,]+([0-9.]+)[\s,]+([0-9.]+)/i);
+    if (rgb) return [Math.round(+rgb[1]), Math.round(+rgb[2]), Math.round(+rgb[3])];
+  }
+  return null;
+}
+
+/** Linearize an sRGB channel per WCAG 2.x. */
+function lin(c) {
+  const v = c / 255;
+  return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+}
+
+/** Relative luminance per WCAG 2.x. */
+function luminance([r, g, b]) {
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** Contrast ratio per WCAG 2.x (returns 1..21, or null on parse failure). */
+function contrastRatio(fg, bg) {
+  const f = parseColor(fg);
+  const b = parseColor(bg);
+  if (!f || !b) return null;
+  const l1 = luminance(f);
+  const l2 = luminance(b);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * @returns {{ aaNormal: boolean, aaLarge: boolean, aaaNormal: boolean, aaaLarge: boolean }}
+ */
+function wcagBadges(ratio) {
+  if (ratio == null) return { aaNormal: false, aaLarge: false, aaaNormal: false, aaaLarge: false };
+  return {
+    aaNormal:  ratio >= 4.5,
+    aaLarge:   ratio >= 3.0,
+    aaaNormal: ratio >= 7.0,
+    aaaLarge:  ratio >= 4.5,
+  };
+}
+
+// ── Component ─────────────────────────────────────────────────────────
+
+class AccessibilitySpecimen extends VBElement {
+  static observedAttributes = ['type'];
+
+  setup() {
+    const type = this.getAttribute('type') || 'contrast';
+    if (type === 'checklist') this.#renderChecklist();
+    else this.#renderContrast();
+  }
+
+  attributeChangedCallback(_name, oldVal, newVal) {
+    if (!this.isConnected || oldVal === newVal) return;
+    this.setup();
+  }
+
+  // ── Contrast mode ─────────────────────────────────────────────────
+
+  #renderContrast() {
+    // Capture authored pairs (button[data-fg][data-bg]) before rebuilding.
+    const pairs = /** @type {HTMLElement[]} */ ([...this.querySelectorAll(':scope > button[data-fg][data-bg]')]).map((b) => ({
+      fg: b.dataset.fg,
+      bg: b.dataset.bg,
+      label: b.dataset.label || b.textContent.trim() || `${b.dataset.fg} on ${b.dataset.bg}`,
+    }));
+
+    const table = document.createElement('table');
+    table.className = 'as-contrast-table';
+
+    const thead = document.createElement('thead');
+    thead.innerHTML = `
+      <tr>
+        <th scope="col">Pair</th>
+        <th scope="col">Sample</th>
+        <th scope="col">Ratio</th>
+        <th scope="col">AA</th>
+        <th scope="col">AA Large</th>
+        <th scope="col">AAA</th>
+        <th scope="col">AAA Large</th>
+      </tr>`;
+    table.appendChild(thead);
+
+    const tbody = document.createElement('tbody');
+    if (pairs.length === 0) {
+      const tr = document.createElement('tr');
+      const td = document.createElement('td');
+      td.colSpan = 7;
+      td.className = 'as-empty';
+      td.textContent = 'No color pairs authored. Add <button data-fg="…" data-bg="…">Label</button> children.';
+      tr.appendChild(td);
+      tbody.appendChild(tr);
+    } else {
+      for (const p of pairs) tbody.appendChild(this.#renderPairRow(p));
+    }
+    table.appendChild(tbody);
+
+    this.replaceChildren(table);
+  }
+
+  #renderPairRow({ fg, bg, label }) {
+    const ratio = contrastRatio(fg, bg);
+    const badges = wcagBadges(ratio);
+    const ratioText = ratio == null ? '?' : `${ratio.toFixed(2)}:1`;
+
+    const tr = document.createElement('tr');
+
+    const tdLabel = document.createElement('th');
+    tdLabel.scope = 'row';
+    tdLabel.className = 'as-pair-label';
+    tdLabel.innerHTML = `<span class="as-swatch" style="background:${bg};border-color:${fg}"></span><span>${escapeText(label)}</span>`;
+    tr.appendChild(tdLabel);
+
+    const tdSample = document.createElement('td');
+    tdSample.className = 'as-pair-sample';
+    tdSample.style.background = bg;
+    tdSample.style.color = fg;
+    tdSample.textContent = 'Aa Bb 123';
+    tr.appendChild(tdSample);
+
+    const tdRatio = document.createElement('td');
+    tdRatio.className = 'as-pair-ratio';
+    tdRatio.textContent = ratioText;
+    tr.appendChild(tdRatio);
+
+    for (const key of ['aaNormal', 'aaLarge', 'aaaNormal', 'aaaLarge']) {
+      const td = document.createElement('td');
+      const ok = badges[key];
+      td.className = `as-badge ${ok ? 'as-pass' : 'as-fail'}`;
+      td.textContent = ok ? '✓' : '✗';
+      td.setAttribute('aria-label', ok ? 'Pass' : 'Fail');
+      tr.appendChild(td);
+    }
+
+    return tr;
+  }
+
+  // ── Checklist mode ────────────────────────────────────────────────
+
+  #renderChecklist() {
+    // Author provides a <ul> with <li data-status="pass|fail|warn|na"> items.
+    const list = this.querySelector(':scope > ul, :scope > ol');
+    if (!list) return;
+    list.classList.add('as-checklist');
+    for (const item of list.querySelectorAll(':scope > li')) {
+      this.#decorateChecklistItem(item);
+    }
+  }
+
+  #decorateChecklistItem(item) {
+    if (item.dataset.decorated === '') return;
+    item.dataset.decorated = '';
+    const status = item.dataset.status || 'na';
+    item.classList.add(`as-status-${status}`);
+
+    const icon = document.createElement('span');
+    icon.className = 'as-checklist-icon';
+    icon.setAttribute('aria-hidden', 'true');
+    icon.textContent = ({ pass: '✓', fail: '✗', warn: '!', na: '–' })[status] || '–';
+
+    const label = ({ pass: 'Pass', fail: 'Fail', warn: 'Warning', na: 'Not applicable' })[status] || 'Not applicable';
+    const sr = document.createElement('span');
+    sr.className = 'as-sr-only';
+    sr.textContent = `${label}: `;
+
+    item.prepend(icon, sr);
+  }
+}
+
+function escapeText(s) {
+  return String(s).replace(/[&<>"']/g, (c) => ({ '&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;' }[c]));
+}
+
+registerComponent('accessibility-specimen', AccessibilitySpecimen);
+
+export { AccessibilitySpecimen };

package/src/web-components/accessibility-specimen/static.html

@@ -0,0 +1,41 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>accessibility-specimen demo</title>
+  <link rel="stylesheet" href="/src/main.css">
+  <style>
+    body { font-family: system-ui, sans-serif; max-inline-size: 48rem; margin-inline: auto; padding: 2rem 1rem; line-height: 1.5; }
+    section { margin-block: 1.5rem; }
+  </style>
+</head>
+<body>
+  <h1>accessibility-specimen</h1>
+
+  <section>
+    <h2>Contrast pairs</h2>
+    <accessibility-specimen>
+      <button data-fg="#000000" data-bg="#ffffff" data-label="Black on white">Default text</button>
+      <button data-fg="#666" data-bg="#ffffff" data-label="Mid-gray on white">Muted text</button>
+      <button data-fg="#ffffff" data-bg="#0066cc" data-label="White on accent blue">Action button</button>
+      <button data-fg="#ffffff" data-bg="#ddd" data-label="White on light-gray">Bad pairing</button>
+    </accessibility-specimen>
+  </section>
+
+  <section>
+    <h2>Checklist</h2>
+    <accessibility-specimen type="checklist">
+      <ul>
+        <li data-status="pass">Form inputs have associated labels.</li>
+        <li data-status="pass">Focus indicators are visible at 2px width minimum.</li>
+        <li data-status="warn">Some images may be missing alt text.</li>
+        <li data-status="fail">Color contrast on muted text fails AA.</li>
+        <li data-status="na">No videos in this component (captions N/A).</li>
+      </ul>
+    </accessibility-specimen>
+  </section>
+
+  <script type="module" src="/src/main.js"></script>
+</body>
+</html>