@antadesign/anta 0.3.34 → 0.3.35

package/docs/components/loader.md

@@ -65,7 +65,8 @@ Use `<Loader>` when you need a value, speed, or accessible loading status.
 
 ## Web Component
 
-Use a raw `<a-loader>` when you are not using the JSX wrapper. Set its size,
+Loader needs its stylesheet without JavaScript registration. Use a raw
+`<a-loader>` outside the JSX wrapper. Set its size,
 speed, and determinate percentage with CSS custom properties. `value` selects
 the static ring; `--loader-value` is the percentage it shows.
 

package/docs/components/menu.md

@@ -7,6 +7,11 @@ on outside-click, `Escape`, or scroll. Rows are dedicated **`MenuItem`s** (not
 buttons), with optional leading icons, trailing keyboard hints, separators,
 grouped sections, and nested submenus.
 
+The trigger can be replaced while Menu stays mounted, such as when a responsive
+layout switches controls. Keep Menu immediately after the replacement element.
+Menu reconnects its trigger listeners and popup relationships without resetting
+its open state.
+
 Open state is uncontrolled by default — pass **`onStateChange`** (event-first:
 `(event, { next, prev })`, or listen for the raw **`statechange`** event) to
 observe it, or pass **`open`** to control it, applying `detail.next` to `open`
@@ -213,7 +218,7 @@ footer stays the menu's divider.
 <Button>Filter</Button>
 <Menu inset={8}>
   <a-menu-header slot="header" data-menu-open>
-    <Input size="small" placeholder="Filter…" />
+    <Input size="small" placeholder="Filter…" aria-label="Filter items" />
   </a-menu-header>
   <MenuItem label="Design" />
   <MenuItem label="Engineering" />
