@birdapi/velinstyle 0.8.0 → 0.9.0

package/components/velin-theme-toggle.js

@@ -129,24 +129,24 @@ class VelinThemeToggle extends HTMLElement {
     this.shadowRoot.innerHTML = `
       <style>${styles}</style>
       <div class="group" part="group">
-        <button class="toggle" part="button" aria-label="Toggle dark mode">
-          <svg class="sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
+        <button class="toggle" part="button" aria-label="Toggle dark mode" aria-pressed="false">
+          <svg class="sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true" focusable="false">
             <circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/>
             <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/>
             <line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/>
             <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/>
           </svg>
-          <svg class="moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
+          <svg class="moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true" focusable="false">
             <path d="M21 12.79A9 9 0 1111.21 3 7 7 0 0021 12.79z"/>
           </svg>
         </button>
         <button class="picker" part="picker" aria-label="Choose theme" aria-haspopup="menu" aria-expanded="false">
-          <svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <svg class="chev" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
             <polyline points="6 9 12 15 18 9"/>
           </svg>
         </button>
       </div>
-      <ul class="menu" role="menu" hidden></ul>
+      <ul class="menu" role="menu" aria-label="Theme selection" hidden></ul>
     `;
 
     this._target = document.querySelector(this.getAttribute('target') || 'html');
@@ -157,6 +157,7 @@ class VelinThemeToggle extends HTMLElement {
 
     this._renderMenu();
     this._initPreference();
+    this._syncTogglePressed();
 
     this._toggleBtn.addEventListener('click', () => this._toggleDarkMode());
     this._pickerBtn.addEventListener('click', (e) => {
@@ -298,10 +299,16 @@ class VelinThemeToggle extends HTMLElement {
     }));
   }
 
+  _syncTogglePressed() {
+    const dark = this._currentSlug() === 'dark';
+    this._toggleBtn?.setAttribute('aria-pressed', dark ? 'true' : 'false');
+  }
+
   _toggleDarkMode() {
     const current = this._currentSlug();
     const next = current === 'dark' ? '' : 'dark';
     this._applyTheme(next, { persist: true });
+    this._syncTogglePressed();
   }
 }
 

package/components/velin-toast.js

