@adia-ai/web-components 0.2.2 → 0.2.4

package/traits/_catalog.json

@@ -1,7 +1,7 @@
 {
   "generated": "scripts/build/traits-catalog.mjs",
   "note": "Generated from packages/web-components/traits/*.js. Do not hand-edit. Run `node scripts/build/traits-catalog.mjs`.",
-  "count": 41,
+  "count": 56,
   "categories": [
     "animation-feedback",
     "audio-haptics-sensory",
@@ -14,6 +14,22 @@
     "visual-dynamics"
   ],
   "traits": [
+    {
+      "name": "error-shake",
+      "category": "animation-feedback",
+      "description": "Horizontal lateral oscillation on validation failure",
+      "attributes": [
+        "data-error-shake-active"
+      ],
+      "events": [
+        "error-shake-done"
+      ],
+      "config": [
+        "data-error-shake-amplitude",
+        "data-error-shake-duration",
+        "data-error-shake-trigger"
+      ]
+    },
     {
       "name": "fade-presence",
       "category": "animation-feedback",
@@ -61,6 +77,21 @@
         "data-spring-damping"
       ]
     },
+    {
+      "name": "success-checkmark",
+      "category": "animation-feedback",
+      "description": "Stroke-draw checkmark on validation success",
+      "attributes": [
+        "data-success-checkmark-active"
+      ],
+      "events": [
+        "success-checkmark-done"
+      ],
+      "config": [
+        "data-success-checkmark-position",
+        "data-success-checkmark-trigger"
+      ]
+    },
     {
       "name": "tilt-hover",
       "category": "animation-feedback",
@@ -71,6 +102,23 @@
       "events": [],
       "config": []
     },
+    {
+      "name": "announcer",
+      "category": "audio-haptics-sensory",
+      "description": "aria-live mirror for AT — announces host state changes via singleton polite/assertive regions",
+      "attributes": [
+        "data-announcer-active"
+      ],
+      "events": [
+        "announcement-made"
+      ],
+      "config": [
+        "data-announce-on",
+        "data-announce-message",
+        "data-announce-priority",
+        "data-announce-throttle"
+      ]
+    },
     {
       "name": "attention-pulse",
       "category": "audio-haptics-sensory",
@@ -95,7 +143,11 @@
       ],
       "config": [
         "data-count-up-target",
-        "data-count-duration"
+        "data-count-duration",
+        "data-count-prefix",
+        "data-count-suffix",
+        "data-count-decimals",
+        "data-count-locale"
       ]
     },
     {
@@ -147,6 +199,22 @@
       "events": [],
       "config": []
     },
+    {
+      "name": "input-mask",
+      "category": "forms-data",
+      "description": "Locale-aware as-you-type formatter (phone, credit-card, date, currency)",
+      "attributes": [
+        "data-input-mask-active",
+        "data-input-mask-complete"
+      ],
+      "events": [
+        "mask-commit"
+      ],
+      "config": [
+        "data-mask-pattern",
+        "data-mask-strip-on-commit"
+      ]
+    },
     {
       "name": "resettable",
       "category": "forms-data",
@@ -185,6 +253,35 @@
       "events": [],
       "config": []
     },
+    {
+      "name": "droppable",
+      "category": "input-interaction",
+      "description": "Marks an element as a drop target for draggable-list-item; emits dnd-drop-enter / leave / receive",
+      "attributes": [
+        "data-droppable-id",
+        "data-droppable-over",
+        "data-droppable-valid"
+      ],
+      "events": [
+        "dnd-drop-enter",
+        "dnd-drop-leave",
+        "dnd-drop-receive"
+      ],
+      "config": []
+    },
+    {
+      "name": "droppable-collection",
+      "category": "input-interaction",
+      "description": "Coordinates droppable children; re-emits drops as dnd-collection-drop",
+      "attributes": [
+        "data-droppable-collection-active",
+        "data-droppable-collection-dragging"
+      ],
+      "events": [
+        "dnd-collection-drop"
+      ],
+      "config": []
+    },
     {
       "name": "focusable",
       "category": "input-interaction",
@@ -205,6 +302,26 @@
       "events": [],
       "config": []
     },
