@antadesign/anta 0.3.30 → 0.3.32

package/docs/components/expander.md

@@ -94,6 +94,43 @@ it's a no-op there. Use it where the expander sits in a content column
 with room to its left (a prose measure); in a full-width / edge-to-edge
 container the chevron would overhang the edge.
 
+## Indicator
+
+`indicatorPlacement="end"` puts the disclosure mark after the header actions.
+The mark stays inside the summary button, so selecting it toggles the section.
+Actions remain separate controls. The default `start` placement keeps the
+right-pointing chevron that turns down when open. At the end, it points down
+when closed and up when open.
+
+Choose `indicator="triangle"` for a filled arrow or `indicator="plus"` for a
+plus that becomes a minus. The default is `chevron`. The built-in motion follows
+the reduced-motion preference. An unrecognized string or number leaves the
+indicator empty; omit `indicator` to keep the default chevron.
+
+```tsx
+<Expander title="Download report" indicatorPlacement="end"
+  actions={<Button size="small" label="Download" />}>
+  …
+</Expander>
+<Expander title="Plus and minus" indicator="plus" indicatorPlacement="end">…</Expander>
+```
+
+Pass a decorative node as `indicator` to replace the built-in mark. One node
+rotates with the section. To switch between two visuals, pass `closed` and
+`open` nodes. Neither form adds a focus stop or an accessible name: the title
+names the summary button, and its `aria-expanded` reports the state. Put
+interactive controls in `actions`.
+
+```tsx
+<Expander title="Custom mark" indicatorPlacement="end"
+  indicator={<Icon shape="chevron-down" />}>…</Expander>
+<Expander title="Two marks" indicatorPlacement="end"
+  indicator={{ closed: <Icon shape="plus" />, open: <Icon shape="minus" /> }}>…</Expander>
+```
+
+On a tertiary end-placement expander, `outdent` still aligns the title and body
+with surrounding content. The indicator stays inside the end edge.
+
 ## Title and level
 
 `title` takes a string or any node. For a string, `level` (1–6) applies
@@ -168,10 +205,10 @@ toggle:
 
 ## Actions
 
-Pass `actions` to render extra controls — buttons, tags — at the end of
-the header row. They sit **outside** the toggle trigger, as its flex
-siblings: clicking them never toggles the expander, they're separately
-focusable, and screen readers announce them as their own controls.
+Pass `actions` to render extra controls — buttons, tags — after the title.
+They sit **outside** the toggle trigger as its header siblings. Clicking them
+never toggles the expander; they're separately focusable and announced as
+their own controls.
 (Don't put interactive elements *inside* a custom `title` instead —
 nesting controls in a button is an accessibility anti-pattern.)
 
