@adia-ai/web-components 0.4.5 → 0.4.6

package/README.md

@@ -1,13 +1,13 @@
 # @adia-ai/web-components
 
-Vanilla web components + A2UI runtime for AdiaUI. **80 light-DOM custom
-elements**, a reactive core, a trait system, and a renderer that turns
-A2UI protocol messages into live DOM.
+Vanilla web components + A2UI runtime for AdiaUI. **95 light-DOM custom
+elements** + **56 composable traits**, a reactive core (signals + tagged-template renderer), form-associated form controls, and integration into the A2UI generation pipeline.
 
-> This package ships UI atoms only. The generation pipeline lives in
-> [`@adia-ai/a2ui-compose`](../a2ui/compose); the pattern corpus in
-> [`@adia-ai/a2ui-corpus`](../a2ui/corpus); the MCP server in
-> [`@adia-ai/a2ui-mcp`](../a2ui/mcp).
+> This package ships UI atoms only. Composite shells (admin / chat / editor / simple / theme) live in [`@adia-ai/web-modules`](../web-modules). The generation pipeline lives in [`@adia-ai/a2ui-compose`](../a2ui/compose); the pattern corpus in [`@adia-ai/a2ui-corpus`](../a2ui/corpus); the MCP server in [`@adia-ai/a2ui-mcp`](../a2ui/mcp).
+>
+> **Consumer guide:** [`USAGE.md`](./USAGE.md) — property reactivity, event contract, form participation, lifecycle, registration, TypeScript. Start here if you're integrating AdiaUI into an app.
+>
+> **Live demos** for every primitive at [`https://ui-kit.exe.xyz/site/components/<name>`](https://ui-kit.exe.xyz/site/) — `<name>` is the tag without the `-ui` suffix (e.g. [`button`](https://ui-kit.exe.xyz/site/components/button), [`select`](https://ui-kit.exe.xyz/site/components/select), [`slider`](https://ui-kit.exe.xyz/site/components/slider)).
 
 ## Install
 
@@ -23,13 +23,23 @@ npm install @adia-ai/web-components @adia-ai/web-modules
 
 ## Quick start
 
-```html
-<link rel="stylesheet" href="node_modules/@adia-ai/web-components/index.css" />
+ESM-only — bundlers (Vite, esbuild, webpack 5+, Rollup) resolve `import` for both `.js` and `.css`; in plain HTML use `<script type="module">` + `<link rel="stylesheet">`.
+
+```js
+import '@adia-ai/web-components';          // registers every *-ui tag (95 primitives)
+import '@adia-ai/web-components/css';      // every primitive's CSS (one stylesheet)
+```
 
-<script type="module">
-  import '@adia-ai/web-components';   // registers every *-ui tag
-</script>
+Or per-component for tree-shaking-conscious bundles:
+
+```js
+import '@adia-ai/web-components/components/button';        // <button-ui> only
+import '@adia-ai/web-components/components/button.css';    // its CSS
+```
 
+Then use the tags in markup:
+
+```html
 <card-ui>
   <header>
     <span slot="icon"><avatar-ui icon="user"></avatar-ui></span>
@@ -49,8 +59,8 @@ web-components/
 ├── core/           — Reactivity + base classes
 │   ├── signals.js       signal() / computed() / effect() / batch() / untracked()
 │   ├── template.js      tagged templates: html, css, repeat, stamp
-│   ├── element.js       AdiaElement — light-DOM reactive base
-│   ├── form.js          AdiaFormElement — form-associated + validation
+│   ├── element.js       UIElement — light-DOM reactive base
+│   ├── form.js          UIFormElement — form-associated + ElementInternals + validation
 │   ├── provider.js      global provider registration + router-ui
 │   ├── anchor.js        popover + anchor-positioning
 │   ├── markdown.js      lightweight markdown renderer
@@ -58,18 +68,19 @@ web-components/
 │   └── data-stream.js   `data-stream-*` attribute trait (HTTP/SSE/WS,
 │                        signal-backed, refcounted shared transports)
 │
-├── components/     — 80 *-ui custom elements (primitives)
+├── components/     — 95 *-ui custom elements (primitives)
 │   └── <tag>/
-│       ├── <tag>.js       class definition (extends AdiaElement)
+│       ├── <tag>.js       class definition (extends UIElement / UIFormElement)
 │       ├── <tag>.css      @scope(tag-ui) two-block: tokens + styles
 │       ├── <tag>.yaml     authoring contract (props, slots, events, examples)
 │       └── <tag>.a2ui.json  generated — do NOT edit
 │
-│  Composite elements (app-shell, app-nav*, adia-chat, adia-editor,
-│  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.
+│  Composite shells (admin-shell, chat-shell, editor-shell, simple-shell,
+│  theme-panel, gen-root, a2ui-root) ship in the sibling
+│  `@adia-ai/web-modules` package — see ADR-0012 for the three-tier
+│  rationale.
 │
-├── traits/         — 41 composable behaviors via defineTrait() + the
+├── traits/         — 56 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
@@ -96,11 +107,39 @@ live at the repo-root `scripts/` directory rather than inside this
 package — they span the monorepo (MCP server, a2ui-corpus data,
 component catalog) and aren't scoped to web-components alone.
 
-## Component contract
+## Using a primitive (consumer guide)
+
+The complete consumer surface — property reactivity, event contract, form participation, lifecycle, registration, TypeScript — lives in [**`USAGE.md`**](./USAGE.md). Start there if you're integrating AdiaUI into an app rather than authoring a new primitive.
+
+Quick reference:
+
+```js
+// Property reactivity — every prop is signal-backed
+slider.value = 75;            // triggers re-render
+
+// Event contract — CustomEvent with typed detail (since v0.4.5)
+slider.addEventListener('change', (e) => console.log(e.detail.value));
+
+// Form participation — 15 primitives extend UIFormElement
+new FormData(document.getElementById('settings'));  // includes every <input-ui>, <select-ui>, etc.
+
+// Lifecycle — UIElement provides connected/render/updated/disconnected hooks
+class MyWidget extends UIElement {
+  connected() { /* set up */ }
+  render() { /* update DOM */ }
+  disconnected() { /* tear down */ }
+}
+
+// Registration — conflict-safe via defineIfFree
+import { defineIfFree } from '@adia-ai/web-components/core';
+defineIfFree('my-widget', MyWidget);
+```
+
+TypeScript users: types ship in the package since v0.4.6. `import type { UISlider, SliderChangeEvent } from '@adia-ai/web-components'` for hand-typed handlers; `HTMLElementTagNameMap` is augmented so `document.querySelector('slider-ui')` returns `UISlider`.
+
+## Authoring a primitive
 
-Every component is a single-file class extending `AdiaElement` (or
-`AdiaFormElement` for form fields). All styling lives in a sibling `.css`
-file using **two-block `@scope`**:
+If you're contributing a new primitive (rather than consuming one), this is for you. Every component is a single-file class extending `UIElement` (or `UIFormElement` for form fields). All styling lives in a sibling `.css` file using **two-block `@scope`**:
 
 ```css
 @scope (button-ui) {