@antadesign/anta 0.3.18 → 0.3.19

package/docs/components/text.md

@@ -0,0 +1,148 @@
+# Text
+
+A block-level text container that scopes the color hierarchy of its
+contents. `priority` sets the emphasis from `primary` (`--text-1`) to
+`quaternary` (`--text-4`). It defaults to `secondary` (`--text-2`), so body
+text reads a step softer than the strongest foreground; pass `primary`
+for emphasis. `tone` adds a tint (`brand`, `success`, `critical`,
+`warning`, `info`, or any literal CSS color for a one-off custom tone); the
+default `neutral` leaves it untinted. `inline` renders it `inline-block` for use
+mid-sentence.
+
+Links nested inside `<Text>` take Anta's prose-link styling from the
+design system, with no per-page overrides to maintain.
+
+## Link behavior
+
+Links inside `<Text>` follow a priority-aware hierarchy that keeps
+emphasis consistent with the surrounding text:
+
+| Priority      | Link color (default)              | Link color (hover)            |
+|---------------|-----------------------------------|-------------------------------|
+| `primary`     | `--link-color` (brand blue)       | `--link-color-hover`          |
+| `secondary`   | `--link-color`                    | `--link-color-hover`          |
+| `tertiary`    | `currentColor` (= `--text-3`)     | `--text-2`                    |
+| `quaternary`  | `currentColor` (= `--text-4`)     | `--text-3`                    |
+
+The underline is a 0.5px hairline at 75% alpha by default and bumps to
+1px / 100% alpha on hover. On `:active` it returns to the 0.5px / 75%
+resting state.
+
+For tinted text (`tone="brand|success|critical|warning|info"`) links are
+always muted regardless of priority: they take `currentColor` and step up
+to the next-stronger level of the same tint on hover. At
+`priority="primary"` there is no level above, so hovering only brings the
+underline to full alpha.
+
+## Demo
+
+## Truncation & expansion
+
+`truncate` takes `true` (or `1`) for a single-line ellipsis, any integer
+≥ 2 for multi-line clamping, and `0` or a negative value for no
+truncation. Both modes use `-webkit-line-clamp` inside
+`display: -webkit-box`, supported in every major browser despite the
+prefix (Firefox 68+, Chrome, Safari, Edge). The host gets `min-width: 0`
+so truncation works inside flex and grid containers.
+
+```tsx
+{/* Single line */}
+<Text truncate>{longSentence}</Text>
+
+{/* Multi-line: pass the line count */}
+<Text truncate={2}>{longSentence}</Text>
+<Text truncate={3}>{longSentence}</Text>
+```
+
+Pair `expandable` with `truncate` to let the reader reveal the full text.
+The fade and chevron appear only when the clamped content overflows; text
+that fits gets neither. Single-line truncation fades on the right edge,
+multi-line over the last line. The chevron is a real `<button>` carrying
+`aria-expanded`: click it, or focus it and press Enter, to drop the clamp.
+`expandable` takes effect only with `truncate`.
+
+Expanding is one-way by default, so the control is removed once the text
+is revealed. Add `collapsible` for a two-way toggle: the chevron stays
+visible while expanded (rotated up) and flips its label between "Show
+more" and "Show less". `collapsible` takes effect only with `expandable`.
+
+```tsx
+{/* One-way: the chevron is removed once expanded */}
+<Text truncate expandable>{longSentence}</Text>
+<Text truncate={3} expandable>{longSentence}</Text>
+
+{/* Two-way: the reader can collapse it back */}
+<Text truncate={3} expandable collapsible>{longSentence}</Text>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `collapsible?` | boolean | — | Let the reader collapse back after expanding: the chevron becomes a
+ "Show more" / "Show less" toggle that stays visible while expanded.
+ Only takes effect together with `expandable`. |
+| `expandable?` | boolean | — | Show a fade hint and chevron over the truncated text and let the user
+ expand it by clicking the chevron region or pressing Enter while the
+ chevron has keyboard focus. Only takes effect together with `truncate`.
+ On its own, expanding is **one-way** — the control is removed once
+ expanded; add `collapsible` for a two-way toggle. |
+| `inline?` | boolean | — | Render as inline-block instead of the default block element. |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary' | secondary | Visual priority. Maps to text-1..text-4 (`primary` = text-1, the
+ strongest). The default is `secondary` (text-2) — body text reads a
+ step softer than the strongest foreground; pass `primary` for emphasis. |
+| `size?` | 'small' \| 'medium' \| 'large' | medium | Type scale. `small` = 13/16, `medium` = 15/20, `large` = 17/24. |
+| `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. Uses the `-webkit-line-clamp`
+ technique, supported in all major browsers (Firefox 68+, Chrome,
+ Safari, Edge). |
+
+Use this when you are not using the React or Preact wrapper and a native HTML control does not fit: construct the equivalent Anta web component from the elements below.
+
+Use `<a-text>` directly for a block that carries the text priority and tone.
+
+```html
+<a-text priority="secondary">
+  Read the <a href="/colors/">color guidance</a>.
+</a-text>
+```
+
+Colour comes from **`priority`** (the neutral text level) and **`tone`** (the tint);
+`size` and the type props set the rest. For a named tone, `Text` consumes the
+global **text role tokens** (`--text-1` … `--text-5`, the `-{tone}` tints,
+`--link-color`), so retuning those once on `:root` / `.dark` shifts text colour
+everywhere (see [Colors](../colors.md)). A custom `tone` (any CSS color) is derived in
+oklch from **`--text-tone-source`** — the same one-off knob as `Button` / `Tag`.
+
+```tsx
+<Text priority="secondary" tone="brand">Tinted secondary text</Text>
+<Text tone="#0d9488">Custom-tone body copy</Text>
+```
+
+`<a-text>` is light-DOM, so one-offs are plain CSS on the element or its prose
+links. The `.fancy` class names the demo example:
+
+```css
+/* teal body text via light-dark() (deep in light, bright in dark; Anta drives
+   color-scheme from its theme toggle), with wider tracking */
+a-text.fancy {
+  color: light-dark(#0f6e5f, #5fd0bb);
+  font-size: 16px;
+  line-height: 1.7;
+  letter-spacing: 0.06em;
+}
+a-text.fancy a { text-decoration-thickness: 2px; text-underline-offset: 3px; }
+```
+
+## Example
+
+```tsx
+import { Text } from '@antadesign/anta'
+
+<Text>The quick brown fox jumps over the lazy dog with a <a href="#">link inside</a> the sentence, followed by enough additional prose to push the paragraph well past a single line. Curabitur sodales ligula in libero, and Donec a tincidunt elit. Mauris vehicula, est nec porta cursus, tellus eros vestibulum lectus, vitae luctus turpis enim sed nibh.</Text>
+```

