@birdapi/velinstyle 0.8.0 → 0.9.0

package/components/velin-modal.js

@@ -98,14 +98,17 @@ class VelinModal extends HTMLElement {
   }
 
   connectedCallback() {
-    const title = this.getAttribute('title') || '';
+    const title = (this.getAttribute('title') || '').trim();
     const safeTitle = escapeHTML(title);
+    const dialogLabel = title
+      ? 'aria-labelledby="velin-modal-title"'
+      : `aria-label="${escapeHTML(this.getAttribute('aria-label') || 'Dialog')}"`;
     this.shadowRoot.innerHTML = `
       <style>${styles}</style>
       <div class="overlay" part="overlay">
-        <div class="dialog" role="dialog" aria-modal="true" aria-labelledby="velin-modal-title" part="dialog">
+        <div class="dialog" role="dialog" aria-modal="true" ${dialogLabel} part="dialog">
           <div class="header" part="header">
-            <h2 class="title" id="velin-modal-title">${safeTitle}</h2>
+            <h2 class="title" id="velin-modal-title"${title ? '' : ' class="velin-sr-only"'}>${safeTitle || 'Dialog'}</h2>
             <button class="close-btn" aria-label="Close" part="close">&#215;</button>
           </div>
           <div class="body" part="body"><slot></slot></div>

package/components/velin-popover.js

@@ -50,24 +50,52 @@ class VelinPopover extends HTMLElement {
     const role = triggerType === 'hover' ? 'tooltip' : 'dialog';
     this._isDialog = role === 'dialog';
 
+    const titleId = title ? `${this._popoverId}-title` : '';
     this.shadowRoot.innerHTML = `
       <style>${styles}</style>
       <slot name="trigger"></slot>
-      <div class="popover popover--${placement}" id="${this._popoverId}" role="${role}" part="popover">
-        ${title ? `<div class="popover__title" part="title">${escapeHTML(title)}</div>` : ''}
+      <div class="popover popover--${placement}" id="${this._popoverId}" role="${role}" part="popover"${titleId ? ` aria-labelledby="${titleId}"` : ''}>
+        ${title ? `<div class="popover__title" id="${titleId}" part="title">${escapeHTML(title)}</div>` : ''}
         <slot></slot>
       </div>
     `;
+    const popoverEl = this.shadowRoot.querySelector('.popover');
+    if (!title && popoverEl) {
+      const fallback =
+        this.getAttribute('aria-label') ||
+        (role === 'tooltip' ? 'Tooltip' : 'Popover');
+      popoverEl.setAttribute('aria-label', fallback);
+    }
 
     const triggerSlot = this.shadowRoot.querySelector('slot[name="trigger"]');
     triggerSlot.addEventListener('slotchange', () => this._wireTrigger(triggerType));
     this._wireTrigger(triggerType);
   }
 
+  _ensureTriggerInteractive(trigger) {
+    const tag = trigger.tagName;
+    if (tag !== 'BUTTON' && tag !== 'A' && trigger.getAttribute('role') !== 'button') {
+      trigger.setAttribute('role', 'button');
+      if (!trigger.hasAttribute('tabindex')) trigger.setAttribute('tabindex', '0');
+    }
+  }
+
+  _onTriggerKey(e) {
+    if (e.key === 'Escape') {
+      this.close();
+      return;
+    }
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      this.toggle();
+    }
+  }
+
   _wireTrigger(triggerType) {
     const trigger = this.shadowRoot.querySelector('slot[name="trigger"]')?.assignedElements()[0];
     if (!trigger) return;
 
+    this._ensureTriggerInteractive(trigger);
     const isHover = triggerType === 'hover';
     trigger.setAttribute('aria-haspopup', isHover ? 'true' : 'dialog');
     trigger.setAttribute('aria-expanded', this.hasAttribute('open') ? 'true' : 'false');
@@ -75,6 +103,10 @@ class VelinPopover extends HTMLElement {
       trigger.setAttribute('aria-controls', this._popoverId);
     }
 
+    trigger.removeEventListener('keydown', this._onTriggerKeyBound);
+    this._onTriggerKeyBound = this._onTriggerKeyBound || this._onTriggerKey.bind(this);
+    trigger.addEventListener('keydown', this._onTriggerKeyBound);
+
     if (triggerType === 'click') {
       trigger.onclick = () => this.toggle();
     } else if (triggerType === 'hover') {

package/components/velin-reveal.js

@@ -1,73 +1,15 @@
 /*
- * velin-reveal.js — reusable scroll-into-view reveal helper.
- *
- * Replaces inline IntersectionObserver snippets that every project ends up
- * copy-pasting. Just call `initReveal()` once, or opt into auto-init by
- * adding `data-velin-reveal-auto` to <html>. Elements with the class
- * `.velin-animate-on-scroll` get `is-visible` toggled when they enter the
- * viewport.
- *
- * Honours `prefers-reduced-motion: reduce` by revealing immediately without
- * animation, and falls back to immediate reveal if IntersectionObserver is
- * unavailable.
- *
- * API:
- *   initReveal(options?) -> () => void teardown function.
- *   options.selector     CSS selector (default '.velin-animate-on-scroll').
- *   options.threshold    IO threshold (default 0.1).
- *   options.rootMargin   IO rootMargin (default '0px 0px -40px 0px').
- *   options.once         if true (default) stops observing once visible.
- *   options.visibleClass class added on intersect (default 'is-visible').
+ * velin-reveal.js — scroll-into-view reveal (delegates to core/motion).
  */
+import { initMotion, initReveal as motionInitReveal, velinMotion } from '../core/motion/index.js';
 
-const DEFAULTS = {
-  selector: '.velin-animate-on-scroll',
-  threshold: 0.1,
-  rootMargin: '0px 0px -40px 0px',
-  once: true,
-  visibleClass: 'is-visible',
-};
-
-const _activeObservers = new WeakMap();
-
-export function initReveal(options = {}) {
-  if (typeof document === 'undefined') return () => {};
-  const opts = { ...DEFAULTS, ...options };
-  const reduced = window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
-  const targets = Array.from(document.querySelectorAll(opts.selector));
-
-  if (reduced || typeof IntersectionObserver === 'undefined') {
-    targets.forEach((el) => el.classList.add(opts.visibleClass));
-    return () => {};
-  }
-
-  const observer = new IntersectionObserver(
-    (entries) => {
-      for (const entry of entries) {
-        if (!entry.isIntersecting) continue;
-        entry.target.classList.add(opts.visibleClass);
-        if (opts.once) observer.unobserve(entry.target);
-      }
-    },
-    { threshold: opts.threshold, rootMargin: opts.rootMargin },
-  );
-
-  targets.forEach((el) => {
-    if (_activeObservers.has(el)) return;
-    _activeObservers.set(el, observer);
-    observer.observe(el);
-  });
-
-  return () => {
-    observer.disconnect();
-    targets.forEach((el) => _activeObservers.delete(el));
-  };
-}
+export { initMotion, velinMotion };
+export const initReveal = motionInitReveal;
 
 if (typeof document !== 'undefined') {
   const autoInit = () => {
-    if (document.documentElement && document.documentElement.hasAttribute('data-velin-reveal-auto')) {
-      initReveal();
+    if (document.documentElement?.hasAttribute('data-velin-reveal-auto')) {
+      initMotion();
     }
   };
   if (document.readyState === 'loading') {
@@ -77,4 +19,4 @@ if (typeof document !== 'undefined') {
   }
 }
 
-export default { initReveal };
+export default { initReveal, initMotion };

package/components/velin-scroll-top.js

@@ -30,7 +30,7 @@ class VelinScrollTop extends HTMLElement {
     this.shadowRoot.innerHTML = `
       <style>${styles}</style>
       <button part="button" aria-label="Scroll to top">
-        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
           <line x1="12" y1="19" x2="12" y2="5"/><polyline points="5 12 12 5 19 12"/>
         </svg>
       </button>

package/components/velin-search.js

@@ -0,0 +1,267 @@
+import { createSearch, highlightHtml, SEARCH_CATEGORIES, resolveDocsSearchUrl } from '../core/search/index.js';
+import { escapeHTMLAttribute } from './sanitize.js';
+
+const CATEGORY_LABELS = {
+  docs: 'Documentation',
+  components: 'Components',
+  api: 'API',
+  examples: 'Examples',
+};
+
+class VelinSearch extends HTMLElement {
+  static get observedAttributes() {
+    return ['index', 'categories', 'min-chars', 'fuzzy', 'placeholder', 'debounce'];
+  }
+
+  constructor() {
+    super();
+    this._search = createSearch();
+    this._debounceTimer = null;
+    this._activeIndex = -1;
+    this._flatResults = [];
+    this._indexLoaded = false;
+    this._listId = `velin-search-listbox-${Math.random().toString(36).slice(2, 9)}`;
+    this._mounted = false;
+  }
+
+  connectedCallback() {
+    if (this._mounted) return;
+    this._mounted = true;
+    this._ensureMarkup();
+    this._loadIndex();
+    this._bindEvents();
+  }
+
+  disconnectedCallback() {
+    this._teardown?.();
+    this._mounted = false;
+  }
+
+  get indexUrl() {
+    return this.getAttribute('index') || '/search-index.json';
+  }
+
+  get minChars() {
+    return parseInt(this.getAttribute('min-chars') || '2', 10);
+  }
+
+  get fuzzy() {
+    const v = this.getAttribute('fuzzy');
+    return v === null ? 0.2 : parseFloat(v) || 0;
+  }
+
+  get categories() {
+    const raw = this.getAttribute('categories');
+    if (!raw) return null;
+    return raw.split(',').map((c) => c.trim()).filter((c) => SEARCH_CATEGORIES.includes(c));
+  }
+
+  get debounceMs() {
+    return parseInt(this.getAttribute('debounce') || '120', 10);
+  }
+
+  _ensureMarkup() {
+    if (this.querySelector('[data-velin-search-input]')) return;
+    const ph = escapeHTMLAttribute(this.getAttribute('placeholder') || 'Search…');
+    const label = escapeHTMLAttribute(this.getAttribute('aria-label') || 'Search');
+    this.innerHTML = `
+      <div class="velin-search">
+        <div class="velin-search__field">
+          <input type="search" class="velin-search__input" data-velin-search-input
+            placeholder="${ph}" autocomplete="off" role="combobox" aria-expanded="false"
+            aria-label="${label}" aria-controls="${this._listId}" aria-autocomplete="list" />
+        </div>
+        <div class="velin-search__status velin-visually-hidden" data-velin-search-status aria-live="polite" aria-atomic="true"></div>
+        <div class="velin-search__results" data-velin-search-results role="listbox"
+          id="${this._listId}" hidden></div>
+      </div>
+    `;
+  }
+
+  _inputEl() {
+    return this.querySelector('[data-velin-search-input]');
+  }
+
+  _resultsEl() {
+    return this.querySelector('[data-velin-search-results]');
+  }
+
+  async _loadIndex() {
+    try {
+      await this._search.loadIndex(this.indexUrl);
+      this._indexLoaded = true;
+    } catch {
+      this._indexLoaded = false;
+    }
+  }
+
+  _bindEvents() {
+    const input = this._inputEl();
+    const panel = this._resultsEl();
+    if (!input || !panel) return;
+
+    input.addEventListener('input', () => {
+      clearTimeout(this._debounceTimer);
+      this._debounceTimer = setTimeout(() => this._runQuery(input.value), this.debounceMs);
+    });
+    input.addEventListener('focus', () => {
+      if (input.value.trim().length >= this.minChars) this._runQuery(input.value);
+    });
+    input.addEventListener('keydown', (e) => this._onKeydown(e, input, panel));
+
+    const onDocClick = (e) => {
+      if (!this.contains(e.target)) this._hide(panel, input);
+    };
+    document.addEventListener('click', onDocClick);
+    this._teardown = () => {
+      document.removeEventListener('click', onDocClick);
+      clearTimeout(this._debounceTimer);
+    };
+  }
+
+  async _runQuery(raw) {
+    const input = this._inputEl();
+    const panel = this._resultsEl();
+    if (!input || !panel) return;
+    const q = raw.trim();
+    if (q.length < this.minChars) {
+      this._hide(panel, input);
+      return;
+    }
+    if (!this._indexLoaded) await this._loadIndex();
+    const { groups } = this._search.query(q, {
+      minChars: this.minChars,
+      fuzzy: this.fuzzy,
+      categories: this.categories || undefined,
+      limit: 12,
+    });
+    this._activeIndex = -1;
+    this._renderResults(panel, input, q, groups);
+    if (this._flatResults.length) {
+      panel.hidden = false;
+      panel.classList.add('velin-search__results--open');
+      input.setAttribute('aria-expanded', 'true');
+    } else {
+      this._hide(panel, input);
+    }
+  }
+
+  _renderResults(panel, input, q, groups) {
+    panel.innerHTML = '';
+    const order = this.categories || [...SEARCH_CATEGORIES];
+    this._flatResults = [];
+    let globalIdx = 0;
+    for (const cat of order) {
+      const items = groups[cat];
+      if (!items?.length) continue;
+      const groupId = `${this._listId}-group-${cat}`;
+      const group = document.createElement('div');
+      group.setAttribute('role', 'group');
+      group.setAttribute('aria-labelledby', groupId);
+      const heading = document.createElement('div');
+      heading.className = 'velin-search__group-label';
+      heading.id = groupId;
+      heading.textContent = CATEGORY_LABELS[cat] || cat;
+      group.appendChild(heading);
+      for (const item of items) {
+        const a = document.createElement('a');
+        const navHref = resolveDocsSearchUrl(item.url);
+        if (navHref) a.href = navHref;
+        a.className = 'velin-search__item';
+        a.setAttribute('role', 'option');
+        a.id = `velin-search-opt-${globalIdx}`;
+        a.innerHTML =
+          `<span class="velin-search__title">${highlightHtml(item.title, q)}</span>` +
+          `<span class="velin-search__excerpt">${highlightHtml(item.excerpt || '', q)}</span>`;
+        a.addEventListener(
+          'click',
+          (e) => {
+            e.preventDefault();
+            if (navHref) window.location.assign(navHref);
+          },
+          true,
+        );
+        a.addEventListener('mouseenter', () => this._setActive(globalIdx, panel, input));
+        group.appendChild(a);
+        this._flatResults.push(item);
+        globalIdx++;
+      }
+      panel.appendChild(group);
+    }
+    const status = this._statusEl();
+    if (status) {
+      status.textContent = this._flatResults.length
+        ? `${this._flatResults.length} results`
+        : 'No results';
+    }
+  }
+
+  _statusEl() {
+    return this.querySelector('[data-velin-search-status]');
+  }
+
+  _setActive(idx, panel, input) {
+    this._activeIndex = idx;
+    panel.querySelectorAll('.velin-search__item').forEach((el, i) => {
+      el.classList.toggle('velin-search__item--active', i === idx);
+      if (i === idx) {
+        input.setAttribute('aria-activedescendant', el.id);
+        el.scrollIntoView({ block: 'nearest' });
+      }
+    });
+  }
+
+  _onKeydown(e, input, panel) {
+    if (e.key === 'Escape') {
+      this._hide(panel, input);
+      return;
+    }
+    if (!this._flatResults.length) return;
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      const next = this._activeIndex < this._flatResults.length - 1 ? this._activeIndex + 1 : 0;
+      this._setActive(next, panel, input);
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      const prev = this._activeIndex > 0 ? this._activeIndex - 1 : this._flatResults.length - 1;
+      this._setActive(prev, panel, input);
+    } else if (e.key === 'Enter') {
+      const target = this._activeIndex >= 0 ? this._flatResults[this._activeIndex] : this._flatResults[0];
+      const navHref = target?.url ? resolveDocsSearchUrl(target.url) : '';
+      if (navHref) {
+        e.preventDefault();
+        window.location.assign(navHref);
+      }
+    }
+  }
+
+  _hide(panel, input) {
+    panel.hidden = true;
+    panel.classList.remove('velin-search__results--open');
+    input.setAttribute('aria-expanded', 'false');
+    input.removeAttribute('aria-activedescendant');
+    this._activeIndex = -1;
+  }
+}
+
+export default VelinSearch;
+
+if (typeof HTMLElement !== 'undefined' && typeof customElements !== 'undefined' && !customElements.get('velin-search')) {
+  customElements.define('velin-search', VelinSearch);
+}
+
+export function bindDeclarativeSearch(root = document) {
+  root.querySelectorAll('[velin-search-input]').forEach((input) => {
+    if (input.dataset.velinSearchBound) return;
+    input.dataset.velinSearchBound = '1';
+    let host = input.closest('velin-search');
+    if (!host) {
+      host = document.createElement('velin-search');
+      host.setAttribute('index', input.getAttribute('data-search-index') || '/search-index.json');
+      const results = input.parentElement?.querySelector('[velin-search-results]');
+      input.before(host);
+      host.appendChild(input);
+      if (results) host.appendChild(results);
+    }
+  });
+}

