microtags 0.0.8 → 0.0.11

package/README.md

@@ -9,11 +9,11 @@
 [![gzip size](https://img.shields.io/bundlephobia/minzip/microtags?style=flat-square)](https://bundlephobia.com/package/microtags)
 [![license](https://img.shields.io/badge/license-Big_Time-blue?style=flat-square)](LICENSE)
 
-Web component helper with reactive props, automatic cleanup, and no
-[Shadow DOM](https://gomakethings.com/the-shadow-dom-is-an-antipattern/).
+Web component helper with reactive props, automatic cleanup, and
+[no Shadow DOM](https://gomakethings.com/the-shadow-dom-is-an-antipattern/).
 Reactive via [alien-signals](https://github.com/stackblitz/alien-signals).
 
-**Size: 3.41 KB** with all dependencies, minified and brotlied
+**Size: <!-- size -->3.48 KB<!-- /size -->** with all dependencies, minified and brotlied
 
 Inspired by [nanotags](https://nanotags.psdcoder.dev/). Reactive props use
 **alien-signals** instead of nanostores atoms.
@@ -25,21 +25,31 @@ Inspired by [nanotags](https://nanotags.psdcoder.dev/). Reactive props use
 - [Install](#install)
   * [Import map](#import-map)
   * [Pre-bundled](#pre-bundled)
-- [Example](#example)
+- [Get Started](#get-started)
+  * [1. Call `.define`](#1-call-define)
+  * [2. Call the `.with*` Methods](#2-call-the-with-methods)
+  * [3. Call `.setup`](#3-call-setup)
+- [Full Example](#full-example)
+- [Validation](#validation)
+  * [Prop validation](#prop-validation)
+    + [`p.schema` vs Standard Schema](#pschema-vs-standard-schema)
   * [Client-side validation](#client-side-validation)
 - [Serverside Example](#serverside-example)
   * [`.TAG`](#tag)
-  * [`.refs`](#refs)
 - [API](#api)
-  * [Props](#props)
-    + [`withProps`](#withprops)
-  * [Refs](#refs)
-    + [`withRefs`](#withrefs)
-    + [Element types](#element-types)
   * [`define`](#define)
-  * [`withContexts`](#withcontexts)
-  * [`setup` and `ctx`](#setup-and-ctx)
-    + [peek and untracked](#peek-and-untracked)
+    + [`ComponentBuilder`](#componentbuilder)
+  * [`builder.withProps`](#builderwithprops)
+    + [`p.json`](#pjson)
+    + [`p.schema`](#pschema)
+  * [`builder.withRefs(fn)`](#builderwithrefsfn)
+  * [`builder.withContexts`](#builderwithcontexts)
+    + [`.withContexts` Example](#withcontexts-example)
+  * [`builder.setup(ctx)`](#buildersetupctx)
+    + [`ctx`](#ctx)
+- [Missing refs](#missing-refs)
+  * [Checking refs in tests](#checking-refs-in-tests)
+- [Typed Events](#typed-events)
 - [Templates](#templates)
 - [Subpath Exports](#subpath-exports)
   * [`microtags/context`](#microtagscontext)
@@ -48,14 +58,14 @@ Inspired by [nanotags](https://nanotags.psdcoder.dev/). Reactive props use
     + [`render`](#render)
   * [`microtags/util`](#microtagsutil)
     + [Coercion](#coercion)
-    + [`runCleanups`](#runcleanups)
+    + [`runAll`](#runall)
     + [`toAttributes`](#toattributes)
-- [Divergence from `nanotags`](#divergence-from-nanotags)
+- [Differences from `nanotags`](#differences-from-nanotags)
   * [Reactivity primitive](#reactivity-primitive)
   * [Effects + Subscriptions](#effects--subscriptions)
   * [Refs: `r.all` instead of `r.many`](#refs-rall-instead-of-rmany)
   * [Context API](#context-api)
-  * [Props](#props-1)
+  * [Props](#props)
   * [Not ported](#not-ported)
   * [Additions / New Features](#additions--new-features)
 
@@ -63,9 +73,7 @@ Inspired by [nanotags](https://nanotags.psdcoder.dev/). Reactive props use
 
 </details>
 
-----------------------------------------------------------------------
 ## Install
-----------------------------------------------------------------------
 
 ```sh
 npm i -S microtags
@@ -96,10 +104,8 @@ Subpaths follow the same URL pattern: `microtags/context`, `microtags/render`.
 
 ### Pre-bundled
 
-For raw-file CDNs (jsDelivr, unpkg) or local files, where dependencies are
-not resolved for you, use the pre-bundled `microtags/min` build. It is a
-single self-contained file with `alien-signals` inlined, so no other
-mappings are needed:
+This package exposes `microtags/min`, which is a single self-contained file
+with `alien-signals` inlined.
 
 ```html
 <script type="importmap">
@@ -111,23 +117,89 @@ mappings are needed:
 </script>
 ```
 
+## Get Started
 
-----------------------------------------------------------------------
-## Example
-----------------------------------------------------------------------
+### 1. Call `.define`
 
-This example depends on having the full HTML already in the DOM. If you want
-to do client-side-rendered components, that is possible. You would update the
-DOM inside `.setup`.
+```ts
+import { define } from 'microtags'
 
-Since the full HTML exists already, defining your components in the
-client-side JS is about "hydrating" the page (adding behavior).
+const myCounter = define('my-counter')
+```
 
 ---
 
-`withProps`, `withRefs`, and `withContexts` are optional and can appear in
-any order. `.setup` ends the chain: it calls `customElements.define` under the
-hood and returns a typed constructor.
+### 2. Call the `.with*` Methods
+
+Methods `withProps`, `withRefs`, and `withContexts` are optional and can appear
+in any order. `.setup` ends the chain. It calls `customElements.define` under
+the hood and returns a typed constructor.
+
+```ts
+myCounter
+    .withProps(p => ({
+        start: p.number(),  // the starting count (an attribute)
+    }))
+    .withRefs(r => ({  // keys in this object are the `data-ref` names in HTML
+        display: r.one<HTMLDivElement>(),  // typed as HTMLDivElement,
+        inc: r.one(),  // depends on a child in HTML with `data-ref="inc"`
+        dec: r.one(),  // depends on a child in HTML with `data-ref="dec"`
+        copy: r.one(),  // the <copy-btn> element, via `data-ref="copy"`
+    }))
+```
+
+### 3. Call `.setup`
+
+Method `.setup` takes a function that gets called with `context` object.
+
+```ts
+myCounter
+    .setup(ctx => {
+        const count = signal(ctx.props.start())
+        // `ctx.refs` are expected to be HTML elements with a matching `data-ref`
+        const display = ctx.refs.display
+
+        // whenever `count` changes
+        ctx.effect(() => {
+            display.textContent = `Count: ${count()}`
+            display.style.color = count() < 0 ? 'red' : 'inherit'
+        })
+
+        // Reflect the live count onto the copy button's `value` attribute.
+        // Because `value` is attribute-backed, this flows into <copy-btn>'s
+        // own signal, so it always copies the current count.
+        ctx.effect(() => {
+            const copy = ctx.refs.copy
+            copy.setAttribute('value', String(count()))
+        })
+
+        /**
+         * Listen for clicks.
+         */
+        ctx.on(ctx.refs.inc, 'click', () => {
+            count(count() + 1)
+        })
+
+        ctx.on(ctx.refs.dec, 'click', () => {
+            count(count() - 1)
+        })
+    })
+```
+
+## Full Example
+
+This example expects the full HTML to already be in the DOM.
+Defining the components is about "hydrating" the page, or adding behavior.
+
+If you want to client-side render the components, that is possible too.
+You can update the DOM inside `.setup`.
+
+>
+> [!NOTE]  
+> The server should know how to create the markup that components depend
+> on here. See [the serverside example](#serverside-example).
+>
+
 
 ```ts
 import { define } from 'microtags'
@@ -135,7 +207,7 @@ import { signal } from 'alien-signals'
 
 /**
  *  - attribute-backed prop (`start`)
- *  - data-ref elements (the <count-button> and <copy-btn> children)
+ *  - data-ref elements -- each needs a data-ref attribute, eg data-ref="inc"
  *  - ctx.effect, ctx.on
  */
 export const myCounter = define('my-counter')
@@ -184,25 +256,102 @@ export const myCounter = define('my-counter')
 </my-counter>
 ```
 
-### Client-side validation
-
-See [example/subscribe-form.ts](./example/subscribe-form.ts).
+## Validation
 
-There are two separate things people call "validation", and `microtags`
-handles them in different places:
+There are two separate things people call "validation":
 
-1. **Prop validation** checks the attributes passed *into* a component.
+1. **Prop validation** checks the attributes passed into a component.
    Pass a [Standard Schema](https://standardschema.dev) (Zod, Valibot,
    ArkType) to [`p.schema`](#withprops); it coerces the attribute value
-   and falls back to `undefined` when the value doesn't match.
-2. **Form input validation** checks live user input in a form, for example a
-   value that changes on every keystroke and needs to report *why* it is invalid.
+   and falls back to `undefined` when the value doesn't coerce.
+2. **Form input validation** -- client-side validation -- checks live user input
+   in a form, for example a value that changes on every keystroke.
    There is no dedicated API for this. Validate the schema directly
-   inside `.setup()` and hold the result in a signal:
+   inside `.setup()` and hold the result as a signal.
+
+### Prop validation
 
-The example below is the second kind -- form input (client-side) validation.
+Pass a [Standard Schema](https://standardschema.dev) validator to `p.schema`.
+The validator runs against the raw attribute and its output becomes the
+signal's value; anything it rejects falls back to `undefined`.
 
 ```ts
+import { z } from 'zod'
+import { define } from 'microtags'
+
+// Any Standard Schema validator works (Zod, Valibot, ArkType). microtags
+// only sees the shared `~standard` interface, so it has no validation
+// library of its own and no dependency on the one you pick.
+const Variant = z.enum(['info', 'success', 'warning', 'danger'])
+
+define('status-badge')
+    .withProps(p => ({
+        // Validates the raw `variant` attribute. A value outside the
+        // four options falls back to `undefined`.
+        variant: p.schema(Variant),
+    }))
+    .setup(ctx => {
+        ctx.effect(() => {
+            const variant = ctx.props.variant() ?? 'info'
+            ctx.host.className = `badge badge-${variant}`
+        })
+    })
+```
+
+```html
+<status-badge variant="success">Saved</status-badge>
+
+<!-- "purple" is not in the enum, so ctx.props.variant() is undefined -->
+<status-badge variant="purple">Unknown</status-badge>
+```
+
+#### `p.schema` vs Standard Schema
+
+[Standard Schema](https://standardschema.dev) is a small shared interface
+that Zod, Valibot and ArkType all implement. `p.schema` validates through that
+interface, so microtags ships no validator of its own.
+
+A schema prop is attribute-backed and observed, exactly like `p.string()` or
+`p.number()`: editing the attribute re-runs the validator and pushes the result
+to `ctx.props`.
+
+The validator's input is the raw attribute string, or `null` when the attribute
+is absent. Because the input is always a string, schemas for non-string values
+must coerce. Use `z.coerce.number()`, not `z.number()`:
+
+```ts
+.withProps(p => ({
+    // "5" -> 5; "0" and the absent attribute both fall back to undefined
+    quantity: p.schema(z.coerce.number().int().min(1)),
+}))
+```
+
+**On success the signal holds the validator's output value**; on failure it
+falls back to `undefined`. The inferred signal type is the schema's output,
+so guard for the `undefined` case, or fold a default into the schema so it
+never fails:
+
+
+```ts
+{
+    // always 'info' | 'success' | 'warning' | 'danger', never undefined
+    variant: p.schema(Variant.catch('info')),
+}
+```
+
+Only synchronous schemas are supported; an async schema throws when the
+attribute is validated.
+
+-------------------------------------------------------
+
+### Client-side validation
+
+There is no special API here. Validate input inside `.setup`, 
+
+See [example/subscribe-form.ts](./example/subscribe-form.ts).
+
+```ts
+// form input (client-side) validation
 import { signal, startBatch, endBatch } from 'alien-signals'
 import { z } from 'zod'
 import { define } from 'microtags'
@@ -219,18 +368,21 @@ define('subscribe-form')
     }))
     .setup(ctx => {
         const value = signal('')
-        const touched = signal(false)
+        const touched = signal<boolean>(false)
 
         // capture the live value (two-way; clears the field on reset)
         ctx.bind(value, ctx.refs.input)
+
         // only reveal errors after the first blur
         ctx.on(ctx.refs.input, 'blur', () => touched(true))
 
+        // ctx.effect is alien-signals/effect with automatic/correct disposal
         ctx.effect(() => {
+            // subscribe to `value` and `touched`
             const result = Email.safeParse(value())
-            const message = result.success ?
+            const message = (result.success ?
                 '' :
-                result.error.issues[0].message
+                result.error.issues[0].message)
             const showError = touched() && !result.success
 
             ctx.refs.submit.disabled = !result.success
@@ -239,6 +391,7 @@ define('subscribe-form')
         })
 
         ctx.on(ctx.refs.form, 'submit', ev => {
+            // subscribe to DOM events
             ev.preventDefault()
             if (!Email.safeParse(value()).success) return
             ctx.refs.status.textContent = 'Thanks for subscribing!'
@@ -250,14 +403,16 @@ define('subscribe-form')
     })
 ```
 
-The error stays hidden until the field is blurred once, then updates live;
-the submit button is gated on validity. See `example/subscribe-form.ts`
-for the full working component.
+The error stays hidden until the field is blurred once, then updates live,
+and the submit button is disabled until valid. See `example/subscribe-form.ts`.
+
+
+---------------------------------------------------------------
 
 
-----------------------------------------------------------------------
 ## Serverside Example
-----------------------------------------------------------------------
+
+See [./example/ssr.ts](./example/ssr.ts).
 
 ### `.TAG`
 
@@ -265,11 +420,11 @@ Each tag name that you pass to `define` is exposed as a property `.TAG`
 on the return value. It is possible to import your web components in Node,
 even though Node does not have browser APIs.
 
-### `.refs`
+The `data-ref` attribute is a fallback. It's used when you don't pass a
+selector to `r.one()`. If you pass explicit CSS selectors to `withRefs`,
+e.g. `{ copy: r.one('button') }`, then the HTML does not require a `data-ref`
+attribute.
 
-All refs are defined per-component, and the ref names are exposed at `.refs`,
-so you can import your web components on the server and read the ref names
-as strings.
 
 ```ts
 import { MyCounter, CountBtn, CopyBtn } from './index.js'
@@ -311,11 +466,39 @@ export function render ():string {
 }
 ```
 
-----------------------------------------------------------------------
+
+---------------------------------------------------------------------
+
+
 ## API
-----------------------------------------------------------------------
 
-### Props
+### `define`
+
+```js
+function define (tagName:string):ComponentBuilder
+```
+
+Function `define(tagName)` returns a [`ComponentBuilder`](#componentbuilder).
+
+
+#### `ComponentBuilder`
+
+The object returned by [`define`](#define). Includes methods:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `.TAG` | `string` | The tag name passed to `define`. See [`.TAG`](#tag). |
+| `.withProps(fn)` | `ComponentBuilder` | Declare reactive attributes. See [Props](#props). |
+| `.withRefs(fn)` | `ComponentBuilder` | Declare DOM refs resolved once the element connects. See [Refs](#refs-1). |
+| `.withContexts(fn)` | `ComponentBuilder` | Consume context values published by an ancestor. See [`withContexts`](#withcontexts). |
+| `.setup(fn)` | `MicrotagElementClass` | Registers the custom element and returns its class. See [`setup`](#setup) below. |
+
+Methods `withProps`, `withRefs`, and `withContexts` each return a new builder,
+so they chain in any order; `setup` ends the chain by registering the element.
+
+---------------------------------------------------------
+
+### `builder.withProps`
 
 Declare reactive attributes via `withProps`. Each prop becomes:
 
@@ -331,8 +514,6 @@ Declare reactive attributes via `withProps`. Each prop becomes:
 | `p.boolean()` | `"true"` / `""` &rarr; `true`, `"false"` &rarr; `false` | `false` |
 | `p.oneOf(opts)` | Picklist enum, throws on invalid | throws |
 
-#### `withProps`
-
 ```ts
 .withProps(p => ({
     count:   p.number(),           // attribute -> number  (NaN when absent)
@@ -344,7 +525,15 @@ Declare reactive attributes via `withProps`. Each prop becomes:
 }))
 ```
 
-##### `p.json`
+Inside `.setup()`, every prop is a callable signal:
+
+```ts
+ctx.props.count()      // read
+ctx.props.count(42)    // write
+```
+
+
+#### `p.json`
 
 `p.json<T>()` -- a prop whose attribute value is parsed with
 `JSON.parse`. The type parameter `T` annotates the parsed result; it is a
@@ -367,6 +556,7 @@ observed, so editing the attribute re-parses and pushes the new value to
 attribute is absent, and when the value is not valid JSON. Parse errors are
 swallowed rather than thrown.
 
+
 ```ts
 // check for `undefined` case
 ctx.effect(() => {
@@ -376,32 +566,46 @@ ctx.effect(() => {
 })
 ```
 
+#### `p.schema`
+
 For input you want validated rather than only parsed, pass a Standard Schema
 to [`p.schema`](#withprops) instead.
 
-Inside `setup()`, every prop is a callable signal:
+
+---------------------------------------------------------
+
+
+### `builder.withRefs(fn)`
+
+Takes a function that gets called with a helpful query selector, `r`.
+
+Call `r.one()` / `r.all()` with no argument to match `[data-ref="<key>"]`,
+where `key` is the key name you passed in. Or pass a CSS selector to query by
+it instead. Queries are resolved relative to the host element, during
+[the `connectedCallback`](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks).
+
+All refs returned from this callback are typed as much as possible, and exposed
+on the `context` object passed to the `.setup` function.
+
 
 ```ts
-ctx.props.count()      // read
-ctx.props.count(42)    // write
+class ComponentBuilder {
+    withRefs<R extends Record<string, RefDef>> (
+        fn:(r:RefsDSL) => R
+    ):ComponentBuilder<Props, R, CtxDefs>
+}
 ```
 
----
 
-### Refs
+Takes a function that gets called with a [`RefsDSL`](./src/builders.ts#L54)
+object. It should return an object of child elements that you want to keep
+references to.
 
 The `data-ref` attribute is a fallback. It's used when you don't pass a
 selector to `r.one()`. If you pass explicit CSS selectors to `withRefs`,
 e.g. `{ copy: r.one('button') }`, then the HTML does not require a `data-ref`
 attribute.
 
-#### `withRefs`
-
-Call `r.one()` / `r.all()` with no argument to match `[data-ref="<key>"]`,
-where `key` is the key name you pass in, or pass a CSS selector to query by
-it instead. Queries are resolved relative to the host element, during
-[the `connectedCallback`](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks).
-
 
 ```ts
 .withRefs(r => ({
@@ -419,67 +623,41 @@ If there are no `data-ref` attribtues in the HTML, use CSS query selectors.
 }))
 ```
 
-See [#refs in serverside-rendering](#refs). Each component created with
-`micortags` exposes a `.refs` property that is an object map
-of ref names, eg `MyComponent.refs.copyButton`.
 
-#### Element types
+---------------------------------------------------------------------
 
-An un-annotated `r.one()` is typed as `HTMLElement`, so `.style`,
-`.textContent`, and `.dataset` work without a cast. There are two ways to
-get a more specific element type:
 
-```ts
-.withRefs(r => ({
-    // Generic argument: sets the type, keeps the [data-ref] selector.
-    display: r.one<HTMLDivElement>(),
-
-    // Tag string: infers the type AND queries by that tag, exactly like
-    // document.querySelector('button'). It does NOT keep [data-ref].
-    save:    r.one('button'),     // SingleRefDef<HTMLButtonElement>
-    items:   r.all('li'),         // MultipleRefDef<HTMLLIElement>
-    button:  r.one(),             // HTMLElement (un-annotated default)
-}))
-```
+### `builder.withContexts`
 
-These flow straight through to `ctx.refs`:
+Context is for the case where a parent component defines some state, e.g. a
+`theme`, and the top-level (application) knows nothing about the theme, but the
+application *does* determine what children the parent renders
+(the app passes in children), and the children need to know the theme.
 
 ```ts
-ctx.refs.display  // HTMLDivElement
-ctx.refs.save     // HTMLButtonElement
-ctx.refs.items    // HTMLLIElement[]
-ctx.refs.button   // HTMLElement (the un-annotated default)
+class ComponentBuilder {
+    withContexts<C extends Record<string, ContextToken<unknown>>> (
+        fn:(c:ContextDSL) => C
+    ):ComponentBuilder<Props, RefDefs, C>
+}
 ```
 
-Non-HTML refs (SVG / MathML) are out of scope: the type parameter is
-constrained to `HTMLElement`, so cast at the use site if you need one
-(e.g. `ctx.refs.icon as unknown as SVGSVGElement`).
-
+#### `.withContexts` Example
 
-### `define`
-
-```ts
-import { define } from 'microtags'
-
-define(tagName:string):ComponentBuilder
+```html
+<!-- The application composes this markup. -->
+<theme-provider>
+    <some-child></some-child>
+    <another-child></another-child>
+</theme-provider>
 ```
 
-Returns a fluent builder. Call `.setup()` to register the custom element.
-All builder methods are chainable and fully type-inferred.
-
-### `withContexts`
-
-Context is for the case where a parent component defines some state, e.g. a
-`theme`, and the top-level (application) knows nothing about the theme. But the
-top level application does determine what children the parent renders
-(it passes in children), and the children need to know the theme.
-
 In that case, there is no way for the "parent" component to pass the theme to
-the children, and the root level (application) doesn't know what the theme is.
+the children. The root level (application) doesn't know what the theme is.
 
-Context gives us a "pull" based way to model this. The context-provider
-publishes the value, and any descendants opt in (or pull values) with
-`withContexts`, and the unknown-consumer and late-arrival problems are handled. 
+Context gives us a way to model this. The context-provider
+publishes the value, and any descendants opt in with
+`withContexts`.
 
 >
 > [!IMPORTANT]  
@@ -487,7 +665,6 @@ publishes the value, and any descendants opt in (or pull values) with
 > Context gives you nothing for first paint or the no-JS case.
 >
 
-
 ```ts
 import { define } from 'microtags'
 import { createContext, provide } from 'microtags/context'
@@ -498,7 +675,8 @@ const ThemeToken = createContext<string>()
 // not reference the children below. The application composes those in.
 define('theme-provider')
     .setup(ctx => {
-        ctx.onCleanup(provide(ctx.host, ThemeToken, 'dark'))
+        const rmContext = provide(ctx.host, ThemeToken, 'dark')
+        ctx.onCleanup(rmContext)
     })
 
 // Child: opts in to the theme and reads whichever provider it is
@@ -515,65 +693,180 @@ define('themed-card')
 ```
 
 ```html
-<!-- The application writes this markup. It nests <themed-card> inside
-     <theme-provider> but never sets the theme itself. -->
 <theme-provider>
     <themed-card>Card content</themed-card>
 </theme-provider>
 ```
 
-`setup()` is deferred until all required contexts resolve. See
-[`microtags/context`](#microtagscontext) for the provider API.
 
-### `setup` and `ctx`
+---------------------------------------------------------
+
+
+### `builder.setup(ctx)`
+
+Registers the custom element via `customElements.define` and returns the
+element class. The returned class exposes `.TAG` and `.refs` as static
+members, for use in [serverside rendering](#serverside-example).
+
+```ts
+class ComponentBuilder {
+    setup (
+        fn:(ctx:SetupContext<
+            Props,
+            RefsMap<RefDefs>,
+            ContextsMap<CtxDefs>
+        >) => void
+    ):MicrotagElementClass<RefDefs> {
+}
+```
+
+The callback function runs once per element instance, and is called with the
+following `context` object.
+
+
+#### `ctx`
+
+The argument passed to the callback given to `setup`.
 
 ```ts
-.setup(ctx => {
-    // ctx.host       the HTMLElement itself
-    // ctx.props      callable signals for each declared prop
-    // ctx.refs       resolved DOM refs
-    // ctx.contexts   consumed context values (reactive)
+ctx:SetupContext<Props, RefsMap<RefDefs>, ContextsMap<CtxDefs>>
+```
 
-    // Run a tracked effect; auto-disposed on disconnect.
-    ctx.effect(() => {
-        document.title = ctx.props.label()
-    })
+##### `ctx` Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `.peek(signal)` | `T` | Read a signal's current value without subscribing, even inside `ctx.effect`. |
+| `.on(target, type, handler, options?)` | `void` | Add a DOM event listener, auto-removed on disconnect. |
+| `.emit(event)` / `.emit(name, detail?, options?)` | `boolean` | Dispatch a pre-built `Event` as-is, or construct and dispatch a bubbling `CustomEvent` from a name. Returns `dispatchEvent`'s result: `false` if a cancelable event had `preventDefault()` called. |
+| `.effect(fn)` | `void` | Run an alien-signals effect that auto-tracks the signals it reads. Auto-disposed on disconnect. |
+| `.bind(signal, element, options?)` | `void` | Bind a signal to a DOM element property, auto-cleaned on disconnect. |
+| `.onCleanup(fn)` | `void` | Register custom teardown to run on disconnect. |
+| `.consume(token)` | `T \| undefined` | Read an optional context value published by an ancestor. See [`withContexts`](#withcontexts). |
+
+See [Typed Events](#typed-events) for more about `.on` and `.emit`.
 
-    // Bind a DOM property to a signal expression; auto-cleaned.
-    ctx.bind(() => String(ctx.props.count()), el, { prop: 'textContent' })
+##### `ctx.bind`
 
-    // Add an event listener; auto-removed on disconnect.
-    ctx.on(el, 'click', handler)
+The `.bind` method treats the signal as the source of truth. The element
+property is set from the signal.
+With no `options`, the control's element property and write-back event are
+auto-detected from its type:
 
-    // Dispatch an event from the host. Pass a name (with optional
-    // detail/options) for a bubbling CustomEvent, or a pre-built
-    // Event. Returns dispatchEvent's result.
-    ctx.emit('change', { value: 42 })
+```ts
+{
+    bind<T> (
+        source:Signal<T>,
+        control:Element,
+        opts?:BindOptions
+    )
+}
+```
+
+| Control | `prop` | write-back `event` |
+|---------|--------|---------------------|
+| `<input type="checkbox">` | `checked` | `change` |
+| `<input type="number">` / `type="range"` | `valueAsNumber` | `input` |
+| Other `<input>` types / `<textarea>` | `value` | `input` |
+| Anything else, e.g. `<select>` | `value` | `change` |
+
+Passing `options` overrides the auto-detected `prop`, and replaces the
+write-back `event` -- omit `options.event` for a one-way binding. A read-only
+getter (`() => T`) is also accepted as the `signal` argument, for binding a
+derived value one-way (pass it with `options` and omit `event`).
+
+```ts
+// two-way, auto-detected (checkbox -> `checked` / `change`)
+ctx.bind(checked, ctx.refs.toggle)
+
+// one-way: push a derived value into a read-only display
+ctx.bind(() => `${count()} items`, ctx.refs.label, { prop: 'textContent' })
+```
 
-    // Read a signal without creating a subscription.
-    const snap = ctx.peek(ctx.props.count)
+---
 
-    // Register arbitrary teardown logic.
-    ctx.onCleanup(() => { /* ... */ })
 
-    // Consume a context imperatively (returns value or undefined).
-    const theme = ctx.consume(ThemeToken)
+## Missing refs
+
+Any calls to `r.one` in `.withRefs` will throw if there is not a matching
+child element.
+
+```
+Error: MY-COMPONENT: missing refs: button, save
+```
+
+The tag name is upper case (it comes from `host.tagName`), and the
+message lists every required ref that was not found.
+
+Call to `r.all()` are **never reported**. A missing match resolves to an
+empty array, not an error.
+
+This check happens right before the custom element runs your `.setup` function.
+
+For a component with no contexts, refs are resolved at the moment the element
+connects to the DOM. For a component that declares
+[`withContexts`](#withcontexts), ref collection is deferred along
+with `setup` until every required context resolves.
+
+
+### Checking refs in tests
+
+A missing `r.one` ref throws while the component connects. When the browser
+runs a lifecycle callback (which is what `appendChild` triggers), it reports
+the exception to the global `error` event rather than propagating it to the
+caller, so a try / catch around `appendChild` sees nothing.
+
+You need to listen for the global `error` event. When every
+`data-ref` the component declares is present, nothing is reported.
+
+```ts
+import { test } from '@substrate-system/tapzero'
+import './my-counter.js'  // the component from the example above
+
+test('all refs resolve', t => {
+    let err:Error|null = null
+    const onError = (ev:ErrorEvent) => { err = ev.error }
+    window.addEventListener('error', onError)
+
+    const el = document.createElement('my-counter')
+    el.innerHTML = `
+        <div data-ref="display"></div>
+        <button data-ref="dec">-</button>
+        <button data-ref="inc">+</button>`
+    document.body.appendChild(el)
+
+    t.ok(err === null, 'no missing refs')
+
+    window.removeEventListener('error', onError)
+    document.body.removeChild(el)
 })
 ```
 
-#### peek and untracked
 
-When you need a non-subscribing read outside of `ctx.peek`, both helpers are
-exported from the main entry:
+## Typed Events
+
+`TypedEvent<Target, Detail>` is a type-only helper that narrows
+`CustomEvent` to a specific `target` and `detail`. Combine it with
+`HTMLElementEventMap` augmentation for app-wide type-safe events.
 
 ```ts
-import { peek, untracked } from 'microtags'
+import type { TypedEvent } from 'microtags'
 
-ctx.effect(() => {
-    const current = peek(ctx.props.count)   // does NOT subscribe
-    untracked(() => {
-        // reads inside here do not subscribe either
-    })
+type TabsChangedEvent = TypedEvent<InstanceType<typeof XTabs>, { index:number }>
+
+declare global {
+    interface HTMLElementEventMap {
+        'tabs:changed':TabsChangedEvent
+    }
+}
+
+// Emitting from setup:
+ctx.emit('tabs:changed', { index: 2 })
+
+// Listening, fully typed:
+ctx.on(tabsEl, 'tabs:changed', ev => {
+    ev.target   // the XTabs instance
+    ev.detail   // { index:number }
 })
 ```
 
@@ -649,6 +942,7 @@ callback function mutates the DOM through properties like `textContent`.
 Nothing concatenates strings into markup, so there is no string-injection
 XSS vector.
 
+
 ## Subpath Exports
 
 ### `microtags/context`
@@ -719,6 +1013,10 @@ signal imperatively.
 
 ### `microtags/render`
 
+```ts
+import { render, renderList } from 'microtags/render'
+```
+
 A keyed reconciler for rendering lists and single items from a
 `<template>`, with no virtual DOM and no diffing library.
 
@@ -846,7 +1144,8 @@ import {
     coerceString,
     coerceBoolean,
     coerceJson,
-    runCleanups,
+    runAll,
+    toAttributes
 } from 'microtags/util'
 ```
 
@@ -872,14 +1171,14 @@ function coerceJson<T = unknown> (raw:string | null):T | undefined
 - `coerceJson` -- `JSON.parse(raw)`, or `undefined` when the attribute is
   absent or not valid JSON. Pass a type parameter to annotate the result.
 
-#### `runCleanups`
+#### `runAll`
 
 Runs every function in the array, even if some throw. After all have run
 it re-throws the first error encountered, so one failing teardown cannot
 skip the rest. A `Cleanup` is a no-argument teardown function, `() => void`.
 
 ```ts
-function runCleanups (fns:Cleanup[]):void
+function runAll (fns:Cleanup[]):void
 ```
 
 #### `toAttributes`
@@ -907,7 +1206,7 @@ function toAttributes (attrs:Attrs):string
 
 ---
 
-## Divergence from `nanotags`
+## Differences from `nanotags`
 
 ### Reactivity primitive
 
@@ -985,8 +1284,6 @@ These nanotags APIs have no microtags equivalent:
 
 - `ctx.getElement` / `ctx.getElements` -- declare refs with `withRefs`, or
   call `ctx.host.querySelector` directly.
-- The `setup` mixin return value -- `setup` returns `void`; it does not
-  assign members back onto the element.
 - The `define(name, setupFn)` two-argument shorthand -- always use the
   builder chain ending in `.setup()`.