@birdapi/velinstyle 0.7.0 → 0.8.0

package/components/velin-flip.js

@@ -0,0 +1,220 @@
+/*
+ * velin-flip.js — FLIP-style reorder + filter helper.
+ *
+ * FLIP (First, Last, Invert, Play) measures item rects before and after a
+ * DOM mutation, then animates the delta. Used for sorting/filtering UIs
+ * where rows reorder visibly. Pair it with the [data-velin-flip] attribute
+ * on a container plus [data-velin-filter-value] chips or [data-velin-filter-input]
+ * inputs to wire chip/search filtering with zero JS in your demo.
+ *
+ * API:
+ *   flipReorder(container, mutateFn, opts?)
+ *   filterList(container, predicateFn, opts?)
+ *
+ *   opts.duration  ms (default 250); reduced-motion forces 0
+ *   opts.easing    CSS timing function (default expo-out token)
+ *   opts.itemSelector children selector (default ':scope > *')
+ *
+ * Auto-init:
+ *   <ul data-velin-flip data-velin-filter-attr="tags" id="myList">
+ *     <li data-tags="a b">..</li> ...
+ *   </ul>
+ *   <button data-velin-filter-value="a" data-velin-filter-target="#myList">A</button>
+ *   <input data-velin-filter-input data-velin-filter-target="#myList">
+ *
+ *   Any chip or input with data-velin-filter-target pointing at a flip
+ *   container is wired automatically. The active chip carries
+ *   data-velin-filter-active so you can style it.
+ */
+
+const REDUCED_MOTION_MQ =
+  typeof window !== 'undefined' && window.matchMedia
+    ? window.matchMedia('(prefers-reduced-motion: reduce)')
+    : null;
+
+const DEFAULTS = {
+  duration: 250,
+  easing: 'var(--velin-ease-expo-out, cubic-bezier(0.16, 1, 0.3, 1))',
+  itemSelector: ':scope > *',
+};
+
+function getItems(container, selector) {
+  return Array.from(container.querySelectorAll(selector));
+}
+
+export function flipReorder(container, mutateFn, options = {}) {
+  if (!container || typeof mutateFn !== 'function') return;
+  const opts = { ...DEFAULTS, ...options };
+  const reduced = REDUCED_MOTION_MQ && REDUCED_MOTION_MQ.matches;
+
+  const items = getItems(container, opts.itemSelector);
+  const before = new Map();
+  items.forEach((el) => {
+    if (!el.hidden) before.set(el, el.getBoundingClientRect());
+  });
+
+  mutateFn();
+
+  if (reduced) return;
+
+  const items2 = getItems(container, opts.itemSelector);
+  items2.forEach((el) => {
+    if (el.hidden) return;
+    const prev = before.get(el);
+    const next = el.getBoundingClientRect();
+    if (!prev) {
+      if (typeof el.animate !== 'function') return;
+      el.animate(
+        [
+          { opacity: 0, transform: 'scale(0.96)' },
+          { opacity: 1, transform: 'scale(1)' },
+        ],
+        { duration: opts.duration, easing: opts.easing, fill: 'both' },
+      );
+      return;
+    }
+    const dx = prev.left - next.left;
+    const dy = prev.top - next.top;
+    if (dx === 0 && dy === 0) return;
+    if (typeof el.animate !== 'function') return;
+    el.animate(
+      [
+        { transform: `translate(${dx}px, ${dy}px)` },
+        { transform: 'translate(0, 0)' },
+      ],
+      { duration: opts.duration, easing: opts.easing, fill: 'both' },
+    );
+  });
+}
+
+export function filterList(container, predicate, options = {}) {
+  if (!container || typeof predicate !== 'function') return;
+  const opts = { ...DEFAULTS, ...options };
+  flipReorder(
+    container,
+    () => {
+      getItems(container, opts.itemSelector).forEach((el) => {
+        el.hidden = !predicate(el);
+      });
+    },
+    opts,
+  );
+}
+
+function readTokens(value) {
+  if (!value) return [];
+  return String(value)
+    .toLowerCase()
+    .split(/[\s,|]+/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function matchTokens(itemTokens, queryTokens, mode) {
+  if (!queryTokens.length) return true;
+  if (mode === 'all') return queryTokens.every((q) => itemTokens.includes(q));
+  return queryTokens.some((q) => itemTokens.includes(q));
+}
+
+function matchSearch(item, query) {
+  if (!query) return true;
+  const haystack =
+    (item.getAttribute('data-tags') || '') +
+    ' ' +
+    (item.getAttribute('data-search') || '') +
+    ' ' +
+    (item.textContent || '');
+  return haystack.toLowerCase().includes(query.toLowerCase());
+}
+
+class FilterController {
+  constructor(container) {
+    this.container = container;
+    this.tag = '';
+    this.search = '';
+    this.matchMode = container.getAttribute('data-velin-filter-mode') === 'all' ? 'all' : 'any';
+    this.itemSelector = container.getAttribute('data-velin-filter-item') || ':scope > *';
+  }
+
+  apply() {
+    const queryTokens = readTokens(this.tag);
+    const term = this.search;
+    filterList(
+      this.container,
+      (el) => {
+        const tokens = readTokens(el.getAttribute('data-tags'));
+        return matchTokens(tokens, queryTokens, this.matchMode) && matchSearch(el, term);
+      },
+      { itemSelector: this.itemSelector },
+    );
+  }
+}
+
+const _controllers = new WeakMap();
+
+function getController(container) {
+  let ctrl = _controllers.get(container);
+  if (!ctrl) {
+    ctrl = new FilterController(container);
+    _controllers.set(container, ctrl);
+  }
+  return ctrl;
+}
+
+function resolveTarget(triggerEl) {
+  const sel = triggerEl.getAttribute('data-velin-filter-target');
+  if (!sel) return null;
+  try {
+    return document.querySelector(sel);
+  } catch {
+    return null;
+  }
+}
+
+function highlightActive(group, active) {
+  if (!group) return;
+  group.querySelectorAll('[data-velin-filter-value]').forEach((btn) => {
+    if (btn === active) btn.setAttribute('data-velin-filter-active', '');
+    else btn.removeAttribute('data-velin-filter-active');
+  });
+}
+
+function autoInit() {
+  if (typeof document === 'undefined') return;
+
+  document.addEventListener('click', (event) => {
+    const target = event.target.closest('[data-velin-filter-value]');
+    if (!target) return;
+    const container = resolveTarget(target);
+    if (!container) return;
+    const group = target.closest('[data-velin-filter-group]') || target.parentElement;
+    highlightActive(group, target);
+    const ctrl = getController(container);
+    ctrl.tag = target.getAttribute('data-velin-filter-value') || '';
+    if (ctrl.tag.toLowerCase() === 'all' || ctrl.tag === '*') ctrl.tag = '';
+    ctrl.apply();
+  });
+
+  const handleInput = (event) => {
+    const input = event.target.closest('[data-velin-filter-input]');
+    if (!input) return;
+    const container = resolveTarget(input);
+    if (!container) return;
+    const ctrl = getController(container);
+    const raw = input.value || (typeof input.getAttribute === 'function' ? input.getAttribute('value') : '');
+    ctrl.search = (raw || '').trim();
+    ctrl.apply();
+  };
+  document.addEventListener('input', handleInput);
+  document.addEventListener('change', handleInput);
+}
+
+if (typeof document !== 'undefined') {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', autoInit, { once: true });
+  } else {
+    autoInit();
+  }
+}
+
+export default { flipReorder, filterList };

package/components/velin-icon.js

@@ -3,14 +3,33 @@ const PROVIDER_CDNS = {
   heroicons: 'https://unpkg.com/heroicons@2/24/outline/{name}.svg',
   bootstrap: 'https://unpkg.com/bootstrap-icons@latest/icons/{name}.svg',
   material: 'https://fonts.gstatic.com/s/i/short-term/release/materialsymbolsoutlined/{name}/default/24px.svg',
-  fontawesome: 'https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/regular/{name}.svg',
+  fontawesome: 'https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/solid/{name}.svg',
 };
 
+const PROVIDER_VARIANTS = {
+  fontawesome: {
+    regular: 'https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/regular/{name}.svg',
+    solid: 'https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/solid/{name}.svg',
+    brands: 'https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/svgs/brands/{name}.svg',
+  },
+  heroicons: {
+    outline: 'https://unpkg.com/heroicons@2/24/outline/{name}.svg',
+    solid: 'https://unpkg.com/heroicons@2/24/solid/{name}.svg',
+    mini: 'https://unpkg.com/heroicons@2/20/solid/{name}.svg',
+  },
+};
+
+function resolveProviderUrl(provider, variant) {
+  const variants = PROVIDER_VARIANTS[provider];
+  if (variant && variants?.[variant]) return variants[variant];
+  return PROVIDER_CDNS[provider];
+}
+
 const _svgCache = new Map();
 
 class VelinIcon extends HTMLElement {
   static get observedAttributes() {
-    return ['name', 'size', 'label', 'provider', 'sprite'];
+    return ['name', 'size', 'label', 'provider', 'variant', 'sprite'];
   }
 
   constructor() {
@@ -31,14 +50,15 @@ class VelinIcon extends HTMLElement {
     const size = this.getAttribute('size') || '24';
     const label = this.getAttribute('label');
     const provider = this.getAttribute('provider');
+    const variant = this.getAttribute('variant');
 
     if (!name) {
       this.innerHTML = '';
       return;
     }
 
-    if (provider && PROVIDER_CDNS[provider]) {
-      this._renderFromCDN(name, size, label, provider);
+    if (provider && (PROVIDER_CDNS[provider] || PROVIDER_VARIANTS[provider])) {
+      this._renderFromCDN(name, size, label, provider, variant);
       return;
     }
 
@@ -60,8 +80,17 @@ class VelinIcon extends HTMLElement {
     this._applyA11y(svg, label);
 
     const use = document.createElementNS(svgNS, 'use');
-    const spriteUrl = this.getAttribute('sprite') || 'velin-icons.svg';
-    use.setAttribute('href', `${spriteUrl}#${name}`);
+    const spriteAttr = this.getAttribute('sprite');
+    const localSymbol = document.getElementById(name);
+    const isLocalSymbol = localSymbol && localSymbol.tagName && localSymbol.tagName.toLowerCase() === 'symbol';
+    let href;
+    if (spriteAttr === '' || (spriteAttr == null && isLocalSymbol)) {
+      href = `#${name}`;
+    } else {
+      const spriteUrl = spriteAttr || 'velin-icons.svg';
+      href = `${spriteUrl}#${name}`;
+    }
+    use.setAttribute('href', href);
     svg.appendChild(use);
 
     this.innerHTML = '';
@@ -69,15 +98,20 @@ class VelinIcon extends HTMLElement {
     this._rendered = true;
   }
 
-  async _renderFromCDN(name, size, label, provider) {
-    const cacheKey = `${provider}:${name}`;
+  async _renderFromCDN(name, size, label, provider, variant) {
+    const cacheKey = `${provider}:${variant || 'default'}:${name}`;
 
     if (_svgCache.has(cacheKey)) {
       this._injectSVG(_svgCache.get(cacheKey), size, label);
       return;
     }
 
-    const url = PROVIDER_CDNS[provider].replace('{name}', name);
+    const template = resolveProviderUrl(provider, variant);
+    if (!template) {
+      this._renderFromSprite(name, size, label);
+      return;
+    }
+    const url = template.replace('{name}', name);
     try {
       const res = await fetch(url);
       if (!res.ok) throw new Error(`${res.status}`);

package/components/velin-live-dot.js

@@ -0,0 +1,85 @@
+/*
+ * <velin-live-dot status="live">Realtime</velin-live-dot>
+ *
+ * Tiny status indicator: a coloured dot with an optional concentric pulse
+ * (driven by the velin-live-pulse keyframe in chart-animation.css). Slot
+ * children render after the dot for an inline "Live - Streaming" label.
+ *
+ * Attributes:
+ *   status   "live" (default) | "paused" | "warning" | "error" | "muted"
+ *            Determines dot colour via the CSS custom prop --velin-live-color.
+ *   pulse    "true" (default) | "false"   Disables the looped pulse.
+ */
+
+const STATUS_COLORS = {
+  live: 'var(--velin-color-success, oklch(60% 0.16 145))',
+  paused: 'var(--velin-color-text-muted, oklch(60% 0.02 240))',
+  warning: 'var(--velin-color-warning, oklch(75% 0.16 80))',
+  error: 'var(--velin-color-danger, oklch(60% 0.2 25))',
+  muted: 'var(--velin-color-border, oklch(85% 0.01 240))',
+};
+
+const styles = `
+  :host {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--velin-space-2, 0.5rem);
+    font-size: inherit;
+    color: inherit;
+    line-height: 1.2;
+  }
+  .dot {
+    inline-size: 0.55rem;
+    block-size: 0.55rem;
+    border-radius: 50%;
+    background: var(--velin-live-color);
+    flex-shrink: 0;
+  }
+  :host([pulse="false"]) .dot { animation: none; }
+  :host(:not([pulse="false"])) .dot { animation: velin-live-pulse 1.8s var(--velin-ease-out, ease-out) infinite; }
+  @media (prefers-reduced-motion: reduce) {
+    .dot { animation: none !important; }
+  }
+`;
+
+const KEYFRAMES_FALLBACK = `
+@keyframes velin-live-pulse {
+  0% { box-shadow: 0 0 0 0 color-mix(in oklch, var(--velin-live-color) 65%, transparent); }
+  70% { box-shadow: 0 0 0 0.6rem color-mix(in oklch, var(--velin-live-color) 0%, transparent); }
+  100% { box-shadow: 0 0 0 0 transparent; }
+}`;
+
+class VelinLiveDot extends HTMLElement {
+  static get observedAttributes() {
+    return ['status', 'pulse'];
+  }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this._render();
+  }
+
+  attributeChangedCallback() {
+    if (this.shadowRoot) this._render();
+  }
+
+  _render() {
+    const status = this.getAttribute('status') || 'live';
+    const color = STATUS_COLORS[status] || STATUS_COLORS.live;
+    this.style.setProperty('--velin-live-color', color);
+    this.shadowRoot.innerHTML = `
+      <style>${styles}${KEYFRAMES_FALLBACK}</style>
+      <span class="dot" aria-hidden="true"></span><slot></slot>
+    `;
+  }
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('velin-live-dot')) {
+  customElements.define('velin-live-dot', VelinLiveDot);
+}
+
+export default VelinLiveDot;

package/components/velin-menubar.js

@@ -0,0 +1,83 @@
+import { rovingTabindex } from './focus-manager.js';
+import { escapeHTML } from './sanitize.js';
+import { SHADOW_A11Y_STYLES } from './shadow-a11y-styles.js';
+
+const styles = `
+  ${SHADOW_A11Y_STYLES}
+  :host { display: block; }
+  .menubar {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--velin-space-1, 0.25rem);
+    padding: var(--velin-space-2, 0.5rem);
+    background: var(--velin-color-surface-bright, #fff);
+    border-bottom: 1px solid var(--velin-color-border, #ddd);
+  }
+  ::slotted([role="menuitem"]) {
+    min-inline-size: 2.75rem;
+    min-block-size: 2.75rem;
+    padding: var(--velin-space-2, 0.5rem) var(--velin-space-4, 1rem);
+    background: none;
+    border: none;
+    border-radius: var(--velin-radius-sm, 0.25rem);
+    cursor: pointer;
+    font-size: var(--velin-text-base, 1rem);
+    color: var(--velin-color-text, #111);
+  }
+  ::slotted([role="menuitem"]:hover) {
+    background: var(--velin-color-surface-dim, #eee);
+  }
+`;
+
+class VelinMenubar extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open', delegatesFocus: true });
+    this._onKey = this._onKey.bind(this);
+  }
+
+  connectedCallback() {
+    const label = escapeHTML(this.getAttribute('aria-label') || 'Menu bar');
+    this.shadowRoot.innerHTML = `
+      <style>${styles}</style>
+      <div class="menubar" role="menubar" aria-label="${label}"><slot></slot></div>
+    `;
+    this.addEventListener('keydown', this._onKey);
+    this.shadowRoot.querySelector('slot')?.addEventListener('slotchange', () => this._init());
+    this._init();
+  }
+
+  _getItems() {
+    const slot = this.shadowRoot.querySelector('slot');
+    return slot ? slot.assignedElements().filter((el) => !el.hasAttribute('disabled')) : [];
+  }
+
+  _init() {
+    const items = this._getItems();
+    items.forEach((el, i) => {
+      if (!el.hasAttribute('role')) el.setAttribute('role', 'menuitem');
+      el.setAttribute('tabindex', i === 0 ? '0' : '-1');
+    });
+  }
+
+  _onKey(e) {
+    const items = this._getItems();
+    if (items.includes(e.target)) rovingTabindex(this, items, e);
+  }
+
+  static get observedAttributes() { return ['aria-label']; }
+
+  attributeChangedCallback(name) {
+    if (name === 'aria-label') {
+      const bar = this.shadowRoot?.querySelector('.menubar');
+      if (bar) bar.setAttribute('aria-label', escapeHTML(this.getAttribute('aria-label') || 'Menu bar'));
+    }
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener('keydown', this._onKey);
+  }
+}
+
+customElements.define('velin-menubar', VelinMenubar);
+export default VelinMenubar;

package/components/velin-rating.js

@@ -0,0 +1,91 @@
+import { rovingTabindex } from './focus-manager.js';
+import { escapeHTML } from './sanitize.js';
+import { SHADOW_A11Y_STYLES } from './shadow-a11y-styles.js';
+
+const styles = `
+  ${SHADOW_A11Y_STYLES}
+  :host { display: inline-block; }
+  .stars { display: inline-flex; gap: var(--velin-space-1, 0.25rem); }
+  button {
+    background: none; border: none; padding: var(--velin-space-1, 0.25rem);
+    font-size: 1.5rem; line-height: 1; cursor: pointer;
+    color: var(--velin-color-border, #ccc);
+  }
+  button[aria-checked="true"] { color: var(--velin-color-warning, #f59e0b); }
+`;
+
+const MAX = 5;
+
+class VelinRating extends HTMLElement {
+  static get observedAttributes() { return ['value']; }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open', delegatesFocus: true });
+    this._onClick = this._onClick.bind(this);
+    this._onKey = this._onKey.bind(this);
+  }
+
+  connectedCallback() {
+    this.shadowRoot.innerHTML = `<style>${styles}</style><div class="stars" role="radiogroup"></div>`;
+    this._render();
+    this.shadowRoot.querySelector('.stars').addEventListener('click', this._onClick);
+    this.shadowRoot.querySelector('.stars').addEventListener('keydown', this._onKey);
+  }
+
+  _value() {
+    const v = parseInt(this.getAttribute('value') || '0', 10);
+    return Math.min(MAX, Math.max(0, Number.isNaN(v) ? 0 : v));
+  }
+
+  _render() {
+    const group = this.shadowRoot.querySelector('.stars');
+    const val = this._value();
+    const label = escapeHTML(this.getAttribute('aria-label') || 'Rating');
+    group.setAttribute('aria-label', label);
+    group.innerHTML = '';
+    for (let i = 1; i <= MAX; i++) {
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.setAttribute('role', 'radio');
+      btn.setAttribute('aria-checked', i <= val ? 'true' : 'false');
+      btn.setAttribute('aria-label', escapeHTML(`${i} star${i > 1 ? 's' : ''}`));
+      btn.setAttribute('tabindex', i === (val || 1) ? '0' : '-1');
+      btn.dataset.value = String(i);
+      btn.textContent = i <= val ? '\u2605' : '\u2606';
+      group.appendChild(btn);
+    }
+  }
+
+  _getButtons() {
+    return [...this.shadowRoot.querySelectorAll('button[role="radio"]')];
+  }
+
+  _onClick(e) {
+    const btn = e.target.closest('button');
+    if (!btn) return;
+    this._setValue(parseInt(btn.dataset.value, 10));
+  }
+
+  _onKey(e) {
+    const buttons = this._getButtons();
+    if (!buttons.includes(e.target)) return;
+    rovingTabindex(this, buttons, e);
+    if (['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(e.key)) {
+      const focused = buttons.find((b) => b.getAttribute('tabindex') === '0');
+      if (focused) this._setValue(parseInt(focused.dataset.value, 10));
+    }
+  }
+
+  _setValue(n) {
+    this.setAttribute('value', String(n));
+    this.dispatchEvent(new CustomEvent('velin-change', { bubbles: true, detail: { value: n } }));
+  }
+
+  attributeChangedCallback(name) {
+    if (name === 'value' && this.shadowRoot?.querySelector('.stars')) this._render();
+  }
+}
+
+customElements.define('velin-rating', VelinRating);
+export default VelinRating;

package/components/velin-reveal.js

@@ -0,0 +1,80 @@
+/*
+ * 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').
+ */
+
+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));
+  };
+}
+
+if (typeof document !== 'undefined') {
+  const autoInit = () => {
+    if (document.documentElement && document.documentElement.hasAttribute('data-velin-reveal-auto')) {
+      initReveal();
+    }
+  };
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', autoInit, { once: true });
+  } else {
+    autoInit();
+  }
+}
+
+export default { initReveal };