@adia-ai/web-components 0.4.6 → 0.4.7

package/components/swatch/swatch.js

@@ -1,121 +1,17 @@
 /**
- * <swatch-ui> — color / style sample primitive.
+ * `<swatch-ui>` — auto-registers the tag on import.
  *
- * A small inline tile representing one visual sample — a chart series's
- * legend marker, a design-token step in a color or spacing scale, a
- * theme-preview pill. Replaces docs-only `<span data-swatch>` usage and
- * the per-shape CSS that used to live inside chart-legend-ui.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * 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>
+ *   import { UISwatch } from '@adia-ai/web-components/components/swatch/class';
  *
- * 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
- *
- * Slots:
- *   default — rich label content; takes precedence over [label] attr
- *
- * 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)
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-const SHAPES = new Set(['block', 'dot', 'square', 'line', 'dashed']);
-const SIZES = new Set(['sm', 'md', 'lg']);
-
-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 },
-  };
-
-  static template = () => null;
-
-  #tileEl = null;
-  #labelEl = null;
-  #stamped = false;
-
-  connected() {
-    this.#stamp();
-  }
-
-  render() {
-    this.#stamp();
-    this.#sync();
-  }
-
-  #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))
-    );
-    this.innerHTML = '';
-
-    this.#tileEl = document.createElement('span');
-    this.#tileEl.setAttribute('data-tile', '');
-    this.#tileEl.setAttribute('aria-hidden', 'true');
-    this.appendChild(this.#tileEl);
-
-    this.#labelEl = document.createElement('span');
-    this.#labelEl.setAttribute('data-label', '');
-    if (slotted.length) {
-      for (const n of slotted) this.#labelEl.appendChild(n);
-    }
-    this.appendChild(this.#labelEl);
-
-    this.#stamped = true;
-  }
-
-  #sync() {
-    if (!this.#tileEl || !this.#labelEl) return;
-
-    // Normalize enum values; fall back silently when a consumer sets a typo.
-    const shape = SHAPES.has(this.shape) ? this.shape : 'square';
-    const size  = SIZES.has(this.size)   ? this.size  : 'md';
-    if (shape !== this.shape) this.setAttribute('shape', shape);
-    if (size  !== this.size)  this.setAttribute('size', size);
-
-    // Color: only write the inline custom property when [color] is set
-    // explicitly; otherwise leave whatever the consumer wrote via
-    // style="--swatch-color: …" alone.
-    if (this.color) {
-      this.style.setProperty('--swatch-color', this.color);
-    }
-
-    // Label: prefer slotted content (already in #labelEl from #stamp);
-    // when label-attr is set and the slot is empty, write the attribute.
-    if (!this.#labelEl.firstChild && this.label) {
-      this.#labelEl.textContent = this.label;
-    } else if (this.#labelEl.firstChild?.nodeType === 3 && this.label) {
-      // Pure-text node from a previous label-attr render — keep it
-      // synced to the current attr value.
-      this.#labelEl.textContent = this.label;
-    }
-
-    // Hide the label box when there's no content. Empty-but-stamped span
-    // would otherwise eat the layout gap.
-    const hasLabel = this.#labelEl.textContent.trim().length > 0
-      || (this.#labelEl.firstElementChild != null);
-    this.#labelEl.toggleAttribute('hidden', !hasLabel);
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UISwatch } from './class.js';
 
-  disconnected() {
-    this.#tileEl = null;
-    this.#labelEl = null;
-    this.#stamped = false;
-  }
-}
+defineIfFree('swatch-ui', UISwatch);
 
-customElements.define('swatch-ui', UISwatch);
 export { UISwatch };

package/components/swiper/class.js

@@ -0,0 +1,373 @@
+/**
+ * Non-side-effect class export for `<swiper-ui>`.
+ *
+ * Importing this file gives you the class(es) without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/swiper`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <swiper-ui autoplay interval="5000" peek>
+ *   <img src="slide1.jpg" alt="Slide 1">
+ *   <card-ui>...</card-ui>
+ *   <div>Any content</div>
+ * </swiper-ui>
+ *
+ * CSS-first carousel. Scroll-snap does all positioning.
+ * JS handles: auto-advance, programmatic API, ARIA, paddles + dots.
+ *
+ * On connect, wraps user children into a [data-swiper-track] scroll
+ * container so pagination dots can sit below (outside overflow).
+ *
+ * Pagination dots and prev/next paddles are JS-stamped on every
+ * engine. Native ::scroll-marker / ::scroll-button are Chrome-135-only
+ * with no Safari / Firefox roadmap; re-evaluate when cross-engine.
+ *
+ * Events:
+ *   change         — { detail: { index, slide } }
+ *   autoplay-pause — { detail: { reason } }
+ *   autoplay-resume
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UISwiper extends UIElement {
+  static properties = {
+    autoplay:          { type: Boolean, default: false, reflect: true },
+    interval:          { type: Number,  default: 5000,  reflect: true },
+    noPauseOnHover:    { type: Boolean, default: false, reflect: true, attribute: 'no-pause-on-hover' },
+    loop:              { type: Boolean, default: false, reflect: true },
+    peek:              { type: Boolean, default: false, reflect: true },
+    snap:              { type: String,  default: 'start', reflect: true },
+    gap:               { type: String,  default: '',    reflect: true },
+    slidesPerView:     { type: String,  default: '',    reflect: true, attribute: 'slides-per-view' },
+  };
+
+  static template = () => null;
+
+  #track = null;
+  #timer = null;
+  #observer = null;
+  #activeIndex = 0;
+  #bound = false;
+  #fallbackNav = false;
+  #drag = null; /* { pointerId, startX, startScrollLeft, hasMoved } */
+
+  get slides() {
+    if (!this.#track) return [];
+    return [...this.#track.children];
+  }
+
+  get activeIndex() { return this.#activeIndex; }
+
+  connected() {
+    // Wrap user children into a scroll track (once)
+    if (!this.#track) {
+      this.#track = document.createElement('div');
+      this.#track.setAttribute('data-swiper-track', '');
+
+      // Move all current children into the track
+      while (this.firstChild) {
+        this.#track.appendChild(this.firstChild);
+      }
+      this.appendChild(this.#track);
+    }
+
+    // ARIA
+    this.setAttribute('role', 'region');
+    this.setAttribute('aria-roledescription', 'carousel');
+    if (!this.getAttribute('aria-label')) {
+      this.setAttribute('aria-label', 'Carousel');
+    }
+
+    this.#labelSlides();
+    this.#setupObserver();
+    this.#setupFallbackNav();
+
+    if (!this.#bound) {
+      this.#bound = true;
+
+      // Pause on hover/focus (default on; suppress with [no-pause-on-hover])
+      if (!this.noPauseOnHover) {
+        this.addEventListener('pointerenter', this.#onPauseHover);
+        this.addEventListener('pointerleave', this.#onResumeHover);
+        this.addEventListener('focusin', this.#onPauseFocus);
+        this.addEventListener('focusout', this.#onResumeFocus);
+      }
+
+      // Keyboard navigation
+      this.addEventListener('keydown', this.#onKeydown);
+
+      // Click + drag (mouse / pen). Touch keeps native pan via scroll-snap.
+      this.#track.addEventListener('pointerdown', this.#onPointerDown);
+      this.#track.addEventListener('pointermove', this.#onPointerMove);
+      this.#track.addEventListener('pointerup',     this.#onPointerUp);
+      this.#track.addEventListener('pointercancel', this.#onPointerUp);
+      // Capture-phase click suppression so a drag-on-button doesn't activate it.
+      this.#track.addEventListener('click', this.#onClickCapture, true);
+    }
+
+    if (this.autoplay) this.play();
+  }
+
+  render() {
+    if (this.gap && this.#track) {
+      const space = `var(--a-space-${this.gap})`;
+      this.style.setProperty('--swiper-gap', space);
+    }
+  }
+
+  disconnected() {
+    this.pause();
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.removeEventListener('pointerenter', this.#onPauseHover);
+    this.removeEventListener('pointerleave', this.#onResumeHover);
+    this.removeEventListener('focusin', this.#onPauseFocus);
+    this.removeEventListener('focusout', this.#onResumeFocus);
+    this.removeEventListener('keydown', this.#onKeydown);
+    if (this.#track) {
+      this.#track.removeEventListener('pointerdown',   this.#onPointerDown);
+      this.#track.removeEventListener('pointermove',   this.#onPointerMove);
+      this.#track.removeEventListener('pointerup',     this.#onPointerUp);
+      this.#track.removeEventListener('pointercancel', this.#onPointerUp);
+      this.#track.removeEventListener('click',         this.#onClickCapture, true);
+    }
+    this.#drag = null;
+    this.#track = null;
+    this.#bound = false;
+  }
+
+  // ── Public API ──
+
+  next() {
+    const slides = this.slides;
+    const nextIndex = Math.min(this.#activeIndex + 1, slides.length - 1);
+    if (nextIndex !== this.#activeIndex || this.loop) {
+      this.goTo(this.loop && nextIndex === this.#activeIndex ? 0 : nextIndex);
+    }
+  }
+
+  prev() {
+    const slides = this.slides;
+    const prevIndex = Math.max(this.#activeIndex - 1, 0);
+    if (prevIndex !== this.#activeIndex || this.loop) {
+      this.goTo(this.loop && prevIndex === this.#activeIndex ? slides.length - 1 : prevIndex);
+    }
+  }
+
+  goTo(index) {
+    const slides = this.slides;
+    const slide = slides[index];
+    if (slide && this.#track) {
+      this.#track.scrollTo({ left: slide.offsetLeft - this.#track.offsetLeft, behavior: 'smooth' });
+    }
+  }
+
+  play() {
+    this.pause();
+    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) return;
+
+    this.#timer = setInterval(() => {
+      const slides = this.slides;
+      const atEnd = this.#activeIndex >= slides.length - 1;
+      if (atEnd && this.loop) this.goTo(0);
+      else if (!atEnd) this.next();
+      else this.pause();
+    }, this.interval || 5000);
+  }
+
+  pause() {
+    if (this.#timer) {
+      clearInterval(this.#timer);
+      this.#timer = null;
+    }
+  }
+
+  // ── Internal ──
+
+  #labelSlides() {
+    const slides = this.slides;
+    slides.forEach((slide, i) => {
+      slide.setAttribute('role', 'group');
+      slide.setAttribute('aria-roledescription', 'slide');
+      if (!slide.getAttribute('aria-label')) {
+        slide.setAttribute('aria-label', `${i + 1} of ${slides.length}`);
+      }
+    });
+  }
+
+  #setupObserver() {
+    this.#observer = new IntersectionObserver(entries => {
+      for (const entry of entries) {
+        if (entry.isIntersecting && entry.intersectionRatio > 0.5) {
+          const slides = this.slides;
+          const index = slides.indexOf(entry.target);
+          if (index !== -1 && index !== this.#activeIndex) {
+            this.#activeIndex = index;
+            this.#updateFallbackDots();
+            this.dispatchEvent(new CustomEvent('change', {
+              bubbles: true,
+              detail: { index, slide: entry.target },
+            }));
+          }
+        }
+      }
+    }, { root: this.#track, threshold: 0.5 });
+
+    for (const slide of this.slides) {
+      this.#observer.observe(slide);
+    }
+  }
+
+  #setupFallbackNav() {
+    if (this.#fallbackNav) return;
+    this.#fallbackNav = true;
+
+    // Stamp prev/next paddles
+    const prev = document.createElement('button-ui');
+    prev.setAttribute('data-swiper-btn', '');
+    prev.setAttribute('data-swiper-prev', '');
+    prev.setAttribute('icon', 'caret-left');
+    prev.setAttribute('variant', 'ghost');
+    prev.setAttribute('aria-label', 'Previous slide');
+    prev.addEventListener('press', () => this.prev());
+
+    const next = document.createElement('button-ui');
+    next.setAttribute('data-swiper-btn', '');
+    next.setAttribute('data-swiper-next', '');
+    next.setAttribute('icon', 'caret-right');
+    next.setAttribute('variant', 'ghost');
+    next.setAttribute('aria-label', 'Next slide');
+    next.addEventListener('press', () => this.next());
+
+    this.appendChild(prev);
+    this.appendChild(next);
+
+    // Stamp pagination dots
+    const dots = document.createElement('div');
+    dots.setAttribute('data-swiper-dots', '');
+    dots.setAttribute('role', 'tablist');
+    dots.setAttribute('aria-label', 'Slide indicators');
+
+    this.slides.forEach((_, i) => {
+      const dot = document.createElement('button');
+      dot.setAttribute('role', 'tab');
+      dot.setAttribute('aria-label', `Slide ${i + 1}`);
+      if (i === 0) dot.setAttribute('aria-current', 'true');
+      dot.addEventListener('click', () => this.goTo(i));
+      dots.appendChild(dot);
+    });
+
+    this.appendChild(dots);
+  }
+
+  #updateFallbackDots() {
+    if (!this.#fallbackNav) return;
+    const dots = this.querySelector('[data-swiper-dots]');
+    if (!dots) return;
+    [...dots.children].forEach((dot, i) => {
+      dot.setAttribute('aria-current', i === this.#activeIndex ? 'true' : 'false');
+    });
+  }
+
+  // ── Event handlers ──
+
+  #onPauseHover = () => {
+    if (this.#timer) {
+      this.pause();
+      this.dispatchEvent(new CustomEvent('autoplay-pause', { bubbles: true, detail: { reason: 'hover' } }));
+    }
+  };
+
+  #onResumeHover = () => {
+    if (this.autoplay && !this.#timer) {
+      this.play();
+      this.dispatchEvent(new CustomEvent('autoplay-resume', { bubbles: true }));
+    }
+  };
+
+  #onPauseFocus = () => {
+    if (this.#timer) {
+      this.pause();
+      this.dispatchEvent(new CustomEvent('autoplay-pause', { bubbles: true, detail: { reason: 'focus' } }));
+    }
+  };
+
+  #onResumeFocus = (e) => {
+    if (this.autoplay && !this.contains(e.relatedTarget)) {
+      this.play();
+      this.dispatchEvent(new CustomEvent('autoplay-resume', { bubbles: true }));
+    }
+  };
+
+  #onKeydown = (e) => {
+    if (e.key === 'ArrowRight') { e.preventDefault(); this.next(); }
+    if (e.key === 'ArrowLeft') { e.preventDefault(); this.prev(); }
+  };
+
+  // ── Click + drag (mouse / pen) ──
+  // Native touch already scroll-pans the track; we only intercept mouse and
+  // pen so cursor users get the same swipe affordance as touch users.
+
+  #DRAG_THRESHOLD_PX = 5;
+
+  #onPointerDown = (e) => {
+    if (e.pointerType === 'touch') return;        /* native pan handles touch */
+    if (e.button !== 0) return;                   /* primary button only */
+    if (e.target.closest('button, button-ui, a, input, select, textarea')) return;
+    this.#drag = {
+      pointerId: e.pointerId,
+      startX: e.clientX,
+      startScrollLeft: this.#track.scrollLeft,
+      hasMoved: false,
+    };
+    /* Disable smooth scroll during drag so the bar tracks the pointer 1:1. */
+    this.#track.style.scrollBehavior = 'auto';
+    this.#track.setAttribute('data-dragging', '');
+  };
+
+  #onPointerMove = (e) => {
+    if (!this.#drag || e.pointerId !== this.#drag.pointerId) return;
+    const dx = e.clientX - this.#drag.startX;
+    if (Math.abs(dx) >= this.#DRAG_THRESHOLD_PX) {
+      if (!this.#drag.hasMoved) {
+        this.#drag.hasMoved = true;
+        /* Capture pointer so we keep tracking even if it leaves the track. */
+        try { this.#track.setPointerCapture(e.pointerId); } catch { /* noop */ }
+      }
+      this.#track.scrollLeft = this.#drag.startScrollLeft - dx;
+      e.preventDefault(); /* suppress text selection while dragging */
+    }
+  };
+
+  #onPointerUp = (e) => {
+    if (!this.#drag || e.pointerId !== this.#drag.pointerId) return;
+    const wasMoved = this.#drag.hasMoved;
+    if (wasMoved) {
+      try { this.#track.releasePointerCapture(e.pointerId); } catch { /* noop */ }
+    }
+    this.#drag = null;
+    /* Re-enable smooth scrolling; scroll-snap will glide to the nearest slide. */
+    this.#track.style.scrollBehavior = '';
+    this.#track.removeAttribute('data-dragging');
+    /* Ensure dragging stays "active" through the click event that follows
+       on the same gesture so #onClickCapture can suppress it. */
+    if (wasMoved) {
+      this.#track.setAttribute('data-just-dragged', '');
+      requestAnimationFrame(() => this.#track?.removeAttribute('data-just-dragged'));
+    }
+  };
+
+  #onClickCapture = (e) => {
+    if (this.#track?.hasAttribute('data-just-dragged')) {
+      e.preventDefault();
+      e.stopPropagation();
+    }
+  };
+}

package/components/swiper/swiper.a2ui.json

@@ -130,6 +130,10 @@
         "swiper",
         "carousel",
         "slide"
+      ],
+      "tags": [
+        "Slideshow",
+        "Carousel"
       ]
     },
     "tag": "swiper-ui",

package/components/swiper/swiper.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `<swiper-ui>` — CSS-first carousel with scroll-snap. Supports autoplay, loop, and peek; JS-stamped pagination dots and paddles.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/swiper
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run components`, then `npm run codegen:dts` to regenerate;
+ * or hand-author this file fully if rich event types are needed.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UISwiper extends UIElement {
+  /** Enable auto-advance */
+  autoplay: boolean;
+  /** Gap between slides (token: sm, md, lg) */
+  gap: string;
+  /** Autoplay interval in ms */
+  interval: number;
+  /** Infinite loop */
+  loop: boolean;
+  /** Suppress the default pause-on-hover/focus behavior for autoplay. */
+  noPauseOnHover: boolean;
+  /** Show peek of adjacent slides */
+  peek: boolean;
+  /** Number of slides visible at once. Accepts "1", "2", "3", or "auto". Empty = CSS default (single slide). */
+  slidesPerView: string;
+  /** Scroll-snap alignment — start, center, end, or none. */
+  snap: 'start' | 'center' | 'end' | 'none';
+}