# Summit.js: Full Documentation

> The open source, AI Agent Native JavaScript framework. Add behavior directly in your HTML with signal-powered s- directives and $ magics. No build step, CSP-safe, about 16KB with focus, positioning, persistence, and masking built in.

Every documentation page, concatenated as markdown in reading order. Source: https://velofy.github.io/summitjs

---

# Getting Started

> Summit is a rugged, signal-powered JavaScript framework for composing behavior directly in your HTML. Learn what it is and write your first component.

Summit is a small JavaScript framework for composing behavior directly in your
markup. You sprinkle a handful of `s-` attributes onto plain HTML and Summit
brings it to life. No build step, no components to import, no JSX. If you know
HTML, you already know most of Summit.

Under the hood it runs on a fine-grained signal engine, so when a value changes
Summit updates only the exact piece of DOM that depends on it. Expressions are
parsed and interpreted rather than handed to `eval`, so Summit works under a
strict Content-Security-Policy with nothing extra to configure.

## Your first component

Here is a complete, working counter. There is no setup around it: this snippet
is running live on the page right now.

```summit
<div s-data="{ count: 0 }">
  <button @click="count--">-</button>
  <output s-text="count">0</output>
  <button @click="count++">+</button>
</div>
```

`s-data` declares a piece of state. `@click` (shorthand for `s-on:click`) runs
an expression when the button is clicked. `s-text` keeps the `<output>` in sync
with `count`. When you click, only that one number re-renders.

## Why Summit

- **Fine-grained reactivity.** A real signal engine tracks exactly which
  expressions read which values, so updates are surgical rather than
  re-rendering whole subtrees.
- **CSP-safe by default.** Expressions run through a hand-written interpreter.
  No `eval`, no `new Function`, no `unsafe-eval` in your policy.
- **Tiny and buildless.** The whole runtime is roughly 16KB gzipped. Drop in one
  script tag and it starts on its own.
- **Familiar.** Fifteen directives, nine magic properties, and the `@` and `:`
  shorthands. If you have used an HTML-first framework before, this will feel
  like home, with the rough edges filed off.

## Where to go next

- [Installation](../installation/) covers the script tag, npm, and bundlers.
- [Reactivity and State](../reactivity-state/) explains `s-data`, computed
  values, and methods.
- The [Directives](../s-data/) and [Magic Properties](../magic-el/) sections are
  a complete reference for every attribute and helper.

---

# UI Library

> An accessible, token-themed component library you copy into your markup and theme with CSS variables. Built with Summit, for people and AI agents.

Summit ships a copy-in UI library: a set of accessible, token-themed components
you drop straight into your HTML. There is no component runtime to install. Each
one is plain markup plus a class, and the interactive ones are wired with the
same `s-` directives you already know. Theme the whole set by changing a few CSS
variables.

It is built the way an AI agent likes to work: predictable class names, behavior
that lives on the element, and nothing that needs a build step.

```summit
<div class="s-row">
  <button class="s-btn">Solid</button>
  <button class="s-btn s-btn-outline">Outline</button>
  <button class="s-btn s-btn-ghost">Ghost</button>
  <span class="s-badge s-badge-success">Live</span>
</div>
```

## Using a component

Load the stylesheet once, then copy any component's markup.

```html
<link rel="stylesheet" href="https://velofy.github.io/summitjs/assets/components.css" />
```

Or copy the rules you need out of `components.css` into your own styles. Every
class is prefixed `s-`, so nothing collides with your existing CSS.

## Theming

Components read the same design tokens as the rest of Summit. Override them on
`:root` (or any scope) and the whole set restyles. The most useful ones:

```css
:root {
  --accent: #ea580c;      /* primary / brand color */
  --s-radius: 12px;       /* corner rounding */
  --s-danger: #e11d48;    /* destructive actions */
}
```

Light and dark are handled for you through `prefers-color-scheme` and the
`data-theme` attribute, exactly like this documentation.

## Accessibility

Interactive components ship with the roles and keyboard behavior you expect:
focus rings on every control, `Escape` to close overlays, click-outside to
dismiss menus, and labels wired to their inputs. Where a component needs an id
to pair a label with a control, use the [$id](../magic-id/) magic.

## The components

**Forms**
[Button](../comp-button/), [Input](../comp-input/), [Select](../comp-select/),
[Checkbox & Radio](../comp-checkbox/), [Switch](../comp-switch/)

**Data display**
[Card](../comp-card/), [Badge & Tag](../comp-badge/), [Alert](../comp-alert/),
[Avatar](../comp-avatar/), [Progress & Spinner](../comp-progress/)

**Overlays**
[Dialog](../comp-dialog/), [Dropdown Menu](../comp-menu/),
[Popover](../comp-popover/), [Tooltip](../comp-tooltip/), [Toast](../comp-toast/)

**Navigation**
[Tabs](../comp-tabs/), [Accordion](../comp-accordion/),
[Breadcrumb](../comp-breadcrumb/), [Pagination](../comp-pagination/)

---

# Button

> Buttons with solid, outline, ghost, subtle, and danger variants, plus sizes and groups.

Buttons trigger actions. Everything starts from one base class, `.s-btn`, and you
add modifiers for variant, size, and shape. Because behavior lives on the
element, you can wire any button up with the same `s-` directives you already
use.

```summit
<div s-data="{ count: 0 }" class="s-row">
  <button class="s-btn" @click="count++">Add to cart</button>
  <button class="s-btn s-btn-outline" @click="count = 0">Reset</button>
  <span s-text="count + (count === 1 ? ' item' : ' items')"></span>
</div>
```

## Variants

The base `.s-btn` is the solid, high-emphasis button. Add one modifier class to
change its emphasis. Use `.s-btn-danger` for destructive actions so the intent
reads at a glance.

```summit
<div class="s-row">
  <button class="s-btn">Solid</button>
  <button class="s-btn s-btn-outline">Outline</button>
  <button class="s-btn s-btn-ghost">Ghost</button>
  <button class="s-btn s-btn-subtle">Subtle</button>
  <button class="s-btn s-btn-danger">Danger</button>
</div>
```

## Sizes

`.s-btn-sm` and `.s-btn-lg` adjust height and padding. Without either, a button
uses the default size.

```summit
<div class="s-row">
  <button class="s-btn s-btn-sm">Small</button>
  <button class="s-btn">Default</button>
  <button class="s-btn s-btn-lg">Large</button>
</div>
```

Add `.s-btn-block` to stretch a button to the full width of its container, which
is handy at the end of a form.

## Icon buttons

`.s-btn-icon` makes a square button sized for a single glyph. Drop an inline SVG
inside and give the button an `aria-label`, since there is no visible text to
name it.

```summit
<div class="s-row">
  <button class="s-btn s-btn-icon" aria-label="Add item">
    <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M12 5v14M5 12h14"/></svg>
  </button>
  <button class="s-btn s-btn-outline s-btn-icon" aria-label="Add item">
    <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M12 5v14M5 12h14"/></svg>
  </button>
  <button class="s-btn s-btn-icon s-btn-sm" aria-label="Add item">
    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M12 5v14M5 12h14"/></svg>
  </button>
</div>
```

## Groups

Wrap two or more buttons in `.s-btn-group` to join them into a single segmented
control. The group squares off the inner corners and collapses the shared
borders for you.

```summit
<div class="s-btn-group" role="group" aria-label="Text alignment">
  <button class="s-btn s-btn-outline">Left</button>
  <button class="s-btn s-btn-outline">Center</button>
  <button class="s-btn s-btn-outline">Right</button>
</div>
```

## Disabled

The native `disabled` attribute dims a button and removes it from the tab order.
Bind it reactively with [`:disabled`](../s-bind/) to gate an action on state.

```summit
<div s-data="{ agreed: false }" class="s-row">
  <label><input type="checkbox" s-model="agreed" /> I accept the terms</label>
  <button class="s-btn" :disabled="!agreed">Continue</button>
</div>
```

## Copy and paste

```html
<button class="s-btn">Solid</button>
<button class="s-btn s-btn-outline">Outline</button>
<button class="s-btn s-btn-ghost">Ghost</button>
<button class="s-btn s-btn-subtle">Subtle</button>
<button class="s-btn s-btn-danger">Danger</button>

<button class="s-btn s-btn-sm">Small</button>
<button class="s-btn s-btn-lg">Large</button>
<button class="s-btn s-btn-block">Full width</button>

<button class="s-btn s-btn-icon" aria-label="Add">
  <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round">
    <path d="M12 5v14M5 12h14" />
  </svg>
</button>

<div class="s-btn-group" role="group" aria-label="Alignment">
  <button class="s-btn s-btn-outline">Left</button>
  <button class="s-btn s-btn-outline">Center</button>
  <button class="s-btn s-btn-outline">Right</button>
</div>

<button class="s-btn" disabled>Disabled</button>
```

## Accessibility

Always use a real `<button>` element so keyboard activation, focus, and the
`disabled` state work without extra code. Every variant shows a visible focus
ring on `:focus-visible`. Give icon-only buttons an `aria-label` so assistive
technology can name them, and label a `.s-btn-group` with `role="group"` and an
`aria-label` describing the set. For handling clicks and keyboard shortcuts, see
[s-on](../s-on/); to pair a button with a field, see [Input](../comp-input/).

---

# Input

> Text inputs and textareas with labels, help text, addons, and validation state.

Inputs collect a line or a block of text. Apply `.s-input` to any text-like
`<input>` and `.s-textarea` to a `<textarea>`, then bind the value with
[`s-model`](../forms/) to keep state and control in sync.

```summit
<div s-data="{ value: '' }" class="s-stack">
  <input class="s-input" s-model="value" placeholder="Type something" />
  <p class="s-help">You typed: <span s-text="value || 'nothing yet'"></span></p>
</div>
```

## A full field

Wrap a label, control, and help text in `.s-field` for consistent spacing. Use
`.s-label` for the label and `.s-help` for the hint below. Mark required fields
with a `.s-req` asterisk inside the label.

```summit
<div class="s-field">
  <label class="s-label" for="email-1">Email <span class="s-req">*</span></label>
  <input class="s-input" id="email-1" type="email" placeholder="you@example.com" />
  <p class="s-help">We only use this to send receipts.</p>
</div>
```

## Input groups

`.s-input-group` sits an `.s-addon` flush against an input to show a prefix such
as a protocol, currency symbol, or unit. The group squares off the touching
corners for you.

```summit
<div class="s-input-group">
  <span class="s-addon">https://</span>
  <input class="s-input" placeholder="your-site.com" />
</div>
```

## Validation state

Add `is-invalid` to an input to switch its border to the danger color, and show
an `.s-error` message in place of the help text. Bind both to state so the error
appears only when the value is actually wrong.

```summit
<div s-data="{ email: '' }" class="s-field">
  <label class="s-label" for="email-2">Email</label>
  <input class="s-input" id="email-2" type="email" s-model="email"
    :class="{ 'is-invalid': email.length > 0 && !email.includes('@') }"
    placeholder="you@example.com" />
  <p class="s-error" s-show="email.length > 0 && !email.includes('@')">Enter a valid email address.</p>
</div>
```

## Textarea

`.s-textarea` styles a multi-line field. It grows vertically and can be resized
by the user. Bind it with `s-model` the same way as a single-line input.

```summit
<div s-data="{ note: '' }" class="s-field">
  <label class="s-label" for="note-1">Notes</label>
  <textarea class="s-textarea" id="note-1" s-model="note" placeholder="Add any details"></textarea>
  <p class="s-help"><span s-text="note.length"></span> characters</p>
</div>
```

## Copy and paste

```html
<div class="s-field">
  <label class="s-label" for="email">Email <span class="s-req">*</span></label>
  <input class="s-input" id="email" type="email" placeholder="you@example.com" />
  <p class="s-help">We only use this to send receipts.</p>
</div>

<div class="s-input-group">
  <span class="s-addon">https://</span>
  <input class="s-input" placeholder="your-site.com" />
</div>

<div class="s-field">
  <label class="s-label" for="handle">Username</label>
  <input class="s-input is-invalid" id="handle" aria-invalid="true" aria-describedby="handle-error" value="taken" />
  <p class="s-error" id="handle-error">That username is already in use.</p>
</div>

<div class="s-field">
  <label class="s-label" for="bio">Bio</label>
  <textarea class="s-textarea" id="bio" placeholder="Tell us about yourself"></textarea>
</div>

<input class="s-input" value="Read only" disabled />
```

## Accessibility

Pair every control with a `<label>` by matching the label's `for` to the input's
`id`, so clicking the label focuses the field. When ids are generated at runtime,
reach for the [$id](../magic-id/) magic. The `.s-req` asterisk is decorative, so
keep the field's real requirement in the `required` attribute. For an invalid
control, set `aria-invalid="true"` and point `aria-describedby` at the
`.s-error` element so screen readers announce the message. See
[Select](../comp-select/) for choosing from options and [s-model](../s-model/)
for the binding details.

---

# Select

> A styled native select bound with s-model.

Select lets you pick one value from a fixed list. Apply `.s-select` to a real
`<select>` element and bind it with [`s-model`](../forms/), so the chosen option
flows straight into your state.

```summit
<div s-data="{ plan: 'pro' }" class="s-stack">
  <div class="s-field">
    <label class="s-label" for="plan-1">Plan</label>
    <select class="s-select" id="plan-1" s-model="plan">
      <option value="free">Free</option>
      <option value="pro">Pro</option>
      <option value="team">Team</option>
    </select>
  </div>
  <p class="s-help">Selected plan: <span s-text="plan"></span></p>
</div>
```

## Driving other state

Because the value is just a piece of your data, you can react to it anywhere.
Here the choice reveals a note with [`s-show`](../s-show/).

```summit
<div s-data="{ size: 'M' }" class="s-stack">
  <div class="s-field">
    <label class="s-label" for="size-1">T-shirt size</label>
    <select class="s-select" id="size-1" s-model="size">
      <option>S</option>
      <option>M</option>
      <option>L</option>
      <option>XL</option>
    </select>
  </div>
  <p class="s-help" s-show="size === 'XL'">XL adds $2 to the price.</p>
</div>
```

## A real native select

`.s-select` styles the browser's own `<select>`. It only restyles the closed
control, so the open list stays the native menu. That is deliberate: you keep the
platform's keyboard handling, type-ahead search, and the correct picker on touch
devices for free, and there is no custom widget to maintain.

## Copy and paste

```html
<div class="s-field">
  <label class="s-label" for="country">Country</label>
  <select class="s-select" id="country" s-model="country">
    <option value="">Choose a country</option>
    <option value="us">United States</option>
    <option value="ca">Canada</option>
    <option value="uk">United Kingdom</option>
  </select>
</div>
```

## Accessibility

Since this is a real `<select>`, screen readers, keyboard navigation, and mobile
pickers all work with no extra wiring. Pair it with a `<label>` by matching the
label's `for` to the select's `id`, or use the [$id](../magic-id/) magic when the
id is generated at runtime. For binding, coercion modifiers, and `multiple`
selects, see [Forms](../forms/) and [s-model](../s-model/); for free-text entry,
see [Input](../comp-input/).

---

# Checkbox & Radio

> Accessible checkboxes and radio groups bound with s-model.

Checkboxes and radios wrap a real `<input>` in a styled label, so you get a
custom look without giving up native behavior. The input stays in the markup and
carries the state; the `.s-box` next to it is only decoration. Bind any of them
with [s-model](../s-model/) and the checked state flows both ways.

## A single checkbox

Point `s-model` at a boolean and the checkbox toggles it. The `<input>` is
visually hidden but still present, and the `.s-box` renders the tick when the
value is `true`.

```summit
<div s-data="{ agree: false }">
  <label class="s-check">
    <input type="checkbox" s-model="agree">
    <span class="s-box"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><path d="M20 6 9 17l-5-5"/></svg></span>
    I agree to the terms
  </label>
  <p class="s-help">agree = <span s-text="agree"></span></p>
</div>
```

```html
<label class="s-check">
  <input type="checkbox" s-model="agree">
  <span class="s-box">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3">
      <path d="M20 6 9 17l-5-5"/>
    </svg>
  </span>
  I agree to the terms
</label>
```

## A group bound to an array

When several checkboxes share one `s-model` and each carries a `value`, Summit
binds them to an array. Checking a box adds its value; unchecking removes it. The
order follows the order the boxes appear in the markup.

```summit
<div s-data="{ toppings: ['cheese'] }">
  <div class="s-stack">
    <label class="s-check">
      <input type="checkbox" value="cheese" s-model="toppings">
      <span class="s-box"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><path d="M20 6 9 17l-5-5"/></svg></span>
      Cheese
    </label>
    <label class="s-check">
      <input type="checkbox" value="mushroom" s-model="toppings">
      <span class="s-box"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><path d="M20 6 9 17l-5-5"/></svg></span>
      Mushroom
    </label>
    <label class="s-check">
      <input type="checkbox" value="olives" s-model="toppings">
      <span class="s-box"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><path d="M20 6 9 17l-5-5"/></svg></span>
      Olives
    </label>
  </div>
  <p class="s-help">toppings = <span s-text="JSON.stringify(toppings)"></span></p>
</div>
```

```html
<div class="s-stack">
  <label class="s-check">
    <input type="checkbox" value="cheese" s-model="toppings">
    <span class="s-box">
      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><path d="M20 6 9 17l-5-5"/></svg>
    </span>
    Cheese
  </label>
  <!-- repeat the label for each value, all sharing s-model="toppings" -->
</div>
```

## A radio group

Radios use `.s-radio-opt`, which rounds the `.s-box` and fills it with a dot when
selected. Give every radio in the group the same `s-model` and a distinct
`value`; the model holds the one chosen value.

```summit
<div s-data="{ plan: 'pro' }">
  <div class="s-stack">
    <label class="s-radio-opt">
      <input type="radio" value="free" s-model="plan">
      <span class="s-box"></span>
      Free
    </label>
    <label class="s-radio-opt">
      <input type="radio" value="pro" s-model="plan">
      <span class="s-box"></span>
      Pro
    </label>
    <label class="s-radio-opt">
      <input type="radio" value="team" s-model="plan">
      <span class="s-box"></span>
      Team
    </label>
  </div>
  <p class="s-help">plan = <span s-text="plan"></span></p>
</div>
```

```html
<div class="s-stack">
  <label class="s-radio-opt">
    <input type="radio" value="free" s-model="plan">
    <span class="s-box"></span>
    Free
  </label>
  <label class="s-radio-opt">
    <input type="radio" value="pro" s-model="plan">
    <span class="s-box"></span>
    Pro
  </label>
</div>
```

## Accessibility

The styled box is purely visual. Because a real `<input type="checkbox">` or
`<input type="radio">` stays in the DOM, you keep native keyboard support out of
the box: focus with `Tab`, toggle a checkbox with `Space`, and move within a
radio group with the arrow keys. Screen readers announce the control's role and
checked state, and wrapping each control in its `<label>` means the visible text
is the accessible name, so no extra ARIA is needed. Grouping related radios or
checkboxes in a `<fieldset>` with a `<legend>` gives the set a shared label.

For an on/off setting, reach for the [Switch](../comp-switch/) instead. See
[Forms](../forms/) for how `s-model` handles every control type.

---

# Switch

> A toggle switch bound with s-model, for on/off settings.

A switch is an on/off control for a single setting, the kind you flip and it
takes effect right away. Summit's switch is a styled `<label class="s-switch">`
wrapping a real checkbox, so binding it is exactly like binding a checkbox: point
[s-model](../s-model/) at a boolean and the track slides between states.

## A live switch

The `<input>` is visually hidden and holds the state; the `.s-track` is the
sliding pill you see. Here the switch flips `on`, and [s-show](../s-show/)
reveals a message only while it is `true`.

```summit
<div s-data="{ on: false }">
  <label class="s-switch">
    <input type="checkbox" s-model="on">
    <span class="s-track"></span>
    Email notifications
  </label>
  <p class="s-help" s-show="on">You will get an email when something changes.</p>
</div>
```

```html
<label class="s-switch">
  <input type="checkbox" s-model="on">
  <span class="s-track"></span>
  Email notifications
</label>
```

## Disabled

Add the native `disabled` attribute to the input to lock a switch. It stops
responding to clicks and keyboard input while keeping its current position, which
is useful for a setting that depends on another choice.

```summit
<div s-data="{ locked: true }">
  <label class="s-switch">
    <input type="checkbox" s-model="locked" disabled>
    <span class="s-track"></span>
    Two-factor auth (required)
  </label>
</div>
```

```html
<label class="s-switch">
  <input type="checkbox" s-model="locked" disabled>
  <span class="s-track"></span>
  Two-factor auth (required)
</label>
```

## Accessibility

Under the hood a switch is a real `<input type="checkbox">`, so it is fully
accessible with no extra work: it is reachable with `Tab`, toggles with `Space`,
and announces its checked state to screen readers. Wrapping the control in its
`<label>` makes the visible text the accessible name. If you want assistive tech
to announce it as a switch rather than a checkbox, add `role="switch"` to the
input; the checked state maps to on and off automatically.

For a set of choices rather than a single toggle, use
[Checkbox & Radio](../comp-checkbox/). See [Forms](../forms/) for the full picture
of `s-model` bindings.

---

# Card

> A surface for grouping content, with header, body, and footer.

A card is a bordered surface that groups related content into one block. Reach
for it whenever a chunk of the page deserves its own edges: a settings panel, a
pricing tier, a summary. It is pure markup, so there is nothing to wire up. You
compose a header, a body, and a footer, and use only the parts you need.

```summit
<div class="s-card" style="max-width:360px">
  <div class="s-card-header">
    <h3 class="s-card-title">Upgrade to Pro</h3>
    <p class="s-card-desc">Lift the project cap and add your whole team.</p>
  </div>
  <div class="s-card-body">
    You are on the Free plan, which tops out at three projects. Pro removes the
    limit and unlocks priority support.
  </div>
  <div class="s-card-footer">
    <button class="s-btn">Upgrade</button>
    <button class="s-btn s-btn-ghost">Maybe later</button>
  </div>
</div>
```

## Anatomy

A card is a `.s-card` wrapper around three optional regions, each with its own
padding so they line up without extra spacing rules.

- `.s-card-header` holds the `.s-card-title` and an optional `.s-card-desc`.
- `.s-card-body` is the main content area.
- `.s-card-footer` lays out actions in a row with a gap, ready for
  [buttons](../comp-button/).

The wrapper clips its corners with `overflow: hidden`, so a full-bleed image or a
colored bar as the first child follows the rounded edge cleanly.

## Body-only card

Drop the header and footer when all you need is a framed block of content.

```summit
<div class="s-card" style="max-width:360px">
  <div class="s-card-body">
    Every region is optional. A card with only a body is still a tidy, bordered
    surface you can drop anywhere in a grid.
  </div>
</div>
```

## Copy

```html
<div class="s-card">
  <div class="s-card-header">
    <h3 class="s-card-title">Upgrade to Pro</h3>
    <p class="s-card-desc">Lift the project cap and add your whole team.</p>
  </div>
  <div class="s-card-body">
    You are on the Free plan, which tops out at three projects.
  </div>
  <div class="s-card-footer">
    <button class="s-btn">Upgrade</button>
    <button class="s-btn s-btn-ghost">Maybe later</button>
  </div>
</div>
```

## Notes

- The card sets a width of whatever it sits in, so control its size from the
  parent layout (a grid, a flex row, or a `max-width` like the demos above).
- The title renders as an `h3` here, but the class carries the styling. Use the
  heading level that fits your document outline.
- Footer actions align to the start. To push them to the right, add your own
  `style="justify-content:flex-end"` or a utility class.

Pair cards with [badges](../comp-badge/) for status and
[avatars](../comp-avatar/) for people. See the full set on the
[overview](../components/).

---

# Badge & Tag

> Small status labels and removable tags.

Badges are small, uppercase labels for status and counts: a build that passed, a
plan tier, an item count on a menu. Tags are their rounded, softer cousin, sized
for user-entered keywords and built to carry a remove button. Both are plain
markup, and the tag's button is where a little Summit state turns a static list
into an editable one.

```summit
<div class="s-row">
  <span class="s-badge">Default</span>
  <span class="s-badge s-badge-solid">Solid</span>
  <span class="s-badge s-badge-outline">Outline</span>
  <span class="s-badge s-badge-info">Info</span>
  <span class="s-badge s-badge-success">Success</span>
  <span class="s-badge s-badge-warning">Warning</span>
  <span class="s-badge s-badge-danger">Danger</span>
</div>
```

## Badge variants

The base `.s-badge` uses your accent tint. Add one modifier to change its weight
or meaning:

- `.s-badge-solid` fills with the accent color for the strongest emphasis.
- `.s-badge-outline` is a quiet, bordered label.
- `.s-badge-info`, `.s-badge-success`, `.s-badge-warning`, and `.s-badge-danger`
  map to the semantic feedback palette, the same colors the
  [alert](../comp-alert/) component uses.

```html
<span class="s-badge s-badge-success">Passing</span>
<span class="s-badge s-badge-danger">3 failed</span>
<span class="s-badge s-badge-outline">Draft</span>
```

## Removable tags

A `.s-tag` is a pill with an inner `<button>` for removal. Bind the list to state
with [s-for](../s-for/), key each tag, and let the button `splice` its own item
out of the array. Because the array is reactive, the tag disappears the moment
you click.

```summit
<div s-data="{ tags: ['Design', 'Research', 'Docs', 'Frontend'] }">
  <div class="s-row">
    <template s-for="(tag, i) in tags" :key="tag">
      <span class="s-tag">
        <span s-text="tag"></span>
        <button @click="tags.splice(i, 1)" aria-label="Remove tag">&times;</button>
      </span>
    </template>
    <span s-show="tags.length === 0" class="s-help">All tags removed.</span>
  </div>
</div>
```

## Copy

```html
<div s-data="{ tags: ['Design', 'Research', 'Docs'] }">
  <div class="s-row">
    <template s-for="(tag, i) in tags" :key="tag">
      <span class="s-tag">
        <span s-text="tag"></span>
        <button @click="tags.splice(i, 1)" aria-label="Remove tag">&times;</button>
      </span>
    </template>
  </div>
</div>
```

## Notes

- Give the remove button an `aria-label` so screen readers announce what it does,
  since the visible content is just a times sign.
- The `:key="tag"` keeps each pill matched to its value across removals, so the
  right one leaves even when earlier tags are gone. Use a unique id if your tags
  can repeat.
- Badges have no interactive behavior; they are labels. For dismissible banners,
  reach for an [alert](../comp-alert/) or a toast instead.

See the whole component set on the [overview](../components/).

---

# Table

> A styled table for displaying rows of tabular data.

A table is a bordered grid of rows and columns for displaying structured data. Reach for it whenever content is naturally tabular: a list of users, a pricing comparison, a log of events. It is pure markup, so there is nothing to wire up. Wrap it in `.s-table-wrap` when columns might overflow on narrow screens.

```summit
<div class="s-table-wrap">
  <table class="s-table">
    <thead>
      <tr>
        <th>Name</th>
        <th>Role</th>
        <th>Status</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Ada Lovelace</td>
        <td>Engineer</td>
        <td>Active</td>
      </tr>
      <tr>
        <td>Grace Hopper</td>
        <td>Admiral</td>
        <td>Active</td>
      </tr>
      <tr>
        <td>Alan Turing</td>
        <td>Mathematician</td>
        <td>Inactive</td>
      </tr>
    </tbody>
  </table>
</div>
```

## Anatomy

A table is a standard `<table>` element carrying the `.s-table` class, optionally wrapped in `.s-table-wrap` for horizontal scrolling.

- `.s-table-wrap` sets `overflow-x: auto` so wide tables scroll instead of breaking the page layout.
- `.s-table thead th` gets a muted background and uppercase header text to separate it from the body.
- `.s-table tbody tr:nth-child(even)` gets a subtle zebra-striped background for row scanning.
- `.s-table tbody tr:hover` highlights the row under the cursor.

## Copy

