@antadesign/anta 0.3.28 → 0.3.29

package/docs/components/input-autocomplete.md

@@ -23,6 +23,12 @@ the first suggestion (then ↑/↓ move through them), and
 Enter on a highlighted row picks it. Esc or an outside click
 closes the list; clicking the field to place the caret keeps it open.
 
+The focused field is associated directly with the suggestion popup and its
+active option through ARIA element reflection. These relationships do not
+require generated popup or option IDs, so separate application roots cannot
+collide. Explicit ARIA relationships authored on a raw Anta Input take
+precedence.
+
 ## Filtering
 
 `filter` decides how suggestions match the text:

package/docs/components/input-date.md

@@ -212,9 +212,15 @@ the standard constraint-validation pipeline.
 
 ## Accessibility
 
+The focused Input field is associated directly with its Calendar dialog through
+ARIA element reflection. The relationship does not require a generated popup ID,
+so separate application roots can render InputDate instances without ID
+collisions. An explicitly authored relationship on a raw Anta Input takes
+precedence.
+
 The calendar is a labelled **group** of day buttons, a flat grid rather than a
-nested `grid`/`row`/`gridcell` tree. The group is named by the visible month
-(`aria-labelledby`). Each day is a `<button>` whose `aria-label` is its full date
+nested `grid`/`row`/`gridcell` tree. The visible month names the group directly.
+Each day is a `<button>` whose `aria-label` is its full date
 including weekday ("Sunday, June 28, 2026"), with `aria-pressed` on the selected day
 and `aria-current="date"` on today. The decorative weekday headers are `aria-hidden`,
 since each day already names its weekday. A roving `tabindex` keeps a single tab

package/docs/components/input.md

@@ -9,9 +9,9 @@ for styling through `::part(input)`.
 ## Size
 
 ```tsx
-<Input size="small"  label="Small"  placeholder="24px tall" />
-<Input size="medium" label="Medium" placeholder="28px tall" /> {/* default */}
-<Input size="large"  label="Large"  placeholder="32px tall" />
+<Input size="small"  label="Small"  placeholder="24px tall" autoComplete="off" />
+<Input size="medium" label="Medium" placeholder="28px tall" autoComplete="off" /> {/* default */}
+<Input size="large"  label="Large"  placeholder="32px tall" autoComplete="off" />
 ```
 
 Three sizes (`medium` is the default). The field **height**, the **type scale**
@@ -27,8 +27,8 @@ Anta's text scale, so a field lines up with same-size `Text` / `Button`.
 ## Label and hint
 
 ```tsx
-<Input label="Display name" defaultValue="Ada Lovelace" />
-<Input label="API key" hint="Find this in Settings → Developers." placeholder="sk-…" />
+<Input label="Display name" defaultValue="Ada Lovelace" autoComplete="name" />
+<Input label="API key" hint="Find this in Settings → Developers." placeholder="sk-…" autoComplete="off" />
 ```
 
 `label` sits above the field; `hint` is neutral helper text below it
@@ -40,12 +40,18 @@ mirrors the label text into `aria-label`, since a native `<label for>` can't
 cross the shadow boundary. The `hint` (or error) is mirrored the same way into
 `aria-description`, so a screen reader announces the message too.
 
+Standard `role` and `aria-*` attributes on `<Input>` or raw `<a-input>` are
+applied to the native input, textarea, or button inside its shadow root. This
+keeps the focused native control as the single accessible control. If you query
+the DOM directly, read those semantics from `a-input.control` rather than from
+the custom-element host.
+
 ## Tooltip
 
 ```tsx
 {/* Drop a <Tooltip> in as a child — it attaches to the field and shows on hover,
     exactly like a tooltip on any other element. */}
-<Input label="API key" placeholder="sk-…">
+<Input label="API key" placeholder="sk-…" autoComplete="off">
   <Tooltip>Find this in Settings → Developers.</Tooltip>
 </Input>
 ```
