@adia-ai/web-components 0.2.2 → 0.2.4

package/traits/confetti-stage.js

@@ -0,0 +1,143 @@
+/**
+ * Shared particle-stage for confetti + confetti-burst traits.
+ *
+ * Strategy: a session-long body-level singleton `<div popover="manual">`
+ * that the Popover API auto-promotes to the browser's top-layer once
+ * `showPopover()` is called. Particles spawn as absolutely-positioned
+ * `<span>` children of this stage with viewport-relative coordinates
+ * read from each host's `getBoundingClientRect()`. Effect: bursts
+ * escape `overflow: hidden` ancestors and render above modals,
+ * drawers, and any z-stacking context — same anchoring as a
+ * top-layer popover.
+ *
+ * The stage is created lazily on first call, never removed. Both
+ * `confetti` and `confetti-burst` import `getStage()` and share the
+ * singleton — there's no per-trait container, no z-index war, and no
+ * tear-down race when bursts overlap.
+ *
+ * Notes:
+ * - happy-dom stubs `showPopover` to a no-op (see test-setup.js), so
+ *   the try/catch only matters in browsers without the Popover API
+ *   (none of our baseline browsers since 2026; Chromium 125+, Safari
+ *   17+, Firefox 125+ all ship it).
+ * - Each particle self-removes on `animationend`. The stage is never
+ *   torn down — it's a session-long shared resource.
+ */
+
+const STAGE_ID = 'adia-confetti-stage';
+
+let stage = null;
+let stylesInjected = false;
+
+/**
+ * Lazily create + return the singleton popover stage. Idempotent —
+ * subsequent calls return the cached node (or rehydrate if it was
+ * removed externally, e.g. by a hot-reload).
+ */
+export function getStage() {
+  if (stage && stage.isConnected) return stage;
+
+  // Existing instance from a prior session / hot-reload?
+  const existing = document.getElementById(STAGE_ID);
+  if (existing) {
+    stage = existing;
+    showSilently(stage);
+    ensureStyles();
+    return stage;
+  }
+
+  const el = document.createElement('div');
+  el.id = STAGE_ID;
+  el.setAttribute('aria-hidden', 'true');
+  // popover="manual" — auto-promoted to the top-layer once shown,
+  // and immune to light-dismiss (no spurious close on outside click).
+  if ('popover' in HTMLElement.prototype) el.setAttribute('popover', 'manual');
+  el.style.cssText =
+    'position:fixed;inset:0;margin:0;padding:0;border:0;background:transparent;' +
+    'pointer-events:none;overflow:visible;z-index:99999;';
+  document.body.appendChild(el);
+  showSilently(el);
+  stage = el;
+  ensureStyles();
+  return stage;
+}
+
+function showSilently(el) {
+  // showPopover throws InvalidStateError if already shown. Guard with
+  // try/catch — cheaper than checking matches(':popover-open'), which
+  // happy-dom doesn't implement either.
+  try { el.showPopover?.(); } catch { /* already shown or unsupported */ }
+}
+
+/**
+ * Compute a host's center in viewport coordinates. Returns null if
+ * the host is detached (rect = 0×0 at 0,0 — bursts on a detached
+ * host would render at the viewport corner, so callers should bail).
+ */
+export function viewportCenterOf(host) {
+  const r = host.getBoundingClientRect();
+  // Detached / display:none host — width+height both 0 with all-zero
+  // coords. Treat as "no anchor" and let the trait fall back.
+  if (r.width === 0 && r.height === 0 && r.left === 0 && r.top === 0) return null;
+  return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+}
+
+/**
+ * Spawn a single particle <span> into the stage. Caller passes the
+ * starting viewport coords (from `viewportCenterOf(host)` plus any
+ * per-particle jitter the physics layer adds) and the visual props.
+ *
+ * The returned element self-removes on `animationend`. Caller is
+ * responsible for triggering motion (CSS transition, Web Animations
+ * API keyframes, or an inline `animation: …` rule).
+ */
+export function spawnParticle(stage, x, y, { size = 6, color = '#f44' } = {}) {
+  const p = document.createElement('span');
+  p.style.cssText =
+    'position:absolute;' +
+    `left:${x}px;top:${y}px;` +
+    `width:${size}px;height:${size}px;background:${color};` +
+    'border-radius:1px;pointer-events:none;will-change:transform,opacity;';
+  stage.appendChild(p);
+  p.addEventListener('animationend', () => p.remove(), { once: true });
+  return p;
+}
+
+/**
+ * Inject the @keyframes blocks the particles animate on. One-time,
+ * idempotent — guarded by a module flag. The keyframes drift each
+ * particle along a random vector; per-particle randomness is set via
+ * inline CSS custom properties (`--dx`, `--dy`, `--rot`).
+ */
+function ensureStyles() {
+  if (stylesInjected) return;
+  if (typeof document === 'undefined') return;
+  const styleEl = document.createElement('style');
+  styleEl.id = 'adia-confetti-stage-styles';
+  styleEl.textContent = `
+    @keyframes adia-confetti-fountain {
+      0%   { transform: translate(0, 0) rotate(0deg);            opacity: 1; }
+      100% { transform: translate(var(--dx, 0), var(--dy, 0))    rotate(var(--rot, 0deg)); opacity: 0; }
+    }
+    @keyframes adia-confetti-fall {
+      0%   { transform: translate(0, 0) rotate(0deg);            opacity: 1; }
+      100% { transform: translate(var(--dx, 0), var(--dy, 0))    rotate(var(--rot, 0deg)); opacity: 0; }
+    }
+  `;
+  document.head?.appendChild(styleEl);
+  stylesInjected = true;
+}
+
+export const SHARED_COLORS = ['#f44', '#4a4', '#44f', '#ff4', '#f4f', '#4ff'];
+
+/**
+ * Test-only: tear down the stage so test suites don't leak particles
+ * across cases. Not part of the public surface.
+ */
+export function _resetStage() {
+  if (stage && stage.parentNode) stage.remove();
+  const styleEl = document.getElementById('adia-confetti-stage-styles');
+  if (styleEl) styleEl.remove();
+  stage = null;
+  stylesInjected = false;
+}