```html
<div class="s-table-wrap">
  <table class="s-table">
    <thead>
      <tr>
        <th>Name</th>
        <th>Role</th>
        <th>Status</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Ada Lovelace</td>
        <td>Engineer</td>
        <td>Active</td>
      </tr>
    </tbody>
  </table>
</div>
```

## Notes

- Always wrap `.s-table` in `.s-table-wrap` if the table might be wider than its container, especially on mobile.
- The table takes the width of its parent. Constrain it with a `max-width` on the wrapper if needed.
- All styling comes from tokens (`--border`, `--surface-2`, `--muted`, `--accent-soft`), so it adapts automatically to light and dark themes.

See the full set in the [overview](../components/).

---

# Alert

> Contextual feedback banners for info, success, warning, and danger.

An alert is an inline banner that gives the reader feedback in place: a helpful
note, a success confirmation, a warning, or an error. It sits in the flow of the
page rather than floating over it, which makes it the right choice for messages
tied to a specific spot, like a form section or a settings panel. Each variant
pairs an icon with a title and a short description.

```summit
<div class="s-stack">
  <div class="s-alert s-alert-info">
    <svg class="s-alert-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>
    <div>
      <p class="s-alert-title">Heads up</p>
      <p class="s-alert-desc">Your trial ends in five days. Add a card to keep your projects.</p>
    </div>
  </div>
  <div class="s-alert s-alert-success">
    <svg class="s-alert-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><path d="m9 11 3 3L22 4"/></svg>
    <div>
      <p class="s-alert-title">Saved</p>
      <p class="s-alert-desc">Your changes are live and visible to your team.</p>
    </div>
  </div>
  <div class="s-alert s-alert-warning">
    <svg class="s-alert-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>
    <div>
      <p class="s-alert-title">Almost out of space</p>
      <p class="s-alert-desc">You have used 92% of your storage. Free some up before uploading more.</p>
    </div>
  </div>
  <div class="s-alert s-alert-danger">
    <svg class="s-alert-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="m15 9-6 6"/><path d="m9 9 6 6"/></svg>
    <div>
      <p class="s-alert-title">Payment failed</p>
      <p class="s-alert-desc">We could not charge your card. Update it to avoid losing access.</p>
    </div>
  </div>
</div>
```

## Anatomy

An alert is a flex row of `.s-alert` plus a variant class:

- `.s-alert-info`, `.s-alert-success`, `.s-alert-warning`, or `.s-alert-danger`
  set the background tint, border, and icon color from the semantic palette.
- `.s-alert-icon` on an inline `<svg>` sizes and colors the leading icon. Use
  `stroke="currentColor"` so it inherits the variant color.
- `.s-alert-title` is the bold headline and `.s-alert-desc` is the muted body.
  Wrap them together in a `<div>` so they stack beside the icon.

Leave off the variant class for a neutral, surface-colored alert. You can also
drop the title and keep a single `.s-alert-desc` for a one-line note.

## Copy

```html
<div class="s-alert s-alert-warning">
  <svg class="s-alert-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor"
       stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
    <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z"/>
    <path d="M12 9v4"/>
    <path d="M12 17h.01"/>
  </svg>
  <div>
    <p class="s-alert-title">Almost out of space</p>
    <p class="s-alert-desc">You have used 92% of your storage.</p>
  </div>
</div>
```

## Notes

- Pick the variant by meaning, not color. Danger is for errors and destructive
  outcomes, warning for things that need attention soon.
- The icon is decorative here because the title carries the message. If an alert
  has no text title, add an `aria-label` to convey its intent.
- Alerts stay in the layout. For transient, stacked messages that appear and
  auto-dismiss, use a toast; for status labels, use a [badge](../comp-badge/).

See the whole component set on the [overview](../components/).

---

# Avatar

> User avatars with initials or images, sizes, and stacked groups.

An avatar is a small, round token that stands in for a person or account. Give it
initials and it renders a tinted circle with centered text; give it an `<img>`
and the photo fills the circle, cropped to a cover fit. Three sizes and a stacked
group cover most of what a user list, comment thread, or header bar needs.

```summit
<div class="s-row">
  <span class="s-avatar">AN</span>
  <span class="s-avatar">GK</span>
  <span class="s-avatar">RB</span>
  <span class="s-avatar">JS</span>
</div>
```

## Sizes

The base avatar is 40px. Add `.s-avatar-sm` for a compact 30px token or
`.s-avatar-lg` for a 56px one. The font scales with each size, so initials stay
centered and legible.

```summit
<div class="s-row">
  <span class="s-avatar s-avatar-sm">SM</span>
  <span class="s-avatar">MD</span>
  <span class="s-avatar s-avatar-lg">LG</span>
</div>
```

## Images

Put an `<img>` inside `.s-avatar` and it covers the circle. The wrapper clips the
photo to a round shape, so any square or rectangular source works.

```summit
<div class="s-row">
  <span class="s-avatar s-avatar-lg">
    <img alt="Avatar" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='56' height='56'%3E%3Crect width='56' height='56' fill='%237c3aed'/%3E%3Ccircle cx='28' cy='22' r='10' fill='%23fff'/%3E%3Cellipse cx='28' cy='52' rx='18' ry='16' fill='%23fff'/%3E%3C/svg%3E" />
  </span>
  <span class="s-avatar">
    <img alt="Avatar" src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='40' height='40'%3E%3Crect width='40' height='40' fill='%230284c7'/%3E%3Ccircle cx='20' cy='16' r='7' fill='%23fff'/%3E%3Cellipse cx='20' cy='38' rx='13' ry='12' fill='%23fff'/%3E%3C/svg%3E" />
  </span>
</div>
```

## Stacked group

Wrap several avatars in `.s-avatar-group` and they overlap with a ring in the
page background between them, the classic "who is here" cluster. A trailing
avatar with a count reads as an overflow.

```summit
<div class="s-avatar-group">
  <span class="s-avatar">AN</span>
  <span class="s-avatar">GK</span>
  <span class="s-avatar">RB</span>
  <span class="s-avatar">+5</span>
</div>
```

## Copy

```html
<!-- Initials -->
<span class="s-avatar">AN</span>

<!-- Photo -->
<span class="s-avatar">
  <img alt="Ada Lovelace" src="/avatars/ada.jpg" />
</span>

<!-- Stacked group with overflow -->
<div class="s-avatar-group">
  <span class="s-avatar">AN</span>
  <span class="s-avatar">GK</span>
  <span class="s-avatar">+5</span>
</div>
```

## Notes

- Keep initials to one or two characters so they stay centered inside the circle.
- Always give the `<img>` a descriptive `alt`, or an empty `alt=""` when the name
  already appears next to the avatar and the image is decorative.
- The ring around grouped avatars comes from the page background color. Place a
  group on a plain surface so the separation reads clearly.

Pair avatars with [cards](../comp-card/) and [badges](../comp-badge/), or browse
the full set on the [overview](../components/).

---

# Progress & Spinner

> Progress bars, spinners, and skeleton placeholders for loading states.

Loading states tell people the app is still working. Summit gives you three
primitives for them: a progress bar you drive from state, a spinner for waits
whose length you cannot predict, and a skeleton that stands in for content that
has not arrived yet. The bar is the only interactive one, so it reads its width
straight off a value in `s-data`.

```summit
<div s-data="{ pct: 40 }" role="progressbar" aria-valuemin="0" aria-valuemax="100" :aria-valuenow="pct">
  <div class="s-progress"><span :style="{ width: pct + '%' }"></span></div>
  <div class="s-row" style="margin-top:.75rem">
    <button class="s-btn s-btn-sm s-btn-outline" @click="pct = Math.max(0, pct - 10)">-10%</button>
    <button class="s-btn s-btn-sm s-btn-outline" @click="pct = Math.min(100, pct + 10)">+10%</button>
    <button class="s-btn s-btn-sm" @click="pct = 100">Finish</button>
    <span s-text="pct + '%'"></span>
  </div>
</div>
```

## Driving the width

The bar is a `.s-progress` track with a single inner `<span>`. You never set a
value attribute; you set the span's width, and the CSS transition animates the
fill. Bind it with `:style` so the width tracks whatever number lives in state.

```summit
<div s-data="{ pct: 65 }">
  <div class="s-progress"><span :style="{ width: pct + '%' }"></span></div>
</div>
```

Keep the number inside `0` to `100`. Clamping with `Math.max` and `Math.min`
when you change it, as the demo above does, means a stray click can never push
the fill past either end.

## Spinner

`.s-spinner` is a standalone element for indeterminate waits, when you know work
is happening but not how far along it is. It needs no state and no inner markup,
just the class. Pair it with a label so the reason for the wait is clear.

```summit
<div class="s-row">
  <span class="s-spinner"></span>
  <span>Loading your workspace</span>
</div>
```

## Skeleton

`.s-skeleton` is a shimmering placeholder block. Give it an inline width and
height so it matches the shape of the content it is standing in for, then stack
several to preview a whole card or list row.

```summit
<div class="s-stack" style="max-width:280px">
  <div class="s-skeleton" style="height:1rem;width:80%"></div>
  <div class="s-skeleton" style="height:1rem;width:60%"></div>
  <div class="s-skeleton" style="height:1rem;width:70%"></div>
</div>
```

## Copy and paste

```html
<!-- Progress bar: width comes from state, not an attribute -->
<div s-data="{ pct: 40 }"
     role="progressbar" aria-valuemin="0" aria-valuemax="100" :aria-valuenow="pct">
  <div class="s-progress">
    <span :style="{ width: pct + '%' }"></span>
  </div>
  <button class="s-btn s-btn-sm" @click="pct = Math.min(100, pct + 10)">Advance</button>
</div>

<!-- Spinner: indeterminate wait -->
<span class="s-spinner" role="status" aria-label="Loading"></span>

<!-- Skeleton: size it to match the missing content -->
<div class="s-skeleton" style="height:1rem;width:60%"></div>
```

## Notes

- The bar carries no semantics on its own. Add `role="progressbar"` with
  `aria-valuemin`, `aria-valuemax`, and a bound `:aria-valuenow` so screen
  readers announce the position, as the top demo does.
- Give the spinner `role="status"` and an `aria-label` so its purpose reaches
  people who cannot see it turn.
- Both the spinner's spin and the skeleton's shimmer stop under
  `prefers-reduced-motion`, so you do not need to disable them yourself.
- Once a load finishes, a [Toast](../comp-toast/) or an [Alert](../comp-alert/)
  is a good way to confirm the result. See all the pieces on the
  [UI Library overview](../components/).

---

# Tooltip

> A CSS-only tooltip that appears on hover and focus.

A tooltip is a small label that appears next to a control to explain what it
does. Summit's version is pure CSS: it shows while the wrapper is hovered or
holds focus, and hides again on its own. There is no `s-data`, no directive, and
no JavaScript to wire up. You just nest the tip inside the trigger.

```summit
<span class="s-tooltip">
  <button class="s-btn s-btn-outline">Hover or focus me</button>
  <span class="s-tip">Saved just now</span>
</span>
```

## Structure

A tooltip is two parts inside one wrapper:

- `.s-tooltip` is the wrapper. It positions the tip and listens for hover and
  focus through CSS alone.
- Inside it goes your trigger (a button or link) and a `<span class="s-tip">`
  holding the text.

The tip is hidden until the wrapper matches `:hover` or `:focus-within`, so it
appears both when you point at the trigger and when a keyboard user tabs onto
it. That is why the trigger should be a naturally focusable element. If you wrap
something that is not focusable, add `tabindex="0"` so keyboard users reach it
too.

## Any trigger

The wrapper works around a button, an icon button, or plain inline text. Keep
the tip short: it renders on a single line and does not wrap.

```summit
<div class="s-row">
  <span class="s-tooltip">
    <button class="s-btn">Publish</button>
    <span class="s-tip">Goes live immediately</span>
  </span>
  <span class="s-tooltip">
    <button class="s-btn s-btn-icon s-btn-outline" aria-label="More info">?</button>
    <span class="s-tip">What is this?</span>
  </span>
</div>
```

## Copy and paste

```html
<span class="s-tooltip">
  <button class="s-btn">Hover me</button>
  <span class="s-tip">Helpful hint</span>
</span>
```

## Notes

- No state is involved. The tooltip needs no `s-data` and adds nothing to your
  JavaScript, so you can drop it anywhere, even into otherwise static markup.
- Because it is CSS-only, the tip always sits above the trigger and centered. It
  does not measure the viewport or flip to stay on screen, so avoid it right at
  the top edge of the page.
- Text stays on one line by design. For anything longer, or for content that
  should open on click and hold buttons or fields, reach for a
  [Popover](../comp-popover/) instead.
- Browse the rest of the set on the [UI Library overview](../components/).

---

# Dialog

> A modal dialog for confirmations and focused tasks, with overlay and Escape to close.

A dialog interrupts the page to ask for a decision or hold a short, focused task.
It draws an overlay across the page, floats a panel in the center, and traps the
user's attention until they act or dismiss it. Everything is driven by one piece
of state: a boolean that says whether the dialog is open. A button flips it on,
and the overlay, the close button, and the `Escape` key flip it back off.

```summit
<div s-data="{ open: false }">
  <button class="s-btn" @click="open = true">Open dialog</button>
  <template s-if="open">
    <div class="s-overlay" @click="open = false"></div>
    <div class="s-dialog" role="dialog" aria-modal="true" s-trap="open" @keydown.escape.window="open = false">
      <div class="s-dialog-header"><h3 class="s-dialog-title">Delete project</h3></div>
      <button class="s-dialog-close" @click="open = false" aria-label="Close">&times;</button>
      <div class="s-dialog-body">This action cannot be undone.</div>
      <div class="s-dialog-footer">
        <button class="s-btn s-btn-ghost" @click="open = false">Cancel</button>
        <button class="s-btn s-btn-danger" @click="open = false">Delete</button>
      </div>
    </div>
  </template>
</div>
```

## Opening and closing

The whole component lives on the `open` boolean in `s-data`. The trigger button
sets it to `true`, and every path out of the dialog sets it back to `false`. The
overlay and panel sit inside a `<template s-if="open">`, so they are added to the
page only while the dialog is open and removed cleanly when it closes. Using
[s-if](../s-if/) here, rather than [s-show](../s-show/), means the markup does not
sit hidden in the DOM between openings.

There are three ways to close it, and all of them write the same state:

- The overlay: `@click="open = false"` on `.s-overlay` closes when the user
  clicks the dimmed area behind the panel.
- The `Escape` key: `@keydown.escape.window="open = false"` listens on the window
  so the key works no matter where focus sits.
- The close button: the `.s-dialog-close` in the corner, plus the Cancel button
  in the footer.

## The pieces

The panel is built from a small set of slots you fill in:

- `.s-overlay` is the fixed, dimmed backdrop. It also acts as the click-to-close
  surface.
- `.s-dialog` is the centered panel. Give it `role="dialog"` and
  `aria-modal="true"` so assistive tech announces it as a modal.
- `.s-dialog-header` wraps the `.s-dialog-title`.
- `.s-dialog-close` is the corner dismiss button. Label it with `aria-label`
  since its only content is a glyph.
- `.s-dialog-body` holds the message or form.
- `.s-dialog-footer` right-aligns the actions. Pair a neutral
  [button](../comp-button/) for cancel with a solid or danger one for confirm.

```html
<div s-data="{ open: false }">
  <button class="s-btn" @click="open = true">Open dialog</button>
  <template s-if="open">
    <div class="s-overlay" @click="open = false"></div>
    <div class="s-dialog" role="dialog" aria-modal="true" s-trap="open" @keydown.escape.window="open = false">
      <div class="s-dialog-header">
        <h3 class="s-dialog-title">Delete project</h3>
      </div>
      <button class="s-dialog-close" @click="open = false" aria-label="Close">&times;</button>
      <div class="s-dialog-body">This action cannot be undone.</div>
      <div class="s-dialog-footer">
        <button class="s-btn s-btn-ghost" @click="open = false">Cancel</button>
        <button class="s-btn s-btn-danger" @click="open = false">Delete</button>
      </div>
    </div>
  </template>
</div>
```

## Side panel variant

Swap `.s-dialog` for `.s-drawer` and the panel docks to the right edge and runs
the full height of the viewport, which suits filters, details, and longer forms.
The overlay, the state, and every close path stay exactly the same; only the
panel class changes.

```html
<div class="s-overlay" @click="open = false"></div>
<div class="s-drawer" role="dialog" aria-modal="true" @keydown.escape.window="open = false">
  <div class="s-dialog-header">
    <h3 class="s-dialog-title">Filters</h3>
  </div>
  <button class="s-dialog-close" @click="open = false" aria-label="Close">&times;</button>
  <div class="s-dialog-body">Panel content.</div>
</div>
```

## Rendering in a real app

The demo above keeps the overlay next to its trigger so the example stays
self-contained. In a real layout that is risky: an ancestor with `overflow:
hidden` can clip the panel, and a local stacking context can push it behind other
content. The fix is to render the dialog at the end of `<body>`, clear of any
parent, with [s-teleport](../s-teleport/):

```html
<div s-data="{ open: false }">
  <button class="s-btn" @click="open = true">Open dialog</button>
  <template s-teleport="body">
    <template s-if="open">
      <div class="s-overlay" @click="open = false"></div>
      <div class="s-dialog" role="dialog" aria-modal="true" s-trap="open" @keydown.escape.window="open = false">
        <div class="s-dialog-body">I render at the end of body, clear of overflow.</div>
      </div>
    </template>
  </template>
</div>
```

The panel is authored inside the component, so `open` and the close handlers keep
working, but it lands at the end of the page where nothing can clip or restack it.

## Accessibility

Mark the panel with `role="dialog"` and `aria-modal="true"` so screen readers
announce it as a modal and treat the content behind it as inert. Point the panel
at its title with `aria-labelledby` (pair the `.s-dialog-title` with an id, which
the [$id](../magic-id/) magic can generate) so the dialog has an accessible name.
The `Escape` handler is bound with `.window`, so the key closes the dialog from
anywhere, which matches the behavior users expect. Give the corner close button an
`aria-label`, since its `&times;` glyph is not a readable name. When you open a
dialog, move focus into it and return focus to the trigger on close so keyboard
users are not stranded.

For a menu of actions rather than a blocking decision, reach for the
[Dropdown Menu](../comp-menu/).

---

# Dropdown Menu

> A button-triggered menu that closes on outside click or Escape.

A dropdown menu hangs a short list of actions off a button. You click the button
to reveal it, pick an action, and it gets out of the way, either because you chose
something, clicked elsewhere, or pressed `Escape`. Like the rest of the library it
runs on one boolean in `s-data`, and the two dismissal paths, outside click and
`Escape`, are wired with plain [event modifiers](../events/).

```summit
<div class="s-anchor" s-data="{ open: false }" @keydown.escape="open = false">
  <button class="s-btn s-btn-outline" @click="open = !open">Options</button>
  <div class="s-menu" s-show="open" @click.outside="open = false">
    <button class="s-menu-item">Edit</button>
    <button class="s-menu-item">Duplicate</button>
    <div class="s-menu-sep"></div>
    <button class="s-menu-item is-danger">Delete</button>
  </div>
</div>
```

## Toggling

The trigger runs `@click="open = !open"`, so clicking it flips the menu open and
closed. The menu itself is a `.s-menu` shown with [s-show](../s-show/), which keeps
the markup in the DOM and toggles its visibility. The wrapper carries the class
`.s-anchor`, which positions the menu absolutely just under the button, so the
list floats over the page instead of pushing content down.

## Closing again

Two handlers cover the ways a menu should dismiss itself:

- Outside click: `@click.outside="open = false"` on the `.s-menu` fires when a
  click lands anywhere outside the menu, so clicking away closes it.
- `Escape`: `@keydown.escape="open = false"` on the wrapper closes the menu from
  the keyboard.

Because the whole thing shares one `open` value, the two paths cannot drift out of
sync.

## The items

The menu is a stack of building blocks you arrange to taste:

- `.s-menu-item` is a single action. Use a `<button>` for actions and an `<a>` for
  links; both pick up the same styling.
- `.s-menu-label` is a small uppercase heading you place above a group of related
  items to caption a section.
- `.s-menu-sep` is a thin divider that splits the list into groups.
- `.is-danger` on an item paints it in the danger color, which suits destructive
  actions like Delete.

```html
<div class="s-anchor" s-data="{ open: false }" @keydown.escape="open = false">
  <button class="s-btn s-btn-outline" @click="open = !open">Options</button>
  <div class="s-menu" s-show="open" @click.outside="open = false">
    <div class="s-menu-label">Actions</div>
    <button class="s-menu-item">Edit</button>
    <button class="s-menu-item">Duplicate</button>
    <div class="s-menu-sep"></div>
    <button class="s-menu-item is-danger">Delete</button>
  </div>
</div>
```

## Accessibility

The trigger is a real `<button>`, so it is focusable and operable with `Enter` and
`Space` out of the box, and each `.s-menu-item` is a button or link for the same
reason. Set `aria-haspopup="menu"` on the trigger and reflect the open state with
`aria-expanded`, bound to your state with [s-bind](../s-bind/), so assistive tech
knows a menu is attached and whether it is showing. The `Escape` handler gives
keyboard users a quick way out, matching the behavior of native menus, and the
outside-click handler keeps a stray open menu from lingering. When the menu opens,
move focus to the first item so the arrow keys and typing land somewhere sensible.

For a blocking confirmation rather than a list of actions, reach for the
[Dialog](../comp-dialog/); for free-form content in a floating panel, see the
[Popover](../comp-popover/).

---

# Popover

> A click-triggered floating panel for rich content, dismissed on outside click or Escape.

A popover is a small floating panel you open with a click to show rich content
next to its trigger: a short form, a set of controls, a detail card. It is more
than a [Tooltip](../comp-tooltip/), which only shows a line of text on hover, and
looser than a [Dropdown Menu](../comp-menu/), which holds a list of actions. The
markup is a `.s-anchor` that positions the floating `.s-popover`, wired with the
same handful of `s-` directives you already use.

## A live popover

The `.s-anchor` establishes the positioning context, the button toggles `open`,
and the `.s-popover` shows while `open` is `true`. Two directives handle
dismissal: `@click.outside` closes the panel when you click anywhere else, and
`@keydown.escape` closes it from the keyboard.

```summit
<div class="s-anchor" s-data="{ open: false }" @keydown.escape="open = false">
  <button class="s-btn s-btn-outline" @click="open = !open">Show popover</button>
  <div class="s-popover" s-show="open" @click.outside="open = false">
    <p style="margin:0 0 .4rem;font-weight:600">Dimensions</p>
    <p style="margin:0;color:var(--muted);font-size:.88rem">Set the width and height of the layer.</p>
  </div>
</div>
```

```html
<div class="s-anchor" s-data="{ open: false }" @keydown.escape="open = false">
  <button class="s-btn s-btn-outline" @click="open = !open">Show popover</button>
  <div class="s-popover" s-show="open" @click.outside="open = false">
    <p style="margin:0 0 .4rem;font-weight:600">Dimensions</p>
    <p style="margin:0;color:var(--muted);font-size:.88rem">Set the width and height of the layer.</p>
  </div>
</div>
```

## A panel with controls

Because a popover holds real content, you can put inputs and buttons inside it.
Clicks that land within the panel do not trigger `@click.outside`, so typing in a
field keeps the popover open. Wire a confirming action to set `open = false` so
the panel closes once the user is done.

```summit
<div class="s-anchor" s-data="{ open: false, name: 'Untitled' }" @keydown.escape="open = false">
  <button class="s-btn" @click="open = !open">Rename</button>
  <div class="s-popover" s-show="open" @click.outside="open = false">
    <label class="s-label">Project name</label>
    <input class="s-input" s-model="name">
    <div class="s-row" style="margin-top:.7rem;justify-content:flex-end">
      <button class="s-btn s-btn-ghost s-btn-sm" @click="open = false">Cancel</button>
      <button class="s-btn s-btn-sm" @click="open = false">Save</button>
    </div>
  </div>
</div>
```

```html
<div class="s-anchor" s-data="{ open: false, name: 'Untitled' }" @keydown.escape="open = false">
  <button class="s-btn" @click="open = !open">Rename</button>
  <div class="s-popover" s-show="open" @click.outside="open = false">
    <label class="s-label">Project name</label>
    <input class="s-input" s-model="name">
    <div class="s-row" style="margin-top:.7rem;justify-content:flex-end">
      <button class="s-btn s-btn-ghost s-btn-sm" @click="open = false">Cancel</button>
      <button class="s-btn s-btn-sm" @click="open = false">Save</button>
    </div>
  </div>
</div>
```

## Positioning

The `.s-popover` is absolutely positioned against its `.s-anchor`, opening just
below the trigger and aligned to its left edge. Because the anchor is the
positioning context, keep the trigger and the panel together inside the same
`.s-anchor`. To place the panel elsewhere, override `top`, `left`, or `right` on
`.s-popover` in your own styles; to widen it past the default `260px`, set a new
`width`.

## Notes

Toggling `open` drives everything, so a single boolean is the whole state model.
Keep `@click.outside` and `@keydown.escape` on the panel and the anchor so the
popover always has a way out, whether the user reaches for the mouse or the
keyboard. For accessibility, add `aria-expanded` bound to `open` on the trigger
and point `aria-controls` at the panel's id, which you can generate with the
[$id](../magic-id/) magic.

For a hover hint of plain text, use a [Tooltip](../comp-tooltip/). For a list of
commands or links, reach for a [Dropdown Menu](../comp-menu/), which shares the
same `.s-anchor` and dismissal pattern. The event modifiers used here are covered
on the [Events](../events/) page.

---

# Toast

> Transient notifications that stack and auto-dismiss.

A toast is a short, transient notification that slides into a corner to confirm
an action or report a result, then clears itself after a moment. Toasts stack in
a fixed `.s-toast-viewport` so several can show at once, newest below the last.
Each one is a `.s-toast` you render from an array with [s-for](../s-for/), which
means adding and removing entries is all it takes to raise and clear them.

## A live toast

The state is an array of toasts. The `add()` method pushes a new entry with a
unique id from `Date.now()`, then schedules `dismiss(id)` with `setTimeout` so
the toast clears itself after three seconds. Manual dismissal calls the same
`dismiss()`, which filters the entry out of the array.

```summit
<div s-data="{ toasts: [], add() { const id = Date.now(); this.toasts.push({ id: id, title: 'Saved', desc: 'Your changes are live.' }); setTimeout(() => this.dismiss(id), 3000); }, dismiss(id) { this.toasts = this.toasts.filter(t => t.id !== id); } }">
  <button class="s-btn" @click="add()">Show toast</button>
  <div class="s-toast-viewport">
    <template s-for="t in toasts" :key="t.id">
      <div class="s-toast s-toast-success">
        <div><p class="s-toast-title" s-text="t.title"></p><p class="s-toast-desc" s-text="t.desc"></p></div>
        <button class="s-btn s-btn-ghost s-btn-icon s-btn-sm" @click="dismiss(t.id)" aria-label="Dismiss">&times;</button>
      </div>
    </template>
  </div>
</div>
```

```html
<div s-data="{
  toasts: [],
  add() {
    const id = Date.now();
    this.toasts.push({ id: id, title: 'Saved', desc: 'Your changes are live.' });
    setTimeout(() => this.dismiss(id), 3000);
  },
  dismiss(id) {
    this.toasts = this.toasts.filter(t => t.id !== id);
  }
}">
  <button class="s-btn" @click="add()">Show toast</button>
  <div class="s-toast-viewport">
    <template s-for="t in toasts" :key="t.id">
      <div class="s-toast s-toast-success">
        <div>
          <p class="s-toast-title" s-text="t.title"></p>
          <p class="s-toast-desc" s-text="t.desc"></p>
        </div>
        <button class="s-btn s-btn-ghost s-btn-icon s-btn-sm" @click="dismiss(t.id)" aria-label="Dismiss">&times;</button>
      </div>
    </template>
  </div>
</div>
```

## Auto-dismiss and manual dismiss

