@antadesign/anta 0.3.31 → 0.3.32

package/docs/components/box.md

@@ -10,6 +10,10 @@ pixels; strings accept CSS lengths. `padding` and `margin` also accept CSS
 shorthand, such as `padding="8px 16px"` or `margin="0 auto"`. Omission adds no
 spacing styles. A bare `round` fully rounds the corners.
 
+Box uses `position: relative` by default. Absolutely positioned descendants
+use it as their containing block. Set `position: static` on the Box if they
+should use another positioned ancestor.
+
 ```tsx
 <Box round={8} padding={10}><span /></Box>
 <Box display="flex" round={8} gap={6} padding={10}><span /></Box>
@@ -44,8 +48,10 @@ edges hide content while scrolling. `fade` enables both automatically.
 
 ### Fading a clipped edge
 
-`fade` masks edges with hidden content and removes the mask as scrolling reveals
-them. `fadeSize` sets its depth. It measures on connection, even off screen.
+`fade` masks edges with hidden content and eases the mask as scrolling reveals
+them. The mask is removed after the last edge fades out, preserving shadows and
+focus rings at rest. `fadeSize` sets its depth. It measures on connection, even
+off screen.
 
 ```tsx
 const TAGS = ['frontend', 'design-system', 'a11y', 'performance']
@@ -64,8 +70,9 @@ const TAGS = ['frontend', 'design-system', 'a11y', 'performance']
 .fade-demo a-tag { flex: 0 0 auto; }
 ```
 
-The mask clips to the padding box. It preserves the Box border, shadows, and
-focus ring when no edge is hidden.
+The fade affects the padding box. The mask remains through its exit transition,
+then disappears so shadows and focus rings are visible at rest. The easing is
+disabled when reduced motion is requested.
 
 To style hidden edges without `fade`, use `observe="edges"` and the
 `hidden-start-x`, `hidden-end-x`, `hidden-start-y`, or `hidden-end-y` CSS states.
@@ -91,9 +98,14 @@ const TAGS = ['frontend', 'design-system', 'a11y', 'performance']
 ## Measurements
 
 By default, `onMeasureChange` reports one frame after observation starts, then when
-the border-box `width` or `height` changes. `changed` contains all fields changed
-since the last event; `current` is the full snapshot. Reporting pauses off screen
-and resumes with a fresh snapshot when Box returns.
+the border-box `width` or `height` changes. `changed` contains fields
+changed since the last event; `current` is the full snapshot. Reporting pauses
+off screen and resumes with a fresh snapshot when Box returns.
+
+Pass `observeOffscreen` when a virtualized layout needs measurement events or
+clipping states while the Box is outside the viewport. It keeps the selected
+observers active. Use `throttle` to limit reads when offscreen content changes
+often.
 
 `observe` accepts one of the eight selections below, or a typed array combining
 them. `observe={['size', 'edges']}` and `observe={['edges', 'size']}` select the
@@ -134,19 +146,35 @@ When no measurement is selected, `onMeasureChange` adds `size`;
 Passing both handlers observes size and context without enabling scroll events.
 Without handlers or `fade`, omitting `observe` keeps Box idle.
 
-Set `throttle` to a minimum interval in milliseconds. The first report has no
-added delay; subsequent reports include a trailing update with the latest values.
-Omit it or pass `0` for frame-based reporting. Negative or non-finite values use
-`0`. The interval applies to `onMeasureChange`; context events are not throttled.
-Throttling limits event delivery; it does not reduce observer reads.
-`edges`, `scroll`, and `fade` continue measuring during scrolling so their
-CSS states remain current.
+Set `throttle` to a minimum interval in milliseconds. The initial measurement
+is immediate; later activity gets a trailing read with the latest values. Omit
+it or pass `0` for frame-based updates. Negative or non-finite values use `0`.
+The interval limits measurement reads, CSS state updates, and
+`onMeasureChange` events; context events are not throttled. The
+`box.measurement` getter still reads fresh values on demand.
 
 `Tooltip truncatedOnly` reads Box's clipping on demand. It works without
 `observe` or `onMeasureChange` and does not enable continuous observation.
 
-This readout observes `['size', 'overflow', 'edges', 'scroll']` with `throttle={100}`.
-Resize or scroll the Box to update it.
+Pass `includeRectsFor` to add matching descendants to each measurement snapshot.
+`current.rects` contains their border boxes in document order, with `top`,
+`left`, `right`, and `bottom` measured from the Box's top-left border edge, plus
+each match's `width` and `height`.
+
+The selector does not start observation or add event triggers. Box reads the
+rects when an existing `observe` selection reports a change. `current.rects`
+always contains the latest array; `changed.rects` appears only when that array
+differs from the previous report. For a fresh read at any time, use
+`box.measurement.rects`.
+
+With `observe="scroll"` and no throttle, Box can query, measure, and compare
+every matching descendant on each reported frame. Keep the selector focused or
+set `throttle` when many descendants match. A larger interval also delays the
+fade as the reader reaches an edge.
+
+This readout observes `['size', 'overflow', 'edges', 'scroll']` with `throttle={100}`
+and `fade`. It includes the first content row in `rects`. Resize or scroll the
+Box to update the values and edge mask.
 
 ```tsx title="measurechange"
 const [measurement, setMeasurement] = useState<BoxMeasurement | null>(null)
