@antadesign/anta 0.3.34 → 0.3.35

package/docs/components/input.md

@@ -1,45 +1,33 @@
 # Input
 
-A text field. The `Input` wrapper renders an `<a-input>` web component whose
-real `<input>` / `<textarea>` lives in **shadow DOM** — so the field is
-self-contained (you never pass a control in) yet fully native underneath:
-focus, IME, autofill, and form submission all work, and the control is reachable
-for styling through `::part(input)`.
+Use Input for forms, search, passwords, and longer text. Add a label to explain
+what to enter, a hint for guidance, and actions such as clearing or revealing a
+password.
 
 ## Size
 
 ```tsx
-<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" />
+<Input size="small"  label="Small"  placeholder="Enter text…" autoComplete="off" />
+<Input size="medium" label="Medium" placeholder="Enter text…" autoComplete="off" /> {/* default */}
+<Input size="large"  label="Large"  placeholder="Enter text…" autoComplete="off" />
 ```
 
-Three sizes (`medium` is the default). The field **height**, the **type scale**
-(font / line-height), and the **icon** all track the size. Each step matches
-Anta's text scale, so a field lines up with same-size `Text` / `Button`.
-
-| size | height | font / line | icon |
-|---|---|---|---|
-| `small` | 24px | 13 / 16 | 14px |
-| `medium` | 28px | 15 / 20 | 16px |
-| `large` | 32px | 17 / 22 | 18px |
+Choose `small`, `medium`, or `large` to suit the surrounding interface.
+Text, icons, and action buttons adjust together. The default is `medium`.
 
 ## Priority
 
-`priority` changes the field surface without changing its size or behavior.
-`primary` (the default) has a fill and border. `secondary` has a transparent
-background and visible border. `tertiary` keeps both transparent at rest, then
-uses secondary's border on hover or focus. Use it where the label or surrounding
-content makes the field easy to find. All three show the same focus ring.
-On an enabled field, a non-neutral `status` keeps its tinted fill and border
-visible at rest.
-
 ```tsx
 <Input label="Primary" placeholder="Filled field" autoComplete="off" />
 <Input priority="secondary" label="Secondary" placeholder="Outlined field" autoComplete="off" />
 <Input priority="tertiary" label="Tertiary" placeholder="Field on hover or focus" autoComplete="off" />
 ```
 
+Use `priority` to choose how much the field stands out. `primary` has a filled
+background, `secondary` has an outline, and `tertiary` stays subtle until someone
+interacts with it. Use tertiary where the label or context makes the field easy
+to find. Status feedback and focus remain visible with every priority.
+
 ## Label and hint
 
 ```tsx
@@ -47,36 +35,23 @@ visible at rest.
 <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
-(`--text-3`, no icon). Both accept a **string or a React node**, so you can
-embed links, `<code>`, or a `<Text>` for full control.
+`label` names the field and appears above it. `hint` provides persistent help
+below it. Both accept text or JSX, including links and emphasis. Keep essential
+instructions here so they remain available while someone types.
 
-The label is wired as the control's accessible name automatically — the element
-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.
+The label also names the field for screen readers, and the hint provides its
+description.
 
 ## 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-…" autoComplete="off">
   <Tooltip>Find this in Settings → Developers.</Tooltip>
 </Input>
 ```
 
-Attach a tooltip by dropping an Anta `<Tooltip>` in as a **child** — no slot or
-prop needed. It anchors to the field and shows on hover, consistent with how
-tooltips attach to a `<Button>` or any other element. (Children with no `slot`
-are projected into a default slot; use `leading` / `trailing` for *in-field*
-content.)
+Place a `Tooltip` inside `Input` to anchor it to the field. It appears on hover
+or keyboard focus. Use `leading` and `trailing` for content inside the field itself.
 
 ## Status
 
@@ -90,84 +65,74 @@ content.)
 <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`,
-`warning`, `success`, `info`, or `brand`. Each pulls its tone's role tokens, so
-dark mode is automatic. The message always rides in `hint`; `status` only
-recolors it.
-
-It reuses the tone palette but isn't `tone`: **`status` is a validation *state*** (it
-also carries the glyph and, for `critical`, validity), whereas `tone` — elsewhere in
-Anta — is decorative color. On `Input` the named tones live on `status`; `tone` is
-reserved for a one-off custom border color.
+`status` colors the field and hint and adds a status icon. Choose `critical`,
+`warning`, `success`, `info`, or `brand`; each adapts to the active theme.
+Put the message in `hint`.
 
-Only `status="critical"` carries validity — it sets `aria-invalid`, flips the
-`:state(invalid)` hook, and reports invalid to a surrounding `<form>` through
-`ElementInternals`. The other tones are advisory and stay valid.
+Use `critical` for an error that must be fixed before submitting the form.
+Other statuses provide feedback without marking the field invalid. Required
+fields and email fields still need valid values.
 
-Each status has a default glyph (`critical` → `warning-diamond`, `warning` →
-`warning-triangle`, `success` → `circle-check`, `info` → `info`, `brand` →
-`circle-small-solid`). Override it with **`statusIcon`** (any shape), or drop it
-with `statusIcon={false}`.
+Use `statusIcon` to replace the default icon, or `statusIcon={false}` to hide it.
+For a custom border color without status feedback, use `tone`.
 
 ## Leading, trailing, and clear
 
 ```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" autoComplete="off" />
-
-{/* type="search" is a shorthand for the leading search icon + clearable below */}
-<Input label="Search" type="search" placeholder="Search…" autoComplete="off" />
+import { useState } from 'preact/hooks'
+import { Input, Icon, Button } from '@antadesign/anta'
+
+function SearchActions() {
+  const [caseSensitive, setCaseSensitive] = useState(false)
+  const [regex, setRegex] = useState(false)
+  return (
+    <>
+      <Button priority="tertiary" icon="case-sensitive"
+        aria-label="Case sensitive" title="Case sensitive"
+        selected={caseSensitive} aria-pressed={caseSensitive}
+        onClick={() => setCaseSensitive(value => !value)} />
+      <Button priority="tertiary" icon="regex"
+        aria-label="Regular expression" title="Regular expression"
+        selected={regex} aria-pressed={regex}
+        onClick={() => setRegex(value => !value)} />
+    </>
+  )
+}
 