Every toast gets a `setTimeout(() => this.dismiss(id), 3000)` when it is added,
so it disappears on its own after three seconds. The close button on each toast
calls the same `dismiss(id)`, letting the user clear it early. Because both paths
filter by the toast's id, dismissing one never disturbs the others still on
screen. Change the timeout to hold toasts longer, or drop it for a toast the user
must close by hand.

## Success and danger variants

The left border of a toast carries its meaning. The base `.s-toast` uses the
accent color; add `.s-toast-success` for a confirmation or `.s-toast-danger` for
an error. Here `add(type)` picks the class and the copy from the kind of toast
you asked for.

```summit
<div s-data="{ toasts: [], add(type) { const id = Date.now(); const ok = type === 'success'; this.toasts.push({ id: id, cls: ok ? 's-toast-success' : 's-toast-danger', title: ok ? 'Saved' : 'Upload failed', desc: ok ? 'Your changes are live.' : 'The file was too large.' }); setTimeout(() => this.dismiss(id), 3000); }, dismiss(id) { this.toasts = this.toasts.filter(t => t.id !== id); } }">
  <div class="s-row">
    <button class="s-btn s-btn-outline" @click="add('success')">Success toast</button>
    <button class="s-btn s-btn-outline" @click="add('danger')">Danger toast</button>
  </div>
  <div class="s-toast-viewport">
    <template s-for="t in toasts" :key="t.id">
      <div class="s-toast" :class="t.cls">
        <div><p class="s-toast-title" s-text="t.title"></p><p class="s-toast-desc" s-text="t.desc"></p></div>
        <button class="s-btn s-btn-ghost s-btn-icon s-btn-sm" @click="dismiss(t.id)" aria-label="Dismiss">&times;</button>
      </div>
    </template>
  </div>
</div>
```

```html
<div class="s-toast" :class="t.cls">
  <div>
    <p class="s-toast-title" s-text="t.title"></p>
    <p class="s-toast-desc" s-text="t.desc"></p>
  </div>
  <button class="s-btn s-btn-ghost s-btn-icon s-btn-sm" @click="dismiss(t.id)" aria-label="Dismiss">&times;</button>
</div>
```

## Notes

The examples keep the toast list in local `s-data` so each is self-contained, but
in a real app you want one viewport and a single list that any component can add
to. Move the array and its `add()` and `dismiss()` methods into a global
[Summit.store](../globals-store/), render the viewport once near the root, and
raise a toast from anywhere with `$store.toasts.add(...)`. That way a save button
in one corner and a form in another share the same stack instead of each managing
its own.

The `.s-toast-viewport` is `position: fixed`, so it floats above the page no
matter where it sits in the markup. Keep the `:key="t.id"` on the `s-for` so
Summit tracks each toast by identity as the array changes, which keeps
auto-dismiss and manual dismiss from removing the wrong one. For a persistent,
inline message rather than a transient one, use an [Alert](../comp-alert/)
instead.

---

# Tabs

> Switch between panels with an underlined or soft tab bar.

Tabs let you split related content into panels and show one at a time. There is
no widget to wire up: a tab is a real `<button>`, the active one is marked with a
class, and each panel is revealed with [s-show](../s-show/). One piece of state,
the name of the current tab, drives the whole thing.

## A live tab bar

The `.s-tabs-list` holds the buttons and draws the underline. Each `.s-tab`
clicks to set `tab` to its own name, and `:class` paints `is-active` on whichever
one matches. The panels below use `s-show` so only the current one renders.

```summit
<div s-data="{ tab: 'account' }">
  <div class="s-tabs-list" role="tablist">
    <button class="s-tab" :class="{ 'is-active': tab === 'account' }" @click="tab = 'account'">Account</button>
    <button class="s-tab" :class="{ 'is-active': tab === 'billing' }" @click="tab = 'billing'">Billing</button>
  </div>
  <div class="s-tab-panel" s-show="tab === 'account'">Manage your account.</div>
  <div class="s-tab-panel" s-show="tab === 'billing'">Update your plan.</div>
</div>
```

```html
<div s-data="{ tab: 'account' }">
  <div class="s-tabs-list" role="tablist">
    <button class="s-tab" :class="{ 'is-active': tab === 'account' }" @click="tab = 'account'">Account</button>
    <button class="s-tab" :class="{ 'is-active': tab === 'billing' }" @click="tab = 'billing'">Billing</button>
  </div>
  <div class="s-tab-panel" s-show="tab === 'account'">Manage your account.</div>
  <div class="s-tab-panel" s-show="tab === 'billing'">Update your plan.</div>
</div>
```

## Soft variant

Wrap the exact same markup in a parent with `class="s-tabs-soft"` and the
underlined bar becomes a padded pill group, with the active tab lifted onto a
raised surface. Nothing about the behavior changes; only the container class is
added.

```summit
<div class="s-tabs-soft" s-data="{ tab: 'account' }">
  <div class="s-tabs-list" role="tablist">
    <button class="s-tab" :class="{ 'is-active': tab === 'account' }" @click="tab = 'account'">Account</button>
    <button class="s-tab" :class="{ 'is-active': tab === 'billing' }" @click="tab = 'billing'">Billing</button>
  </div>
  <div class="s-tab-panel" s-show="tab === 'account'">Manage your account.</div>
  <div class="s-tab-panel" s-show="tab === 'billing'">Update your plan.</div>
</div>
```

```html
<div class="s-tabs-soft" s-data="{ tab: 'account' }">
  <div class="s-tabs-list" role="tablist">
    <button class="s-tab" :class="{ 'is-active': tab === 'account' }" @click="tab = 'account'">Account</button>
    <button class="s-tab" :class="{ 'is-active': tab === 'billing' }" @click="tab = 'billing'">Billing</button>
  </div>
  <div class="s-tab-panel" s-show="tab === 'account'">Manage your account.</div>
  <div class="s-tab-panel" s-show="tab === 'billing'">Update your plan.</div>
</div>
```

## Notes

- The current tab is just a string on `s-data`, so you can set a default by
  starting it at the tab you want open, or restore it from a URL or storage.
- Each tab is a real button, so it is reachable with `Tab` and activates with
  `Enter` or `Space` for free. Add `role="tablist"` on the list and pair panels
  with `role="tabpanel"` if you want the full ARIA tab semantics.
- Prefer `s-show` here so panel state stays in the DOM as you switch. If a panel
  is expensive and should only mount when opened, use [s-if](../s-if/) instead.

For stacked sections that expand in place rather than swap, see
[Accordion](../comp-accordion/). The whole set is on the
[overview](../components/).

---

# Accordion

> Collapsible sections, single or multiple open.

An accordion stacks sections that expand and collapse in place. Each header is a
real `<button>`, the chevron rotates through a class, and the panel below is
revealed with [s-show](../s-show/). The classic behavior is one section open at a
time, which takes a single string of state.

## One open at a time

Track which item is `open` as a string. Each trigger toggles: click the open one
and it sets `open` back to empty; click a closed one and it takes over. Because
only one value can match, opening a section closes whatever was open before.

```summit
<div class="s-accordion" s-data="{ open: 'a' }">
  <div class="s-accordion-item">
    <button class="s-accordion-trigger" :class="{ 'is-open': open === 'a' }" @click="open = open === 'a' ? '' : 'a'">
      <span>Is it accessible?</span>
      <svg class="s-chevron" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 9 6 6 6-6"/></svg>
    </button>
    <div class="s-accordion-panel" s-show="open === 'a'">Yes, every control is a real button.</div>
  </div>
  <div class="s-accordion-item">
    <button class="s-accordion-trigger" :class="{ 'is-open': open === 'b' }" @click="open = open === 'b' ? '' : 'b'">
      <span>Can I open many?</span>
      <svg class="s-chevron" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 9 6 6 6-6"/></svg>
    </button>
    <div class="s-accordion-panel" s-show="open === 'b'">Track an array instead of a single value.</div>
  </div>
</div>
```

```html
<div class="s-accordion" s-data="{ open: 'a' }">
  <div class="s-accordion-item">
    <button class="s-accordion-trigger" :class="{ 'is-open': open === 'a' }" @click="open = open === 'a' ? '' : 'a'">
      <span>Is it accessible?</span>
      <svg class="s-chevron" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 9 6 6 6-6"/></svg>
    </button>
    <div class="s-accordion-panel" s-show="open === 'a'">Yes, every control is a real button.</div>
  </div>
  <div class="s-accordion-item">
    <button class="s-accordion-trigger" :class="{ 'is-open': open === 'b' }" @click="open = open === 'b' ? '' : 'b'">
      <span>Can I open many?</span>
      <svg class="s-chevron" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 9 6 6 6-6"/></svg>
    </button>
    <div class="s-accordion-panel" s-show="open === 'b'">Track an array instead of a single value.</div>
  </div>
</div>
```

## Allowing multiple open

To let several sections stay open at once, track an array of open ids instead of
a single string. Each trigger toggles its own membership: if the id is already in
the array, `splice` it out; otherwise `push` it in. The class check and the panel
both test with `includes`.

```summit
<div class="s-accordion" s-data="{ open: ['a'] }">
  <div class="s-accordion-item">
    <button class="s-accordion-trigger" :class="{ 'is-open': open.includes('a') }" @click="open.includes('a') ? open.splice(open.indexOf('a'), 1) : open.push('a')">
      <span>Shipping</span>
      <svg class="s-chevron" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 9 6 6 6-6"/></svg>
    </button>
    <div class="s-accordion-panel" s-show="open.includes('a')">Orders ship within two business days.</div>
  </div>
  <div class="s-accordion-item">
    <button class="s-accordion-trigger" :class="{ 'is-open': open.includes('b') }" @click="open.includes('b') ? open.splice(open.indexOf('b'), 1) : open.push('b')">
      <span>Returns</span>
      <svg class="s-chevron" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 9 6 6 6-6"/></svg>
    </button>
    <div class="s-accordion-panel" s-show="open.includes('b')">Return anything within thirty days.</div>
  </div>
</div>
```

## Notes

- Every trigger is a real button, so it is keyboard reachable and toggles with
  `Enter` or `Space` without extra wiring.
- The `.s-chevron` rotates on its own through the `is-open` class in
  `components.css`; you only bind the class, never the transform.
- Start `open` at an id (or seed the array) to have a section expanded on first
  render, or set it to `''` (or `[]`) to begin fully collapsed.

For swapping between panels rather than stacking them, see
[Tabs](../comp-tabs/). The whole set is on the [overview](../components/).

---

# Breadcrumb

> Show the path to the current page.

A breadcrumb shows where the current page sits in your hierarchy and lets people
step back up it. It is pure markup: a `<nav>` labeled for assistive tech, a chain
of links, and a plain `.s-sep` between each one. The last item is the current
page, so it is text rather than a link.

## The trail

Each ancestor is a normal `<a>`, separated by a `<span class="s-sep">`. The final
crumb carries `aria-current="page"` and no link, which both styles it as the
current location and tells screen readers they have arrived.

```summit
<nav class="s-breadcrumb" aria-label="Breadcrumb">
  <a href="#">Home</a><span class="s-sep">/</span>
  <a href="#">Components</a><span class="s-sep">/</span>
  <span aria-current="page">Breadcrumb</span>
</nav>
```

```html
<nav class="s-breadcrumb" aria-label="Breadcrumb">
  <a href="#">Home</a><span class="s-sep">/</span>
  <a href="#">Components</a><span class="s-sep">/</span>
  <span aria-current="page">Breadcrumb</span>
</nav>
```

## Notes

- Mark the last crumb with `aria-current="page"`. It is the one visual and
  assistive-tech signal that this crumb is where you are, and the stylesheet
  keys its stronger color off that attribute.
- Give the `<nav>` an `aria-label` such as `Breadcrumb` so it is announced as a
  distinct landmark separate from your main navigation.
- The separator is decorative. Keeping it in its own `.s-sep` span leaves the
  links clean and lets you swap the character (a slash, a chevron) in one place.
- The trail is static markup, so it drops into any page as-is. To render it from
  a route array, wrap the crumbs in a [s-for](../s-for/) and mark the final item
  with `aria-current`.

To move through pages of results rather than up a hierarchy, see
[Pagination](../comp-pagination/). The whole set is on the
[overview](../components/).

---

# Pagination

> Navigate through pages of results.

Pagination splits a long list of results into numbered pages and gives people
Prev and Next controls to move through them. One number of state, the current
page, drives which button is active and when the ends disable. The number
buttons themselves come straight out of a [s-for](../s-for/).

## A live pager

`page` holds the current page and `total` the count. Prev and Next clamp with
`Math.max` and `Math.min` so they never step past the ends, and `:disabled`
greys them out there. Each numbered button sets `page` to its own value and lights
up through `:class` when it matches.

```summit
<div s-data="{ page: 1, total: 5 }">
  <div class="s-pagination">
    <button @click="page = Math.max(1, page - 1)" :disabled="page === 1">Prev</button>
    <template s-for="n in total" :key="n">
      <button :class="{ 'is-active': page === n }" @click="page = n" s-text="n"></button>
    </template>
    <button @click="page = Math.min(total, page + 1)" :disabled="page === total">Next</button>
  </div>
</div>
```

```html
<div s-data="{ page: 1, total: 5 }">
  <div class="s-pagination">
    <button @click="page = Math.max(1, page - 1)" :disabled="page === 1">Prev</button>
    <template s-for="n in total" :key="n">
      <button :class="{ 'is-active': page === n }" @click="page = n" s-text="n"></button>
    </template>
    <button @click="page = Math.min(total, page + 1)" :disabled="page === total">Next</button>
  </div>
</div>
```

## Notes

- Prev disables at page one and Next at the last page, driven by `:disabled`. The
  stylesheet fades a disabled control and turns off its pointer events, so it
  reads as unavailable and cannot be clicked.
- `Math.max(1, page - 1)` and `Math.min(total, page + 1)` keep `page` inside
  range even if a control is clicked at the edge, so the state can never run off
  either end.
- The `is-active` class fills the current page with your accent color. Because it
  is bound with `:class`, exactly one number lights up at a time.
- `page` is a plain number, so you can watch it to fetch the matching slice of
  data, or seed it from the URL to deep-link a page.

To show where the current page sits in your site hierarchy instead, see
[Breadcrumb](../comp-breadcrumb/). The whole set is on the
[overview](../components/).

---

# Techniques

> Presentational recipes you compose with Summit's directives and classes: animated loaders, matte glassmorphism, retro interfaces, navbar patterns, and using Tailwind.

Techniques are recipes that sit on top of the core: small, self-contained
patterns you copy in and compose with the directives and components you already
use. They are pure markup plus a class, token-themed, and they work in both
light and dark.

Load the stylesheet once, then use any `s-` prefixed class from the pages below.

```html
<link rel="stylesheet" href="https://velofy.github.io/summitjs/assets/techniques.css" />
```

## Loaders

- [Loaders & Spinners](../technique-animation/): fifteen pure-CSS loaders, animated logo marks, and skeleton screens.

## Style families

- [Matte Glassmorphism](../technique-glassmorphism/): frosted, low-gloss surfaces that stay legible over anything.
- [Neumorphism](../technique-neumorphism/): soft, extruded UI built from twin light and dark shadows.
- [Claymorphism](../technique-claymorphism/): puffy, rounded, playful clay surfaces.
- [Retro UI](../technique-retro/): hard shadows and neon text.
- [Brutalism](../technique-brutalism/): stark borders, loud type, and blunt offset shadows.
- [Aurora Backgrounds](../technique-aurora/): slow, glowing color fields behind your content.
- [Glow & Spotlight](../technique-glow/): a highlight that follows the cursor across a card.

## Patterns

- [Navbar Patterns](../technique-navbars/): active links, a responsive mobile menu, and a glass bar.
- [Using Tailwind CSS](../technique-tailwind/): Summit for behavior, Tailwind for styling, no build step.

---

# Loaders & Spinners

> A gallery of pure-CSS loaders: rings, dots, bars, shapes, animated logo marks, and skeleton screens.

Loading states set the tone for how fast an app feels. Every loader here is
pure CSS, so nothing runs on the main thread to animate it. Pick one, drop in
the markup, and it inherits your accent color and both themes.

## Spinners

Ring-shaped loaders, from a plain ring to a masked conic sweep.

```summit
<div style="display:grid; grid-template-columns:repeat(auto-fill,minmax(110px,1fr)); gap:1.6rem; text-align:center">
  <div><div style="height:44px;display:grid;place-items:center"><span class="s-spinner"></span></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Ring</p></div>
  <div><div style="height:44px;display:grid;place-items:center"><span class="s-load-dual"></span></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Dual ring</p></div>
  <div><div style="height:44px;display:grid;place-items:center"><span class="s-load-dash"></span></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Dashed</p></div>
  <div><div style="height:44px;display:grid;place-items:center"><span class="s-load-arc"></span></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Arc</p></div>
  <div><div style="height:44px;display:grid;place-items:center"><span class="s-load-orbit"></span></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Orbit</p></div>
</div>
```

## Dots and bars

Good for inline or indeterminate loading, and for chat "typing" states.

```summit
<div style="display:grid; grid-template-columns:repeat(auto-fill,minmax(120px,1fr)); gap:1.6rem; text-align:center">
  <div><div style="height:44px;display:grid;place-items:center"><div class="s-dots"><span></span><span></span><span></span></div></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Bouncing dots</p></div>
  <div><div style="height:44px;display:grid;place-items:center"><div class="s-load-wave"><span></span><span></span><span></span><span></span><span></span></div></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Wave</p></div>
  <div><div style="height:44px;display:grid;place-items:center"><div class="s-load-bars"><span></span><span></span><span></span><span></span><span></span></div></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Equalizer</p></div>
  <div><div style="height:44px;display:grid;place-items:center"><div class="s-load-typing"><span></span><span></span><span></span></div></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Typing</p></div>
</div>
```

## Shapes

Squares, grids, and ripples for a bit more personality.

```summit
<div style="display:grid; grid-template-columns:repeat(auto-fill,minmax(110px,1fr)); gap:1.6rem; text-align:center">
  <div><div style="height:48px;display:grid;place-items:center"><span class="s-load-pulse"></span></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Pulse</p></div>
  <div><div style="height:48px;display:grid;place-items:center"><div class="s-load-ripple"><span></span><span></span></div></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Ripple</p></div>
  <div><div style="height:48px;display:grid;place-items:center"><div class="s-load-grid"><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span><span></span></div></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Grid</p></div>
  <div><div style="height:48px;display:grid;place-items:center"><span class="s-load-flip"></span></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Flip</p></div>
  <div><div style="height:48px;display:grid;place-items:center"><div class="s-load-bounce"><span></span><span></span></div></div><p style="margin:.55rem 0 0;font-size:.78rem;color:var(--faint)">Bounce</p></div>
</div>
```

## Animated logo marks

Three ways to bring the Summit mark to life while something loads: it breathes,
redraws its outline, or rests inside a sweeping ring. The mark is a two-part SVG
(`.sun` and `.peak`), so the same classes animate your own logo.

```summit
<div class="s-row" style="gap:2.5rem; align-items:center">
  <span class="s-logo-loader s-lg s-logo-pulse"><svg viewBox="0 0 40 32"><rect class="sun" x="21" y="3" width="9" height="9" rx="1.5" transform="rotate(45 25.5 7.5)"/><path class="peak" d="M2 28 L13 10 L20 22 L26 14 L38 28 Z"/></svg></span>
  <span class="s-logo-loader s-lg s-logo-draw"><svg viewBox="0 0 40 32"><rect class="sun" x="21" y="3" width="9" height="9" rx="1.5" transform="rotate(45 25.5 7.5)"/><path class="peak-outline" d="M2 28 L13 10 L20 22 L26 14 L38 28"/></svg></span>
  <span class="s-logo-loader s-lg s-logo-orbit"><svg viewBox="0 0 40 32"><rect class="sun" x="21" y="3" width="9" height="9" rx="1.5" transform="rotate(45 25.5 7.5)"/><path class="peak" d="M2 28 L13 10 L20 22 L26 14 L38 28 Z"/></svg></span>
</div>
```

## Indeterminate bar

```summit
<div class="s-bar" style="max-width:320px"></div>
```

## Skeleton screens

A skeleton mirrors the shape of the content that is coming, so the layout does
not jump when it arrives. Drive the swap with a boolean in `s-data`.

```summit
<div s-data="{ loading: true }">
  <button class="s-btn s-btn-sm" @click="loading = !loading">Toggle loading</button>
  <div style="margin-top:1.1rem">
    <div s-show="loading" class="s-row" style="align-items:flex-start; gap:.8rem">
      <div class="s-skel-avatar"></div>
      <div class="s-stack" style="flex:1; gap:.5rem">
        <div class="s-skel-title" style="width:45%"></div>
        <div class="s-skel-text" style="width:92%"></div>
        <div class="s-skel-text" style="width:70%"></div>
      </div>
    </div>
    <div s-show="!loading" class="s-row" style="align-items:flex-start; gap:.8rem">
      <div class="s-avatar">AL</div>
      <div>
        <p style="margin:0; font-weight:650">Ada Lovelace</p>
        <p style="margin:.2rem 0 0; color:var(--muted)">Wrote the first algorithm, long before the hardware existed to run it.</p>
      </div>
    </div>
  </div>
</div>
```

## Class reference

| Loader | Markup |
| --- | --- |
| Ring | `<span class="s-spinner"></span>` |
| Dual ring | `<span class="s-load-dual"></span>` |
| Dashed | `<span class="s-load-dash"></span>` |
| Arc | `<span class="s-load-arc"></span>` |
| Orbit | `<span class="s-load-orbit"></span>` |
| Bouncing dots | `<div class="s-dots"><span></span>×3</div>` |
| Wave | `<div class="s-load-wave"><span></span>×5</div>` |
| Equalizer | `<div class="s-load-bars"><span></span>×5</div>` |
| Typing | `<div class="s-load-typing"><span></span>×3</div>` |
| Pulse | `<span class="s-load-pulse"></span>` |
| Ripple | `<div class="s-load-ripple"><span></span><span></span></div>` |
| Grid | `<div class="s-load-grid"><span></span>×9</div>` |
| Flip | `<span class="s-load-flip"></span>` |
| Bounce | `<div class="s-load-bounce"><span></span><span></span></div>` |
| Bar | `<div class="s-bar"></div>` |
| Skeleton | `.s-skel-text`, `.s-skel-title`, `.s-skel-avatar`, `.s-skel-block` |

## Accessibility

All of these respect `prefers-reduced-motion` and stop for users who ask for
less motion. Mark a pending region with `aria-busy="true"` for screen readers.

---

# Matte Glassmorphism

> Frosted, low-gloss glass surfaces that blur what is behind them while staying legible in both themes.

Glassmorphism is a surface that blurs and tints whatever sits behind it. The
glossy version can wash out text; the matte version dials down the shine and
saturation so content stays readable over any background. Both are one class.

## Matte over a busy background

`.s-glass-matte` is a heavier frost with low gloss. Here it floats over a stage
of solid color shapes so you can see the blur at work.

```summit
<div class="s-glass-stage">
  <span class="blob b1"></span><span class="blob b2"></span><span class="blob b3"></span>
  <div class="s-glass-matte" style="padding:1.3rem 1.5rem; max-width:340px; margin:0 auto">
    <p style="margin:0 0 .3rem; font-weight:700">Matte glass</p>
    <p style="margin:0; color:var(--muted); font-size:.92rem">Frosted, low-gloss, and legible over anything behind it. No gradient, no glare.</p>
  </div>
</div>
```

## Glossy vs matte

The plain `.s-glass` keeps more transparency and saturation for a brighter,
glassier look. Choose it for accents and `.s-glass-matte` for anything holding
text.

```summit
<div class="s-glass-stage" style="display:flex; gap:1rem; flex-wrap:wrap; justify-content:center">
  <span class="blob b1"></span><span class="blob b2"></span>
  <div class="s-glass" style="padding:1rem 1.2rem; flex:1; min-width:150px">
    <p style="margin:0; font-weight:700">.s-glass</p>
    <p style="margin:.2rem 0 0; font-size:.85rem; color:var(--muted)">Bright and glossy.</p>
  </div>
  <div class="s-glass-matte" style="padding:1rem 1.2rem; flex:1; min-width:150px">
    <p style="margin:0; font-weight:700">.s-glass-matte</p>
    <p style="margin:.2rem 0 0; font-size:.85rem; color:var(--muted)">Soft and legible.</p>
  </div>
</div>
```

## Copy it in

Put a glass surface over any positioned background: an image, a photo, or the
solid color blobs used here.

```html
<div class="s-glass-stage">
  <span class="blob b1"></span><span class="blob b2"></span><span class="blob b3"></span>
  <div class="s-glass-matte" style="padding:1.3rem 1.5rem">
    Your content here.
  </div>
</div>
```

## Notes

- The effect uses `backdrop-filter`, supported in all current browsers. Where it
  is unavailable the surface degrades to a solid panel, which is still legible.
- Keep body text on `.s-glass-matte`, not `.s-glass`, for contrast.
- A glass bar makes a great sticky header. See [Navbar Patterns](../technique-navbars/).

---

# Neumorphism

> Soft, extruded UI built from twin light and dark shadows on a matching surface.

Neumorphism, or soft UI, makes elements look pressed out of, or into, the
surface behind them. The trick is two shadows: a dark one below-right and a
light one above-left, on a surface that matches the element. It reads best on a
neutral background, so place these inside a `.s-neu-surface`.

## Raised and inset

```summit
<div class="s-neu-surface">
  <div class="s-row" style="gap:1.2rem; flex-wrap:wrap">
    <div class="s-neu" style="flex:1; min-width:150px">
      <p style="margin:0; font-weight:650">Raised</p>
      <p style="margin:.25rem 0 0; color:var(--muted); font-size:.88rem">Extruded from the surface.</p>
    </div>
    <div class="s-neu-inset" style="flex:1; min-width:150px">
      <p style="margin:0; font-weight:650">Inset</p>
      <p style="margin:.25rem 0 0; color:var(--muted); font-size:.88rem">Pressed into the surface.</p>
    </div>
  </div>
</div>
```

## Buttons that press

The button sinks into an inset shadow while held.

```summit
<div class="s-neu-surface">
  <div class="s-row">
    <button class="s-neu-btn">Save</button>
    <button class="s-neu-btn">Cancel</button>
  </div>
</div>
```

## Copy it in

```html
<div class="s-neu-surface">
  <div class="s-neu">Raised card</div>
  <div class="s-neu-inset">Inset well</div>
  <button class="s-neu-btn">Press me</button>
</div>
```

## Notes

- Neumorphism needs low contrast between the element and its background, which
  can hurt legibility and focus visibility. Use it for accents, not for dense
  or critical controls.
- The classes are `.s-neu-surface` (the backing), `.s-neu` (raised),
  `.s-neu-inset` (pressed in), and `.s-neu-btn`. Shadows adapt in dark mode.

---

# Claymorphism

> Puffy, rounded, playful clay surfaces with soft inner and outer shadows.

Claymorphism is soft and toylike: big corner radii, a drop shadow for lift, and
two inner shadows that make a surface look inflated, like a pressed piece of
clay. It suits friendly, consumer, and onboarding interfaces.

## Clay card

```summit
<div class="s-clay" style="max-width:340px">
  <div class="s-row" style="gap:.8rem; align-items:center">
    <div class="s-avatar s-avatar-lg">SJ</div>
    <div>
      <p style="margin:0; font-weight:700">Streak: 7 days</p>
      <p style="margin:.2rem 0 0; color:var(--muted); font-size:.9rem">Keep it going tomorrow.</p>
    </div>
  </div>
</div>
```

## Clay buttons

```summit
<div class="s-row">
  <button class="s-clay-btn">Claim reward</button>
  <button class="s-clay-btn" style="background:var(--surface); color:var(--text)">Later</button>
</div>
```

## Copy it in

```html
<div class="s-clay">A soft, inflated card.</div>
<button class="s-clay-btn">Tap me</button>
```

## Notes

- The puffed look comes from an outer drop shadow plus inner top and bottom
  shadows. It recolors with your accent through `.s-clay-btn`.
- Pair it with the [Claymorphism](../technique-claymorphism/) accent and rounded
  [components](../components/) for a consistent, playful set.

