@adia-ai/web-components 0.4.5 → 0.4.7

package/USAGE.md

@@ -0,0 +1,604 @@
+# Using `@adia-ai/web-components` — Consumer Guide
+
+The complete reference for engineers and agents **integrating** AdiaUI into an app. For authoring new primitives (contributing to the library), see [`README.md`](./README.md) § "Authoring a primitive".
+
+> This document answers the five most-common questions consumers ask. If something here is wrong, surprising, or missing, that's a bug — open an issue with the surface it describes.
+
+---
+
+## Contents
+
+1. [Install](#install)
+2. [The mental model](#the-mental-model)
+3. [Property reactivity (signal-backed)](#property-reactivity-signal-backed)
+4. [Property binding patterns (templates / framework integration)](#property-binding-patterns)
+5. [Event contract — `CustomEvent` with `detail`](#event-contract)
+6. [Form participation — `UIFormElement` + `ElementInternals`](#form-participation)
+7. [Lifecycle — `connected` / `render` / `updated` / `disconnected`](#lifecycle)
+8. [Theming, density, size](#theming-density-size)
+9. [Registration — auto vs explicit](#registration--auto-vs-explicit)
+10. [TypeScript](#typescript)
+11. [Anti-patterns](#anti-patterns)
+
+---
+
+## Install
+
+```bash
+npm install @adia-ai/web-components
+```
+
+Pair with [`@adia-ai/web-modules`](../web-modules) for composite shells (admin / chat / editor / simple / theme):
+
+```bash
+npm install @adia-ai/web-components @adia-ai/web-modules
+```
+
+### Importing
+
+The package is ESM-only — works under any modern bundler (Vite, esbuild, webpack 5+, Rollup) or plain `<script type="module">`.
+
+```js
+// Everything — registers every *-ui tag (95 primitives)
+import '@adia-ai/web-components';
+import '@adia-ai/web-components/css';
+
+// Or per-component for tree-shaking-conscious bundles
+import '@adia-ai/web-components/components/button';
+import '@adia-ai/web-components/components/button.css';
+```
+
+Subpath exports also available:
+
+```js
+// Core utilities — signals, templating, base classes
+import { signal, computed, effect, html, UIElement, UIFormElement } from '@adia-ai/web-components/core';
+
+// Traits — composable behavior decorators
+import '@adia-ai/web-components/traits';
+```
+
+---
+
+## The mental model
+
+Every AdiaUI primitive is a **standard light-DOM custom element**. There's no shadow DOM, no compiler, no framework — just `customElements.define()` extending a small `UIElement` base class. The base class wires a signal-backed property system on top.
+
+The contract every primitive obeys:
+
+| Surface | What it is | How to use |
+|---|---|---|
+| **Properties** | Reactive — every prop in `static properties` is backed by a signal. Setting `el.prop = v` triggers a re-render. | `slider.value = 75` |
+| **Attributes** | Mirror of properties (where `reflect: true`). Setting `[attr]` round-trips through the property setter. | `<slider-ui value="50">` |
+| **Events** | `CustomEvent` with typed `detail` payload. Bubbling unless noted otherwise. | `slider.addEventListener('change', e => e.detail.value)` |
+| **Slots** | Light-DOM children projected by attribute selectors (`:scope > [slot="icon"]`). No `<slot>` element. | `<card-ui><span slot="heading">Title</span></card-ui>` |
+
+This is the entire surface. There are no magic helpers; no proprietary state-management; no compiler. If you know vanilla web components + standard DOM, you know AdiaUI.
+
+---
+
+## Property reactivity (signal-backed)
+
+Every property declared in a primitive's `static properties` map is **signal-backed**. The setter mutates an internal `signal()`; the host's render effect subscribes to all signals and re-runs on every property change. So:
+
+```js
+const slider = document.querySelector('slider-ui');
+
+slider.value = 75;      // thumb moves to 75%, readout updates, aria-valuenow reflects
+slider.value = 10;      // thumb moves to 10%
+slider.disabled = true; // [disabled] reflects, click handlers no-op
+```
+
+This works for **every primitive**. There's no "is this prop reactive?" question — they all are.
+
+### Attributes round-trip
+
+Setting an attribute also propagates. `attributeChangedCallback` writes back into the property setter, which mutates the signal, which fires the render effect:
+
+```js
+slider.setAttribute('value', '25');   // same effect as slider.value = 25
+```
+
+This means you can drive a primitive from either side. Whatever your tooling sets — properties or attributes — works.
+
+### Why this matters
+
+Consumers sometimes assume that property changes only update the DOM if explicitly subscribed to via `attributeChangedCallback`. **That's not the case here.** The signal-backed property system means every property is reactive by default, with zero per-component opt-in. If you set a property and the DOM doesn't update, it's a bug in the primitive, not a missing subscription on your side.
+
+---
+
+## Property binding patterns
+
+When wiring a primitive's property to external state (your own signals, framework state, RxJS observables, etc.), the binding pattern matters. **An eagerly-evaluated value snapshot is one-shot**, not reactive.
+
+### Using the built-in `html` template
+
+The package ships its own lightweight template tag at `@adia-ai/web-components/core`. It detects signals and functions as bound values and wraps them in effects:
+
+```js
+import { html, signal, stamp } from '@adia-ai/web-components/core';
+
+const minL = signal(0.5);
+
+// ✅ Reactive — signal passed directly. Re-fires on every minL.value mutation.
+const tpl1 = html`<slider-ui .value=${minL} min="0" max="1" step="0.01"></slider-ui>`;
+
+// ✅ Reactive with transform — function-as-value. Function re-runs on dependency change.
+const tpl2 = html`<slider-ui .value=${() => minL.value * 100} min="0" max="100"></slider-ui>`;
+
+// ❌ NON-REACTIVE — eagerly evaluated. Snapshots at render time only.
+const tpl3 = html`<slider-ui .value=${minL.value * 100} min="0" max="100"></slider-ui>`;
+//                              ^^^^^^^^^^^^^^^^^^^^^^^^
+//                              evaluates to a number now; nothing to subscribe to
+```
+
+The `.prop=` syntax sets the JS property (not the attribute). The `attr=` syntax sets an attribute. Both round-trip through the signal-backed setter, so either works for reactive updates from your side.
+
+### Using React, Lit, Vue, Svelte, etc.
+
+When the binding system isn't AdiaUI's `html` tag, the rule generalizes:
+
+**Set the primitive's property inside whatever effect/watcher hook your framework provides.** The property setter mutates the signal, the host re-renders. Don't try to "bind" the value via attributes alone — properties are the reactive path.
+
+```jsx
+// React example
+function MinLSlider({ minL, onMinLChange }) {
+  const ref = useRef(null);
+  useEffect(() => {
+    if (ref.current) ref.current.value = minL * 100;
+  }, [minL]);
+  return <slider-ui ref={ref} min="0" max="100" onChange={e => onMinLChange(e.detail.value / 100)} />;
+}
+```
+
+```html
+<!-- Lit example -->
+<slider-ui .value=${this.minL * 100} @change=${e => this.minL = e.detail.value / 100}></slider-ui>
+```
+
+```html
+<!-- Vue example -->
+<slider-ui :value="minL * 100" @change="onMinLChange($event.detail.value / 100)"></slider-ui>
+```
+
+```svelte
+<!-- Svelte example -->
+<slider-ui value={minL * 100} on:change={e => minL = e.detail.value / 100}></slider-ui>
+```
+
+### The eager-evaluation trap
+
+Reported real-world bug: a consumer wrote `.value=${signal.value * 100}` and reported "the slider doesn't move on undo." The slider IS reactive; the binding pattern wasn't. `signal.value * 100` evaluates eagerly to a number; the template system never sees the signal, so it can't subscribe.
+
+**Fix:** pass `${signal}` (signal direct) or `${() => signal.value * 100}` (function as value). Both get effect-wrapped.
+
+---
+
+## Event contract
+
+Every interactive primitive emits **`CustomEvent` with a `detail` payload**. Since v0.4.5, this is uniform across all 17 form-bearing primitives.
+
+| Event | Fires on | Detail shape |
+|---|---|---|
+| `change` | Value commit (blur, drag end, keystroke commit) | `{ value }` or `{ value, checked }` for boolean primitives |
+| `input` | Every value tick (typing, dragging) | `{ value }` |
+| `submit` | Enter without shift in `<textarea-ui>` | (none — `event.preventDefault()` to suppress form submission) |
+| Component-specific | See per-component yaml | Per-component detail |
+
+### Listening
+
+```js
+// Typed payload (canonical)
+slider.addEventListener('change', (e) => {
+  console.log(e.detail.value);    // canonical reading path
+});
+
+// Untyped (backwards-compatible — `this.value = v` runs before dispatch)
+slider.addEventListener('change', (e) => {
+  console.log(e.target.value);    // also valid
+});
+```
+
+Both paths return the same value. Pick whichever your tooling makes ergonomic.
+
+### Value-semantic vs boolean-semantic
+
+| Class | Components | Detail |
+|---|---|---|
+| Value-semantic | input, select, slider, textarea, range, rating, search, otp-input, calendar-picker | `{ value }` |
+| Boolean-semantic | switch, check, radio, option-card | `{ value, checked }` |
+| Special | upload | `{ value, files }` |
+
+For boolean primitives, `value` is the form-submission string ("on" by default; the form value attribute if set), and `checked` is the actual checked state.
+
+### Component-specific events
+
+Some primitives emit named events beyond `change`/`input`:
+
+- `<select-ui>` — emits `action` for option-callbacks with `detail.action`
+- `<search-ui>` — emits `search` after debounce with `detail.value`
+- `<chat-composer>` — emits `composer-submit` on Enter with `detail.value`
+- `<color-picker-ui>` — emits multiple typed events (`input`, `change`, `format-change`) with structured detail
+
+Each primitive's yaml lists its complete event surface. Live demos at `https://ui-kit.exe.xyz/site/components/<name>`.
+
+### Bubbling
+
+All standard events bubble. Internal-routing collisions (e.g. a trait listening for an event then re-emitting one with the same name) are avoided by name discipline — see the `event-name-collision` memory entry for the lesson.
+
+---
+
+## Form participation
+
+15 primitives extend `UIFormElement` and participate in standard forms via `ElementInternals`:
+
+```
+input, select, slider, switch, segmented, check, radio, textarea,
+range, color-picker, rating, option-card, search, otp-input, code
+```
+
+They behave like native form controls:
+
+```html
+<form id="settings">
+  <input-ui name="username" type="text" value="alice"></input-ui>
+  <select-ui name="theme" value="ocean">…</select-ui>
+  <slider-ui name="density" value="50" min="0" max="100"></slider-ui>
+  <switch-ui name="notifications" checked></switch-ui>
+  <button-ui type="submit" text="Save"></button-ui>
+</form>
+```
+
+```js
+const form = document.getElementById('settings');
+const data = new FormData(form);
+// → { username: "alice", theme: "ocean", density: "50", notifications: "on" }
+```
+
+### Validation
+
+The full validation surface from native form controls works:
+
+```js
+input.checkValidity();        // boolean
+input.reportValidity();       // boolean + shows error UI
+input.setInvalid('Custom');   // mark invalid with custom message
+input.setValid();             // clear error state
+input.validity;               // ValidityState — { valid, valueMissing, patternMismatch, ... }
+input.validationMessage;      // localized error message
+input.willValidate;           // boolean
+```
+
+Constraint attributes (`required`, `pattern`, `minlength`, `maxlength`) work natively. CSS pseudo-classes (`:valid`, `:invalid`, `:required`, `:disabled`) work in your own CSS without any opt-in.
+
+### Custom validation timing
+
+`UIFormElement` validates **on blur if dirty** and **on form reset**. Override the timing via:
+
+```js
+const input = document.querySelector('input-ui');
+input.addEventListener('blur', () => {
+  if (!input.value.includes('@')) {
+    input.setInvalid('Must be an email');
+  } else {
+    input.setValid();
+  }
+});
+```
+
+### Form events
+
+Submit events bubble normally:
+
+```js
+form.addEventListener('submit', (e) => {
+  e.preventDefault();
+  const data = new FormData(form);
+  fetch('/api/save', { method: 'POST', body: data });
+});
+```
+
+---
+
+## Lifecycle
+
+`UIElement` exposes four overridable lifecycle methods. Defaults are no-ops. Override what you need:
+
+```js
+import { UIElement } from '@adia-ai/web-components/core';
+
+class MyWidget extends UIElement {
+  static properties = {
+    label: { type: String, default: '' },
+  };
+
+  #onKeydown = (e) => {       // stable arrow field — required for remove
+    if (e.key === 'Escape') this.label = '';
+  };
+
+  connected() {
+    // Called once per insertion.
+    // Set up listeners on document / external targets here.
+    document.addEventListener('keydown', this.#onKeydown);
+  }
+
+  render() {
+    // Called every time any property signal mutates.
+    // Update internal DOM here. Reading `this.foo` subscribes the host's
+    // render effect to that signal.
+    this.textContent = this.label || 'Empty';
+  }
+
+  updated(changed) {
+    // Called after `render()`.
+    // `changed` is a Map<propName, oldValue> for this tick.
+    if (changed.has('label')) {
+      this.dispatchEvent(new CustomEvent('label-change', {
+        bubbles: true, detail: { value: this.label }
+      }));
+    }
+  }
+
+  disconnected() {
+    // Called once per removal.
+    // Clean up listeners + intervals + observers here.
+    document.removeEventListener('keydown', this.#onKeydown);
+  }
+}
+
+customElements.define('my-widget', MyWidget);
+```
+
+### Why the `#field` arrow pattern
+
+`addEventListener('event', fn)` and `removeEventListener('event', fn)` only match when `fn` is the same reference. Inline arrows allocate a fresh closure every call, so the remove never fires:
+
+```js
+// ❌ Wrong — different reference each call
+connected()    { document.addEventListener('click', (e) => this.foo()); }
+disconnected() { document.removeEventListener('click', (e) => this.foo()); }  // doesn't remove
+
+// ✅ Correct — stable reference
+#onClick = (e) => this.foo();
+connected()    { document.addEventListener('click', this.#onClick); }
+disconnected() { document.removeEventListener('click', this.#onClick); }
+```
+
+The same applies to `bind()` — call it once in the constructor or use a field, not at the listener site.
+
+### Order of operations
+
+1. `constructor()` — `installProps()` defines reactive getters/setters from `static properties`
+2. Element inserted into DOM → `connectedCallback()` fires
+3. `connected()` (the overridable hook) runs in `untracked()` so reads don't subscribe outer effects
+4. Host's main render effect installs: subscribes to all property signals, calls `template()` + `render()`
+5. On any property change: effect re-runs, re-stamps template, calls `render()` then `updated(changed)`
+6. Element removed → `disconnectedCallback()` fires → `disconnected()` (overridable)
+
+---
+
+## Theming, density, size
+
+AdiaUI is parametric. Three attributes drive global appearance:
+
+```html
+<div data-theme="ocean" density="compact" size="sm">
+  <!-- all descendants re-theme / re-densify / re-scale -->
+</div>
+```
+
+| Attribute | Values | Effect |
+|---|---|---|
+| `[data-theme]` | `default`, `ocean`, `forest`, `sunset`, `lavender`, `rose`, `slate`, `midnight` | Swaps the OKLCH color ramp |
+| `[density]` | `compact` (0.85×), `spacious` (1.15×) | Multiplies `--a-density` token |
+| `[size]` | `sm`, `md`, `lg` | Shifts typescale + component dimensions |
+| `[radius]` | `sharp` (0), `rounded` (1), `round` (2) | Multiplies `--a-radius-k` token |
+
+Each is a CSS-variable override; no class toggles, no re-imports. Set on any ancestor → applies to that subtree.
+
+For a control surface to let users change these at runtime, use [`<theme-panel>`](https://ui-kit.exe.xyz/site/components/theme-panel) from `@adia-ai/web-modules/theme`.
+
+---
+
+## Registration — auto vs explicit
+
+### Auto-register (default)
+
+Importing a primitive's `.js` file immediately runs `customElements.define('button-ui', UIButton)`. This is the canonical path — once imported, the tag works everywhere:
+
+```js
+import '@adia-ai/web-components/components/button';
+// <button-ui> is now usable in any markup
+```
+
+The `sideEffects` field in `package.json` keeps this path tree-shake-safe.
+
+### Conflict-safe registration (`defineIfFree`)
+
+Multiple packages may try to register the same tag (e.g. when a host page imports the AdiaUI bundle AND a downstream consumer imports per-component subpaths). Native `customElements.define` throws `NotSupportedError` on duplicate registration. The package ships a no-op-on-duplicate helper:
+
+```js
+import { defineIfFree, isRegistered, register } from '@adia-ai/web-components/core';
+
+class MyWidget extends HTMLElement { /* … */ }
+
+// Registers if free; returns false (no throw) if already taken
+const ok = defineIfFree('my-widget', MyWidget);
+
+// Check before registering
+if (!isRegistered('my-widget')) {
+  register('my-widget', MyWidget);
+}
+```
+
+When subclassing an AdiaUI primitive under a different tag name:
+
+```js
+import { UISlider } from '@adia-ai/web-components/components/slider';
+import { register } from '@adia-ai/web-components/core';
+
+class MySlider extends UISlider {
+  static properties = { ...UISlider.properties, custom: { type: String } };
+}
+register('my-slider', MySlider);
+```
+
+The `slider-ui` import auto-registers, but that doesn't interfere — `my-slider` is a distinct tag that hosts your subclass.
+
+### Non-side-effect class imports (since v0.4.7)
+
+Every component ships a sibling `class` subpath that exports the class **without** running `customElements.define`. Use it when you need test isolation, tag-name override, or selective composition:
+
+```js
+// Auto-register (default; tag registered immediately):
+import '@adia-ai/web-components/components/slider';
+
+// Class import (no auto-register; you decide when to define):
+import { UISlider } from '@adia-ai/web-components/components/slider/class';
+
+// Subclass + register under a different tag
+class MySlider extends UISlider {
+  static properties = { ...UISlider.properties, custom: { type: String } };
+}
+customElements.define('my-slider', MySlider);
+```
+
+**Test isolation example** — register the class under a unique per-test tag so subclass tests don't clobber the global registration:
+
+```js
+import { UISlider } from '@adia-ai/web-components/components/slider/class';
+import { defineIfFree } from '@adia-ai/web-components/core';
+
+beforeEach(() => {
+  const tag = `slider-ui-test-${Math.random().toString(36).slice(2, 8)}`;
+  defineIfFree(tag, class extends UISlider { /* test overrides */ });
+});
+```
+
+The class subpath is available for every component that has an `<x-ui>` tag (~95 primitives). TypeScript types are picked up from the same per-primitive `.d.ts` files used by the auto-register path — no separate `.d.ts` per subpath needed.
+
+---
+
+## TypeScript
+
+Since v0.4.6, the package ships `.d.ts` declarations. v0.4.6 covered the 17 form-bearing primitives (input/select/slider/etc.) with hand-authored rich event types; v0.4.7 codegen extended coverage to the remaining 73 non-form primitives (button/card/table/chart/etc.) from each component's `.a2ui.json` sidecar. **90 of 95** primitives that ship a JS class are now typed (the 5 CSS-only "elements" — `header`, `footer`, `section`, etc. — have no class). Adding the package to your dependencies automatically picks up:
+
+- Typed properties on every primitive (e.g. `el.value` is `number` on `<slider-ui>`, `boolean` on `<switch-ui>`)
+- Typed events — `addEventListener('change', e => e.detail.value)` infers the detail shape
+- `HTMLElementTagNameMap` augmentation — `document.querySelector('slider-ui')` returns `UISlider`
+- Public types for `UIElement`, `UIFormElement`, signal, computed, effect, html, stamp
+
+```ts
+import type { UISlider, SliderChangeEvent } from '@adia-ai/web-components';
+
+const slider: UISlider = document.querySelector('slider-ui')!;
+slider.value = 75;                              // typed Number — string would error
+
+slider.addEventListener('change', (e: SliderChangeEvent) => {
+  console.log(e.detail.value);                  // number, inferred
+});
+
+slider.addEventListener('change', (e) => {      // also inferred
+  e.detail.value.toFixed(2);                    // ok — Number.prototype is in scope
+});
+```
+
+For older bundlers without `exports` field support, add to `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+---
+
+## Anti-patterns
+
+Things to avoid, with why:
+
+### ❌ Don't bind eagerly-evaluated values to reactive props
+
+```js
+// BREAKS — value is a number, not a signal
+<slider-ui .value=${signal.value * 100}></slider-ui>
+
+// WORKS — pass the signal or a function
+<slider-ui .value=${signal}></slider-ui>
+<slider-ui .value=${() => signal.value * 100}></slider-ui>
+```
+
+### ❌ Don't subscribe via `attributeChangedCallback` to a primitive's attributes
+
+The base class already handles this. Use the property setter instead:
+
+```js
+// BREAKS — fragile, duplicates the base class's mirror
+const observer = new MutationObserver(...);
+observer.observe(slider, { attributes: ['value'] });
+
+// WORKS — set the property; signals propagate
+slider.value = 75;
+```
+
+### ❌ Don't use shadow DOM patterns
+
+AdiaUI is light-DOM. `::part()`, `::slotted()`, `<slot>` elements don't exist:
+
+```js
+// BREAKS — no shadow tree
+slider.shadowRoot.querySelector('.thumb');
+
+// WORKS — children are real DOM
+slider.querySelector('[slot="thumb"]');
+```
+
+### ❌ Don't add inline event handlers via `onchange=`
+
+The HTML `on*` attributes don't pick up the typed `detail`:
+
+```html
+<!-- BREAKS — fires but no typed handler signature -->
+<slider-ui onchange="console.log(this.value)"></slider-ui>
+
+<!-- WORKS — addEventListener gets the CustomEvent -->
+<slider-ui id="s"></slider-ui>
+<script>
+  document.getElementById('s').addEventListener('change', e => console.log(e.detail.value));
+</script>
+```
+
+### ❌ Don't try to register a tag name twice
+
+`customElements.define()` throws on re-registration. The auto-register pattern handles this for you. If you import a primitive twice (e.g. via two different paths), the bundler de-dupes; if it doesn't, the first define wins and the second throws.
+
+### ❌ Don't write `static properties` with un-typed defaults
+
+```js
+// BREAKS — undefined defaults cause attribute parsing surprises
+static properties = { value: {} };
+
+// WORKS — declare type + default
+static properties = {
+  value: { type: Number, default: 0, reflect: true },
+};
+```
+
+### ❌ Don't read property values from inside `constructor()`
+
+Properties are installed by `installProps()` in `super()`, but the host's render effect doesn't install until `connectedCallback()`. Reading properties in the constructor returns defaults; mutating them is fine, but if you depend on the rendered DOM existing, do it in `connected()` or later.
+
+---
+
+## More
+
+- [`README.md`](./README.md) — package overview + authoring guide
+- [Component yaml contracts](./components/) — every primitive's complete API (props, events, slots, examples)
+- [Live demos](https://ui-kit.exe.xyz/site/components/) — every primitive in action
+- [`docs/specs/component-token-contract.md`](../../docs/specs/component-token-contract.md) — full authoring contract
+- [`docs/specs/component-implementation-patterns.md`](../../docs/specs/component-implementation-patterns.md) — render strategies
+- [`docs/specs/traits.md`](../../docs/specs/traits.md) — composable behaviors
+
+For consumer questions not covered here, file an issue against [adiahealth/gen-ui-kit](https://github.com/adiahealth/gen-ui-kit/issues). This document is the canonical answer — if it doesn't have your answer, it's a doc gap worth fixing.

package/components/accordion/accordion.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `<accordion-ui>` — Accordion container managing single/multiple open states.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/accordion
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run components`, then `npm run codegen:dts` to regenerate;
+ * or hand-author this file fully if rich event types are needed.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIAccordion extends UIElement {
+  /** Allow multiple panels to be open simultaneously */
+  multiple: boolean;
+}