@antadesign/anta 0.3.34 → 0.3.35

package/docs/components/title.md

@@ -1,27 +1,42 @@
 # Title
 
-A margin-free heading with six `level`s. `level` sets the type scale and the
-`aria-level` exposed to assistive technology. `priority` runs from `primary`
-through `quaternary` (`--text-1` through `--text-4`); `tone` accepts `neutral`
-(the default), a named tone, or a literal CSS color.
+Use Title for page, section, and component headings. Choose a heading level,
+then adjust its emphasis with `priority` and `tone`.
 
-Use a raw `<h1>`–`<h6>` for document-outline or SEO semantics. Anta's reset
-gives those headings the same type scale and document margins. Use `<Title>` in
-component layouts when you need tone, priority, or parent-controlled spacing.
-
-> **`<Title>` has no margins.** Space it with the parent’s `gap` or padding. For
-> a one-off, add `marginBlock` to the title itself.
+Title has no margins. Use the parent's `gap` or padding to space it within a
+layout. For native HTML heading elements, use `<h1>`–`<h6>` with Anta's reset.
 
 ## Levels
 
-The parent supplies the `16px` gap between these titles.
+Choose `level` to match the heading hierarchy. It sets the type scale and the
+heading level announced by screen readers. This example uses a parent `gap`
+to space the titles.
+
+## Typeface
+
+Use `serif` for page and section titles, `sans-serif` for cards, panels, and
+metrics, and `monospace` for identifiers such as run IDs and file paths.
+
+Omit `font` to use the theme's choice. The Antithesis theme uses serif for
+levels 1–3 and sans serif for levels 4–6. Other themes use sans serif throughout.
+Changing `font` preserves the heading's size and line height.
+
+```tsx
+<Title level={2}>Recent runs</Title>
+<Title level={2} font="sans-serif">Run 4821: 12 failures</Title>
+<Title level={2} font="monospace">checkout-service/run_4821</Title>
+```
+
+Each typeface covers all six levels.
+
+```tsx
+<Title level={1} font="serif">Serif 1</Title>
+<Title level={1} font="sans-serif">Sans serif 1</Title>
+<Title level={1} font="monospace">Monospace 1</Title>
+```
 
-  Level 1: Workspace settings
-  Level 2: Recent activity
-  Level 3: Security alerts
-  Level 4: Sign-in policy
-  Level 5: Session timeout
-  Level 6: Updated five minutes ago
+A string `header` on a [Card](./card.md) renders a sans-serif title at every card
+size.
 
 ## Inline content
 
@@ -63,14 +78,15 @@ Use a number for multi-line titles.
 | 1     | 28px      | 32px        |
 | 2     | 24px      | 28px        |
 | 3     | 20px      | 24px        |
-| 4     | 17px      | 20px        |
+| 4     | 17px      | 22px        |
 | 5     | 15px      | 20px        |
 | 6     | 13px      | 16px        |
 
 ## Tone × priority
 
-The four priorities are shown across every named tone at `level={3}`. Omit
-`tone` for the neutral scale. The grid scrolls horizontally on narrow screens.
+Use `priority` to choose emphasis, from `primary` through `quaternary`.
+Use `tone` for a named color or a custom CSS color. Omit it for neutral text.
+The examples compare every named tone at `level={3}`.
 
 
     Neutral primary
@@ -106,25 +122,25 @@ The four priorities are shown across every named tone at `level={3}`. Omit
 
 ## Accessibility
 
-`<Title>` renders an `<a-title>` tag with `role="heading"` and
-`aria-level={level}`. It is not a real `<h*>`. Use a raw heading when the HTML
-document outline or SEO needs heading elements; the reset applies the same type
-scale.
+Title exposes `role="heading"` and an `aria-level` matching `level`. Choose
+levels that follow the page's heading hierarchy. When your integration requires
+native HTML headings, use `<h1>`–`<h6>` with Anta's reset for the same type scale
+and document margins.
 
 ## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `level?` | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 2 | Heading level, 1-6. Drives font-size, line-height, and vertical rhythm. Also surfaced to assistive tech via `aria-level` (h1 is typically reserved for the page title). |
