@antadesign/anta 0.3.33 → 0.3.35

package/docs/components/tabs.md

@@ -1,13 +1,12 @@
 # Tabs
 
-A tablist for switching between views. The strip is data-driven: pass an
-`options` array (like [RadioGroup](./radio.md)), each entry a unique `value` plus a
-`label` (or `children`) and optional `icon` / `iconTrailing`. That alone is a
-selectable strip that emits the chosen value; add matching `<TabPanel>` children
-(see [Panels](#panels)) to show and hide the content too.
+Use Tabs to switch between related views, such as account and security settings.
+Pass an `options` array with a unique `value` and a label for each tab. Add
+matching `TabPanel` children to display the selected view, or render that
+content yourself.
 
-Each option can also set `className`, `style`, and `data-*` attributes on its
-individual `<a-tab>`.
+Options also accept icons, custom content, `className`, `style`, and `data-*`
+attributes. See [Panels](#panels) for content layout.
 
 ## Priority
 
@@ -43,9 +42,9 @@ custom color); columns are priorities.
 
 **Per-tab tone.** A `tone` on an individual option overrides the strip's tone for that one
 tab: it colors the label and icons in every mode, and the indicator when it's the active tab.
-A named tone colors the sliding indicator too; a custom literal color tones the label
-everywhere but the indicator only under `noslide` (the single shared sliding element can't
-read a descendant's color).
+The track background and border keep the strip's tone when selection changes.
+Named tones also color the sliding indicator. For a custom CSS color on an
+individual option, pass `noslide` to color its indicator too.
 
 ```tsx
 <Tabs
@@ -70,6 +69,9 @@ Three sizes reuse [Button](./button.md)'s type scale, so a strip lines up with
 same-size buttons and inputs: `small`, `medium` (default), `large`. Icons scale
 with the tab.
 
+In the Antithesis theme, tabs match text buttons' horizontal padding:
+10px per side at `small`, 12px at `medium`, and 14px at `large`.
+
 ## Orientation
 
 `horizontal` (default) lays the tabs in a row; `vertical` stacks them into a column.
@@ -119,10 +121,9 @@ instead of `label`, like a [Tag](./tag.md) counter.
 When the tabs don't fit, their labels truncate with an ellipsis; the strip never
 widens the page. To scroll or wrap labels instead, see [Styling](#styling).
 
-Set an option's **`tooltip`** and a clipped tab reveals its full label on hover; tabs
-that fit show nothing. It renders as a `truncatedOnly` [Tooltip](./tooltip.md#show-only-when-truncated)
-anchored to the tab, so it shows only when the label ellipsizes. Hover the truncated
-tabs above to see it.
+Set an option's `tooltip` to reveal its full label when truncated. Tabs whose
+labels fit do not show a tooltip. See
+[Show only when truncated](./tooltip.md#show-only-when-truncated).
 
 ```tsx
 <Tabs
@@ -159,79 +160,75 @@ tabs above to see it.
 </div>
 ```
 
-Add a `<TabPanel value="…">` child for each option; each panel shows itself when
-its value is active. The panel names its tab as its accessible label
-(`aria-labelledby`, off-DOM). Panel content is arbitrary React, so it renders normally.
+Add a `TabPanel` child with a matching `value` for each option. The selected
+panel is visible and uses its tab as its accessible label. Panel content can
+include forms, charts, or other components.
+
+Panels are optional. To render the selected content yourself, listen to
+`onStateChange` or `onValueChange`.
+
+<a id="jsx-vs-dom"></a>
 
-Panels are **optional**. Without panels, `Tabs` renders the strip. Listen to
-`onStateChange` / `onValueChange` and render the content yourself.
+### Panel layout
 
-### JSX vs DOM
+`Tabs` renders the strip followed by its panels as siblings, without a wrapper.
+`className`, `id`, `style`, and extra props apply to the strip. Keep the strip
+and its panels under the same parent so they can coordinate selection and
+accessible labels.
 
-The strip renders from the `options` array; each `<TabPanel>` renders a
-self-managing `<a-tabpanel>`. `Tabs` **never reads or toggles the panels**: there's
-no child introspection, so it renders the same in static SSR and works with any
-renderer. There is **no wrapper element**: the JSX becomes the strip followed by the
-panels as flat **siblings**, and `className` / `id` / `style` / `...rest` land on the
-strip. Arranging them is up to you (see below):
+The resulting structure is:
 
 ```html
-<a-tabs role="tablist">
+<a-tabs role="tablist" aria-label="Settings" default-state="account">
   <a-tab role="tab" value="account" tabindex="0"><a-tab-label>Account</a-tab-label></a-tab>
-  …
+  <a-tab role="tab" value="security" tabindex="-1"><a-tab-label>Security</a-tab-label></a-tab>
 </a-tabs>
-<a-tabpanel role="tabpanel" value="account">…</a-tabpanel>   <!-- active: shown -->
-<a-tabpanel role="tabpanel" value="security">…</a-tabpanel>  <!-- inactive: display:none -->
+<a-tabpanel role="tabpanel" value="account">Account settings</a-tabpanel>
+<a-tabpanel role="tabpanel" value="security">Security settings</a-tabpanel>
 ```
 
-A horizontal strip stacks above its panels in normal flow with no extra markup; for a
-vertical strip beside its panels, wrap `<Tabs>` in your own flex row. The panels find
-the strip as a sibling under the same parent (`a-tabpanel` → `:scope > a-tabs`), so
-keep them together; to split them into separate layout regions, drive a
-controlled `value` and render the panels yourself.
-
-Each `<a-tabpanel>` sits **beside** `<a-tabs>` (its sibling, never inside it, so a
-panel never lands in the primary track). It reads the active value from `<a-tabs>`
-and shows/hides **itself** via its own off-DOM `:state(active)`; nothing writes
-`hidden` / `inert` on it. The panel↔tab link is off-DOM too
-(`internals.ariaLabelledByElements`), so no `id` wiring is needed. No web component
-writes the light DOM, only your JSX does, which keeps a worker-thread reactive engine
-in sync.
+A horizontal strip and its panels stack in normal flow. For a vertical strip
+beside its panels, wrap `Tabs` in a flex row. To place content in a separate
+layout region, control `value` and render that content yourself.
 
 ### Hiding an inactive panel
 
-A `<TabPanel>` stays mounted while inactive (its DOM, form values, and scroll
-survive tab switches); `hideMode` picks how it hides:
+Inactive panels stay mounted, preserving form values and scroll position.
+Choose how they hide with `hideMode`:
 
-- **`display`** (default): `display:none`; leaves the tab order + a11y tree.
-- **`visibility`**: `visibility:hidden`, keeping its layout box (to avoid reflow
-  or to measure a hidden panel).
+- `display` (default) removes the inactive panel from layout, keyboard navigation,
+  and the accessibility tree.
+- `visibility` keeps its layout space while hiding its content.
 
 ```tsx
-<TabPanel value="b" hideMode="visibility"><Chart /></TabPanel>
+<TabPanel value="activity" hideMode="visibility"><ActivityChart /></TabPanel>
 ```
 
-To **not render** an inactive panel at all (unmount it to reset its state or defer an
-expensive subtree, or mount it lazily on first open), drive selection with a
-controlled `value` and render the panels yourself. `Tabs` passes panels straight
-through, so you decide what's mounted:
+To reset a panel's state when leaving it, control selection and render only the
+active panel:
 
 ```tsx
-const [tab, setTab] = useState('a')
+const [tab, setTab] = useState('summary')
 
-// Unmount inactive — only the open panel exists:
-<Tabs value={tab} onStateChange={(_e, { next }) => next && setTab(next)} options={…}>
-  {tab === 'a' && <TabPanel value="a"><Expensive /></TabPanel>}
-  {tab === 'b' && <TabPanel value="b"><Form /></TabPanel>}
+<Tabs
+  label="Report"
+  value={tab}
+  onStateChange={(_event, { next }) => { if (next !== null) setTab(next) }}
+  options={[
+    { value: 'summary', label: 'Summary' },
+    { value: 'activity', label: 'Activity' },
+  ]}
+>
+  {tab === 'summary' && <TabPanel value="summary"><Summary /></TabPanel>}
+  {tab === 'activity' && <TabPanel value="activity"><ActivityChart /></TabPanel>}
 </Tabs>
-
-// Lazy — mount on first open, keep after (track a "seen" set in state):
-{seen.has('b') && <TabPanel value="b"><Heavy /></TabPanel>}
 ```
 
-The same controlled pattern places the strip and panels in **different layout
-regions**: render `<Tabs options={…} value onStateChange>` in one place and your
-content wherever you like, switching on the value yourself.
+For expensive panels, track which values have been opened and mount each panel
+on its first visit. Keep it mounted afterward to preserve its state.
+
+The same controlled pattern lets you place the strip and selected content in
+separate layout regions. Render the content according to the current `value`.
 
 ## Controlled vs. uncontrolled
 
@@ -261,7 +258,7 @@ const [tab, setTab] = useState('overview')
 
 <Tabs
   value={tab}
-  onStateChange={(e, { next }) => setTab(next)}
+  onStateChange={(_event, { next }) => { if (next !== null) setTab(next) }}
   options={[
     { value: 'overview', label: 'Overview' },
     { value: 'activity', label: 'Activity' },
@@ -269,7 +266,9 @@ const [tab, setTab] = useState('overview')
 />
 ```
 
-## Keyboard & accessibility
+<a id="keyboard-accessibility"></a>
+
+## Keyboard and accessibility
 
 The selected tab is in the page's tab order. Once focus enters the strip, the
 arrow keys move between enabled tabs (wrapping at the ends), `Home` /
@@ -277,19 +276,16 @@ arrow keys move between enabled tabs (wrapping at the ends), `Home` /
 arrow / `Home` / `End` navigation activates as it moves (selection follows focus).
 Disabled tabs are skipped and dropped from the tab order.
 
-Pass `label` for the tablist's accessible name. Each `<TabPanel>` names its tab as
-its accessible label (`aria-labelledby`), set off-DOM so nothing writes the panel's
-attributes. Static panel content remains readable without making the panel a tab
-stop. Set `tabIndex={0}` when you want a text-only panel itself to receive focus;
-when the panel starts with a focusable control, Tab reaches that control directly.
+Pass `label` to name the tablist for screen readers. Each `TabPanel` uses its
+corresponding tab as its accessible label. Set `tabIndex={0}` when a text-only
+panel should receive keyboard focus. When the panel starts with a focusable
+control, Tab reaches that control directly.
 
 ## Routing
 
-`Tabs` reports the picked value and leaves navigation to the app, so a strip can
-switch routes as readily as panels. Treat each `value` as a path: control `value`
-from the current location and navigate in `onStateChange` (the pick fires *on click*;
-`onValueChange` waits for `value` to change, which for a route happens only after
-you've already navigated). Skip the `<TabPanel>`s, since the router renders the view.
+To use Tabs for routes, control `value` from the current path and navigate in
+`onStateChange`. It reports the requested destination before the route changes.
+The router renders the content, so omit `TabPanel` children.
 
 ```tsx
 <Tabs
@@ -317,16 +313,20 @@ Three callbacks, in firing order:
 | `onChange(e)` | **after** selection applies | — | native `change` event |
 | `onValueChange(e, { value })` | **after** selection applies | — | `{ value }` |
 
-Use **`onStateChange`** when you control `value`: it fires on the user's pick before
-anything applies, so it's your chance to set the new `value`. Applying it (or the
-element self-applying, uncontrolled) then fires **`onChange`** / **`onValueChange`**,
-so those suit an uncontrolled strip reacting to its own pick. **`onFocus`** /
-**`onBlur`** report focus entering and leaving the strip (wired to `focusin` /
-`focusout`, since focus lands on a tab).
+Use `onStateChange` to accept or cancel a requested selection. Use `onChange` or
+`onValueChange` to respond after selection changes. `onFocus` and `onBlur`
+report focus entering and leaving the strip.
 
 ```tsx
-// Uncontrolled: the strip owns selection, so onValueChange fires on each pick.
-<Tabs defaultValue="a" onValueChange={(_e, { value }) => route(value)}>…</Tabs>
+<Tabs
+  label="Report"
+  defaultValue="summary"
+  onValueChange={(_event, { value }) => saveLastView(value)}
+  options={[
+    { value: 'summary', label: 'Summary' },
+    { value: 'activity', label: 'Activity' },
+  ]}
+/>
 ```
 
 ## Tabs props
@@ -347,7 +347,7 @@ so those suit an uncontrolled strip reacting to its own pick. **`onFocus`** /
 | `options?` | TabOption[] | — | The tabs, as a data array (the strip's single source). Each entry is a `TabOption` (`value`, `label` or `children`, `icon`, `iconTrailing`, `tone`, `disabled`, `round`, `className`, `style`). `className` and `style` land on that option's individual `<a-tab>`, not on the strip. |
 | `orientation?` | 'horizontal' \| 'vertical' | 'horizontal' | Layout + arrow-key axis. Horizontal ellipsizes labels when tabs overflow (scroll is opt-in via CSS); vertical stacks them. |
 | `priority?` | 'primary' \| 'secondary' \| 'tertiary' | 'primary' | Visual priority. `primary` is the raised pill on a recessed track (the segmented-control look); `secondary` keeps that sizing but drops the track, marking the selected tab with a subtle active background fill; `tertiary` is a bottom-underline indicator under the selected tab (no track, no rest line). `tone` colors `secondary` + `tertiary`; `primary` stays neutral. |
-| `round?` | boolean \| number \| string | — | Fully-round the tabs and the sliding indicator (and the primary track well). Applies strip-wide; a single tab's `round` rounds just that tab. A `number` (px) or CSS length string sets a custom radius on the top-level track well only — the tab pills + indicator stay fully round. |
+| `round?` | boolean \| number \| string | — | Fully-round the tabs, the sliding indicator, and the primary track. Applies strip-wide; a single tab's `round` rounds just that tab. A `number` (px) or CSS length string sets that radius on all three. |
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size — small 24px · medium 28px · large 32px tall, matching Button's scale (the tab's label leading runs a touch tighter, offset by 1px more block padding per side). |
 | `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Tone applied to the selected indicator/label, or any literal CSS color for a one-off custom tone (derived in oklch). Named tones track light/dark. |
 | `value?` | string | — | Controlled active value — the tab `value` to mark selected (and, when a `<TabPanel value="…">` shares it, the panel to reveal). When set, you own selection: the strip renders exactly what this says, and a user pick only *requests* a change via `onStateChange` — apply it by updating this prop. Leave undefined (and use `defaultValue`) for uncontrolled. |
@@ -365,7 +365,7 @@ so those suit an uncontrolled strip reacting to its own pick. **`onFocus`** /
 | `label?` | ReactNode | — | Visible label. The string shorthand for the tab's content; for richer content pass `children` instead (`label` wins when both are set). |
 | `round?` | boolean | — | Fully-round just this tab's box. `<Tabs round>` rounds the whole strip (tabs + sliding indicator) instead. |
 | `style?` | CSSProperties | — | Inline styles on the option's rendered row. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | inherits the strip's `tone | Per-tab tone override, same vocabulary as `<Tabs tone>` — colors this one tab's label + icons (all priorities/modes, named or custom color) and, when it's the active tab, its indicator. For a **custom literal color** the sliding indicator can't adopt it (the shared moving element can't read a descendant's color), so a custom tone colors the label everywhere and the indicator only in `noslide`; the six **named** tones color both in every mode. Overrides the strip's `tone` for this tab. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | inherits the strip's `tone | Per-tab tone override, same vocabulary as `<Tabs tone>` — colors this one tab's label + icons (all priorities/modes, named or custom color) and, when it's the active tab, its indicator. The track keeps the strip's tone. For a **custom literal color** the sliding indicator can't adopt it (the shared moving element can't read a descendant's color), so a custom tone colors the label everywhere and the indicator only in `noslide`; the six **named** tones color both in every mode. Overrides the strip's `tone` for this tab. |
 | `tooltip?` | ReactNode | — | Tooltip for this tab — a string or any node — shown **only when one of the tab's ellipsizing label parts is truncated** (tabs ellipsize when the strip overflows), so clipped content reveals its full text on hover while a tab that fits shows nothing. Rendered as a `truncatedOnly` `<Tooltip>` anchored to the tab. For an always-visible tooltip or other custom trigger content, use `children` with your own `<Tooltip>` instead. |
 
 ## TabPanel props
@@ -379,6 +379,13 @@ so those suit an uncontrolled strip reacting to its own pick. **`onFocus`** /
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
+Use `state` for controlled selection or `default-state` for the initial
+uncontrolled selection. The read-only `.value` property returns the applied
+selection. Remove `state` to release control and retain that selection.
+User picks update internal state without rewriting authored attributes.
+Accept a controlled pick through `statechange` by setting `state` to
+`event.detail.next`. An empty string is a valid option value.
+
 Keep the tab strip and panels as siblings under one parent. Panels read the active
 value from `<a-tabs>`. Give the selected tab `tabindex="0"` and the others
 `tabindex="-1"`; `<a-tabs>` moves focus and selection with the arrow keys, while
@@ -414,21 +421,20 @@ tabs.addEventListener('change', () => {
 Reach for the props first: **`tone`**, **`size`**, **`priority`**. The focus ring is
 the global `--focus-ring` (see [Colors](../colors.md#focus-ring)).
 
-For anything else the strip is light-DOM: `<a-tabs>` the tablist, each `<a-tab>` a
-tab (its text wrapped in `<a-tab-label>`), `<a-tabpanel>` a panel, and the moving
-indicator is `<a-tabs>`'s `::before`. Target them with ordinary CSS (an un-layered rule
-beats `@layer anta` without `!important`) and reach for real properties
-(`border-radius`, `padding`, `background`, …), **not** the internal `--*` output tokens.
-The demo classes (`.square-tabs`, `.glow-tabs`, …) are hooks. Replace them with selectors you own.
+Use ordinary CSS to style the strip (`a-tabs`), tabs (`a-tab`), labels
+(`a-tab-label`), and panels (`a-tabpanel`). The strip's `::before` paints the
+moving indicator. Unlayered consumer rules override Anta's defaults. Use
+properties such as `border-radius`, `padding`, and `background`.
+Replace the example classes with your own selectors.
 
 **Roomier track.** The strip hugs its tabs by default (0 padding), so it's exactly a
 same-size button tall. For a gap around the selected pill (the classic "well" look), add
-`padding` and bump `border-radius` by the same amount, so the outer corner stays concentric
-with the tabs' 4px. The strip grows 2×the padding taller.
+`padding` and add the same amount to the tabs' radius, `--tab-radius`, so the outer corner
+stays concentric with the tabs in every theme and size. The strip grows 2×the padding taller.
 
 ```css
-a-tabs.roomy-1 { padding: 1px; border-radius: 5px; }   /* 4 + 1 */
-a-tabs.roomy-3 { padding: 3px; border-radius: 7px; }   /* 4 + 3 */
+a-tabs.roomy-1 { padding: 1px; border-radius: calc(var(--tab-radius) + 1px); }
+a-tabs.roomy-3 { padding: 3px; border-radius: calc(var(--tab-radius) + 3px); }
 ```
 
 **Squarer primary.** Square corners, heavier labels, and a roomier `4px` track with no
@@ -494,19 +500,19 @@ shares the strip width:
 .wrap-tabs a-tab-label { white-space: normal; text-overflow: clip; overflow: visible; text-align: center; }
 ```
 
-**Disable the slide.** By default the selected-tab indicator slides between tabs (a
-single rectangle, via CSS anchor positioning). Pass `noslide` to paint it on each tab
-instead, so the highlight snaps with no movement. It's also the automatic fallback
-where anchor positioning isn't supported.
+Pass `noslide` to make the selected-tab highlight change without sliding.
+The highlight also changes without sliding when the browser lacks CSS anchor
+positioning support.
 
 ```tsx
 <Tabs noslide defaultValue="a">…</Tabs>
 ```
 
-**Fully-rounded pill.** The built-in **`round`** prop rounds the track, every tab, **and**
-the sliding pill to `999px` in one flag, no CSS needed (it drives `--tab-radius`, which feeds
-the tabs, the moving indicator, and the primary track well):
+**Rounded corners.** The built-in **`round`** prop rounds the track, every tab, and the
+sliding pill together. `true` makes them full pills; a number (px) or CSS length sets one
+custom radius for all three:
 
 ```tsx
-<Tabs round defaultValue="a" label="Sections">…</Tabs>   {/* pill track + tabs + indicator */}
+<Tabs round defaultValue="a" label="Sections">…</Tabs>      {/* pill track + tabs + indicator */}
+<Tabs round={8} defaultValue="a" label="Sections">…</Tabs>  {/* 8px on all three */}
 ```

package/docs/components/text.md

@@ -1,54 +1,21 @@
 # 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.
+Use Text for body copy, descriptions, and supporting information. Set `priority`
+to emphasize important content or soften secondary details, and use `tone` to
+add color. Text also styles any links inside it.
 
 ## 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.
+Links follow the surrounding text's emphasis and color. In supporting text,
+they stay muted; hover makes them easier to identify. The examples show how
+links look at each priority and tone.
 
 ## Demo
 
 ## Truncation and 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.
-
-JSX `Text` adds a `truncatedOnly` tooltip containing its text content. It
-opens only when the text clips. Nest a `<Tooltip>` to replace that tooltip;
-an empty nested tooltip suppresses it. `expandable` text has no automatic
-tooltip because its own control reveals the content.
+Use `truncate` to keep long text compact. Pass a number to choose how many lines
+to show. Readers can hover over shortened text to read the full content in a tooltip.
 
 ```tsx
 {/* Single line */}
@@ -59,10 +26,52 @@ tooltip because its own control reveals the content.
 <Text truncate={3}>{longSentence}</Text>
 ```
 
+Add `expandable` to let readers reveal long text when they need it. The **Show more**
+icon button appears only when the text does not fit. Add `collapsible` to let them fold it again.
+
+```tsx
+{/* One-way: the chevron is hidden once expanded */}
+<Text truncate expandable>{longSentence} <a href="/text/#link-behavior">Link guidance</a>.</Text>
+<Text truncate={3} expandable>{longSentence} <a href="/text/#link-behavior">Link guidance</a>.</Text>
+
+{/* Two-way: the reader can collapse it back */}
+<Text truncate={3} expandable collapsible>{longSentence} <a href="/text/#link-behavior">Link guidance</a>.</Text>
+
+{/* Make the folded preview a single expansion target */}
+<Text truncate={3} expandable collapsible expandableInert>{longSentence} <a href="/text/#link-behavior">Link guidance</a>.</Text>
+```
+
+Use `expandableInert` when readers should expand the text before following its
+links. Selecting anywhere in the folded preview expands it; its links become
+available after expansion.
+
+## Component props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `collapsible?` | boolean | — | Allow refolding after expansion. The control stays visible, rotates its chevron, and switches between "Show more" and "Show less". Requires `expandable`. The expanded collapse target spans the full width over 16px of bottom padding; removing that padding with custom CSS allows it to overlap content. |
+| `expandable?` | boolean | — | Show a fade and expansion control when truncated text overflows. Select the control or focus it and press Enter or Space to reveal all content. Expansion is one-way: the control hides once expanded. Add `collapsible` to allow refolding. Requires `truncate`; disables the automatic tooltip. The control comes first in Tab order. By default, folded text stays selectable and its links remain focusable and clickable. Single-line text fades at the inline end with an inline-end target; multiline text fades over its last line with a full-width target. Folded content clips without scrolling or extra padding, and expansion preserves its width. |
+| `expandableInert?` | boolean | — | Make the entire folded, overflowing preview an expand target. JSX applies `inert` to its content, blocking focus, clicks, and text selection and removing it from the accessibility tree until expanded. Fitting text stays interactive, as does server-rendered content before browser measurement. Requires `expandable`. |
+| `inline?` | boolean | — | Render as inline-block instead of the default block element. |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' \| 'quaternary' | secondary | Text emphasis, from `primary` (`--text-1`, strongest) to `quaternary` (`--text-4`). `secondary` uses `--text-2`; `tertiary` uses `--text-3`. Neutral primary/secondary links use `--link-color` and `--link-color-hover`. Tertiary/quaternary links inherit the text color, with `--text-2` and `--text-3` respectively on hover. |
+| `size?` | 'small' \| 'medium' \| 'large' | medium | Font size / line height in pixels: `small` = 13/16, `medium` = 15/20, `large` = 17/24. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Color tint. `neutral` uses `--text-{N}`; named tones use `--text-{N}-{tone}`. A CSS color such as `rebeccapurple` keeps its hue, with lightness and chroma set per priority in oklch. With named tones, links inherit the text color and hover uses the next-stronger tone level; at `primary`, hover changes only the underline. |
+| `truncate?` | boolean \| number | — | Clamp with a trailing ellipsis: `true` or `1` selects one line, integers ≥ 2 select that many lines, and `0` or negative values disable truncation. Clipped, non-expandable Text shows its content in an automatic tooltip. Nest `<Tooltip>` to replace it or an empty tooltip to suppress it. Uses CSS `-webkit-line-clamp` in `display: -webkit-box`, with `min-width: 0` for flex and grid layouts. |
+
+## Web Component
+
+Use `<a-text>` directly for text priority and tone.
+
+```html
+<a-text priority="secondary">
+  Read the <a href="/colors/">color guidance</a>.
+</a-text>
+```
+
 ### Use a tooltip with the web component
 
-`<a-text>` does not add a tooltip. Nest `<a-tooltip truncated-only>` and pass
-the full text as its content:
+Raw Text has no automatic tooltip. Nest `<a-tooltip truncated-only>` with the
+full text:
 
 ```html
 <a-text truncate="1" style="max-width: 260px; cursor: help">
@@ -73,74 +82,89 @@ the full text as its content:
 </a-text>
 ```
 
-`a-text.isTruncated` is a read-only layout measurement. Read it on the UI
-thread when you compose custom truncation behavior.
+Read `a-text.isTruncated` on the UI thread to check whether the clamp hides content.
+This read-only layout measurement does not change markup or accessibility.
 
-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`.
+### Expand raw HTML
 
-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`.
+Place a direct `a-button` before `a-text-content` to put expansion first in Tab
+order. No application toggle handler is needed. Load both entries alongside your
+shared tokens and styles:
 
-```tsx
-{/* One-way: the chevron is removed once expanded */}
-<Text truncate expandable>{longSentence}</Text>
-<Text truncate={3} expandable>{longSentence}</Text>
+```ts
+import '@antadesign/anta/elements/a-text'
+import '@antadesign/anta/elements/a-button'
+```
 
-{/* Two-way: the reader can collapse it back */}
-<Text truncate={3} expandable collapsible>{longSentence}</Text>
+```html
+<a-text truncate="1" expandable collapsible>
+  <a-button role="button" tabindex="0" priority="quaternary" paddingless></a-button>
+  <a-text-content>A long description that needs more than one line.</a-text-content>
+</a-text>
 ```
 
-## Component props
+Expansion and accessible button labels work automatically. Your attributes and
+children stay unchanged. Explicit button ARIA overrides the defaults;
+synchronize any authored `aria-expanded` yourself.
 
-| 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. A clipped, non-expandable JSX `Text` shows its text content in a tooltip by default. Nest a `<Tooltip>` to provide your own tooltip instead. Uses the `-webkit-line-clamp` technique, supported in all major browsers (Firefox 68+, Chrome, Safari, Edge). |
+Migrate flat expandable raw markup to these two children. JSX supplies them for
+you; plain Text needs no content wrapper.
 
-## Web Component
+For multiline raw Text, set `--line-clamp` in your stylesheet. JSX sets the line
+count through the `truncate` prop:
 
-Use the web component directly when you are not using React or Preact and a native control does not fit.
+```html
+<a-text class="summary" truncate="3" expandable collapsible>
+  <a-button role="button" tabindex="0" priority="quaternary" paddingless></a-button>
+  <a-text-content>A longer description to show across three lines.</a-text-content>
+</a-text>
+```
+
+```css
+a-text.summary { --line-clamp: 3; }
+```
 
-Use `<a-text>` directly for a block that carries the text priority and tone.
+### Make folded content inert
+
+Raw authors manage `inert` on `a-text-content`. Add `expandable-inert` for a
+full-preview expand target, and update `inert` from `textpresentationchange`:
 
 ```html
-<a-text priority="secondary">
-  Read the <a href="/colors/">color guidance</a>.
+<a-text id="summary" truncate="1" expandable collapsible expandable-inert>
+  <a-button role="button" tabindex="0" priority="quaternary" paddingless></a-button>
+  <a-text-content>A long description with <a href="/text/">a link</a>.</a-text-content>
 </a-text>
 ```
 
+```js
+const text = document.querySelector('#summary')
+const content = text.querySelector(':scope > a-text-content')
+text.addEventListener('textpresentationchange', ({ detail }) => {
+  content.inert = detail.overflowing && !detail.expanded
+})
+```
+
+This non-bubbling notification reports `{ expanded, overflowing }` after
+measurement or expansion. Late listeners receive the current snapshot
+asynchronously. `overflowing` describes the folded preview, retained while
+expanded. The element leaves `inert` to you.
+
 ## Styling
 
-Color 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 color
-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`.
+Use `priority`, `tone`, and `size` for emphasis, color, and type scale. Shared
+[Colors](../colors.md) keep Text consistent with your theme. For a custom color,
+pass `tone` or set `--text-tone-source`.
 
 ```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:
+Style the light-DOM host, content, control, and links with plain CSS. The `.fancy`
+class belongs to this 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 */
+/* Anta's theme controls color-scheme for light-dark(). */
 a-text.fancy {
   color: light-dark(#0f6e5f, #5fd0bb);
   font-size: 16px;