@@ -309,13 +346,15 @@ function Accordion() {
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `title` | ReactNode | — | Summary (header) content. A string is rendered with the `level` type scale; pass a node (e.g. a `<Title>`) for full control or real heading semantics in the document outline. |
-| `actions?` | ReactNode | — | Header actions (e.g. buttons, tags) rendered at the end of the header row, OUTSIDE the toggle trigger — clicking them never toggles, they're separately focusable, and screen readers see them as separate controls. |
+| `actions?` | ReactNode | — | Header actions rendered outside the toggle trigger. With an end indicator, actions sit between the title and indicator. |
 | `defaultOpen?` | boolean | — | Initial open state for the uncontrolled case. |
 | `disabled?` | boolean | — | Disables the header: not clickable or focusable, hover affordance off, text dimmed. The open state freezes as-is — disabling an open expander keeps it open. `actions` stay live; disable them separately if needed. |
+| `indicator?` | ReactNode | 'chevron' | Built-in disclosure mark, a decorative node, or separate closed/open visuals. Other primitive values leave the indicator empty. Custom nodes are passive; use `actions` for controls. |
+| `indicatorPlacement?` | 'start' \| 'end' | 'start' | Place the disclosure mark before the title or after the actions. |
 | `level?` | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | 5 | Heading type scale applied to a string `title` (mirrors `<Title>`'s levels). Visual only — for outline semantics, pass a `<Title>` as the title. |
 | `onStateChange?` | (event, detail) => void | — | Fired before the open state changes. `event` is the cancelable `statechange` — call `event.preventDefault()` to veto an *uncontrolled* toggle (e.g. confirm before closing). `detail.next` is the requested open state, `detail.prev` the current one (booleans). In controlled mode, apply `detail.next` to `open` to accept, or do nothing to reject. |
 | `open?` | boolean | — | Controlled open state. When provided, the consumer owns open/close. Selecting the summary requests a change through `onStateChange`; omit `open` for uncontrolled use. |
-| `outdent?` | boolean | — | Outdent the chevron into the left gutter so the title and body sit flush with surrounding content (the docs-header layout). Only takes effect with `priority="tertiary"` — on the filled priorities the container edge has to bound the chevron, so it's a no-op there. |
+| `outdent?` | boolean | — | Align the title and body with surrounding content on a tertiary expander. With the default start indicator, the mark hangs in the gutter; an end indicator stays inside its edge. |
 | `priority?` | 'primary' \| 'secondary' \| 'tertiary' | 'secondary' | Surface emphasis. `secondary` (the default) is a subtle fill; `primary` is a more pronounced card; `tertiary` is transparent (the bare disclosure). |
 | `round?` | boolean \| number \| string | — | Round corners sized to half the folded (header) height: a pill when folded, and — when expanded — the same corner radius rather than a bigger stadium. The element measures the header, so it tracks custom header content. Pass a `number` (px) or CSS length string for a *fixed* radius that overrides the measurement (and skips it) in both states. |
 | `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone. Named tones re-point the text and (on filled priorities) the surface to the matching palette; a custom color keeps its hue while lightness/chroma are pinned. `'neutral'` (the default) is the same as omitting it. |
@@ -324,7 +363,8 @@ function Accordion() {
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
-Slots hold the title and actions. The details element contains the collapsible body.
+Slots hold the title, actions, and an optional custom indicator. The details
+element contains the collapsible body.
 
 ```html
 <a-expander default-state="open">
@@ -336,6 +376,29 @@ Slots hold the title and actions. The details element contains the collapsible b
 </a-expander>
 ```
 
+Use the `indicator` and `indicator-placement` attributes for built-in marks.
+For custom artwork, assign one element to `slot="indicator"`. Assign two
+elements with `data-when="closed"` and `data-when="open"` when the artwork
+changes between states. Indicator content is decorative and cannot receive focus
+or pointer events.
+
+```html
+<a-expander indicator="triangle" indicator-placement="end">…</a-expander>
+
+<a-expander indicator-placement="end">
+  <a-expander-summary slot="title">Custom mark</a-expander-summary>
+  <a-icon slot="indicator" shape="chevron-down" aria-hidden="true" inert></a-icon>
+  <a-expander-details>Content</a-expander-details>
+</a-expander>
+
+<a-expander indicator-placement="end">
+  <a-expander-summary slot="title">Two marks</a-expander-summary>
+  <a-icon slot="indicator" data-when="closed" shape="plus" aria-hidden="true" inert></a-icon>
+  <a-icon slot="indicator" data-when="open" shape="minus" aria-hidden="true" inert></a-icon>
+  <a-expander-details>Content</a-expander-details>
+</a-expander>
+```
+
 ### Native HTML details
 
 For a simple disclosure, add `data-anta` to native `<details>`. It keeps the
@@ -358,18 +421,18 @@ Reach for the props first: **`tone`** sets the color (any CSS color for a custom
 tone — it derives the surface in oklch), **`priority`** the fill, **`level`** the
 heading. Two knobs are worth keeping: **`--expander-tone-source`** (the color a
 custom `tone` derives from — set it to drive the palette from your own variable) and
-**`--expander-gutter`** (the shared left inset that re-insets header + body + chevron
-in lockstep; `outdent` sets it to `0`).
+**`--expander-gutter`** (the shared title and body inset; it also positions the
+start indicator). It is 24px at the start, 12px at the end, and `0` with tertiary
+`outdent`.
 
 ```tsx
 <Expander tone="#e0457b" title="Custom" />
 ```
 
 For everything else, `<a-expander>` exposes shadow **parts** — `::part(summary)` (the
-header button), `::part(content)` (the body), `::part(actions)` (the actions row) — and
-the light-DOM `<a-expander-summary>` / `<a-expander-details>` children, which you style
-directly. The header hover / active / focus states and the chevron all live on
-`::part(summary)`.
+header button), `::part(indicator)` (the decorative mark), `::part(content)` (the
+body), and `::part(actions)` (the actions row) — and the light-DOM
+`<a-expander-summary>` / `<a-expander-details>` children, which you style directly.
 
 Each example keeps its CSS in a `<style>` **inside** its own preview, targeting a demo
 class on that preview's expander (e.g. `.hide-chevron`) — so the rule you read is
@@ -377,25 +440,19 @@ literally in the preview's DOM, next to the element it styles, never a page-wide
 stylesheet. The folded recipe under each preview is that same CSS; in your app, swap the
 demo class for your own selector.
 
-**Hide the chevron.** There's deliberately no prop for it: a region that folds needs a
-visible affordance. For a genuine one-off, the chevron is the summary's `::before`, so
-remove it — then pull `--expander-gutter` in (it drives the title *and* body inset
-together) to tighten the now-empty gutter, and drop your own marker into the title:
+**Hide the indicator.** A disclosure needs a visible affordance. If the title
+provides one, hide the indicator part and tighten the unused gutter:
 
 ```css
-a-expander.hide-chevron::part(summary)::before { display: none; }  /* remove the built-in chevron */
+a-expander.hide-chevron::part(indicator) { display: none; }
 a-expander.hide-chevron { --expander-gutter: 12px; }               /* tighten the inset (default 24px) */
 ```
 
-**Swap the chevron glyph.** It's a CSS mask, so point `mask-image` at your own SVG; it
-keeps its gutter position and the open-state rotation:
+**Change the indicator.** Use the built-in `triangle` or `plus` preset, or
+provide a custom node through `indicator` / `slot="indicator"`:
 
-```css
-/* the chevron is the summary's ::before with a mask-image; swap the glyph for a
-   solid triangle — it keeps its position and the open-state rotate */
-a-expander.swap-chevron::part(summary)::before {
-  mask-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M8 5l11 7-11 7z'/%3E%3C/svg%3E");
-}
+```tsx
+<Expander title="Triangle indicator" indicator="triangle" priority="tertiary">…</Expander>
 ```
 
 **Tint the whole header** on hover / press by styling the summary part (the header
@@ -473,29 +530,13 @@ export function SaveButton() {
 `}</style>
 ```
 
-*A chevron as a status indicator* — drop the built-in toggle chevron and put a
-**non-interactive** chevron in `actions` instead. The whole header still toggles; the
-indicator only reflects state, rotating via `:state(open)`. With the `<Expander>` JSX
-wrapper, pass `actions={<Icon shape="chevron-down" />}` (the preview below uses the
-equivalent element composition because these docs render statically):
+*Style the indicator by state* with `:state(open)` and `::part(indicator)`. The
+example changes its color without changing the built-in glyph or motion:
 
 ```tsx
-{/* renders an <a-expander> whose only header control is a non-interactive
-    chevron in the actions slot; the whole header toggles, the chevron flips */}
-<Expander actions={<Icon shape="chevron-down" />} className="indicator" defaultOpen>
-  Build log
-</Expander>
-
-{/* the JSX wrapper boxes the icon in a layout-neutral span, so target the
-    [slot="actions"] element */}
+<Expander title="Build log" indicatorPlacement="end" className="indicator" defaultOpen>…</Expander>
 <style>{`
-  a-expander.indicator { --expander-gutter: 12px; }                /* one var: title + body inset */
-  a-expander.indicator::part(summary)::before { display: none; }   /* drop the built-in chevron */
-  a-expander.indicator [slot="actions"] {
-    pointer-events: none;
-    margin-inline-end: 6px;                                        /* a little more right inset */
-    transition: transform 150ms ease;
-  }
-  a-expander.indicator:state(open) [slot="actions"] { transform: rotate(180deg); }  /* points down → up */
+  a-expander.indicator::part(indicator) { color: var(--text-4); }
+  a-expander.indicator:state(open)::part(indicator) { color: var(--text-1); }
 `}</style>
 ```

package/docs/components/menu.md

@@ -328,13 +328,13 @@ menus: mark one row for single-select, several for multi-select (pair with
 `data-menu-open` to keep the menu open as choices toggle). The tint tracks
 `tone`, so a toned row stays in its own color.
 
-For a real checkable row, add **`selectionIndicator`** (`'checkbox'` or `'radio'`).
-It renders a passive checkbox/radio at the leading edge (reusing the
-[Checkbox](./checkbox.md) / [Radio](./radio.md) element visuals),
-flips the row to `role="menuitemcheckbox"` / `"menuitemradio"`, and pairs
-`aria-checked` — the row stays the control, the indicator is decorative. This is
-what [Select](./select.md)'s `selection` modes render; use it directly for
-a checkable menu.
+For a checkable row, add `selectionIndicator`. The `checkbox` and `radio`
+variants render a passive leading mark. The `switch` variant renders a passive
+trailing switch for settings that take effect immediately. The
+row remains the control and carries `aria-checked`; the indicator adds no focus
+stop or nested role. A switch row keeps the menu open when selected.
+
+[Select](./select.md)'s selection modes use the checkbox and radio variants.
 
 ```tsx
 {/* Plain tint (no indicator) */}
@@ -345,6 +345,28 @@ a checkable menu.
 <MenuItem selectionIndicator="checkbox" label="Show archived" selected data-menu-open />
 ```
 
+```tsx
+const [notifications, setNotifications] = useState(true)
+const [automaticUpdates, setAutomaticUpdates] = useState(false)
+
+<Button>Settings</Button>
+<Menu>
+  <MenuItem
+    selectionIndicator="switch"
+    label="Notifications"
+    selected={notifications}
+    onSelect={() => setNotifications((value) => !value)}
+  />
+  <MenuItem
+    selectionIndicator="switch"
+    label="Automatic updates"
+    hint="Install new versions automatically"
+    selected={automaticUpdates}
+    onSelect={() => setAutomaticUpdates((value) => !value)}
+  />
+</Menu>
+```
+
 ## Badges, counters, and hints
 
 Drop a `<Tag>` (or any element) as a **child** of a `MenuItem` for a trailing
@@ -411,11 +433,11 @@ navigating links.
 | `onMouseDown?` | (event) => void | — | Raw `mousedown` on the row. Mainly to `preventDefault()` so the row doesn't take focus on a mouse press — e.g. a combobox option keeping focus in its input field while the click still selects. |
 | `onSelect?` | (event, detail) => void | — | Activation handler — fires when *this* item is chosen (click / Enter / Space), unless it's `disabled`. It does **not** fire for a submenu parent (clicking that opens the flyout, which isn't a selection) nor for a selection bubbling up from a nested submenu. On a link item it fires alongside the navigation. Receives the event plus a `{ value, label }` detail. |
 | `role?` | string | — | ARIA role override. Defaults to the role implied by `selectionIndicator` (`menuitem` / `menuitemcheckbox` / `menuitemradio`); set it to reparent the row under a different container role — e.g. `option` inside a `listbox`. |
-| `selected?` | boolean | — | Mark the item as selected. On a plain row (no `selectionIndicator`) this is a persistent background tint, the same resting fill a pressed row shows — also the way to flag the current page on a link item. On a checkable row (`selectionIndicator` set) it instead drives the leading `checkbox` / `radio` indicator and the row's `aria-checked`. |
-| `selectionIndicator?` | 'checkbox' \| 'radio' \| 'check' | — | Turn the row into a checkable item, driven by `selected` (the row stays the control and carries `aria-checked`): - `'checkbox'` → `role="menuitemcheckbox"`, a leading passive `<a-checkbox>` (before `icon`); the tint is dropped (the box carries state). - `'radio'` → `role="menuitemradio"`, a leading passive `<a-radio>`; tint dropped. - `'check'` → `role="menuitemradio"`, a trailing check glyph on the selected row *and* the background tint (the canonical single-select look). Omit for a plain row (the default). |
+| `selected?` | boolean | — | Mark the item as selected. On a plain row (no `selectionIndicator`) this is a persistent background tint, the same resting fill a pressed row shows — also the way to flag the current page on a link item. On a checkable row (`selectionIndicator` set) it instead drives the indicator and the row's `aria-checked`. |
+| `selectionIndicator?` | 'checkbox' \| 'radio' \| 'check' \| 'switch' | — | Turn the row into a checkable item, driven by `selected` (the row stays the control and carries `aria-checked`): - `'checkbox'` → `role="menuitemcheckbox"`, a leading passive `<a-checkbox>` (before `icon`); the tint is dropped (the box carries state). - `'radio'` → `role="menuitemradio"`, a leading passive `<a-radio>`; tint dropped. - `'check'` → `role="menuitemradio"`, a trailing check glyph on the selected row *and* the background tint (the canonical single-select look). - `'switch'` → `role="menuitemcheckbox"`, a trailing passive `<a-switch>`; selecting the row keeps its menu open. Omit for a plain row (the default). |
 | `submenu?` | boolean | — | Marks this item as a submenu parent: adds the trailing chevron and `aria-haspopup="menu"`. Nest the flyout as a `<Menu>` child. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone — colors the label, icon, and hover/selected tint (and the `checkbox`/`radio` indicator, which adopts it). A named tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose hue + chroma are kept while the lightness is pinned to match the brand text. `critical` is the destructive action; `neutral` (the default) is the standard gray. |
-| `toneScope?` | 'all' \| 'selected' | 'all' | Apply `tone` to every row state, or only while the row is selected. In `selected` scope, an unselected row and its checkbox/radio indicator stay neutral. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone — colors the label, icon, hover/selected tint, and selection indicator. A named tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose hue + chroma are kept while the lightness is pinned to match the brand text. `critical` is the destructive action; `neutral` (the default) is the standard gray. |
+| `toneScope?` | 'all' \| 'selected' | 'all' | Apply `tone` to every row state, or only while the row is selected. In `selected` scope, an unselected row and its indicator stay neutral. |
 | `value?` | string \| number | — | An opaque value identifying this item, handed back in `onSelect`'s detail so a shared handler can tell which row was chosen without a per-item closure. |
 
 ## Keyboard
@@ -489,12 +511,12 @@ or do nothing to reject. (Submenus are always uncontrolled, regardless of `open`
 | `ping?` | string | — | Space-separated URLs the browser pings on navigation. |
 | `rel?` | string | — | Anchor rel. |
 | `role?` | string | — | ARIA role override. Defaults to the role implied by `selectionIndicator` (`menuitem` / `menuitemcheckbox` / `menuitemradio`); set it to reparent the row under a different container role — e.g. `option` inside a `listbox`. |
-| `selected?` | boolean | — | Mark the item as selected. On a plain row (no `selectionIndicator`) this is a persistent background tint, the same resting fill a pressed row shows — also the way to flag the current page on a link item. On a checkable row (`selectionIndicator` set) it instead drives the leading `checkbox` / `radio` indicator and the row's `aria-checked`. |
-| `selectionIndicator?` | 'checkbox' \| 'radio' \| 'check' | — | Turn the row into a checkable item, driven by `selected` (the row stays the control and carries `aria-checked`): - `'checkbox'` → `role="menuitemcheckbox"`, a leading passive `<a-checkbox>` (before `icon`); the tint is dropped (the box carries state). - `'radio'` → `role="menuitemradio"`, a leading passive `<a-radio>`; tint dropped. - `'check'` → `role="menuitemradio"`, a trailing check glyph on the selected row *and* the background tint (the canonical single-select look). Omit for a plain row (the default). |
+| `selected?` | boolean | — | Mark the item as selected. On a plain row (no `selectionIndicator`) this is a persistent background tint, the same resting fill a pressed row shows — also the way to flag the current page on a link item. On a checkable row (`selectionIndicator` set) it instead drives the indicator and the row's `aria-checked`. |
+| `selectionIndicator?` | 'checkbox' \| 'radio' \| 'check' \| 'switch' | — | Turn the row into a checkable item, driven by `selected` (the row stays the control and carries `aria-checked`): - `'checkbox'` → `role="menuitemcheckbox"`, a leading passive `<a-checkbox>` (before `icon`); the tint is dropped (the box carries state). - `'radio'` → `role="menuitemradio"`, a leading passive `<a-radio>`; tint dropped. - `'check'` → `role="menuitemradio"`, a trailing check glyph on the selected row *and* the background tint (the canonical single-select look). - `'switch'` → `role="menuitemcheckbox"`, a trailing passive `<a-switch>`; selecting the row keeps its menu open. Omit for a plain row (the default). |
 | `submenu?` | boolean | — | Marks this item as a submenu parent: adds the trailing chevron and `aria-haspopup="menu"`. Nest the flyout as a `<Menu>` child. |
 | `target?` | string | — | Anchor target, e.g. `'_blank'`. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone — colors the label, icon, and hover/selected tint (and the `checkbox`/`radio` indicator, which adopts it). A named tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose hue + chroma are kept while the lightness is pinned to match the brand text. `critical` is the destructive action; `neutral` (the default) is the standard gray. |
-| `toneScope?` | 'all' \| 'selected' | 'all' | Apply `tone` to every row state, or only while the row is selected. In `selected` scope, an unselected row and its checkbox/radio indicator stay neutral. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | neutral | Semantic tone — colors the label, icon, hover/selected tint, and selection indicator. A named tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose hue + chroma are kept while the lightness is pinned to match the brand text. `critical` is the destructive action; `neutral` (the default) is the standard gray. |
+| `toneScope?` | 'all' \| 'selected' | 'all' | Apply `tone` to every row state, or only while the row is selected. In `selected` scope, an unselected row and its indicator stay neutral. |
 | `value?` | string \| number | — | An opaque value identifying this item, handed back in `onSelect`'s detail so a shared handler can tell which row was chosen without a per-item closure. |
 
 ## Web Component

package/docs/components/panel.md

@@ -2,7 +2,7 @@
 
 `Panel` is a container that can maximize to the browser viewport without moving
 or remounting its children. It fills its parent's width and height and uses
-`overflow: scroll` by default.
+`overflow: auto` to show scrollbars only when content overflows.
 
 Give the parent a defined height for Panel to fill vertically. With an
 auto-height parent, percentage height follows normal CSS sizing and the Panel
@@ -138,20 +138,19 @@ Anta buttons can send `panelmaximizerequest`, `panelrestorerequest`, or
 ## Styling
 
 Panel defaults to `display: block`, `width: 100%`, `height: 100%`,
-`box-sizing: border-box`, and `overflow: scroll`. Padding and borders stay inside
+`box-sizing: border-box`, and `overflow: auto`. Padding and borders stay inside
 its assigned size. It does not set `flex-grow`.
 
 Override these through ordinary CSS. Use `height: auto` for content-driven
-height or `overflow: auto` for scrollbars only when content overflows.
-With `overflow: scroll`, scrollbar visibility and reserved space follow the
-browser and operating system's scrollbar settings.
+height or `overflow: scroll` to request scrollbars even when content fits.
+Scrollbar appearance follows the browser and operating system's settings.
 
 Set the background on Panel. Its maximized surface inherits that background,
 so inner content can keep its natural height. Style light-DOM children, such as
 [Box](./box.md) or [Capture](./capture.md), for content layout shared between both states.
 Use `:state(maximized)` for viewport styling and `::part(content)` for the
 maximized scrolling surface. In normal mode, the content slot uses `display: contents`.
-The maximized surface also uses `overflow: scroll`; override
+The maximized surface also uses `overflow: auto`; override
 `::part(content)` to change its overflow separately from the normal Panel.
 
 Enter a note, then select **Maximize panel** and **Restore panel**. The input

package/docs/components/select-faceted.md

@@ -28,12 +28,21 @@ is limited. `offset` sets the gap in pixels between the trigger and the menu:
 <SelectFaceted placement="top-end" offset={8} facets={FACETS} />
 ```
 
-Open **Metadata** in the first demo to choose key–value tags such as
+Open **Recency** in the first demo, select **Custom range**, then pick **From**
+and **To** from the fields side by side. Each field closes its own calendar after
+a pick while the Recency editor stays open for the second date.
+
+Open **Metadata** to choose key–value tags such as
 **env production** or **region us-east**. Its `renderOption` callback reads
 custom option fields and renders a `Tag` with `label` and `value`. Search
 for **production** to see the same tag in global results.
 
 ```tsx
+const recencySummary = (v) =>
+  'preset' in v
+    ? { today: 'Today', yesterday: 'Yesterday', last14: 'Last 14 days', last30: 'Last 30 days' }[v.preset]
+    : v.from && v.to ? `${v.from} → ${v.to}` : 'Custom range'
+
 const FACETS = [
   { key: 'assignee', label: 'Assignee', kind: 'multiple', filter: true, options: people },
   { key: 'owner',    label: 'Owner',    kind: 'single',   filter: true, options: people },
@@ -56,6 +65,7 @@ const FACETS = [
   },
   { key: 'title',    label: 'Title contains', kind: 'text' },
   { key: 'duration', label: 'Min duration', kind: 'custom', summary: (v) => `≥ ${v.min}s`, render: /* … */ },
+  { key: 'recency',  label: 'Recency', kind: 'custom', summary: recencySummary, render: /* radio presets and two InputDate fields */ },
 ]
 
 const isSet = (v) => !(v == null || v === '' || (Array.isArray(v) && v.length === 0))
@@ -83,8 +93,7 @@ function Demo() {
 
       {active.length > 0 && (
         <div style={{ display: 'flex', flexDirection: 'row', flexWrap: 'wrap', gap: 8, alignItems: 'center' }}>
-          {/* Show one editable control for each active facet. Its label becomes
-              the control's `leading` prefix. */}
+          {/* Show an editable control or summary for each active facet. */}
           {active.map((facet) => {
             // Options facets → an editable Select (single shows the trailing check;
             // both are filterable + have a clearable footer).
@@ -106,7 +115,12 @@ function Demo() {
                 />
               )
 
-            // Free-form text / custom → an editable Input.
+            if (facet.key === 'recency') {
+              const recency = value.recency
+              return <Tag key={facet.key} label="Recency" value={recencySummary(recency)} />
+            }
+
+            // Free-form text / duration → an editable Input.
             const val = facet.kind === 'text' ? value[facet.key] : value[facet.key]?.min
             const write = (raw) =>
               setFacet(facet.key, facet.kind === 'text' ? raw || undefined : raw ? { min: raw } : undefined)
@@ -144,9 +158,9 @@ function Demo() {
 }
 ```
 
-The trigger opens the facet menu. The example renders one editable
-[Select](./select.md) below it for each active facet. Each Select receives the
-facet label through `leading`, which displays it as a prefix.
+The trigger opens the facet menu. The example shows active values beside it.
+Option facets use an editable [Select](./select.md) with the facet label in its
+`leading` prefix. Recency uses a summary tag and is edited in the facet menu.
 
 ### Custom option content
 
@@ -300,7 +314,7 @@ A custom facet stores a `Date` directly. Unlike the value of a `single` or
 #### A recency filter: presets plus a range
 
 This editor combines a `RadioGroup` of presets with a **Custom range** option
-that reveals two `InputDate` fields. Its value is either `{ preset }` or
+that reveals two `InputDate` fields side by side. Its value is either `{ preset }` or
 `{ from, to }`. The `resolveRange` helper converts either shape into the date
 range used to filter the result set. Each InputDate calendar opens above the
 facet menu without closing it.
@@ -332,7 +346,7 @@ const recency: SelectFacetCustom<Recency> = {
     const mode = value == null ? '' : 'preset' in value ? value.preset : 'custom'
     const range = value && 'from' in value ? value : { from: '', to: '' }
     return (
-      <div style={{ display: 'grid', gap: 8 }}>
+      <div style={{ display: 'grid', gap: 8, minWidth: 360 }}>
         <RadioGroup
           size="small"
           options={PRESETS}                       // Today / Yesterday / Last 14 / Last 30 / Custom range
@@ -342,12 +356,12 @@ const recency: SelectFacetCustom<Recency> = {
           onStateChange={(_e, { next }) => onChange(next === 'custom' ? range : { preset: next })}
         />
         {mode === 'custom' && (
-          <>
+          <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, minmax(0, 1fr))', gap: 8 }}>
             <InputDate size="small" label="From" value={range.from}
               onValueChange={(from) => onChange({ from, to: range.to })} />
             <InputDate size="small" label="To" value={range.to} min={range.from || undefined}
               onValueChange={(to) => onChange({ from: range.from, to })} />
-          </>
+          </div>
         )}
       </div>
     )

package/docs/components/title.md

@@ -38,6 +38,24 @@ the title text.
 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.
 
+## Truncation
+
+Pass `truncate` for a single-line ellipsis or a positive number to clamp to that
+many lines. When the title is clipped, JSX `Title` shows its full text in a
+tooltip. A nested `<Tooltip>` overrides that automatic tooltip.
+
+```tsx
+<Title truncate style={{ maxWidth: '320px' }}>
+  A long workspace heading that stays on one line in a compact layout
+</Title>
+```
+
+Use a number for multi-line titles.
+
+```tsx
+<Title truncate={2}>A long heading clamped after its second line</Title>
+```
+
 ## Level reference
 
 | level | font-size | line-height |
@@ -100,6 +118,7 @@ scale.
 | `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. |
+| `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
 

package/docs/credits.md

@@ -6,6 +6,7 @@
 - Ksenia Toloknova — lead designer
 - Leonid Kniazev — contributing designer
 - Vehbi Karaagac — engineer
+- Fernando Oliveros — engineer, leading the [Plot package](./packages/plot.md)
 
 ## Icons
 
@@ -16,3 +17,5 @@ Anta's icon set is built on the shoulders of several excellent open-source icon
 - Blueprint by Palantir — additional product-UI glyphs covering domains the previous two don't (Apache License 2.0).
 
 Full license texts and per-icon attribution are reproduced verbatim in the package's NOTICES.md.
+
+The Antithesis theme uses Hugeicons. These icons are licensed only for use by Antithesis.