@@ -60,12 +66,12 @@ content.)
 
 ```tsx
 {/* No status = neutral helper text */}
-<Input label="Display name" defaultValue="Ada Lovelace" hint="This is your public name." />
-<Input label="Workspace" defaultValue="acme" status="info" hint="Lowercase letters and dashes only." />
-<Input label="Username" defaultValue="ada" status="success" hint="Username is available." />
-<Input label="Password" type="password" defaultValue="hunter2" status="warning" hint="Weak — add more characters." />
-<Input label="Email" defaultValue="not-an-email" status="critical" hint="Enter a valid email address." />
-<Input label="Plan" defaultValue="Pro" status="brand" hint="You're on the Pro plan." />
+<Input label="Display name" defaultValue="Ada Lovelace" hint="This is your public name." autoComplete="name" />
+<Input label="Workspace" defaultValue="acme" status="info" hint="Lowercase letters and dashes only." autoComplete="off" />
+<Input label="Username" defaultValue="ada" status="success" hint="Username is available." autoComplete="username" />
+<Input label="Password" type="password" defaultValue="hunter2" status="warning" hint="Weak — add more characters." autoComplete="new-password" />
+<Input label="Email" type="email" defaultValue="not-an-email" status="critical" hint="Enter a valid email address." autoComplete="email" />
+<Input label="Plan" defaultValue="Pro" status="brand" hint="You're on the Pro plan." autoComplete="off" />
 ```
 
 `status` tints the border and the `hint`, and prefixes a glyph — `critical`,
@@ -92,15 +98,16 @@ with `statusIcon={false}`.
 ```tsx
 {/* clearable — the clear button shows once there's a value */}
 {/* dimActions — adornments rest quiet, brighten when the field is hovered/focused */}
-<Input label="Search" placeholder="Search…" clearable dimActions defaultValue="design tokens" />
+<Input label="Search" placeholder="Search…" clearable dimActions defaultValue="design tokens" autoComplete="off" />
 
 {/* type="search" is a shorthand for the leading search icon + clearable below */}
-<Input label="Search" type="search" placeholder="Search…" />
+<Input label="Search" type="search" placeholder="Search…" autoComplete="off" />
 
 {/* leading / trailing take any node — see the live playground above */}
-<Input label="Search" leading={<Icon shape="search" />} clearable dimActions />
+<Input label="Search" leading={<Icon shape="search" />} clearable dimActions autoComplete="off" />
 <Input
   label="Date"
+  autoComplete="off"
   leading={<Icon shape="calendar" />}
   trailing={<Button priority="quaternary" size="small" icon="eye" aria-label="Pick" />}
   dimActions
@@ -149,6 +156,7 @@ const [reveal, setReveal] = useState(false)
 
 <Input
   label="Password"
+  autoComplete="current-password"
   type={reveal ? 'text' : 'password'}
   defaultValue="hunter2"
   dimActions
@@ -176,10 +184,10 @@ Firefox. So Anta keeps the native field.
 
 ```tsx
 {/* Grows with content, capped at 6 rows, then scrolls */}
-<Input multiline maxRows={6} label="Bio (autogrows)" placeholder="Tell us…" />
+<Input multiline maxRows={6} label="Bio (autogrows)" placeholder="Tell us…" autoComplete="off" />
 
 {/* Constant height of 3 rows */}
-<Input multiline rows={3} label="Notes (fixed 3 rows)" placeholder="…" />
+<Input multiline rows={3} label="Notes (fixed 3 rows)" placeholder="…" autoComplete="off" />
 ```
 
 `multiline` renders a `<textarea>` under the same API. With **no `rows`** it
@@ -195,11 +203,11 @@ browser.
 
 ```tsx
 // Uncontrolled: the element updates its value after input.
-<Input label="Name" defaultValue="Ada" onChange={(e) => log(e.target.value)} />
+<Input label="Name" defaultValue="Ada" autoComplete="name" onChange={(e) => log(e.target.value)} />
 
 // Controlled: application state supplies the value.
 const [v, setV] = useState('')
-<Input label="Name" value={v} onInput={(e) => setV(e.target.value)} />
+<Input label="Name" value={v} autoComplete="name" onInput={(e) => setV(e.target.value)} />
 ```
 
 Like a native input: pass `defaultValue` for **uncontrolled**, or `value` +
@@ -240,7 +248,7 @@ value-based, also has only `onValueChange`.)
 
 ```tsx
 <form onSubmit={handle}>
