# nanotags

Tiny Web Components wrapper powered by Nano Stores reactivity. No Shadow DOM, typed builder API, reactive props and refs

## Agent Skills

This project ships Agent Skills for AI coding agents in the `psd-coder/nanotags` GitHub repo. Install all of them with `npx skills add psd-coder/nanotags --skill '*' -a <agent> -g`, where `<agent>` is one of `claude-code`, `codex`, `cursor`, `github-copilot`, `gemini-cli`, `opencode`, `grok`, `pi`.

To install one skill, pass its name: `npx skills add psd-coder/nanotags --skill <name> -a <agent> -g` or `gh skill install psd-coder/nanotags <name> --agent <agent> --scope user`. Drop `-g`, or pass `--scope project`, to install into the current project instead.

- [nanotags-components](https://raw.githubusercontent.com/psd-coder/nanotags/HEAD/packages/nanotags/skills/nanotags-components/SKILL.md): Rules for writing idiomatic nanotags components (Custom Elements + nanostores). Use when creating, reviewing, or refactoring anything that calls define(), withProps, withRefs, withContexts, setup(ctx), ctx.effect, ctx.bind, ctx.emit, renderList, or createContext. Also use when porting hand-written DOM code to nanotags, or when component code reaches for manual querySelector, addEventListener, dispatchEvent, store.subscribe/listen, classList toggling, element maps, or setTimeout reconciliation.

# Getting Started

A thin Web Components wrapper powered by [Nano Stores](https://github.com/nanostores/nanostores) reactivity. It leans on the platform—Custom Elements, standard DOM, regular CSS—instead of reinventing them. The result is a typed, reactive component model with automatic cleanup in under **2.5 KB**.

```typescript
import { define } from "nanotags";

define("copy-btn")
  .withRefs((r) => ({ code: r.one("code") }))
  .setup((ctx) => {
    ctx.on(ctx.host, "click", async () => {
      await navigator.clipboard.writeText(ctx.refs.code.textContent);
      ctx.host.classList.add("active");
      setTimeout(() => ctx.host.classList.remove("active"), 1000);
    });
  });
```

## Why nanotags?

- **No Shadow DOM**: markup stays in the regular DOM, styled with normal CSS
- **Reactive props** via [Nano Stores](https://github.com/nanostores/nanostores) atoms: subscribe when you need updates, `.get()` when you don't
- **Typed fluent builder**: props, refs, and contexts are fully inferred through the chain
- **Automatic cleanup**: event listeners, store subscriptions, and bindings are removed on disconnect
- **Tree-shakeable**: `nanotags/render` and `nanotags/context` are separate entry points
- **Standard Schema**: built-in validators plus any [Standard Schema](https://github.com/standard-schema/standard-schema)-compatible library (Valibot, Zod, ArkType)
- **Hydration-first**: built for statically rendered markup. Pair with [Astro](https://astro.build/), server-rendered HTML, or any static-first setup to hydrate lightweight interactive islands

## Installation

Install `nanotags nanostores`:

- pnpm: `pnpm add nanotags nanostores`
- npm: `npm install nanotags nanostores`
- yarn: `yarn add nanotags nanostores`
- bun: `bun add nanotags nanostores`

[`nanostores`](https://github.com/nanostores/nanostores) is a peer dependency.

**CDN**

No build step needed. Add an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to your HTML:

Then use bare specifiers as usual:

```html
<script type="module">
  import { define } from "nanotags";
  import { atom } from "nanostores";
</script>
```

Sub-entry points (`nanotags/render`, `nanotags/context`) follow the same URL pattern.

## Agent skill

The repo ships an [agent skill](https://github.com/psd-coder/nanotags/tree/HEAD/packages/nanotags/skills/nanotags-components) with the rules for idiomatic components and references for the exact API, Astro integration and testing. Install it so your coding agent writes idiomatic nanotags:

Install every skill for your agent:

- Claude Code
  - user scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a claude-code -g`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent claude-code --scope user`
    - curl: `mkdir -p ~/.claude/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C ~/.claude/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
  - project scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a claude-code`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent claude-code --scope project`
    - curl: `mkdir -p .claude/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C .claude/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
- Codex
  - user scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a codex -g`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent codex --scope user`
    - curl: `mkdir -p ~/.agents/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C ~/.agents/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
  - project scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a codex`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent codex --scope project`
    - curl: `mkdir -p .agents/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C .agents/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
- Cursor
  - user scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a cursor -g`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent cursor --scope user`
    - curl: `mkdir -p ~/.cursor/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C ~/.cursor/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
  - project scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a cursor`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent cursor --scope project`
    - curl: `mkdir -p .agents/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C .agents/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
- GitHub Copilot
  - user scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a github-copilot -g`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent github-copilot --scope user`
    - curl: `mkdir -p ~/.copilot/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C ~/.copilot/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
  - project scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a github-copilot`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent github-copilot --scope project`
    - curl: `mkdir -p .agents/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C .agents/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
- VS Code
  - user scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a github-copilot -g`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent github-copilot --scope user`
    - curl: `mkdir -p ~/.copilot/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C ~/.copilot/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
  - project scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a github-copilot`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent github-copilot --scope project`
    - curl: `mkdir -p .agents/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C .agents/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
- Gemini CLI
  - user scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a gemini-cli -g`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent gemini-cli --scope user`
    - curl: `mkdir -p ~/.gemini/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C ~/.gemini/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
  - project scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a gemini-cli`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent gemini-cli --scope project`
    - curl: `mkdir -p .agents/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C .agents/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
- OpenCode
  - user scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a opencode -g`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent opencode --scope user`
    - curl: `mkdir -p ~/.config/opencode/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C ~/.config/opencode/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
  - project scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a opencode`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent opencode --scope project`
    - curl: `mkdir -p .agents/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C .agents/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
- Grok Build
  - user scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a grok -g`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent grok --scope user`
    - curl: `mkdir -p ~/.grok/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C ~/.grok/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
  - project scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a grok`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent grok --scope project`
    - curl: `mkdir -p .grok/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C .grok/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
- Pi
  - user scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a pi -g`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent pi --scope user`
    - curl: `mkdir -p ~/.agents/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C ~/.agents/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`
  - project scope
    - npx skills: `npx skills add psd-coder/nanotags --skill '*' -a pi`
    - gh skill: `gh skill install psd-coder/nanotags --all --agent pi --scope project`
    - curl: `mkdir -p .pi/skills && curl -fsSL https://codeload.github.com/psd-coder/nanotags/tar.gz/HEAD | tar -xz -C .pi/skills --strip-components=4 nanotags-HEAD/packages/nanotags/skills`

## Quick Start

Start with markup: nanotags hydrates existing DOM rather than rendering from scratch:

```html
<x-counter count="0">
  <span data-ref="display">0</span>
  <button data-ref="increment">+1</button>
</x-counter>
```

Then define the component:

```typescript
import { define } from "nanotags";

const Counter = define("x-counter")
  .withProps((p) => ({
    count: p.number(),
  }))
  .withRefs((r) => ({
    increment: r.one("button"),
    display: r.one("span"),
  }))
  .setup((ctx) => {
    ctx.on(ctx.refs.increment, "click", () => {
      ctx.props.$count.set(ctx.props.$count.get() + 1);
    });

    ctx.effect(ctx.props.$count, (value) => {
      ctx.refs.display.textContent = String(value);
    });
  });
```

What happens:

1. **[`define("x-counter")`](api#define)**: starts the builder chain, names the custom element
2. **[`.withProps`](api#withprops)**: declares a `count` attribute parsed as a number, exposed as `ctx.props.$count` atom
3. **[`.withRefs`](api#withrefs)**: declares typed refs resolved via `[data-ref="name"]` selectors
4. **[`.setup`](api#setup)**: wires event listeners and reactive effects; everything is auto-cleaned on disconnect

## Lifecycle

nanotags builds on the standard Custom Elements lifecycle with a thin reactive layer on top.

**1. Constructor**

Reactive prop stores are created and getter/setter descriptors are defined on the element instance. Attribute-backed props read their initial value from the DOM; JSON and property-only props start as `undefined`.

The element is usable as a JS object at this point, but it is not connected to the DOM and [`setup()`](api#setup) has not run.

**2. connectedCallback**

All props are hydrated: each prop's `get` function is called, the raw value is parsed through the schema, and the corresponding atom is set. Then [`setup()`](api#setup) runs.

If [`withContexts()`](api#withcontexts) was used, setup is deferred until all declared contexts resolve. See [Context API](cookbook#context-api) for details.

**3. attributeChangedCallback**

Fires when an observed attribute changes. The new value is validated through the prop's schema and pushed to the corresponding atom. Only attribute-backed props trigger this; JSON and property-only props are not observed.

**4. disconnectedCallback**

All registered cleanups run: event listeners are removed, store subscriptions are cancelled, and any [`onCleanup()`](api#oncleanup) callbacks execute. The cleanup list is then cleared.

**Reconnection**

Re-connecting a previously disconnected component runs [`setup()`](api#setup) again with a fresh cleanup scope. Props that were set programmatically (via the property setter) retain their values; attribute-backed props that were never set programmatically re-read from the DOM.

This means:

- All props are re-hydrated
- Effects and listeners are re-registered
- Refs are re-resolved from the current DOM
- Mixin members are re-assigned

**Cleanup guarantees**

All of these are auto-cleaned on disconnect:

- Event listeners registered via [`ctx.on()`](api#on)
- Store subscriptions from [`ctx.effect()`](api#effect)
- Bindings from [`ctx.bind()`](api#bind)
- Custom teardown from [`ctx.onCleanup()`](api#oncleanup)

If a cleanup function throws, the remaining cleanups still execute. The first error is re-thrown after all cleanups complete.

## FAQ

**Why no Shadow DOM?**

Shadow DOM brings encapsulation at the cost of complexity: styling piercing, slotting quirks, form participation hacks. nanotags targets server-rendered or static markup where global CSS is already the norm. Keeping elements in the light DOM means your existing styles, CSS frameworks, and dev tools work as expected.

**How does it compare to Lit / Stencil / vanilla CE?**

nanotags is intentionally minimal. It doesn't ship a template engine, virtual DOM, or lifecycle beyond connect/disconnect. If you need those, use Lit. If you want a thin reactivity layer over standard custom elements with TypeScript-first DX, nanotags is a good fit.

**Does it work with SSR frameworks?**

Yes. nanotags is designed for hydration: render markup on the server (Astro, PHP, Rails, static HTML), then hydrate on the client. Props are read from attributes, refs are resolved from existing DOM.

**What happens when a context provider is missing?**

When [`withContexts()`](api#withcontexts) is used, setup is deferred until all declared contexts resolve. If a provider never appears, setup never runs and the element stays inert. Use [`consume()`](api#contextconsume) directly for contexts that may or may not be available.

# API

## Builder API

The fluent builder creates components through an immutable chain. Each step returns a new builder instance, accumulating type information:

```typescript
define("x-my-comp") // ComponentBuilder (entry point)
  .withProps((p) => ({ ... })) // + prop types
  .withRefs((r) => ({ ... })) // + ref types
  .setup((ctx) => { ... }); // terminates chain, registers element
```

`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.

### define

`define(name)` / `define(name, setup)`

Entry point for creating a component. Returns a `ComponentBuilder` when called with just a name. For simple components, pass setup directly as the second argument:

```typescript
const Logger = define("x-logger", (ctx) => {
  console.log("connected:", ctx.host.tagName);
});
```

### withProps

Declare validated, reactive attributes via `withProps()`. Each prop becomes:

- An observed HTML attribute (auto-synced via `attributeChangedCallback`)
- A [Nano Stores](https://github.com/nanostores/nanostores) `WritableAtom` at `ctx.props.$propName`
- A typed getter/setter on the element instance

Prop names are camelCase in JS and automatically mapped to kebab-case HTML attributes: `tabIndex` → `tab-index`, `isOpen` → `is-open`. The property setter reflects back to the attribute.

Four built-in validators coerce raw attribute strings to typed values:

| Validator | Coercion | `null` attr |
|-----------|----------|-------------|
| `p.string()` | `String(val)` | `""` |
| `p.number()` | `Number(val)` | `0` |
| `p.boolean()` | `"true"` / `""` → `true`, `"false"` → `false` | `false` |
| `p.oneOf(opts)` | Picklist enum, throws on invalid | throws |

```typescript
.withProps((p) => ({
  title: p.string(),
  count: p.number(),
  open:  p.boolean(),
  size:  p.oneOf(["s", "m", "l"]),
}))
```

Each validator accepts an optional fallback. Pass `null` to make the prop nullable (inferred type becomes `T | null`):

```typescript
.withProps((p) => ({
  label: p.string(null), // string | null
  size:  p.oneOf(["s", "m", "l"], null), // "s" | "m" | "l" | null
}))
```

Props use [Standard Schema](https://github.com/standard-schema/standard-schema) internally, so any compatible validator (Valibot, Zod, ArkType) works as a custom prop schema.

#### JSON props

For complex data that doesn't fit into a string attribute, use `p.json()` with a Standard Schema validator:

```typescript
import * as v from "valibot";

.withProps((p) => ({
  items: p.json(v.array(v.object({ id: v.number(), name: v.string() })), []),
  config: p.json(v.nullable(v.object({ theme: v.string() }))), // no seed -> null
}))
```

JSON props differ from attribute-backed props:

- **Not observed**: not in `observedAttributes`, no `attributeChangedCallback`
- **Setter writes to atom directly**: no attribute created in the DOM
- **Hydrated once on connect**: reads from a `<script type="application/json">` tag, falls back to a kebab-case attribute
- **No seed, no fallback**: the value is `null`, and it goes through the schema, so a schema that rejects `null` throws on connect

```html
<!-- preferred: script tag (no attribute quoting; escape `<` as \u003c if the data can contain </script>) -->
<x-list>
  <script type="application/json" data-prop="items">
    [{ "id": 1, "name": "Alice" }, { "id": 2, "name": "Bob" }]
  </script>
</x-list>

<!-- also works: inline attribute -->
<x-list items='[{"id":1,"name":"Alice"}]'></x-list>
```

After hydration, set programmatically:

```typescript
el.items = [{ id: 3, name: "Charlie" }]; // updates atom, no DOM attribute
```

#### Property-only props

Set `attribute: false` to create a prop that exists only as a JS property and a Nano Stores atom, not an HTML attribute. The accessor is defined in the **constructor**, so it exists right after `document.createElement()`; the value stays `undefined` until the element connects or the property is assigned:

```typescript
.withProps((p) => ({
  label: p.string(), // attribute-backed
  value: { schema: p.string(""), attribute: false }, // property-only
}))
```

This is useful when:

- The value is large or complex (editor content, serialized state): writing kilobytes to a DOM attribute is wasteful
- A component wraps an imperative resource (CodeMirror, canvas) and exposes its state as `.value`
- A parent uses `ctx.bind()` on a child: `bind()` needs the `.value` property to exist from construction time, before setup runs

The full `PropDef` shape:

```typescript
type PropDef<T> = {
  schema: StandardSchemaV1<unknown, T>;
  attribute?: boolean; // default: true
  get?: (host: HTMLElement, key: string) => unknown; // custom hydration reader
};
```

### withRefs

Declare typed element references. Refs query the component's own DOM, skipping elements inside nested custom elements by default.

`r.one()` returns a single element (throws if missing), `r.many()` returns an array (throws if empty). When you pass a tag name, it's used for both **type inference** and **runtime validation**:

```typescript
.withRefs((r) => ({
  trigger: r.one("button"), // HTMLButtonElement, validated
  items:   r.many("li"), // HTMLLIElement[], validated
  circle:  r.one("circle"), // SVGCircleElement, validated
}))
```

SVG tag names work the same way, including camelCase tags like `feGaussianBlur`. For tags shared with HTML (`a`, `script`, `title`, `style`) the HTML variant wins; use the element generic (`r.one<SVGAElement>("a")`) for the SVG one.

By default, refs match `[data-ref="name"]`. Non-tag strings (containing `.`, `#`, `[`, etc.) are treated as CSS selectors:

```typescript
.withRefs((r) => ({
  custom: r.one(".my-trigger"), // Element
  typed:  r.one<HTMLButtonElement>(".my-trigger"), // HTMLButtonElement (type-only)
  any:    r.many<HTMLElement>(), // HTMLElement[] (no tag validation)
}))
```

#### Ref ownership

By default, a component **owns** only its direct refs: elements inside nested custom elements are skipped for proper encapsulation:

```html
<x-parent>
  <span data-ref="title">owned by x-parent</span>
  <x-child>
    <span data-ref="subtitle">owned by x-child, skipped by x-parent</span>
  </x-child>
</x-parent>
```

With **slot-based composition** (e.g. Astro components passed into structural wrappers), refs may end up inside other custom elements even though they conceptually belong to the outer component. To claim ownership, prefix the ref with the component's tag name, `<custom-element>:<ref-name>`:

```html
<x-code-example>
  <x-resizable-panes>
    <button data-ref="x-code-example:tabs">owned by x-code-example</button>
  </x-resizable-panes>
</x-code-example>
```

The JS definition stays the same: each ref automatically checks both `[data-ref="name"]` (direct ownership) and `[data-ref="x-component:name"]` (explicit ownership). You can mix both in the same component.

### withContexts

Declares required contexts on the builder. Setup is deferred until all contexts resolve:

```typescript
import { createContext } from "nanotags/context";

const tabsCtx = createContext<TabsAPI>("tabs");

define("x-tab")
  .withContexts({ tabs: tabsCtx })
  .setup((ctx) => {
    ctx.contexts.tabs.register(ctx.host);
  });
```

If a context never resolves (no provider ancestor), setup never runs. For dynamic or conditional access, use `consume()` directly. See the [Context API guide](cookbook#context-api).

### setup

The `setup()` function receives a [SetupContext](api#setup-context) object and runs when the component connects. It wires up behavior: event listeners, reactive effects, bindings, and cleanup.

#### Mixin (return value)

Returning an object from `setup()` assigns its members to the element instance, fully typed on the constructor:

```typescript
const Timer = define("x-timer").setup((ctx) => {
  let id: number;
  return {
    start() { id = setInterval(() => ctx.emit("tick"), 1000); },
    stop()  { clearInterval(id); },
  };
});

document.body.appendChild(new Timer());
document.querySelector("x-timer")!.start();
```

Mixin members are available only after the element is connected (i.e. after `setup()` runs).

## Setup Context

The `setup()` function receives a context object (`ctx`) with properties and methods for building reactive components.

### host

The component's `HTMLElement` itself. Useful for reading layout, appending content, or passing to external APIs.

```typescript
ctx.host.classList.add("active");
```

### props

Reactive prop stores, each prefixed with `$`. Every prop declared via `withProps()` becomes a Nano Stores `WritableAtom`:

```typescript
ctx.props.$count.get(); // read current value
ctx.props.$count.set(42); // update value
ctx.effect(ctx.props.$count, (val) => { /* react */ });
```

### refs

Resolved element references declared via `withRefs()`:

```typescript
ctx.refs.trigger // HTMLButtonElement
ctx.refs.items // HTMLLIElement[]
```

### contexts

Resolved context values when `withContexts()` is used:

```typescript
ctx.contexts.tabs.register(ctx.host);
ctx.effect(ctx.contexts.tabs.$active, (active) => { /* ... */ });
```

### effect

`effect(store, callback)` / `effect([storeA, storeB], callback)`

Subscribe to one or more Nano Stores atoms. Callback fires immediately with current value(s). Unsubscribes on disconnect.

```typescript
ctx.effect(ctx.props.$count, (count) => {
  ctx.refs.display.textContent = String(count);
});

ctx.effect([storeA, storeB], (a, b) => {
  /* ... */
});
```

### bind

`bind(store, element, options?)`

Two-way binds a DOM control to a Nano Stores atom. The store is the source of truth: the control is set from the store on bind.

**No options**. Auto-detects control type:

| Control | Property | Listens to |
|---------|----------|------------|
| `input[type=checkbox]` | `.checked` | `change` |
| `input[type=number\|range]` | `.valueAsNumber` | `input` |
| `input` / `textarea` | `.value` | `input` |
| `select` | `.value` | `change` |
| Custom element with `.value` | `.value` | `change` |

```typescript
ctx.bind($name, ctx.refs.nameInput);
ctx.bind($agreed, ctx.refs.checkbox);
```

**With options**. Bind to any element property. Omit `event` for one-way (store → element):

```typescript
ctx.bind($theme, el, { prop: "theme" }); // one-way
ctx.bind($val, el, { prop: "value", event: "change" }); // two-way
```

When binding to a custom element, `.value` (or the target property) must be defined via `withProps()`, not as a mixin return value. Props are available from the constructor, while mixin members only exist after `connectedCallback`.

### on

`on(target, type, listener, options?)`

Attach event listeners with automatic cleanup. Accepts a single element, an array, `document`, or `window`. Event types are fully inferred for each target:

```typescript
ctx.on(ctx.refs.trigger, "click", (e) => { /* ... */ });
ctx.on(ctx.refs.items, "mouseenter", (e) => { /* ... */ });
ctx.on(document, "keydown", (e) => { /* ... */ });
```

### emit

`emit(event)` / `emit(name, detail?, options?)`

Dispatch an existing `Event` or construct and dispatch a bubbling `CustomEvent`

```typescript
ctx.emit(new CustomEvent("reset"));
ctx.emit("change", { value: 42 });
```

### getElement

`getElement(selector)` / `getElement(root, selector)`

Asserts that the element exists and returns it with the correct type, no null checks or casting. Tag-name selectors narrow the return type automatically. Throws if nothing matches.

```typescript
ctx.getElement("input"); // HTMLInputElement (throws if missing)
ctx.getElement("circle"); // SVGCircleElement
ctx.getElement(customParent, ".item"); // Element
// type-only, no runtime tag check
ctx.getElement<HTMLInputElement>(customRoot, ".my-input"); // HTMLInputElement
```

### getElements

`getElements(selector)` / `getElements(root, selector)`

Works the same as [`getElement()`](api#getelement) but returns **all** matching elements as a typed `Array` (not a `NodeList`). Throws if none found.

```typescript
ctx.getElements("button"); // HTMLButtonElement[]
// type-only, no runtime tag check
ctx.getElements<"input">(customRoot, ".field"); // HTMLInputElement[]
```

Both methods are primarily useful for dynamic queries inside [`renderList()`](api#renderlist) update callbacks or other imperative code. For static element references, prefer [refs](api#withrefs).

For nullable results, use `ctx.host.querySelector()/querySelectorAll()` directly.

### onCleanup

`onCleanup(callback)`

Register arbitrary teardown logic to run on disconnect:

```typescript
const raf = requestAnimationFrame(tick);
ctx.onCleanup(() => cancelAnimationFrame(raf));
```

## Context API

Cross-component communication for parent-child relationships. Import from the separate `nanotags/context` entry point (~0.4 KB).

```typescript
import { createContext } from "nanotags/context";
```

For a conceptual overview, see the [Context API guide](cookbook#context-api).

### createContext

`createContext<T>(name?)`

Creates a typed context key with `provide()` and `consume()` methods. The optional `name` is used as the `Symbol` description for debugging.

```typescript
type TabsAPI = {
  register: (el: Element) => void;
  $active: WritableAtom<string>;
};

const tabsContext = createContext<TabsAPI>("tabs");
```

### context.provide

`contextKey.provide(ctx, value)`

Registers the component as a context provider. Any descendant that consumes this context key will receive `value`.

The `ctx` parameter requires `host` (HTMLElement) and `onCleanup`; the setup context satisfies this. The provider's event listener is auto-cleaned on disconnect.

```typescript
define("x-tabs").setup((ctx) => {
  const $active = atom("");
  tabsContext.provide(ctx, {
    register: (el) => { /* ... */ },
    $active,
  });
});
```

On connect, `provide()` also dispatches a `context-provider` event to resolve any pending consumers that connected before the provider.

### context.consume

`contextKey.consume(ctx, callback)`

Requests the context value from the nearest ancestor provider. The callback receives the provided value.

```typescript
define("x-tab").setup((ctx) => {
  tabsContext.consume(ctx, (tabs) => {
    tabs.register(ctx.host);
    ctx.effect(tabs.$active, (active) => { /* ... */ });
  });
});
```

If a provider is already connected, the callback fires synchronously. If not, the request is queued and resolved when the provider calls `provide()`. Pending requests are cleaned up on disconnect.

## Rendering

Keyed reconciliation utilities for dynamic content. Import from the separate `nanotags/render` entry point (~0.4 KB).

```typescript
import { render, renderList } from "nanotags/render";
```

Both `render()` and `renderList()` **own the entire container**: any child not part of the current render cycle is removed. Containers must be dedicated to rendered content.

### render

`render(container, template, options?)`

Single-item rendering. Options are optional. Omit for static templates (loading spinners, error states, empty placeholders):

```typescript
render(container, loadingTpl); // static
render(container, profileTpl, { // data-driven
  data: user,
  update: (el, u) => { el.setAttribute("name", u.name); },
});
```

Switching templates replaces the previous element.
Internally delegates to `renderList()` with a single-element array.

### renderList

`renderList(container, template, options)`

Reconcile a data array against DOM by key. Creates, updates, removes, and reorders elements without recreating the whole list. Skips `update` when the item reference hasn't changed (`===`).

```html
<ul data-ref="list">
  <template data-ref="rowTpl">
    <li><span class="name"></span></li>
  </template>
</ul>
```

```typescript
ctx.effect($users, (users) => {
  renderList(ctx.refs.list, ctx.refs.rowTpl, {
    data: users,
    key: (user) => user.id,
    update: (el, user) => {
      ctx.getElement(el, ".name").textContent = user.name;
    },
  });
});
```

**Options:**

| Option | Type | Description |
|--------|------|-------------|
| `data` | `readonly T[]` | Array of items to render |
| `key` | `(item: T, index: number) => string \| number` | Unique key per item |
| `update` | `(el: Element, item: T) => void` | Called on create and when the item reference changes |

## Testing API

Helpers from `nanotags/testing` for testing components in jsdom or happy-dom. They work with any test runner. They never end up in a browser bundle, because nothing imports them at runtime. For a guided walkthrough, see [Testing](cookbook#testing) in the Cookbook.

When a component is in `HTMLElementTagNameMap`, or you pass its class, the helpers are typed from its definition: `h` checks prop names and values, `mount` and `create` return the component's element type, and `ref`/`refs` only accept its ref names.

### h

`h(target, props?, ...children): Markup`

Builds the HTML a server would render for an element, in the shape of React's `createElement`. `target` is a tag name or a component class. Children are more `h` calls, or raw HTML strings for markup copied as is.

```typescript
import { h, mount } from "nanotags/testing";

const markup = h(
  "x-chart",
  { size: "lg", disabled: false, bars: [{ label: "a", value: 1 }] },
  h("ul", { "data-ref": "list" }),
  h("template", { "data-ref": "tpl" }, h("li")),
);
const host = mount(markup);
```

| Prop | Written as |
|------|------------|
| Attribute prop (`size`) | an attribute with the kebab-cased name |
| JSON prop from `p.json()` (`bars`) | a `<script type="application/json" data-prop="bars">` seed |
| Anything else (`id`, `class`, `data-*`, `aria-*`, `viewBox`, props on plain elements) | an attribute, name as given |

- `undefined` is skipped. `null` and `false` leave an attribute out, `true` writes it empty, and numbers become strings. A JSON prop writes `null` and `false` into its seed.
- Property-only props (`{ schema, attribute: false }`) cannot be written as markup, and on a typed component `h` rejects them. Set them on a host built with `create`, before `connect`.
- The result is a `Markup`. It remembers the element type, so `mount` returns it typed, and inside a template literal it turns into its HTML.
- Throws for a string that is not a tag name, and for a custom element tag that is not defined yet (usually a missing import).
- When a key is not one of the component's attribute props, `h` constructs one instance with the attribute props set, to tell a JSON prop from a plain attribute. If that throws, so does `h`. Otherwise a constructor error surfaces from `mount` or `create`.

### mount

`mount(target, parent?): HTMLElement`

Puts markup on the page and connects it. `target` can be:

- markup from `h`,
- a tag name or component class, the same as `h(target)`,
- a raw HTML string, for the page around the component.

Returns the first element, typed when it comes from `h`, a tag name or a class. Everything it adds is removed by `cleanup`.

```typescript
const containerMarkup = h("div", { "data-scroll-container": true });
const markup = h("x-scroll-controls", null, CHILDREN);

const container = mount(containerMarkup);
const host = mount(markup, container);
```

The markup is fully built before anything connects, so a component finds its children, attributes and JSON seeds in place. It is inserted in one go, so a component also sees the siblings after it. (happy-dom connects elements one by one, so there a component only sees the siblings before it.)

`parent` defaults to `document.body` and must be on the page. `mount` throws if the markup has no element, if a tag name or class is not defined, or if the parent is not on the page. Raw HTML goes in as is, undefined tags included, so a test can define a component after mounting it. An error thrown in a component's setup is rethrown from `mount`, in both jsdom and happy-dom.

### create

`create(target): HTMLElement`

Builds one element like `mount`, but does not put it on the page. Call `connect` when the test is ready. Use it to set things up before the component's setup runs: stub a neighbouring element, fake layout sizes, or set a property the way a parent would. Throws unless the markup has exactly one root element.

```typescript
const markup = h("x-share-button", null, CHILDREN);
const host = create(markup);
const tooltip = stubElement(ref(host, "tooltip"), { open: false });
connect(host);

expect(tooltip.writes("open")).toEqual([false]);
```

### connect

`connect(host, parent?): host`

Puts a host on the page, which runs its setup, or parks it until every context it declares has a provider. Without `parent`, a host from `disconnect` goes back where it was, and any other host goes into `document.body`. Throws if the parent is not on the page, and rethrows errors from setup.

### disconnect

`disconnect(host): host`

Takes the host off the page, which runs its cleanup, and rethrows errors from that cleanup. Call `connect(host)` afterwards to put it back and run setup again.

```typescript
disconnect(host);
host.bars = []; // nothing reacts while disconnected
connect(host);

expect(ref(host, "list").children).toHaveLength(0);
```

### cleanup

`cleanup(): void`

Removes everything the helpers added since the last call and undoes every `provideContext`. Call it after each test: `afterEach(cleanup)`. It leaves other DOM alone. If a component's cleanup throws, `cleanup` still removes everything else first, then rethrows the error, or an `AggregateError` when several failed.

### ref

`ref(host, name): Element`

Finds a ref the same way the component does, and throws if it is missing.

- After setup, it returns the element the component found, including refs declared with a selector.
- Before setup, it looks for `data-ref="name"` (or `data-ref="host-tag:name"`), skipping refs that belong to a nested component.
- On a connected host whose setup never ran (usually a missing context provider), it throws an error that says so.

On a typed host, `name` must be one of its `r.one` refs, and the result has the type the ref declares. Pass a type argument for markup the test added itself.

```typescript
ref(host, "list"); // HTMLUListElement, from r.one("ul")
ref<HTMLDialogElement>(host, "fixture").open;
```

### refs

`refs(host, name): Element[]`

Like `ref`, for `r.many` refs. Returns all matches in document order and throws if there are none. Unlike `querySelectorAll`, it skips refs inside nested components.

```typescript
const items = refs(host, "items");
const firstButton = ref<HTMLButtonElement>(items[0]!, "button");
```

### provideContext

`provideContext(host, key, value): void`

Provides a context on `host`, so a component that uses `withContexts` can be tested without its real provider. The order does not matter: a component mounted first waits for the provider, sets up when `provideContext` runs, and any error from that setup is rethrown here. `cleanup` removes the provider. The context key must be exported from the module that creates it.

```typescript
const menubarMarkup = h("ul", { role: "menubar" });
const markup = h("x-menu-item", null, CHILDREN);

const menubar = mount(menubarMarkup);
provideContext(menubar, menuContext, { moveFocus: vi.fn() });
const host = mount(markup, menubar);
```

### stubElement

`stubElement(el, shape): StubbedElement`

Replaces the members of an element the component talks to, such as a tooltip or a modal, and records how the component uses them. This way the test does not need the real element. It also works when `el` is a registered component, but its methods come from its setup: stub them once it has connected. `stubElement` throws if the setup has not run yet, and a reconnect brings the real methods back.

- A value in `shape` becomes a property that records every write.
- A function becomes a method that records every call. It also runs, with the element as `this`, and its return value goes back to the caller.

```typescript
const modal = stubElement(ref(host, "detailsModal"), {
  isOpen: false,
  open() {
    modal.el.isOpen = true;
  },
});

ref(host, "trigger").click();

expect(modal.calls("open")).toEqual([[]]);
expect(modal.get("isOpen")).toBe(true);
```

| Member | Description |
|--------|-------------|
| `el` | The same element, typed as if it had the stubbed members |
| `get(key)` | The current value of a stubbed property |
| `writes(key)` | Every value written to a stubbed property, in order |
| `calls(key)` | The arguments of every call to a stubbed method, in order |
| `reset()` | Forgets recorded writes and calls, keeps current values |

To record what the component writes during setup, stub a host built with `create` before calling `connect`.

### uniqueTag

`uniqueTag(prefix = "test"): string`

Returns a new custom element name, `x-<prefix>-<n>`, for a component defined inside a test. A tag name can only be defined once per page, so tests that reuse a fixed name would share one component.

### DOM differences

jsdom and happy-dom are not browsers. The helpers smooth over one difference: jsdom does not throw errors from a component's constructor, setup or cleanup, but `mount`, `create`, `connect`, `disconnect`, `cleanup` and `provideContext` rethrow them in both. For the other gaps and ready-made shims, see [DOM differences](cookbook#dom-differences).

## TypeScript

### TypedEvent

`TypedEvent<Target, Detail>`

A type-only helper that narrows `CustomEvent` to a specific `target` and `detail`. Useful for defining type-safe custom events:

```typescript
import type { TypedEvent } from "nanotags";

type TabsChangedEvent = TypedEvent<
  InstanceType<typeof XTabs>,
  { index: number }
>;
```

Combine with `HTMLElementEventMap` augmentation for app-wide type safety. See [Typed custom events](cookbook#typed-custom-events) and [Augmenting HTMLElementTagNameMap](cookbook#augmenting-htmlelementtagnamemap) recipes.

# Cookbook

## Best Practices

### Code structure

Keep a consistent order inside `setup()` so components read predictably:

1. **Variable definitions**: atoms, constants, cached values
2. **Methods**: named functions for reusable logic
3. **Event handlers**: `ctx.on()` calls
4. **Effects**: `ctx.effect()` subscriptions
5. **Return mixin**: the optional object returned from setup

```typescript
define("x-search")
  .withProps((p) => ({ query: p.string() }))
  .withRefs((r) => ({ input: r.one("input"), results: r.one("ul") }))
  .setup((ctx) => {
    // 1. Variables
    const $filtered = computed(ctx.props.$query, (q) => filterItems(q));

    // 2. Methods
    function clearSearch() {
      ctx.props.$query.set("");
    }

    // 3. Event handlers
    ctx.on(ctx.refs.input, "input", (e) => {
      ctx.props.$query.set(e.currentTarget.value);
    });

    // 4. Effects
    ctx.effect($filtered, (items) => {
      renderList(ctx.refs.results, tpl, {
        data: items,
        key: (item) => item.id,
        update: (el, item) => {
          el.textContent = item.name;
        },
      });
    });

    // 5. Return mixin
    return { clearSearch };
  });
```

### Refs over manual selection

Prefer [`withRefs()`](api#withrefs) for elements you always need. Use [`ctx.getElement()`](api#getelement) / [`ctx.getElements()`](api#getelements) only for dynamic queries (e.g. inside [`renderList()`](api#renderlist) update callbacks):

```typescript
// Good: static ref
.withRefs((r) => ({ trigger: r.one("button") }))

// Good: dynamic query inside renderList update
update: (el, item) => {
  ctx.getElement(el, ".name").textContent = item.name;
}
```

### Reactive state with atoms

When state changes over time, use [Nano Stores](https://github.com/nanostores/nanostores) atoms instead of local `let` variables. Atoms integrate with [`ctx.effect()`](api#effect) and [`ctx.bind()`](api#bind), keeping updates declarative:

```typescript
// Avoid: imperative variable + manual DOM update
let count = 0;
ctx.on(ctx.refs.btn, "click", () => {
  count++;
  ctx.refs.display.textContent = String(count);
});

// Prefer: atom + effect
const $count = atom(0);
ctx.on(ctx.refs.btn, "click", () => {
  $count.set($count.get() + 1);
});
ctx.effect($count, (count) => {
  ctx.refs.display.textContent = String(count);
});
```

The atom approach scales better: multiple effects can react to the same state, and the current value is always accessible via `.get()`.

### Effects over imperative handlers

When a DOM update depends on state, express it as an [`ctx.effect()`](api#effect) rather than scattering updates across event handlers. Effects make the data flow explicit: state changes in one place, the DOM reacts in another:

```typescript
// Avoid: updating DOM inside the handler
ctx.on(ctx.refs.toggle, "click", () => {
  const next = !ctx.props.$open.get();
  ctx.props.$open.set(next);
  ctx.host.setAttribute("aria-expanded", String(next));
  ctx.refs.body.hidden = !next;
});

// Prefer: handler changes state, effect updates DOM
ctx.on(ctx.refs.toggle, "click", () => {
  ctx.props.$open.set(!ctx.props.$open.get());
});

ctx.effect(ctx.props.$open, (open) => {
  ctx.host.setAttribute("aria-expanded", String(open));
  ctx.refs.body.hidden = !open;
});
```

## Components Communication

Parents pass data down through props. Children notify parents via custom events ([`ctx.emit()`](api#emit) / [`ctx.on()`](api#on)). When a child needs ongoing access to parent state, use the [context protocol](cookbook#context-api) (`nanotags/context`). Unrelated components share [Nano Stores](https://github.com/nanostores/nanostores) atoms directly.

### Parent to child

The primary channel. A parent sets attributes or properties on its children, and each child reacts via its own prop stores:

```typescript
// Parent sets attribute, child's $mode atom updates automatically
childEl.setAttribute("mode", "dark");

// Or via property
childEl.mode = "dark";
```

### Child to parent

Standard DOM events. The child dispatches with [`ctx.emit()`](api#emit), the parent listens with [`ctx.on()`](api#on):

```typescript
// Child
ctx.emit("tab:select", { index: 2 });

// Parent
ctx.on(ctx.refs.tabs, "tab:select", (e) => {
  console.log(e.detail.index); // 2
});
```

### Child needs parent state or API

Use the [Context protocol](cookbook#context-api). The parent exposes a value via [`provide()`](api#contextprovide), descendants receive it via [`consume()`](api#contextconsume) or [`withContexts()`](api#withcontexts). This avoids tight coupling and works regardless of DOM depth.

When components form a logical group (Tabs/Tab, Accordion/Panel), the parent provides a typed API and children declare required contexts:

```typescript
import { createContext } from "nanotags/context";

type TabsAPI = { $active: WritableAtom<string> };
const tabsContext = createContext<TabsAPI>("tabs");

const XTabs = define("x-tabs").setup((ctx) => {
  const $active = atom("");

  tabsContext.provide(ctx, {
    $active,
  });
});

define("x-tab-panel")
  .withProps((p) => ({ value: p.string() }))
  .withContexts({ tabs: tabsContext })
  .setup((ctx) => {
    ctx.effect(ctx.contexts.tabs.$active, (active) => {
      ctx.host.hidden = active !== ctx.props.$value.get();
    });
  });
```

[`withContexts()`](api#withcontexts) defers setup until all declared contexts resolve. For dynamic or conditional access, use [`consume()`](api#contextconsume) directly.

### Siblings or unrelated components

Share a [Nano Stores](https://github.com/nanostores/nanostores) atom directly. Import the same store in both components and react via [`ctx.effect()`](api#effect):

```typescript
// shared store (plain module)
export const $theme = atom("light");

// component A
ctx.on(ctx.refs.toggle, "click", () => {
  $theme.set($theme.get() === "light" ? "dark" : "light");
});

// component B
ctx.effect($theme, (theme) => {
  ctx.host.dataset.theme = theme;
});
```

### Combining patterns

You can provide a Nano Stores atom through the Context protocol so that siblings under the same parent share state without a global import:

```typescript
const filterCtx = createContext<WritableAtom<string>>("filter");

define("x-filter-panel").setup((ctx) => {
  const $filter = atom("");
  filterCtx.provide(ctx, $filter);
});

// child A writes to the store
define("x-search-input")
  .withRefs((r) => ({ input: r.one("input") }))
  .withContexts({ filter: filterCtx })
  .setup((ctx) => {
    ctx.on(ctx.refs.input, "input", (e) => {
      ctx.contexts.filter.set(e.currentTarget.value);
    });
  });

// sibling B reacts to changes
define("x-results-list")
  .withContexts({ filter: filterCtx })
  .setup((ctx) => {
    ctx.effect(ctx.contexts.filter, (query) => {
      // filter visible items
    });
  });
```

## Context API

The Context API enables cross-component communication for parent-child relationships without tight coupling. It's imported from the separate `nanotags/context` entry point (~0.4 KB).

### When to use context

Use context when a child component needs **ongoing access to parent state or API**, not just a one-time value (use props) or a fire-and-forget notification (use events).

### How it works

The protocol uses two DOM events following the [Web Components Community Context Protocol](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md):

**Normal case** (parent connects first):

1. [`provide()`](api#contextprovide) registers a `context-request` event listener on the host
2. [`consume()`](api#contextconsume) dispatches a `context-request` event that bubbles up
3. The provider catches it, stops propagation, and calls the callback with the value
4. The callback runs synchronously

**Late provider** (child upgrades before parent):

1. The `consume()` dispatch goes unhandled: no provider is listening yet
2. A lazy document-level handler stores the pending request
3. When the parent's `provide()` runs, it dispatches a `context-provider` event
4. The document handler re-dispatches `context-request` from pending consumers, resolving them

This means context works regardless of element upgrade order.

### provide vs consume vs withContexts

There are two ways to consume context. Prefer `withContexts()`; use `consume()` only when the context is optional.

**[`withContexts()`](api#withcontexts) (declarative, preferred)**: declares required contexts on the builder. Setup is deferred until **all** contexts resolve:

```typescript
define("x-tab")
  .withContexts({ tabs: tabsCtx })
  .setup((ctx) => {
    // ctx.contexts.tabs is guaranteed to be available here
    ctx.contexts.tabs.register(ctx.host);
  });
```

Use when: the component **cannot function** without the context value. If a provider never appears, setup never runs and the element stays inert.

**[`consume()`](api#contextconsume) (imperative)**: requests context inside setup. The callback runs when/if the context resolves:

```typescript
define("x-widget").setup((ctx) => {
  // Setup runs immediately, context is optional
  tabsCtx.consume(ctx, (tabs) => {
    tabs.register(ctx.host);
  });
});
```

Use when: the context is **optional**; the component should still function without it, or you need to handle the "no provider" case yourself.

Context consumers registered via `consume()` are automatically cleaned up on disconnect: pending requests are removed from the document-level queue. Providers remove their `context-request` listener on disconnect.

## TypeScript

Both patterns below use TypeScript [global augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#global-augmentation) to extend built-in DOM interfaces.

### Augmenting HTMLElementTagNameMap

Register your element so that refs ([`r.one()`/`r.many()`](api#withrefs)), [`ctx.getElement()`](api#getelement), [`ctx.getElements()`](api#getelements), and standard DOM APIs (`querySelector`, `createElement`) return properly typed instances:

```typescript
declare global {
  interface HTMLElementTagNameMap {
    "x-my-el": InstanceType<typeof MyEl>;
  }
}

const MyEl = define("x-my-el").withProps(/* ... */).setup(/* ... */);
```

This also enables typed ref lookups in other components:

```typescript
r.one("x-my-el"); // typed as InstanceType<typeof MyEl>, validated at runtime
```

### Typed custom events

Use [`TypedEvent`](api#typedevent) to define type-safe events, then augment `HTMLElementEventMap` so that [`ctx.on()`](api#on), [`ctx.emit()`](api#emit), and `addEventListener` are fully typed:

```typescript
import type { TypedEvent } from "nanotags";

type SelectionChangeEvent = TypedEvent<
  InstanceType<typeof XListBox>,
  { selected: string[] }
>;

declare global {
  interface HTMLElementEventMap {
    "listbox:change": SelectionChangeEvent;
  }
}

// Emit (inside x-listbox setup):
ctx.emit("listbox:change", { selected: ["a", "b"] });

// Listen (anywhere in the app):
ctx.on(listboxEl, "listbox:change", (e) => {
  e.target; // XListBox instance
  e.detail.selected; // string[]
});
```

### Combining both augmentations

For a complete component definition, declare both the element and its events together:

```typescript
import { define } from "nanotags";
import type { TypedEvent } from "nanotags";

type TabsChangedEvent = TypedEvent<
  InstanceType<typeof XTabs>,
  { index: number }
>;

declare global {
  interface HTMLElementTagNameMap {
    "x-tabs": InstanceType<typeof XTabs>;
  }
  interface HTMLElementEventMap {
    "tabs:changed": TabsChangedEvent;
  }
}

const XTabs = define("x-tabs")
  .withProps((p) => ({ active: p.string("") }))
  .setup((ctx) => {
    // ...
  });
```

## Attachments

Attachments are reusable functions that receive the setup context (`ctx`) and wire up behavior—effects, event listeners, cleanup—without creating a new component.

Unlike regular helper functions, attachments are **lifecycle-aware**: because they receive `ctx`, everything they register via [`ctx.on()`](api#on), [`ctx.effect()`](api#effect), or [`ctx.onCleanup()`](api#oncleanup) is automatically cleaned up when the host component disconnects. A plain helper that calls `addEventListener` would leak listeners; an attachment never does.

Attachments also compose naturally with the [context protocol](cookbook#context-api). An attachment can call [`consume()`](api#contextconsume) to access ancestor state, or accept a context value as a parameter, letting you build reusable behaviors (keyboard navigation, drag handling, focus traps) that participate in the component tree without being components themselves.

### Writing your own

An attachment is just a function, no special API needed. Follow these conventions:

1. Accept `ctx: SetupContext<{}, {}>` as the first parameter, so it composes with any component
2. Use [`ctx.on()`](api#on), [`ctx.effect()`](api#effect), [`ctx.onCleanup()`](api#oncleanup) for auto-cleanup
3. Accept configuration via additional parameters or an options object
4. Optionally return state or methods for the calling component

```typescript
export function attachClickOutside(ctx: SetupContext<{}, {}>, callback: () => void) {
  ctx.on(document, "click", (e) => {
    if (!ctx.host.contains(e.target as Node)) callback();
  });
}
```

### Example: roving focus

Arrow-key navigation through a group of focusable elements:

```typescript
export function attachRovingFocus(
  ctx: SetupContext<{}, {}>,
  container: HTMLElement,
  items: HTMLElement[],
  options: { onFocus?: (el: HTMLElement) => void } = {},
) {
  function setActive(index: number) {
    items.forEach((item, i) => {
      item.setAttribute("tabindex", i === index ? "0" : "-1");
    });
  }

  setActive(0);

  ctx.on(container, "keydown", (e) => {
    const current = items.indexOf(document.activeElement as HTMLElement);
    if (current === -1) return;

    let next = -1;
    if (e.key === "ArrowRight") next = (current + 1) % items.length;
    if (e.key === "ArrowLeft")
      next = (current - 1 + items.length) % items.length;
    if (e.key === "Home") next = 0;
    if (e.key === "End") next = items.length - 1;

    if (next !== -1) {
      e.preventDefault();
      setActive(next);
      items[next].focus();
      options.onFocus?.(items[next]);
    }
  });
}
```

Usage:

```typescript
define("x-tabs")
  .withRefs((r) => ({ tablist: r.one("div"), tabs: r.many<HTMLElement>("[role=tab]") }))
  .setup((ctx) => {
    attachRovingFocus(ctx, ctx.refs.tablist, ctx.refs.tabs, {
      onFocus: (el) => activate(el.dataset.value),
    });
  });
```

## Testing

`nanotags/testing` helps you test components in jsdom or happy-dom, with any test runner. It builds the markup a page would have, connects the component, and gives you typed access to its refs. The [Testing API](api#testing-api) lists every helper; this section shows how to use them.

### What to test

You have two options, and you can pick per component:

- **Test the logic on its own.** If a component is mostly glue, move the real logic into a plain module next to it and test that module with ordinary unit tests. The component file stays a thin layer of DOM wiring that the type checker already covers.
- **Mount the component and test its behaviour.** If what matters is how the component reacts in the DOM (reading its initial data, updating when a prop changes, reusing list items, cleaning up on disconnect), mount it and assert what the DOM shows. That is what `nanotags/testing` is for.

```
ui/Chart/
  components.ts    define() + refs + one effect
  utils.ts         deriveChartBars(...)   <- plain logic, easy to test
  utils.test.ts
```

### Setup

The helpers need a DOM but do not ship one, so install jsdom or happy-dom and tell your runner to use it. Only test files import `nanotags/testing`, and no runtime entry does, so it stays out of your browser bundle.

```typescript
// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: { environment: "jsdom" },
});
```

### Your first test

```typescript
import { afterEach, expect, it } from "vitest";
import { cleanup, h, mount, ref } from "nanotags/testing";

// Registers x-char-count and adds it to HTMLElementTagNameMap.
import "./components";

afterEach(cleanup);

it("counts characters as the user types", () => {
  const markup = h(
    "x-char-count",
    null,
    h("textarea", { "data-ref": "field", maxlength: 10 }),
    h("span", { "data-ref": "count" }, "0"),
  );
  const host = mount(markup);
  const field = ref(host, "field"); // HTMLTextAreaElement, from r.one("textarea")

  field.value = "hello";
  field.dispatchEvent(new Event("input", { bubbles: true }));

  expect(ref(host, "count").textContent).toBe("5");
});
```

Step by step:

1. `h("x-char-count", null, ...children)` builds the HTML for the component. The nested `h` calls build what goes inside it: the same markup the server renders.
2. `mount(markup)` puts that HTML on the page and returns the component element, called the **host**. The component sets up exactly as it would in the browser.
3. `ref(host, "field")` finds a ref the same way the component does.
4. `afterEach(cleanup)` removes everything the test added, so the next test starts clean.

Why not build the element by hand? The order is easy to get wrong. If you append the element first and set its `innerHTML` after, the component has already looked for its refs, found nothing, and thrown. `mount` builds everything first and connects it last, so the component sees the full markup, just like on a real page.

### Typed tests

If the component adds itself to `HTMLElementTagNameMap` (see [Augmenting HTMLElementTagNameMap](#augmenting-htmlelementtagnamemap)), the helpers know its props and refs:

- `mount` returns the chart element for `h("x-chart", ...)` markup, so `host.bars = [...]` needs no cast.
- `h("x-chart", { ... })` checks every prop name and value.
- `ref(host, "list")` only accepts the component's `r.one` refs and returns the element type the ref declares.

A typo becomes a compile error instead of a confusing test failure. Passing the component class instead of a tag name works the same way.

For markup the test adds itself, pass the element type: `ref<HTMLElement>(host, "fixture")`. A tag that is not in the map returns a plain `HTMLElement`.

### Building markup with `h`

`h(tag, props, ...children)` works like React's `createElement`, but it returns HTML. On a real page the server renders a component's attributes, its JSON data and its inner markup. `h` gives you each of those:

```typescript
const markup = h(
  "x-calculator",
  { storageTb: 100, readsPct: undefined, presets: [{ id: "a", label: "A" }] },
  CHILDREN,
);
const host = mount(markup);
```

| You pass                                 | `h` writes                                             | On the page this is               |
| ---------------------------------------- | ------------------------------------------------------ | --------------------------------- |
| An attribute prop (`storageTb`)          | `storage-tb="100"`                                     | an attribute the server rendered  |
| A JSON prop (`presets`, from `p.json()`) | `<script type="application/json" data-prop="presets">` | the JSON seed the server rendered |
| Children                                 | the HTML inside the element                            | the component's template          |

A few rules keep test data simple:

- `undefined` is skipped. `null` and `false` leave the attribute out. So you can pass optional values straight through, and a missing one tests the prop's fallback.
- `true` writes an empty attribute, like `disabled=""`. Numbers become strings.
- Prop names are written in kebab-case, so name them after the prop: `storageTb` becomes `storage-tb`. Other attributes (`id`, `class`, `data-*`, `aria-*`, `viewBox` on an SVG) are written exactly as given.
- Children are more `h` calls, or raw HTML strings for markup copied as is. Nested `h` calls are typed too, so a component inside the markup gets checked props of its own:

```typescript
const markup = h("x-dashboard", null, h("x-chart", { bars }, CHART_CHILDREN));
mount(markup);
```

Property-only props (`{ schema, attribute: false }`) have no place in markup, and on a typed component `h` rejects them. Set them as properties before the component connects, as shown in [Before the component connects](#before-the-component-connects).

### The page around the component

Many components read DOM they do not own: the nav a scroll spy watches, the container a set of controls scrolls, the link that opens a modal. Mount that too, and `cleanup` removes it as well. `mount` also accepts a raw HTML string, handy for a larger piece of page copied as is.

```typescript
const containerMarkup = h("div", {
  "data-scroll-container": true,
  "data-scroll-id": "cards",
});
const markup = h("x-scroll-controls", { scrollId: "cards" }, CHILDREN);

mount(containerMarkup);
const host = mount(markup);

expect(ref(host, "prev").disabled).toBe(true);
```

`mount` returns the first element of the markup. It inserts everything at once, so a component sees the siblings that come after it, just like on a parsed page. happy-dom is the exception: it sets up each element as it is inserted, so a component there only sees the siblings before it. If a component reads its surroundings in setup, mount the surroundings first.

To put a component inside another element, pass that element as the second argument. It must already be on the page:

```typescript
const markup = h("x-cms-form", null, CHILDREN);

const dialog = mount("dialog");
const host = mount(markup, dialog);
```

### Before the component connects

A component sets up as soon as it connects. Sometimes the test needs to do something first: replace a neighbouring element with a stub, fake layout sizes, or set a property the way a parent would. Build the element with `create` instead of `mount`. It is ready but not yet on the page. Then call `connect`:

```typescript
const markup = h("x-share-button", null, CHILDREN);
const host = create(markup);
host.label = "Share"; // a property a parent would set before connect
connect(host); // setup runs now
```

### Stubbing other elements

Components often talk to elements they do not own: a tooltip, a modal, another component. Do not import the real one just to make a ref resolve. Replace it with `stubElement`. The test stays about one component, and it does not depend on the order in which modules register their elements.

`stubElement(el, shape)` gives the element the members in `shape`:

- A value becomes a property that remembers every write. Read them with `writes(name)`, and the current value with `get(name)`.
- A function becomes a method that remembers every call. Read them with `calls(name)`. The function also runs, with the element as `this`, so the stub can act like the real thing.

```typescript
const modal = stubElement(ref(host, "detailsModal"), {
  isOpen: false,
  open() {
    modal.el.isOpen = true;
  },
});

ref(host, "detailsTrigger").click();

expect(modal.calls("open")).toEqual([[]]);
expect(modal.get("isOpen")).toBe(true);
```

`modal.el` is the same element, typed as if it had those members. The stubbed element can even be a registered component. Its props can be stubbed at any time, but its methods come from its setup, which would replace a stub. So stub its methods once it has connected: `stubElement` throws if its setup has not run yet. Reconnecting it runs setup again and brings the real methods back.

A stub records only what happens after you install it. On a mounted host, the component's setup has already run, so its first writes are not recorded. To check them, stub before connecting:

```typescript
const markup = h("x-share-button", null, CHILDREN);
const host = create(markup);
const tooltip = stubElement(ref(host, "tooltip"), { open: false });
connect(host);

expect(tooltip.writes("open")).toEqual([false]);
```

If the rest of the test only cares about later writes, drop these with `tooltip.reset()`.

### Events

Listen with your runner's spy. A listener on the host goes away with it. A listener on `document` or `window` outlives the test, so remove it afterwards.

```typescript
const onPicked = vi.fn<(event: CustomEvent<string>) => void>();
host.addEventListener("picked", onPicked);

ref(host, "option").click();

expect(onPicked.mock.calls.map(([event]) => event.detail)).toEqual(["a"]);
```

If the event has no payload and you need the state at the moment it fired, read the state inside the listener: `host.addEventListener("change", () => values.push(host.value))`. Reading `host.value` later only shows the last value.

### Contexts

A component that uses `withContexts` waits until every context has a provider. Instead of mounting the real provider (with its own markup, refs and setup), use `provideContext`.

Take the tabs from [Child needs parent state or API](#child-needs-parent-state-or-api). To test `x-tab-panel` on its own, the test needs the same context key the component uses, so export it from the module that creates it:

```typescript
// tabs/context.ts
import type { WritableAtom } from "nanostores";
import { createContext } from "nanotags/context";

export type TabsAPI = { $active: WritableAtom<string> };
export const tabsContext = createContext<TabsAPI>("tabs");
```

Then any element on the page can stand in for `x-tabs`:

```typescript
import { atom } from "nanostores";
import { afterEach, expect, it } from "vitest";
import { cleanup, h, mount, provideContext } from "nanotags/testing";

import { tabsContext } from "./context";
// Registers x-tab-panel.
import "./components";

afterEach(cleanup);

it("shows the panel only while its tab is active", () => {
  const markup = h("x-tab-panel", { value: "b" });
  const $active = atom("a");

  const tabs = mount("div");
  provideContext(tabs, tabsContext, { $active });
  const panel = mount(markup, tabs);

  expect(panel.hidden).toBe(true);

  $active.set("b");
  expect(panel.hidden).toBe(false);
});
```

The value you provide is whatever the real provider would give: here a plain atom the test controls. The order does not matter. A component mounted before its provider waits and sets up once the provider appears, just like at runtime. `cleanup` removes the provider.

Without a provider the component never sets up, and it looks broken: no effects run and its methods are missing. `ref` and `refs` catch this. On a connected host that has not set up, they throw an error that names the missing provider.

### Components defined in a test

Some tests need a small component of their own, such as a wrapper that runs an attachment, or a provider for a context. A tag name can only be defined once per page, and defining it again keeps the first version. So two tests that use the same name would share one component. `uniqueTag` returns a fresh name each time:

```typescript
const tag = uniqueTag("roving");
define(tag)
  .withRefs((r) => ({ tabs: r.many<HTMLElement>("[role=tab]") }))
  .setup((ctx) => {
    attachRovingFocus(ctx, ctx.host, ctx.refs.tabs);
  });

const markup = h(tag, null, TABS_CHILDREN);
const host = mount(markup);
```

### Disconnect and reconnect

`disconnect(host)` takes the host off the page and runs its cleanup. `connect(host)` puts it back in the same place, and setup runs again:

```typescript
const markup = h("x-chart", null, CHILDREN);
const host = mount(markup);

disconnect(host);
host.bars = [{ label: "a", value: 1 }]; // nothing reacts while disconnected
expect(ref(host, "list").children).toHaveLength(0);

connect(host);
expect(ref(host, "list").children).toHaveLength(1);
```

### Errors surface where they happen

jsdom does not throw errors from a component's setup or cleanup. It reports them as a window `error` event instead, and the test carries on with a broken element and fails somewhere else much later. The helpers fix this, right at the call: `mount` and `create` rethrow constructor errors, `mount`, `connect` and `provideContext` rethrow setup errors, and `disconnect` and `cleanup` rethrow cleanup errors.

`cleanup` always removes everything before it throws, so one broken component cannot leak into the next test. If several fail, it throws them together as an `AggregateError`.

### Upgrade order

In the browser, the order of imports decides which component sets up first. `define("x-modal")` sets up every `<x-modal>` already on the page, so if it is imported before `x-modal-outlet`, the outlet can call `modal.close()` in its setup. Swap the two imports and the outlet finds a plain element with no `close` method.

A parent whose setup calls into a child depends on import order, and that is a design smell, not a testing problem. If a test needs special steps to get the order right, the component will break the same way the day someone reorders the imports. Let state flow down instead: the parent provides it through a [context](#provide-vs-consume-vs-withcontexts), and the child reacts whenever it sets up. The context protocol works in either order, so a plain `mount` tests it.

```typescript
// Coupled: the outlet's first effect calls into the modal, so x-modal must set up first.
ctx.effect($hash, (hash) => {
  if (!hash) ctx.refs.modal.close();
});

// Decoupled: the outlet provides the state, and the modal follows it.
modalContext.provide(ctx, { $open: computed($hash, (hash) => hash !== "") });

define("x-modal")
  .withContexts({ modal: modalContext })
  .setup((ctx) => {
    ctx.effect(ctx.contexts.modal.$open, (open) => {
      // show or hide the dialog
    });
  });
```

`mount` sets up the outer component first and its children after, the same as a browser. (happy-dom sets up the children first, so a coupled test that passes there can still fail in a browser.) For a coupled component you cannot change yet, connect the child on its own first:

```typescript
const modalMarkup = h("x-modal", { "data-ref": "modal" }, MODAL_CHILDREN);

const modal = mount(modalMarkup);
const host = create("x-modal-outlet");
host.append(modal);
connect(host);
```

Moving the modal disconnects and reconnects it, so its setup runs twice. If the child is not registered at all, stub its methods with `stubElement` instead.

### DOM differences

jsdom and happy-dom are not browsers, and some gaps matter for component tests. Checked against jsdom 29 and happy-dom 20:

|                                                               | jsdom 29                                        | happy-dom 20                                                                           |
| ------------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------- |
| `dialog.showModal()` / `show()` / `close()`                   | missing                                         | works, `close` event fires                                                             |
| `ResizeObserver`, `IntersectionObserver`                      | missing                                         | present                                                                                |
| `matchMedia`                                                  | missing                                         | present                                                                                |
| `element.scrollTo`                                            | missing                                         | present                                                                                |
| `showPopover()`, `element.animate`                            | missing                                         | missing                                                                                |
| Layout (`clientWidth`, `getBoundingClientRect`)               | always `0`                                      | always `0`                                                                             |
| Setup order of nested components                              | outer first, like a browser                     | inner first                                                                            |
| A component whose attribute prop has no fallback              | constructed with its attributes, like a browser | constructed before its attributes land, so the prop's schema rejects the missing value |
| Error thrown in `attributeChangedCallback`                    | window `error` event                            | thrown from `setAttribute`                                                             |
| Error thrown in `connectedCallback` or `disconnectedCallback` | window `error` event                            | thrown from the insertion or removal                                                   |

The helpers handle the last row for you (see [Errors surface where they happen](#errors-surface-where-they-happen)). The rest you fill in yourself, in a `beforeAll`. Keep each shim as small as what the component actually uses, and keep all of them in one shared module so every test gets the same fake.

```typescript
// test/stubs/dialogMethods.ts
// jsdom ships <dialog> without showModal/show, so any component driving a real dialog is
// untestable out of the box. This installs the minimum the spec guarantees and components
// rely on: `open` reflects visibility, and close() fires a non-bubbling "close" event once.
function open(this: HTMLDialogElement) {
  this.open = true;
}

function close(this: HTMLDialogElement) {
  if (!this.open) return;
  this.open = false;
  this.dispatchEvent(new Event("close"));
}

export function installDialogMethods() {
  HTMLDialogElement.prototype.showModal = open;
  HTMLDialogElement.prototype.show = open;
  HTMLDialogElement.prototype.close = close;
}
```

An observer shim wants a handle back, so the test can decide what the callback sees:

```typescript
// test/stubs/intersectionObserver.ts
import { vi } from "vitest";

export function installIntersectionObserver() {
  const created: FakeIntersectionObserver[] = [];

  class FakeIntersectionObserver {
    targets: Element[] = [];
    disconnected = false;
    callback: IntersectionObserverCallback;
    constructor(callback: IntersectionObserverCallback) {
      this.callback = callback;
      created.push(this);
    }
    observe(target: Element) {
      this.targets.push(target);
    }
    unobserve(target: Element) {
      this.targets = this.targets.filter((el) => el !== target);
    }
    disconnect() {
      this.disconnected = true;
    }
    /** Drive the component: hand it the entries a real observer would. */
    trigger(entries: Partial<IntersectionObserverEntry>[]) {
      this.callback(entries as IntersectionObserverEntry[], this as never);
    }
  }

  vi.stubGlobal("IntersectionObserver", FakeIntersectionObserver);
  return { latest: () => created.at(-1) };
}
```

Layout has no shim worth writing. Define the geometry the component reads, on the element it reads it from:

```typescript
Object.defineProperty(container, "scrollWidth", {
  value: 900,
  configurable: true,
});
Object.defineProperty(container, "clientWidth", {
  value: 300,
  configurable: true,
});
container.scrollTo = vi.fn();
```

If a component needs so much faked geometry that the test becomes a fiction, that behaviour belongs in an end-to-end test in a real browser instead.

### Rules of thumb

- Copy the real markup, and note in a comment which template it comes from. If the test markup drifts from the template, the test passes while the component is broken.
- **Assert what the DOM shows**: text, attributes, `hidden`, focus, and what the component wrote to a stub. `nanotags/testing` intentionally gives no access to `ctx`.
- Vitest moves `vi.mock` above every import, so its factory cannot use the file's variables. Create the ones it needs with `vi.hoisted`.
- Use `await vi.waitFor(...)` for anything asynchronous. With fake timers, check the state just before and just after the timer fires.
- Test against the platform, not your wrapper. A component that listens on `closest("dialog")` can be tested inside a bare `<dialog>`, which is one reason to build on platform elements.

# Examples

Live playground: edit code and see changes in the Preview immediately.

- [Counter](/examples/counter.md): A minimal counter using nanotags with nanostores reactivity.
- [Live Search](/examples/live-search.md): Real-time country filtering with p.json(), valibot schema, ctx.bind, ctx.effect, renderList, and computed stores.
- [Modal](/examples/modal.md): Modal dialog with a focus trap attachment for accessible keyboard navigation.
- [Tabs](/examples/tabs.md): Tab navigation with parent-child context and keyboard support.
- [Todo List](/examples/todo-list.md): Todo list with nested components and keyed list reconciliation via renderList.
- [Toggle Group](/examples/toggle-group.md): Single or multi-select toggle buttons with event-based parent-child communication.


- [Counter](/examples/counter.md): A minimal counter using nanotags with nanostores reactivity.
- [Live Search](/examples/live-search.md): Real-time country filtering with p.json(), valibot schema, ctx.bind, ctx.effect, renderList, and computed stores.
- [Modal](/examples/modal.md): Modal dialog with a focus trap attachment for accessible keyboard navigation.
- [Tabs](/examples/tabs.md): Tab navigation with parent-child context and keyboard support.
- [Todo List](/examples/todo-list.md): Todo list with nested components and keyed list reconciliation via renderList.
- [Toggle Group](/examples/toggle-group.md): Single or multi-select toggle buttons with event-based parent-child communication.