+    {
+      "name": "long-press",
+      "category": "input-interaction",
+      "description": "Press-and-hold trigger: fires after configurable duration with progress events",
+      "attributes": [
+        "data-long-press-active",
+        "data-long-press-progress",
+        "data-long-press-fired"
+      ],
+      "events": [
+        "long-press",
+        "long-press-cancelled",
+        "long-press-progress"
+      ],
+      "config": [
+        "data-long-press-duration",
+        "data-long-press-tolerance",
+        "data-long-press-progress-interval"
+      ]
+    },
     {
       "name": "pressable",
       "category": "input-interaction",
@@ -230,7 +347,7 @@
     {
       "name": "confetti-burst",
       "category": "interaction-delight",
-      "description": "Upward fountain particle burst",
+      "description": "Upward fountain particle burst — fires on each `press` event",
       "attributes": [
         "data-confetti-burst-active"
       ],
@@ -249,6 +366,39 @@
       "events": [],
       "config": []
     },
+    {
+      "name": "arrow-grid-nav",
+      "category": "keyboard-navigation",
+      "description": "2D arrow-key navigation for grids, calendars, menubars (APG grid pattern)",
+      "attributes": [
+        "data-arrow-grid-nav-active",
+        "data-grid-active-row",
+        "data-grid-active-col"
+      ],
+      "events": [
+        "grid-activate",
+        "grid-edge",
+        "grid-cell-change"
+      ],
+      "config": [
+        "data-grid-columns",
+        "data-grid-mode"
+      ]
+    },
+    {
+      "name": "focus-restore",
+      "category": "keyboard-navigation",
+      "description": "Capture previously-focused element on connect, restore focus on disconnect",
+      "attributes": [
+        "data-focus-restore-active"
+      ],
+      "events": [
+        "focus-restored"
+      ],
+      "config": [
+        "data-focus-restore-on-mount"
+      ]
+    },
     {
       "name": "focus-trap",
       "category": "keyboard-navigation",
@@ -291,6 +441,22 @@
       ],
       "config": []
     },
+    {
+      "name": "keyboard-reorderable",
+      "category": "keyboard-navigation",
+      "description": "Keyboard alternative to draggable-list-item: arrow keys + Space to lift / drop / Esc to cancel",
+      "attributes": [
+        "data-keyboard-reorderable-lifting",
+        "data-keyboard-reorderable-id"
+      ],
+      "events": [
+        "dnd-lift",
+        "dnd-drop-target-change",
+        "dnd-drop",
+        "dnd-drop-cancel"
+      ],
+      "config": []
+    },
     {
       "name": "roving-tabindex",
       "category": "keyboard-navigation",
@@ -317,7 +483,8 @@
       "description": "Positions relative to an anchor element",
       "attributes": [
         "data-anchor-positioning-placed",
-        "data-anchor-placement-actual"
+        "data-anchor-placement-actual",
+        "data-anchor-mode"
       ],
       "events": [
         "anchor-placed"
@@ -380,6 +547,22 @@
       "events": [],
       "config": []
     },
+    {
+      "name": "scroll-progress",
+      "category": "layout-measurement",
+      "description": "Page or element scroll progress as 0..1 attribute + CSS variable + event",
+      "attributes": [
+        "data-scroll-progress-active",
+        "data-scroll-progress"
+      ],
+      "events": [
+        "scroll-progress"
+      ],
+      "config": [
+        "data-scroll-progress-mode",
+        "data-scroll-container"
+      ]
+    },
     {
       "name": "drag-ghost",
       "category": "motion-positioning",
@@ -402,6 +585,41 @@
       ],
       "config": []
     },
+    {
+      "name": "draggable-list-item",
+      "category": "motion-positioning",
+      "description": "Pointer drag for list reordering; emits dnd-lift/drop-target-change/drop/drop-cancel",
+      "attributes": [
+        "data-draggable-list-item-lifting",
+        "data-draggable-list-item-id"
+      ],
+      "events": [
+        "dnd-lift",
+        "dnd-drop-target-change",
+        "dnd-drop",
+        "dnd-drop-cancel"
+      ],
+      "config": []
+    },
+    {
+      "name": "drop-target",
+      "category": "motion-positioning",
+      "description": "Declarative drop zone: hit-testing, accept-reject, drag-over feedback",
+      "attributes": [
+        "data-drop-target-active",
+        "data-drop-target-over",
+        "data-drop-target-rejected"
+      ],
+      "events": [
+        "drop-enter",
+        "drop-leave",
+        "drop-receive",
+        "drop-rejected"
+      ],
+      "config": [
+        "data-drop-target-accepts"
+      ]
+    },
     {
       "name": "inertia-drag",
       "category": "motion-positioning",
@@ -414,6 +632,22 @@
       ],
       "config": []
     },