-{/* leading / trailing take any node — see the live playground above */}
-<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
-/>
+function Demo() {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', width: '100%', maxWidth: '320px' }}>
+      <Input label="Leading icon" placeholder="Search…" leading={<Icon shape="search" />} autoComplete="off" />
+      <Input label="Trailing actions" placeholder="Search…" trailing={<SearchActions />} dimActions autoComplete="off" />
+      <Input label="Clear action" placeholder="Search…" clearable dimActions defaultValue="design tokens" autoComplete="off" />
+      <Input label="All adornments" leading={<Icon shape="search" />} trailing={<SearchActions />} clearable dimActions defaultValue="design tokens" autoComplete="off" />
+      <Input label="Text adornments" leading="from" trailing="each" defaultValue="$20" autoComplete="off" />
+    </div>
+  )
+}
 ```
 
-`leading` and `trailing` paste any node at the field edges (like the expander's
-`actions`) — an icon, a button, a unit label. A leading item is inset from the
-left by the same `pad-x` as the text, so it lines up on the field's rhythm; the
-playground at the top of this page shows a live leading icon alongside the clear
-button.
+Use `leading` and `trailing` to place icons, buttons, or short text inside the
+field. Use either on its own or combine them with a clear button. The preview
+shows search options and text such as “from” and “each.”
 
-**`type="search"`** is a shorthand for that search pattern: it defaults a leading
-search icon and `clearable` (override either — pass your own `leading`, or
-`clearable={false}`). It's wrapper-only — the native `search` type never reaches the
-DOM input, so the browser's own clear/search chrome never appears; Anta owns it.
-
-**`dimActions`** rests the adornments quiet (60% opacity) and brightens them to
-full when the field is hovered or focused — a "quiet until engaged" look for
-trailing actions. It dims the whole slot, so it covers icons and buttons alike.
-
-`clearable` adds a clear button at the right edge, shown once the field has a
-value. It's a real `<a-button>` in the `clear` slot — full button styling,
-**keyboard-focusable** — and it works **without framework hydration**: a-button's
-global handler fires a `clearrequest` trigger on click and Enter/Space, which the
-element turns into the lifecycle below.
-
-Two hooks bracket the clear. **`onClearClick`** fires first and is **cancelable** —
-`e.preventDefault()` keeps the value (e.g. a "discard unsaved text?" confirm). If
-it isn't prevented, the field clears: it empties, fires `input` / `change` (a
-controlled `onChange` runs with the empty value), refocuses, then fires
-**`onClearInput`**. On a raw `<a-input>`, bind both lowercase (`onclearclick` /
-`onclearinput`) — that form binds in React and Preact alike.
-
-Note: there's no `type="search"` — that type makes browsers inject their own
-clear button and magnifier (and style them inconsistently). Anta owns every
-in-field control, and the element resets the native search/number/reveal
-decorations across browsers.
+Trailing icon buttons adjust to the field size, with space around them to keep them
+inside the border. You don't need to size them separately.
+
+Use `dimActions` to keep these extras subtle until someone hovers over or
+focuses the field.
+
+`clearable` shows a clear button when an editable field has a value. After
+clearing, focus returns to the field so typing can continue. See
+[Events](#events) to cancel a clear or respond after it completes.
+
+For a search field, use `type="search"` to add a search icon and clear button.
+You can replace the icon with `leading` or hide the button with
+`clearable={false}`.
 
 ### Password reveal
 
 ```tsx
-// Reveal toggle = flip `type` between password and text. Native masking when
-// hidden, plain text when shown; password managers keep working.
 const [reveal, setReveal] = useState(false)
 
 <Input
@@ -187,93 +152,112 @@ const [reveal, setReveal] = useState(false)
 />
 ```
 
-A `trailing` eye `<Button>` flips the field's `type` between `password` and
-`text` — native disc masking when hidden, plain text when revealed. Because it
-stays a real `type="password"` when hidden, password managers and autofill keep
-working, and the uncontrolled value is preserved across the toggle.
-
-The mask glyph stays the browser default — restyling it means dropping
-`type="password"`, which loses password-manager support and isn't masked in
-Firefox. So Anta keeps the native field.
+Use a trailing button to toggle `type` between `password` and `text` without
+changing the value. The browser masks the password while it is hidden.
+`autoComplete="current-password"` identifies an existing password for autofill.
 
 ## Multiline
 
 ```tsx
-{/* Grows with content, capped at 6 rows, then scrolls */}
+{/* Grows with content, then scrolls */}
 <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="…" autoComplete="off" />
+{/* Keeps a fixed height */}
+<Input multiline rows={3} label="Notes (fixed height)" placeholder="…" autoComplete="off" />
 ```
 
-`multiline` renders a `<textarea>` under the same API. With **no `rows`** it
-**autogrows** with its content via CSS `field-sizing: content` — capped by
-`maxRows` if you set one (omit for unbounded growth), then it scrolls. Pass a
-fixed **`rows`** count for a constant-height box instead.
-
-Autogrow uses CSS `field-sizing` where supported (Chromium, Safari ≥ 26.2) and a
-built-in JS resize everywhere else (Firefox, older Safari), so it grows in every
-browser.
+Use `multiline` for longer text. The field grows as someone types.
+Set `maxRows` to limit its growth, or `rows` to keep a fixed height and scroll
+longer content.
 
 ## Controlled and uncontrolled
 
 ```tsx
 // Uncontrolled: the element updates its value after input.
