@adia-ai/web-components 0.2.1 → 0.2.2

package/README.md

@@ -57,8 +57,11 @@ web-components/
 │  gen-ui, a2ui-root) ship in the sibling `@adia-ai/web-modules`
 │  package as of 0.0.29 — see ADR-0012 for the three-tier rationale.
 │
-├── traits/         — 42 composable behaviors via defineTrait()
-│                     (pressable, focusTrap, confetti, resizable, …)
+├── traits/         — 41 composable behaviors via defineTrait() + the
+│                     <traits-host> wrapper for raw-HTML declarative
+│                     composition. Generated catalog at _catalog.json
+│                     drives the MCP get_traits tool + per-trait demo
+│                     pages. Full contract in docs/specs/traits.md.
 │
 ├── a2ui/           — deprecation shim for one release
 │   └── index.js            Re-exports @adia-ai/a2ui-utils with a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-utils.",
   "type": "module",
   "exports": {

package/traits/index.js

@@ -2,6 +2,11 @@
 // _catalog.json (generated from defineTrait() metadata). When adding a
 // trait, place it under its category header here, then run
 // `npm run build:traits` to refresh the catalog.
+//
+// Side-effect: the <traits-host> wrapper is auto-registered when this
+// barrel is imported, so consumers who use the trait library at all
+// also get raw-HTML declarative composition for free.
+import './traits-host.js';
 
 // input-interaction
 export { pressable } from './pressable.js';

package/traits/scroll-lock.test.js

@@ -10,9 +10,11 @@ describe('scroll-lock', () => {
 
   it('connect sets body overflow:hidden + active attribute', () => {
     const host = mountHost();
-    connectTrait(scrollLock, host);
+    const inst = connectTrait(scrollLock, host);
     expect(document.body.style.overflow).toBe('hidden');
     expect(host.hasAttribute('data-scroll-lock-active')).toBe(true);
+    // Balanced disconnect to keep the module-level lockCount honest for sibling tests.
+    inst.disconnect(host);
   });
 
   it('disconnect restores body overflow + clears attribute', () => {

package/traits/traits-host.js

@@ -0,0 +1,53 @@
+/**
+ * <traits-host traits="pressable scale-press ripple">
+ *   <div>raw markup with trait behaviors attached</div>
+ * </traits-host>
+ *
+ * Tiny pass-through wrapper that extends declarative trait composition
+ * to raw HTML. Without this element, only UIElement subclasses can read
+ * the `traits=` attribute. Wrap any markup in <traits-host> and the
+ * named traits attach to the wrapper itself — events bubble up from
+ * children, attribute toggles land on the wrapper, and the children
+ * render unaffected.
+ *
+ * The host uses `display: contents` so it does not introduce a layout
+ * box; the wrapped children participate in the parent's flex/grid
+ * exactly as if the wrapper were not there.
+ *
+ * Use this for:
+ *   - sprinkling `pressable` onto a custom button you don't want to
+ *     turn into a UIElement
+ *   - giving a `<dialog>` or `<details>` a `focus-trap` without a
+ *     wrapper component
+ *   - composing `magnetic-hover` + `tilt-hover` onto an existing
+ *     marketing CTA without rewriting it as a component
+ *
+ * For UIElement subclasses, prefer the bare attribute on the element
+ * itself: `<button-ui traits="ripple">…</button-ui>`. The wrapper is
+ * for cases where the host element is NOT a UIElement.
+ */
+
+import { UIElement } from '../core/element.js';
+
+class TraitsHost extends UIElement {
+  static template = () => null;
+
+  connected() {
+    // No-op — UIElement reads `traits` attribute and applies behavior.
+  }
+}
+
+if (typeof customElements !== 'undefined' && !customElements.get('traits-host')) {
+  customElements.define('traits-host', TraitsHost);
+}
+
+// One-shot stylesheet keeps the host out of the layout flow so children
+// render in the parent's box.
+if (typeof document !== 'undefined' && document.head && !document.querySelector('#adia-traits-host-style')) {
+  const style = document.createElement('style');
+  style.id = 'adia-traits-host-style';
+  style.textContent = 'traits-host { display: contents; }';
+  document.head.appendChild(style);
+}
+
+export { TraitsHost };

package/traits/traits-host.test.js

@@ -0,0 +1,73 @@
+/**
+ * <traits-host> behavior tests — focus on the wrapper-specific contract:
+ *  - children pass through visually (display: contents)
+ *  - declarative traits attach to the wrapper
+ *  - traits attribute swaps work the same as on UIElement subclasses
+ *  - events from children bubble up to the wrapper for trait capture
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import './traits-host.js';
+import './pressable.js';
+import './hoverable.js';
+import { resetDOM } from './_test-helpers.js';
+
+describe('<traits-host>', () => {
+  beforeEach(resetDOM);
+
+  it('is registered as a UIElement subclass', () => {
+    const ctor = customElements.get('traits-host');
+    expect(ctor).toBeTruthy();
+  });
+
+  it('declarative traits=" " attaches to the wrapper itself', () => {
+    document.body.innerHTML = '<traits-host traits="pressable"><div>Raw</div></traits-host>';
+    const host = document.body.firstElementChild;
+    host.dispatchEvent(new PointerEvent('pointerdown'));
+    expect(host.hasAttribute('data-pressable-pressed')).toBe(true);
+    host.dispatchEvent(new PointerEvent('pointerup'));
+    expect(host.hasAttribute('data-pressable-pressed')).toBe(false);
+  });
+
+  it('events from children bubble up so the trait captures them', () => {
+    document.body.innerHTML = '<traits-host traits="hoverable"><span class="inner">Hover</span></traits-host>';
+    const host = document.body.firstElementChild;
+    const inner = host.querySelector('.inner');
+    // Synthesize a pointerenter on the wrapper (DOM bubbling up from inner
+    // would also work but happy-dom doesn't always reflect that for hover).
+    host.dispatchEvent(new PointerEvent('pointerenter', { bubbles: true }));
+    expect(host.hasAttribute('data-hoverable-hover')).toBe(true);
+    host.dispatchEvent(new PointerEvent('pointerleave', { bubbles: true }));
+    expect(host.hasAttribute('data-hoverable-hover')).toBe(false);
+  });
+
+  it('changing traits attribute swaps the trait stack', () => {
+    document.body.innerHTML = '<traits-host traits="pressable"><div>x</div></traits-host>';
+    const host = document.body.firstElementChild;
+    host.dispatchEvent(new PointerEvent('pointerdown'));
+    expect(host.hasAttribute('data-pressable-pressed')).toBe(true);
+    host.dispatchEvent(new PointerEvent('pointerup'));
+
+    host.setAttribute('traits', 'hoverable');
+    host.dispatchEvent(new PointerEvent('pointerdown'));
+    expect(host.hasAttribute('data-pressable-pressed')).toBe(false);
+    host.dispatchEvent(new PointerEvent('pointerenter'));
+    expect(host.hasAttribute('data-hoverable-hover')).toBe(true);
+  });
+
+  it('removing the host cleans up trait attributes', () => {
+    document.body.innerHTML = '<traits-host traits="pressable"><div>x</div></traits-host>';
+    const host = document.body.firstElementChild;
+    host.dispatchEvent(new PointerEvent('pointerdown'));
+    expect(host.hasAttribute('data-pressable-pressed')).toBe(true);
+    host.remove();
+    expect(host.hasAttribute('data-pressable-pressed')).toBe(false);
+  });
+
+  it('with no traits attribute: pure pass-through, children render', () => {
+    document.body.innerHTML = '<traits-host><span class="x">child</span></traits-host>';
+    const host = document.body.firstElementChild;
+    expect(host.querySelector('.x')).toBeTruthy();
+    expect(host.querySelector('.x').textContent).toBe('child');
+  });
+});