@antadesign/anta 0.3.28 → 0.3.30

package/docs/components/steps.md

@@ -260,10 +260,10 @@ Events match [`Tabs`](./tabs.md#events).
 | `onStateChange?` | (event, detail) => void | — | Fired whenever the active tab changes — event-first. `detail` is `{ next, prev }` (values; `null` = none). Cancelable: `event.preventDefault()` vetoes it (uncontrolled), or in controlled mode answer by updating `value`. |
 | `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ value }` snapshot as the 2nd argument. |
 | `orientation?` | 'horizontal' \| 'vertical' | 'horizontal' | Layout + arrow-key axis. Horizontal ellipsizes labels when tabs overflow (scroll is opt-in via CSS); vertical stacks them. |
-| `priority?` | StepPriority | 'secondary' | Visual emphasis. Primary uses a solid selected marker and a stronger completed connector; secondary is the outlined default; tertiary is compact and borderless. |
+| `priority?` | 'primary' \| 'secondary' \| 'tertiary' | 'secondary' | Visual emphasis. Primary uses a solid selected marker and a stronger completed connector; secondary is the outlined default; tertiary is compact and borderless. |
 | `renderMarker?` | (option, state) => ReactNode | — | Builds a custom marker from a step and its current state. A returned node replaces `marker` and the built-in state marker; return `undefined` to use those fallbacks, or `null` for an empty ring. |
 | `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?` | StepTone \| '' | 'neutral' | Tone applied to every step without its own `tone`. Error steps stay critical and disabled steps stay neutral. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| '' | 'neutral' | Tone applied to every step without its own `tone`. Error steps stay critical and disabled steps stay neutral. |
 | `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. |
 
 ## Step option props
@@ -271,14 +271,14 @@ Events match [`Tabs`](./tabs.md#events).
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `label` | ReactNode | — | Visible phase label. It ellipsizes in a constrained step; its full content is available in a tooltip only when clipped. |
-| `state` | StepState | — | Application-owned process state. Selection and availability are separate; `error` keeps a critical icon and outline, and selection adds the fill. |
+| `state` | 'incomplete' \| 'loading' \| 'completed' \| 'error' | — | Application-owned process state. Selection and availability are separate; `error` keeps a critical icon and outline, and selection adds the fill. |
 | `value` | string | — | Stable phase identity. Values must be unique within the sequence. |
 | `className?` | string | — | CSS class on the option's rendered row. |
 | `disabled?` | boolean | — | Disables this phase. A custom `marker` or `renderMarker` result is kept; otherwise it uses the incomplete marker. |
 | `hint?` | ReactNode | — | Secondary text shown below the label. It ellipsizes in a constrained step; its full content is available in a tooltip only when clipped. |
 | `marker?` | StepMarker | — | Replaces the marker derived from `state`. A number is shown directly; an Anta icon shape is rendered as an `<Icon>`. |
 | `style?` | CSSProperties | — | Inline styles on the option's rendered row. |
-| `tone?` | StepTone \| '' | inherits Steps `tone | Tone for this phase. It colors the label, hint, marker, and completed connector. Overrides the Steps `tone`; error steps stay critical and disabled steps stay neutral. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| '' | inherits Steps `tone | Tone for this phase. It colors the label, hint, marker, and completed connector. Overrides the Steps `tone`; error steps stay critical and disabled steps stay neutral. |
 
 ## Web Component
 

package/docs/components/switch.md

@@ -6,6 +6,8 @@ The `Switch` wrapper renders a form-associated `<a-switch>` element. It works un
 
 ## Tone
 
+Switch is neutral by default. Pass `tone="brand"` or another tone to color the control.
+
 `tone` colors the whole control: the checked track, plus the unchecked track border and thumb. Six named tones are available, or pass any CSS color for a custom tone. The label and hint stay neutral.
 
 ```tsx
@@ -17,7 +19,7 @@ The `Switch` wrapper renders a form-associated `<a-switch>` element. It works un
 
 ## Selected-only tone
 
-`toneScope="selected"` applies the switch's `tone` to the checked track only. The unchecked track and thumb stay neutral until the switch is on. Use it when a resting tinted control could imply a validation state.
+To apply a tone only while selected, pass `toneScope="selected"` together with `tone`, such as `tone="brand"`. Only the checked track is tinted; the unchecked track border and thumb stay neutral.
 
 ```tsx
 <Switch tone="brand" toneScope="selected" label="Off stays neutral" />
@@ -119,7 +121,10 @@ Use **`onStateChange`** to intercept a toggle or drive a controlled switch. Use
 
 ## Accessibility
 
-The wrapper sets `role="switch"` and keeps `aria-checked` in sync with the current value. It derives the accessible name from `label` or text children. For a label-less switch, pass `aria-label`.
+The wrapper sets `role="switch"`, and the element keeps `aria-checked` in sync
+with the current value. Its light-DOM label supplies the accessible name and its
+hint supplies the accessible description through `ElementInternals`; no generated
+IDs are needed. For a label-less switch, pass `aria-label`.
 
 Space toggles the switch. It follows the [WAI-ARIA switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/).
 
@@ -130,7 +135,7 @@ Space toggles the switch. It follows the [WAI-ARIA switch pattern](https://www.w
 | `checked?` | boolean | — | Controlled checked value. In controlled mode, update this in `onStateChange`. |
 | `defaultChecked?` | boolean | false | Initial checked value for an uncontrolled switch. |
 | `disabled?` | boolean | — | Disables interaction and removes the switch from the tab order. |
-| `hint?` | ReactNode | — | Secondary text rendered under the label. It does not become part of the accessible name. |
+| `hint?` | ReactNode | — | Secondary text rendered under the label and exposed as the switch's accessible description. It does not become part of the accessible name. |
 | `label?` | string | — | Visible, stable label for the setting. Use `children` for richer label content. |
 | `labelPosition?` | 'start' \| 'end' | 'end' | Put the visible label before or after the control. Grid layout changes only the visual order, preserving DOM/source order for assistive technologies. |
 | `name?` | string | — | Form field name. A checked switch submits `value` under this name. |
@@ -139,15 +144,16 @@ Space toggles the switch. It follows the [WAI-ARIA switch pattern](https://www.w
 | `onValueChange?` | (event, attrs) => void | — | Post-apply callback with the new form-relevant value snapshot. |
 | `round?` | boolean \| number \| string | — | Fully round the thumb and track. Pass a `number` (px) or CSS length string for a custom track radius; the thumb radius is 3px smaller. |
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size variant. small=26×16px, medium=30×18px, large=34×20px. |
-| `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'brand' | Color of the track and thumb. A tinted tone also colors the unchecked track border and thumb; use `toneScope="selected"` to color only the checked track. |
-| `toneScope?` | ToneScope | 'all' | Apply `tone` to every state, or only while checked so the unchecked track and thumb stay neutral. |
+| `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color of the track and thumb. A tinted tone also colors the unchecked track border and thumb; use `toneScope="selected"` to color only the checked track. |
+| `toneScope?` | 'all' \| 'selected' | 'all' | Apply `tone` to every state, or only while checked so the unchecked track and thumb stay neutral. |
 | `value?` | string | "on" | Value submitted while checked. |
 
 ## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
-The focusable host carries the state. Label and hint are light-DOM children.
+The focusable host carries the state. Label and hint are light-DOM children that
+the element exposes as its accessible name and description.
 
 ```html
 <a-switch role="switch" tabindex="0" name="updates" default-state="checked">

package/docs/components/tabs.md

@@ -271,15 +271,17 @@ const [tab, setTab] = useState('overview')
 
 ## Keyboard & accessibility
 
-Every enabled tab is in the tab order; `Tab` / `Shift`+`Tab` step through them.
-The arrow keys also move between enabled tabs (wrapping at the ends), `Home` /
+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` /
 `End` jump to the first / last, and `Space` / `Enter` activate the focused tab;
 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.
+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.
 
 ## Routing
 
@@ -357,7 +359,7 @@ so those suit an uncontrolled strip reacting to its own pick. **`onFocus`** /
 | `value` | string | — | This tab's identity — pairs it with the `<TabPanel value="…">` of the same value, and the value reported by `onStateChange` / `onChange`. Unique per strip. |
 | `children?` | ReactNode | — | Tab content when you need more than a string — used if `label` is omitted. |
 | `className?` | string | — | CSS class on the option's rendered row. |
-| `disabled?` | boolean | — | Disable just this tab — skipped by keyboard nav and dropped from the tab order (a disabled-but-selected tab stays reachable, per the ARIA pattern). |
+| `disabled?` | boolean | — | Prevent user activation of this tab. A disabled tab can still indicate the current selection. |
 | `icon?` | IconShape | — | Leading icon shape, rendered before the label. |
 | `iconTrailing?` | IconShape | — | Trailing icon shape, rendered after the label. |
 | `label?` | ReactNode | — | Visible label. The string shorthand for the tab's content; for richer content pass `children` instead (`label` wins when both are set). |
@@ -371,17 +373,18 @@ so those suit an uncontrolled strip reacting to its own pick. **`onFocus`** /
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `value` | string | — | Pairs this panel with the tab (`options` entry) of the same `value`. |
-| `children?` | ReactNode | — | Panel content — arbitrary React/Preact. |
-| `className?` | string | — | CSS class on the rendered `<a-tabpanel>`. |
 | `hideMode?` | 'display' \| 'visibility' | display | How this panel hides while inactive: `display` (default — removed from layout and the a11y tree) or `visibility` (keeps its layout box, to measure it or avoid reflow). Both stay mounted; to *not render* an inactive panel, render it conditionally off a controlled `value` (see the Tabs docs). |
-| `style?` | CSSProperties | — | Inline style on the rendered `<a-tabpanel>`. |
 
 ## Web Component
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
 Keep the tab strip and panels as siblings under one parent. Panels read the active
-value from `<a-tabs>`.
+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
+your change handler updates those attributes for the next visit to the strip. Add
+`tabindex="0"` to a text-only panel only when you want the panel itself in the page
+Tab sequence.
 
 Add `fill` to make horizontal tabs share the available width equally.
 
@@ -396,6 +399,16 @@ Add `fill` to make horizontal tabs share the available width equally.
 </div>
 ```
 
+```js title="Keep the raw DOM tab stop on the selected tab"
+const tabs = document.querySelector('a-tabs')
+
+tabs.addEventListener('change', () => {
+  for (const tab of tabs.querySelectorAll('a-tab')) {
+    tab.tabIndex = tab.getAttribute('value') === tabs.value ? 0 : -1
+  }
+})
+```
+
 ## Styling
 
 Reach for the props first: **`tone`**, **`size`**, **`priority`**. The focus ring is

package/docs/components/tooltip.md

@@ -67,9 +67,11 @@ The underlying `<a-tooltip>` works in plain HTML too, as a child of any element:
 
 ### Adjacent and nested tooltips
 
-Only one tooltip shows at a time. Moving between **adjacent** anchors hands off
-cleanly — the outgoing bubble cross-fades out as the next fades in (no blink).
-With `follow` tooltips (used below to show it), the outgoing bubble also keeps
+Only one tooltip shows at a time. Moving between **adjacent** anchors with
+`follow` tooltips hands off cleanly — the outgoing bubble cross-fades out as the
+next fades in (no blink). If either tooltip does not have `follow`, the next
+tooltip waits for its configured delay. With `follow` tooltips (used below to
+show it), the outgoing bubble also keeps
 trailing the cursor and fades by distance from its anchor (transparent by ~100px
 away), so a near hop reads as a smooth cross-fade and a far one is already gone.
 With **nested** anchors, the inner (descendant) tooltip wins while you're over
@@ -125,7 +127,7 @@ shows.
 | `delay?` | number | 300 | Show delay in milliseconds after hover / focus. Never use `0` — use ~`50` for a near-instant tooltip (0 has caused issues in practice). |
 | `follow?` | boolean | — | Follow the cursor instead of pinning under the anchor. The bubble is pinned (anchored beneath the target) by default; pass `follow` for the cursor-tracking behavior, which fades by distance as the cursor leaves. |
 | `interactive?` | boolean | — | Make the bubble hoverable and clickable — enables pointer events and keeps it open while the cursor is over it, so its content (links, buttons) can be interacted with. Always pinned (an interactive bubble can't follow the cursor, even with `follow`). |
-| `placement?` | 'top' \| 'bottom' | bottom | Which side of the anchor the bubble prefers. Auto-flips to the other side when there isn't room. |
+| `placement?` | 'top' \| 'bottom' \| 'left' | bottom | Which side of the anchor the bubble prefers. Auto-flips to the other side when there isn't room. |
 | `round?` | boolean \| number \| string | — | Round the bubble to a 20px radius (matching a round menu). Pass a `number` (px) or a CSS length string for a custom radius. |
 | `truncatedOnly?` | boolean | — | Only show when the target is actually truncated (its text overflows and is ellipsized); a label that fits gets no tooltip. The check is a UI-thread layout read, re-measured on each show. By default it measures every Anta ellipsizing label part inside the anchor, then the anchor itself — override with `truncatedSelector`. |
 | `truncatedSelector?` | string | — | CSS selector (resolved within the anchor) for the element or elements whose overflow decides whether a `truncatedOnly` tooltip shows. |

package/docs/index.md

@@ -50,8 +50,10 @@ Anta is designed for a clean DOM. Prefer the props and attributes exposed by eac
 
 - [Box](./components/box.md)
 - [Capture](./components/capture.md)
+- [Panel](./components/panel.md)
 
 ## Packages
 
+- [Plot](./packages/plot.md)
 - [Table](./packages/table.md)
 - [Stickers](./packages/stickers.md)

package/docs/install-config.md

@@ -61,8 +61,9 @@ seed-derived default palette or provide your own theme.
 
 ### Cascade layers
 
-Anta's reset and element CSS use child layers inside `@layer anta`. `tokens.css`
-orders them above preflight resets and below your component and utility layers:
+Anta's reset and element CSS use child layers inside `@layer anta`. Every Anta
+stylesheet reserves the same order, so granular stylesheets remain safe when a
+bundler loads them before `tokens.css`:
 
 ```css
 @layer base, anta, components, utilities;
@@ -72,8 +73,8 @@ orders them above preflight resets and below your component and utility layers:
 `anta.theme` lets the optional reference palette replace component formulas. The
 outer `anta` layer keeps its public cascade position.
 
-To change that order, declare it in CSS loaded **before** `tokens.css`. The
-first declaration fixes a layer's position:
+To change that order, declare it in CSS loaded **before any Anta stylesheet**.
+The first declaration fixes a layer's position:
 
 ```css
 /* your global.css, loaded before anta */

package/docs/normalization.md

@@ -57,7 +57,9 @@ See `src/reset.css` for the full set. Heading values are duplicated in
 
 ## Cascade layers — how to override
 
-Anta declares this layer order once (in `tokens.css`):
+Every Anta stylesheet reserves the same layer order before defining its rules.
+This keeps granular imports safe when a bundler loads component CSS before
+`tokens.css`:
 
 ```css
 @layer base, anta, components, utilities;