-<Input label="Name" defaultValue="Ada" autoComplete="name" onChange={(e) => log(e.target.value)} />
+<Input label="Name" defaultValue="Ada" autoComplete="name" onChange={(e) => console.log(e.target.value)} />
 
 // Controlled: application state supplies the value.
-const [v, setV] = useState('')
-<Input label="Name" value={v} autoComplete="name" onInput={(e) => setV(e.target.value)} />
+const [value, setValue] = useState('')
+<Input label="Name" value={value} autoComplete="name" onInput={(e) => setValue(e.target.value)} />
 ```
 
-Like a native input: pass `defaultValue` for **uncontrolled**, or `value` +
-`onInput` / `onChange` for **controlled**. The controlled value is reflected to
-the shadow control only when it differs from what's there, so the caret never
-jumps mid-edit.
+Use `defaultValue` when the field can manage its own value. Use `value` with
+`onInput` or `onValueChange` when your application needs to keep track of every
+edit, such as updating a search or showing a character count.
 
-Read the value off `e.target.value` in either handler — the event retargets to
-the `<a-input>` host, whose `value` getter returns the control's value.
+Read the current text from `e.target.value`, or use the value provided by
+`onValueChange`. Use `onChange` for edits that are committed, such as when the
+field loses focus.
 
-Note: like other custom-element form controls (and unlike React's built-in
-`<input>`), a controlled value that you *transform* applies on the next render,
-but one you *reject* — set state back to the same string — isn't auto-reverted,
-since the framework skips the re-render. Constrain hard with `maxLength` /
-`pattern` / `type`, or transform in the handler.
+Changing the value in state updates the field. Setting state to the same value
+may not undo a typed edit. Use `maxLength` for a length limit, and apply any text
+formatting in your change handler.
 
 ## Events
 
-| handler | fires | payload |
+| Handler | When it fires | Value or action |
 |---|---|---|
-| `onInput(e)` | on **every keystroke** | read `e.target.value` |
-| `onChange(e)` | on **commit** (blur / Enter) — native `change` semantics, *not* React's per-keystroke `onChange` | read `e.target.value` |
-| `onValueChange(e, attrs)` | on `input` **and** `change` (and clear) | `{ value, name, empty, valid, validationMessage }` |
-| `onClearClick(e)` | before the `clearable` × clears | ✅ `e.preventDefault()` keeps the value |
-
-**Input has no `onStateChange`, on purpose.** That event belongs to components
-with a *discrete* state — a small enum like `Checkbox`'s `checked · unchecked ·
-indeterminate` or a menu's `open · closed` — where a transition can be vetoed as
-a unit before it applies. A text field's value is **free-form**, not a discrete
-state, so there's nothing to model as `state` and nothing to veto wholesale;
-you control it the native way (`value` + `onInput`/`onChange`, reject by not
-updating). Reach for `onValueChange` as the one unified "the value changed"
-handler — it's the same callback `Checkbox`, `RadioGroup`, and `Select` expose,
-so form code reads the same across all of them. (`Select`, likewise composed and
-value-based, also has only `onValueChange`.)
+| `onInput(e)` | When editing changes the value, or the field is cleared | Read `e.target.value` |
+| `onChange(e)` | On commit, such as blur or Enter, or when cleared | Read `e.target.value` |
+| `onValueChange(e, attrs)` | On both `input` and `change` | `{ value, name, empty, valid, validationMessage }` |
+| `onClearClick(e)` | Before clearing | Call `e.preventDefault()` synchronously to cancel |
+| `onClearInput(e)` | After clearing | The value is empty |
+
+Use `onValueChange` to receive the current text and validation result together.
+It runs while editing and when an edit is committed, so it can run more than
+once for the same value.
+
+Use `onClearClick` to keep a draft from being cleared. Try **Clear** with
+**Protect draft** enabled, then turn protection off and try again.
+
+```tsx
+import { useState } from 'preact/hooks'
+import { Input, Checkbox, Button } from '@antadesign/anta'
+
+function Demo() {
+  const [value, setValue] = useState('Keep this draft')
+  const [protect, setProtect] = useState(true)
+  const [event, setEvent] = useState('Edit the field or select Clear.')
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '12px', width: '320px', maxWidth: '100%' }}>
+      <Input
+        label="Draft"
+        value={value}
+        clearable
+        hint={event}
+        onValueChange={(event, { value }) => {
+          setValue(value)
+          setEvent(event.type === 'input' ? 'Draft updated.' : 'Draft committed.')
+        }}
+        onClearClick={event => {
+          if (protect) {
+            event.preventDefault()
+            setEvent('Clear cancelled. Turn off Protect draft to clear it.')
+          }
+        }}
+        onClearInput={() => setEvent('Draft cleared.')}
+      />
+      <Checkbox label="Protect draft" checked={protect}
+        onStateChange={(_, { next }) => setProtect(next)} />
+      <Button label="Restore draft" onClick={() => setValue('Keep this draft')} />
+    </div>
+  )
+}
+```
 
 ## Forms
 
 ```tsx
-<form onSubmit={handle}>
+<form>
   <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>
 ```
 
-Because `<a-input>` is form-associated, it submits with the surrounding
-`<form>` under its `name` — `new FormData(form)` includes it, no hidden mirror
-needed. `required` participates in native validity, and `<Button type="reset">`
-restores the field to its `defaultValue` via `formResetCallback`.
+Input submits its value under `name` with the surrounding form, and
+`new FormData(form)` includes it. Native constraints such as `required` block
+normal submission while invalid. A reset button restores `defaultValue`.
 
 ## Types and validation
 
@@ -286,98 +270,92 @@ restores the field to its `defaultValue` via `formResetCallback`.
 <Input type="number"   label="Number"   autoComplete="off" min={0} max={100} />
 ```
 