@@ -488,7 +493,7 @@ or do nothing to reject. (Submenus are always uncontrolled, regardless of `open`
 | `open?` | boolean | — | Controlled open state. Omit for the default **uncontrolled** menu (it opens/closes itself via its triggers). Pass a boolean to **control** it: the menu's visibility follows `open`, and user dismiss (Esc, outside-click, select) fires `onStateChange` *without* self-closing — you update `open` in response. Submenus are always uncontrolled regardless of this. See STATEFUL-COMPONENTS.md. |
 | `placement?` | 'bottom-start' \| 'bottom-end' \| 'top-start' \| 'top-end' \| 'bottom' \| 'top' \| 'right-start' \| 'right-end' \| 'left-start' \| 'left-end' \| 'right' \| 'left' | bottom-start | Preferred placement relative to the trigger. `bottom` / `top` place the menu below / above; `right` / `left` place it beside (like a submenu flyout). The cross-axis suffix (`-start` / `-end`) aligns the near / far edges, and no suffix centers on the trigger. The menu flips to the opposite side when the preferred one lacks room, and clamps to the viewport. |
 | `role?` | string | menu | ARIA role of the menu surface. |
-| `round?` | boolean \| number \| string | — | Round the menu: the container softens to a 20px radius and its items go fully round. A `number` (px) or CSS length string tunes the container radius only — items stay full pills. |
+| `round?` | boolean \| number \| string | — | Round the menu container to a 20px radius. A `number` (px) or CSS length string sets a custom container radius. Items use the container radius minus `inset`, clamped to zero. Nested submenus inherit the container radius unless they set their own `round` value. |
 | `stopPropagation?` | boolean \| string \| string[] | — | Contain events so they don't bubble out of the menu to ancestor handlers (e.g. a clickable row the menu sits in). Selecting an item is always contained; this extends it to whole event types. `true` contains `click`; pass an event name or list (`"click pointerdown"`) to contain those. |
 
 ## MenuItem props
@@ -521,12 +526,16 @@ or do nothing to reject. (Submenus are always uncontrolled, regardless of `open`
 
 ## Web Component
 
-Use the web component directly when you are not using React or Preact and a native control does not fit.
+Use `<a-menu>` and `<a-menu-item>` directly outside JSX.
 
 Put a focusable trigger immediately before `<a-menu>` and omit `state` for an
 uncontrolled menu. Its light-DOM `<a-menu-item>` rows need their own `tabindex`
 values.
 
+Follow [Install and configure](../install-config.md) to load styles and browser behavior.
+For server-rendered applications, also follow
+[Browser hydration](../install-config.md#browser-hydration).
+
 ```html
 <a-button role="button" tabindex="0" aria-haspopup="menu">
   <a-button-label>Actions</a-button-label>
@@ -539,9 +548,29 @@ values.
 
 ## Styling
 
-The popover surface lives in shadow DOM and is exposed as a **part** — style its
+Menu item corners follow the container radius minus `inset`, clamped to zero.
+The default 8px container radius and 4px inset give items a 4px radius.
+The Antithesis theme uses a 2px container radius, so its items have square corners
+with the default inset. Pass `round` for a 20px container radius and 16px item
+radius, or pass a number or CSS length for a custom container radius.
+Nested submenus inherit the container radius unless they set their own `round`
+value. Each submenu subtracts its own `inset` to determine its item radius.
+Use `round` and `inset` to keep these radii connected. A direct CSS override of
+`::part(menu)` or a menu item's `border-radius` controls that surface independently.
+
+The popover surface lives in shadow DOM. Style its
 chrome (background, frost, border, radius, shadow, padding, min-width) with
-`::part(menu)`. Menu items are light DOM, so style them (and their
+`::part(menu)`. Use `::part(scroll)` for the scrolling body and `::part(header)` /
+`::part(footer)` for the pinned slots. Keep `display` overrides scoped to
+`::part(menu):popover-open` so closed menus remain hidden. Position and available
+height follow the trigger and viewport; overrides of positioning, visibility,
+transforms, or transitions can change those behaviors.
+
+Put overrides in `components`, `utilities`, or unlayered CSS. If older part
+overrides are in `base`, move them to a later layer so they take precedence over
+Anta's defaults. See [Cascade layers](../install-config.md#cascade-layers).
+
+Menu items are light DOM, so style them (and their
 `a-icon` / `kbd` / `a-menu-item-label` children) directly. Match **both** item
 shapes — the `a-menu-item` custom element and the `a[data-anta-menu-item]` link —
 with `:is(a-menu-item, a[data-anta-menu-item])`, or a link row skips your item
@@ -555,7 +584,7 @@ a-menu.fancy::part(menu) {
   border-radius: 22px;
   min-width: 240px;
   padding: 8px;
-  background: light-dark(rgba(255,255,255,0.55), rgba(28,26,32,0.5));
+  background: light-dark(color-mix(in oklch, white 55%, transparent), color-mix(in oklch, rgb(28,26,32) 50%, transparent));
   backdrop-filter: blur(28px) saturate(180%);
 }
 /* Items are light DOM — style them directly. `:is()` catches both an

package/docs/components/panel.md

@@ -154,6 +154,24 @@ maximized scrolling surface. In normal mode, the content slot uses `display: con
 The maximized surface also uses `overflow: auto`; override
 `::part(content)` to change its overflow separately from the normal Panel.
 
+The `::part(placeholder)` region reserves the normal content size while the
+surface is maximized. Panel measures its width and height, but your `::part()`
+rules can override those dimensions. Changing layout properties such as `width`,
+`height`, `padding`, `border`, or `box-sizing` can change the reserved space and
+move neighboring content. To preserve that space, customize `background` or
+`outline` and leave layout properties unchanged.
+
+Use `::part(content)::backdrop` to style the native popover backdrop. By default,
+the backdrop is transparent and ignores pointer events.
+
+Defaults live in external CSS and follow Anta's cascade layers. Put normal
+part overrides in `components`, `utilities`, or unlayered CSS. A `base` layer
+rule no longer overrides these defaults. See [Content Security Policy](../install-config.md#content-security-policy)
+for stylesheet loading and inline-style constraints.
+
+Inside another shadow root, load `@antadesign/anta/elements/a-panel.css` in
+that root through a stylesheet link. Document styles cannot reach Panel there.
+
 Enter a note, then select **Maximize panel** and **Restore panel**. The input
 keeps its value. The `panel-demo` classes supply this example's appearance;
 replace them with your own selectors.

package/docs/components/progress.md

@@ -1,27 +1,27 @@
-// The demo source lives in a sibling `.ts` file rather than inline
-// here because Astro's MDX pipeline trims leading whitespace from
-// JSX-attribute template literals, which scrambles the indentation
-// Monaco needs for folding ranges. A regular module import preserves
-// the template literal's bytes verbatim.
+// Keep the playground source in a module so MDX preserves its indentation.
 
 # Progress
 
-`Progress` shows task completion. Pass `value` for known progress. Omit it, or
-pass `false`, while work is underway without a known duration.
+Use Progress for uploads, downloads, and other tasks that take time. Show a
+percentage when you know the total, or a loading animation while completion is
+unknown. Add a label and hint to explain what is happening.
 
-## Value, label and hint
+## Value, label, and hint
 
 ```tsx
 <Progress value={60} />
-<Progress value={42} label="Uploading files…" hint="3 of 7" />
+<Progress value={3} max={7} label="Uploading files…" hint="3 of 7" />
 
-// Omit value, or pass false, while the duration is unknown.
+// Omit value while the total is unknown.
 <Progress label="Preparing upload…" hint="~ 3 minutes left" />
 ```
 
-`value` sets known completion relative to `max`, which defaults to `100`.
-`label` follows the percentage. `hint` is right-aligned. With no `value`, the
-label identifies indeterminate work and the loading animation takes the track.
+Pass `value` to show completion. For a percentage, use the default `max` of
+`100`. For a count, pass the total as `max`; the example shows 3 of 7 files.
+
+Use `label` to name the task and `hint` for details such as completed items or an
+estimated time. While the total is unknown, omit `value` or pass `false` to show
+loading stripes without a percentage.
 
 ## Size
 
@@ -31,8 +31,8 @@ label identifies indeterminate work and the loading animation takes the track.
 <Progress size="large" tone="info" value={60} label="Large" hint="~ 3 minutes left" />
 ```
 
-`size` scales the track and the default label row together. `medium` is the
-default.
+Use `small` for compact task lists and `large` for more prominent feedback.
+The track, percentage, label, and hint scale together.
 
 ## Tone
 
@@ -45,8 +45,9 @@ default.
 <Progress value={60} tone="#e0457b" label="Custom" />
 ```
 
-`tone` colors the track, indicator, and label row. Use `neutral` for the
-default, a named semantic tone, or any CSS color.
+Use `brand` for the primary task or a semantic tone to match its status. Keep
+the task's meaning in its label or hint so readers can understand it without
+color. Pass a CSS color for a custom tone.
 
 ## Border
 
@@ -78,9 +79,9 @@ default, a named semantic tone, or any CSS color.
 />
 ```
 
-The track starts borderless. Set a border width to reveal its tone-aware border
-color. A bottom edge works for an indicator at the top of an app. A top edge
-works for one at the bottom.
+Add a border to separate progress from the surrounding content. A bottom
+border suits a bar along the top of an app; a top border suits one along the
+bottom. The border color follows the tone.
 
 ## Round
 
@@ -89,25 +90,40 @@ works for one at the bottom.
 <Progress value={60} round={4} label="4px radius" />
 ```
 
-`round` makes the track fully round. Pass a number or CSS length for a custom
-radius.
+Use `round` for a pill-shaped track. Pass a number in pixels or a CSS length
+to match the corners of nearby content.
+
+## Custom content
+
+Use `children` when task details need more than a plain label and hint. Pass
+`label` and `hint` to keep an accessible description of the task.
+
+```tsx
+<Progress value={3} max={5} label="Sending report.csv" hint="3 of 5">
+  <Text>Sending <strong>report.csv</strong> · 3 of 5</Text>
+</Progress>
+```
 
 ## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `hint?` | string | — | Right-aligned hint text (e.g. "3 of 7"). Like `label`, it's not rendered when custom `children` are provided but still feeds the accessible name. |
-| `label?` | string | — | Text label displayed after the percentage, or on its own for indeterminate progress. When you provide custom `children` (which replace the default label row), `label` is no longer rendered — but it still supplies the progressbar's accessible name. |
-| `max?` | number | 100 | Upper bound of the range. |
-| `round?` | boolean \| number \| string | — | Fully-round track (`border-radius: 999px`); the fill is clipped to it. Pass a `number` (px) or a CSS length string for a custom radius. |
+| `hint?` | string | — | Details shown at the end of the row, such as "3 of 7" or a time estimate. Included in the accessible name even when custom `children` replace the row. |
+| `label?` | string | — | Task name shown after the percentage, or on its own during loading. Custom `children` replace the label row; this prop still supplies the progressbar's accessible name. |
+| `max?` | number | 100 | Total amount to complete. Use a positive number to show a count, such as 3 of 7 files. When `value` is supplied, a non-positive or non-finite total shows an empty fill. |
+| `round?` | boolean \| number \| string | — | Pill-shaped track. Pass a number in pixels or a CSS length for a custom corner radius. |
 | `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. Scales the track and the default label row together. |
-| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color variant, or any literal CSS color for a one-off custom tone (the surface / indicator / text are derived from it in oklch). Named tones track light/dark automatically. |
-| `value?` | number \| false | — | Current progress value. Omit this prop, or pass `false`, to show indeterminate progress. Negative values are clamped to 0. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color for the track, fill, and label row. Pass a named tone or a CSS color. Named tones follow the current theme. |
+| `value?` | number \| false | — | Completed amount relative to `max`. Omit this prop or pass `false` to show a loading animation without a percentage. Values are clamped to the range; non-finite values show zero completion. |
+
+<a id="raw-html"></a>
 
 ## Web Component
 
+<a id="web-component"></a>
+
 ```html
-<a-progress style="width: 100%" value="42" max="100" tone="info" role="progressbar"
+<a-progress value="42" max="100" tone="info" role="progressbar"
   aria-valuenow="42" aria-valuemin="0" aria-valuemax="100" aria-label="Upload, 42%">
   <a-progress-label>
     <a-progress-number>42%</a-progress-number>
@@ -123,12 +139,25 @@ radius.
 </a-progress>
 ```
 
-Use this when you are not using the React or Preact wrapper and a native HTML
-control does not fit: construct the equivalent Anta web component from the
-elements below.
+Use `<a-progress>` directly when you need its label layout in plain HTML.
+`a-progress-number`, `a-progress-text`, and `a-progress-hint` form the default
+row; you can also supply your own content.
+
+Load `@antadesign/anta/elements/a-progress` or the full bundle. Add `role` and
+ARIA values on the host, and keep them in sync with `value`, `max`, and visible
+text. Omit `value` for loading stripes.
 
-Add the progressbar semantics and label structure when using the element
-directly.
+The JSX wrapper supplies the markup, numeric CSS variables, and ARIA from props.
+Raw `value` and `max` rendering requires numeric CSS `attr()`, which is not
+available in every browser that meets Anta's minimum requirements. Numeric
+`--progress-value` and `--progress-max` variables override the corresponding
+attributes. JSX supplies and updates them automatically across supported browsers.
+
+Server-rendered JSX values use inline style attributes. A CSP with
+`style-src-attr 'none'` blocks these variables; attribute rendering then requires
+numeric CSS `attr()` support. Native `<progress data-anta>` uses browser-owned
+values without inline CSS variables across supported browsers. See
+[Content Security Policy](../install-config.md#content-security-policy).
 
 ### Native HTML progress
 
@@ -146,33 +175,38 @@ directly.
 <progress data-anta round="50px" aria-label="Preparing upload" style="width: 100%"></progress>
 ```
 
-For a plain HTML progress indicator, add `data-anta` to `<progress>`. It keeps
-the browser's native semantics, including indeterminate progress when `value`
-is absent, while using Anta's track, fill, tone, and size treatments. Native
-progress does not render Anta's label or hint structure; give it an accessible
-name instead.
+Use `<progress data-anta>` for a native progress bar with Anta's appearance.
+The browser handles completion and accessibility from `value` and `max`. Omit
+`value` for unknown completion, and give the control an accessible name.
+
+Native progress supports tone, size, and rounding. It has no built-in label row.
+The same Progress entry and full bundle style both forms.
 
 ## Styling
 
 ```css
-/* a fancy bar: rounded track (all sides), a multi-stop gradient fill with a glow,
-   and a crisp hard right edge (the default soft right-edge fade is cleared). */
+/* Rounded track and gradient fill with a glow. */
 a-progress.fancy {
   border-radius: 999px;
   background: light-dark(var(--bg-5), #26232c);
 }
-a-progress.fancy::part(indicator) {
-  background: linear-gradient(90deg, #6a5acd, #d44ea3 55%, #ff8a5b);
-  box-shadow: 0 0 12px rgba(212, 78, 163, 0.55);   /* glow */
+a-progress.fancy::before {
+  background: linear-gradient(
+    90deg,
+    light-dark(#6a5acd, #8b7cf0),
+    light-dark(#d44ea3, #ec64bc) 55%,
+    light-dark(#ff8a5b, #ffa477)
+  );
+  box-shadow: 0 0 12px color-mix(in oklch, #d44ea3 55%, transparent);
 }
-a-progress.fancy::part(indicator)::after { background: none; }   /* hard right edge */
 
-/* the percentage / label / hint are light-DOM children — recolor for the bar */
+/* Keep the label readable against the custom fill. */
 a-progress.fancy a-progress-number,
 a-progress.fancy a-progress-text { color: #fff; }
 a-progress.fancy a-progress-hint { color: var(--text-2); }
 ```
 
-For one-offs, the **track** is the host (style `a-progress` directly) and the
-**indicator** (fill bar) is a shadow **part** — `::part(indicator)`. The `.fancy`
-class is just for the demo.
+Use `tone`, `size`, and `round` for the component's appearance. For further
+customization, style `a-progress` for the track and `a-progress::before` for the
+fill or loading stripes. Target the label tags or your own children for text
+styling. `.fancy` belongs to this example.

package/docs/components/radio.md

@@ -1,9 +1,8 @@
 # Radio
 
-A single-select control. `RadioGroup` is the whole component — you pass it an
-`options` array and it renders one radio per entry, owning selection, keyboard
-navigation, and the form value. There's no separate `Radio` component: options
-are data, not markup.
+Use RadioGroup when someone needs to choose one option from a visible set,
+such as a plan or contact method. Pass the choices through `options` and add
+a group label to explain the decision.
 
 ## Options, label, and hint
 
@@ -20,12 +19,11 @@ are data, not markup.
 />
 ```
 
-Each entry needs a unique `value` (its identity and submitted value) and a
-`label`, plus an optional `hint` — secondary copy rendered under that option,
-styled like `Input`'s hint.
+Give each option a unique `value` and a `label`. Add an option `hint` when a
+choice needs explanation. The selected option's value is submitted with the form.
 
-The group's own `label` and `hint` form a header **above** the options: the
-`label` first, the `hint` (an instruction for the whole set) directly under it.
+Use the group's `label` to name the whole set and its `hint` for instructions
+that apply to every option.
 
 Each option can also set `className`, `style`, and `data-*`.
 `RadioGroup` forwards them to that option's `<a-radio>` so you can add
@@ -161,25 +159,15 @@ enabled one), the arrow keys (`↑`/`↓`/`←`/`→`) move the selection betwee
 options (wrapping at the ends), and `Space` / `Enter` select the focused option.
 Follows the [WAI-ARIA radio-group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).
 
-Under the hood the split is deliberate. The `<a-radio-group>` web component
-**never mutates the DOM** — it coordinates entirely off-DOM: selection is set as a
-property on each `<a-radio>` (which reflects it into `:state(selected)` +
-`aria-checked` via its own `ElementInternals`), the form value goes through
-`ElementInternals`, and focus is tracked with `aria-activedescendant`. Each
-option's light-DOM label and hint also become its accessible name and description
-through direct element references, without generated IDs. The
-**roving `tabindex`** — which option Tab lands on — is the one piece rendered
-declaratively, by the `RadioGroup` wrapper, from the current value. That's why
-selection is owned by the element but the wrapper holds the value: it needs it to
-place the tab stop. (Hand-assembling raw `<a-radio-group>` / `<a-radio>` works
-too; make the group the tab stop with `tabindex="0"` and it falls back to
-`aria-activedescendant` for keyboard nav.)
+Each option's label names it for screen readers, and its hint supplies a
+description. Give the group a `label` or `aria-label` so the choice itself also
+has an accessible name.
 
 ## Forms
 
-`<a-radio-group>` is a form-associated custom element. Give it a `name` and the
-selected option's `value` is submitted with the form like a native radio group;
-form reset restores the `defaultValue` selection.
+Add `name` to submit the selected option's value with a form. An uncontrolled
+group returns to `defaultValue` on form reset. For a controlled group, handle
+the reset request in `onStateChange` and update `value` as needed.
 
 ```tsx
 <form>
@@ -193,7 +181,7 @@ form reset restores the `defaultValue` selection.
 
 ## Controlled vs. uncontrolled
 
-**Uncontrolled** — pass `defaultValue` and let the group own selection:
+Pass `defaultValue` when the group can manage its own selection:
 
 ```tsx
 <RadioGroup name="plan" defaultValue="pro" options={[
@@ -203,9 +191,9 @@ form reset restores the `defaultValue` selection.
 ]} />
 ```
 
-**Controlled** — pass `value` + `onStateChange` and own it yourself. The group
-fires *before* applying, so you accept by updating `value` and reject by doing
-nothing (or `event.preventDefault()` to veto in uncontrolled mode):
+Pass `value` with `onStateChange` when the application controls selection.
+Update `value` to accept a requested choice, or leave it unchanged to reject it.
+For an uncontrolled group, call `event.preventDefault()` to cancel a user pick:
 
 ```tsx
 const [plan, setPlan] = useState('pro')
@@ -213,7 +201,7 @@ const [plan, setPlan] = useState('pro')
 <RadioGroup
   name="plan"
   value={plan}
-  onStateChange={(e, { next }) => setPlan(next)}
+  onStateChange={(_event, { next }) => { if (next !== null) setPlan(next) }}
   options={[
     { value: 'free', label: 'Free' },
     { value: 'pro', label: 'Pro' },
@@ -237,20 +225,20 @@ Three callbacks, in firing order:
 | `onChange(e)` | **after** selection applies | — | native `change` event |
 | `onValueChange(e, attrs)` | **after** selection applies | — | `{ value, name }` |
 
-Reach for **`onStateChange`** to intercept/veto or to filter on `reason` (reset vs
-restore vs user); for the everyday "react to the new value", use **`onValueChange`**.
-`onChange` is the plain native hook. **`onFocus` / `onBlur`** report focus entering
-and leaving the *group* (wired to `focusin` / `focusout`, since focus lands on an
-individual option).
-
-The group has `onStateChange` because its selection is a **discrete** state (one
-of a fixed set) the element self-applies — so a transition can be vetoed before it
-lands, and it carries `reason`. Value-based composites without a self-applying
-element — `Input`, and the composed `Select` — skip it and expose only
-`onValueChange`; the `onValueChange` shape is the same across all of them.
+Use `onStateChange` to control or cancel a selection request. Its `reason`
+distinguishes a user pick from form reset or restoration. Use `onValueChange`
+to save or react to an applied selection. `onChange` exposes the native event.
+`onFocus` and `onBlur` report focus entering and leaving the group.
 
 ```tsx
-<RadioGroup onValueChange={(_e, { value }) => save(value)} options={…} />
+<RadioGroup
+  label="Contact method"
+  onValueChange={(_event, { value }) => save(value)}
+  options={[
+    { value: 'email', label: 'Email' },
+    { value: 'sms', label: 'SMS' },
+  ]}
+/>
 ```
 
 ## RadioGroup props
@@ -279,7 +267,15 @@ element — `Input`, and the composed `Select` — skip it and expose only
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 
-The group owns selection and the single tab stop. Put options in `<a-radio-list>`.
+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.
+
+Put options in `<a-radio-list>` and add `tabindex="0"` to the group for
+keyboard access. The raw group manages focus among its options.
 
 ```html
 <a-radio-group role="radiogroup" tabindex="0" name="plan" default-state="pro">

package/docs/components/select-faceted.md

@@ -20,6 +20,16 @@ facet also opens a dialog containing its search field and options menu. Text and
 custom facets use dialogs for their editable content. An unfiltered option facet
 keeps the menu popup pattern.
 
+Global search matches options across all `single` and `multiple` facets, including
+facets with `filter: false`. A facet's `filter` controls its own search field.
+Each field keeps its query independently. Built-in matching searches `value`,
+`label`, and `hint` without case sensitivity; whitespace in a query matches a
+run of whitespace. A custom `filter` receives the original query, including
+leading and trailing spaces, in both search locations.
+It also runs for an empty per-facet query. A whitespace-only global query keeps
+the facet list visible instead of opening global results. Select's custom
+filter receives a trimmed query; account for this difference when sharing predicates.
+
 Pass `placement` to control where the root facet menu opens relative to its
 trigger. It uses the same values as `Menu` and still flips or clamps when space
 is limited. `offset` sets the gap in pixels between the trigger and the menu:
@@ -95,7 +105,7 @@ function Demo() {
       <SelectFaceted facets={FACETS} value={value} onValueChange={setValue} searchable />
 
       {active.length > 0 && (
-        <div style={{ display: 'flex', flexDirection: 'row', flexWrap: 'wrap', gap: 8, alignItems: 'center' }}>
+        <div style={{ display: 'flex', flexDirection: 'row', flexWrap: 'wrap', gap: 8, alignItems: 'center', maxWidth: '100%' }}>
           {/* Show an editable control or summary for each active facet. */}
           {active.map((facet) => {
             // Options facets → an editable Select (single shows the trailing check;
@@ -108,13 +118,13 @@ function Demo() {
                   indicator={facet.kind === 'single' ? 'check' : undefined}
                   options={facet.options}
                   renderOption={facet.renderOption}
-                  value={value[facet.key]}
+                  value={value[facet.key] ?? (facet.kind === 'single' ? null : [])}
                   onValueChange={(v) => setFacet(facet.key, v)}
                   leading={`${facet.label}:`}
+                  aria-label={facet.label}
                   filter={facet.filter}
                   clearable
-                  // Chip sizes to its value and caps at a max-width (ellipsizing past it).
-                  style={{ width: 'fit-content', maxWidth: '240px' }}
+                  className="sf-chip"
                 />
               )
 
@@ -134,12 +144,11 @@ function Demo() {
                 leading={`${facet.label}:`}
                 clearable
                 dimActions
+                className="sf-chip"
                 onFocus={() => setFocusedKey(facet.key)}
                 onBlur={() => setFocusedKey(null)}
                 onInput={(e) => write(e.currentTarget.value)}
                 onClearInput={() => { setFocusedKey(null); setFacet(facet.key, undefined) }}
-                // Size the chip to its value, capped at a max-width.
-                style={{ width: 'fit-content', maxWidth: '240px' }}
               />
             )
           })}
@@ -161,9 +170,17 @@ function Demo() {
 }
 ```
 
+The demo gives editable chips a consistent width, capped by their container.
+Input truncates long values with an ellipsis when the field is unfocused.
+
+```css
+.sf-chip { width: 240px; max-width: 100%; }
+```
+
 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.
+`leading` prefix and `aria-label` as its accessible name. Recency uses a summary
+tag and is edited in the facet menu.
 
 ### Custom option content
 
@@ -503,3 +520,33 @@ It can store a value of type `V`, including an object such as a date range.
 | `kind` | `'custom'` | Discriminant. |
 | `render` | `(ctx) => ReactNode` | Renders the editor. `ctx.value` is the current `V`; `ctx.onChange(next)` sets it, and `undefined` clears the facet. `ctx.close()` closes the menu. |
 | `summary` | `(value: V) => ReactNode` | The chip on the facet's row while a value is set. |
+
+## Styling
+
+`size` and `priority` style the default trigger. `tone` and `toneScope` style
+option rows. `className`, `style`, and extra attributes apply to the default
+Button; a custom `renderTrigger` owns its own styling and attributes.
+
+SelectFaceted uses external styles for its fixed layout, including the text
+editor's padding. Consumer `style` props, option styles, render-hook styles,
+and custom color or radius props can still produce inline style attributes.
+Server-rendered inline styles are blocked by `style-src-attr 'none'`.
+
+The text editor uses a CSS-only `a-select-faceted-text` region in its Menu.
+If you targeted the former `div[data-menu-open]` wrapper, replace that part of
+your selector with `a-select-faceted-text`. Its padding now comes from CSS,
+so selectors that require an inline `style` attribute no longer apply.
+Use your trigger's class and the adjacent Menu to scope its padding. The class
+in this example belongs to the demo; replace it with your own selector. Open
+**Title contains** to see the larger inset.
+
+```tsx
+<SelectFaceted
+  className="roomy-text-filter"
+  facets={[{ key: 'title', label: 'Title contains', kind: 'text' }]}
+/>
+```
+
+```css
+.roomy-text-filter + a-menu a-select-faceted-text { padding: 8px; }
+```