-  <Input name="email" label="Email" type="email" required clearable />
+  <Input name="email" label="Email" type="email" autoComplete="email" required clearable />
   <Button tone="brand" type="submit" label="Sign up" />
   <Button priority="tertiary" type="reset" label="Reset" />
 </form>
@@ -254,12 +262,12 @@ restores the field to its `defaultValue` via `formResetCallback`.
 ## Types and validation
 
 ```tsx
-<Input type="text"     label="Text" />
-<Input type="email"    label="Email" />
-<Input type="password" label="Password" />
-<Input type="tel"      label="Tel" />
-<Input type="url"      label="URL" />
-<Input type="number"   label="Number" min={0} max={100} />
+<Input type="text"     label="Text"     autoComplete="off" />
+<Input type="email"    label="Email"    autoComplete="email" />
+<Input type="password" label="Password" autoComplete="current-password" />
+<Input type="tel"      label="Tel"      autoComplete="tel" />
+<Input type="url"      label="URL"      autoComplete="url" />
+<Input type="number"   label="Number"   autoComplete="off" min={0} max={100} />
 ```
 
 `type` accepts `text` (default), `email`, `password`, `tel`, `url`, and
@@ -267,6 +275,12 @@ restores the field to its `defaultValue` via `formResetCallback`.
 constraint validation. (`search` is omitted on purpose — see above.)
 `number` also takes `min` / `max` / `step`.
 
+Set `autoComplete` to describe the field's purpose. `email`, `tel`, and `url`
+derive their matching token from `type`. Other purposes need an explicit token,
+such as `name`, `username`, `current-password`, `new-password`, or
+`one-time-code`. Use `autoComplete="off"` for examples and application fields
+that do not represent autofill data.
+
 For a **controlled** numeric field — one whose `value` you hold in state — prefer
 `type="text"` with `inputMode="decimal"` (or `"numeric"`) over `type="number"`. A
 number input runs value sanitization, so a mid-typing `"1."` or `"1.0"` reports an
@@ -296,10 +310,10 @@ function onSubmit(e) {
 }
 
 <form noValidate onSubmit={onSubmit}>
-  <Input name="email" type="email" required hint={errors.email}
+  <Input name="email" type="email" autoComplete="email" required hint={errors.email}
          status={errors.email ? 'critical' : undefined}
          onInput={() => setErrors(p => ({ ...p, email: undefined }))} />
-  <Input name="age" type="number" min="18" max="120" hint={errors.age}
+  <Input name="age" type="number" autoComplete="off" min="18" max="120" hint={errors.age}
          status={errors.age ? 'critical' : undefined}
          onInput={() => setErrors(p => ({ ...p, age: undefined }))} />
   <Button type="submit" label="Submit" />
@@ -345,7 +359,7 @@ Re-template the host to two columns and drop each part into one. The hint stays
 under the field by landing in the same column.
 
 ```tsx
-<Input className="label-side" label="Display name" hint="Shown on your profile" />
+<Input className="label-side" label="Display name" hint="Shown on your profile" autoComplete="name" />
 
 {/* .label-side is just for the demo — use your own selector */}
 <style>{`
@@ -369,9 +383,9 @@ left-edge lines up. Each hint still tucks under its own field.
 
 ```tsx
 <div className="aligned-form">
-  <Input label="Email" type="email" hint="We'll never share it." />
-  <Input label="Confirm password" type="password" />
-  <Input label="PIN" />
+  <Input label="Email" type="email" autoComplete="email" hint="We'll never share it." />
+  <Input label="Confirm password" type="password" autoComplete="new-password" />
+  <Input label="PIN" autoComplete="one-time-code" />
 </div>
 
 <style>{`