---

# Retro UI

> Hard offset shadows and neon text for a retro, terminal, or arcade look.

Sometimes you want the opposite of soft and frosted: chunky borders, hard
shadows, monospace type, and a little glow. These classes give an interface a
retro, terminal, or arcade feel while staying token-themed.

## Retro card and tag

A thick border and a hard offset shadow, in the accent color.

```summit
<div class="s-retro" style="max-width:360px">
  <span class="s-retro-tag">New</span>
  <p style="margin:.7rem 0 0"><span class="s-neon">SUMMIT.EXE</span> loaded successfully.</p>
  <p style="margin:.4rem 0 0; color:var(--muted); font-size:.88rem">Ready for input.</p>
</div>
```

## Retro buttons

The button presses into its own shadow when you click it.

```summit
<div class="s-row">
  <button class="s-retro-btn">Start</button>
  <button class="s-retro-btn" style="background:var(--surface); color:var(--text)">Options</button>
</div>
```

## Neon glow

`.s-neon` adds a soft glow to text, built from the accent color.

```summit
<div class="s-retro" style="text-align:center; padding:1.6rem">
  <span class="s-neon" style="font-size:1.6rem">GAME OVER</span>
  <p style="margin:.6rem 0 0; font-family:var(--mono); color:var(--muted)">Insert coin to continue</p>
</div>
```

## Copy it in

```html
<div class="s-retro">
  <span class="s-retro-tag">New</span>
  <p><span class="s-neon">Hello</span>, world.</p>
</div>

<button class="s-retro-btn">Press me</button>
```

The classes are `.s-retro` (card), `.s-retro-btn` (button), `.s-retro-tag`
(label), and `.s-neon` (glow text). They read the same design tokens as
everything else, so they recolor with your accent.

---

# Brutalism

> Stark borders, loud uppercase type, and blunt offset shadows for a raw, confident look.

Neo-brutalism is loud and honest: sharp corners, thick borders, hard offset
shadows in solid black, and type that shouts. Where glass and clay are soft,
brutalism is blunt. It reads as confident and a little punk.

## Brutal card

```summit
<div class="s-brutal" style="max-width:360px">
  <span class="s-brutal-tag">Ship it</span>
  <p style="margin:.7rem 0 0; font-weight:700; font-size:1.05rem">No gradients. No apologies.</p>
  <p style="margin:.35rem 0 0; color:var(--muted)">Just borders, shadows, and nerve.</p>
</div>
```

## Brutal buttons

The button slams into its shadow when pressed.

```summit
<div class="s-row">
  <button class="s-brutal-btn s-brutal-accent">Deploy</button>
  <button class="s-brutal-btn">Cancel</button>
</div>
```

## Accent panel

```summit
<div class="s-brutal s-brutal-accent" style="max-width:360px">
  <p style="margin:0; font-weight:800; text-transform:uppercase; letter-spacing:.03em">Limited drop</p>
  <p style="margin:.3rem 0 0">Bold blocks of color, framed hard.</p>
</div>
```

## Copy it in

```html
<div class="s-brutal">
  <span class="s-brutal-tag">New</span>
  <p>Raw and framed.</p>
</div>

<button class="s-brutal-btn s-brutal-accent">Go</button>
```

The classes are `.s-brutal` (card), `.s-brutal-accent` (fill it with the accent),
`.s-brutal-btn`, and `.s-brutal-tag`. For a softer take on hard shadows, see
[Retro UI](../technique-retro/).

---

# Aurora Backgrounds

> Slow, glowing color fields that drift behind your content for a premium hero look.

An aurora is a soft field of colored light that drifts slowly behind your
content. It gives heroes and feature panels a premium, ambient feel without a
busy image. The glow lives on pseudo-elements, so your content sits cleanly on
top.

## Aurora panel

```summit
<div class="s-aurora" style="text-align:center">
  <p style="margin:0; font-family:var(--font); font-size:1.6rem; font-weight:800; letter-spacing:-.02em">Reach the summit</p>
  <p style="margin:.5rem auto 0; max-width:34ch; opacity:.85">A calm, drifting glow behind a clear message.</p>
  <button class="s-btn" style="margin-top:1.1rem">Get started</button>
</div>
```

## As a hero background

Put anything inside: a headline, a form, a call to action. The color field moves
on its own.

```html
<section class="s-aurora">
  <h1>Your headline here</h1>
  <p>Supporting copy that stays crisp on top of the glow.</p>
  <button class="s-btn">Primary action</button>
</section>
```

## Notes

- The glow uses two blurred, animated radial shapes on `::before` and `::after`.
  It runs on the compositor and pauses under `prefers-reduced-motion`.
- The panel commits to one fixed dark surface with light text in both light and
  dark themes, so the glow always reads and the copy stays legible. Recolor the
  two shapes in `techniques.css` to match your brand.
- For a foreground surface over a busy backdrop, use
  [Matte Glassmorphism](../technique-glassmorphism/) instead.

---

# Glow & Spotlight

> A soft highlight that follows the cursor across a card, driven by a tiny Summit handler.

A spotlight card puts a soft highlight under the cursor and moves it as you go.
The highlight is pure CSS; Summit's only job is to feed the pointer position
into two CSS variables. Move your cursor across the card below.

## Spotlight card

```summit
<div class="s-glow-card" s-data
     @mousemove="$el.style.setProperty('--mx', $event.offsetX + 'px'); $el.style.setProperty('--my', $event.offsetY + 'px')"
     style="max-width:380px">
  <p style="margin:0; font-weight:700">Spotlight</p>
  <p style="margin:.35rem 0 0; color:var(--muted)">A highlight follows your cursor across this card, then fades when you leave.</p>
  <div class="s-row" style="margin-top:1rem">
    <button class="s-btn s-btn-sm">Action</button>
    <button class="s-btn s-btn-sm s-btn-ghost">Dismiss</button>
  </div>
</div>
```

## How it works

The card's `::before` draws a radial highlight at `var(--mx) var(--my)` and fades
in on hover. A `@mousemove` handler writes the pointer's position, taken from
`$event`, onto the element with `$el`.

```html
<div class="s-glow-card"
     @mousemove="$el.style.setProperty('--mx', $event.offsetX + 'px');
                 $el.style.setProperty('--my', $event.offsetY + 'px')">
  Your content here.
</div>
```

## Notes

- No state is needed: the handler reads [$event](../s-on/) and writes to
  [$el](../magic-el/) directly, so there is nothing to store.
- The highlight only appears on hover, so touch users see a clean card.
- Tint the glow by changing the accent mix in the `.s-glow-card::before` rule.

---

# Navbar Patterns

> Navigation bars with active links, a responsive mobile menu, and a glass variant, wired with Summit state.

A navbar is mostly layout plus a little state: which link is active, and whether
the mobile menu is open. Summit handles the state; these classes handle the
look.

## Active link

Track the current section in `s-data` and mark the matching link.

```summit
<nav class="s-navbar" s-data="{ active: 'home' }">
  <span class="s-navbar-brand">Summit<span class="dot">.js</span></span>
  <div class="s-navbar-links">
    <a class="s-navbar-link" :class="{ 'is-active': active === 'home' }" @click="active = 'home'">Home</a>
    <a class="s-navbar-link" :class="{ 'is-active': active === 'docs' }" @click="active = 'docs'">Docs</a>
    <a class="s-navbar-link" :class="{ 'is-active': active === 'pricing' }" @click="active = 'pricing'">Pricing</a>
  </div>
  <div class="s-navbar-actions"><button class="s-btn s-btn-sm">Sign in</button></div>
</nav>
```

## Responsive with a mobile menu

Below a narrow width the inline links hide and a toggle appears. The toggle
flips an `open` flag that reveals a stacked menu. Resize the window to see it
switch.

```summit
<nav s-data="{ open: false }">
  <div class="s-navbar">
    <span class="s-navbar-brand">Summit<span class="dot">.js</span></span>
    <div class="s-navbar-links">
      <a class="s-navbar-link">Home</a>
      <a class="s-navbar-link">Docs</a>
      <a class="s-navbar-link">Pricing</a>
    </div>
    <div class="s-navbar-actions">
      <button class="s-navbar-toggle" @click="open = !open" aria-label="Toggle menu" :aria-expanded="open">&#9776;</button>
    </div>
  </div>
  <div class="s-navbar-mobile" :class="{ 'is-open': open }">
    <a class="s-navbar-link" @click="open = false">Home</a>
    <a class="s-navbar-link" @click="open = false">Docs</a>
    <a class="s-navbar-link" @click="open = false">Pricing</a>
  </div>
</nav>
```

## Glass navbar

Drop [matte glass](../technique-glassmorphism/) onto the bar for a header that
floats over the page.

```summit
<div class="s-glass-stage" style="padding:1.5rem">
  <span class="blob b1"></span><span class="blob b2"></span>
  <nav class="s-navbar s-glass-matte">
    <span class="s-navbar-brand">Summit<span class="dot">.js</span></span>
    <div class="s-navbar-links">
      <a class="s-navbar-link is-active">Home</a>
      <a class="s-navbar-link">Docs</a>
    </div>
    <div class="s-navbar-actions"><button class="s-btn s-btn-sm">Get started</button></div>
  </nav>
</div>
```

## Notes

- Make it sticky with `position: sticky; top: 0` on the `.s-navbar`.
- The classes are `.s-navbar`, `.s-navbar-brand`, `.s-navbar-links`,
  `.s-navbar-link` (`.is-active`), `.s-navbar-actions`, `.s-navbar-toggle`, and
  `.s-navbar-mobile` (`.is-open`).

---

# Using Tailwind CSS

> Summit for behavior, Tailwind for styling. They compose cleanly because Summit lives in attributes and Tailwind lives in classes.

Summit and Tailwind solve different problems and never collide. Tailwind styles
your markup through the `class` attribute; Summit adds behavior through `s-`
attributes. You can add, toggle, and compute Tailwind classes with Summit's
reactivity, and neither needs a build step.

## Toggle utilities reactively

Bind Tailwind classes with `:class`. Summit merges the reactive object with any
static `class` you already have.

```html
<div s-data="{ open: false }">
  <button class="rounded-md bg-teal-600 px-4 py-2 font-semibold text-white"
          @click="open = !open">
    Toggle
  </button>

  <p class="mt-3 text-slate-600" :class="open ? 'block' : 'hidden'">
    Now you see me.
  </p>
</div>
```

## Compute classes from state

Because `:class` takes an object, you can drive whole variants from a value.

```html
<div s-data="{ status: 'ok' }">
  <span class="rounded px-2 py-1 text-sm font-medium"
        :class="{
          'bg-green-100 text-green-700': status === 'ok',
          'bg-red-100 text-red-700': status === 'error'
        }">
    <span s-text="status"></span>
  </span>
  <button class="ml-2 underline" @click="status = status === 'ok' ? 'error' : 'ok'">flip</button>
</div>
```

## No build, both from a CDN

For a quick page, load Tailwind's browser build and Summit together. Nothing to
compile.

```html
<script src="https://cdn.tailwindcss.com"></script>
<script src="https://velofy.github.io/summitjs/summit.min.js" defer></script>

<div s-data="{ count: 0 }" class="flex items-center gap-3 p-4">
  <button class="rounded bg-slate-900 px-3 py-1.5 text-white" @click="count++">Add</button>
  <span class="text-lg font-bold" s-text="count"></span>
</div>
```

For production, use Tailwind's CLI or a framework integration to purge unused
classes, then load `summitjs` alongside your bundle exactly as above.

## Why it composes

- Summit reads only `s-`, `@`, and `:` attributes, so it never touches your
  `class` list except where you ask it to with `:class`.
- Tailwind's classes are static strings, which is exactly what Summit's
  [s-bind](../s-bind/) is best at toggling.
- The [UI Library](../components/) and [Techniques](../techniques/) are optional:
  use them, use Tailwind, or mix both in the same page.

---

# Installation

> Add Summit with a single script tag, or install it from npm for use with a bundler.

Summit ships two ways: a zero-build script you drop into any page, and an npm
package for projects that use a bundler. Both give you the same runtime.

## Script tag

The fastest path. Add one tag to your `<head>` and Summit starts on its own
once the DOM is ready. Use `defer` so it runs after the document is parsed.

```html
<script src="https://velofy.github.io/summitjs/summit.min.js" defer></script>
```

That is the entire setup. Any `s-` attributes already in the page come alive,
and so does anything you add later, because Summit watches the DOM for changes.

> Pin a version in production, for example `summitjs@0.1.0`, so a new release
> can never change your site without you knowing.

## npm

For projects with a build step, install the package:

```bash
npm install summitjs
```

Import the `Summit` global, register anything you need, then start it yourself.
Nothing runs until you call `start()`.

```js
import Summit from "summitjs";

Summit.data("counter", () => ({
  count: 0,
  increment() {
    this.count++;
  },
}));

Summit.start();
```

The package ships ES modules, a CommonJS build, and TypeScript types, so editor
autocomplete and type checking work out of the box.

## Content-Security-Policy

Summit never calls `eval` or `new Function`. Expressions in your markup are
parsed and interpreted by Summit itself, so a strict policy needs no
`'unsafe-eval'`:

```
Content-Security-Policy: script-src 'self'
```

Everything on this documentation site runs under exactly that constraint.

## Starting manually

The script-tag build starts automatically. If you would rather control the
moment yourself, for example to register custom directives first, call
`Summit.start()` and it will only run once:

```html
<script src="https://velofy.github.io/summitjs/summit.min.js"></script>
<script>
  Summit.directive("sparkle", (el) => {
    el.style.transition = "opacity .3s";
  });
  Summit.start();
</script>
```

See [Summit.start](../globals-start/) for the details.

---

# Reactivity and State

> Declare state with s-data, derive values with getters, and add behavior with methods. Summit tracks reads and updates only what changed.

State in Summit lives in a component, declared with `s-data`. Everything inside
that element can read and write the state, and every expression that reads a
value is re-run automatically when that value changes.

## Declaring state

Pass `s-data` an object literal. Its properties become reactive state.

```summit
<div s-data="{ name: 'Ada', count: 0 }">
  <p>Hello, <span s-text="name"></span>.</p>
  <button @click="count++">Clicked <span s-text="count"></span> times</button>
</div>
```

When you click, Summit knows the button's text read `count`, so it updates just
that text node. Nothing else on the page is touched.

## Derived values

A getter is a value computed from other state. Summit caches it and only
recomputes when something it depends on changes.

```summit
<div s-data="{ first: 'Ada', last: 'Lovelace', get full() { return this.first + ' ' + this.last } }">
  <input s-model="first" />
  <input s-model="last" />
  <p>Full name: <strong s-text="full"></strong></p>
</div>
```

`full` re-evaluates only when `first` or `last` change, and reading it twice in
the same render does the work once.

## Methods

Functions on the object are methods. Inside them, `this` is the component state,
so you can read and mutate freely.

```summit
<div s-data="{ count: 0, double() { this.count *= 2 } }">
  <output s-text="count">0</output>
  <button @click="count++">+1</button>
  <button @click="double()">Double</button>
</div>
```

## Reusable components

For anything beyond a small inline object, register a named provider with
[Summit.data](../globals-data/) and reference it by name. The provider is a
function that returns the state object, so each use gets its own copy.

```js
Summit.data("counter", (start = 0) => ({
  count: start,
  increment() {
    this.count++;
  },
}));
```

```html
<div s-data="counter(10)">
  <button @click="increment()">
    Count: <span s-text="count"></span>
  </button>
</div>
```

## Nested components

Components nest. An inner `s-data` can read its own state and everything from
its ancestors, with the nearest name winning on a conflict.

```summit
<div s-data="{ theme: 'teal' }">
  <p>Outer theme: <span s-text="theme"></span></p>
  <div s-data="{ label: 'inner' }">
    <p><span s-text="label"></span> can still see <span s-text="theme"></span></p>
  </div>
</div>
```

## Shared state

State that many components need lives in a store, not in `s-data`. Reach it from
any expression with the [$store](../magic-store/) magic. See
[Summit.store](../globals-store/) to create one.

---

# Templating

> Put state on the screen with s-text and s-html, and drive attributes, classes, and styles with s-bind.

Templating is how state reaches the page: text, HTML, attributes, classes, and
styles. Summit gives you three directives for it, each reactive.

## Text

`s-text` sets an element's text content. It escapes automatically, so it is
always safe for untrusted values.

```summit
<div s-data="{ user: 'Ada' }">
  <p>Signed in as <span s-text="user"></span>.</p>
</div>
```

Any expression works, not just a variable:

```html
<span s-text="'You have ' + items.length + ' items'"></span>
```

## HTML

`s-html` sets `innerHTML`. Only ever use it with content you trust, because it
is not escaped.

```html
<div s-html="renderedMarkdown"></div>
```

## Attributes

`s-bind` sets an attribute from an expression. The shorthand is a leading colon,
which is what you will normally write.

```summit
<div s-data="{ url: 'https://example.com', busy: true }">
  <a :href="url">Visit</a>
  <button :disabled="busy">Save</button>
</div>
```

Boolean attributes are handled for you: when the expression is falsy the
attribute is removed, when truthy it is added.

## Classes

Bind `class` with an object and each key is toggled by its value. Classes already
on the element in plain `class` are kept.

```summit
<div s-data="{ active: true, error: false }">
  <span class="badge" :class="{ 'is-active': active, 'is-error': error }">status</span>
  <button @click="active = !active">Toggle</button>
</div>
```

An array of names works too:

```html
<span :class="[size, active && 'on']"></span>
```

## Styles

Bind `style` with an object of camelCase or kebab-case properties.

```summit
<div s-data="{ pct: 40 }">
  <div style="height:8px;background:#e6e9ef;border-radius:4px">
    <div :style="{ width: pct + '%', height: '8px', background: '#0d9488', borderRadius: '4px' }"></div>
  </div>
  <button @click="pct = Math.min(100, pct + 10)">More</button>
</div>
```

For the full attribute reference, including how bound values merge with static
ones, see [s-bind](../s-bind/).

---

# Events

> Respond to user input with s-on and its @ shorthand, including a full set of modifiers for keys, timing, and event control.

`s-on` listens for an event and runs an expression when it fires. The shorthand
is `@`, which is what you will normally reach for.

```summit
<div s-data="{ open: false }">
  <button @click="open = !open">Toggle</button>
  <p s-show="open">Now you see it.</p>
</div>
```

## The event object

The current event is available as `$event` inside the expression.

```html
<input @input="query = $event.target.value" />
```

If the expression evaluates to a function, Summit calls it with the event, so a
bare method reference works too:

```html
<button @click="handleClick">Save</button>
```

## Modifiers

Modifiers are dot-suffixed flags that adjust how the listener behaves. They
stack in any order.

### Event control

| Modifier | Effect |
| --- | --- |
| `.prevent` | `event.preventDefault()` |
| `.stop` | `event.stopPropagation()` |
| `.self` | Only fire when the target is this element, not a child |
| `.outside` | Fire when a click lands outside this element |
| `.once` | Remove the listener after it fires once |
| `.capture` | Listen in the capture phase |
| `.passive` | Register a passive listener |

```summit
<div s-data="{ open: true }">
  <button @click="open = true">Open</button>
  <div s-show="open" @click.outside="open = false" style="padding:1rem;border:1px solid var(--border);border-radius:8px;margin-top:.5rem">
    Click anywhere outside to close.
  </div>
</div>
```

### Targets

By default the listener is attached to the element. Redirect it with `.window`
or `.document`, which is how you register global shortcuts.

```html
<div @keydown.escape.window="close()"></div>
```

### Keys

Filter keyboard events to specific keys. Named aliases include `.enter`,
`.escape`, `.tab`, `.space`, `.up` `.down` `.left` `.right` (also `.arrow-up`
and friends), `.page-up`, `.page-down`, `.home`, `.end`, `.delete`, and
`.backspace`. Any other key works by its name, for example `.k`.

```summit
<div s-data="{ log: '' }">
  <input @keydown.enter="log = 'Submitted: ' + $event.target.value" placeholder="Type and press Enter" />
  <p s-text="log"></p>
</div>
```

Combine with system keys `.shift`, `.ctrl`, `.alt`, and `.cmd` (alias `.meta`)
for shortcuts. This fires only on Cmd/Ctrl + K:

```html
<div @keydown.cmd.k.prevent="openPalette()"></div>
```

### Timing

`.debounce` waits until events stop before running; `.throttle` runs at most
once per interval. Both default to 250ms and accept a custom duration.

```html
<input @input.debounce.400ms="search()" />
```

### Name transforms

`.camel` turns a dashed event name into camelCase, and `.dot` restores dots in
event names that used dashes:

```html
<div @custom-event.camel="onCustomEvent()"></div>
```

For dispatching your own events, see [$dispatch](../magic-dispatch/). The full
directive reference is on the [s-on](../s-on/) page.

---

# Forms

> Bind form controls to state in both directions with s-model, covering text, numbers, checkboxes, radios, and selects.

`s-model` creates a two-way binding between a form control and a piece of state.
Type in the field and the state updates; change the state and the field follows.

```summit
<div s-data="{ name: '' }">
  <input s-model="name" placeholder="Your name" />
  <p>Hello<span s-text="name ? ', ' + name : ''"></span>.</p>
</div>
```

## Every control type

`s-model` reads and writes the right property for each kind of input, so the
same directive covers all of them.

```summit
<div s-data="{ text: 'hi', agree: true, size: 'M', picks: [] }">
  <p><input s-model="text" /> <span s-text="text"></span></p>
  <p><label><input type="checkbox" s-model="agree" /> Agree</label> <span s-text="agree"></span></p>
  <p>
    <select s-model="size"><option>S</option><option>M</option><option>L</option></select>
    <span s-text="size"></span>
  </p>
  <p>
    <label><input type="checkbox" value="a" s-model="picks" /> A</label>
    <label><input type="checkbox" value="b" s-model="picks" /> B</label>
    <span s-text="JSON.stringify(picks)"></span>
  </p>
</div>
```

- **Text, textarea, number, range**: bound to the value.
- **Checkbox**: a boolean when bound to a single control, or an array of the
  checked values when several share one model.
- **Radio**: the value of the selected control.
- **Select**: the chosen value, or an array when the select is `multiple`.

## Modifiers

| Modifier | Effect |
| --- | --- |
| `.lazy` / `.change` | Sync on `change` instead of every keystroke |
| `.blur` | Sync only when the field loses focus |
| `.number` | Coerce the value to a number |
| `.boolean` | Coerce `"true"` / `"false"` strings to a boolean |
| `.debounce` | Wait for typing to pause before syncing (default 250ms) |
| `.fill` | Seed empty state from the control's initial value |

```html
<input type="number" s-model.number="age" />
<input s-model.debounce.300ms="search" />
```

## Building custom inputs

Every element with `s-model` exposes `el._summitModel`, an object with `get` and
`set`, so a wrapper component can drive the same binding from custom controls.
The full reference is on the [s-model](../s-model/) page.

---

# Lifecycle

> Run code when a component initializes, react to DOM changes automatically, and clean up when elements leave.

Summit manages a component from the moment its element appears to the moment it
leaves. You can hook into that lifecycle in three places.

## Initialization

When a component is set up, Summit calls its `init()` method if it has one. This
is the place for setup work: reading storage, starting a timer, fetching data.

```js
Summit.data("clock", () => ({
  time: "",
  init() {
    this.tick();
    setInterval(() => this.tick(), 1000);
  },
  tick() {
    this.time = new Date().toLocaleTimeString();
  },
}));
```

For a one-off expression rather than a method, use the [s-init](../s-init/)
directive:

```html
<div s-data="{ ready: false }" s-init="ready = true"></div>
```

## Reacting to changes

Most of the time you do not watch for changes yourself: any expression that
reads state re-runs when that state changes. For an explicit side effect that
should re-run on change, use [s-effect](../s-effect/):

```summit
<div s-data="{ count: 0 }">
  <button @click="count++">Add</button>
  <span s-effect="$el.style.opacity = count % 2 ? 0.5 : 1" s-text="count"></span>
</div>
```

To watch a single value and get both the new and old value, use the
[$watch](../magic-watch/) magic.

## Automatic setup for new nodes

Summit watches the document with a `MutationObserver`. Any element you add later,
whether by hand, from a fetch, or from another library, is initialized the
moment it enters the DOM. There is nothing to call and no load order to get
right.

```summit
<div s-data="{ rows: [] }">
  <button @click="rows.push('Row ' + (rows.length + 1))">Add a row</button>
  <ul>
    <template s-for="row in rows" :key="row">
      <li s-text="row"></li>
    </template>
  </ul>
</div>
```

## Cleanup

When an element is removed, Summit tears its component down and runs every
cleanup registered for it: event listeners are removed, effects are stopped,
and timers you registered through a directive are cleared. Keyed
[s-for](../s-for/) reuses nodes across updates, so state is preserved for rows
that merely moved.

## Waiting for the DOM

After you change state, the DOM updates on the next tick. To run code after that
update lands, use [$nextTick](../magic-nextTick/):

```html
<button @click="open = true; $nextTick(() => $refs.panel.focus())">Open</button>
```

## Page-level events

Summit dispatches `summit:init` on `document` just before it initializes the
page, and `summit:initialized` once it has finished. Listen for them to run code
around startup, for example to register a plugin before anything renders.

---

# s-data

> Declare a reactive component and its state.

`s-data` marks an element as a component and gives it state. Everything inside
that element, its own directives and every descendant, can read and write that
state, and Summit re-runs the expressions that depend on a value whenever the
value changes.

## Inline state

Pass `s-data` an object literal. Its properties become reactive state that the
whole subtree can use.

```summit
<div s-data="{ name: 'Ada', count: 0 }">
  <p>Hello, <span s-text="name"></span>.</p>
  <button @click="count++">Clicked <span s-text="count"></span> times</button>
</div>
```

An empty component is fine too. `s-data` on its own (or `s-data=""`) starts with
an empty object, which is handy when the element only needs an [s-init](../s-init/)
or a place to hang [$refs](../magic-refs/).

## Getters

A getter defines a value derived from other state. Summit turns each getter into
a cached computed, so it recomputes only when something it read changes and
returns the cached result the rest of the time.

```summit
<div s-data="{ first: 'Ada', last: 'Lovelace', get full() { return this.first + ' ' + this.last } }">
  <input s-model="first" />
  <input s-model="last" />
  <p>Full name: <strong s-text="full"></strong></p>
</div>
```

Read `full` in ten places and it still runs once per change to `first` or
`last`.

## Methods

A function property is a method. Summit binds it to the component, so `this` is
always the state whether you call it as `double()` or `this.double()`, and
assigning to `this.count` triggers reactivity.

```summit
<div s-data="{ count: 0, double() { this.count *= 2 } }">
  <output s-text="count">0</output>
  <button @click="count++">+1</button>
  <button @click="double()">Double</button>
</div>
```

## init()

If the state object has an `init()` method, Summit calls it once as the
component is set up, before its children initialize. Use it to seed values,
start a timer, or kick off a fetch. A matching `destroy()` method, if present,
runs when the component is torn down.

```summit
<div s-data="{ now: '', init() { this.now = new Date().toLocaleTimeString() } }">
  <p>Loaded at <span s-text="now"></span>.</p>
</div>
```

Inside `init()`, and inside any method, the `$`-magics are reachable through
`this`, so `this.$refs`, `this.$watch`, and `this.$el` all work.

## Named providers

For anything past a small inline object, register the state once with
[Summit.data](../globals-data/) and reference it by name. The provider is a
function that returns the state object, so every element that uses it gets a
fresh copy.

```js
Summit.data("counter", (start = 0) => ({
  count: start,
  increment() {
    this.count++;
  },
}));
```

Call it with arguments right in the attribute. The name is matched first against
your registered providers, and the arguments are evaluated in the surrounding
scope.

```html
<div s-data="counter(10)">
  <button @click="increment()">
    Count: <span s-text="count"></span>
  </button>
</div>
```

## Nesting and scope

Components nest freely. An inner `s-data` sees its own state plus everything from
its ancestors, and the nearest name wins when two scopes define the same key.