+| `font?` | 'serif' \| 'sans-serif' \| 'monospace' | — | Typeface. Serif names the page and its parts; sans serif names objects on the page, such as cards, panels, and metrics; monospace names technical identifiers, such as run IDs, hashes, and file paths. Omit it to let the theme choose by level: the Antithesis theme sets levels 1–3 in serif and 4–6 in sans serif, and other themes use sans serif throughout. |
+| `level?` | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 2 | Heading level, 1–6. Sets the type scale and the `aria-level` exposed to assistive technology (h1 is typically reserved for the page title). |
 | `priority?` | 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary' | primary | Visual priority. Maps to text-1..text-4 (`primary` = text-1). |
 | `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Color tint. `neutral` (the default) is the untinted `--text-{N}` scale; a named tone applies the matching `--text-{N}-{tone}` palette. Any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) is a one-off custom tone — its hue is kept while lightness/chroma are pinned per priority in oklch. |
 | `truncate?` | boolean \| number | — | Truncate with a trailing ellipsis. `true` (or `1`) clamps to a single line; any integer ≥ 2 clamps to that many lines; `0` or a negative value means no truncation. A clipped JSX `Title` shows its text content in a tooltip by default. Nest a `<Tooltip>` to provide your own tooltip instead. |
 
 ## Web Component
 
-Use the web component directly when you are not using React or Preact and a native control does not fit.
-
-Set the heading role and level when writing `<a-title>` directly.
+Use `<a-title>` directly outside JSX. Set both `role="heading"` and
+`aria-level` to describe its place in the heading hierarchy.
 
 ```html
 <a-title level="2" tone="brand" role="heading" aria-level="2">
@@ -134,17 +150,15 @@ Set the heading role and level when writing `<a-title>` directly.
 
 ## Styling
 
-`priority` selects a neutral text level. Named `tone`s use the matching global
-text tokens. A literal `tone` is stored in `--title-tone-source` and resolved
-into the four priority levels.
+Start with `priority` and `tone` for emphasis and color:
 
 ```tsx
 <Title priority="secondary">Supporting heading</Title>
 <Title tone="#0d9488">Custom-tone heading</Title>
 ```
 