@@ -155,19 +183,25 @@ const [measurement, setMeasurement] = useState<BoxMeasurement | null>(null)
   round={8}
   className="measure-probe-box"
   observe={['size', 'overflow', 'edges', 'scroll']}
+  fade
+  includeRectsFor=".measure-probe-target"
   throttle={100}
   onMeasureChange={(_, { current }) => setMeasurement(current)}
 >
   <Text size="small" priority="tertiary">Resize or scroll this Box.</Text>
-  <div className="measure-probe-wide">wide content, so both axes overflow</div>
+  <div className="measure-probe-wide measure-probe-target">wide content, so both axes overflow</div>
   <div className="measure-probe-wide">and a second line, so the vertical axis does too</div>
   <div className="measure-probe-wide">and a third</div>
 </Box>
 
 <div className="measure-probe-readout">
-  {Object.entries(measurement ?? {}).map(([field, value]) => (
-    <Tag key={field} size="small" label={field} value={String(value)} />
-  ))}
+  {Object.entries(measurement ?? {}).map(([field, value]) => field === 'rects' && Array.isArray(value)
+    ? <div key={field} className="measure-probe-rects">
+        <Tag size="small" label="rects" value={`${value.length} match${value.length === 1 ? '' : 'es'}`} />
+        <pre><code>{JSON.stringify(value, null, 2)}</code></pre>
+      </div>
+    : <Tag key={field} size="small" label={field} value={String(value)} />
+  )}
 </div>
 ```
 
@@ -184,6 +218,8 @@ const [measurement, setMeasurement] = useState<BoxMeasurement | null>(null)
 }
 .measure-probe-wide { inline-size: 520px; padding-block: 6px; }
 .measure-probe-readout { display: flex; flex-wrap: wrap; gap: 6px; }
+.measure-probe-rects { flex-basis: 100%; min-width: 0; }
+.measure-probe-rects pre { margin: 4px 0 0; padding: 8px; border: 1px solid var(--border-4); border-radius: 4px; background: var(--bg-2); white-space: pre-wrap; overflow-wrap: anywhere; }
 ```
 
 See the [measurement fields](#boxmeasurement). Overflow fields map to kebab-case
@@ -284,13 +320,15 @@ const canvasRef = useRef<HTMLCanvasElement>(null)
 | `fade?` | boolean | — | Fades out every edge that currently hides clipped content, and drops the fade from an edge once the reader scrolls to it. |
 | `fadeSize?` | number \| string | 24 | Depth of the `fade` gradient. A `number` is pixels; a string is any CSS length. |
 | `gap?` | number \| string | — | Gap between children, matching the CSS `gap` property. A `number` is pixels; a string is any CSS length or two-value gap (`'1rem'`, `'8px 16px'`). Applies while the Box is a flex or grid container. |
+| `includeRectsFor?` | string | — | CSS selector for descendants whose border boxes are included in `measurement.rects` when Box measures. Coordinates are relative to this Box's top-left border edge; matches are in document order. Box reads and compares matching rects for each measurement event. With `observe="scroll"`, use `throttle` when the selector matches many descendants; it also delays CSS state updates after the initial read. |
 | `margin?` | number \| string | — | Outer spacing, matching CSS `margin`. Numbers are pixels; strings accept CSS shorthand, `auto`, negative lengths, and custom properties. Omission adds no style. |
 | `observe?` | 'width' \| 'height' \| 'size' \| 'context' \| 'overflow' \| 'edges' \| 'scroll' \| 'all' \| readonly BoxObservation[] | — | One selection or an array of selections, in any order. `'size'` watches width and height; `'context'` watches rendering context; `'overflow'` watches content dimensions and clipping. `'edges'` reports which edges hide content; `'scroll'` reports offsets, potentially every frame; `'all'` selects everything. Selections are independent: use `['size', 'edges']` to combine them. A measurement handler implies `'size'` when no measurement is selected; a context handler adds `'context'`. Size skips content and scroll observers; overflow adds content observation; hidden edges and scroll add scroll reads. Without handlers or `fade`, omission stays idle. |
+| `observeOffscreen?` | boolean | — | Keeps measurement events and CSS clipping states current outside the viewport. Has no effect unless `observe` or `fade` selects measurement. |
 | `onContextChange?` | (event, detail) => void | — | Fired after Box's browser and local rendering context changes. `detail` contains the changed fields and a full current snapshot. |
-| `onMeasureChange?` | (event, detail) => void | — | Fired when a selected measurement field changes. `detail` contains all fields changed since the last event and a full current snapshot. |
+| `onMeasureChange?` | (event, detail) => void | — | Fired when a selected measurement field changes. `detail.changed` contains fields changed since the previous event; `detail.current` includes the full snapshot with matching rects. Rect changes alone do not trigger an event. |
 | `padding?` | number \| string | — | Inner spacing, matching CSS `padding`. Numbers are pixels; strings accept CSS shorthand, percentages, and custom properties. Omission adds no style. |
 | `round?` | boolean \| number \| string | — | Fully-round corners (`border-radius: 999px`, clamped to the box). Pass a `number` (px) or a CSS length string (`'1rem'`) for a custom radius. Omit for square corners. |
-| `throttle?` | number | 0 | Minimum interval between measurement events, in milliseconds. The first report has no added delay; a trailing report delivers the latest values. Active observers and CSS clipping states are not throttled. |
+| `throttle?` | number | 0 | Minimum interval between measurements, in milliseconds. The initial measurement runs immediately; a trailing read updates CSS states and delivers the latest event. Descendant rects are read only for emitted events. The `measurement` getter always reads fresh values. |
 
 ### BoxMeasurement
 
@@ -307,6 +345,7 @@ const canvasRef = useRef<HTMLCanvasElement>(null)
 | `hiddenStartY` | boolean | — |  |
 | `overflowX` | boolean | — | Content exceeds the padding box on this axis, regardless of CSS overflow. |
 | `overflowY` | boolean | — |  |
+| `rects` | BoxRect[] | — | Matches for `includeRectsFor`, in document order. Empty when omitted. |
 | `scrollableX` | boolean | — | The exceeded content can be scrolled by the reader on this axis. |
 | `scrollableY` | boolean | — |  |
 | `scrollHeight` | number | — |  |
@@ -315,6 +354,19 @@ const canvasRef = useRef<HTMLCanvasElement>(null)
 | `scrollWidth` | number | — | Full scrollable-content dimensions, matching `scrollWidth` / `scrollHeight`. |
 | `width` | number | — | Border-box width and height in CSS pixels. |
 
+### BoxRect
+
+Coordinates and dimensions of a matched descendant's border box.
+
+| Field | Type | Default | Description |
+|------|------|---------|-------------|
+| `bottom` | number | — |  |
+| `height` | number | — |  |
+| `left` | number | — |  |
+| `right` | number | — |  |
+| `top` | number | — |  |
+| `width` | number | — |  |
+
 ### BoxContext
 
 | Field | Type | Default | Description |
@@ -381,7 +433,10 @@ Use `<a-box>` without JSX. Events are non-bubbling `CustomEvent`s with the same
 observation. Combine the eight selections with spaces, such as
 `observe="size edges"` or `observe="size scroll"`, in any order. Repeated tokens
 have no effect; unknown tokens are ignored. A bare `observe` means `"all"`.
-`throttle="100"` limits measurement events to a 100 ms interval.
+`throttle="100"` limits measurement reads, CSS state updates, and measurement
+events to a 100 ms interval.
+Add `observe-offscreen` to keep measurement observation active outside the
+viewport.
 
 ```html title="a-box"
 <a-box display="grid" gap="8px" round="12px" observe="all"
@@ -392,7 +447,9 @@ have no effect; unknown tokens are ignored. A bare `observe` means `"all"`.
 ```
 
 Import `@antadesign/anta/elements/a-box` to register the element. Listen for
-`measurechange` and `contextchange` with `addEventListener`.
+`measurechange` and `contextchange` with `addEventListener`. Set
+`include-rects-for=".marker"` to add matching descendant rects to each
+measurement without changing the observation triggers.
 `box.measurement`, `box.context`, and `box.isTruncated` read values synchronously.
 
 ## Styling

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/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>
     )