+    {
+      "name": "layout-animation",
+      "category": "motion-positioning",
+      "description": "FLIP-style layout transition: animate from old to new bounds without explicit coordinates",
+      "attributes": [
+        "data-layout-animation-active"
+      ],
+      "events": [
+        "layout-animation-done"
+      ],
+      "config": [
+        "data-layout-animate-duration",
+        "data-layout-animate-easing",
+        "data-layout-animate-trigger"
+      ]
+    },
     {
       "name": "resizable",
       "category": "motion-positioning",
@@ -453,6 +687,23 @@
         "data-tossable-bounds"
       ]
     },
+    {
+      "name": "view-transition",
+      "category": "motion-positioning",
+      "description": "Wraps document.startViewTransition() for morph animations between DOM states",
+      "attributes": [
+        "data-view-transition-active"
+      ],
+      "events": [
+        "view-transition-start",
+        "view-transition-end"
+      ],
+      "config": [
+        "data-view-transition-name",
+        "data-view-transition-duration",
+        "data-view-transition-easing"
+      ]
+    },
     {
       "name": "glow-focus",
       "category": "visual-dynamics",
@@ -481,7 +732,9 @@
         "data-noise-texture-active"
       ],
       "events": [],
-      "config": []
+      "config": [
+        "data-noise-strength"
+      ]
     },
     {
       "name": "parallax",

package/traits/active-state.test.js

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

package/traits/anchor-positioning.js

@@ -1,10 +1,48 @@
+/**
+ * anchor-positioning — pin a host element to a named anchor.
+ *
+ * Native path (Chromium 125+, Safari 18.0+):
+ *   - Promotes the host into the top layer via `popover="manual"` +
+ *     `host.showPopover()` so it escapes any `overflow: hidden` ancestor.
+ *   - Names the anchor with `anchor-name: --anchor-{slug}` and points the
+ *     host at it with `position-anchor: --anchor-{slug}`.
+ *   - Lays out via `position-area`; the browser drives reflow on its own,
+ *     no JS scroll/resize loop needed.
+ *
+ * Fallback path (Firefox 129+ today, Safari < 18.0):
+ *   - Plain `position: fixed` + measured top/left from getBoundingClientRect.
+ *   - scroll (capture) + resize listeners drive re-layout.
+ *   - Mirrors the v0 behavior so the public attribute API is unchanged.
+ *
+ * `data-anchor-mode="native"|"fallback"` is reflected on the host so
+ * consumers and DevTools sessions can see which path actually ran.
+ */
+
 import { defineTrait } from './define.js';
 
+/**
+ * Feature-detect both halves of the API we depend on. Chrome 125+ and
+ * Safari 18.0+ pass both; Firefox 129's partial implementation typically
+ * fails the `position-area` half and lands on the fallback. Mirrors the
+ * detection used in core/anchor.js so the trait + the popover helper
+ * agree on which path ran.
+ */
+const supportsNative =
+  typeof CSS !== 'undefined' &&
+  (CSS.supports?.('anchor-name', '--x') ?? false) &&
+  (CSS.supports?.('position-area', 'bottom') ?? false);
+
+let anchorIdCounter = 0;
+
 export const anchorPositioning = defineTrait({
   name: 'anchor-positioning',
   category: 'layout-measurement',
   description: 'Positions relative to an anchor element',
-  attributes: ['data-anchor-positioning-placed', 'data-anchor-placement-actual'],
+  attributes: [
+    'data-anchor-positioning-placed',
+    'data-anchor-placement-actual',
+    'data-anchor-mode',
+  ],
   events: ['anchor-placed'],
   config: ['data-anchor', 'data-anchor-placement', 'data-anchor-gap'],
   setup({ host }) {
@@ -12,57 +50,172 @@ export const anchorPositioning = defineTrait({
     const placement = host.getAttribute('data-anchor-placement') || 'bottom';
     const gap = parseInt(host.getAttribute('data-anchor-gap'), 10) || 0;
 
-    function position() {
-      const anchor = document.querySelector(anchorSel) ||
-        document.getElementById(anchorSel);
-      if (!anchor) return;
-
-      const ar = anchor.getBoundingClientRect();
-      const hr = host.getBoundingClientRect();
-      const vw = window.innerWidth;
-      const vh = window.innerHeight;
-
-      let top, left;
-      let actual = placement;
-
-      if (placement.startsWith('bottom')) {
-        top = ar.bottom + gap;
-        left = ar.left + (ar.width - hr.width) / 2;
-        if (top + hr.height > vh) { top = ar.top - hr.height - gap; actual = 'top'; }
-      } else if (placement.startsWith('top')) {
-        top = ar.top - hr.height - gap;
-        left = ar.left + (ar.width - hr.width) / 2;
-        if (top < 0) { top = ar.bottom + gap; actual = 'bottom'; }
-      } else if (placement.startsWith('left')) {
-        top = ar.top + (ar.height - hr.height) / 2;
-        left = ar.left - hr.width - gap;
-        if (left < 0) { left = ar.right + gap; actual = 'right'; }
-      } else {
-        top = ar.top + (ar.height - hr.height) / 2;
-        left = ar.right + gap;
-        if (left + hr.width > vw) { left = ar.left - hr.width - gap; actual = 'left'; }
-      }
-
-      left = Math.max(0, Math.min(left, vw - hr.width));
-      top = Math.max(0, Math.min(top, vh - hr.height));
-
-      host.style.position = 'fixed';
-      host.style.top = `${top}px`;
-      host.style.left = `${left}px`;
-      host.setAttribute('data-anchor-positioning-placed', '');
-      host.setAttribute('data-anchor-placement-actual', actual);
-      host.dispatchEvent(new CustomEvent('anchor-placed', { bubbles: true, detail: { actual } }));
-    }
+    const anchor = resolveAnchor(anchorSel);
+    if (!anchor) return () => {};
 
-    position();
-    window.addEventListener('scroll', position, true);
-    window.addEventListener('resize', position);
-
-    return () => {
-      window.removeEventListener('scroll', position, true);
-      window.removeEventListener('resize', position);
-      host.removeAttribute('data-anchor-positioning-placed');
-      host.removeAttribute('data-anchor-placement-actual');
-    };
+    return supportsNative
+      ? setupNative({ host, anchor, placement, gap })
+      : setupFallback({ host, anchor, placement, gap });
   },
 });
+
+function resolveAnchor(sel) {
+  if (!sel) return null;
+  try {
+    return document.querySelector(sel) || document.getElementById(sel);
+  } catch (_) {
+    // Bare ids ("anchor-x" without a leading "#") throw on querySelector.
+    return document.getElementById(sel);
+  }
+}
+
+// ── Native path ─────────────────────────────────────────────────────────
+
+function setupNative({ host, anchor, placement, gap }) {
+  const name = `--anchor-${++anchorIdCounter}`;
+  const prevAnchorName = anchor.style.anchorName;
+  const prevPopover = host.getAttribute('popover');
+
+  // Tag the anchor + the host so the layout engine can wire them up.
+  anchor.style.anchorName = name;
+  host.style.position = 'fixed';
+  host.style.positionAnchor = name;
+  host.style.positionArea = placementToPositionArea(placement);
+  host.style.margin = placementToGapMargin(placement, gap);
+  // Clear any v0 fallback-leftover coordinates so they don't fight CSS.
+  host.style.top = '';
+  host.style.left = '';
+  // Let the browser flip across either axis when the requested edge clips.
+  host.style.positionTryFallbacks = 'flip-block, flip-inline, flip-block flip-inline';
+
+  // Promote into the top layer so overflow:hidden ancestors can't clip.
+  if (!prevPopover) host.setAttribute('popover', 'manual');
+  let didShow = false;
+  try {
+    host.showPopover();
+    didShow = true;
+  } catch (_) {
+    // Already-shown / unsupported in the test env — both are non-fatal.
+  }
+
+  host.setAttribute('data-anchor-mode', 'native');
+  host.setAttribute('data-anchor-positioning-placed', '');
+  host.setAttribute('data-anchor-placement-actual', placement);
+  host.dispatchEvent(new CustomEvent('anchor-placed', {
+    bubbles: true,
+    detail: { actual: placement, mode: 'native' },
+  }));
+
+  return () => {
+    anchor.style.anchorName = prevAnchorName;
+    host.style.positionAnchor = '';
+    host.style.positionArea = '';
+    host.style.positionTryFallbacks = '';
+    host.style.margin = '';
+    if (didShow) {
+      try { host.hidePopover(); } catch (_) { /* already-hidden / unsupported */ }
+    }
+    if (!prevPopover) host.removeAttribute('popover');
+    host.removeAttribute('data-anchor-mode');
+    host.removeAttribute('data-anchor-positioning-placed');
+    host.removeAttribute('data-anchor-placement-actual');
+  };
+}
+
+// ── Fallback path ───────────────────────────────────────────────────────
+
+function setupFallback({ host, anchor, placement, gap }) {
+  function position() {
+    const ar = anchor.getBoundingClientRect();
+    const hr = host.getBoundingClientRect();
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+
+    let top, left;
+    let actual = placement;
+
+    if (placement.startsWith('bottom')) {
+      top = ar.bottom + gap;
+      left = ar.left + (ar.width - hr.width) / 2;
+      if (top + hr.height > vh) { top = ar.top - hr.height - gap; actual = 'top'; }
+    } else if (placement.startsWith('top')) {
+      top = ar.top - hr.height - gap;
+      left = ar.left + (ar.width - hr.width) / 2;
+      if (top < 0) { top = ar.bottom + gap; actual = 'bottom'; }
+    } else if (placement.startsWith('left')) {
+      top = ar.top + (ar.height - hr.height) / 2;
+      left = ar.left - hr.width - gap;
+      if (left < 0) { left = ar.right + gap; actual = 'right'; }
+    } else {
+      top = ar.top + (ar.height - hr.height) / 2;
+      left = ar.right + gap;
+      if (left + hr.width > vw) { left = ar.left - hr.width - gap; actual = 'left'; }
+    }
+
+    left = Math.max(0, Math.min(left, vw - hr.width));
+    top = Math.max(0, Math.min(top, vh - hr.height));
+
+    host.style.position = 'fixed';
+    host.style.top = `${top}px`;
+    host.style.left = `${left}px`;
+    host.setAttribute('data-anchor-positioning-placed', '');
+    host.setAttribute('data-anchor-placement-actual', actual);
+    host.dispatchEvent(new CustomEvent('anchor-placed', {
+      bubbles: true,
+      detail: { actual, mode: 'fallback' },
+    }));
+  }
+
+  host.setAttribute('data-anchor-mode', 'fallback');
+  position();
+  window.addEventListener('scroll', position, true);
+  window.addEventListener('resize', position);
+
+  return () => {
+    window.removeEventListener('scroll', position, true);
+    window.removeEventListener('resize', position);
+    host.removeAttribute('data-anchor-mode');
+    host.removeAttribute('data-anchor-positioning-placed');
+    host.removeAttribute('data-anchor-placement-actual');
+  };
+}
+
+// ── Placement → CSS helpers ─────────────────────────────────────────────
+
+/**
+ * Map our placement vocabulary (top|bottom|left|right + -start|-end) to
+ * the CSS `position-area` keyword pair that produces equivalent layout.
+ *
+ * The bare cardinals span the cross-axis ("span-all") so the host
+ * centers; the -start / -end variants pin to the named edge.
+ */
+function placementToPositionArea(placement) {
+  switch (placement) {
+    case 'bottom':       return 'bottom span-all';
+    case 'bottom-start': return 'bottom span-right';
+    case 'bottom-end':   return 'bottom span-left';
+    case 'top':          return 'top span-all';
+    case 'top-start':    return 'top span-right';
+    case 'top-end':      return 'top span-left';
+    case 'left':         return 'left span-all';
+    case 'left-start':   return 'left span-bottom';
+    case 'left-end':     return 'left span-top';
+    case 'right':        return 'right span-all';
+    case 'right-start':  return 'right span-bottom';
+    case 'right-end':    return 'right span-top';
+    default:             return 'bottom span-all';
+  }
+}
+
+/**
+ * Apply gap on the main (anchor-adjacent) axis only — the cross-axis
+ * spans the anchor and shouldn't carry margin or alignment will drift.
+ */
+function placementToGapMargin(placement, gap) {
+  if (!gap) return '';
+  if (placement.startsWith('bottom')) return `${gap}px 0 0 0`;
+  if (placement.startsWith('top'))    return `0 0 ${gap}px 0`;
+  if (placement.startsWith('left'))   return `0 ${gap}px 0 0`;
+  if (placement.startsWith('right'))  return `0 0 0 ${gap}px`;
+  return `${gap}px`;
+}