package/components/velin-secure-field.js

@@ -0,0 +1,99 @@
+import { escapeHTML, escapeHTMLAttribute, sanitizeInputType } from './sanitize.js';
+
+const styles = `
+  :host { display: block; }
+  label { display: block; font-size: var(--velin-text-sm); margin-block-end: var(--velin-space-1); }
+  input {
+    width: 100%;
+    min-height: 2.75rem;
+    padding: var(--velin-space-2) var(--velin-space-3);
+    font: inherit;
+    border: 1px solid var(--velin-color-border);
+    border-radius: var(--velin-radius-md);
+  }
+  input:focus-visible {
+    outline: 3px solid var(--velin-color-focus);
+    outline-offset: 2px;
+  }
+  .velin-field-help {
+    font-size: var(--velin-text-xs);
+    color: var(--velin-color-text-muted);
+    margin-block-start: var(--velin-space-1);
+  }
+`;
+
+async function encryptValue(plain, mode) {
+  if (mode !== 'aes-gcm' || !globalThis.crypto?.subtle) {
+    return JSON.stringify({ encoding: 'base64', payload: btoa(unescape(encodeURIComponent(plain))) });
+  }
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const key = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, false, ['encrypt']);
+  const encoded = new TextEncoder().encode(plain);
+  const cipher = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, encoded);
+  return JSON.stringify({
+    encoding: 'aes-gcm',
+    iv: Array.from(iv),
+    cipher: Array.from(new Uint8Array(cipher)),
+  });
+}
+
+class VelinSecureField extends HTMLElement {
+  static get observedAttributes() {
+    return ['type', 'name', 'label', 'mode', 'autocomplete'];
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this._onChange = null;
+  }
+
+  connectedCallback() {
+    if (!this._onChange) this.render();
+  }
+
+  disconnectedCallback() {
+    const input = this.shadowRoot?.querySelector('input');
+    if (input && this._onChange) input.removeEventListener('change', this._onChange);
+    this._onChange = null;
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) this.render();
+  }
+
+  render() {
+    const type = sanitizeInputType(this.getAttribute('type'));
+    const name = this.getAttribute('name') || 'secure';
+    const label = this.getAttribute('label') || 'Secure field';
+    const autocomplete = escapeHTMLAttribute(this.getAttribute('autocomplete') || 'off');
+    const id = `velin-secure-${Math.random().toString(36).slice(2, 9)}`;
+
+    const input = this.shadowRoot?.querySelector('input');
+    if (input && this._onChange) input.removeEventListener('change', this._onChange);
+
+    this.shadowRoot.innerHTML = `
+      <style>${styles}</style>
+      <label for="${id}">${escapeHTML(label)}</label>
+      <input id="${id}" type="${type}" autocomplete="${autocomplete}" part="input" />
+      <p class="velin-field-help">Demo-only client encoding — use HTTPS and server-side crypto for real secrets.</p>
+    `;
+
+    const newInput = this.shadowRoot.querySelector('input');
+    this._onChange = async () => {
+      const mode = this.getAttribute('mode') || 'aes-gcm';
+      const payload = await encryptValue(newInput.value, mode);
+      this.dispatchEvent(new CustomEvent('velin-secure-submit', {
+        bubbles: true,
+        detail: { name, payload },
+      }));
+    };
+    newInput.addEventListener('change', this._onChange);
+  }
+}
+
+if (!customElements.get('velin-secure-field')) {
+  customElements.define('velin-secure-field', VelinSecureField);
+}
+
+export default VelinSecureField;