-`<a-title>` is light DOM, so local type treatment is ordinary CSS. The class is
-only for this example.
+Target `a-title` with ordinary CSS to adjust its typography. The
+`.release-heading` class scopes this example. Replace it with your own selector.
 
 ```css
 a-title.release-heading {

package/docs/components/toaster.md

@@ -1,20 +1,158 @@
 # Toaster
 
-A viewport-anchored region that shows toasts — short, self-dismissing notices
-stacked in a corner. It isn't a fixed "toast card": you toast **anything** — a
-`Banner`, a `Card`, a `Sticker`, a string, a bespoke node — and the region handles
-placement, stacking, and the auto-dismiss timer.
-
-Two pieces work together. **`<Toaster>`** is the region; you mount one and keep it
-mounted (a portal is fine). **`Toaster.manager`** is the store you drive from
-anywhere: `Toaster.manager.add(render)` adds a toast, where `render` is a function
-returning the content. The store holds no DOM — the mounted `<Toaster>` subscribes
-to it and renders each toast through React/Preact, so there's nowhere for a toast
-to go if no `<Toaster>` is mounted.
-
-Configure one toast and fire it — the playground shows the render function plus the
-options object you pass to `add`. Edit the `Banner` in the code (or the props panel)
-and the `{ placement, duration }` it's toasted with.
+Show temporary notices in one of six viewport placements. Toast a `Banner`,
+`Card`, string, JSX, or an existing DOM node. Toaster handles placement, stacking,
+and dismissal timing.
+
+Mount `Toaster` once in your application, then call `Toaster.manager.add()`
+when an action needs feedback.
+
+```tsx title="ToasterDemo.tsx"
+import { useState } from 'preact/hooks'
+import { Toaster, Button, Input, Banner, Card } from '@antadesign/anta'
+import { StickerClap } from '@antadesign/stickers'
+import styles from './ToasterDemo.module.css'
+
+export default function ToasterDemo() {
+  const [duration, setDuration] = useState('4000')
+
+  // Empty / zero / non-numeric → the 5000ms default (0 is not sticky; sticky is Infinity).
+  const opts = () => ({ placement: 'bottom-right' as const, duration: Number(duration) || 5000 })
+
+  return (
+    <div className={styles.demo}>
+      {/* The region — kept mounted for the store to render into. */}
+      <Toaster />
+
+      <div className={styles.controls}>
+        <Input
+          leading="Duration"
+          trailing="ms"
+          type="number"
+          defaultValue="4000"
+          onValueChange={(_e, a) => setDuration(a.value)}
+        />
+      </div>
+
+      <div className={styles.buttons}>
+        <Button
+          priority="secondary"
+          label="Toast text"
+          onClick={() => Toaster.manager.add(() => 'Your changes were saved.', opts())}
+        />
+        <Button
+          priority="secondary"
+          tone="success"
+          label="Toast a Banner"
+          onClick={() =>
+            Toaster.manager.add(
+              (id) => (
+                <Banner
+                  tone="success"
+                  round
+                  message="Your changes were saved."
+                  onDismiss={() => Toaster.manager.dismiss(id)}
+                />
+              ),
+              opts(),
+            )
+          }
+        />
+        <Button
+          priority="secondary"
+          tone="info"
+          label="Toast a Card"
+          onClick={() =>
+            Toaster.manager.add(
+              () => (
+                <Card tone="info" size="small" header="Deployment ready">
+                  Your build passed all checks.{' '}
+                  <Button size="small" priority="tertiary" label="Dismiss" data-toast-dismiss />
+                </Card>
+              ),
+              opts(),
+            )
+          }
+        />
+        <Button
+          priority="secondary"
+          tone="brand"
+          label="Toast a Sticker"
+          onClick={() => Toaster.manager.add(() => <StickerClap size={96} label="Nice work" />, opts())}
+        />
+        <Button
+          priority="secondary"
+          label="Toast with countdown"
+          onClick={() => {
+            const ms = Number(duration) || 5000
+            Toaster.manager.add(
+              (id) => (
+                <div className={styles.countdownToast}>
+                  <Banner
+                    tone="info"
+                    round
+                    message="Auto-dismissing — hover to pause"
+                    onDismiss={() => Toaster.manager.dismiss(id)}
+                  />
+                  {/* Reads the toast's own --toast-remaining — no duration passed. */}
+                  <span className={styles.countdownBar} />
+                </div>
+              ),
+              { placement: 'bottom-right', duration: ms },
+            )
+          }}
+        />
+      </div>
+    </div>
+  )
+}
+```
+
+```css title="ToasterDemo.module.css"
+.demo {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.controls {
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  flex-wrap: wrap;
+}
+
+.buttons {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.countdownToast {
+  position: relative;
+}
+
+.countdownBar {
+  position: absolute;
+  left: 10px;
+  right: 10px;
+  bottom: 5px;
+  height: 3px;
+  border-radius: 999px;
+  transform-origin: left;
+  background: color-mix(in oklch, currentColor 35%, transparent);
+  transform: scaleX(var(--toast-remaining));
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .countdownBar {
+    display: none;
+  }
+}
+```
+
+Use the playground to try notification content, placement, and duration.
+Edit the Banner and the options passed to `add`.
 
 ## Mount the region, drive the store
 
@@ -33,8 +171,8 @@ function App() {
 }
 ```
 
-Then, from anywhere, add a toast by passing a render function. The simplest case is
-a string — it's wrapped in a dismissible `Banner` for you:
+Add a toast by passing a function that returns its content. Returning a string
+creates a dismissible Banner:
 
 ```tsx
 import { Toaster } from '@antadesign/anta'
@@ -42,16 +180,14 @@ import { Toaster } from '@antadesign/anta'
 Toaster.manager.add(() => 'Saved.', { placement: 'bottom-right' })
 ```
 
-`add` returns an `id`, and the render function receives it — so a toast can dismiss
-itself. See [Timing and dismissal](#timing-and-dismissal) for how each kind of
-content closes its toast.
+`add` returns an `id` and passes it to the render function. Use it to update or
+dismiss that notification. See [Timing and dismissal](#timing-and-dismissal).
 
 ## Toast anything
 
-The render function can return a **string, JSX, or a live DOM node** — the same
-`add` handles all three. A bare string / number is wrapped in a dismissible `Banner`;
-other JSX renders through the reconciler as-is; a DOM node is slotted by the element
-(return a *stable* node, created once, not a fresh one per call).
+Return a string or number for a dismissible Banner, or JSX for custom content.
+For an existing widget, return its DOM node. Use a stable node that is not owned
+by another React or Preact tree.
 
 ```tsx
 // JSX — rendered as-is
@@ -68,10 +204,18 @@ el.textContent = '🎉'
 Toaster.manager.add(() => el)
 ```
 
-Returning a raw DOM node **into React errors** if you hand it to JSX directly —
-`add` avoids that by routing a `Node` to the element instead of the reconciler.
-(Toast a JSX component like `<Banner/>` by returning it; reach for a DOM node only
-when you already have one, e.g. from a non-React widget.)
+### Existing DOM nodes
+
+Return a DOM node from the render function rather than placing it directly in
+JSX. Toast moves the original node into its content region, preserving listeners
+and widget state. It does not clone the node or restore its previous parent when
+the toast is removed.
+
+When using the raw `content` property, replacing or clearing it removes only
+nodes previously supplied through that property. A fragment's children move into
+the toast, leaving the fragment empty. Refill and reassign the fragment to
+replace those children. The getter returns the assigned node, or `null` after
+clearing. Never supply a node still owned by another renderer.
 
 ## Placement
 
@@ -80,29 +224,25 @@ grow upward (newest nearest the edge), top zones grow downward. Six values:
 
 `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`.
 
-One `<Toaster>` serves every placement — each toast routes to its own zone, so a
-single mounted region drops notices in any corner.
+One Toaster serves all six placements. Choose a placement for each notification.
 
 ## Timing and dismissal
 
-Each toast auto-dismisses after `duration` (ms), 5000 by default; the countdown
-pauses while the pointer is over the toast **or** focus is inside it. `duration:
-Infinity` keeps it until dismissed (empty, zero, and non-positive values fall back
-to the default). On dismiss the toast animates out and then leaves.
+Set `duration` in milliseconds to control how long a notification stays visible.
+The default is 5000ms. The timer pauses while the toast is hovered or contains
+focus. Pass `Infinity` to keep it until dismissed. Empty, zero, and non-positive
+values use the default. Dismissing a toast plays its exit animation, then removes it.
 
 ```tsx
 Toaster.manager.add(() => 'Still here until you close it', { duration: Infinity })   // sticky
 ```
 
-The toast itself carries **no ✕** — dismissal comes from the content. Three ways,
-depending on what you toast:
+Provide a dismissal action when a notification should be closable before its
+timer ends:
 
-- **A string** auto-wraps in a `Banner`, so its ✕ is there for free.
-- **Any control carrying `data-toast-dismiss`** dismisses the toast on click. This is
-  the simplest path — no handler, no `id`, no `onDismiss`; the render function doesn't
-  even take an argument. Add the attribute to a button, link, or menu item inside
-  the content (the same convention as `<a-banner>`'s `data-banner-dismiss` and
-  `<a-dialog>`'s `data-dialog-close`):
+- A string becomes a Banner with its own close button.
+- Add `data-toast-dismiss` to a button, link, or menu item inside custom content
+  to dismiss its toast without a separate handler:
 
   ```tsx
   Toaster.manager.add(() => (
@@ -112,9 +252,8 @@ depending on what you toast:
   ))
   ```
 
-- **A `Banner` you toast yourself** dismisses through its own `onDismiss` — wire it
-  to `dismiss(id)`, and its ✕ (plus any `data-banner-dismiss` action inside it)
-  closes the toast:
+- For a Banner you render yourself, connect `onDismiss` to `dismiss(id)`.
+  Its close button and any `data-banner-dismiss` actions then close the toast:
 
   ```tsx
   Toaster.manager.add((id) => (
@@ -131,9 +270,8 @@ Toaster.manager.update(id, () => 'Saved')       // swap content in place
 Toaster.manager.clear()                         // dismiss all
 ```
 
-Pass your own `id` to **upsert** — a second `add` with the same id replaces the
-live toast's content and restarts its timer, instead of stacking a duplicate. Good
-for a step that reports progress, or to dedupe a repeated event:
+Pass the same `id` to update an existing notification and restart its timer.
+Use this for task progress or repeated events that should share one notice:
 
 ```tsx
 Toaster.manager.add(() => <Banner message="Saving…" />, { id: 'save' })
@@ -143,12 +281,11 @@ Toaster.manager.add(() => <Banner tone="success" message="Saved" />, { id: 'save
 
 ## Show the time left
 
-The toast exposes how much of its timer is left as **`--toast-remaining`** — a
-number that animates from `1` (just shown) to `0` (about to dismiss), inherited by
-the content. Draw a countdown with one CSS rule that reads it. No duration to pass,
-no keyframes, no timer of your own — and it pauses with the toast (hover / focus)
-because the variable itself pauses. Try **Toast with countdown** in the demo above
-and hover it.
+Read `--toast-remaining` to draw a countdown. It decreases from `1` to `0` and
+pauses while the toast is hovered or contains focus. Use the same value for the
+bar so it follows the notification's timer.
+
+Try **Toast with countdown** and hover the notification to pause it.
 
 ```tsx
 Toaster.manager.add(
@@ -172,23 +309,20 @@ Toaster.manager.add(
 }
 ```
 
-**Why a variable, not a prop?** You could instead pass `secondsLeft` into the render
-function and tick it. But updating a prop re-runs the render function and re-diffs the
-whole toast — the Banner, its ✕, everything — many times a second, which can disturb
-focus, text selection, or an in-progress animation inside the content. `--toast-remaining`
-updates a single inherited value the browser interpolates on the compositor: the
-content renders **once**, nothing reconciles, and it's smooth at display refresh rate
-instead of the application's tick interval. The toast already tracks its timer
-and pause state, so exposing the value keeps one source of truth.
+The countdown is visual feedback. Dismissal still follows `duration` if the
+browser cannot animate the custom property. With `duration: Infinity`, the
+value stays at `1`.
+
+Hide a custom countdown bar for people who prefer reduced motion:
 
-`--toast-remaining` is display only — the real dismissal is the toast's own timer — so
-where a browser can't animate a custom property it simply stays full. A **sticky**
-(`duration: Infinity`) toast has no countdown; the value stays `1`.
+```css
+@media (prefers-reduced-motion: reduce) {
+  .countdown-bar { display: none; }
+}
+```
 
-The bar is motion — if you draw one, gate it under `prefers-reduced-motion` yourself
-(e.g. `@media (prefers-reduced-motion: reduce) { .countdown-bar { display: none } }`).
-`a-toast`'s own enter/exit fades are already suppressed there; `--toast-remaining`
-keeps ticking so non-visual uses still work, and the toast still auto-dismisses.
+Toast already suppresses its entrance and exit fades for reduced motion.
+The timer continues, so notifications still dismiss on schedule.
 
 ## Multiple regions
 
@@ -207,17 +341,27 @@ export const alerts = createToaster()
 alerts.add(() => <Banner tone="critical" message="Connection lost" />, { placement: 'top-center' })
 ```
 
-One store drives one `<Toaster>`.
+Use one Toaster per store.
+
+### Server rendering and shared stores
+
+Keep toast stores empty during server rendering to avoid hydration mismatches.
+Follow [Browser hydration](../install-config.md#browser-hydration) before mounting.
+
+Use the same JSX entry for a region and its default `Toaster.manager`.
+Independent full and granular builds have separate default stores. To coordinate
+across those entries, pass the same `createToaster()` store explicitly.
 
 ## Announcements
 
-Announcement is opt-in **per toast**: pass `politeness` to give that toast an
-`aria-live` region — `'polite'` waits for a pause, `'assertive'` interrupts. Omit
-it for no announcement, which is right when the content carries its own live
-semantics (a `Banner` defaults to `role="status"`).
+Use `politeness: 'polite'` for a routine screen reader announcement, or
+`'assertive'` for an urgent notice that should interrupt. Omit it when the
+content already supplies its announcement. Banner defaults to `role="status"`.
+When Toaster supplies the announcement, set the Banner's role to `none` to
+avoid nested live regions.
 
 ```tsx
-Toaster.manager.add(() => <Banner tone="critical" message="Connection lost" />, {
+Toaster.manager.add(() => <Banner role="none" tone="critical" message="Connection lost" />, {
   politeness: 'assertive',
 })
 ```
@@ -231,11 +375,11 @@ Toaster.manager.add(() => <Banner tone="critical" message="Connection lost" />,
 
 ## Web Component
 
-Use the web component directly when you are not using React or Preact and a native control does not fit.
+Use `<a-toaster>` and `<a-toast>` directly outside JSX. Place each toast in a
+slot named for its placement, such as `bottom-center`. Add a dismissal control
+with `data-toast-dismiss`, then listen for `dismiss` and remove that toast.
 
-Place each `<a-toast>` in a positional slot. This button clones the toast template
-into the toaster. `data-toast-dismiss` requests removal; listen for `dismiss` and
-remove the toast from the DOM.
+This example adds a notification by cloning a template:
 
 ```html
 <div data-anta-composition="toaster">
@@ -245,8 +389,8 @@ remove the toast from the DOM.
   <template data-toast-template>
     <a-toast slot="bottom-center" aria-live="polite">
       <a-banner tone="info" round>
-        <a-banner-message slot="message">A new version is available.</a-banner-message>
-        <a-button slot="actions" role="button" tabindex="0" data-toast-dismiss><a-button-label>Dismiss</a-button-label></a-button>
+        <a-banner-message>A new version is available.</a-banner-message>
+        <a-banner-actions><a-button role="button" tabindex="0" data-toast-dismiss><a-button-label>Dismiss</a-button-label></a-button></a-banner-actions>
       </a-banner>
     </a-toast>
   </template>
@@ -267,10 +411,20 @@ remove the toast from the DOM.
 </script>
 ```
 
+### Raw toast timing
+
+`duration="Infinity"` keeps a toast until dismissed. Missing, empty, zero,
+negative, and invalid durations use 5000ms. Hover and focus each pause the timer.
+
+Change `rev` or call `restart()` to restart the countdown. Changing `duration`
+alone applies on the next restart. Reconnecting starts a fresh duration or
+resumes a pending exit. The `dismiss` event fires after the exit animation.
+The application then removes the element.
+
 ## Styling
 
 The region and item are plain custom elements — style them with ordinary CSS
-(`@layer anta`, so an un-layered rule of yours wins without `!important`).
+(defaults use `@layer anta.components`, so an unlayered rule wins without `!important`).
 
 Region spacing lives on `a-toaster` as tokens: **`--toaster-inset`** (gap from the
 viewport edge), **`--toaster-gap`** (space between stacked toasts), and
@@ -288,8 +442,12 @@ a-toaster { --toaster-width: 420px; --toaster-gap: 10px; }
 a-toast { filter: drop-shadow(0 6px 20px color-mix(in oklch, black 22%, transparent)); }
 ```
 
-The content keeps its own styling — a toned `Banner` brings its surface, a `Card`
-its border.
+The content keeps its own styling. A toned `Banner` brings its surface; a `Card`
+brings its border. `a-toaster::part(region)` reaches the popover surface.
+`::part(zone)` reaches all six columns, and `::part(top-left)` through
+`::part(bottom-right)` reaches one placement. `a-toast::part(content)` reaches
+the content slot. Keep columns and the region click-through when customizing
+their appearance. Countdown timing belongs to `duration` and `restart()`.
 
 ## Example