```summit
<div s-data="{ theme: 'teal' }">
  <p>Outer theme: <span s-text="theme"></span></p>
  <div s-data="{ label: 'inner' }">
    <p><span s-text="label"></span> can still read <span s-text="theme"></span></p>
  </div>
</div>
```

State that many unrelated components share belongs in a store rather than
`s-data`. Create one with [Summit.store](../globals-store/) and reach it from any
expression with [$store](../magic-store/).

---

# s-bind

> Bind attributes, classes, and styles, with the colon shorthand.

`s-bind` sets an attribute from an expression and keeps it in sync as the data
behind that expression changes. The shorthand is `:`, which is what you will
normally write.

```summit
<div s-data="{ label: 'Save changes' }">
  <button :title="label" s-text="label"></button>
</div>
```

`:title="label"` is exactly `s-bind:title="label"`. Whenever `label` changes,
the attribute updates.

## Boolean attributes

For HTML boolean attributes such as `disabled`, `checked`, `required`,
`readonly`, `selected`, `open`, `hidden`, and `multiple`, a truthy value adds the
attribute and a falsy value removes it entirely. Summit also reflects the value
to the matching DOM property, so form state stays correct.

```summit
<div s-data="{ agreed: false }">
  <label><input type="checkbox" s-model="agreed" /> I agree</label>
  <button :disabled="!agreed">Continue</button>
</div>
```

For a non-boolean attribute the rule is similar: `false`, `null`, and
`undefined` remove the attribute, and every other value is set as a string.

## :class

`:class` merges its result with whatever is already in the static `class`
attribute, so you never lose your base classes. The value can be a string, an
object, or an array.

The object form is the common one. Each key is a class name, applied while its
value is truthy.

```summit
<div s-data="{ active: true, busy: false }">
  <style>
    .tag { padding: .25rem .5rem; border: 1px solid var(--border); border-radius: 6px; }
    .tag.active { font-weight: 700; }
    .tag.busy { opacity: .5; }
  </style>
  <span class="tag" :class="{ active: active, busy: busy }">Status</span>
  <button @click="active = !active">Toggle active</button>
</div>
```

The array form lists classes to apply, and its entries can themselves be strings
or objects, which is handy for mixing always-on classes with conditional ones.

```html
<span class="tag" :class="[size, { active: isActive }]"></span>
```

Because the static classes are always kept, put a class in `class` or in
`:class`, not both, when you want to toggle it off.

## :style

`:style` takes an object of CSS properties and merges it onto the static `style`
attribute. Property names may be written camelCase or kebab-case, and any entry
whose value is `null` or `false` is skipped.

```summit
<div s-data="{ hue: 200 }">
  <input type="range" min="0" max="360" s-model="hue" />
  <p :style="{ color: 'hsl(' + hue + ', 70%, 45%)', fontWeight: 700 }">
    Live color at hue <span s-text="hue"></span>.
  </p>
</div>
```

A string value works too and is merged the same way.

## Binding an object of attributes

Given no attribute name, `s-bind="obj"` applies a whole object at once. Plain
entries become attributes, `@`-prefixed keys become event listeners, and
`:`-prefixed keys become dynamic bindings whose function is re-run reactively.

```html
<button s-bind="{ type: 'button', ':disabled'() { return busy }, '@click'() { save() } }">
  Save
</button>
```

## .camel

HTML attribute names are case-insensitive, which is a problem for SVG and other
camelCase attributes. The `.camel` modifier converts the bound name from dashes
to camelCase, so `:view-box.camel` sets `viewBox`.

---

# s-on

> Listen for events with the @ shorthand and a full set of modifiers.

`s-on` attaches an event listener to an element and runs an expression each time
the event fires. You write it as `s-on:click="..."`, but the `@` shorthand is
what you will reach for almost every time:

```summit
<div s-data="{ count: 0 }">
  <button @click="count++">Clicked <span s-text="count"></span> times</button>
</div>
```

