@adia-ai/web-components 0.2.0 → 0.2.2

package/traits/define.js

@@ -2,12 +2,17 @@
  * defineTrait() — Factory for creating composable behavior traits.
  *
  * A trait is a reusable behavior package: event listeners, attribute management,
- * and cleanup — defined once, attached to any element.
+ * and cleanup — defined once, attached to any element. The trait file is the
+ * single source of truth: name, category, description, attributes, events,
+ * and config all live here, and the public catalog (a2ui-corpus retrieval/
+ * catalog.js) is generated from the live registry — never hand-curated.
  *
  *   import { defineTrait } from './define.js';
  *
  *   export const pressable = defineTrait({
  *     name: 'pressable',
+ *     category: 'input-interaction',
+ *     description: 'Normalizes click/tap/keyboard into a single "press" event',
  *     attributes: ['data-pressable-pressed'],
  *     events: ['press'],
  *     config: [],
@@ -30,12 +35,31 @@
 
 const registry = new Map();
 
+const KNOWN_CATEGORIES = new Set([
+  'input-interaction',
+  'keyboard-navigation',
+  'forms-data',
+  'layout-measurement',
+  'motion-positioning',
+  'animation-feedback',
+  'visual-dynamics',
+  'interaction-delight',
+  'audio-haptics-sensory',
+]);
+
 export function defineTrait(spec) {
   if (!spec.name) throw new Error('Trait requires a name');
   if (!spec.setup) throw new Error(`Trait "${spec.name}" requires a setup function`);
+  if (!spec.category) throw new Error(`Trait "${spec.name}" requires a category`);
+  if (!KNOWN_CATEGORIES.has(spec.category)) {
+    throw new Error(`Trait "${spec.name}" has unknown category "${spec.category}". Known: ${[...KNOWN_CATEGORIES].join(', ')}`);
+  }
+  if (!spec.description) throw new Error(`Trait "${spec.name}" requires a description`);
 
   const schema = Object.freeze({
     name: spec.name,
+    category: spec.category,
+    description: spec.description,
     attributes: Object.freeze(spec.attributes || []),
     events: Object.freeze(spec.events || []),
     config: Object.freeze(spec.config || []),
@@ -63,14 +87,30 @@ export function defineTrait(spec) {
   }
 
   factory.schema = schema;
-  registry.set(spec.name, schema);
+  registry.set(spec.name, factory);
   return factory;
 }
 
-export function getTraitSchema(name) {
+/**
+ * Look up a trait factory by its declared name.
+ * Returns null if no trait with that name has been imported yet.
+ *
+ * Used by UIElement to resolve declarative `<comp-ui traits="pressable …">`
+ * attributes — the named trait must have been imported somewhere in the
+ * app before the element is connected, otherwise the lookup misses.
+ */
+export function getTrait(name) {
   return registry.get(name) || null;
 }
 
+/**
+ * Look up a trait's frozen schema by name. Convenience wrapper over
+ * `getTrait(name)?.schema`.
+ */
+export function getTraitSchema(name) {
+  return registry.get(name)?.schema || null;
+}
+
 export function listTraits() {
   return [...registry.keys()];
 }

package/traits/dirty-state.js

@@ -2,6 +2,8 @@ import { defineTrait } from './define.js';
 
 export const dirtyState = defineTrait({
   name: 'dirty-state',
+  category: 'forms-data',
+  description: 'Tracks modified vs initial value',
   attributes: ['data-dirty-state-dirty', 'data-dirty-state-pristine'],
   events: [],
   config: [],

package/traits/dirty-state.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { dirtyState } from './dirty-state.js';
+import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+
+describe('dirty-state', () => {
+  beforeEach(resetDOM);
+
+  it('starts in pristine state', () => {
+    const host = mountHost('input', { value: 'initial' });
+    connectTrait(dirtyState, host);
+    expect(host.hasAttribute('data-dirty-state-pristine')).toBe(true);
+    expect(host.hasAttribute('data-dirty-state-dirty')).toBe(false);
+  });
+
+  it('input event with changed value flips to dirty', () => {
+    const host = mountHost('input', { value: 'initial' });
+    connectTrait(dirtyState, host);
+    host.value = 'modified';
+    host.dispatchEvent(new Event('input'));
+    expect(host.hasAttribute('data-dirty-state-dirty')).toBe(true);
+    expect(host.hasAttribute('data-dirty-state-pristine')).toBe(false);
+  });
+
+  it('reverting to initial value flips back to pristine', () => {
+    const host = mountHost('input', { value: 'initial' });
+    connectTrait(dirtyState, host);
+    host.value = 'modified';
+    host.dispatchEvent(new Event('input'));
+    expect(host.hasAttribute('data-dirty-state-dirty')).toBe(true);
+    host.value = 'initial';
+    host.dispatchEvent(new Event('input'));
+    expect(host.hasAttribute('data-dirty-state-pristine')).toBe(true);
+    expect(host.hasAttribute('data-dirty-state-dirty')).toBe(false);
+  });
+
+  it('disconnect clears both state attributes', () => {
+    const host = mountHost('input', { value: 'x' });
+    const inst = connectTrait(dirtyState, host);
+    host.value = 'changed';
+    host.dispatchEvent(new Event('input'));
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-dirty-state-dirty')).toBe(false);
+    expect(host.hasAttribute('data-dirty-state-pristine')).toBe(false);
+  });
+});

package/traits/drag-ghost.js

@@ -2,6 +2,8 @@ import { defineTrait } from './define.js';
 
 export const dragGhost = defineTrait({
   name: 'drag-ghost',
+  category: 'motion-positioning',
+  description: 'Ghost clone at origin during drag',
   attributes: ['data-drag-ghost-active'],
   events: [],
   config: [],

package/traits/drag-ghost.test.js

@@ -0,0 +1,19 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { dragGhost } from './drag-ghost.js';
+import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+
+describe('drag-ghost', () => {
+  beforeEach(resetDOM);
+
+  it('connect attaches without throwing', () => {
+    const host = mountHost();
+    expect(() => connectTrait(dragGhost, host)).not.toThrow();
+  });
+
+  it('disconnect clears the active attribute', () => {
+    const host = mountHost();
+    const inst = connectTrait(dragGhost, host);
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-drag-ghost-active')).toBe(false);
+  });
+});

package/traits/draggable.js

@@ -2,6 +2,8 @@ import { defineTrait } from './define.js';
 
 export const draggable = defineTrait({
   name: 'draggable',
+  category: 'motion-positioning',
+  description: 'Pointer drag to reposition',
   attributes: ['data-draggable-dragging'],
   events: ['drag-end'],
   config: [],

package/traits/draggable.test.js

@@ -0,0 +1,60 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { draggable } from './draggable.js';
+import { mountHost, connectTrait, spyEvent, resetDOM } from './_test-helpers.js';
+
+function pointer(host, type, x, y) {
+  const ev = new PointerEvent(type, { clientX: x, clientY: y, pointerId: 1, bubbles: true });
+  host.dispatchEvent(ev);
+}
+
+describe('draggable', () => {
+  beforeEach(resetDOM);
+
+  it('pointerdown sets data-draggable-dragging', () => {
+    const host = mountHost();
+    connectTrait(draggable, host);
+    pointer(host, 'pointerdown', 10, 10);
+    expect(host.hasAttribute('data-draggable-dragging')).toBe(true);
+  });
+
+  it('pointermove during drag updates translate', () => {
+    const host = mountHost();
+    connectTrait(draggable, host);
+    pointer(host, 'pointerdown', 10, 10);
+    pointer(host, 'pointermove', 30, 50);
+    expect(host.style.translate).toContain('20px');
+    expect(host.style.translate).toContain('40px');
+  });
+
+  it('pointerup fires drag-end with x,y in detail and clears dragging', () => {
+    const host = mountHost();
+    connectTrait(draggable, host);
+    const spy = spyEvent(host, 'drag-end');
+    pointer(host, 'pointerdown', 0, 0);
+    pointer(host, 'pointermove', 25, 75);
+    pointer(host, 'pointerup', 25, 75);
+    expect(host.hasAttribute('data-draggable-dragging')).toBe(false);
+    expect(spy.count).toBe(1);
+    expect(spy.last.x).toBe(25);
+    expect(spy.last.y).toBe(75);
+  });
+
+  it('respects [disabled] — no drag, no event', () => {
+    const host = mountHost('div', { disabled: '' });
+    connectTrait(draggable, host);
+    const spy = spyEvent(host, 'drag-end');
+    pointer(host, 'pointerdown', 0, 0);
+    pointer(host, 'pointermove', 50, 50);
+    pointer(host, 'pointerup', 50, 50);
+    expect(host.hasAttribute('data-draggable-dragging')).toBe(false);
+    expect(spy.count).toBe(0);
+  });
+
+  it('disconnect removes listeners + dragging attribute', () => {
+    const host = mountHost();
+    const inst = connectTrait(draggable, host);
+    pointer(host, 'pointerdown', 0, 0);
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-draggable-dragging')).toBe(false);
+  });
+});

package/traits/fade-presence.js

@@ -2,6 +2,8 @@ import { defineTrait } from './define.js';
 
 export const fadePresence = defineTrait({
   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: [],

package/traits/fade-presence.test.js

@@ -0,0 +1,20 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { fadePresence } from './fade-presence.js';
+import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+
+describe('fade-presence', () => {
+  beforeEach(resetDOM);
+
+  it('connect attaches without throwing', () => {
+    const host = mountHost();
+    expect(() => connectTrait(fadePresence, host)).not.toThrow();
+  });
+
+  it('disconnect clears managed attributes', () => {
+    const host = mountHost();
+    const inst = connectTrait(fadePresence, host);
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-fade-presence-entering')).toBe(false);
+    expect(host.hasAttribute('data-fade-presence-exiting')).toBe(false);
+  });
+});

package/traits/focus-trap.js

@@ -4,6 +4,8 @@ const FOCUSABLE_SELECTOR = 'a[href], [role="button"][tabindex], input:not([disab
 
 export const focusTrap = defineTrait({
   name: 'focus-trap',
+  category: 'keyboard-navigation',
+  description: 'Traps Tab/Shift+Tab within a container',
   attributes: ['data-focus-trap-active'],
   events: ['focus-trap-escape'],
   config: [],

package/traits/focus-trap.test.js

@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { focusTrap } from './focus-trap.js';
+import { mountHost, connectTrait, spyEvent, resetDOM } from './_test-helpers.js';
+
+function focusableChild(host, label) {
+  const btn = document.createElement('button');
+  btn.textContent = label;
+  host.appendChild(btn);
+  return btn;
+}
+
+describe('focus-trap', () => {
+  beforeEach(resetDOM);
+
+  it('connect sets data-focus-trap-active', () => {
+    const host = mountHost();
+    focusableChild(host, 'A');
+    focusableChild(host, 'B');
+    connectTrait(focusTrap, host);
+    expect(host.hasAttribute('data-focus-trap-active')).toBe(true);
+  });
+
+  it('Escape fires focus-trap-escape event', () => {
+    const host = mountHost();
+    focusableChild(host, 'A');
+    connectTrait(focusTrap, host);
+    const spy = spyEvent(host, 'focus-trap-escape');
+    host.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    expect(spy.count).toBeGreaterThanOrEqual(1);
+  });
+
+  it('disconnect clears attribute and stops listening', () => {
+    const host = mountHost();
+    focusableChild(host, 'A');
+    const inst = connectTrait(focusTrap, host);
+    const spy = spyEvent(host, 'focus-trap-escape');
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-focus-trap-active')).toBe(false);
+    host.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    expect(spy.count).toBe(0);
+  });
+});

package/traits/focusable.js

@@ -2,6 +2,8 @@ import { defineTrait } from './define.js';
 
 export const focusable = defineTrait({
   name: 'focusable',
+  category: 'input-interaction',
+  description: 'Keyboard-only focus ring, ignores pointer focus',
   attributes: ['data-focusable-keyboard'],
   events: [],
   config: [],

package/traits/focusable.test.js

@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { focusable } from './focusable.js';
+import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+
+describe('focusable', () => {
+  beforeEach(resetDOM);
+
+  it('keyboard focus → sets data-focusable-keyboard', () => {
+    const host = mountHost();
+    connectTrait(focusable, host);
+    host.dispatchEvent(new FocusEvent('focus'));
+    expect(host.hasAttribute('data-focusable-keyboard')).toBe(true);
+  });
+
+  it('mouse focus → does NOT set data-focusable-keyboard', () => {
+    const host = mountHost();
+    connectTrait(focusable, host);
+    host.dispatchEvent(new MouseEvent('mousedown'));
+    host.dispatchEvent(new FocusEvent('focus'));
+    expect(host.hasAttribute('data-focusable-keyboard')).toBe(false);
+  });
+
+  it('blur clears the attribute', () => {
+    const host = mountHost();
+    connectTrait(focusable, host);
+    host.dispatchEvent(new FocusEvent('focus'));
+    expect(host.hasAttribute('data-focusable-keyboard')).toBe(true);
+    host.dispatchEvent(new FocusEvent('blur'));
+    expect(host.hasAttribute('data-focusable-keyboard')).toBe(false);
+  });
+
+  it('mousedown→blur→keyboard-focus correctly distinguishes the second visit', () => {
+    const host = mountHost();
+    connectTrait(focusable, host);
+    // First visit via mouse
+    host.dispatchEvent(new MouseEvent('mousedown'));
+    host.dispatchEvent(new FocusEvent('focus'));
+    expect(host.hasAttribute('data-focusable-keyboard')).toBe(false);
+    host.dispatchEvent(new FocusEvent('blur'));
+    // Second visit via keyboard
+    host.dispatchEvent(new FocusEvent('focus'));
+    expect(host.hasAttribute('data-focusable-keyboard')).toBe(true);
+  });
+
+  it('disconnect clears attribute and removes listeners', () => {
+    const host = mountHost();
+    const inst = connectTrait(focusable, host);
+    host.dispatchEvent(new FocusEvent('focus'));
+    expect(host.hasAttribute('data-focusable-keyboard')).toBe(true);
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-focusable-keyboard')).toBe(false);
+  });
+});

package/traits/glow-focus.js

@@ -1,17 +1,22 @@
 import { defineTrait } from './define.js';
+import { prefersReducedMotion } from './_motion.js';
 
 export const glowFocus = defineTrait({
   name: 'glow-focus',
+  category: 'visual-dynamics',
+  description: 'Animated pulsing glow on focus',
   attributes: ['data-glow-focus-active'],
   events: [],
   config: [],
   setup({ host }) {
     let savedBoxShadow = '';
+    const reduced = prefersReducedMotion();
 
     function onFocus() {
       savedBoxShadow = host.style.boxShadow;
       host.style.boxShadow = '0 0 8px 2px rgba(59, 130, 246, 0.6)';
-      host.style.transition = 'box-shadow 200ms ease';
+      // Skip the easing under reduced-motion — instant on/off.
+      host.style.transition = reduced ? '' : 'box-shadow 200ms ease';
       host.setAttribute('data-glow-focus-active', '');
     }
 

package/traits/glow-focus.test.js

@@ -0,0 +1,31 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { glowFocus } from './glow-focus.js';
+import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+
+describe('glow-focus', () => {
+  beforeEach(resetDOM);
+
+  it('focus sets data-glow-focus-active and applies box-shadow', () => {
+    const host = mountHost();
+    connectTrait(glowFocus, host);
+    host.dispatchEvent(new FocusEvent('focus'));
+    expect(host.hasAttribute('data-glow-focus-active')).toBe(true);
+    expect(host.style.boxShadow).toContain('rgba(59, 130, 246');
+  });
+
+  it('blur clears active + restores box-shadow', () => {
+    const host = mountHost();
+    connectTrait(glowFocus, host);
+    host.dispatchEvent(new FocusEvent('focus'));
+    host.dispatchEvent(new FocusEvent('blur'));
+    expect(host.hasAttribute('data-glow-focus-active')).toBe(false);
+  });
+
+  it('disconnect mid-focus clears active', () => {
+    const host = mountHost();
+    const inst = connectTrait(glowFocus, host);
+    host.dispatchEvent(new FocusEvent('focus'));
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-glow-focus-active')).toBe(false);
+  });
+});

package/traits/gradient-shift.js

@@ -1,11 +1,20 @@
 import { defineTrait } from './define.js';
+import { prefersReducedMotion } from './_motion.js';
 
 export const gradientShift = defineTrait({
   name: 'gradient-shift',
+  category: 'visual-dynamics',
+  description: 'Animated rainbow gradient backgrounds',
   attributes: ['data-gradient-shift-active'],
   events: [],
   config: [],
   setup({ host }) {
+    // Reduced-motion: leave the gradient static instead of animating it.
+    if (prefersReducedMotion()) {
+      host.setAttribute('data-gradient-shift-active', '');
+      return () => host.removeAttribute('data-gradient-shift-active');
+    }
+
     const keyframeName = `adia-gradient-${Math.random().toString(36).slice(2, 8)}`;
 
     const style = document.createElement('style');

package/traits/gradient-shift.test.js

@@ -0,0 +1,22 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { gradientShift } from './gradient-shift.js';
+import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+
+describe('gradient-shift', () => {
+  beforeEach(resetDOM);
+
+  it('connect sets data-gradient-shift-active', () => {
+    const host = mountHost();
+    connectTrait(gradientShift, host);
+    expect(host.hasAttribute('data-gradient-shift-active')).toBe(true);
+  });
+
+  it('disconnect clears active + reverts inline styles', () => {
+    const host = mountHost();
+    const inst = connectTrait(gradientShift, host);
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-gradient-shift-active')).toBe(false);
+    expect(host.style.animation).toBe('');
+    expect(host.style.backgroundSize).toBe('');
+  });
+});

package/traits/haptic-feedback.js

@@ -2,6 +2,8 @@ import { defineTrait } from './define.js';
 
 export const hapticFeedback = defineTrait({
   name: 'haptic-feedback',
+  category: 'audio-haptics-sensory',
+  description: 'Vibration API feedback',
   attributes: ['data-haptic-feedback-active'],
   events: [],
   config: ['data-haptic-pattern'],

package/traits/haptic-feedback.test.js

@@ -0,0 +1,52 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { hapticFeedback } from './haptic-feedback.js';
+import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+
+describe('haptic-feedback', () => {
+  let originalVibrate;
+
+  beforeEach(() => {
+    resetDOM();
+    originalVibrate = navigator.vibrate;
+  });
+
+  afterEach(() => {
+    if (originalVibrate) navigator.vibrate = originalVibrate;
+    else delete navigator.vibrate;
+  });
+
+  it('without navigator.vibrate: no-op cleanup, no crash', () => {
+    delete navigator.vibrate;
+    const host = mountHost();
+    expect(() => connectTrait(hapticFeedback, host)).not.toThrow();
+  });
+
+  it('with navigator.vibrate: press fires vibrate with parsed pattern', () => {
+    const vibrate = vi.fn();
+    navigator.vibrate = vibrate;
+    const host = mountHost('div', { 'data-haptic-pattern': '20,10,20' });
+    connectTrait(hapticFeedback, host);
+    expect(host.hasAttribute('data-haptic-feedback-active')).toBe(true);
+    host.dispatchEvent(new CustomEvent('press', { bubbles: true }));
+    expect(vibrate).toHaveBeenCalledWith([20, 10, 20]);
+  });
+
+  it('default pattern is [10] when no data-haptic-pattern set', () => {
+    const vibrate = vi.fn();
+    navigator.vibrate = vibrate;
+    const host = mountHost();
+    connectTrait(hapticFeedback, host);
+    host.dispatchEvent(new CustomEvent('press', { bubbles: true }));
+    expect(vibrate).toHaveBeenCalledWith([10]);
+  });
+
+  it('disconnect removes the press listener', () => {
+    const vibrate = vi.fn();
+    navigator.vibrate = vibrate;
+    const host = mountHost();
+    const inst = connectTrait(hapticFeedback, host);
+    inst.disconnect(host);
+    host.dispatchEvent(new CustomEvent('press', { bubbles: true }));
+    expect(vibrate).not.toHaveBeenCalled();
+  });
+});

package/traits/hotkey.js

@@ -32,6 +32,8 @@ function matchesCombo(e, combo) {
 
 export const hotkey = defineTrait({
   name: 'hotkey',
+  category: 'keyboard-navigation',
+  description: 'Global or scoped keyboard shortcuts',
   attributes: [],
   events: ['hotkey'],
   config: ['data-hotkey', 'data-hotkey-global'],

package/traits/hotkey.test.js

@@ -0,0 +1,61 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { hotkey } from './hotkey.js';
+import { mountHost, connectTrait, spyEvent, resetDOM } from './_test-helpers.js';
+
+describe('hotkey', () => {
+  beforeEach(resetDOM);
+
+  it('fires "hotkey" event on matching combo', () => {
+    const host = mountHost('div', { 'data-hotkey': 'ctrl+k' });
+    connectTrait(hotkey, host);
+    const spy = spyEvent(host, 'hotkey');
+    host.dispatchEvent(new KeyboardEvent('keydown', { key: 'k', ctrlKey: true }));
+    expect(spy.count).toBe(1);
+    expect(spy.last.combo).toBe('ctrl+k');
+  });
+
+  it('does not fire on non-matching combo', () => {
+    const host = mountHost('div', { 'data-hotkey': 'ctrl+k' });
+    connectTrait(hotkey, host);
+    const spy = spyEvent(host, 'hotkey');
+    host.dispatchEvent(new KeyboardEvent('keydown', { key: 'j', ctrlKey: true }));
+    host.dispatchEvent(new KeyboardEvent('keydown', { key: 'k' }));
+    host.dispatchEvent(new KeyboardEvent('keydown', { key: 'k', altKey: true }));
+    expect(spy.count).toBe(0);
+  });
+
+  it('shift modifier required when declared', () => {
+    const host = mountHost('div', { 'data-hotkey': 'shift+a' });
+    connectTrait(hotkey, host);
+    const spy = spyEvent(host, 'hotkey');
+    host.dispatchEvent(new KeyboardEvent('keydown', { key: 'a' }));
+    expect(spy.count).toBe(0);
+    host.dispatchEvent(new KeyboardEvent('keydown', { key: 'a', shiftKey: true }));
+    expect(spy.count).toBe(1);
+  });
+
+  it('global mode listens on document', () => {
+    const host = mountHost('div', { 'data-hotkey': 'ctrl+/', 'data-hotkey-global': '' });
+    connectTrait(hotkey, host);
+    const spy = spyEvent(host, 'hotkey');
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: '/', ctrlKey: true }));
+    expect(spy.count).toBe(1);
+  });
+
+  it('non-global mode does not listen on document', () => {
+    const host = mountHost('div', { 'data-hotkey': 'ctrl+/' });
+    connectTrait(hotkey, host);
+    const spy = spyEvent(host, 'hotkey');
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: '/', ctrlKey: true }));
+    expect(spy.count).toBe(0);
+  });
+
+  it('disconnect removes the keydown listener', () => {
+    const host = mountHost('div', { 'data-hotkey': 'ctrl+k', 'data-hotkey-global': '' });
+    const inst = connectTrait(hotkey, host);
+    const spy = spyEvent(host, 'hotkey');
+    inst.disconnect(host);
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'k', ctrlKey: true }));
+    expect(spy.count).toBe(0);
+  });
+});

package/traits/hoverable.js

@@ -2,6 +2,8 @@ import { defineTrait } from './define.js';
 
 export const hoverable = defineTrait({
   name: 'hoverable',
+  category: 'input-interaction',
+  description: 'Pointer hover enter/leave state tracking',
   attributes: ['data-hoverable-hover'],
   events: [],
   config: [],

package/traits/hoverable.test.js

@@ -0,0 +1,24 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { hoverable } from './hoverable.js';
+import { mountHost, connectTrait, resetDOM } from './_test-helpers.js';
+
+describe('hoverable', () => {
+  beforeEach(resetDOM);
+
+  it('pointerenter sets data-hoverable-hover; pointerleave clears it', () => {
+    const host = mountHost();
+    connectTrait(hoverable, host);
+    host.dispatchEvent(new PointerEvent('pointerenter'));
+    expect(host.hasAttribute('data-hoverable-hover')).toBe(true);
+    host.dispatchEvent(new PointerEvent('pointerleave'));
+    expect(host.hasAttribute('data-hoverable-hover')).toBe(false);
+  });
+
+  it('disconnect clears attribute even mid-hover', () => {
+    const host = mountHost();
+    const inst = connectTrait(hoverable, host);
+    host.dispatchEvent(new PointerEvent('pointerenter'));
+    inst.disconnect(host);
+    expect(host.hasAttribute('data-hoverable-hover')).toBe(false);
+  });
+});