-`type` accepts `text` (default), `email`, `password`, `tel`, `url`, and
-`number` — each gets the right mobile keyboard, autofill behavior, and native
-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
-empty `value` and can't be entered; storing the parsed `Number` and rendering it
-back drops the decimal for the same reason. Keep the raw string in state and parse
-to a number where you use it — `inputMode` still brings up the numeric keypad. An
-**uncontrolled** `type="number"` (no bound `value`) has neither problem.
-
-Every type carries its native constraints (`required`, the `type` itself,
-`pattern`, `min`/`max`, `min`/`maxLength`). The field reports them to the
-surrounding `<form>` automatically (via `ElementInternals`), so submission is
-blocked while invalid — no extra wiring.
+Choose `type` to match what someone will enter: text, an email address,
+a password, a phone number, a URL, or a number. Use `search` for a search field.
+
+Set `autoComplete` to help the browser fill in familiar information, such as a
+name or saved password. Email, telephone, and URL fields already use matching
+autocomplete hints. Use `autoComplete="off"` where autofill isn't useful.
+
+For numeric text that needs to keep partial entries or trailing zeros, use
+`type="text"` with `inputMode="decimal"` or `"numeric"`. Keep the text as entered
+and convert it to a number when needed. `inputMode` suggests a keyboard without
+restricting what can be entered.
+
+Use `required`, length limits, a `pattern`, or numeric limits to check values
+before submission. Available checks depend on the field type. A `pattern`
+checks the finished value without blocking typing.
 
 ### Native validation
 
 ```tsx
-// Surface the browser's own validity messages as Anta's critical-status UI.
-const [errors, setErrors] = useState({})
-
-function onSubmit(e) {
-  e.preventDefault()
-  const next = {}
-  e.currentTarget.querySelectorAll('a-input').forEach((el) => {
-    if (!el.checkValidity()) next[el.name] = el.validationMessage
-  })
-  setErrors(next)
+import { useState } from 'preact/hooks'
+import { Input, Button } from '@antadesign/anta'
+
+function Demo() {
+  const [errors, setErrors] = useState<Record<string, string | undefined>>({})
+
+  function onSubmit(e: SubmitEvent) {
+    e.preventDefault()
+    const next: Record<string, string | undefined> = {}
+    const form = e.currentTarget as HTMLFormElement
+    form.querySelectorAll('a-input').forEach((el: any) => {
+      if (!el.checkValidity()) next[el.name] = el.validationMessage
+    })
+    setErrors(next)
+  }
+  const clearError = (name: string) => setErrors(previous => ({ ...previous, [name]: undefined }))
+
+  return (
+    <form noValidate onSubmit={onSubmit}
+      style={{ display: 'flex', flexDirection: 'column', gap: '14px', width: '300px' }}>
+      <Input name="email" label="Email" type="email" autoComplete="email"
+        placeholder="you@example.com" required hint={errors.email}
+        status={errors.email ? 'critical' : undefined}
+        onInput={() => clearError('email')} />
+      <Input name="site" label="Website" type="url" autoComplete="url"
+        placeholder="https://…" hint={errors.site}
+        status={errors.site ? 'critical' : undefined}
+        onInput={() => clearError('site')} />
+      <Input name="age" label="Age" type="number" autoComplete="off"
+        placeholder="18 – 120" min="18" max="120" hint={errors.age}
+        status={errors.age ? 'critical' : undefined}
+        onInput={() => clearError('age')} />
+      <div style={{ display: 'flex', gap: '8px' }}>
+        <Button type="submit" tone="brand" label="Submit" />
+        <Button type="reset" priority="tertiary" label="Reset" onClick={() => setErrors({})} />
+      </div>
+    </form>
+  )
 }
-
-<form noValidate onSubmit={onSubmit}>
-  <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" 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" />
-</form>
 ```
 