@@ -80,8 +80,12 @@ class VelinToast extends HTMLElement {
   }
 
   show({ message, type = 'info', duration = 5000 } = {}) {
+    const assertive = type === 'error' || type === 'danger';
+    this.setAttribute('role', assertive ? 'alert' : 'status');
+    this.setAttribute('aria-live', assertive ? 'assertive' : 'polite');
     const toast = document.createElement('div');
     toast.className = `toast toast--${type}`;
+    toast.setAttribute('role', assertive ? 'alert' : 'status');
     toast.innerHTML = `
       <div class="toast-content">${escapeHTML(message)}</div>
       <button class="toast-close" aria-label="Close">&#215;</button>

package/components/{velin-tooltip-wc.js → velin-tooltip.js}

@@ -23,7 +23,7 @@ const styles = `
 
 let tooltipId = 0;
 
-class VelinTooltipWC extends HTMLElement {
+class VelinTooltip extends HTMLElement {
   static get observedAttributes() { return ['content', 'placement']; }
 
   constructor() {
@@ -93,5 +93,24 @@ class VelinTooltipWC extends HTMLElement {
   }
 }
 
-customElements.define('velin-tooltip-wc', VelinTooltipWC);
-export default VelinTooltipWC;
+/** @deprecated Use `<velin-tooltip>` */
+class VelinTooltipWC extends VelinTooltip {
+  static _warned = false;
+
+  connectedCallback() {
+    if (!VelinTooltipWC._warned && typeof console !== 'undefined' && console.warn) {
+      VelinTooltipWC._warned = true;
+      console.warn('[velinstyle] <velin-tooltip-wc> is deprecated; use <velin-tooltip> instead.');
+    }
+    super.connectedCallback();
+  }
+}
+
+if (!customElements.get('velin-tooltip')) {
+  customElements.define('velin-tooltip', VelinTooltip);
+}
+if (!customElements.get('velin-tooltip-wc')) {
+  customElements.define('velin-tooltip-wc', VelinTooltipWC);
+}
+export default VelinTooltip;
+export { VelinTooltip, VelinTooltipWC };

package/core/a11y/component-contracts.json

@@ -0,0 +1,221 @@
+{
+  "wcagLevel": "AAA",
+  "version": "0.9.0",
+  "components": {
+    "velin-accordion": {
+      "status": "pass",
+      "roles": ["group"],
+      "keyboard": "Arrow/Home/End between summaries",
+      "reducedMotion": true,
+      "requiredAttributes": [],
+      "notes": "Wires aria-controls on summary elements."
+    },
+    "velin-announcer": {
+      "status": "pass",
+      "roles": ["status"],
+      "liveRegion": "polite|assertive",
+      "keyboard": "N/A",
+      "reducedMotion": true
+    },
+    "velin-bottom-nav": {
+      "status": "pass",
+      "roles": ["navigation"],
+      "requiredAttributes": ["aria-label"],
+      "keyboard": "Native links or buttons in slot",
+      "notes": "Host aria-label; slotchange syncs aria-current and infers item labels from data-nav/title."
+    },
+    "velin-carousel": {
+      "status": "pass",
+      "roles": ["group", "button"],
+      "keyboard": "Arrows, Home, End, dots",
+      "reducedMotion": true
+    },
+    "velin-code-block": {
+      "status": "pass",
+      "roles": ["button"],
+      "requiredAttributes": [],
+      "keyboard": "Expand toggle keyboard",
+      "notes": "Expand uses aria-expanded and aria-controls."
+    },
+    "velin-collapse": {
+      "status": "pass",
+      "roles": ["button"],
+      "keyboard": "Enter/Space on trigger",
+      "requiredAttributes": []
+    },
+    "velin-combobox": {
+      "status": "pass",
+      "roles": ["combobox", "listbox"],
+      "keyboard": "Roving, Escape, Enter",
+      "requiredAttributes": ["aria-label"]
+    },
+    "velin-command": {
+      "status": "pass",
+      "roles": ["dialog"],
+      "keyboard": "Escape, arrows in results, Tab trap",
+      "requiredAttributes": []
+    },
+    "velin-copy": {
+      "status": "pass",
+      "roles": ["button"],
+      "requiredAttributes": ["aria-label"],
+      "keyboard": "Native button"
+    },
+    "velin-countdown": {
+      "status": "pass",
+      "roles": ["timer"],
+      "liveRegion": "polite",
+      "keyboard": "N/A"
+    },
+    "velin-counter": {
+      "status": "pass",
+      "roles": ["status"],
+      "liveRegion": "polite",
+      "keyboard": "N/A",
+      "reducedMotion": true
+    },
+    "velin-dialog": {
+      "status": "pass",
+      "roles": ["dialog"],
+      "keyboard": "Native dialog, Escape",
+      "requiredAttributes": [],
+      "notes": "aria-labelledby on dialog, aria-modal true."
+    },
+    "velin-drawer": {
+      "status": "pass",
+      "roles": ["dialog"],
+      "keyboard": "Escape, Tab trap",
+      "requiredAttributes": []
+    },
+    "velin-dropdown": {
+      "status": "pass",
+      "roles": ["menu", "button"],
+      "keyboard": "Roving, typeahead, Escape"
+    },
+    "velin-email": {
+      "status": "pass",
+      "roles": ["button"],
+      "requiredAttributes": ["aria-label"]
+    },
+    "velin-icon": {
+      "status": "pass",
+      "roles": ["img", "presentation"],
+      "requiredAttributes": ["label"],
+      "notes": "Decorative when no label; SVG aria-hidden. Do not set aria-hidden on host in JS."
+    },
+    "velin-lightbox": {
+      "status": "pass",
+      "roles": ["dialog"],
+      "keyboard": "Escape, arrows, Tab trap",
+      "liveRegion": "polite"
+    },
+    "velin-live-dot": {
+      "status": "pass",
+      "roles": ["status"],
+      "requiredAttributes": [],
+      "notes": "Status exposed via aria-label on host, not color alone."
+    },
+    "velin-menubar": {
+      "status": "pass",
+      "roles": ["menubar", "menu"],
+      "requiredAttributes": ["aria-label"],
+      "keyboard": "Roving arrows"
+    },
+    "velin-modal": {
+      "status": "pass",
+      "roles": ["dialog"],
+      "keyboard": "Escape, Tab trap",
+      "requiredAttributes": []
+    },
+    "velin-persist": {
+      "status": "pass",
+      "keyboard": "N/A",
+      "notes": "display:contents; auto-saves form field values (WCAG 3.3.7 Redundant Entry helper). Clears on form submit."
+    },
+    "velin-popover": {
+      "status": "pass",
+      "roles": ["dialog", "tooltip"],
+      "keyboard": "Escape, Enter/Space on trigger; focus opens hover mode",
+      "notes": "aria-labelledby or default aria-label; non-button triggers get role=button."
+    },
+    "velin-progress-ring": {
+      "status": "pass",
+      "roles": ["progressbar"],
+      "requiredAttributes": []
+    },
+    "velin-rating": {
+      "status": "pass",
+      "roles": ["radiogroup"],
+      "keyboard": "Roving, arrows"
+    },
+    "velin-scroll-top": {
+      "status": "pass",
+      "roles": ["button"],
+      "requiredAttributes": ["aria-label"],
+      "reducedMotion": true
+    },
+    "velin-scrollspy": {
+      "status": "pass",
+      "keyboard": "Native nav links",
+      "notes": "Sets aria-current on active link."
+    },
+    "velin-search": {
+      "status": "pass",
+      "roles": ["combobox", "listbox"],
+      "requiredAttributes": ["aria-label"],
+      "keyboard": "Arrows, Enter, Escape",
+      "notes": "Default aria-label Search when unset."
+    },
+    "velin-secure-field": {
+      "status": "pass",
+      "roles": ["textbox"],
+      "requiredAttributes": [],
+      "notes": "Native label association."
+    },
+    "velin-segmented-control": {
+      "status": "pass",
+      "roles": ["group"],
+      "requiredAttributes": ["aria-label"],
+      "keyboard": "Roving"
+    },
+    "velin-sheet": {
+      "status": "pass",
+      "roles": ["dialog"],
+      "keyboard": "Escape, Tab trap"
+    },
+    "velin-sparkline": {
+      "status": "pass",
+      "roles": ["img", "presentation"],
+      "requiredAttributes": ["label"],
+      "notes": "Uses label, aria-label, or figcaption aria-labelledby."
+    },
+    "velin-stepper": {
+      "status": "pass",
+      "roles": ["list"],
+      "keyboard": "N/A (display); pair with buttons calling next()/prev()",
+      "notes": "aria-label per step (completed/current/upcoming); sr-only Completed text; aria-current on active step."
+    },
+    "velin-tabs": {
+      "status": "pass",
+      "roles": ["tablist", "tab", "tabpanel"],
+      "keyboard": "Roving, auto-select arrows"
+    },
+    "velin-theme-toggle": {
+      "status": "pass",
+      "roles": ["button", "menu"],
+      "keyboard": "Menu arrows, Escape",
+      "notes": "aria-pressed on theme toggle."
+    },
+    "velin-toast": {
+      "status": "pass",
+      "roles": ["status", "alert"],
+      "liveRegion": "polite|assertive",
+      "keyboard": "Close button"
+    },
+    "velin-tooltip": {
+      "status": "pass",
+      "roles": ["tooltip"],
+      "keyboard": "Escape, focusin"
+    }
+  }
+}

package/core/attributes/index.js

@@ -0,0 +1,6 @@
+export {
+  registerAttribute,
+  getAttributeHandler,
+  bootAttributes,
+  listRegisteredAttributes,
+} from './registry.js';

package/core/attributes/registry.js

@@ -0,0 +1,268 @@
+import { lazyDefine } from '../../components/runtime/index.js';
+import { initMotion } from '../motion/index.js';
+
+/** @type {Map<string, { enhance: (el: HTMLElement) => void|Promise<void> }>} */
+const registry = new Map();
+
+export function registerAttribute(name, handler) {
+  registry.set(name, handler);
+}
+
+export function getAttributeHandler(name) {
+  return registry.get(name);
+}
+
+function bridgeComponent(el, tag, attrs = {}) {
+  el.setAttribute('data-velin-component', tag);
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v != null) el.setAttribute(k, v);
+  }
+  return lazyDefine(tag);
+}
+
+function registerBuiltins() {
+  registerAttribute('velin-modal', {
+    enhance(el) {
+      bridgeComponent(el, 'velin-modal', { open: el.getAttribute('velin-modal') || '' });
+    },
+  });
+  registerAttribute('velin-tabs', { enhance: (el) => bridgeComponent(el, 'velin-tabs') });
+  registerAttribute('velin-accordion', { enhance: (el) => bridgeComponent(el, 'velin-accordion') });
+  registerAttribute('velin-tooltip', {
+    enhance(el) {
+      const tip = el.getAttribute('velin-tooltip') || el.getAttribute('title') || '';
+      if (tip && el.hasAttribute('title')) el.removeAttribute('title');
+      if (el.tagName === 'VELIN-TOOLTIP' || el.tagName === 'VELIN-TOOLTIP-WC') {
+        el.setAttribute('content', tip);
+        return lazyDefine('velin-tooltip');
+      }
+      const wc = document.createElement('velin-tooltip');
+      wc.setAttribute('content', tip);
+      const parent = el.parentElement;
+      if (parent) {
+        parent.insertBefore(wc, el);
+        wc.appendChild(el);
+      }
+      return lazyDefine('velin-tooltip');
+    },
+  });
+  registerAttribute('velin-copy', {
+    enhance(el) {
+      const text = el.getAttribute('velin-copy') || el.textContent?.trim() || '';
+      if (!el.querySelector('velin-copy')) {
+        const wc = document.createElement('velin-copy');
+        wc.setAttribute('value', text);
+        if (el.tagName === 'BUTTON') {
+          wc.append(...el.childNodes);
+          el.replaceWith(wc);
+          return lazyDefine('velin-copy');
+        }
+        el.appendChild(wc);
+      }
+      return lazyDefine('velin-copy');
+    },
+  });
+  registerAttribute('velin-counter', {
+    enhance(el) {
+      bridgeComponent(el, 'velin-counter', {
+        value: el.getAttribute('velin-counter') || '0',
+      });
+    },
+  });
+  registerAttribute('velin-notify', {
+    async enhance(el) {
+      await lazyDefine('velin-toast');
+      el.addEventListener('click', () => {
+        const msg = el.getAttribute('velin-notify') || el.textContent || '';
+        document.dispatchEvent(
+          new CustomEvent('velin-toast-show', { detail: { message: msg, variant: el.dataset.variant || 'info' } }),
+        );
+      });
+    },
+  });
+  registerAttribute('velin-theme', {
+    enhance(el) {
+      const theme = el.getAttribute('velin-theme') || 'toggle';
+      if (theme === 'toggle') {
+        if (!el.querySelector('velin-theme-toggle')) {
+          el.appendChild(document.createElement('velin-theme-toggle'));
+        }
+        return lazyDefine('velin-theme-toggle');
+      }
+      document.documentElement.setAttribute('data-velin-theme', theme);
+    },
+  });
+  registerAttribute('velin-scroll-top', {
+    enhance(el) {
+      const raw = el.getAttribute('velin-scroll-top');
+      const threshold = raw && raw !== 'true' ? raw : '300';
+      if (el.tagName === 'VELIN-SCROLL-TOP') {
+        if (raw && raw !== 'true') el.setAttribute('threshold', threshold);
+        return lazyDefine('velin-scroll-top');
+      }
+      let wc = document.querySelector('velin-scroll-top');
+      if (!wc) {
+        wc = document.createElement('velin-scroll-top');
+        wc.setAttribute('threshold', threshold);
+        (el === document.body || el === document.documentElement ? document.body : el).appendChild(wc);
+      }
+      return lazyDefine('velin-scroll-top');
+    },
+  });
+  registerAttribute('velin-progress', {
+    enhance(el) {
+      const ring = el.hasAttribute('ring');
+      if (ring) return bridgeComponent(el, 'velin-progress-ring');
+      el.classList.add('velin-progress');
+      const val = parseInt(el.getAttribute('velin-progress') || '0', 10);
+      el.setAttribute('role', 'progressbar');
+      el.setAttribute('aria-valuenow', String(val));
+      el.style.setProperty('--velin-progress', `${Math.min(100, val)}%`);
+    },
+  });
+  registerAttribute('velin-search', {
+    async enhance(el) {
+      if (el.tagName !== 'VELIN-SEARCH') {
+        const host = document.createElement('velin-search');
+        host.setAttribute('index', el.getAttribute('data-search-index') || '/search-index.json');
+        el.replaceWith(host);
+        host.appendChild(el);
+      }
+      return lazyDefine('velin-search');
+    },
+  });
+  registerAttribute('velin-lazy', {
+    enhance(el) {
+      if (el.tagName === 'IMG') {
+        el.loading = 'lazy';
+        el.decoding = 'async';
+        if (el.hasAttribute('velin-skeleton') || el.dataset.velinSkeleton) {
+          el.classList.add('velin-skeleton', 'velin-skeleton--image');
+          el.addEventListener('load', () => el.classList.remove('velin-skeleton', 'velin-skeleton--image'), { once: true });
+        }
+      }
+    },
+  });
+  registerAttribute('velin-skeleton', {
+    enhance(el) {
+      const variant = el.getAttribute('velin-skeleton') || 'text';
+      el.classList.add('velin-skeleton', `velin-skeleton--${variant}`);
+      const hasText = Boolean(el.textContent?.trim()) && el.children.length > 0;
+      if (!hasText && !el.textContent?.trim()) {
+        el.setAttribute('aria-hidden', 'true');
+      }
+    },
+  });
+  registerAttribute('velin-loading', {
+    enhance(el) {
+      el.classList.add('velin-spinner');
+      el.setAttribute('aria-busy', 'true');
+      el.setAttribute('role', 'status');
+      if (!el.getAttribute('aria-label')?.trim()) {
+        el.setAttribute('aria-label', 'Loading');
+      }
+    },
+  });
+  registerAttribute('velin-grid', {
+    enhance(el) {
+      const cols = el.getAttribute('velin-grid') || 'auto';
+      el.classList.add('velin-grid');
+      if (cols !== 'auto') el.style.setProperty('--velin-grid-cols', cols);
+    },
+  });
+  registerAttribute('velin-anchor', {
+    enhance(el) {
+      if (!el.id && el.getAttribute('velin-anchor')) el.id = el.getAttribute('velin-anchor');
+      el.setAttribute('tabindex', '-1');
+    },
+  });
+  registerAttribute('velin-code', {
+    async enhance(el) {
+      const lang =
+        el.getAttribute('velin-code') ||
+        el.getAttribute('language') ||
+        el.getAttribute('data-language') ||
+        '';
+      el.classList.add('velin-code-block');
+      if (lang && lang !== 'true') {
+        el.dataset.language = lang;
+        if (!el.getAttribute('language')) el.setAttribute('language', lang);
+      }
+      if (!el.querySelector('[data-velin-copy]')) {
+        const btn = document.createElement('button');
+        btn.type = 'button';
+        btn.className = 'velin-code-block__copy velin-btn velin-btn--sm';
+        btn.textContent = 'Copy';
+        btn.setAttribute('data-velin-copy', '');
+        btn.setAttribute('velin-copy', el.querySelector('code')?.textContent || el.textContent || '');
+        el.style.position = 'relative';
+        el.appendChild(btn);
+      }
+      await lazyDefine('velin-copy');
+
+      const { initHighlight, highlightElement } = await import('../highlight/index.js');
+      const immediate =
+        el.getAttribute('data-velin-highlight') === 'immediate' ||
+        (typeof matchMedia !== 'undefined' &&
+          matchMedia('(prefers-reduced-motion: reduce)').matches);
+      if (immediate) {
+        await highlightElement(el);
+      } else {
+        initHighlight(el, { root: el });
+      }
+    },
+  });
+  registerAttribute('velin-quote', {
+    enhance(el) {
+      if (el.tagName === 'BLOCKQUOTE' || el.tagName === 'Q') {
+        el.classList.add('velin-quote');
+      }
+    },
+  });
+  registerAttribute('velin-highlight', {
+    enhance(el) {
+      // Inline text mark (search/docs) — not syntax highlighting; see velinSyntax / velin-code
+      el.classList.add('velin-highlight');
+    },
+  });
+
+  for (const motion of ['velin-reveal', 'velin-fade', 'velin-slide', 'velin-scale', 'velin-parallax', 'velin-hover', 'velin-stagger', 'velin-scroll']) {
+    registerAttribute(motion, { enhance() {} });
+  }
+}
+
+registerBuiltins();
+
+const enhanced = new WeakSet();
+
+/**
+ * @param {ParentNode} [root]
+ */
+export async function bootAttributes(root = document) {
+  const selector = [...registry.keys()].map((a) => `[${a}]`).join(',');
+  const elements = root.querySelectorAll(selector);
+
+  for (const el of elements) {
+    if (enhanced.has(el)) continue;
+    for (const attr of registry.keys()) {
+      if (!el.hasAttribute(attr)) continue;
+      const handler = registry.get(attr);
+      if (handler?.enhance) await handler.enhance(el);
+    }
+    enhanced.add(el);
+  }
+
+  initMotion({ root });
+  if (typeof HTMLElement !== 'undefined') {
+    const { bindDeclarativeSearch } = await import('../../components/velin-search.js');
+    bindDeclarativeSearch(root);
+    if (!document.querySelector('velin-announcer')) {
+      const { getAnnouncer } = await import('../../components/a11y-utils.js');
+      getAnnouncer();
+    }
+  }
+}
+
+export function listRegisteredAttributes() {
+  return [...registry.keys()];
+}