package/traits/confetti.js

@@ -1,6 +1,21 @@
 import { defineTrait } from './define.js';
-import { prefersReducedMotion } from './_motion.js';
+import { prefersReducedMotion } from './motion.js';
+import { getStage, viewportCenterOf, spawnParticle, SHARED_COLORS } from './confetti-stage.js';
 
+/**
+ * `confetti` — falling-shower particle burst on connect.
+ *
+ * Particles are pushed into the singleton body-level
+ * `<div popover="manual" id="adia-confetti-stage">`, anchored to the
+ * host's viewport position at fire-time. The Popover API auto-promotes
+ * the stage to the browser's top-layer, so the shower escapes
+ * `overflow: hidden` ancestors and renders above modals, drawers, and
+ * any z-stacking context.
+ *
+ * Anchor model: viewport-fixed at fire-time. If the user scrolls
+ * during the 1.5s shower, the particles continue from their original
+ * viewport position — same UX as standard web-confetti libraries.
+ */
 export const confetti = defineTrait({
   name: 'confetti',
   category: 'interaction-delight',
@@ -15,61 +30,43 @@ export const confetti = defineTrait({
       return () => host.removeAttribute('data-confetti-active');
     }
 
-    const canvas = document.createElement('canvas');
-    canvas.style.cssText = 'position:absolute;inset:0;pointer-events:none;z-index:9999;';
-    host.style.position = host.style.position || 'relative';
-    host.appendChild(canvas);
+    const stage = getStage();
+    const center = viewportCenterOf(host);
 
-    const ctx = canvas.getContext('2d');
-    let rafId = null;
-    let running = true;
+    host.setAttribute('data-confetti-active', '');
 
-    // Bail gracefully when canvas 2D isn't available (SSR, JSDOM, happy-dom).
-    if (!ctx) {
-      host.setAttribute('data-confetti-active', '');
-      return () => {
-        canvas.remove();
-        host.removeAttribute('data-confetti-active');
-      };
-    }
+    // Fire one shower of ~60 particles. They fall from a band centered
+    // on the host's top edge, drift sideways under wind, and fade out.
+    if (center) {
+      const rect = host.getBoundingClientRect();
+      const halfW = Math.max(rect.width, 80) / 2;
+      // Band starts a hair above the host so the first frame lands
+      // visibly inside the host's bounds, then drifts down.
+      const startY = center.y - rect.height / 2 - 8;
 
-    const colors = ['#f44', '#4a4', '#44f', '#ff4', '#f4f', '#4ff'];
-    const particles = Array.from({ length: 60 }, () => ({
-      x: Math.random(),
-      y: Math.random() * -1,
-      vx: (Math.random() - 0.5) * 2,
-      vy: Math.random() * 2 + 1,
-      size: Math.random() * 4 + 2,
-      color: colors[Math.floor(Math.random() * colors.length)],
-    }));
+      for (let i = 0; i < 60; i++) {
+        const x = center.x + (Math.random() - 0.5) * halfW * 2;
+        const y = startY + Math.random() * 12;
+        const dx = (Math.random() - 0.5) * 80;
+        const dy = 200 + Math.random() * 240;
+        const rot = (Math.random() - 0.5) * 540;
+        const size = Math.random() * 4 + 2;
+        const color = SHARED_COLORS[Math.floor(Math.random() * SHARED_COLORS.length)];
+        const delay = Math.random() * 600;
+        const dur = 900 + Math.random() * 700;
 
-    function resize() {
-      canvas.width = host.offsetWidth;
-      canvas.height = host.offsetHeight;
-    }
-
-    function tick() {
-      if (!running) return;
-      resize();
-      ctx.clearRect(0, 0, canvas.width, canvas.height);
-      for (const p of particles) {
-        p.x += p.vx * 0.002;
-        p.y += p.vy * 0.003;
-        if (p.y > 1.1) { p.y = -0.1; p.x = Math.random(); }
-        ctx.fillStyle = p.color;
-        ctx.fillRect(p.x * canvas.width, p.y * canvas.height, p.size, p.size);
+        const p = spawnParticle(stage, x, y, { size, color });
+        p.style.setProperty('--dx', `${dx}px`);
+        p.style.setProperty('--dy', `${dy}px`);
+        p.style.setProperty('--rot', `${rot}deg`);
+        p.style.animation = `adia-confetti-fall ${dur}ms ${delay}ms ease-in forwards`;
       }
-      rafId = requestAnimationFrame(tick);
     }
 
-    host.setAttribute('data-confetti-active', '');
-    tick();
-
     return () => {
-      running = false;
-      if (rafId) cancelAnimationFrame(rafId);
-      canvas.remove();
       host.removeAttribute('data-confetti-active');
+      // In-flight particles self-remove on animationend; nothing to
+      // tear down on the stage (it's a session-long singleton).
     };
   },
 });

package/traits/confetti.test.js

@@ -1,9 +1,13 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { confetti } from './confetti.js';
-import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+import { _resetStage } from './confetti-stage.js';
+import { mountHost, connectTrait, resetDOM } from './test-helpers.js';
 
 describe('confetti', () => {
-  beforeEach(resetDOM);
+  beforeEach(() => {
+    resetDOM();
+    _resetStage();
+  });
 
   it('connect sets data-confetti-active without throwing', () => {
     const host = mountHost();
@@ -18,10 +22,25 @@ describe('confetti', () => {
     expect(host.hasAttribute('data-confetti-active')).toBe(false);
   });
 
-  it('without canvas (happy-dom): graceful degradation', () => {
-    // happy-dom returns null from canvas.getContext('2d'). The trait must
-    // null-check and not crash. Caught one of the original brittleness bugs.
+  it('no canvas: graceful degradation in happy-dom', () => {
+    // Old contract: this trait used a host-scoped <canvas>. New
+    // contract: it pushes <span> particles into the body-level
+    // popover stage (no canvas anywhere). The test name is kept for
+    // continuity — the assertion is the same: connect must not throw
+    // in environments without real layout (rect = 0,0,0,0 in
+    // happy-dom; viewportCenterOf returns null and the trait skips
+    // particle spawning gracefully).
     const host = mountHost();
     expect(() => connectTrait(confetti, host)).not.toThrow();
   });
+
+  it('does not append particles inside the host (stage is body-level)', () => {
+    const host = mountHost();
+    const inst = connectTrait(confetti, host);
+    // The old implementation appended a <canvas> child to the host.
+    // The new implementation must leave the host's children alone —
+    // every particle belongs to the body-level popover stage.
+    expect(host.children.length).toBe(0);
+    inst.disconnect(host);
+  });
 });

package/traits/count-up.js

@@ -1,5 +1,5 @@
 import { defineTrait } from './define.js';
-import { prefersReducedMotion } from './_motion.js';
+import { prefersReducedMotion } from './motion.js';
 
 export const countUp = defineTrait({
   name: 'count-up',
@@ -7,14 +7,34 @@ export const countUp = defineTrait({
   description: 'Animated numeric transitions',
   attributes: ['data-count-up-active'],
   events: ['count-up-done'],
-  config: ['data-count-up-target', 'data-count-duration'],
+  config: [
+    'data-count-up-target',
+    'data-count-duration',
+    'data-count-prefix',
+    'data-count-suffix',
+    'data-count-decimals',
+    'data-count-locale',
+  ],
   setup({ host }) {
-    const target = parseFloat(host.getAttribute('data-count-up-target')) || 0;
+    const target   = parseFloat(host.getAttribute('data-count-up-target')) || 0;
     const duration = parseInt(host.getAttribute('data-count-duration'), 10) || 1000;
+    const prefix   = host.getAttribute('data-count-prefix') ?? '';
+    const suffix   = host.getAttribute('data-count-suffix') ?? '';
+    const decimals = Math.max(0, parseInt(host.getAttribute('data-count-decimals'), 10) || 0);
+    const locale   = host.getAttribute('data-count-locale') || undefined;
+
+    // Locale-aware separators ("2,438,000" not "2438000"). The decimals attr
+    // controls the fraction-digit count for currency / percentage cases
+    // ($2,438,000.00 with decimals=2; 12.5% with decimals=1).
+    const formatter = new Intl.NumberFormat(locale, {
+      minimumFractionDigits: decimals,
+      maximumFractionDigits: decimals,
+    });
+    const fmt = (value) => `${prefix}${formatter.format(value)}${suffix}`;
 
     // Reduced-motion: jump straight to target and fire done event.
     if (prefersReducedMotion()) {
-      host.textContent = target;
+      host.textContent = fmt(target);
       host.setAttribute('data-count-up-active', '');
       queueMicrotask(() => {
         host.removeAttribute('data-count-up-active');
@@ -38,12 +58,17 @@ export const countUp = defineTrait({
       const elapsed = now - start;
       const progress = Math.min(elapsed / duration, 1);
       const value = target * easeOutQuart(progress);
-      host.textContent = Math.round(value);
+      // Round to the configured decimal precision so the displayed value
+      // doesn't flicker between fraction-bearing intermediates.
+      const rounded = decimals > 0
+        ? Math.round(value * Math.pow(10, decimals)) / Math.pow(10, decimals)
+        : Math.round(value);
+      host.textContent = fmt(rounded);
 
       if (progress < 1) {
         rafId = requestAnimationFrame(tick);
       } else {
-        host.textContent = target;
+        host.textContent = fmt(target);
         host.removeAttribute('data-count-up-active');
         host.dispatchEvent(new CustomEvent('count-up-done', { bubbles: true }));
       }

package/traits/count-up.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { countUp } from './count-up.js';
-import { mountHost, connectTrait, spyEvent, resetDOM, wait, raf } from './_test-helpers.js';
+import { mountHost, connectTrait, spyEvent, resetDOM, wait, raf } from './test-helpers.js';
 
 describe('count-up', () => {
   beforeEach(resetDOM);

package/traits/declarative.test.js

@@ -16,7 +16,7 @@ import { UIElement } from '../core/element.js';
 import { pressable } from './pressable.js';
 import { focusable } from './focusable.js';
 import { hoverable } from './hoverable.js';
-import { resetDOM } from './_test-helpers.js';
+import { resetDOM } from './test-helpers.js';
 
 let counter = 0;
 function defineUniqueTag(BaseImpl) {

package/traits/dirty-state.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { dirtyState } from './dirty-state.js';
-import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+import { mountHost, connectTrait, resetDOM } from './test-helpers.js';
 
 describe('dirty-state', () => {
   beforeEach(resetDOM);

package/traits/drag-ghost.js

@@ -9,16 +9,66 @@ export const dragGhost = defineTrait({
   config: [],
   setup({ host }) {
     let ghost = null;
+    let clickOffsetX = 0;
+    let clickOffsetY = 0;
+
+    function onPointerDown(e) {
+      // Capture click offset against host's visual box (post-transform).
+      const rect = host.getBoundingClientRect();
+      clickOffsetX = e.clientX - rect.left;
+      clickOffsetY = e.clientY - rect.top;
+    }
 
     function onDragStart(e) {
+      // Snapshot is taken synchronously at setDragImage() time. We position
+      // the ghost over the host's exact viewport rect so the bitmap is
+      // pixel-identical to what the user clicked — no CSS-scope drift, no
+      // box-sizing surprises, no transform mismatch. The clone is removed
+      // before the browser paints its next frame (drag image is the
+      // browser's own translucent overlay on the cursor), so the user
+      // never sees a doubled element.
+      //
+      // The data-drag-ghost-active attribute is set AFTER setDragImage(),
+      // so the ghost snapshot doesn't pick up the dragged-state styling
+      // (e.g. opacity: 0.4 on the original).
+      const rect = host.getBoundingClientRect();
+      const cs = getComputedStyle(host);
+
       ghost = host.cloneNode(true);
+      // box-sizing: border-box makes width == rect.width regardless of
+      // whether the host was content-box; rect.width/.height already are
+      // the host's border-box dimensions (getBoundingClientRect post-
+      // transform visual box). margin: 0 prevents collapse-into-body
+      // margins from offsetting the ghost.
       ghost.style.cssText = `
-        position: fixed; top: -9999px; left: -9999px;
-        pointer-events: none; opacity: 0.8; z-index: 99999;
+        position: fixed;
+        left: ${rect.left}px; top: ${rect.top}px;
+        width: ${rect.width}px; height: ${rect.height}px;
+        box-sizing: border-box;
+        margin: 0;
+        pointer-events: none;
+        opacity: 0.8;
+        z-index: 99999;
       `;
+      // Preserve the host's transform so a scaled/rotated host produces a
+      // matching ghost bitmap.
+      if (cs.transform && cs.transform !== 'none') {
+        ghost.style.transform = cs.transform;
+        ghost.style.transformOrigin = cs.transformOrigin;
+      }
       document.body.appendChild(ghost);
-      e.dataTransfer?.setDragImage(ghost, 0, 0);
+      e.dataTransfer?.setDragImage(ghost, clickOffsetX, clickOffsetY);
       host.setAttribute('data-drag-ghost-active', '');
+      // Hide the ghost in the next microtask — setDragImage already took
+      // its snapshot synchronously. We hide rather than remove so any
+      // browser that re-reads the element during the drag cycle (rare,
+      // but Safari has historically done this on drop) still finds it.
+      // We hide via visibility (paint suppressed) rather than
+      // display:none (which would zero the bitmap if the browser ever
+      // re-snapshots).
+      queueMicrotask(() => {
+        if (ghost) ghost.style.visibility = 'hidden';
+      });
     }
 
     function onDragEnd() {
@@ -27,10 +77,12 @@ export const dragGhost = defineTrait({
     }
 
     host.setAttribute('draggable', 'true');
+    host.addEventListener('pointerdown', onPointerDown);
     host.addEventListener('dragstart', onDragStart);
     host.addEventListener('dragend', onDragEnd);
 
     return () => {
+      host.removeEventListener('pointerdown', onPointerDown);
       host.removeEventListener('dragstart', onDragStart);
       host.removeEventListener('dragend', onDragEnd);
       if (ghost) { ghost.remove(); ghost = null; }

package/traits/drag-ghost.test.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { dragGhost } from './drag-ghost.js';
-import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+import { mountHost, connectTrait, resetDOM } from './test-helpers.js';
 
 describe('drag-ghost', () => {
   beforeEach(resetDOM);