-The element proxies native validity: `<a-input>` exposes `checkValidity()` and
-`validationMessage` (the browser's localized message).
+You can show the browser's validation messages as hints. Check each field
+with `checkValidity()`, put its `validationMessage` in `hint`, and use
+`status="critical"` for errors. Add `noValidate` to the form when your handler
+will display the messages instead of the browser's popup.
 
-Pass `validationMessage` to **`hint`** and set **`status="critical"`** — the
-field goes red, shows the warning glyph, and reports invalid to the form. Mark
-the form `noValidate` so the browser's default bubbles step aside for Anta's
-styling. Try submitting empty, or with a bad email / out-of-range age.
-
-**Enter doesn't submit the form.** The real `<input>` lives in shadow DOM, so
-it isn't a light-DOM member of the `<form>`, and pressing Enter won't trigger
-native implicit submission — a deliberate choice, since auto-submitting a
-half-filled multi-field form is usually more annoyance than help. To submit on
-Enter, handle it yourself (`onKeyDown` → `form.requestSubmit()`), or reach for
-Anta's upcoming `<Form>` component. Everything else — value submission under
-`name`, `checkValidity()`, `formReset` — works natively.
+Try submitting an empty email, an invalid address, or an age outside the range.
+Use **Submit** to send the form. Input does not submit automatically on Enter.
 
 ## Layout
 
-The label, field, and hint **aren't hardcoded to "stacked."** The element lays
-them out as a single-column **grid** (hence the default label-above / hint-below
-rhythm) and exposes each region as a shadow part (`label`, `field`, `hint`).
-Rearrange them from your own CSS: re-template the grid on `a-input`, then place
-the parts. No layout prop to learn — your rule wins because the element's
-defaults live in `@layer anta`.
+Labels appear above their fields and hints below. Use CSS to move a label
+beside its field, align labels across a form, or place a hint alongside a field.
+The examples show the selectors to use.
 
-And because each `<a-input>` is itself a normal grid/flex item, **wrapping** is
-just sizing: give the inputs a `min-width` (and maybe `max-width`) inside any
-wrapping container and they reflow by available width — the field's internal
-grid is independent of how the fields themselves flow.
+You can also arrange whole fields in columns or let them wrap as the available
+space changes.
 
-The `.label-side` / `.aligned-form` / `.wrap-fields` classes below are only to
-scope each demo — swap your own selector.
+The classes below scope each example. Replace them with your own selectors.
 
 ### Label on the left
 
-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.
+Use two columns for the label and field. Place the hint in the field's column.
 
 ```tsx
 <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>{`
   a-input.label-side {
     grid-template-columns: max-content minmax(0, 1fr);
@@ -392,10 +370,8 @@ under the field by landing in the same column.
 
 ### Label column
 
-Put the fields in a grid and let each one adopt the form's tracks with
-`grid-template-columns: subgrid` — which reaches *through* the shadow boundary,
-so every label shares one column sized to the longest label, and every field
-left-edge lines up. Each hint still tucks under its own field.
+Keep labels in a shared column so fields line up even when their labels have
+different lengths. Each hint stays with its field.
 
 ```tsx
 <div className="aligned-form">
@@ -405,7 +381,6 @@ left-edge lines up. Each hint still tucks under its own field.
 </div>
 
 <style>{`
-  /* one shared label column; subgrid lets each field adopt the form's tracks */
   .aligned-form { display: grid; grid-template-columns: max-content minmax(0, 1fr); gap: 16px 12px; }
   .aligned-form > a-input { grid-column: 1 / -1; grid-template-columns: subgrid; align-items: center; }
   .aligned-form > a-input::part(label) { grid-column: 1; }
@@ -416,9 +391,8 @@ left-edge lines up. Each hint still tucks under its own field.
 
 ### Hint on the right
 
-Put the hint beside the field instead of under it — a short note, a counter, a
-unit. Two columns (field, then hint); the label spans the top, and the hint
-centers against the field.
+Place a short hint or counter beside the field. The label spans both columns,
+and the hint aligns vertically with the field.
 
 ```tsx
 <Input className="hint-right" label="Username" hint="3–20 characters" placeholder="ada" autoComplete="username" />
@@ -436,9 +410,8 @@ centers against the field.
 
 ### Wrap by field width
 
-Leave the fields stacked and let an outer grid flow them into as many columns as
-fit — `minmax(200px, 1fr)` makes each field claim at least 200px, so the row
-wraps to fewer columns as it narrows. Resize the preview to see it reflow.
+Let fields share a row when there is room and wrap when space is limited.
+Narrow the preview to see the layout adjust.
 
 ```tsx
 <div className="wrap-fields">
@@ -449,7 +422,6 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
 </div>
 
 <style>{`
-  /* fields stay stacked; the grid wraps them by available width */
   .wrap-fields { display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 16px; }
 `}</style>
 ```
@@ -458,56 +430,87 @@ wraps to fewer columns as it narrows. Resize the preview to see it reflow.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `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`. |
+| `autoComplete?` | 'off' \| 'on' \| 'name' \| 'username' \| 'email' \| 'current-password' \| 'new-password' \| 'one-time-code' \| 'tel' \| 'url' \| (string & {}) | — | Native autocomplete token describing the field purpose. Overrides the token derived from the email, tel, or url type. Set an explicit token for other purposes, such as `username`, `current-password`, or `one-time-code`. |
 | `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. |
-| `dimActions?` | boolean | — | Dim the `leading` / `trailing` adornments at rest; they brighten to full when the field is hovered or focused (a quiet-until-engaged affordance for trailing actions). |
+| `children?` | ReactNode | — | Extra content between the field and hint. A `Tooltip` child anchors to the field. Use `leading` and `trailing` for content inside the field. |
+| `clearable?` | boolean | — | Show a clear button before trailing content when an editable field has a value. |
+| `defaultValue?` | string | — | Initial value for an uncontrolled field, restored on form reset. |
+| `dimActions?` | boolean | — | Keep leading, trailing, and clear content subtle until someone hovers over or focuses the field. |
 | `disabled?` | boolean | — | Disable the field. |
-| `hint?` | ReactNode | — | Message below the field. Neutral helper text by default; `status` recolors it and prefixes the matching glyph. |
-| `inputMode?` | 'none' \| 'text' \| 'decimal' \| 'numeric' \| 'tel' \| 'search' \| 'email' \| 'url' | — | Virtual-keyboard hint. Overrides the value derived from `type`. |
-| `label?` | ReactNode | — | Field label, shown above the control. A string is rendered with the label type scale; pass a node for full control. Associated with the control as its accessible name (the element mirrors the label text to `aria-label`, since `<label for>` can't cross the shadow boundary). |
-| `leading?` | ReactNode | — | Content pinned to the start of the field (e.g. an icon). |
-| `max?` | number \| string | — |  |
-| `maxLength?` | number | — | Max input length. |
-| `maxRows?` | number | — | Cap the autogrow height (in rows) of a `multiline` field with no `rows`. Omit for unbounded growth. |
-| `min?` | number \| string | — | Min / max / step — for `type="number"`. |
-| `minLength?` | number | — | Min input length. |
-| `multiline?` | boolean | — | Render a `<textarea>` instead of an `<input>`. Without `rows` it grows with its content from one line (capped by `maxRows` if set). Autogrow uses CSS `field-sizing` where supported (Chrome/Edge, Safari ≥ 26.2) and falls back to a built-in JS resize elsewhere (Firefox, older Safari), so it grows in every browser. |
-| `name?` | string | — | Form field name — submitted with the form via ElementInternals. |
+| `hint?` | ReactNode | — | Persistent help or feedback below the field. `status` colors the message and adds a status icon. |
+| `inputMode?` | 'none' \| 'text' \| 'decimal' \| 'numeric' \| 'tel' \| 'search' \| 'email' \| 'url' | — | Virtual keyboard hint. Overrides the value derived from `type` without changing validation. |
+| `label?` | ReactNode | — | Explain what to enter. Accepts text or JSX and also names the field for screen readers. |
+| `leading?` | ReactNode | — | Content at the start of the field, such as an icon or text. |
+| `max?` | number \| string | — | Maximum value for `type="number"`. |
+| `maxLength?` | number | — | Maximum text length for native types that support it. |
+| `maxRows?` | number | — | Maximum row count for autogrow when `rows` is unset. Omit for unlimited growth. |
+| `min?` | number \| string | — | Minimum value for `type="number"`. |
+| `minLength?` | number | — | Minimum text length for native types that support it. |
+| `multiline?` | boolean | — | Allow longer text and grow the field as someone types. Use `maxRows` to limit growth or `rows` to keep a fixed height. |
+| `name?` | string | — | Form field name for submission, named form lookup, and attribute selectors. |
 | `onBlur?` | (e) => void | — | Fires when the field loses focus. |
-| `onChange?` | (e) => void | — | Fires on **commit** (blur / Enter) — the platform `change` semantics, **not** React's per-keystroke `onChange`. This is a web component, so `onChange` keeps the native meaning; reach for `onInput` (every keystroke) or `onValueChange` (both) for live updates. Read `e.target.value`. |
-| `onClearClick?` | (e) => void | — | Fires when the built-in clear button (`clearable`) is clicked, *before* the field is cleared. Call `e.preventDefault()` to keep the current value — the clear is cancelled and `onClearInput` won't fire. Backed by the element's cancelable, bubbling `clearclick` event. |
-| `onClearInput?` | (e) => void | — | Fires after the built-in clear button (`clearable`) has cleared the field — so `onInput` / `onChange` fire too — making this useful for reacting specifically to a clear. Doesn't fire if `onClearClick` cancelled the clear. Backed by the element's bubbling `clearinput` event. |
+| `onChange?` | (e) => void | — | Fires on native commit, such as blur or Enter, and on clear. Use `onInput` or `onValueChange` for live edits. Read `e.target.value`. |
+| `onClearClick?` | (e) => void | — | Fires before the built-in clear action. Call `e.preventDefault()` synchronously to keep the value and cancel `onClearInput`. Corresponds to the cancelable, bubbling `clearclick` event. |
+| `onClearInput?` | (e) => void | — | Fires after clearing, following `onInput` and `onChange`. Does not fire when clearing is canceled. Corresponds to the bubbling `clearinput` event. |
 | `onFocus?` | (e) => void | — | Fires when the field gains focus. |
-| `onInput?` | (e) => void | — | Fires on every keystroke. Read `e.target.value`. |
-| `onValueChange?` | (event, attrs) => void | — | Unified value-change handler — the easy path for state. Fires on `input` *and* `change` (and on clear), with the native `event` plus a convenience `attrs` snapshot (`value`, `name`, `empty`, `valid`, `validationMessage`) so you can do `setForm(s => ({ ...s, [attrs.name]: attrs.value }))` without digging into the event. Use `event.type` to tell a live edit (`input`) from a commit (`change`); read `id` / `type` / `className` off `event.target`. |
-| `pattern?` | string | — | Validation pattern (single-line). |
+| `onInput?` | (e) => void | — | Fires when editing changes the value or the field is cleared. Read `e.target.value`. |
+| `onValueChange?` | (event, attrs) => void | — | Receive the current text, field name, and validation result while editing and when an edit is committed, including clear. Can run more than once for the same value. Use `event.type` to distinguish the events. |
+| `pattern?` | string | — | Validation pattern for supported single-line types. Checks validity without preventing typing. |
 | `placeholder?` | string | — | Placeholder shown when empty. |
 | `priority?` | 'primary' \| 'secondary' \| 'tertiary' | primary | Field emphasis. `primary` has a fill and border, `secondary` keeps the border without a fill, and `tertiary` makes the border transparent until hover or focus. Status borders remain visible at rest. |
 | `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`). 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). |
+| `role?` | string | — | ARIA role for the native control, such as `combobox` for an InputAutocomplete trigger. The element delegates this and standard `aria-*` props to its native shadow control. |
+| `round?` | boolean \| number \| string | — | Give the field fully rounded corners. Pass a number in pixels or a CSS length for a custom radius. The clear button stays circular. |
+| `rows?` | number | — | Fixed visible row count. Also enables `multiline`. |
+| `size?` | 'small' \| 'medium' \| 'large' | medium | Adjust the field, text, icons, and action buttons together to suit the surrounding interface. |
 | `spellCheck?` | boolean | — | Toggle native spell-checking. |
-| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | — | Validation / feedback tone — colors the border + `hint` and prefixes a glyph. Only `critical` marks the field invalid (`aria-invalid`, blocks form submission, `:state(invalid)`); `success` / `warning` / `info` / `brand` are advisory and stay valid. Omit (or `neutral`) for a plain field. |
-| `statusIcon?` | (string & {}) \| false \| IconShape | — | Glyph shown before the `hint` when `status` is set. Each status has a default (critical → `warning-diamond`, warning → `warning-triangle`, success → `circle-check`, info → `info`, brand → `circle-small-solid`); pass a shape to override, or `false` to drop it. `neutral` has no default glyph. |
-| `step?` | number \| string | — |  |
-| `tone?` | string | — | Custom accent color — any literal CSS color tints the border when shown (focus ring stays the global `--focus-ring`). For consistency with the other controls' custom-tone knob; a `status` still overrides for validation. |
-| `trailing?` | ReactNode | — | Content pinned to the end of the field (e.g. icons, buttons), after the clear button when `clearable`. |
+| `status?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' | — | Feedback for the field and hint. Use `critical` for an error that must be fixed before submission. Other statuses provide feedback without adding a validation error. Required fields and other validation rules still apply. |
+| `statusIcon?` | (string & {}) \| false \| IconShape | — | Icon before the hint. The defaults are `warning-diamond` for critical, `warning-triangle` for warning, `circle-check` for success, `info` for info, and `circle-small-solid` for brand. Pass a shape to replace it or `false` to hide it. Neutral has no default icon. |
+| `step?` | number \| string | — | Allowed increment for `type="number"`. |
+| `tone?` | string | — | Custom CSS border color. A non-neutral `status` takes precedence. The focus ring uses the global `--focus-ring`. |
+| `trailing?` | ReactNode | — | Content at the end of the field, after the clear button. Anta buttons fit the field height and keep their padding. Icon-only Buttons are square; text buttons keep their natural width. Pass buttons directly or in a fragment for compact spacing. Other wrapping elements keep the text inset. Override either inset with the `--input-trailing-inset` CSS property. |
 | `truncate?` | boolean | true | Ellipsize an overflowing single-line value. Read-only inputs already do this; pass `false` when an editable field should show the full value. |
-| `type?` | 'text' \| 'search' \| 'email' \| 'password' \| 'tel' \| 'url' \| 'number' | text | Single-line input type. Ignored when `multiline`. `search` is a **wrapper-only** shorthand: it defaults a leading search icon and a clear button (both overridable — pass your own `leading`, or `clearable={false}`) and sets `inputmode="search"`, but the DOM input stays `type="text"`. The native `search` type never reaches the element, so the browser's own clear/search affordances never appear — Anta owns that chrome. |
-| `value?` | string | — | Controlled value. Pair with `onChange` / `onInput`. |
+| `type?` | 'text' \| 'search' \| 'email' \| 'password' \| 'tel' \| 'url' \| 'number' | text | Choose the kind of information to enter. Ignored for multiline fields. `search` adds a search icon and clear button. Replace the icon with `leading` or hide the button with `clearable={false}`. |
+| `value?` | string | — | Controlled value. Update it with `onInput` or `onValueChange` for live editing. |
 
 ## Web Component
 
-Use the web component directly when you are not using React or Preact and a native control does not fit.
+Use `<a-input>` directly outside React or Preact.
+
+Slots accept content; shadow parts expose regions for CSS. The `label`,
+`leading`, `clear`, `trailing`, and `hint` slots are independent of the parts
+with matching names. Unslotted children appear after the field and before the hint.
+
+Group trailing buttons in `<a-input-trailing slot="trailing">` to use compact
+action spacing. Mixed content keeps the text inset. The grouping tag needs no
+JavaScript registration.
+
+Anta buttons fit the field height and keep their own padding. Add
+`data-anta-icon-only` to a raw icon-only button for a square box. Text buttons
+keep their natural width. The JSX Button and ButtonCopy wrappers mark their
+icon-only actions automatically.
+
+Set `role` and `aria-*` on `<a-input>` to describe the field to assistive
+technology. Input applies them to the control that receives focus. Explicit
+names and descriptions take precedence over its label and hint.
 
-Slots hold the label, hint, and controls around the native field.
+The JSX `type="search"` shorthand uses a native text input. On a raw `<a-input>`,
+`type="search"` uses a native search input. Listen for `clearclick` and
+`clearinput` with `addEventListener()` to handle clearing without a JSX wrapper.
+
+The `name` property and attribute stay in sync. Updating either changes the
+submitted field name, `form.elements.namedItem()` lookup, and attribute selectors.
+Removing the name excludes the field from form submission.
+
+`checkValidity()`, `reportValidity()`, `validity`, `validationMessage`, and
+`willValidate` expose form validation. `status="critical"` adds a custom error;
+other statuses remain advisory. There is no public `setCustomValidity()` method.
+
+Use `rows` for a fixed height or `maxrows` to limit growth. Some browsers
+recalculate a growing field's height on the next value change after its width
+or font changes.
 
 ```html
 <a-input name="email" type="email" autocomplete="email" placeholder="you@example.com">
@@ -518,32 +521,27 @@ Slots hold the label, hint, and controls around the native field.
 
 ### Native HTML inputs
 
-For a standard HTML form, add `data-anta` to a native input. Text, search,
-email, telephone, URL, password, and number inputs keep their native editing,
-keyboard, validation, and form behavior while using Anta's field chrome. Search
-keeps its browser-supplied affordances; file keeps its native chooser and selected
-file name, with an Anta-styled chooser button. `submit` and `reset` inputs use the
-matching Anta button chrome; set `priority="primary"` on a submit control when it
-is the form's main action.
+Add `data-anta` to an HTML input to give it Anta styling while keeping its
+usual browser behavior. Search and file inputs keep their built-in controls.
+Submit and reset inputs look like Anta buttons. Use `priority="primary"` for
+the form's main action.
 
-`<textarea data-anta>` uses the same field chrome. Set `rows` for its height; one
-field-height is the minimum, and it resizes vertically. Native textareas do not
-autogrow; use Input's [`multiline`](#multiline) instead.
+Use `<textarea data-anta>` for longer text with a manually resizable height.
+For a field that grows as someone types, use [multiline Input](#multiline).
 
-Use `data-anta-size="small"` or `"large"` for field sizing. Native inputs own
-their `size` attribute, so Anta does not reuse it. `round` and a custom-color
-`tone` work the same way as Input.
+Choose a size with `data-anta-size="small"` or `"large"`.
+Use `round` for rounded corners and `tone` for a custom border color.
 
 ```html
-<input data-anta data-anta-size="small" type="text" name="name" placeholder="Small text">
-<input data-anta type="search" name="search" placeholder="Search">
-<input data-anta type="email" name="email" placeholder="Email">
-<input data-anta type="tel" name="phone" placeholder="Telephone">
-<input data-anta round type="url" name="site" placeholder="Rounded URL">
-<input data-anta type="password" name="password" value="password">
-<input data-anta tone="rebeccapurple" type="number" name="seats" value="3" min="1">
-<textarea data-anta rows="3" name="notes" placeholder="Notes"></textarea>
-<input data-anta type="file" name="attachment" accept=".pdf,.docx">
+<input data-anta data-anta-size="small" type="text" name="name" aria-label="Name" placeholder="Small text">
+<input data-anta type="search" name="search" aria-label="Search" placeholder="Search">
+<input data-anta type="email" name="email" aria-label="Email" placeholder="Email">
+<input data-anta type="tel" name="phone" aria-label="Telephone" placeholder="Telephone">
+<input data-anta round type="url" name="site" aria-label="Website" placeholder="Rounded URL">
+<input data-anta type="password" name="password" aria-label="Password" value="password">
+<input data-anta tone="rebeccapurple" type="number" name="seats" aria-label="Seats" value="3" min="1">
+<textarea data-anta rows="3" name="notes" aria-label="Notes" placeholder="Notes"></textarea>
+<input data-anta type="file" name="attachment" aria-label="Attachment" accept=".pdf,.docx">
 
 <input data-anta type="submit" value="Submit" priority="primary">
 <input data-anta type="reset" value="Reset">
@@ -551,82 +549,78 @@ their `size` attribute, so Anta does not reuse it. `round` and a custom-color
 
 ## Styling
 
-Reach for the props first: **`priority`** sets the field surface,
-**`status`** a validation tone (border + message), **`tone`** a custom accent
-color for the border (any CSS color), and **`size`** the dimensions. The focus
-ring is the global [`--focus-ring`](../colors.md#focus-ring).
+Use `priority` for the field surface, `status` for feedback, `tone` for a custom
+border color, and `size` for dimensions. The focus ring uses the global
+[`--focus-ring`](../colors.md#focus-ring).
 
 ```tsx
 <Input tone="#e0457b" label="Custom accent" autoComplete="off" />
 ```
 
-For everything else, `<a-input>` is shadow-DOM — style its **parts** with plain
-CSS: `::part(field | input | label | leading | trailing | clear | hint)`, plus the
-`:state(filled)` / `:state(invalid)` state hooks and `:focus-within::part(field)`
-for the focused state. The clear button is a real `<a-button>` in the `clear` slot,
-so style it directly. `light-dark()` works too (Anta sets `color-scheme` from its
-theme toggle).
+Style shadow regions with `::part(field)`, `::part(input)`, `::part(input-label)`,
+`::part(label)`, `::part(leading)`, `::part(trailing)`, `::part(clear)`, and
+`::part(hint)`. Use `:state(filled)` for a nonempty value,
+`:state(invalid)` for critical status, and `:focus::part(field)` when the
+editable control is focused. Focus on a slotted action does not match this rule. The clear button lives in the light DOM, so target it
+with a regular selector. Use `light-dark()` for theme-specific colors.
+
+Set `--input-trailing-inset` to override the ending space for any trailing
+content. Text and mixed content use the field's text inset by default;
+buttons-only groups use compact spacing.
+
+In button fields, `::part(input)` targets the native button, and
+`::part(input-label)` targets its value or placeholder text. `::part(label)`
+targets the separate visible field label.
+
+Select uses the same field styling. See [Select styling](./select.md#styling) for
+trigger customization.
 
 ```css
 a-input::part(field) { border-radius: 999px; }
 a-input::part(input) { font-variant-numeric: tabular-nums; }
 a-input::part(label) { text-transform: uppercase; }
+a-input.custom-inset { --input-trailing-inset: 4px; }
 ```
 
-The border is drawn as an **inset `box-shadow`**, so its width (`0.5px` at rest,
-including tertiary's transparent border, and `1px` on hover, focus, or
-non-neutral status)
-never changes the box size. The field height stays aligned with `Button`.
-Drop the leading `inset` to draw the border as an outset ring instead. You can
-also re-point an `--input-*` color token on one instance
-(`style={{ '--input-border': 'var(--border-1)' }}`)
-or a wrapping selector; the resolver lives in `@layer anta`, so any un-layered rule
-of yours wins.
+To remove the field's border, use `box-shadow: none` as shown in the example.
 
-The `.fancy` class is just for the demo — a borderless pill that fills dark-grey
-and darkens on focus in light mode, and the inverse in dark:
+If your policy blocks inline styles, set custom colors and dimensions in an
+external stylesheet. See [Content Security Policy](../install-config.md#content-security-policy)
+for customization props that emit inline styles.
+
+Some browsers may show native number steppers or controls on a raw
+`<a-input type="search">`. These keep their browser behavior. The JSX
+`<Input type="search">` uses a text input with Anta's own search icon and clear
+button.
+
+This example creates a borderless pill with a dark fill in light mode and a
+light fill in dark mode. The fill changes on focus.
 
 ```css
-/* a borderless pill — the resting border is a box-shadow, so clear it. Dark-grey
-   fill that darkens on focus, white text; the inverse in dark mode via light-dark()
-   (Anta drives color-scheme from its theme toggle). */
 a-input.fancy::part(field) {
   border-radius: 999px;
-  box-shadow: none;                          /* remove the box-shadow border */
+  box-shadow: none;
   background: light-dark(#3a3a3a, #ececec);
   padding-block: 10px;
-  padding-inline: 20px;                      /* roomier */
+  padding-inline: 20px;
 }
 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); }
+a-input.fancy:focus::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 |
+Use placeholders for example values or formatting cues. Keep an accessible
+name and put essential instructions in a persistent label or hint.
 
-`#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.
+Keep placeholder text readable against the field background in both light and
+dark themes. See W3C's [placeholder contrast guidance](https://www.w3.org/WAI/tutorials/forms/instructions/#styling).
 
-This demo uses `#767676` on white in every state and theme.
+This example uses a darker placeholder on a fixed light background.
 Replace `.placeholder-contrast` with your own class.
 
 ```tsx