package/docs/components/title.md

@@ -0,0 +1,146 @@
+# 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 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.
+
+## Levels
+
+The parent supplies the `16px` gap between these titles.
+
+  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
+
+## Inline content
+
+Pass icons and inline elements as children. Icons are optically aligned with
+the title text.
+
+```tsx
+<Title level={3}>
+  <Icon shape="book-open" /> Saved items{' '}
+  <span style={{ color: 'var(--text-1-brand)' }}>(3)</span>
+</Title>
+```
+
+Use a span for a small inline accent. Don't nest `<Text>` or `<a-text>` inside a
+title: they are block containers, while heading content should remain inline.
+
+## Level reference
+
+| level | font-size | line-height |
+|------:|----------:|------------:|
+| 1     | 28px      | 32px        |
+| 2     | 24px      | 28px        |
+| 3     | 20px      | 24px        |
+| 4     | 17px      | 20px        |
+| 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.
+
+
+    Neutral primary
+    Secondary
+    Tertiary
+    Quaternary
+
+    Brand primary
+    Secondary
+    Tertiary
+    Quaternary
+
+    Success primary
+    Secondary
+    Tertiary
+    Quaternary
+
+    Critical primary
+    Secondary
+    Tertiary
+    Quaternary
+
+    Warning primary
+    Secondary
+    Tertiary
+    Quaternary
+
+    Info primary
+    Secondary
+    Tertiary
+    Quaternary
+
+
+## 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.
+
+### 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). |
+| `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. |
+
+Use this when you are not using the React or Preact wrapper and a native HTML control does not fit: construct the equivalent Anta web component from the elements below.
+
+Set the heading role and level when writing `<a-title>` directly.
+
+```html
+<a-title level="2" tone="brand" role="heading" aria-level="2">
+  Release notes
+</a-title>
+```
+
+`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.
+
+```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.
+
+```css
+a-title.release-heading {
+  font-size: 18px;
+  line-height: 24px;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+}
+```
+
+## Example
+
+```tsx
+import { Title } from '@antadesign/anta'
+
+<Title>Section heading</Title>
+```

package/docs/components/toaster.md

@@ -0,0 +1,313 @@
+# 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.
+
+## Mount the region, drive the store
+
+Mount one `<Toaster>` at a stable spot in your tree and leave it there:
+
+```tsx
+import { Toaster } from '@antadesign/anta'
+
+function App() {
+  return (
+    <>
+      <YourApp />
+      <Toaster />        {/* keep it mounted — toasts render here */}
+    </>
+  )
+}
+```
+
+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:
+
+```tsx
+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.
+
+## 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).
+
+```tsx
+// JSX — rendered as-is
+Toaster.manager.add(() => <Card tone="info" size="small" header="Deployment ready">
+  Your build passed all checks.
+</Card>, { placement: 'top-right' })
+
+// a string — auto-wrapped in a dismissible Banner
+Toaster.manager.add(() => 'Copied to clipboard')
+
+// a DOM node (create it once, return the same reference)
+const el = document.createElement('div')
+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.)
+
+## Placement
+
+`placement` picks the corner or edge; the default is `bottom-right`. Bottom zones
+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.
+
+## 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.
+
+```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:
+
+- **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. Just 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`):
+
+  ```tsx
+  Toaster.manager.add(() => (
+    <Card header="Update ready">
+      A new version is available. <Button data-toast-dismiss label="Later" />
+    </Card>
+  ))
+  ```
+
+- **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:
+
+  ```tsx
+  Toaster.manager.add((id) => (
+    <Banner tone="success" round message="Saved" onDismiss={() => Toaster.manager.dismiss(id)} />
+  ))
+  ```
+
+Or drive dismissal from anywhere with the returned id:
+
+```tsx
+const id = Toaster.manager.add(() => 'Saving…', { duration: Infinity })
+Toaster.manager.dismiss(id)                     // animate out, then remove
+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:
+
+```tsx
+Toaster.manager.add(() => <Banner message="Saving…" />, { id: 'save' })
+// …later…
+Toaster.manager.add(() => <Banner tone="success" message="Saved" />, { id: 'save' })  // in place
+```
+
+## 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.
+
+```tsx
+Toaster.manager.add(
+  (id) => (
+    <div className="countdown-toast">
+      <Banner tone="info" round message="Auto-dismissing…" onDismiss={() => Toaster.manager.dismiss(id)} />
+      <span className="countdown-bar" />
+    </div>
+  ),
+  { duration: 6000 },
+)
+```
+
+```css
+.countdown-toast { position: relative; }
+.countdown-bar {
+  position: absolute; inset-inline: 10px; bottom: 5px; height: 3px;
+  border-radius: 999px; transform-origin: left;
+  background: color-mix(in oklch, currentColor 35%, transparent);
+  transform: scaleX(var(--toast-remaining));   /* 1 → 0 over the toast's life */
+}
+```
+
+**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 your tick interval. The toast already owns the timer and its pause, so
+exposing the value keeps one source of truth.
+
+`--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`.
+
+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.
+
+## Multiple regions
+
+`Toaster.manager` is the default store. For an isolated region, create your own and
+bind it to a `<Toaster>` with `toaster`:
+
+```tsx
+import { createToaster, Toaster } from '@antadesign/anta'
+
+export const alerts = createToaster()
+
+// mount its region:
+<Toaster toaster={alerts} />
+
+// drive it:
+alerts.add(() => <Banner tone="critical" message="Connection lost" />, { placement: 'top-center' })
+```
+
+One store drives one `<Toaster>`.
+
+## 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"`).
+
+```tsx
+Toaster.manager.add(() => <Banner tone="critical" message="Connection lost" />, {
+  politeness: 'assertive',
+})
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label?` | string | 'Notifications' | Accessible label for the region landmark. |
+| `toaster?` | Toaster | — | The store this region renders. Omit to bind the default store driven by
+ `Toaster.manager`; pass a `createToaster()` for an isolated region. |
+
+Use this when you are not using the React or Preact wrapper and a native HTML control does not fit: construct the equivalent Anta web component from the elements below.
+
+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.
+
+```html
+<div data-anta-composition="toaster">
+  <a-button data-toast-add role="button" tabindex="0"><a-button-label>Show update</a-button-label></a-button>
+  <a-toaster role="region" aria-label="Notifications">
+  </a-toaster>
+  <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>
+    </a-toast>
+  </template>
+</div>
+<script type="module">
+  import '@antadesign/anta/elements'
+
+  const root = document.querySelector('[data-anta-composition="toaster"]')
+  const trigger = root.querySelector('[data-toast-add]')
+  const template = root.querySelector('template[data-toast-template]')
+  const toaster = root.querySelector('a-toaster')
+
+  trigger.addEventListener('click', () => toaster.append(template.content.cloneNode(true)))
+  // A dismissed toast finishes its exit animation, but stays in the DOM until its owner removes it.
+  root.addEventListener('dismiss', (event) => {
+    if (event.target instanceof HTMLElement && event.target.matches('a-toast')) event.target.remove()
+  })
+</script>
+```
+
+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`).
+
+Region spacing lives on `a-toaster` as tokens: **`--toaster-inset`** (gap from the
+viewport edge), **`--toaster-gap`** (space between stacked toasts), and
+**`--toaster-width`** (column width). The item's enter/exit timing lives on
+`a-toast`: **`--toast-dur`**. The item also publishes **`--toast-remaining`** (a
+number, `1` → `0`, tracking the auto-dismiss timer) for content to read — see
+[Show the time left](#show-the-time-left). The item is style-neutral — no chrome of
+its own — so a toast looks like exactly the content you pass.
+
+`<a-toast>` is the content box itself, so add elevation (or any style) with the
+plain `a-toast` selector:
+
+```css
+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.
+
+## Example
+
+```tsx
+import { Toaster, Button, Banner } from '@antadesign/anta'
+
+<Toaster />
+<Button
+  label="Toast it"
+  onClick={() =>
+    Toaster.manager.add(
+      (id) => (
+        <Banner
+          tone="success"
+          round
+          message="Your changes were saved."
+          onDismiss={() => Toaster.manager.dismiss(id)}
+        />
+      ),
+      { placement: 'bottom-right', duration: 4000 },
+    )
+  }
+/>
+```