`@click` and `s-on:click` are exactly the same directive. The part after the
colon (or the `@`) is the event name, and everything after the first dot is a
[modifier](#modifiers).

## The event object

The native event is available inside the expression as `$event`, so you can read
the target, the pressed key, coordinates, or anything else off it.

```html
<input @input="query = $event.target.value" />
```

If your expression evaluates to a function rather than running inline, Summit
calls that function for you and passes the event as its argument. That means a
bare method reference works without writing out the call:

```html
<button @click="handleClick">Save</button>
```

Here `handleClick` receives the event, the same as if you had written
`@click="handleClick($event)"`.

## Modifiers

Modifiers are dot-suffixed flags on the directive name that change how the
listener behaves. They stack, and apart from a timing duration (which has to
follow its `.debounce` or `.throttle`) the order does not matter.

### Event control

These adjust dispatch and registration of the listener itself.

| Modifier | Effect |
| --- | --- |
| `.prevent` | Calls `event.preventDefault()` before your expression runs |
| `.stop` | Calls `event.stopPropagation()` before your expression runs |
| `.self` | Only fires when `event.target` is this element, never a descendant |
| `.outside` | Fires when the event happens outside this element (see [Targets](#targets)) |
| `.once` | Registers the listener with `{ once: true }`, so it runs at most once |
| `.capture` | Registers the listener in the capture phase (`{ capture: true }`) |
| `.passive` | Registers a passive listener (`{ passive: true }`) |

```summit
<div s-data="{ hits: 0 }">
  <button @click.once="hits++">Only counts once</button>
  <span s-text="hits"></span>
</div>
```

### Targets

By default the listener lives on the element itself. Two modifiers move it
elsewhere, which is how you register global shortcuts and dismiss-on-outside
behavior:

- `.window` attaches the listener to `window`.
- `.document` attaches it to `document`.
- `.outside` also listens on `document`, then ignores any event whose target is
  this element or one of its descendants. Events on nodes that have already been
  removed from the page are ignored too, so tearing down an element does not
  trigger it.

```summit
<div s-data="{ open: true }">
  <button @click="open = true">Open</button>
  <div s-show="open" @click.outside="open = false" style="padding:1rem;border:1px solid var(--border);border-radius:8px;margin-top:.5rem">
    Click anywhere outside this box to close it.
  </div>
</div>
```

A window-scoped keyboard shortcut looks like this:

```html
<div @keydown.escape.window="closeModal()"></div>
```

### Key filters

On a keyboard event you can restrict the listener to specific keys by adding the
key name as a modifier. Summit recognizes these aliases and maps each to the
matching `KeyboardEvent.key` value:

| Modifier | Matches `event.key` |
| --- | --- |
| `.enter` | `Enter` |
| `.tab` | `Tab` |
| `.space` | `" "` (the space bar) |
| `.esc` / `.escape` | `Escape` |
| `.up` / `.arrow-up` | `ArrowUp` |
| `.down` / `.arrow-down` | `ArrowDown` |
| `.left` / `.arrow-left` | `ArrowLeft` |
| `.right` / `.arrow-right` | `ArrowRight` |
| `.page-up` | `PageUp` |
| `.page-down` | `PageDown` |
| `.home` | `Home` |
| `.end` | `End` |
| `.delete` | `Delete` |
| `.backspace` | `Backspace` |

Any key that is not in the table matches by its own name, compared
case-insensitively (and with camelCase keys treated as their dashed form). So
`.k` matches the K key and `.a` matches A.

```summit
<div s-data="{ log: 'Nothing yet' }">
  <input @keydown.enter="log = 'Submitted: ' + $event.target.value" placeholder="Type and press Enter" />
  <p s-text="log"></p>
</div>
```

When you list more than one key filter, the listener fires if the event matches
any of them.

### System keys

System modifiers require a held modifier key. Unlike key filters, these are
combined with AND, so every one you list must be down when the event fires.

| Modifier | Requires |
| --- | --- |
| `.shift` | Shift held |
| `.ctrl` | Control held |
| `.alt` | Alt / Option held |
| `.cmd` / `.meta` | Command / Windows (Meta) held |

Combine them with a key filter to build shortcuts. This one fires only on
Cmd (or the Meta key) plus K, and blocks the browser default:

```html
<div @keydown.cmd.k.prevent.window="openPalette()"></div>
```

### Timing

`.debounce` waits until events stop arriving before running your expression, and
`.throttle` runs it at most once per interval. Both default to 250ms. To set a
custom duration, add it as the very next modifier after the timing flag. A bare
number and a `ms` suffix are milliseconds; an `s` suffix is seconds.

```html
<input @input.debounce="search()" />        <!-- 250ms -->
<input @input.debounce.400ms="search()" />   <!-- 400ms -->
<div @scroll.throttle.2s="track()"></div>    <!-- 2000ms -->
```

### Name transforms

Because HTML lowercases attribute names, two modifiers help you target events
whose names contain capitals or dots:

- `.camel` converts a dashed event name to camelCase, so `@custom-event.camel`
  listens for a `customEvent` event.
- `.dot` converts dashes back to dots, so `@my-event.dot` listens for a
  `my.event` event.

```html
<div @custom-event.camel="onCustomEvent($event.detail)"></div>
```

To send events that these modifiers can catch, use
[$dispatch](../magic-dispatch/). For the state that these listeners usually
update, see [s-data](../s-data/) and [reactivity](../reactivity-state/).

---

# s-text

> Set an element's text content from an expression.

`s-text` sets an element's text content to the value of an expression and
updates it whenever the data behind that expression changes.

```summit
<div s-data="{ name: 'Ada' }">
  <p>Hello, <span s-text="name"></span>.</p>
</div>
```

The element's existing content is replaced, so you can give it fallback text to
show before Summit loads. It is swapped out on init.

## Any expression

The value is a full expression, not just a property name, so format it inline.

```summit
<div s-data="{ price: 42 }">
  <p s-text="'$' + price.toFixed(2)"></p>
  <button @click="price++">Raise price</button>
</div>
```

`null` and `undefined` render as an empty string. Every other value is turned
into a string.

## Text is escaped

`s-text` writes through `textContent`, so whatever the expression returns shows
as literal text. HTML in the value is never parsed, which makes `s-text` safe
for user-supplied strings.

```summit
<div s-data="{ raw: '<em>not italic</em>' }">
  <p s-text="raw"></p>
</div>
```

The angle brackets appear on screen instead of creating an `<em>`. When you
deliberately want markup rendered, and only for content you trust, reach for
[s-html](../s-html/).

---

# s-html

> Set an element's innerHTML from an expression.

`s-html` sets an element's `innerHTML` to the value of an expression and re-runs
when that value changes. Reach for it when the content itself is markup, for
example a fragment rendered on the server or returned from a fetch.

```summit
<div s-data="{ note: '<strong>Saved</strong> just now' }">
  <p s-html="note"></p>
</div>
```

Unlike [s-text](../s-text/), the string is parsed as HTML, so the `<strong>`
above becomes real bold text.

## Injected markup is initialized

After setting the HTML, Summit walks the new children and initializes any Summit
directives it finds, using the surrounding component's scope. A fragment that
arrives with `s-text` or `@click` on it becomes reactive right away, with no
extra step.

## Only use it on trusted content

**Setting `innerHTML` from untrusted input is an XSS vulnerability.** A string
containing a `<script>` tag or an `onerror` handler can run code in your page.
Never point `s-html` at anything a user typed, a URL parameter, or a third-party
response you do not control.

If the source is not fully trusted, use [s-text](../s-text/) instead, which
escapes everything it renders.

---

# s-model

> Two-way binding for form controls.

`s-model` wires a form control to a piece of state in both directions. When the
user changes the control, the state updates; when the state changes from
anywhere else, the control updates to match. It replaces the pair of an
[s-bind](../s-bind/) on `value` and an [s-on](../s-on/) input listener that you
would otherwise write by hand.

```summit
<div s-data="{ name: '' }">
  <input s-model="name" placeholder="Your name" />
  <p>Hello<span s-text="name ? ', ' + name : ''"></span>.</p>
</div>
```

## How it stays in sync

Two things run under the hood. A reactive effect writes the current state into
the control whenever the state changes, and an event listener reads the control
back into the state whenever the user interacts with it. The read and write both
know which property matters for the element, so the same directive covers every
control type.

The listener defaults to the `input` event for text-like fields and switches to
`change` for `select`, `checkbox`, and `radio` elements.

## Every control type

`s-model` inspects the element and picks the right value to read and write:

- **Text, textarea, number, range**: bound to the control's value.
- **Checkbox**: a boolean when one checkbox is bound on its own, or an array of
  the checked controls' `value` attributes when several checkboxes share the same
  model.
- **Radio**: the `value` of the selected control in the group.
- **Select**: the chosen option's value, or an array of selected values when the
  `select` has the `multiple` attribute.

```summit
<div s-data="{ text: 'hi', qty: 1, agree: true, size: 'M', picks: [] }">
  <p><input s-model="text" /> <span s-text="text"></span></p>
  <p><input type="number" s-model.number="qty" /> <span s-text="qty + 1"></span></p>
  <p><label><input type="checkbox" s-model="agree" /> Agree</label> <span s-text="String(agree)"></span></p>
  <p>
    <select s-model="size"><option>S</option><option>M</option><option>L</option></select>
    <span s-text="size"></span>
  </p>
  <p>
    <label><input type="checkbox" value="a" s-model="picks" /> A</label>
    <label><input type="checkbox" value="b" s-model="picks" /> B</label>
    <span s-text="JSON.stringify(picks)"></span>
  </p>
</div>
```

## Modifiers

| Modifier | Effect |
| --- | --- |
| `.lazy` / `.change` | Sync on the `change` event instead of on every keystroke |
| `.blur` | Sync only when the control loses focus |
| `.number` | Coerce the read value with `parseFloat`, keeping the string if it is not a number |
| `.boolean` | Coerce the strings `"true"` and `"false"` to real booleans, otherwise fall back to a truthiness check |
| `.debounce` | Wait until edits pause before syncing state (default 250ms) |
| `.fill` | Seed empty state from the control's initial value on setup |

`.number` and `.boolean` apply when the value is read from text-like fields,
radios, and single selects.

`.debounce` defaults to 250ms and takes a custom duration as the next modifier,
the same as it does on [s-on](../s-on/): `ms` is milliseconds, `s` is seconds.

```html
<input type="number" s-model.number="age" />
<input s-model.debounce.300ms="search" />
<input s-model.lazy="title" />
```

### Filling from markup

`.fill` is useful when the initial value lives in the HTML rather than in
`s-data`. On setup, if the bound state is `undefined`, `null`, or an empty
string, `s-model.fill` reads the control's current value (running it through any
`.number` or `.boolean` coercion) and seeds the state with it.

```html
<input s-model.fill="color" value="#3366ff" />
```

## Building custom inputs

Every element with `s-model` gets an `_summitModel` property assigned to it, an
object with `get` and `set` functions that read and write the bound state:

```js
el._summitModel.get();      // current value
el._summitModel.set("new"); // update the state
```

A wrapper component can use this to drive the binding from a non-standard
control. Put `s-model` on the wrapper, then have the custom widget call
`_summitModel.set(...)` when its value changes and read `_summitModel.get()` to
render, and the two-way binding works exactly as it does for native inputs.

For the underlying value binding this builds on, see [s-bind](../s-bind/), and
for the form patterns it fits into, see [forms](../forms/).

---

# s-show

> Toggle an element's visibility with display.

`s-show` shows or hides an element by setting its inline `display`. The element
never leaves the DOM: it stays parsed, initialized, and keeps its state. Only
its visibility flips.

## Toggling visibility

Give `s-show` any expression. When it is truthy the element is visible, when it
is falsy it is hidden with `display: none`.

```summit
<div s-data="{ open: true }">
  <button @click="open = !open">Toggle panel</button>
  <p s-show="open">You can see me. Hide me and I stay in the DOM.</p>
</div>
```

When the expression becomes falsy, Summit sets `display: none`. When it becomes
truthy again, Summit restores whatever `display` the element had to begin with.
If you started the element at `display: flex`, that value comes back; if it had
no inline display, the property is removed so your CSS or the browser default
takes over.

## Beating stubborn CSS

If another rule forces the element to display, add the `.important` modifier so
Summit hides it with `display: none !important`.

```html
<div s-show.important="expanded">...</div>
```

## Difference from s-if

Both hide things, but they do it at different levels:

- `s-show` keeps the element in the DOM and only changes `display`. Toggling is
  cheap, and any internal state (input values, scroll position, child
  component state) is preserved while hidden.
- [s-if](../s-if/) adds and removes the element itself. When the condition is
  false the node is gone from the DOM and its reactive effects are torn down;
  when it returns it is built fresh.

Reach for `s-show` when you toggle often or need to keep state alive. Reach for
`s-if` when the element is expensive or rarely shown and you want it fully gone.

## Working with transitions

Pair `s-show` with [s-transition](../s-transition/) to animate the element as it
appears and disappears. The initial render is applied instantly; every toggle
after that runs the enter or leave animation.

```html
<div
  s-show="open"
  s-transition:enter="fade"
  s-transition:enter-start="opacity-0"
  s-transition:enter-end="opacity-100"
  s-transition:leave="fade"
  s-transition:leave-start="opacity-100"
  s-transition:leave-end="opacity-0"
>
  Fades in and out.
</div>
```

---

# s-if

> Conditionally render an element in the DOM.

`s-if` adds an element to the DOM when its expression is truthy and removes it
when it is falsy. Unlike hiding with `display`, the element genuinely comes and
goes.

## Conditionally rendering

Put `s-if` on the element you want to appear and disappear.

```summit
<div s-data="{ loggedIn: false }">
  <button @click="loggedIn = !loggedIn" s-text="loggedIn ? 'Log out' : 'Log in'">Log in</button>
  <p s-if="loggedIn">Welcome back. This paragraph is built fresh each time.</p>
  <p s-if="!loggedIn">Please log in to continue.</p>
</div>
```

Behind the scenes Summit leaves a comment marker where the element used to be.
When the condition turns true it clones the element in at that spot and
initializes it; when the condition turns false it tears the element down and
removes it. Because the node is rebuilt each time it returns, its internal state
does not carry over between removals.

## Works on any element

You do not need a `<template>` wrapper. `s-if` works directly on any element,
and the element itself (minus its `s-if` attribute) is the blueprint that gets
cloned in and out.

```html
<article s-if="post">...</article>
```

A `<template>` still works if you prefer it. In that case its single root child
is used as the blueprint:

```html
<template s-if="post">
  <article>...</article>
</template>
```

## Difference from s-show

`s-if` and [s-show](../s-show/) look similar but differ in what they do to the
element:

- `s-if` adds and removes the node. While the condition is false the element is
  not in the DOM at all and its reactive effects are destroyed. Returning to
  true rebuilds it from scratch.
- `s-show` always keeps the node in the DOM and only toggles its `display`. State
  inside it survives being hidden.

Use `s-if` when you want the element and its cost gone entirely, or when it is
rarely shown. Use `s-show` when you toggle frequently or need to preserve the
element's internal state.

For lists of elements that come and go, see [s-for](../s-for/), which reconciles
by key. To animate elements as they appear and disappear, pair
[s-transition](../s-transition/) with `s-show`.

---

# s-for

> Render a list, reconciled by key.

`s-for` renders one copy of a template for each item in a collection. It lives on
a `<template>` element and, with a `:key`, reconciles the list by key so existing
nodes are moved rather than rebuilt.

## Rendering a list

Put `s-for` on a `<template>` that wraps a single root element. Summit renders
that element once per item and inserts the results where the template stood.

```summit
<div s-data="{ colors: ['teal', 'amber', 'rose'] }">
  <ul>
    <template s-for="color in colors">
      <li s-text="color"></li>
    </template>
  </ul>
</div>
```

The template must be a `<template>` tag with exactly one root child. Summit warns
in the console if either is missing.

## Item and index

Use `item in items` for just the value, or `(item, index) in items` when you also
need the position.

```summit
<div s-data="{ tasks: ['Write docs', 'Ship it', 'Celebrate'] }">
  <ol>
    <template s-for="(task, i) in tasks">
      <li><span s-text="i + 1"></span>. <span s-text="task"></span></li>
    </template>
  </ol>
</div>
```

Each iteration gets its own scope holding `item` (and `index` if named). Those
blocks can still read state from ancestor components as usual. Both `in` and `of`
are accepted as the separator.

## Iterating a range

Give `s-for` a number and it counts from 1 up to that number.

```summit
<div s-data="{ n: 5 }">
  <div>
    <template s-for="star in n">
      <span s-text="'*'"></span>
    </template>
  </div>
</div>
```

`star in 5` yields the values `1, 2, 3, 4, 5`.

## Iterating an object

Pass an object and `(value, key) in object` gives you each entry. The second name
receives the property key.

```summit
<div s-data="{ specs: { cpu: '8 core', ram: '16 GB', ssd: '1 TB' } }">
  <dl>
    <template s-for="(value, key) in specs">
      <div><dt s-text="key"></dt><dd s-text="value"></dd></div>
    </template>
  </dl>
</div>
```

## Keyed reconciliation

Add `:key` (or `s-bind:key`) with an expression that is unique per item. When the
list changes, Summit matches items by key: a block whose key already exists is
kept and moved to its new position rather than destroyed and recreated. That
preserves DOM state such as focus, scroll, and uncommitted input values across
reorders.

```summit
<div s-data="{
  people: [{ id: 1, name: 'Ada' }, { id: 2, name: 'Grace' }, { id: 3, name: 'Alan' }],
  reverse() { this.people = [...this.people].reverse() }
}">
  <button @click="reverse()">Reverse order</button>
  <ul>
    <template s-for="person in people" :key="person.id">
      <li>
        <span s-text="person.name"></span>
        <input placeholder="type here, then reverse" />
      </li>
    </template>
  </ul>
</div>
```

Type into an input, then reverse the list: because each row is matched by
`person.id` and moved, your text stays with its person. Without a `:key`, Summit
falls back to the object key for objects, or the numeric index otherwise, which
rebuilds rows when their position changes and loses that state.

To conditionally render a single element rather than a list, see
[s-if](../s-if/).

---

# s-effect

> Run a side effect that re-runs when its reactive dependencies change.

`s-effect` runs an expression as a reactive side effect. It runs once when the
element initializes, then re-runs automatically whenever any state it read
changes. Summit tracks those reads for you, so there is no dependency list to
maintain.

```summit
<div s-data="{ count: 0 }">
  <button @click="count++">Clicked <span s-text="count"></span> times</button>
  <p s-effect="document.title = 'Count: ' + count">Watch the browser tab title.</p>
</div>
```

Each click reads `count`, so Summit re-runs the effect and the tab title
updates. Re-runs are batched onto the microtask queue, so several changes in the
same tick collapse into a single run.

## When to use it

Use `s-effect` for side effects that reach outside the reactive graph: writing
to `document.title`, syncing to `localStorage`, logging, or driving a non-Summit
library. The expression runs for what it does, not for a value it returns.

To put a value on screen you do not need `s-effect`. Bind it directly with
[s-text](../s-text/) or [s-bind](../s-bind/), or derive it with a getter, and let
that directive track its own dependencies.

```summit
<div s-data="{ count: 0 }">
  <button @click="count++">+1</button>
  <p s-text="'Count is ' + count"></p>
</div>
```

Reserve `s-effect` for the cases a plain binding cannot express. To respond to
one specific value changing rather than everything an expression touches, see
[$watch](../magic-watch/). To run something once at startup with no re-runs, use
[s-init](../s-init/).

---

# s-init

> Run an expression when the element initializes.

`s-init` runs an expression once, at the moment its element is set up. It is the
quick, inline way to do a bit of startup work without writing an `init()` method
on your data.

## Running once at startup

Put the expression right on the element. It runs a single time as Summit
initializes the element, before any children below it are set up.

```summit
<div s-data="{ ready: false, at: '' }"
     s-init="ready = true; at = new Date().toLocaleTimeString()">
  <p s-show="ready">Ready at <span s-text="at"></span>.</p>
</div>
```

Unlike [s-effect](../s-effect/), which re-runs whenever the state it reads
changes, `s-init` fires exactly once and never again. Reach for it when you want
a one-time action, not a reactive one.

## It works on any element

`s-init` is an ordinary directive, so it is not limited to a component root. You
can attach it to any element inside a component, and each one runs as that
element initializes.

```html
<ul s-data="{ items: [] }">
  <li s-init="items.push('first row')">Loading...</li>
</ul>
```

## Relationship to a component's init() method

A component defined with [s-data](../s-data/) can expose an `init()` method,
which Summit calls when the component is created (see
[Lifecycle](../lifecycle/)). The two are complementary:

- Use `init()` for setup that is substantial or belongs alongside the
  component's data, such as fetching, reading storage, or starting a timer.
- Use `s-init` for a short expression on a single element, including elements
  that do not own any data of their own.

When one element carries both an `s-data` `init()` method and an `s-init`
directive, the `init()` method runs first, then the `s-init` expression.

---

# s-ref

> Name an element so you can reach it through $refs.

`s-ref` gives an element a name so you can reach the real DOM node later through
the [$refs](../magic-refs/) magic. This is how you focus an input, measure a
box, or hand a node to another library, without reaching for
`document.querySelector`.

## Naming and reaching an element

The value of `s-ref` is the name. That name becomes a key on `$refs`, and its
value is the element itself.

```summit
<div s-data="{}">
  <input s-ref="field" placeholder="Your name" />
  <button @click="$refs.field.focus()">Focus the input</button>
</div>
```

Refs are registered on the nearest component root, so every element inside the
same [s-data](../s-data/) component shares one `$refs` registry. When the
element leaves the DOM, its ref is removed for you.

## Dynamic names

If the expression resolves to a non-empty string, Summit uses that string as the
name. Otherwise it falls back to the literal text you wrote. That means a plain
name like `s-ref="field"` just works, and you can also compute a name, which is
handy inside an [s-for](../s-for/) loop.

```html
<template s-for="item in items" :key="item.id">
  <li s-ref="'row-' + item.id" s-text="item.label"></li>
</template>
```

Here each row registers under `row-1`, `row-2`, and so on, reachable as
`$refs['row-' + id]`. One thing to watch: because the value is evaluated,
choosing a static name that also happens to be a string variable in scope will
use that variable's value as the name instead of the literal text.

## Reaching a ref after the DOM updates

If you reveal an element and then want to focus it in the same handler, wait for
the DOM to catch up first with [$nextTick](../magic-nextTick/).

```html
<button @click="open = true; $nextTick(() => $refs.panel.focus())">Open</button>
```

---

# s-cloak

> Hide markup until Summit has initialized it.

Before Summit runs, your markup is just plain HTML: an [s-text](../s-text/) span
is empty, an [s-show](../s-show/) element is fully visible, and bound attributes
are unset. For a brief moment the page can show that raw, un-hydrated state.
`s-cloak` hides an element until Summit has finished initializing it.

## The pattern

Add one CSS rule that hides anything carrying the attribute, then mark the
elements you want kept out of sight until they are ready.

```html
<style>
  [s-cloak] { display: none; }
</style>

<div s-data="{ user: 'Ada' }" s-cloak>
  Signed in as <span s-text="user"></span>
</div>
```

When Summit initializes the element it removes the `s-cloak` attribute. The rule
stops matching, and the element appears in its finished state with no flash of
raw template in between. Because the attribute is removed during setup, the rule
only ever affects markup that has not been processed yet.

The removal happens after the element's other directives have run, so by the
time it becomes visible its text, bindings, and classes are already in place.

## Where to put it

Put `s-cloak` on the outermost element whose contents you do not want to flash,
which is usually the same element that carries [s-data](../s-data/). You can
also place it on individual pieces, such as a list that fills in from a fetch.

The CSS rule is yours to add once, globally. Summit does not inject it for you,
and there is nothing else to configure: the attribute is simply removed the
first time the element initializes.

---

# s-ignore

> Skip Summit initialization for an element and its children.

`s-ignore` tells Summit to leave an element and everything inside it alone.
Summit does not read its directives, does not descend into its children, and
sets up no reactivity anywhere in that subtree.

## Skipping a subtree

When Summit reaches an element marked `s-ignore`, it stops there and moves on.
Any directives inside the ignored region are left untouched.

```summit
<div s-data="{ name: 'Ada' }">
  <p>Summit runs here: <span s-text="name"></span></p>
  <div s-ignore>
    <p>Summit skips here: <span s-text="name"></span></p>
  </div>
</div>
```

The first span shows `Ada`. The second sits inside an `s-ignore` block, so its
[s-text](../s-text/) never runs and the span stays empty. The skip covers the
whole subtree, not just the element itself.

## When to use it

- **Third-party widgets** that manage their own DOM, such as a map, a rich text
  editor, or a payment field. Wrapping the mount point in `s-ignore` keeps
  Summit from walking into markup it does not own and does not understand.
- **Server-rendered islands** and large static regions where you simply want to
  skip the initialization walk.

`s-ignore` is a hard stop for the entire subtree, not a per-directive opt-out.
If you need reactivity on part of that region, keep it outside the ignored
element. Where [s-cloak](../s-cloak/) hides markup until it is ready, `s-ignore`
never initializes it at all.

---

# s-teleport

> Render an element at a different place in the DOM.

`s-teleport` renders content somewhere else in the document while keeping it
wired to the component it was written in. It is what you use for modals,
popovers, and toasts that need to escape a parent's `overflow` or stacking
context.

## A template that renders elsewhere

`s-teleport` goes on a `<template>` element. Its value is a CSS selector,
resolved with `document.querySelector`. Summit clones the template's content,
inserts the clones at the target, and initializes them with the current
component's scope, so the moved markup can still read and write the component's
state.

```html
<div s-data="{ open: false }">
  <button @click="open = true">Open</button>

  <template s-teleport="body">
    <div s-show="open" class="modal">
      <p>I render at the end of body, but I still read the component.</p>
      <button @click="open = false">Close</button>
    </div>
  </template>
</div>
```

The modal markup is authored inside the component, yet it ends up appended to
`<body>`, clear of any `overflow: hidden` ancestor. Because Summit initializes
it with the component's scope, `open` still controls it with
[s-show](../s-show/) and the Close button still writes back.

## Choosing where it lands

By default the content is placed inside the target, as its last child. Two
modifiers place it relative to the target instead.

| Placement | Result |
| --- | --- |
| `s-teleport="sel"` | Appended inside the target, as its last child |
| `s-teleport.prepend="sel"` | Inserted just before the target element |
| `s-teleport.append="sel"` | Inserted just after the target element |

So `s-teleport="body"` puts the content at the end of the page body, while
`s-teleport.append="#anchor"` drops it in right after the element with id
`anchor`.

## Notes

- The directive only works on a `<template>` element. On anything else Summit
  logs a warning and does nothing.
- The selector must match an element that already exists when the template
  initializes. If the target is not found, Summit warns and renders nothing.
- Only the template's children are moved. The `<template>` element itself stays
  where you wrote it and shows nothing.
- When the component or the template is removed, Summit tears down and removes
  the teleported nodes too, so no detached DOM is left behind.

To animate the teleported content as it appears, pair it with
[s-transition](../s-transition/).

---

# s-transition

> Animate elements as they enter and leave.

`s-transition` animates an element as it becomes visible and as it hides. It
comes in two flavors: a class style, where you supply the CSS classes for each
phase, and a helper style, where a few modifiers produce a default fade and
scale with no CSS to write.

## How it pairs with s-show

Transitions run through [s-show](../s-show/). Put both directives on the same
element: `s-show` decides when the element is visible, and `s-transition`
animates the change. The very first render is applied instantly with no
animation. Every toggle after that plays the enter animation when the element
appears and the leave animation when it hides, and the element is only set to
`display: none` once the leave animation finishes.

Note that [s-if](../s-if/) does not run transitions. It adds and removes the node
directly, so to animate an element in and out, use `s-show` rather than `s-if`.

## Class style

Supply a class list for each phase after a colon. There are six phases, three for
entering and three for leaving:

- `s-transition:enter` stays applied for the whole enter animation.
- `s-transition:enter-start` is the starting look, applied before the first frame.
- `s-transition:enter-end` is the target look, applied on the next frame.
- `s-transition:leave`, `s-transition:leave-start`, and `s-transition:leave-end`
  mirror those three for leaving.

On enter, Summit adds the `enter` and `enter-start` classes, then on the next
frame removes `enter-start` and adds `enter-end`, so the element transitions from
the start look to the end look. When the animation is done it removes the `enter`
and `enter-end` classes. Leaving works the same way with the `leave` classes.

The animation's duration is read from the element's computed
`transition-duration`, so define your `transition` on the class that stays
applied through the phase, that is `enter` and `leave`. If no CSS transition
duration is found, Summit falls back to 150ms.

```html
<div s-data="{ open: false }">
  <button @click="open = !open">Toggle</button>

  <div
    s-show="open"
    s-transition:enter="fade"
    s-transition:enter-start="opacity-0 shift"
    s-transition:enter-end="opacity-100 rest"
    s-transition:leave="fade"
    s-transition:leave-start="opacity-100 rest"
    s-transition:leave-end="opacity-0 shift"
  >
    I fade and slide as I enter and leave.
  </div>
</div>
```

```css
/* Stays applied for the whole phase, so it sets the duration. */
.fade { transition: opacity 300ms ease, transform 300ms ease; }

/* The hidden look: start of enter, end of leave. */
.opacity-0 { opacity: 0; }
.shift     { transform: translateY(-8px); }

/* The visible look: end of enter, start of leave. */
.opacity-100 { opacity: 1; }
.rest        { transform: translateY(0); }
```

## Helper style

Use `s-transition` with no phase and let modifiers describe the animation with
inline styles instead of CSS classes:

- `.opacity` fades the element.
- `.scale` scales it. Follow it with a number to set the scale as a percent, for
  example `.scale.90` scales from 90%. On its own it uses 95%.
- `.duration` sets the time, for example `.duration.300ms` or `.duration.300`.
- `.delay` waits before starting, for example `.delay.100ms`.

A bare `s-transition` with no modifiers defaults to a fade combined with a scale
from 95%, over 150ms.

```summit
<div s-data="{ open: false }">
  <button @click="open = !open">Toggle</button>
  <p s-show="open" s-transition>Default fade and scale.</p>
  <p s-show="open" s-transition.duration.500ms.scale.90>Slower, with more scale.</p>
</div>
```

Because the helper style writes its own inline styles, it needs no accompanying
CSS to be visible.

---

# s-intersect

> Run an expression when an element enters or leaves the viewport.

`s-intersect` runs an expression the moment its element scrolls into view. It
wraps an `IntersectionObserver` so you can lazy-load, reveal on scroll, or fire
analytics without writing observer boilerplate.

```summit
<div s-data="{ seen: false }">
  <div s-intersect="seen = true" class="s-card" style="padding:1rem">
    <p s-text="seen ? 'This block is in view.' : 'Scroll me into view.'"></p>
  </div>
</div>
```

## Enter and leave

By default the expression runs when the element becomes visible. Add the `:leave`
part to run when it goes out of view instead. You can use both on one element.

```html
<div s-intersect="playing = true" s-intersect:leave="playing = false"></div>
```

## Modifiers

- `.once` stops observing after the first time it fires.
- `.half` waits until the element is at least half visible.
- `.full` waits until it is almost entirely visible.

```html
<img src="hero.jpg" s-intersect.once="loaded = true">
<section s-intersect.half="active = true"></section>
```

## s-resize

Its sibling `s-resize` runs an expression whenever the element changes size,
exposing the new box as `$width` and `$height`.

```html
<div s-resize="w = $width" s-text="Math.round(w) + 'px wide'"></div>
```

Both directives detach their observers automatically when the element is
removed, so there is nothing to clean up.

---

# s-trap

> Keep keyboard focus inside an element while it is open.

`s-trap` keeps keyboard focus inside an element for as long as an expression is
truthy. This is what makes a modal dialog or a menu usable from the keyboard:
`Tab` cycles within it, and when it closes, focus returns to whatever opened it.

```summit
<div s-data="{ open: false }">
  <button class="s-btn" @click="open = true">Open dialog</button>
  <div s-show="open" s-trap="open" class="s-card" style="padding:1rem; max-width:340px; display:grid; gap:0.6rem">
    <p>Focus is trapped here. Tab stays inside; Shift+Tab wraps back.</p>
    <input class="s-input" placeholder="First field">
    <input class="s-input" placeholder="Second field">
    <button class="s-btn" @click="open = false">Close</button>
  </div>
</div>
```

## What it does

When the expression flips true, `s-trap`:

- remembers the element that was focused,
- moves focus to the first focusable child,
- keeps `Tab` and `Shift+Tab` cycling within the element.

When it flips false, focus returns to the remembered element. Removing the
element also releases the trap, so there is nothing to tear down.

## Pair it with Escape and a backdrop

`s-trap` handles focus; you still wire up dismissal the usual way.

```html
<div s-show="open" s-trap="open" @keydown.escape="open = false">
  ...
</div>
```

The built-in [Dialog](../comp-dialog/) component already uses `s-trap`, so most
of the time you get this for free.

---

# s-anchor

> Position an element next to a reference, flipping to stay in view.

`s-anchor` positions a floating element next to a reference element and keeps it
on screen, flipping to the other side and shifting inward when it would overflow
the viewport. It is the positioning behind menus, popovers, and tooltips.

```summit
<div s-data="{ open: false }">
  <button class="s-btn" s-ref="trigger" @click="open = !open">Open menu</button>
  <div s-show="open" s-anchor="$refs.trigger" class="s-menu" style="min-width:170px">
    <button class="s-menu-item" @click="open = false">Profile</button>
    <button class="s-menu-item" @click="open = false">Settings</button>
    <button class="s-menu-item" @click="open = false">Sign out</button>
  </div>
</div>
```

The expression resolves to the reference element, usually through
[$refs](../magic-refs/).

## Placement

Modifiers choose the side and alignment. The default is `bottom` and `start`.

- Side: `.top` or `.bottom`
- Alignment: `.start`, `.center`, or `.end`
- Gap: `.offset.N` sets the distance in pixels (default 8)

```html
<div s-anchor.top.end="$refs.trigger">...</div>
<div s-anchor.bottom.center.offset.12="$refs.trigger">...</div>
```

## Staying in view

`s-anchor` re-positions on scroll and resize. If the preferred side would run off
the screen it flips to the opposite side, and it clamps horizontally so the
element never leaves the viewport. The [Menu](../comp-menu/) and
[Popover](../comp-popover/) components use it out of the box.

---

# s-collapse

> Animate an element open and closed by height.

`s-collapse` smoothly animates an element's height as an expression toggles. It
is a drop-in, animated alternative to [s-show](../s-show/) for accordions,
disclosure panels, and expanding menus.

```summit
<div s-data="{ open: false }">
  <button class="s-btn" @click="open = !open">Toggle details</button>
  <div s-collapse="open">
    <div style="padding:0.75rem 0">
      <p>This region slides open and closed instead of snapping.</p>
      <p>The height animates from 0 to its natural size.</p>
    </div>
  </div>
</div>
```

## How it differs from s-show

`s-show` flips `display` instantly. `s-collapse` keeps the element in flow and
animates its height, so the content around it eases into place. On first render
it sets the starting height with no animation, so there is no flash of motion on
load.

## Accessibility

Because the collapsed element stays in the DOM, pair it with the toggle's state
for assistive tech:

```html
<button @click="open = !open" :aria-expanded="open">Toggle</button>
<div s-collapse="open">...</div>
```

---

# s-mask

> Format an input as the user types against a pattern.

`s-mask` formats an input while you type it. Give it a pattern and Summit inserts
the fixed characters and rejects anything that does not fit, so phone numbers,
card numbers, and dates come out clean.

```summit
<div s-data>
  <label class="s-field">
    <span class="s-label">Phone</span>
    <input class="s-input" s-mask="'(999) 999-9999'" placeholder="(555) 123-4567">
  </label>
</div>
```

## Pattern tokens

The expression is a string of tokens:

- `9` accepts a digit
- `a` accepts a letter
- `*` accepts a letter or a digit

Every other character is a literal that the mask inserts for you as you reach it.

```html
<input s-mask="'9999-9999-9999-9999'">   <!-- card number -->
<input s-mask="'99/99'">                 <!-- expiry MM/YY -->
<input s-mask="'aaa-999'">               <!-- license plate -->
```

The pattern is an ordinary expression, so it can come from your state and change
at runtime:

```html
<input s-mask="pattern">
```

---

# $el

> The current DOM element.

`$el` is the DOM element the current expression runs on. It is the element that
carries the directive, not the component root, so inside `@click` it is the
element you clicked and inside `s-text` it is the element being filled.

```summit
<div s-data="{ count: 0 }">
  <button @click="count++; $el.textContent = 'Clicked ' + count + ' times'">
    Click me
  </button>
</div>
```

Each expression sees its own `$el`. In the demo above `$el` is the button, so
writing to `$el.textContent` changes only the button.

## Reading from the element

Because `$el` is a real element, the whole DOM API is available. This is useful
for reading a property straight off the node instead of mirroring it in state.

```summit
<div s-data="{ shown: '' }">
  <input @input="shown = $el.value.toUpperCase()" placeholder="Type here" />
  <p s-text="shown"></p>
</div>
```

## Reaching the component root

`$el` is always the nearest element, which is often deep inside a component. When
you want the element that owns the `s-data` instead, use
[$root](../magic-root/). To reach other named elements in the component, use
[$refs](../magic-refs/).

---

# $refs

> Elements in this component marked with s-ref.

`$refs` is an object of the elements in the current component that you tagged
with [s-ref](../s-ref/), keyed by their ref name. It is how you reach a specific
element to focus it, measure it, or call a method on it, without a query
selector.

```summit
<div s-data="{}">
  <input s-ref="field" placeholder="Your name" />
  <button @click="$refs.field.focus()">Focus the field</button>
</div>
```

Mark an element with `s-ref="name"` and it appears as `$refs.name`.

## Naming a ref

By default the literal attribute value is the name, so `s-ref="field"` registers
under `field`. When the value resolves to a non-empty string it is treated as a
dynamic name instead, which is what you want inside a loop where each element
needs its own key. The full rules are on the [s-ref](../s-ref/) page.

## Scope and lifetime

`$refs` collects the refs for the nearest component, the closest `s-data`
ancestor. A ref registered inside a child component is not visible from a parent,
and vice versa. When an element leaves the DOM its entry is removed, so `$refs`
only ever holds elements that are currently mounted.

Refs are populated as elements initialize, so read them from an event handler or
inside [$nextTick](../magic-nextTick/) rather than at the top of `init()`, when a
later sibling may not exist yet.

---

# $store

> The reactive global store.

`$store` is the reactive root that holds every store you register with
[Summit.store](../globals-store/). Reading a store value inside an expression
tracks it, and writing to one triggers an update, so a change made in one
component reaches every component that reads it.

Register a store by name, then reach it as `$store.<name>` from any expression.

```js
Summit.store("cart", {
  items: [],
  get count() {
    return this.items.length;
  },
  add(item) {
    this.items.push(item);
  },
});
```

```html
<div s-data>
  <button @click="$store.cart.add('apple')">Add to cart</button>
  <p>Cart has <span s-text="$store.cart.count"></span> items.</p>
</div>
```

## Single values

A store does not have to be an object. Single values are reactive too, so a
plain boolean works and its writes still update every reader.

```js
Summit.store("darkMode", false);
```

```html
<button @click="$store.darkMode = !$store.darkMode" :aria-pressed="$store.darkMode">
  Toggle theme
</button>
```

Because reads track and writes trigger, `$store.darkMode = !$store.darkMode` is
reactive with nothing extra to wire up.

## When to reach for it

Use `$store` for state that many, otherwise unrelated components need to share.
For state that belongs to one component and its children, keep it in `s-data`.
See [Summit.store](../globals-store/) for creating and reading stores from
JavaScript.

---

# $watch

> Run a callback when a watched expression changes.

`$watch` runs a callback whenever a watched expression changes. The signature is
`$watch(expression, callback)`, where `expression` is a string evaluated in the
component's scope and `callback` receives the new value and the old value.

```summit
<div s-data="{ count: 0, last: 'no changes yet' }"
     s-init="$watch('count', (value, old) => last = old + ' to ' + value)">
  <button @click="count++">Increment</button>
  <p>count is <span s-text="count"></span></p>
  <p>last change: <span s-text="last"></span></p>
</div>
```

Set the watcher up once, in [s-init](../s-init/) or in a component's `init()`
method. The callback then fires on every later change to the expression.

## It only fires on a real change

`$watch` compares values and only calls your callback when the value actually
changes. That means you can mutate the watched value from inside the callback
without spinning into an infinite loop, which is a common trap in other
frameworks.

## It returns an unwatch function

`$watch` returns a function that stops the watcher. Call it when you no longer
need the callback.

```summit
<div s-data="{ n: 0, log: 'watching', stop: null }"
     s-init="stop = $watch('n', (value, old) => log = old + ' to ' + value)">
  <button @click="n++">Increment</button>
  <button @click="stop && (stop(), log = 'stopped')">Stop watching</button>
  <p>n is <span s-text="n"></span></p>
  <p>log: <span s-text="log"></span></p>
</div>
```

After you stop the watcher the callback no longer runs, even as `n` keeps
changing. You rarely need to call this by hand, though: a watcher is torn down
automatically when its component leaves the DOM.

## Watching derived values

The first argument is any expression, not just a property name, so you can watch
a nested path or a computed result.

```js
this.$watch("user.name", (name) => console.log("name is now", name));
this.$watch("items.length", (n) => console.log(n, "items"));
```

For a side effect that should re-run without needing the old value, reach for
[s-effect](../s-effect/) instead.

---

# $dispatch

> Dispatch a custom DOM event.

`$dispatch` creates and dispatches a `CustomEvent` from the current element, so
components can talk to each other through the DOM. The signature is
`$dispatch(name, detail?, options?)`.

```summit
<div s-data="{ received: 'nothing yet' }" @notify="received = $event.detail">
  <button @click="$dispatch('notify', 'hello from the button')">Send</button>
  <p>parent received: <span s-text="received"></span></p>
</div>
```

The button dispatches `notify`, the event bubbles up to the surrounding
component, and its `@notify` handler reads the payload from `$event.detail`.

## The payload

Whatever you pass as the second argument becomes `event.detail`. Read it in a
listener as `$event.detail`.

```html
<button @click="$dispatch('add-to-cart', { id: 42, qty: 2 })">Add</button>
```

## Defaults and options

The event is created with `bubbles`, `composed`, and `cancelable` all set to
`true`, so it rises through ancestors, crosses shadow DOM boundaries, and can be
cancelled. Pass a third argument to override any of those.

```js
$dispatch("saved", payload, { bubbles: false });
```

`$dispatch` returns `false` when a listener calls `preventDefault()` on the
event, and `true` otherwise.

## Listening from elsewhere

Because the event bubbles, any ancestor can listen with `@event-name`. To catch
an event no matter where it was dispatched, listen on the window with the
`.window` modifier.

```html
<div @add-to-cart.window="count += $event.detail.qty"></div>
```

For the full listener reference, including modifiers, see the [s-on](../s-on/)
and [Events](../events/) pages.

---

# $nextTick

> Run code after the next DOM update.

When you change state, Summit updates the DOM on the next microtask, not
immediately. `$nextTick` lets you run code after that update has landed, so you
can read the freshly rendered DOM. It takes an optional callback and returns a
promise.

```summit
<div s-data="{ msg: 'start', immediate: '', deferred: '' }">
  <button @click="msg = 'updated';
                  immediate = $refs.out.textContent;
                  $nextTick(() => deferred = $refs.out.textContent)">
    Update
  </button>
  <p s-ref="out" s-text="msg"></p>
  <p>read immediately: <span s-text="immediate"></span></p>
  <p>read after nextTick: <span s-text="deferred"></span></p>
</div>
```

Reading the element right after changing `msg` still sees the old text, because
the DOM has not updated yet. Reading inside `$nextTick` sees the new text.

## Awaiting the update

`$nextTick` returns a promise, so in an `async` method you can await it instead
of passing a callback.

```js
async grow() {
  this.rows.push(newRow());
  await this.$nextTick();
  this.$refs.list.scrollTop = this.$refs.list.scrollHeight;
}
```

A common use is focusing an element that only just appeared, which is why you
will often see `$nextTick` paired with [$refs](../magic-refs/).

```html
<button @click="open = true; $nextTick(() => $refs.panel.focus())">Open</button>
```

---

# $root

> The root element of the nearest component.

`$root` is the root element of the nearest component, the closest ancestor (or
the element itself) that carries an `s-data`. Wherever you are in the markup,
`$root` points back at the element that owns the component.

```summit
<div s-data="{ count: 0 }" data-role="panel">
  <div>
    <button @click="count = $root.querySelectorAll('button').length">
      Count buttons under $root
    </button>
  </div>
  <p>$root is a <span s-text="$root.tagName"></span> element.</p>
  <p>buttons found: <span s-text="count"></span></p>
</div>
```

Even though the button is nested two levels deep, `$root` reaches past its
wrappers to the outer `s-data` element.

## $root versus $el

[$el](../magic-el/) is the element the current expression runs on, which changes
from one directive to the next. `$root` is fixed for the whole component: it is
the same element for every expression inside it. Use `$el` for the element at
hand and `$root` when you need the component's outer boundary, for example to
scope a query or read a data attribute set on the root.

If the expression is outside any component, `$root` is `null`.

---

# $id

> Generate stable, scoped unique ids.

`$id` generates a stable, unique id, which is exactly what you need to pair a
label with its input or to wire up `aria-` attributes without hand-writing ids
that might collide. The signature is `$id(name, key?)`.

```summit
<div s-data="{}" s-id="['email']">
  <label :for="$id('email')">Email</label>
  <input :id="$id('email')" type="email" />
</div>
```

Both calls to `$id('email')` return the same value, so the label's `for` matches
the input's `id`. The generated id is unique on the page, so you can render this
component many times and every copy stays correctly paired.

## Scoping ids with s-id

By default each `$id` call produces a fresh page-unique id, which means two
separate calls would not agree. The `s-id` directive fixes that: it opens an id
group on an element, and every `$id('name')` inside that subtree returns the same
id for that name.

```html
<div s-id="['email', 'password']">
  ...every $id('email') and $id('password') in here is stable...
</div>
```

Pass `s-id` an array of the names you want to scope. Groups nest: an inner
`s-id` shadows an outer one for the names it lists.

## Ids in a list

Inside an [s-for](../s-for/) loop, open a fresh group per row so each row gets
its own ids and none of them collide.

```html
<template s-for="user in users" :key="user.id">
  <div s-id="['row']">
    <label :for="$id('row')" s-text="user.name"></label>
    <input :id="$id('row')" :aria-describedby="$id('row') + '-hint'" />
  </div>
</template>
```

## The key argument

The optional second argument appends a key to the id, which is handy when one
group needs a distinct id per item without a wrapper element.

```html
<div s-id="['opt']">
  <template s-for="choice in choices" :key="choice">
    <label :for="$id('opt', choice)" s-text="choice"></label>
    <input type="radio" :id="$id('opt', choice)" name="choice" :value="choice" />
  </template>
</div>
```

Every `$id('opt', choice)` for a given `choice` returns the same id, so labels
and radios line up per option.

---

# $data

> The current component's reactive state object.

`$data` is the current component's reactive state object, the same object you
declared with `s-data`. Most of the time you read state by name, but when you
need the whole object at once, `$data` hands it to you. Reads and writes through
it stay reactive.

```summit
<div s-data="{ name: 'Ada', role: 'admin' }">
  <p s-text="JSON.stringify($data)"></p>
  <button @click="$data.name = 'Grace'">Rename</button>
</div>
```

Writing `$data.name` updates the same state as writing `name`, so the text above
re-renders. `$data` is just the state object itself, reached as a value.

## When to use it

Reach for `$data` when you want to work with the state as an object rather than
by individual names, for example to serialize it, iterate its keys, pass it to a
helper, or reset it in one assignment.

```html
<button @click="Object.keys($data).forEach(k => $data[k] = '')">Clear all</button>
```

## Which component

`$data` is the state of the nearest component. In
[nested components](../reactivity-state/) the inner `s-data` wins, so `$data`
inside a child gives the child's state, not the parent's. To reach shared state
across components, use [$store](../magic-store/) instead.

---

# $persist

> Reactive state backed by localStorage that survives reloads.

`$persist` makes a piece of state stick around. Wrap a default value with it in
your `s-data`, and Summit seeds the value from `localStorage`, then writes it
back on every change. Reload the page and the value is still there.

```summit
<div s-data="{ count: $persist(0) }">
  <button class="s-btn" @click="count++">Clicked <span s-text="count"></span> times</button>
  <p style="color:var(--muted)">Reload the page: the count stays.</p>
</div>
```

The storage key defaults to the property name, so `count` above is saved under
`"count"`.

## Choosing the key

When two components both persist a `count`, give them distinct keys with `.as()`
so they do not overwrite each other.

```html
<div s-data="{ count: $persist(0).as('cart-count') }"></div>
```

## What you can store

`$persist` serializes with `JSON`, so strings, numbers, booleans, arrays, and
plain objects all work. The value stays fully reactive after it is restored, so
everything that reads it updates as usual.

```html
<div s-data="{ prefs: $persist({ theme: 'dark', density: 'cozy' }) }"></div>
```

If storage is unavailable (private mode, disabled), `$persist` quietly falls
back to the default value so your component still runs.

---

# $focus

> Move keyboard focus around from an expression.

`$focus` is a small helper for moving keyboard focus. Use it to send focus to a
field after an action, or to step through the focusable elements inside a region.

```summit
<div s-data>
  <button class="s-btn" @click="$focus.within($refs.box).first()">Focus first field</button>
  <div s-ref="box" style="margin-top:0.6rem; display:flex; gap:0.5rem">
    <input class="s-input" placeholder="First">
    <input class="s-input" placeholder="Second">
  </div>
</div>
```

## Methods

- `$focus.focus(el)` focuses a specific element, e.g. `$focus.focus($refs.field)`.
- `$focus.first()` / `$focus.last()` focus the first or last focusable element.
- `$focus.next()` / `$focus.previous()` step through them, wrapping around.
- `$focus.within(el)` returns a helper rooted at `el` instead of the current one.

By default `$focus` looks inside the element it is used on. `within` lets you aim
it at any other element, which pairs well with [$refs](../magic-refs/).

```html
<input s-ref="email" @keydown.enter="$focus.focus($refs.password)">
```

For a full focus trap on a dialog or menu, reach for the [s-trap](../s-trap/)
directive, which builds on the same idea.

---

# Summit.data

> Register a reusable named component.

`Summit.data` registers a named component so you can reference it from any
`s-data` attribute instead of repeating an inline object. It is the tool for
anything beyond a one-off snippet: a counter, a dropdown, a form, a component
you use in ten places.

## Registering a component

Call `Summit.data(name, provider)`. The provider is a factory: a function that
returns the state object. Returning the object from a function (rather than
sharing one object) is what gives every use its own independent copy.

```js
Summit.data("counter", (start = 0) => ({
  count: start,
  increment() {
    this.count++;
  },
}));
```

```html
<div s-data="counter">
  <button @click="increment()">
    Count: <span s-text="count"></span>
  </button>
</div>
```

The returned object becomes reactive state exactly like an inline `s-data`
object: properties are tracked, getters become cached derived values, and
methods are bound so `this` is the component. See
[Reactivity and State](../reactivity-state/) for how that state behaves.

## Passing arguments

Reference the provider like a function call and Summit passes the arguments
through. The argument list is evaluated in the parent scope, so you can hand in
literals or values from an enclosing component.

```html
<div s-data="counter(10)">
  <span s-text="count"></span>
</div>
```

Bare names work too: `s-data="counter"` calls the provider with no arguments,
letting your parameter defaults (`start = 0` above) take over.

## A fresh copy every time

Because the provider is a function, each element that references it runs the
factory again and gets a separate state object. Two `s-data="counter"` blocks on
the same page keep independent counts.

## Lifecycle hooks

If the returned object has an `init()` method, Summit calls it once the
component's state is set up. A `destroy()` method runs when the element is
removed from the DOM. This works for named providers and inline objects alike.

```js
Summit.data("clock", () => ({
  now: "",
  timer: 0,
  init() {
    this.timer = setInterval(() => (this.now = new Date().toLocaleTimeString()), 1000);
  },
  destroy() {
    clearInterval(this.timer);
  },
}));
```

See [Lifecycle](../lifecycle/) for the full order of these hooks.

## Chaining and timing

`Summit.data` returns the `Summit` global, so registrations chain:

```js
Summit
  .data("counter", () => ({ count: 0 }))
  .data("clock", () => ({ now: "" }));
```

Registration is timing-safe. You can register a provider before or after
[Summit.start](../globals-start/), and any matching `s-data` in the page, now or
added later, resolves to it.

---

# Summit.store

> Create and read global reactive state.

State that many components share lives in a store, not in `s-data`. `Summit.store`
both creates a store and reads one back, depending on whether you pass a value.
Every store is reactive, so any expression that reads it updates when it changes.

## Creating a store

Call `Summit.store(name, value)` with a starting value. Pass an object for
structured state:

```js
Summit.store("cart", {
  items: [],
  get count() {
    return this.items.length;
  },
  add(item) {
    this.items.push(item);
  },
});
```

An object store is made reactive the same way a component is: getters become
cached derived values and methods are bound so `this` is the store. If the
object has an `init()` method, Summit calls it once, right after the store is
created.

Primitives work too, and stay reactive because every store lives under one
reactive root:

```js
Summit.store("darkMode", false);
```

## Reading a store

Call `Summit.store(name)` with no value to read the current one:

```js
const cart = Summit.store("cart");
cart.add({ id: 1 });
```

In markup, reach any store through the [$store](../magic-store/) magic. Reads
track, so the view stays in sync, and writes are reactive out of the box:

```html
<button @click="$store.darkMode = !$store.darkMode">
  Toggle theme
</button>

<p s-text="$store.cart.count"></p>
```

## Return values

The call returns something useful in every form:

- `Summit.store("cart", { ... })` returns the reactive store object.
- `Summit.store("darkMode", false)` returns the stored value.
- `Summit.store("cart")` returns the store's current value.

## Updating a store

Mutate an object store through its own methods or properties, from JavaScript or
from an expression, and every reader updates:

```js
Summit.store("cart").add({ id: 2 });
```

For a primitive store, assign through `$store` in an expression
(`$store.darkMode = true`), or call `Summit.store(name, value)` again from
JavaScript to replace the value. To create the store, see the object and
primitive examples above.

---

# Summit.bind

> Register a reusable set of bindings.

`Summit.bind` registers a named bundle of attributes, event handlers, and
dynamic bindings so you can apply the whole set at once instead of repeating the
same `:class`, `@click`, and `aria-*` attributes on every element that needs
them. It is the reusable form of an object passed to
[s-bind](../s-bind/).

## Registering a bundle

Call `Summit.bind(name, provider)`. The provider is a function that takes no
arguments and returns an object of bindings:

```js
Summit.bind("menuButton", () => ({
  type: "button",
  "aria-haspopup": "true",
  "@click"() {
    Summit.store("menu").open = !Summit.store("menu").open;
  },
  ":aria-expanded"() {
    return Summit.store("menu").open;
  },
}));
```

`Summit.bind` returns the `Summit` global, so it chains with your other
registrations.

## What a bind provider returns

The object uses the same shape [s-bind](../s-bind/) accepts, and each kind of key
is handled differently:

- A plain key sets an attribute. Boolean attributes such as `disabled` are added
  or removed based on truthiness; a value of `false` or `null` removes the
  attribute.
- An `@event` key adds an event listener. Its value is the handler, called with
  the event. The listener is removed automatically when the element is torn down.
- A `:attr` key is a dynamic binding. Its value is a getter function that Summit
  runs inside a reactive effect, so the attribute re-applies whenever the
  reactive state the getter reads changes. Read that state from a store or other
  reactive source, since a bind provider has no component scope of its own.

## Applying a bundle

Retrieve a registered provider with `Summit.getBind(name)`, which returns the
provider function (or `undefined` if none is registered). Calling it produces the
bindings object, which you hand to [s-bind](../s-bind/). Add `Summit` to the
expression globals once so markup can reach it:

```js
Summit.addGlobals(["Summit"]);
```

```html
<button s-bind="Summit.getBind('menuButton')()"></button>
```

Because `s-bind` merges these bindings onto the element, you can still add
element-specific attributes and directives alongside the shared bundle.

---

# Summit.directive

> Register a custom directive.

`Summit.directive` adds a new `s-` attribute to Summit. Your directive runs when
Summit initializes an element that carries it, with the same utilities the
built-in directives use, so a directive you write is a first-class citizen.

## Registering a directive

Call `Summit.directive(name, handler, priority?)`. The name is used without the
`s-` prefix. This registers `s-tooltip`:

```js
Summit.directive("tooltip", (el, meta, utils) => {
  utils.effect(() => {
    el.setAttribute("title", String(utils.evaluate(meta.expression)));
  });
});
```

```html
<button s-tooltip="'Copied ' + count + ' times'">Copy</button>
```

`Summit.directive` returns the `Summit` global, so registrations chain.

## The handler signature

The handler receives three arguments: `(el, meta, utils)`.

`el` is the element the directive is on.

`meta` describes how the attribute was written:

- `name`, the directive name without `s-` (here, `"tooltip"`).
- `value`, the part after a colon, or `null` if absent (`"click"` in `s-on:click`).
- `modifiers`, the dot-separated modifiers as an array (`["prevent", "stop"]`).
- `expression`, the attribute's value string, ready to pass to `evaluate`.
- `raw`, the original attribute name as written in the DOM.

`utils` is the directive author's toolkit:

- `evaluate(expression)` runs a value expression in the element's scope.
- `evaluateAction(expression, locals?)` runs statements (like an `s-on` handler),
  optionally with extra local variables.
- `effect(fn)` creates a reactive effect that re-runs when its dependencies
  change and is torn down automatically with the element.
- `cleanup(fn)` registers a teardown callback.
- `initTree(el, scopes?)` and `destroyTree(el)` initialize or tear down a subtree,
  used by structural directives that manage their own children.
- `scopes` is the scope stack visible at this element.
- `makeEnv(el, locals?)` builds a fresh evaluation environment for an element.
- `Summit` is the global itself.

Use `effect` for anything that should react to state, and `cleanup` for anything
that must be undone (a listener, a timer). Errors thrown in a handler are caught
and logged, so one broken directive will not stop the rest of the page.

## Priority

The optional third argument sets ordering. When an element has several
directives, lower numbers run earlier. The default is `100`, so pass a smaller
number to run before most directives and a larger one to run after:

```js
Summit.directive("setup", handler, 0); // runs early, before default directives
```

## Timing

Registration is timing-safe: register before or after
[Summit.start](../globals-start/). Built-in directives are registered when
Summit loads, and registering a custom directive with the same name overrides
the built-in.

For a fuller walkthrough, see
[Writing directives and plugins](../advanced-extending/).

---

# Summit.magic

> Register a custom magic property.

`Summit.magic` adds a `$`-prefixed helper that every expression can reach, the
same way the built-ins [$el](../magic-el/), [$refs](../magic-refs/), and
[$store](../magic-store/) work. Use it to expose a value or a small function to
your markup without threading it through component state.

## Registering a magic

Call `Summit.magic(name, factory)`. The name is used with a `$` prefix in
expressions. The factory receives a context object and returns whatever `$name`
should be:

```js
Summit.magic("clipboard", () => (text) => navigator.clipboard.writeText(text));
```

```html
<button @click="$clipboard(label)">Copy</button>
```

Return a function and `$name(...)` calls it. Return a value and `$name` is that
value:

```js
Summit.magic("now", () => new Date());
```

`Summit.magic` returns the `Summit` global, so registrations chain.

## The magic context

The factory is called with a context object for the element where the magic is
used:

- `el` is the element the expression is running on.
- `scopes` is the scope stack visible at that element.
- `evaluate(expression)` evaluates an expression in that scope.
- `effect(fn)` creates a reactive effect torn down with the element.
- `cleanup(fn)` registers a teardown callback.

Because the factory runs per use, a magic can be element-aware. This one reads
the current element's id:

```js
Summit.magic("myId", (ctx) => ctx.el.id);
```

Use `effect` and `cleanup` when your magic sets up something reactive or
disposable, so it is cleaned up when the element goes away.

## Timing

Registration is timing-safe: register before or after
[Summit.start](../globals-start/). Registering a magic with the name of a
built-in overrides it. For a broader guide, see
[Writing directives and plugins](../advanced-extending/).

---

# Summit.plugin

> Install a plugin that registers features in bulk.

`Summit.plugin` installs a plugin: a function that registers a set of related
features in one call. It is how you package data providers, directives, magics,
stores, and binds together and share them across projects.

## Installing a plugin

Call `Summit.plugin(fn)`. Summit calls your function immediately with the
`Summit` global, so the plugin registers everything it needs through the same
API you would use by hand:

```js
function tooltips(Summit) {
  Summit.directive("tooltip", (el, meta, utils) => {
    utils.effect(() => {
      el.setAttribute("title", String(utils.evaluate(meta.expression)));
    });
  });

  Summit.magic("hint", () => (text) => text.trim());
}

Summit.plugin(tooltips);
```

A plugin is just a function, so it can register as many features as it likes:

```js
Summit.plugin((Summit) => {
  Summit
    .data("counter", () => ({ count: 0 }))
    .store("darkMode", false)
    .magic("uppercase", () => (s) => String(s).toUpperCase());
});
```

## Chaining

`Summit.plugin` returns the `Summit` global, so you can install several plugins
and keep registering:

```js
Summit
  .plugin(tooltips)
  .plugin(forms)
  .start();
```

Everything a plugin registers is timing-safe, so it does not matter whether you
install plugins before or after [Summit.start](../globals-start/). See
[Writing directives and plugins](../advanced-extending/) for the pieces a plugin
is built from.

---

# Summit.start

> Start Summit and initialize the DOM.

`Summit.start` scans the DOM, brings every `s-` attribute to life, and begins
watching for elements added later. The script-tag build calls it for you. The
npm build leaves the timing to you, so you can register your data, directives,
and magics first.

## Starting

Call `Summit.start()` to initialize the whole document, or pass a root element to
initialize just that subtree:

```js
Summit.start();
```

```js
Summit.start(document.getElementById("app"));
```

When no root is given, Summit starts from `document.body`. After the initial
pass it keeps a watcher on the document, so any `s-` markup you add later comes
alive on its own and torn-down elements are cleaned up.

## It runs once

`Summit.start` is idempotent. The first call initializes the DOM; later calls
return immediately and do nothing. That makes it safe to call after registering
features without worrying about double-initialization:

```js
Summit.directive("sparkle", (el) => {
  el.style.transition = "opacity .3s";
});
Summit.start();
```

The script-tag build already calls `start()` once the DOM is ready, so calling
it again yourself is harmless.

## Lifecycle events

`start` dispatches two events on `document`, so you can hook into
initialization:

- `summit:init` fires just before Summit walks the DOM.
- `summit:initialized` fires after the initial pass completes.

```js
document.addEventListener("summit:initialized", () => {
  console.log("Summit is running");
});
```

## Checking status and version

`Summit.started()` returns `true` once `start` has run, and `false` before:

```js
if (!Summit.started()) Summit.start();
```

`Summit.version` is the version string of the running build:

```js
console.log(Summit.version); // "0.1.0"
```

For install options and manual-start setup, see
[Installation](../installation/).

---

# signal()

> A single reactive value you read by calling it and update with set().

A signal is the smallest unit of reactive state in Summit: one value that keeps
track of every effect that read it. Computed values, effects, and the deep
`reactive()` proxy are all built on the same tracking core, so once you
understand signals the rest of the system follows.

## Creating a signal

`signal(initial)` returns a signal that holds `initial`.

```js
import { signal } from "summitjs";

const count = signal(0);
```

The signal is a function, not an object with a `.value` property. You read it by
calling it, and you write it with `.set()`.

## Reading

Call the signal to get its current value. When you read a signal inside an
[effect()](../reactive-effect/) or [computed()](../reactive-computed/), that
reader subscribes to the signal and re-runs whenever the value changes.

```js
count(); // 0
```

## Writing

`.set(next)` replaces the value. Pass the next value directly, or a function
that receives the previous value and returns the next one.

```js
count.set(1);
count.set((prev) => prev + 1); // now 2
```

A write only wakes subscribers when the value actually changes, compared with
`Object.is`. Setting a signal to the value it already holds does nothing.

## Peeking without subscribing

`.peek()` returns the current value without subscribing the active effect. Reach
for it when you need the value but do not want a later change to trigger a
re-run.

```js
count.peek(); // 2, and the surrounding effect will not depend on count
```

## Checking for a signal

`isSignal(x)` returns `true` for any value produced by `signal()`, and `false`
otherwise.

```js
import { signal, isSignal } from "summitjs";

isSignal(count); // true
isSignal(() => 0); // false
```

`signal` is also available on the global as `Summit.signal`. `isSignal` ships as
a named export of `summitjs`.

## How signals underpin the framework

Every reactive `s-` directive ultimately reads and writes signals. The state you
declare with `s-data` lives in a [reactive()](../reactive-reactive/) proxy, and
both signals and that proxy feed the one dependency-tracking engine described in
[How reactivity works](../advanced-reactivity/). For the HTML-first way to hold
and update state, see [Reactivity and State](../reactivity-state/). To derive a
cached value from a signal, reach for [computed()](../reactive-computed/); to run
a side effect when it changes, use [effect()](../reactive-effect/).

---

# computed()

> A cached value derived from other reactive state.

A computed value is derived from other reactive state and cached. It runs its
getter once, remembers the result, and only recomputes when one of the values it
read has changed. That makes it cheaper than a plain function you call
repeatedly, which would redo the work on every call.

## Creating a computed

Pass `computed` a getter function. It returns a computed you read the same way as
a [signal](../reactive-signal/), by calling it.

```js
import { signal, computed } from "summitjs";

const price = signal(10);
const qty = signal(2);
const total = computed(() => price() * qty());

total(); // 20
```

Like a signal, a computed is a function, not an object with a `.value`. Read it
by calling it.

## Caching and laziness

A computed is lazy: the getter does not run until something reads the computed
for the first time. After that, the cached result is returned on every read until
a dependency changes.

```js
const doubled = computed(() => {
  console.log("recomputing");
  return price() * 2;
});

doubled(); // logs "recomputing", returns 20
doubled(); // returns 20, no log: served from cache

price.set(15);
doubled(); // logs "recomputing", returns 30
```

Reading a computed twice in a row does the work once. Only a change to a
dependency such as `price` invalidates the cache.

## Composition

Because a computed both reads dependencies and is itself readable, computeds
chain. Reading one computed inside another subscribes to it, and reading a
computed inside an [effect()](../reactive-effect/) re-runs the effect when the
computed's result changes.

```js
const withTax = computed(() => total() * 1.2);

withTax(); // computes total once, then applies tax
```

## Peeking

`.peek()` returns the current result, recomputing first if it is stale, without
subscribing the active effect.

```js
total.peek(); // current total, without creating a dependency
```

## Where computeds show up

The getters you define in `s-data` are cached the same way a computed is, which
is why a derived value like a full name recomputes only when its parts change.
See [Derived values](../reactivity-state/) for the HTML-first form, and
[How reactivity works](../advanced-reactivity/) for the tracking model
underneath. `computed` is also available on the global as `Summit.computed`.

---

# effect()

> Run a function reactively whenever its dependencies change.

An effect runs a function and re-runs it whenever any reactive value it read
during its last run changes. This is the heart of Summit: every reactive
directive is a kind of effect. Tracking is fine-grained, so a change wakes only
the effects that actually read the value that changed.

## Running an effect

`effect(fn)` runs `fn` once immediately, recording which signals, computeds, and
reactive properties it reads. When any of those change, `fn` runs again.

```js
import { signal, effect } from "summitjs";

const name = signal("Ada");

effect(() => {
  console.log("Hello,", name());
});
// logs "Hello, Ada" right away

name.set("Grace");
// logs "Hello, Grace"
```

Dependencies are recomputed on every run, so an effect that reads different
values on different runs subscribes to exactly what it read the last time.

## Stopping an effect

`effect()` returns a runner. Pass it to `stop()` to dispose the effect
permanently: it unsubscribes from every dependency and never runs again.

```js
import { signal, effect, stop } from "summitjs";

const count = signal(0);
const runner = effect(() => console.log(count()));

count.set(1); // logs 1
stop(runner);
count.set(2); // nothing logs
```

You can also call the returned runner yourself to force a re-run.

## Reading without subscribing

Wrap a read in `untrack()` to use a value without depending on it. The effect
still runs, but a later change to an untracked value will not trigger it.

```js
import { signal, effect, untrack } from "summitjs";

const a = signal(1);
const b = signal(10);

effect(() => {
  // Re-runs when a changes, but not when b changes.
  console.log(a() + untrack(() => b()));
});
```

## Writing a value the effect also reads

An effect that writes a signal it also reads will not trigger itself into a loop.
The system skips re-running the effect that is currently executing, so this is
safe.

```js
const n = signal(0);
effect(() => {
  if (n() < 3) n.set(n() + 1); // does not recurse infinitely
});
```

## Timing

By default an effect re-runs synchronously, the moment a dependency changes. The
DOM-facing effects behind directives instead batch onto the microtask queue so a
burst of writes produces a single update, which is why you await
[nextTick()](../reactive-nexttick/) to read the updated DOM. To coalesce several
synchronous writes into one effect run yourself, use
[batch()](../reactive-batch/).

`effect` is also available on the global as `Summit.effect`; `stop` and
`untrack` ship as named exports of `summitjs`. For the full tracking model, see
[How reactivity works](../advanced-reactivity/).

---

# reactive()

> A deeply reactive object or array.

`reactive(obj)` wraps a plain object or array in a deep proxy that tracks reads
and triggers on writes. It is what backs a component's `s-data` scope, so a plain
assignment like `state.open = true` updates everything that read `open`. Where a
[signal](../reactive-signal/) holds one value, `reactive` gives you an ordinary
object you can read and mutate by property.

## Creating reactive state

```js
import { reactive, effect } from "summitjs";

const state = reactive({ count: 0, user: { name: "Ada" } });

effect(() => console.log(state.count)); // logs 0
state.count++; // logs 1
```

Reading a property subscribes the active effect to that property; writing it
wakes the effects that read it. Adding or deleting a property also notifies code
that iterates the object, for example an `s-for`.

## Deep and lazy

Nested objects and arrays are reactive too. They are wrapped the first time you
access them, not all at once up front.

```js
effect(() => console.log(state.user.name)); // logs "Ada"
state.user.name = "Grace"; // logs "Grace"
```

## What gets wrapped

Only plain objects and arrays become reactive. Class instances, including DOM
nodes, `Date`, `Map`, and `RegExp`, pass through untouched, so you can safely
store a DOM element or other host object in reactive data without breaking it.

```js
const s = reactive({
  el: document.querySelector("#app"), // stored as-is, not proxied
  items: [1, 2, 3], // proxied
});
```

`reactive` is idempotent: wrapping the same object twice returns the same proxy,
and wrapping an existing proxy returns it unchanged.

## Unwrapping and detecting

`toRaw(value)` returns the original plain object behind a proxy. It is safe to
call on a value that was never reactive, in which case it returns the value
as-is.

```js
import { reactive, toRaw, isReactive } from "summitjs";

const raw = { count: 0 };
const state = reactive(raw);

toRaw(state) === raw; // true
isReactive(state); // true
isReactive(raw); // false
```

## How it fits

`reactive` and [signal()](../reactive-signal/) share one dependency-tracking
core, so an [effect()](../reactive-effect/) or [computed()](../reactive-computed/)
can depend on a mix of both. This proxy is exactly what gives `s-data` its
ergonomics; see [Reactivity and State](../reactivity-state/) for the HTML side
and [How reactivity works](../advanced-reactivity/) for the internals.
`reactive` is also available on the global as `Summit.reactive`; `toRaw` and
`isReactive` ship as named exports of `summitjs`.

---

# batch()

> Group writes so effects run once.

Without batching, each write to a [signal](../reactive-signal/) or reactive
property triggers its dependent effects right away. When you make several related
writes, that can run the same effect more than once. `batch()` defers those
triggers until the whole function has run, then flushes each affected effect a
single time.

## Grouping writes

```js
import { signal, effect, batch } from "summitjs";

const first = signal("Ada");
const last = signal("Lovelace");

effect(() => console.log(first(), last())); // logs "Ada Lovelace"

batch(() => {
  first.set("Grace");
  last.set("Hopper");
});
// effect runs once, logging "Grace Hopper"
```

Outside a batch, the two writes would run the effect twice. Inside one, the
effect is queued once and runs after the batch closes. Duplicate triggers of the
same effect are collapsed.

## Return value

`batch()` returns whatever its function returns, so you can compute and commit in
one step.

```js
const label = batch(() => {
  first.set("Alan");
  last.set("Turing");
  return `${first()} ${last()}`;
});
```

## Nesting

Batches nest. Only the outermost batch flushes effects, so wrapping
already-batched code adds no extra runs.

```js
batch(() => {
  first.set("Ada");
  batch(() => {
    last.set("Lovelace");
  });
  // nothing has flushed yet
});
// effects flush once here
```

## Batch versus the scheduler

`batch()` coalesces synchronous writes within one function. It is different from
the microtask scheduling that DOM-facing directives use, where updates are
already deferred to the next tick. When you need to read the DOM after updates
apply, await [nextTick()](../reactive-nexttick/) instead.

`batch` is also available on the global as `Summit.batch`. For the trigger and
flush mechanism underneath, see [How reactivity works](../advanced-reactivity/).

---

# nextTick()

> Wait for pending reactive updates to flush.

Reactive DOM updates do not happen synchronously on every write. Directives queue
their work and flush once on the next microtask, so a burst of state changes
produces a single coalesced update. `nextTick()` resolves after that flush, which
is how you read the DOM once it reflects your latest changes.

## Awaiting updates

Call `nextTick()` with no argument to get a promise that resolves after the
pending flush.

```js
import { signal, nextTick } from "summitjs";

const count = signal(0);

count.set(1);
await nextTick();
// pending effects have run and the DOM reflects count === 1
```

## With a callback

Pass a function and `nextTick()` runs it after the flush, then resolves.

```js
nextTick(() => {
  // runs after pending updates have applied
  console.log("flushed");
});
```

Either form returns a `Promise<void>`, so you can `await` it or chain `.then()`.

## The $nextTick magic

Inside markup, the same capability is available as the
[$nextTick](../magic-nextTick/) magic. It is this function bound into the
expression scope, so you can wait for the DOM from an `s-` attribute:

```html
<button @click="count++; $nextTick(() => console.log('updated'))">+1</button>
```

Use `nextTick` from JavaScript and `$nextTick` from an expression.

## How the flush works

The batched, DOM-facing effects that directives are built on schedule themselves
onto this same microtask queue, so awaiting `nextTick` after a state change is the
reliable way to observe the resulting DOM. To collapse several synchronous writes
into one effect run before the flush, see [batch()](../reactive-batch/). For the
queue and effect machinery underneath, see
[How reactivity works](../advanced-reactivity/). `nextTick` is also available on
the global as `Summit.nextTick`.

---

# How reactivity works

> How Summit tracks dependencies and updates the DOM.

Everything reactive in Summit rests on one small engine. A handful of primitives,
a few hundred lines, decide what re-runs when a value changes. This page walks
that engine end to end so you can reason about updates, write your own effects,
and understand exactly why a directive fires when it does.

If you just want to use signals, computeds, and effects, the
[Reactivity](../reactive-signal/) reference pages cover the public API. This page
is about the machinery underneath them.

## The signal, the atom of state

A signal holds one value. Reading it subscribes whoever is currently watching.
Writing it wakes those watchers, but only if the value actually changed.

```js
const count = Summit.signal(0);

count();        // read: returns 0 and subscribes the active effect
count.set(1);   // write: notifies subscribers
count.peek();   // read the value WITHOUT subscribing
```

Internally each signal owns a `dep`, a set of the effects that read it. A read
calls `track(dep)`, which adds the active effect to that set. A write compares
the new value to the old one with `Object.is` and, only if they differ, calls
`trigger(dep)` to wake every effect in the set. Setting a signal to its current
value does nothing, so no downstream work happens for a no-op write. `.peek()`
skips `track`, so you can read a value without becoming dependent on it.

## Effects and dependency tracking

An effect is a function that re-runs whenever any value it read last time
changes. It is the other half of the signal: signals are read inside effects,
and effects are what signals wake.

```js
const name = Summit.signal("Ada");
Summit.effect(() => {
  console.log("name is", name());
});
name.set("Grace"); // logs "name is Grace"
```

The link is built by running the function. Before an effect runs, Summit sets it
as the current active effect. Any signal read during that run calls `track`,
which records the dependency in both directions: the effect is added to the
signal's dep set, and the dep is pushed onto the effect's own `deps` list.

Dependencies are re-collected on every run. The first thing an effect does when
it re-runs is `cleanupDeps`, which unsubscribes it from every dep it currently
holds. It then runs the function and re-subscribes only to what it reads this
time. That is why tracking is fine-grained and dynamic: if an effect takes a
different branch and stops reading a value, it stops depending on it. Nothing
you no longer read can wake you.

Because a dep is one set per value, a change wakes only the effects that read
that exact value. When you click a button that increments `count`, the only
effects that re-run are the ones that read `count`. Every other text node,
attribute, and list on the page is untouched.

## The active-effect stack

Only one effect can be "active" at a time, but effects nest: an effect can run
code that creates or runs another effect. Summit tracks this with a stack. When
an effect starts it is pushed on and becomes active; when it finishes it is
popped and the previous effect on the stack becomes active again. Reads always
attribute to the effect at the top of the stack, so a nested effect captures its
own dependencies without stealing the outer effect's.

The stack also powers the self-write guard. An effect that both reads and writes
the same value could otherwise trigger itself forever. Two checks prevent that.
First, if an effect is already on the stack when it is asked to run again, the
re-entrant call returns immediately. Second, `trigger` never re-runs the effect
that is currently active. So an effect can safely write a value it also reads
without spinning into an infinite loop.

## Computed values are cached

A computed is a derived value that memoizes its result. Unlike a plain getter,
which recomputes on every read, a computed recomputes only when one of its own
dependencies changes, and it stays lazy: the getter does not run until something
reads the computed.

```js
const first = Summit.signal("Ada");
const last = Summit.signal("Lovelace");
const full = Summit.computed(() => first() + " " + last());

full(); // runs the getter once, caches "Ada Lovelace"
full(); // returns the cached value, no recompute
last.set("Byron"); // marks full stale, but does not recompute yet
full(); // now recomputes and caches "Ada Byron"
```

A computed is built on a lazy effect plus a `dirty` flag. Reading the computed
runs the getter only when `dirty` is set, stores the result, and clears the
flag. When a dependency changes, the computed's scheduler marks it dirty again
and notifies the computed's own subscribers so they re-read on demand. This is
why a computed is both a consumer (it subscribes to whatever its getter reads)
and a producer (it has its own dep that effects can subscribe to). The getters
you write in `s-data` are backed by this, so reading a derived value twice in one
render does the work at most once.

## Batching writes

Sometimes you change several values at once and want dependent effects to run a
single time at the end, not once per write. That is what `batch` does.

```js
Summit.batch(() => {
  first.set("Grace");
  last.set("Hopper");
}); // effects that read first or last run once, after both writes
```

While a batch is open, triggered effects are collected into a pending set
instead of running. When the outermost batch closes, that set is flushed once.
Batches nest, and only the outermost flush runs anything, so helper functions
that each open a batch compose cleanly.

## The scheduler and the DOM

Batching groups writes you make yourself. The scheduler solves a different
problem: keeping DOM updates cheap regardless of how the writes arrive.

Plain effects run synchronously the moment a dependency changes. DOM-facing
effects do not. They are created with a scheduler, so instead of re-running
inline they queue themselves onto a microtask. The queue is a set, so an effect
that is triggered many times in one tick is only queued once, and the whole
queue flushes together on the next microtask. A burst of state changes therefore
produces a single coalesced DOM update, even without an explicit `batch`.

`nextTick` sits on top of this queue. It resolves after the current flush, which
is how you read the freshly updated DOM.

```js
count.set(count.peek() + 1);
await Summit.nextTick();
// the DOM reflecting the new count has now been painted
```

The primitive that ties effects to this scheduler is `domEffect`. It creates a
lazy effect whose scheduler enqueues it, runs it once immediately to establish
its dependencies and paint the first result, and returns a disposer. Run once
now, re-run on a microtask forever after, until stopped.

## How directives sit on top

Every reactive directive is a `domEffect`. When a directive calls
`utils.effect(fn)`, Summit wraps `fn` in a `domEffect` and registers its disposer
as element cleanup. That single mechanism explains the whole system:

- `s-text` runs an effect that sets `textContent` from an expression. The effect
  reads whatever the expression reads, so it re-runs when any of those values
  change, and updates only that one text node.
- `s-show`, `:bind`, and `s-model` are the same shape: an effect that reads state
  and writes one piece of the DOM.
- `s-if` and `s-for` run effects that read a condition or a list and add or
  remove nodes in response.

The component scope itself, the object you pass to `s-data`, is wrapped in a
reactive proxy. Reading `count` inside a directive expression goes through that
proxy, which calls `track` for the `count` property, subscribing the directive's
effect to exactly that property. Writing `count` calls `trigger` for that
property, waking exactly the directives that read it. When the element is
removed, Summit runs its cleanups, which stop those effects and unsubscribe them
from every dep.

## Reactive objects

The bridge between the low-level signal API and the object ergonomics of
`s-data` is `reactive`. It wraps a plain object or array in a proxy that tracks
property reads and triggers on writes, so `this.open = true` inside a method just
works.

```js
const state = Summit.reactive({ open: false, items: [] });
Summit.effect(() => console.log("open?", state.open));
state.open = true; // logs "open? true"
```

Reactivity is deep and lazy: nested plain objects and arrays are wrapped the
first time you access them. Only plain objects and arrays are wrapped, though.
Class instances, DOM nodes, `Date`, `Map`, `RegExp`, and other host objects are
returned untouched, so storing a DOM element in reactive data never breaks it.
The proxy is cached per object and idempotent, so wrapping the same object twice
returns the same proxy, and `toRaw` unwraps it again when you need the plain
value.

## Where to go next

- [signal](../reactive-signal/) and [computed](../reactive-computed/) for the
  value primitives.
- [effect](../reactive-effect/) for the tracking primitive, and
  [reactive](../reactive-reactive/) for deep reactive objects.
- [batch](../reactive-batch/) and [nextTick](../reactive-nexttick/) for
  controlling when work runs.

---

# The CSP-safe evaluator

> How Summit evaluates expressions without eval, safe under CSP.

Every Summit directive contains a JavaScript expression: `s-text="count"`,
`@click="open = !open"`, `:class="{ active: selected }"`. Most HTML-first
frameworks turn those strings into functions with `new Function` or `eval`. That
requires `unsafe-eval` in your Content-Security-Policy, which is exactly the
thing a strict policy is meant to forbid.

Summit takes a different path. It ships its own small JavaScript engine and never
calls `eval` or `new Function`, so it runs under a strict CSP with the standard
build and nothing to configure.

## Why no eval

A Content-Security-Policy that omits `unsafe-eval` blocks `eval`, `new Function`,
and the string forms of `setTimeout`/`setInterval` at runtime, in the browser.
Any framework that compiles expressions with those APIs simply stops working
under such a policy unless you either loosen the policy or ship a separate,
restricted build.

Because Summit interprets expressions itself, there is nothing for the policy to
block. The same script tag works whether or not your site sets a strict CSP, and
you never maintain two builds.

## The pipeline

An expression string travels through three stages before it produces a value.

1. **Lexer.** `tokenize` scans the string into a flat list of tokens: numbers,
   strings, template literals, identifiers, and a fixed set of operators and
   punctuators.
2. **Parser.** `parse` reads those tokens into an abstract syntax tree, a
   structured description of the expression. The set of node shapes the parser
   can produce is the whole language: anything it cannot build is a parse error.
3. **Interpreter.** `Interpreter.run` walks the tree and computes a value,
   resolving names against your component's scope. It is a plain tree walk, no
   code generation of any kind.

Parsed trees are cached by their source and mode, so an expression that a
directive re-evaluates on every state change is parsed once and interpreted many
times.

There are two parse modes, and the caller chooses based on what it wants:

- **Expression mode** parses a single value expression, used by value directives
  like `s-data`, `s-text`, `:bind`, and `s-show`. Here a leading `{` is an object
  literal.
- **Program mode** parses a list of statements, used by action directives like
  `s-on` handlers and `s-init`. Here a leading `{` is a block.

That split is how Summit resolves the classic ambiguity of `{ }` without
guessing. The directive already knows whether it wants a value or an action.

## What syntax is supported

The parser and interpreter implement a broad, practical subset of JavaScript
expression syntax. All of the following work inside directives:

- **Literals:** numbers (including floats, exponents, and hex like `0xff`),
  single- and double-quoted strings with escapes, template literals with
  `${...}` interpolation, `true`, `false`, `null`, `undefined`, and `this`.
- **Objects and arrays,** including shorthand properties, computed keys, method
  shorthand, getters and setters, array holes, and spread (`{ ...a }`,
  `[ ...xs ]`).
- **Member access** with `.` and `[ ]`, and optional chaining `?.` for property
  reads, computed reads, and calls.
- **Function calls** with spread arguments and optional calls (`fn?.()`).
- **Operators:** `! - +`, `typeof`, `void`, prefix and postfix `++`/`--`,
  arithmetic `+ - * / % **`, comparison `< > <= >=`, equality `== != === !==`,
  `in`, `instanceof`, logical `&& || ??`, the ternary `?:`, and assignment in all
  its forms (`= += -= *= /= %= **= &&= ||= ??=`).
- **Arrow functions,** with expression or block bodies, default parameters,
  destructuring parameters, and rest parameters.
- **The `new` operator,** for constructing allowlisted built-ins and your own
  functions: `new Date(0)`, `new Map()`, `new Set([1, 2])`, `new RegExp('\\d')`.
  Only names your scope or the global allowlist expose are reachable, so it stays
  CSP-safe.
- **Regex literals,** with flags: `/\d+/.test(v)`, `s.split(/,\s*/)`,
  `s.replace(/@/g, ' at ')`. A `/` after a value is still division.

In program mode (action directives) you additionally get statements: `if`/`else`,
`return`, `let`/`const`/`var` with destructuring, `for`, `for...of`, `while`,
`break`, `continue`, and blocks. This is why `@click` handlers can hold real
multi-statement logic.

```html
<button @click="
  let next = count + 1;
  if (next > max) next = 0;
  count = next
">step</button>
```

## What is not supported

The subset stops where an expression language should. If you write any of these
in a directive, you get a parse error, which Summit catches and logs to the
console rather than executing:

- Bitwise operators (`& | ^ ~ << >> >>>`).
- The `function` keyword and function declarations. Use arrow functions.
- Classes, `try`/`catch`, `throw`, `switch`, `do...while`, `async`/`await`, and
  generators.
- Comments and tagged template literals.

Keeping the surface bounded is not only about safety. It also keeps directive
expressions readable. Anything more involved belongs in a `Summit.data` method,
where you write ordinary JavaScript that your bundler and CSP already trust.

## How names resolve

When the interpreter meets an identifier, it looks in three places, in order:

1. **Interpreter-local bindings:** arrow-function parameters and any `let`/`const`
   declared in the same expression.
2. **The component scope:** the merged `s-data` stack, innermost first, so an
   inner component shadows an outer one, plus the `$`-prefixed magics.
3. **The global allowlist:** a fixed set of safe globals (below). Names in the
   allowlist resolve to the real global; anything else resolves to `undefined`.

Reads are deliberately tolerant. Accessing a property of `null` or `undefined`
yields `undefined` instead of throwing, and calling a method that does not exist
is a no-op that returns `undefined`. This keeps templates resilient to
half-loaded data. Assigning to a property of `null` or calling a value that is
present but not a function still throws, because those are real mistakes.

Arrow functions capture `this` lexically from the surrounding component, while
methods and getters defined in an object literal receive the usual dynamic
`this`, matching how the same code behaves in a normal engine.

## The global allowlist

An expression can only name a global if it is on the allowlist. The default set
covers the common, safe surface:

```text
Math, JSON, Date, Object, Array, Number, String, Boolean,
parseInt, parseFloat, isNaN, isFinite, RegExp,
Map, Set, WeakMap, WeakSet, Promise, Intl, console,
window, document, location, navigator, history,
localStorage, sessionStorage,
setTimeout, clearTimeout, setInterval, clearInterval,
requestAnimationFrame, cancelAnimationFrame,
fetch, alert, confirm, prompt, structuredClone,
URL, URLSearchParams, encodeURIComponent, decodeURIComponent,
NaN, Infinity
```

To let expressions reach a global you provide, add it:

```js
Summit.addGlobals(["gsap", "dayjs"]);
```

Now `dayjs()` resolves inside any directive. The allowlist is a scoping and
ergonomics boundary: it controls which names an expression may mention, and it
keeps a typo from silently reaching an unrelated global. It is not a full
sandbox, because allowlisted globals expose their whole surface. The point that
matters for CSP is narrower and firmer: Summit itself never needs `unsafe-eval`.

## Under a strict CSP

Because the evaluator uses no dynamic code, Summit is happy with a policy that
forbids it entirely:

```text
Content-Security-Policy: default-src 'self'; script-src 'self'
```

Load Summit as a normal script under that header and every directive works.
There is no `unsafe-eval`, no `unsafe-inline` required for the framework, and no
alternate build to swap in. The browser is still the ultimate enforcer: even the
allowlisted `window` cannot be used to smuggle in `window.eval(...)`, because the
browser blocks eval at runtime regardless of who calls it. Summit's contribution
is that it never asks you to open that door in the first place.

## See also

- [Reactivity](../advanced-reactivity/) for how the values these expressions read
  are tracked.
- [Extending Summit](../advanced-extending/) to reach the evaluator from your own
  directives with `utils.evaluate` and `utils.evaluateAction`.

---

# Writing directives and plugins

> Build custom directives, magics, and plugins.

Summit's built-in directives and magics are not privileged. They are registered
through the same public API you use for your own, and they receive the same
utilities. So a directive you write is a first-class citizen: it can evaluate
expressions in the element's scope, create reactive effects, and clean up after
itself, exactly like `s-text` does.

This page shows how to build a custom directive, a custom magic, and how to
bundle both into a reusable plugin.

## A custom directive

Register a directive with [Summit.directive](../globals-directive/). You pass a
name without the `s-` prefix and a handler function. The name becomes the
attribute: registering `"money"` gives you `s-money`.

```js
Summit.directive("money", (el, meta, utils) => {
  utils.effect(() => {
    const amount = Number(utils.evaluate(meta.expression)) || 0;
    el.textContent = amount.toLocaleString(undefined, {
      style: "currency",
      currency: "USD",
    });
  });
});
```

```html
<span s-money="price"></span>
```

That is the whole thing, and it is reactive. `utils.effect` runs the callback
once and re-runs it whenever any value the callback read changes. Because the
callback reads `price` through `utils.evaluate`, the text updates the moment
`price` changes, and only that text node updates.

### The handler arguments

Your handler is called with three arguments.

`el` is the element the directive is on.

`meta` describes the parsed attribute:

- `meta.name` is the directive name (`"money"`).
- `meta.value` is the part after a colon, or `null`. For `s-interval:500` it is
  `"500"`.
- `meta.modifiers` is the dot-separated list. For `@click.prevent.once` it is
  `["prevent", "once"]`.
- `meta.expression` is the attribute's value, the expression string.
- `meta.raw` is the original attribute name as written.

`utils` is the directive author's toolkit:

- `utils.evaluate(expression)` evaluates a value expression in this element's
  scope and returns the result.
- `utils.evaluateAction(expression, locals?)` evaluates one or more statements,
  optionally with extra local names (this is how `s-on` injects `$event`).
- `utils.effect(fn)` creates a batched reactive effect that is torn down
  automatically when the element is removed.
- `utils.cleanup(fn)` registers a teardown callback.
- `utils.scopes` is the scope stack visible at this element, and `utils.initTree`
  / `utils.destroyTree` let a directive set up or tear down a subtree it manages.
- `utils.Summit` is the Summit global, and `utils.makeEnv` builds a fresh
  evaluation environment for another element.

### Reading modifiers and cleaning up

A directive that is not purely reactive uses `meta.value`, `evaluateAction`, and
`cleanup`. Here is one that runs an action on an interval and tears the timer
down with the element:

```js
Summit.directive("interval", (el, meta, utils) => {
  const ms = Number(meta.value) || 1000;
  const id = setInterval(() => utils.evaluateAction(meta.expression), ms);
  utils.cleanup(() => clearInterval(id));
});
```

```html
<div s-data="{ seconds: 0 }" s-interval:1000="seconds++">
  <span s-text="seconds"></span>
</div>
```

Anything you register with `utils.cleanup` runs when the element leaves the DOM.
Effects created with `utils.effect` are cleaned up for you, so you only need
`cleanup` for listeners, timers, and observers you create yourself.

### Priority

A third argument sets the directive's priority. Lower numbers run earlier on the
same element, and the default is `100`.

```js
Summit.directive("focus", handler, 5); // runs before most directives
```

For reference, the built-ins run in this order: `s-ref` (10), `s-id` (15), the
structural `s-if`/`s-for`/`s-teleport` (20), `s-bind` (50), `s-model` (60),
`s-on` (70), `s-text`/`s-html` (80), `s-transition` (85), `s-show` (90),
`s-effect` (100), `s-init` (200), and `s-cloak` (1000). The structural directives
are a fixed internal group that take over their own subtree; a custom directive
runs in priority order after the scope and any structural directive are set up,
and Summit still descends into the element's children afterward.

## A custom magic

A magic is a `$`-prefixed helper available in every expression. Register one with
[Summit.magic](../globals-magic/). The factory receives a context object and
returns either a value or a function.

```js
Summit.magic("copy", () => (text) => navigator.clipboard.writeText(text));
```

```html
<button @click="$copy(title)">Copy title</button>
```

The factory's context gives you the element and scope plus the same evaluation
and lifecycle helpers directives get:

```js
Summit.magic("logged", (ctx) => {
  // ctx.el, ctx.scopes, ctx.evaluate, ctx.effect, ctx.cleanup
  return (label) => console.log(label, ctx.el);
});
```

Return a plain value for a property-style magic, or a function for a callable
one. Magics are also exposed on the component scope, so inside a `Summit.data`
method you can reach them as `this.$copy`, `this.$refs`, and so on.

## Bundling a plugin

A plugin is just a function that receives the Summit global. Use
[Summit.plugin](../globals-plugin/) to run it. Everything a plugin registers,
directives, magics, data providers, stores, and extra globals, lives together in
one installable unit.

```js
function commercePlugin(Summit) {
  Summit.addGlobals(["Intl"]);

  Summit.directive("money", (el, meta, utils) => {
    utils.effect(() => {
      const amount = Number(utils.evaluate(meta.expression)) || 0;
      el.textContent = amount.toLocaleString(undefined, {
        style: "currency",
        currency: "USD",
      });
    });
  });

  Summit.magic("copy", () => (text) => navigator.clipboard.writeText(text));

  Summit.data("cart", () => ({
    items: [],
    get total() {
      return this.items.reduce((sum, i) => sum + i.price, 0);
    },
  }));
}

Summit.plugin(commercePlugin);
```

`Summit.plugin` calls your function immediately with the global and returns the
global, so registration methods chain:

```js
Summit.plugin(commercePlugin).plugin(analyticsPlugin).start();
```

### When to register

Register your directives, magics, and plugins before Summit starts, so they are
in place when the page is first initialized. With the CDN build, which starts on
its own once the DOM is ready, put your registrations in a script that runs
before that, or register them inside a `summit:init` listener:

```js
document.addEventListener("summit:init", () => {
  Summit.plugin(commercePlugin);
});
```

Registration itself is timing-safe: the order of your registrations does not
matter, and registering a name that already exists overrides the previous
handler, which is how you can replace a built-in directive with your own.

## See also

- [Summit.directive](../globals-directive/), [Summit.magic](../globals-magic/),
  and [Summit.plugin](../globals-plugin/) for the reference details.
- [How reactivity works](../advanced-reactivity/) for what `utils.effect` does
  under the hood.
- [The CSP-safe evaluator](../advanced-evaluator/) for what `utils.evaluate`
  accepts.

---

# Migrating from Alpine

> A guide for developers coming from Alpine.js.

If you know Alpine, you already know Summit. The mental model is the same: state
declared on an element, expressions in attributes, `@` for events and `:` for
bindings. Most of a migration is a find-and-replace of the directive prefix.
This page covers that rename and then the handful of places where Summit behaves
differently on purpose.

## The prefix rename

Alpine's directives start with `x-`. Summit's start with `s-`. The two
shorthands are identical: `@click` is still `@click`, and `:class` is still
`:class`, because those are just short forms of `s-on:` and `s-bind:`.

```html
<!-- Alpine -->
<div x-data="{ open: false }">
  <button @click="open = !open">Toggle</button>
  <p x-show="open">Hello</p>
</div>

<!-- Summit -->
<div s-data="{ open: false }">
  <button @click="open = !open">Toggle</button>
  <p s-show="open">Hello</p>
</div>
```

## Directive mapping

Every Alpine directive has a same-named Summit counterpart. Rename the prefix and
you are done.

| Alpine        | Summit        | Notes                                          |
| ------------- | ------------- | ---------------------------------------------- |
| `x-data`      | `s-data`      | Same object-or-provider form.                  |
| `x-bind` / `:`| `s-bind` / `:`| Shorthand unchanged.                           |
| `x-on` / `@`  | `s-on` / `@`  | Shorthand unchanged.                           |
| `x-text`      | `s-text`      |                                                |
| `x-html`      | `s-html`      |                                                |
| `x-model`     | `s-model`     | Extra modifiers, see below.                    |
| `x-show`      | `s-show`      |                                                |
| `x-if`        | `s-if`        | Works on any element, not just `<template>`.   |
| `x-for`       | `s-for`       | Keyed reconciliation, see below.               |
| `x-effect`    | `s-effect`    |                                                |
| `x-init`      | `s-init`      |                                                |
| `x-ref`       | `s-ref`       |                                                |
| `x-cloak`     | `s-cloak`     |                                                |
| `x-ignore`    | `s-ignore`    |                                                |
| `x-teleport`  | `s-teleport`  |                                                |
| `x-transition`| `s-transition`|                                                |
| `x-id`        | `s-id`        | Pairs with the `$id` magic.                    |

The magics keep their names too: `$el`, `$refs`, `$store`, `$watch`, `$dispatch`,
`$nextTick`, `$root`, and `$id` all work as you expect. Summit adds one,
[$data](../magic-data/), which returns the nearest scope object.

The global API maps one for one as well: `Alpine.data`, `Alpine.store`,
`Alpine.bind`, `Alpine.directive`, `Alpine.magic`, `Alpine.plugin`, and
`Alpine.start` become [Summit.data](../globals-data/),
[Summit.store](../globals-store/), [Summit.bind](../globals-bind/),
[Summit.directive](../globals-directive/), [Summit.magic](../globals-magic/),
[Summit.plugin](../globals-plugin/), and [Summit.start](../globals-start/).

## What is genuinely different

The rename gets you a working page. These differences are where Summit is worth
understanding, because they change what you can rely on.

### Fine-grained signals

Alpine re-runs an element's effects when the data it touched changes. Summit runs
on a signal engine that tracks reads at the level of individual values. When you
update one property, the only expressions that re-run are the ones that actually
read that property, and each updates just its own text node or attribute. There
is no subtree to re-evaluate.

One practical upshot is getters. A getter you define in `s-data` is a cached
computed: it recomputes only when one of its own dependencies changes, and
reading it several times in one render does the work once. The same getter in
Alpine re-runs on every read. See [How reactivity works](../advanced-reactivity/)
for the full picture.

### CSP-safe with the standard build

Alpine's default build compiles expressions with `new Function`, so a strict
Content-Security-Policy needs Alpine's separate CSP build (which restricts what
expressions may do). Summit interprets expressions with its own engine and never
calls `eval` or `new Function`, so a policy like `script-src 'self'` works with
the one and only build, and directive expressions still support a broad slice of
JavaScript. The details, including the exact supported syntax and the global
allowlist, are in [The CSP-safe evaluator](../advanced-evaluator/).

### $watch returns an unwatch function and will not loop

In Summit, `$watch` returns a function that stops the watcher, and the callback
fires only on an actual change (compared with `Object.is`), skipping the initial
value. That means mutating the watched value inside its own callback cannot spin
into an infinite loop, and you can tear a watcher down when you no longer need
it.

```html
<div s-data="{ query: '', stop: null }"
     s-init="stop = $watch('query', (value) => console.log('now', value))">
  <input s-model="query" />
  <button @click="stop && stop()">Stop watching</button>
</div>
```

### Keyed s-for reconciliation

Give `s-for` a `:key` and Summit reconciles the list by key. Matching rows are
reused and moved rather than destroyed and recreated, so focus, scroll position,
input values, and any per-row state survive reordering and insertion. This is the
area where Alpine struggles most on large or reordering lists.

```html
<template s-for="item in items" :key="item.id">
  <li s-text="item.label"></li>
</template>
```

### s-if works on any element

Alpine's `x-if` must wrap a `<template>`. Summit's `s-if` works directly on any
element. Summit drops a comment anchor where the element was and uses the element
itself, minus its `s-if` attribute, as the blueprint it clones in and out.

```summit
<div s-data="{ open: false }">
  <button @click="open = !open" s-text="open ? 'Hide' : 'Show'">Show</button>
  <p s-if="open">No template element required.</p>
</div>
```

You can still use a `<template>` if you prefer, and you should when the content
is more than a single root element.

### The s-model modifier set

`s-model` handles text, number, range, checkbox (boolean or array), radio, and
single or multiple selects, with these modifiers: `.lazy`, `.change`, `.blur`,
`.number`, `.boolean`, `.debounce`, `.throttle`, and `.fill`. A few are worth
calling out for Alpine users:

- `.fill` seeds the model from the control's own initial value when the model is
  empty, so server-rendered form values become the starting state.
- `.boolean` coerces the input to a real boolean.
- `.debounce` and `.throttle` accept a duration, for example `s-model.debounce.500ms`.

The bound value is also exposed on the element as `el._summitModel = { get, set }`,
which makes it straightforward to build custom input components that participate
in `s-model`.

## A note on load order

Alpine is sensitive to when you register directives and plugins relative to
`alpine:init`. Summit's registries are timing-safe: registration order does not
matter and a later registration overrides an earlier one of the same name.
Summit dispatches `summit:init` on `document` just before it initializes the page
and `summit:initialized` when it is done, so register your plugins before start,
or inside a `summit:init` listener. See
[Extending Summit](../advanced-extending/) for the full pattern.

---

# Data Fetching

> summitjs/net, a tiny reactive data layer whose resources expose loading, error, and data as signals that drive the DOM.

Fetching data with raw `fetch` in a directive works for the simplest case, but
real screens need loading and error states, cancellation, and protection from
races. `summitjs/net` is an optional layer (about 2KB gzip, shipped separately
so the core stays small) that provides exactly that. It is the essential part of
a client like axios, but reactive: a **resource** exposes `data`, `error`,
`loading`, and `status` as signals, so the DOM updates itself.

## Install

With a bundler, register the plugin:

```js
import Summit from "summitjs";
import { net } from "summitjs/net";
Summit.plugin(net); // adds the $fetch magic and the s-resource directive
Summit.start();
```

Or drop in a second script after the core, no build step:

```html
<script src="https://velofy.github.io/summitjs/summit.min.js" defer></script>
<script src="https://velofy.github.io/summitjs/summit-net.min.js" defer></script>
```

## The resource pattern

Create a resource with `$fetch.resource(url, options)` and read its signals in
the markup. `immediate: true` fetches on creation.

```html
<div s-data="{ users: $fetch.resource('/api/users', { immediate: true }) }">
  <p s-show="users.loading">Loading…</p>
  <p s-show="users.error" s-text="users.error.message"></p>
  <ul>
    <template s-for="u in users.data || []" :key="u.id">
      <li s-text="u.name"></li>
    </template>
  </ul>
</div>
```

A resource carries:

| Member | Meaning |
| --- | --- |
| `data` | The parsed response body, or `undefined` before the first success. |
| `error` | A `NetError` (`status`, `body`, `message`), or `undefined`. |
| `loading` | `true` while a request is in flight. |
| `status` | `"idle"`, `"loading"`, `"success"`, or `"error"`. |
| `refetch(overrides?)` | Run the request again. Never rejects; failures land in `error`. |
| `mutate(next, options?)` | Set `data` optimistically, with optional rollback. |
| `abort()` | Cancel the in-flight request. |

## Search-as-you-type, races handled for you

Bind the request options to state with `s-resource`. When a value the config
reads changes, the resource refetches, and **latest-wins** cancellation means a
slow earlier response can never overwrite a newer one.

```html
<div s-data="{ q: '' }"
     s-resource:results="{ url: '/api/search', params: { q }, debounce: 200 }">
  <input s-model="q" placeholder="Search…">
  <template s-for="row in results.data || []" :key="row.id">
    <div s-text="row.title"></div>
  </template>
</div>
```

## Imperative requests

`$fetch` is also a client for one-off calls. Bodies are JSON-encoded, responses
are JSON-parsed, and a non-2xx status **throws** a `NetError` instead of quietly
resolving with the error body.

```html
<form s-data="{ title: '' }"
      @submit.prevent="$fetch.post('/api/todos', { title }).then(() => title = '')">
  <input s-model.trim="title">
  <button type="submit">Add</button>
</form>
```

## Optimistic updates

`mutate` sets `data` immediately and, when given a `request`, rolls back if it
fails.

```html
<div s-resource:todo="{ url: '/api/todos/1', immediate: true }">
  <button @click="todo.mutate(
    (t) => ({ ...t, done: !t.done }),
    { request: () => $fetch.post('/api/todos/1/toggle'), rollbackOnError: true }
  )">Toggle</button>
</div>
```

## A configured client

For a base URL, auth headers, or cross-cutting error handling, register
`createNet`. Headers can be a function so a token is read fresh per request.

```js
import { createNet } from "summitjs/net";

Summit.plugin(createNet({
  baseURL: "/api",
  headers: () => ({ authorization: "Bearer " + localStorage.token }),
  onError(e) { if (e.status === 401) location.href = "/login"; },
}));
```

The same client is available without Summit for plain scripts and tests:

```js
import { createClient } from "summitjs/net";

const api = createClient({ baseURL: "/api" });
const todo = await api.post("/todos", { title: "Ship it" });
```

## What it handles

- **Non-2xx throws.** Native `fetch` resolves on 404 and 500; here they become a
  `NetError`, so an error body never lands in `data`.
- **Latest wins.** Out-of-order responses are discarded by a per-resource
  sequence, so the freshest request always wins.
- **Abort on unmount.** A resource created in a component aborts its in-flight
  request when the element is removed.
- **No unhandled rejections.** `refetch` never rejects; failures surface through
  `error`.

## What it deliberately omits

It is not a full HTTP library. There are no adapters, no Node transport, no
upload/download progress, and no interceptor chains, just one `beforeRequest`,
one `afterResponse`, and one `onError` hook. Cancellation uses `AbortController`.
For anything heavier, use your own client and keep Summit for the view.