@adia-ai/web-components 0.2.0 → 0.2.2

package/traits/_catalog.json

@@ -0,0 +1,509 @@
+{
+  "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,
+  "categories": [
+    "animation-feedback",
+    "audio-haptics-sensory",
+    "forms-data",
+    "input-interaction",
+    "interaction-delight",
+    "keyboard-navigation",
+    "layout-measurement",
+    "motion-positioning",
+    "visual-dynamics"
+  ],
+  "traits": [
+    {
+      "name": "fade-presence",
+      "category": "animation-feedback",
+      "description": "Enter/exit fade with lifecycle",
+      "attributes": [
+        "data-fade-presence-entering",
+        "data-fade-presence-exiting"
+      ],
+      "events": [
+        "fade-in-done",
+        "fade-out-done"
+      ],
+      "config": []
+    },
+    {
+      "name": "ripple",
+      "category": "animation-feedback",
+      "description": "Material-style press ripple effect",
+      "attributes": [
+        "data-ripple-active"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "scale-press",
+      "category": "animation-feedback",
+      "description": "Subtle scale transform on press",
+      "attributes": [
+        "data-scale-press-active"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "spring-animate",
+      "category": "animation-feedback",
+      "description": "Spring-based motion transitions",
+      "attributes": [
+        "data-spring-animate-active"
+      ],
+      "events": [],
+      "config": [
+        "data-spring-stiffness",
+        "data-spring-damping"
+      ]
+    },
+    {
+      "name": "tilt-hover",
+      "category": "animation-feedback",
+      "description": "Tilt based on pointer position",
+      "attributes": [
+        "data-tilt-hover-active"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "attention-pulse",
+      "category": "audio-haptics-sensory",
+      "description": "Periodic pulse to draw attention",
+      "attributes": [
+        "data-attention-pulse-active"
+      ],
+      "events": [],
+      "config": [
+        "data-pulse-interval"
+      ]
+    },
+    {
+      "name": "count-up",
+      "category": "audio-haptics-sensory",
+      "description": "Animated numeric transitions",
+      "attributes": [
+        "data-count-up-active"
+      ],
+      "events": [
+        "count-up-done"
+      ],
+      "config": [
+        "data-count-up-target",
+        "data-count-duration"
+      ]
+    },
+    {
+      "name": "haptic-feedback",
+      "category": "audio-haptics-sensory",
+      "description": "Vibration API feedback",
+      "attributes": [
+        "data-haptic-feedback-active"
+      ],
+      "events": [],
+      "config": [
+        "data-haptic-pattern"
+      ]
+    },
+    {
+      "name": "sound-feedback",
+      "category": "audio-haptics-sensory",
+      "description": "Synthesized tones via Web Audio API",
+      "attributes": [
+        "data-sound-feedback-active"
+      ],
+      "events": [],
+      "config": [
+        "data-sound-type"
+      ]
+    },
+    {
+      "name": "typewriter",
+      "category": "audio-haptics-sensory",
+      "description": "Animated text reveal character by character",
+      "attributes": [
+        "data-typewriter-active"
+      ],
+      "events": [
+        "typewriter-done"
+      ],
+      "config": [
+        "data-typewriter-speed"
+      ]
+    },
+    {
+      "name": "dirty-state",
+      "category": "forms-data",
+      "description": "Tracks modified vs initial value",
+      "attributes": [
+        "data-dirty-state-dirty",
+        "data-dirty-state-pristine"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "resettable",
+      "category": "forms-data",
+      "description": "Snaps the host value back to its initial value on form reset",
+      "attributes": [
+        "data-resettable-active"
+      ],
+      "events": [
+        "reset-applied"
+      ],
+      "config": []
+    },
+    {
+      "name": "validation",
+      "category": "forms-data",
+      "description": "Validation rules: required, minlength, pattern, email",
+      "attributes": [
+        "data-validation-invalid",
+        "data-validation-valid",
+        "data-validation-message"
+      ],
+      "events": [
+        "validated"
+      ],
+      "config": [
+        "data-validate"
+      ]
+    },
+    {
+      "name": "active-state",
+      "category": "input-interaction",
+      "description": "Tracks pointer-down / active interaction state",
+      "attributes": [
+        "data-active-state-active"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "focusable",
+      "category": "input-interaction",
+      "description": "Keyboard-only focus ring, ignores pointer focus",
+      "attributes": [
+        "data-focusable-keyboard"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "hoverable",
+      "category": "input-interaction",
+      "description": "Pointer hover enter/leave state tracking",
+      "attributes": [
+        "data-hoverable-hover"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "pressable",
+      "category": "input-interaction",
+      "description": "Normalizes click/tap/keyboard into a single \"press\" event",
+      "attributes": [
+        "data-pressable-pressed"
+      ],
+      "events": [
+        "press"
+      ],
+      "config": []
+    },
+    {
+      "name": "confetti",
+      "category": "interaction-delight",
+      "description": "Radial particle burst on press",
+      "attributes": [
+        "data-confetti-active"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "confetti-burst",
+      "category": "interaction-delight",
+      "description": "Upward fountain particle burst",
+      "attributes": [
+        "data-confetti-burst-active"
+      ],
+      "events": [
+        "confetti-burst-done"
+      ],
+      "config": []
+    },
+    {
+      "name": "magnetic-hover",
+      "category": "interaction-delight",
+      "description": "Element subtly follows cursor",
+      "attributes": [
+        "data-magnetic-hover-active"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "focus-trap",
+      "category": "keyboard-navigation",
+      "description": "Traps Tab/Shift+Tab within a container",
+      "attributes": [
+        "data-focus-trap-active"
+      ],
+      "events": [
+        "focus-trap-escape"
+      ],
+      "config": []
+    },
+    {
+      "name": "hotkey",
+      "category": "keyboard-navigation",
+      "description": "Global or scoped keyboard shortcuts",
+      "attributes": [],
+      "events": [
+        "hotkey"
+      ],
+      "config": [
+        "data-hotkey",
+        "data-hotkey-global"
+      ]
+    },
+    {
+      "name": "keyboard-nav",
+      "category": "keyboard-navigation",
+      "description": "Arrow keys, Enter, Escape — semantic navigation events",
+      "attributes": [],
+      "events": [
+        "nav-up",
+        "nav-down",
+        "nav-left",
+        "nav-right",
+        "nav-enter",
+        "nav-escape",
+        "nav-home",
+        "nav-end"
+      ],
+      "config": []
+    },
+    {
+      "name": "roving-tabindex",
+      "category": "keyboard-navigation",
+      "description": "Focus management within composite widgets",
+      "attributes": [],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "typeahead",
+      "category": "keyboard-navigation",
+      "description": "Incremental search within a collection",
+      "attributes": [
+        "data-typeahead-match"
+      ],
+      "events": [
+        "typeahead-match"
+      ],
+      "config": []
+    },
+    {
+      "name": "anchor-positioning",
+      "category": "layout-measurement",
+      "description": "Positions relative to an anchor element",
+      "attributes": [
+        "data-anchor-positioning-placed",
+        "data-anchor-placement-actual"
+      ],
+      "events": [
+        "anchor-placed"
+      ],
+      "config": [
+        "data-anchor",
+        "data-anchor-placement",
+        "data-anchor-gap"
+      ]
+    },
+    {
+      "name": "intersection-observer",
+      "category": "layout-measurement",
+      "description": "Visibility detection (viewport)",
+      "attributes": [
+        "data-intersection-visible",
+        "data-intersection-ratio"
+      ],
+      "events": [
+        "element-visible",
+        "element-hidden"
+      ],
+      "config": [
+        "data-intersection-threshold"
+      ]
+    },
+    {
+      "name": "portal",
+      "category": "layout-measurement",
+      "description": "Renders content in a different DOM root",
+      "attributes": [
+        "data-portal-active"
+      ],
+      "events": [],
+      "config": [
+        "data-portal-target"
+      ]
+    },
+    {
+      "name": "resize-observer",
+      "category": "layout-measurement",
+      "description": "Reacts to element size changes",
+      "attributes": [
+        "data-resize-observer-observed",
+        "data-resize-width",
+        "data-resize-height"
+      ],
+      "events": [
+        "element-resize"
+      ],
+      "config": []
+    },
+    {
+      "name": "scroll-lock",
+      "category": "layout-measurement",
+      "description": "Disables background scrolling",
+      "attributes": [
+        "data-scroll-lock-active"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "drag-ghost",
+      "category": "motion-positioning",
+      "description": "Ghost clone at origin during drag",
+      "attributes": [
+        "data-drag-ghost-active"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "draggable",
+      "category": "motion-positioning",
+      "description": "Pointer drag to reposition",
+      "attributes": [
+        "data-draggable-dragging"
+      ],
+      "events": [
+        "drag-end"
+      ],
+      "config": []
+    },
+    {
+      "name": "inertia-drag",
+      "category": "motion-positioning",
+      "description": "Momentum-based dragging, smooth deceleration",
+      "attributes": [
+        "data-inertia-drag-coasting"
+      ],
+      "events": [
+        "drag-end"
+      ],
+      "config": []
+    },
+    {
+      "name": "resizable",
+      "category": "motion-positioning",
+      "description": "Drag edges/corners to resize",
+      "attributes": [
+        "data-resizable-resizing",
+        "data-resizable-edge"
+      ],
+      "events": [
+        "resize-end"
+      ],
+      "config": []
+    },
+    {
+      "name": "snap-to-grid",
+      "category": "motion-positioning",
+      "description": "Snaps position to configurable grid",
+      "attributes": [
+        "data-snap-to-grid-snapped"
+      ],
+      "events": [],
+      "config": [
+        "data-snap-grid"
+      ]
+    },
+    {
+      "name": "tossable",
+      "category": "motion-positioning",
+      "description": "Flick with momentum + viewport bounce",
+      "attributes": [
+        "data-tossable-flying"
+      ],
+      "events": [
+        "toss-end"
+      ],
+      "config": [
+        "data-tossable-bounds"
+      ]
+    },
+    {
+      "name": "glow-focus",
+      "category": "visual-dynamics",
+      "description": "Animated pulsing glow on focus",
+      "attributes": [
+        "data-glow-focus-active"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "gradient-shift",
+      "category": "visual-dynamics",
+      "description": "Animated rainbow gradient backgrounds",
+      "attributes": [
+        "data-gradient-shift-active"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "noise-texture",
+      "category": "visual-dynamics",
+      "description": "Procedural grain overlay",
+      "attributes": [
+        "data-noise-texture-active"
+      ],
+      "events": [],
+      "config": []
+    },
+    {
+      "name": "parallax",
+      "category": "visual-dynamics",
+      "description": "Layered motion relative to pointer",
+      "attributes": [
+        "data-parallax-active"
+      ],
+      "events": [],
+      "config": [
+        "data-parallax-strength"
+      ]
+    },
+    {
+      "name": "shimmer-loading",
+      "category": "visual-dynamics",
+      "description": "Skeleton shimmer effect",
+      "attributes": [
+        "data-shimmer-loading-active"
+      ],
+      "events": [],
+      "config": []
+    }
+  ]
+}

package/traits/_motion.js

@@ -0,0 +1,57 @@
+/**
+ * Shared motion helpers — reduced-motion preference detection.
+ *
+ * Per WCAG 2.1 SC 2.3.3, autonomous motion (animations users didn't
+ * explicitly initiate) must respect `prefers-reduced-motion: reduce`.
+ * Traits that fire timer-driven or decorative animation should consult
+ * `prefersReducedMotion()` in their setup() and either bail or render
+ * a static fallback.
+ *
+ * User-initiated motion (drag, resize, toss, inertia) does NOT need
+ * this guard — those traits respond to direct user input and are not
+ * subject to the autonomous-animation rule.
+ */
+
+let cached = null;
+
+export function prefersReducedMotion() {
+  if (cached !== null) return cached;
+  if (typeof window === 'undefined' || !window.matchMedia) {
+    cached = false;
+    return cached;
+  }
+  try {
+    cached = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  } catch {
+    cached = false;
+  }
+  return cached;
+}
+
+/**
+ * Subscribe to reduced-motion changes — returns a cleanup fn.
+ * Useful when a trait wants to switch behavior live as the user toggles
+ * the OS preference.
+ */
+export function onReducedMotionChange(callback) {
+  if (typeof window === 'undefined' || !window.matchMedia) return () => {};
+  let mql;
+  try {
+    mql = window.matchMedia('(prefers-reduced-motion: reduce)');
+  } catch {
+    return () => {};
+  }
+  const handler = (e) => {
+    cached = e.matches;
+    callback(e.matches);
+  };
+  mql.addEventListener?.('change', handler);
+  return () => mql.removeEventListener?.('change', handler);
+}
+
+/**
+ * Test-only: reset the cached result so tests can mock matchMedia between cases.
+ */
+export function _resetMotionCache() {
+  cached = null;
+}

package/traits/_smoke.test.js

@@ -0,0 +1,111 @@
+/**
+ * Universal trait contract — runs against every trait imported from
+ * traits/index.js. Asserts schema integrity, attribute cleanup on
+ * disconnect, and idempotent connect/disconnect cycles.
+ *
+ * Per-trait behavior tests live in `<trait>.test.js` siblings.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import * as traits from './index.js';
+import { mountHost, connectTrait, expectValidSchema, resetDOM } from './_test-helpers.js';
+
+const KNOWN_CATEGORIES = new Set([
+  'input-interaction',
+  'keyboard-navigation',
+  'forms-data',
+  'layout-measurement',
+  'motion-positioning',
+  'animation-feedback',
+  'visual-dynamics',
+  'interaction-delight',
+  'audio-haptics-sensory',
+]);
+
+const ALL_TRAITS = Object.entries(traits).filter(([, fn]) => typeof fn === 'function' && fn.schema);
+
+describe('trait registry — universal contract', () => {
+  beforeEach(resetDOM);
+
+  it('exports at least 40 traits', () => {
+    expect(ALL_TRAITS.length).toBeGreaterThanOrEqual(40);
+  });
+
+  it('every trait declares a known category', () => {
+    for (const [exportName, trait] of ALL_TRAITS) {
+      expect(KNOWN_CATEGORIES.has(trait.schema.category), `${exportName} category=${trait.schema.category}`).toBe(true);
+    }
+  });
+
+  it('every trait has a non-empty description', () => {
+    for (const [exportName, trait] of ALL_TRAITS) {
+      expect(trait.schema.description, `${exportName} missing description`).toBeTruthy();
+      expect(trait.schema.description.length, `${exportName} description too short`).toBeGreaterThan(10);
+    }
+  });
+
+  it('every trait passes the schema-shape contract', () => {
+    for (const [, trait] of ALL_TRAITS) expectValidSchema(trait);
+  });
+
+  it('attribute, event, and config names use kebab-case', () => {
+    const KEBAB_OR_DATA = /^(?:data-)?[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+    for (const [exportName, trait] of ALL_TRAITS) {
+      for (const a of trait.schema.attributes) {
+        expect(KEBAB_OR_DATA.test(a), `${exportName} attribute "${a}" not kebab-case`).toBe(true);
+        expect(a.startsWith('data-'), `${exportName} attribute "${a}" must start with data-`).toBe(true);
+      }
+      for (const e of trait.schema.events) {
+        expect(KEBAB_OR_DATA.test(e), `${exportName} event "${e}" not kebab-case`).toBe(true);
+      }
+      for (const c of trait.schema.config) {
+        expect(c.startsWith('data-'), `${exportName} config "${c}" must start with data-`).toBe(true);
+      }
+    }
+  });
+
+  it('connect → disconnect leaves no managed attributes behind', () => {
+    for (const [exportName, trait] of ALL_TRAITS) {
+      const host = mountHost();
+      const inst = connectTrait(trait, host);
+      inst.disconnect(host);
+      for (const attr of trait.schema.attributes) {
+        expect(host.hasAttribute(attr), `${exportName} left "${attr}" after disconnect`).toBe(false);
+      }
+      host.remove();
+    }
+  });
+
+  it('connect → disconnect → connect again does not throw', () => {
+    for (const [exportName, trait] of ALL_TRAITS) {
+      const host = mountHost();
+      const inst1 = connectTrait(trait, host);
+      inst1.disconnect(host);
+      expect(() => {
+        const inst2 = connectTrait(trait, host);
+        inst2.disconnect(host);
+      }, `${exportName} reconnect threw`).not.toThrow();
+      host.remove();
+    }
+  });
+
+  it('two parallel instances on different hosts do not interfere', () => {
+    for (const [exportName, trait] of ALL_TRAITS) {
+      const a = mountHost();
+      const b = mountHost();
+      const instA = connectTrait(trait, a);
+      const instB = connectTrait(trait, b);
+      // Disconnect one — the other should still clean up correctly.
+      expect(() => instA.disconnect(a), `${exportName} disconnect-A threw`).not.toThrow();
+      expect(() => instB.disconnect(b), `${exportName} disconnect-B threw`).not.toThrow();
+      a.remove();
+      b.remove();
+    }
+  });
+
+  it('catalog count matches export count', async () => {
+    const mod = await import('./_catalog.json', { with: { type: 'json' } });
+    const catalog = mod.default || mod;
+    expect(catalog.count, `catalog says ${catalog.count}, exports has ${ALL_TRAITS.length}`).toBe(ALL_TRAITS.length);
+  });
+});