package/components/velin-sparkline.js

@@ -120,7 +120,6 @@ class VelinSparkline extends HTMLElement {
     const wantsArea = this.hasAttribute('area') && this.getAttribute('area') !== 'false';
     const wantsGlow = this.hasAttribute('glow') && this.getAttribute('glow') !== 'false';
     const animate = (this.getAttribute('animate') || 'draw').toLowerCase();
-    const label = this.getAttribute('label');
 
     const points = buildPoints(values, w, h, min, max);
     const linePath = pointsToPath(points);
@@ -133,12 +132,7 @@ class VelinSparkline extends HTMLElement {
     svg.style.display = 'block';
     svg.style.width = '100%';
     svg.style.height = '100%';
-    if (label) {
-      svg.setAttribute('role', 'img');
-      svg.setAttribute('aria-label', label);
-    } else {
-      svg.setAttribute('aria-hidden', 'true');
-    }
+    this._applyA11y(svg);
 
     if (wantsArea) {
       const defs = document.createElementNS(NS, 'defs');
@@ -198,6 +192,32 @@ class VelinSparkline extends HTMLElement {
       this.classList.add('velin-spark-tick');
     }
   }
+
+  _applyA11y(svg) {
+    const label = (this.getAttribute('label') || this.getAttribute('aria-label') || '').trim();
+    if (label) {
+      svg.setAttribute('role', 'img');
+      svg.setAttribute('aria-label', label);
+      svg.removeAttribute('aria-hidden');
+      svg.removeAttribute('aria-labelledby');
+      return;
+    }
+    const cap = this.closest('figure')?.querySelector('figcaption');
+    const capText = cap?.textContent?.trim();
+    if (capText) {
+      if (!cap.id) cap.id = `velin-sparkline-cap-${Math.random().toString(36).slice(2, 9)}`;
+      svg.setAttribute('role', 'img');
+      svg.setAttribute('aria-labelledby', cap.id);
+      svg.removeAttribute('aria-hidden');
+      svg.removeAttribute('aria-label');
+      return;
+    }
+    svg.setAttribute('role', 'presentation');
+    svg.setAttribute('aria-hidden', 'true');
+    svg.setAttribute('focusable', 'false');
+    svg.removeAttribute('aria-label');
+    svg.removeAttribute('aria-labelledby');
+  }
 }
 
 if (typeof customElements !== 'undefined' && !customElements.get('velin-sparkline')) {

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

@@ -49,10 +49,14 @@ const styles = `
   .panels ::slotted(*) { display: none; }
   .panels ::slotted([data-active]) { display: block; }
   @media (prefers-reduced-motion: reduce) { .step__marker { transition: none; } }
+  .velin-sr-only {
+    position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px;
+    overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0;
+  }
 `;
 
-class VelinStepperWC extends HTMLElement {
-  static get observedAttributes() { return ['active']; }
+class VelinStepper extends HTMLElement {
+  static get observedAttributes() { return ['active', 'aria-label', 'labels']; }
 
   constructor() {
     super();
@@ -67,19 +71,25 @@ class VelinStepperWC extends HTMLElement {
 
   _buildSteps() {
     const labels = (this.getAttribute('labels') || '').split(',').map(s => s.trim());
+    const listLabel = this.getAttribute('aria-label') || 'Progress';
     const stepsHTML = labels.map((label, i) => {
       const state = i < this._current ? 'completed' : i === this._current ? 'active' : '';
-      const marker = i < this._current ? '&#10003;' : (i + 1);
+      const status =
+        i < this._current ? 'completed' : i === this._current ? 'current step' : 'upcoming';
+      const marker =
+        i < this._current
+          ? '<span class="velin-sr-only">Completed</span><span aria-hidden="true">&#10003;</span>'
+          : `<span aria-hidden="true">${i + 1}</span>`;
       const ariaCurrent = i === this._current ? ' aria-current="step"' : '';
-      return `<div class="step ${state}" role="listitem"${ariaCurrent}><span class="step__marker" aria-hidden="true">${marker}</span><span class="step__label">${escapeHTML(label)}</span></div>`;
+      const itemLabel = label ? `${label}, ${status}` : `Step ${i + 1}, ${status}`;
+      return `<div class="step ${state}" role="listitem" aria-label="${escapeHTML(itemLabel)}"${ariaCurrent}><span class="step__marker">${marker}</span><span class="step__label">${escapeHTML(label)}</span></div>`;
     }).join('');
 
     this.shadowRoot.innerHTML = `
       <style>${styles}</style>
-      <div class="steps" role="list" aria-label="Progress" part="steps">${stepsHTML}</div>
+      <div class="steps" role="list" aria-label="${escapeHTML(listLabel)}" part="steps">${stepsHTML}</div>
       <div class="panels" part="panels"><slot></slot></div>
     `;
-    this._updatePanels();
   }
 
   _updatePanels() {
@@ -124,5 +134,24 @@ class VelinStepperWC extends HTMLElement {
   }
 }
 
-customElements.define('velin-stepper-wc', VelinStepperWC);
-export default VelinStepperWC;
+/** @deprecated Use `<velin-stepper>` */
+class VelinStepperWC extends VelinStepper {
+  static _warned = false;
+
+  connectedCallback() {
+    if (!VelinStepperWC._warned && typeof console !== 'undefined' && console.warn) {
+      VelinStepperWC._warned = true;
+      console.warn('[velinstyle] <velin-stepper-wc> is deprecated; use <velin-stepper> instead.');
+    }
+    super.connectedCallback();
+  }
+}
+
+if (!customElements.get('velin-stepper')) {
+  customElements.define('velin-stepper', VelinStepper);
+}
+if (!customElements.get('velin-stepper-wc')) {
+  customElements.define('velin-stepper-wc', VelinStepperWC);
+}
+export default VelinStepper;
+export { VelinStepper, VelinStepperWC };