@@ -391,7 +405,7 @@ unit. Two columns (field, then hint); the label spans the top, and the hint
 centers against the field.
 
 ```tsx
-<Input className="hint-right" label="Username" hint="3–20 characters" placeholder="ada" />
+<Input className="hint-right" label="Username" hint="3–20 characters" placeholder="ada" autoComplete="username" />
 
 <style>{`
   a-input.hint-right {
@@ -412,10 +426,10 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
 
 ```tsx
 <div className="wrap-fields">
-  <Input label="First name" />
-  <Input label="Last name" />
-  <Input label="Email" type="email" />
-  <Input label="Phone" type="tel" />
+  <Input label="First name" autoComplete="given-name" />
+  <Input label="Last name" autoComplete="family-name" />
+  <Input label="Email" type="email" autoComplete="email" />
+  <Input label="Phone" type="tel" autoComplete="tel" />
 </div>
 
 <style>{`
@@ -430,6 +444,7 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
 |------|------|---------|-------------|
 | `autoComplete?` | 'off' \| 'on' \| 'name' \| 'username' \| 'email' \| 'current-password' \| 'new-password' \| 'one-time-code' \| 'tel' \| 'url' \| (string & {}) | — | Native autocomplete token. Overrides the value derived from `type` (`email` / `tel` / `url`) — set it for the cases `type` can't express, e.g. `username`, `current-password`, `new-password`, `one-time-code`, or `off`. |
 | `autoFocus?` | boolean | — | Focus this field when its containing `Dialog` opens. |
+| `button?` | boolean | — | Render the field surface with a native button as its focus target. This is available for Input-styled popup triggers; the value becomes the button text and the placeholder is shown while it is empty. |
 | `children?` | ReactNode | — | Extra content rendered directly under the field, above the hint/error (it pushes the message down). A no-box child like an Anta `<Tooltip>` takes no space and anchors to the field — consistent with how tooltips attach to any other element. Use the named `leading` / `trailing` props for in-field content. |
 | `clearable?` | boolean | — | Show a clear button as the first trailing item once the field has a value. |
 | `defaultValue?` | string | — | Initial value for the uncontrolled case. |
@@ -457,7 +472,7 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
 | `placeholder?` | string | — | Placeholder shown when empty. |
 | `readOnly?` | boolean | — | Make the field read-only. |
 | `required?` | boolean | — | Mark the field required (drives native validity). |
-| `role?` | string | — | ARIA `role` for the field — e.g. `combobox` when the input drives a suggestion `listbox` (see `InputAutocomplete`). Left unset by default. |
+| `role?` | string | — | ARIA `role` for the field — e.g. `combobox` when the input drives a suggestion `listbox` (see `InputAutocomplete`). The custom element delegates it, together with standard `aria-*` props, to the focused native shadow control. Left unset by default. |
 | `round?` | boolean \| number \| string | — | Fully-round the field (`border-radius: 999px`). Pass a `number` (px) or a CSS length string for a custom radius. The `clearable` × button always rounds to a circle to match (it isn't sized by a custom field value). |
 | `rows?` | number | — | Fixed visible row count — a constant-height `<textarea>` (implies `multiline`). |
 | `size?` | 'small' \| 'medium' \| 'large' | medium | Size variant. small=24px, medium=28px, large=32px tall; the type scale and icon track the size (small 13/16 + 14px icon · medium 15/20 + 16px · large 17/22 + 18px). |
@@ -478,7 +493,7 @@ Use the web component directly when you are not using React or Preact and a nati
 Slots hold the label, hint, and controls around the native field.
 
 ```html
-<a-input name="email" placeholder="you@example.com">
+<a-input name="email" type="email" autocomplete="email" placeholder="you@example.com">
   <span slot="label">Email</span>
   <span slot="hint">We only use it for account notices.</span>
 </a-input>
@@ -524,7 +539,7 @@ Reach for the props first: **`status`** sets a validation tone (border + message
 dimensions. The focus ring is the global [`--focus-ring`](../colors.md#focus-ring).
 
 ```tsx
-<Input tone="#e0457b" label="Custom accent" />
+<Input tone="#e0457b" label="Custom accent" autoComplete="off" />
 ```
 
 For everything else, `<a-input>` is shadow-DOM — style its **parts** with plain
@@ -563,5 +578,49 @@ a-input.fancy::part(field) {
   padding-inline: 20px;                      /* roomier */
 }
 a-input.fancy::part(input) { color: light-dark(#ffffff, #1a1a1a); }
+a-input.fancy::part(input)::placeholder {
+  color: light-dark(#b8b8b8, #666666);
+  opacity: 1;
+}
 a-input.fancy:focus-within::part(field) { background: light-dark(#161616, #ffffff); }
 ```
+
+### Placeholder contrast
+
+If the label, marking, context, or hint leaves the field's purpose unclear,
+a stronger placeholder can help. Keep an accessible name and put essential
+instructions in a persistent label or hint.
+
+Antune uses `--text-4` for placeholders. These ratios compare the default neutral
+Input backgrounds with the example's literal color:
+
+| Style | Placeholder | Background | Contrast |
+| --- | --- | --- | --- |
+| Antune light theme | `#7a737c` | `#ffffff` | 4.59:1 |
+| Antune dark theme | `#7c737c` | `#000000` | 4.60:1 |
+| Example | `#767676` | `#ffffff` | 4.54:1 |
+
+`#767676` is the lightest opaque 8-bit neutral gray that passes 4.5:1 on white.
+W3C recommends [sufficient placeholder contrast](https://www.w3.org/WAI/tutorials/forms/instructions/#styling).
+Redundant placeholders remain debated in the
+[meeting discussion](https://www.w3.org/2025/04/16-matf-minutes.html) and
+[open W3C issue](https://github.com/w3c/wcag/issues/4343); there is no agreed exemption.
+
+This demo uses `#767676` on white in every state and theme.
+Replace `.placeholder-contrast` with your own class.
+
+```tsx
+<Input className="placeholder-contrast" label="Email" type="email" autoComplete="email" placeholder="you@example.com" />
+```
+
+```css
+a-input.placeholder-contrast::part(field) { background: #ffffff; }
+a-input.placeholder-contrast::part(input) { color: #161616; }
+a-input.placeholder-contrast::part(input)::placeholder {
+  color: #767676;
+  opacity: 1;
+}
+```
+
+Check contrast separately if you use a different background.
+Native inputs and textareas use `::placeholder` without `::part(input)`.

package/docs/components/menu.md

@@ -415,7 +415,7 @@ navigating links.
 | `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). |
 | `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?` | ToneScope | '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. |
+| `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. |
 | `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
@@ -461,7 +461,7 @@ or do nothing to reject. (Submenus are always uncontrolled, regardless of `open`
 | `inset?` | number \| string | 4 | Inner inset for the scroll body and named header/footer content. A number is pixels; a CSS length string is used as written. |
 | `nohover?` | boolean | — | Submenu-only (a `<Menu>` nested inside a `MenuItem`); ignored on a root menu. Submenus open on hover by default (with intent timing) as well as on click — set `nohover` to make this submenu click-only. Hover-intent is mouse-only regardless: on touch (and pen) a submenu always opens on tap and stays open until dismissed. |
 | `offset?` | number | 4 | Gap in pixels between the trigger and the menu. |
-| `onactivedescendant?` | (e) => void | — | Combobox-mode cursor report (raw element event). Fires when the active option changes as arrow keys move the cursor while focus stays in a `[data-menu-search]` filter field; `detail.id` is the active option's `id` (`null` when none). The reactive layer that renders the field reflects this onto its `aria-activedescendant` — the element can't write that light-DOM attribute itself. Passed straight through to the element. |
+| `onactivedescendant?` | (e) => void | — | Combobox-mode cursor report (raw element event). Fires when the active option changes as arrow keys move the cursor while focus stays in a `[data-menu-search]` filter field; `detail.id` is an authored option `id`, or `null`. Built-in Anta Inputs receive the active option through a direct ARIA element relationship; this remains available to custom fields and observers. Passed straight through to the element. |
 | `onStateChange?` | (event, detail) => void | — | Fired before the open state changes — on open, and on every dismiss (Esc, outside-click, scroll, selecting an item). `event` is the cancelable `statechange`; `detail.next`/`detail.prev` are the requested/previous open state (booleans). It's the declarative way to observe a menu, and the handler you pair with `open` to drive a controlled menu (apply `detail.next` to `open`). Uncontrolled, `event.preventDefault()` vetoes the transition (e.g. keep the menu 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. |
@@ -494,7 +494,7 @@ or do nothing to reject. (Submenus are always uncontrolled, regardless of `open`
 | `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?` | ToneScope | '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. |
+| `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. |
 | `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

@@ -0,0 +1,189 @@
+# Panel
+
+`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.
+
+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
+can grow with its content. A parent's `min-height` alone does not generally
+establish a height for `height: 100%` to fill.
+
+> **Warning:** For now, Panel is a nonvisual utility container only. Supply your
+> own appearance and controls. Built-in chrome, resizing, and folding are not
+> available yet.
+
+## Usage
+
+### Declarative
+
+Panel manages its own state. Use `data-custom-event="paneltoggle"` on
+an Anta button to toggle maximization without a click handler.
+
+```tsx title="Declarative Panel"
+import { Box, Button, Input, Panel } from '@antadesign/anta'
+
+function Workspace() {
+  return (
+    <Panel style={{ background: 'var(--bg-3)' }}>
+      <Box
+        display="flex"
+        gap={16}
+        padding={16}
+      >
+        <Input aria-label="Workspace note" placeholder="Write a note" />
+        <Button data-custom-event="paneltoggle">
+          Maximize / restore
+        </Button>
+      </Box>
+    </Panel>
+  )
+}
+```
+
+### Controlled
+
+Pass `maximized` to manage state in your application. The button updates it
+through `onClick`; `onStateChange` accepts requests from declarative controls
+inside the panel.
+
+```tsx title="Controlled Panel"
+import { useState } from 'react'
+import { Box, Button, Input, Panel } from '@antadesign/anta'
+
+function Workspace() {
+  const [maximized, setMaximized] = useState(false)
+
+  return (
+    <Panel
+      style={{ background: 'var(--bg-3)' }}
+      maximized={maximized}
+      onStateChange={(_event, { next }) => setMaximized(next)}
+    >
+      <Box
+        display="flex"
+        gap={16}
+        padding={16}
+      >
+        <Input aria-label="Workspace note" placeholder="Write a note" />
+        <Button onClick={() => setMaximized(value => !value)}>
+          {maximized ? 'Restore panel' : 'Maximize panel'}
+        </Button>
+      </Box>
+    </Panel>
+  )
+}
+```
+
+## How does this work?
+
+Maximizing applies `popover="manual"` to the internal content slot and calls
+`showPopover()` to fill the viewport. Children keep their DOM ancestry, theme,
+and event bubbling. A placeholder preserves the panel's normal layout size.
+Restoring calls `hidePopover()` and returns the same content to normal layout.
+
+```html title="Internal content while maximized"
+<!-- Managed by Panel inside its shadow root. -->
+<slot part="content" popover="manual" tabindex="-1"></slot>
+```
+
+While maximized, Panel traps focus inside its content. Tab and Shift+Tab cycle
+through its controls. Restoring releases the trap and returns focus to the
+previous external control, when available.
+
+Provide a keyboard-accessible **Restore** control: Escape and outside clicks
+do not restore the panel. Panel adds no dialog role, background inertness, or
+scroll lock. Use [Dialog](./dialog.md) for modal interactions.
+
+Panel fills the browser viewport, without invoking the Fullscreen API.
+Browsers without Popover API support keep it in normal layout.
+
+## Component props
+
+For uncontrolled state, omit `maximized` and optionally set `defaultMaximized`.
+Call `event.preventDefault()` synchronously in `onStateChange` to cancel an
+uncontrolled transition. In controlled mode, reject a request by leaving
+`maximized` unchanged.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `defaultMaximized?` | boolean | — | Initial viewport maximization for an uncontrolled panel, read once on connect. |
+| `maximized?` | boolean | — | Fill the browser viewport and contain keyboard focus within the panel. When supplied, the application owns the state. |
+| `onStateChange?` | (event, detail) => void | — | Requested maximization change. Update `maximized` to accept a controlled request, or prevent the event to veto an uncontrolled request. |
+
+## Web component
+
+Import `@antadesign/anta/elements` to register the elements in this example.
+The button toggles the nearest panel without JavaScript handlers.
+
+```html title="Declarative web component"
+<a-panel style="background: var(--bg-3)">
+  <a-box display="flex" padding="16px" gap="16px" style="--box-padding: 16px; --box-gap: 16px">
+    <a-input aria-label="Workspace note" placeholder="Write a note"></a-input>
+    <a-button role="button" tabindex="0" data-custom-event="paneltoggle">
+      Maximize / restore
+    </a-button>
+  </a-box>
+</a-panel>
+```
+
+Use `state="normal"` or `state="maximized"` for controlled state, or `default-state="maximized"`
+for an initially maximized, uncontrolled panel.
+
+`requestMaximize()` and `requestRestore()` emit a cancelable, non-bubbling
+`statechange` with `{ next, prev }` using those state strings.
+Anta buttons can send `panelmaximizerequest`, `panelrestorerequest`, or
+`paneltoggle` through `data-custom-event` to the nearest Panel.
+
+## Styling
+
+Panel defaults to `display: block`, `width: 100%`, `height: 100%`,
+`box-sizing: border-box`, and `overflow: scroll`. 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.
+
+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
+`::part(content)` to change its overflow separately from the normal Panel.
+
+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.
+
+```html title="A persistent workspace panel"
+<a-panel class="panel-demo">
+  <a-box class="panel-demo-content">
+    <a-box class="panel-demo-toolbar" display="flex">
+      <a-text weight="medium">Workspace preview</a-text>
+      <a-button role="button" tabindex="0" data-custom-event="paneltoggle">
+        <span class="panel-demo-maximize">Maximize panel</span>
+        <span class="panel-demo-restore">Restore panel</span>
+      </a-button>
+    </a-box>
+    <a-capture>
+      <a-input placeholder="Write a note before maximizing" aria-label="Workspace note"></a-input>
+      <a-text>Panel keeps this Box and Capture in their original DOM location.</a-text>
+    </a-capture>
+  </a-box>
+</a-panel>
+```
+
+```css title="Preview layout and appearance"
+.panel-demo { border: 1px solid var(--border-4); border-radius: 8px; background: var(--bg-3); }
+.panel-demo-content { display: flex; flex-direction: column; gap: 20px; padding: 20px; }
+.panel-demo-toolbar { justify-content: space-between; align-items: center; gap: 12px; flex-wrap: wrap; }
+.panel-demo-content a-capture { display: grid; gap: 16px; }
+.panel-demo-content a-input { width: 100%; }
+.panel-demo-restore { display: none; }
+.panel-demo:state(maximized) .panel-demo-content { padding: max(20px, env(safe-area-inset-top)) max(20px, env(safe-area-inset-right)) max(20px, env(safe-area-inset-bottom)) max(20px, env(safe-area-inset-left)); }
+.panel-demo:state(maximized) .panel-demo-maximize { display: none; }
+.panel-demo:state(maximized) .panel-demo-restore { display: inline; }
+```

package/docs/components/radio.md

@@ -165,7 +165,9 @@ 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`. The
+`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
@@ -270,7 +272,7 @@ element — `Input`, and the composed `Select` — skip it and expose only
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size applied to every option (an option's own `size` wins). |
 | `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | 'neutral' | Validation/feedback tone for the group `hint` — recolors it (same tone set as `Input`'s `status`). Use `critical` for an error message, etc.; omit for the neutral default. |
 | `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Mark tone applied to every option (an option's own `tone` wins), or any literal CSS color for a one-off custom tone. In the default `all` scope it colors the selected-ring fill + dot and the unselected ring border. Named tones track light/dark mode. Set `toneScope="selected"` to tone only the selected option and leave the rest neutral. The option text stays neutral — recolor it in plain CSS via the `--text-N-{tone}` tokens. |
-| `toneScope?` | ToneScope | 'all' | Apply `tone` to every state, or only to the selected option so unselected rings stay neutral. An option's own `toneScope` wins. |
+| `toneScope?` | 'all' \| 'selected' | 'all' | Apply `tone` to every state, or only to the selected option so unselected rings stay neutral. An option's own `toneScope` wins. |
 | `value?` | string | — | Controlled selected value. The group follows this prop and reports a requested change through `onStateChange`. Leave it undefined for uncontrolled use. |
 
 ## Web Component