prime-ui-kit 0.20.1 → 0.21.1

package/src/components/drawer/COMPONENT.md

@@ -8,7 +8,7 @@
 ## When to use
 - Editing settings or a record without leaving the page.
 - Filters or navigation on narrow screens (`side="left"`).
-- Read-only details of a list row (order, user, event), with its status and a ⋯ menu in the header (`Drawer.Actions`).
+- Read-only details of a list row (order, user, event), with its status under the title (`Drawer.Description`) and a ⋯ menu in the header (`Drawer.Actions`).
 - Long content (history, logs) that needs a tall scrolling area.
 
 ## When not to use
@@ -30,13 +30,14 @@ Drawer.Root                    state and dismiss policy (no DOM)
 └─ Drawer.Content              portal + scrim + role="dialog" panel at the side
    ├─ Drawer.Guard             no DOM: holds the drawer (busy / dirty) from inside
    ├─ Drawer.Header            grid: [Icon] [Title + Description] [Actions] [close Button]
-   │  ├─ Drawer.Icon           tone tile around an Icon, or an Avatar.Root / Thumbnail.Root with no tile
-   │  ├─ Drawer.Title          <h2>
-   │  ├─ Drawer.Description    <p>
-   │  └─ Drawer.Actions        row of tier-s controls before the close button
+   │  ├─ Drawer.Icon           tone tile around an Icon, or the record's Avatar / Thumbnail, no tile, 40
+   │  ├─ Drawer.Title          line 1: <h2>; `loading` holds it with a skeleton
+   │  ├─ Drawer.Description    line 2: <p>; the record's status Badges lead it (tier s), then the text
+   │  └─ Drawer.Actions        buttons only (icon buttons, a ⋯ Dropdown), tier s, on the title's line
    ├─ Drawer.Body              the only scrolling zone (ScrollContainer)
    │  └─ Drawer.Section        <section>: <h3> label, description, Drawer.Actions at the heading's end
    └─ Drawer.Footer            always: Close or Cancel + the main action, primary last
+      ├─ Drawer.Actions        the start group: an action apart from the main pair
       ├─ Drawer.Meta           <p>, muted status at the start
       └─ Drawer.Close          clones its child; closes on click
 ```
@@ -81,19 +82,19 @@ No DOM, no ref. State and dismiss policy.
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `className` and the other attributes of the `<header>`. |
 
 ### Drawer.Actions
-`ref` → `HTMLDivElement`. A row of controls at the end of the header, before the close button: a status Badge, a ⋯ Dropdown; under the title when it would get less than 12rem; or at the end of a `Drawer.Section` heading. Controls inside take tier `s`.
+`ref` → `HTMLDivElement`. Header buttons only (icon buttons, a ⋯ Dropdown; a status goes in `Drawer.Description`), tier `s`, on the title's line; under it below 12rem; at the end of a `Drawer.Section` heading. In `Drawer.Footer`: the start group at the footer tier.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `children` and the other attributes of the row. |
 
 ### Drawer.Icon
-`ref` → `HTMLSpanElement`. An `aria-hidden` 40 px tile with a tone fill; around an `Avatar.Root` or a `Thumbnail.Root` (the record's picture) no tile — `data-media`, the avatar sized to 40 px.
+`ref` → `HTMLSpanElement`. An `aria-hidden` 40 px tile with a tone fill; around the record's picture (an `Avatar.Root` or a `Thumbnail.Root` anywhere inside, also from your own component) no tile (`data-media`), the picture at 40 px.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` | Soft fill and icon color; not used around a picture. |
-| `children` | `ReactNode` | — (required) | An `Icon` (sized to the m icon), or the record's picture: an `Avatar.Root` (sized to the tile) or a `Thumbnail.Root`. |
+| `children` | `ReactNode` | — (required) | An `Icon` (sized to the m icon), or the record's picture: an `Avatar.Root` (size `l`) or a `Thumbnail.Root` (size `m`), set by the slot. |
 | `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the tile. |
 
 ### Drawer.Title
@@ -101,10 +102,11 @@ No DOM, no ref. State and dismiss policy.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `loading` | `boolean` | `false` | The name loads (a record opened by a link): a `Skeleton` holds the title line and `aria-busy` is set, so the header never moves; the name fades in. |
 | `…rest` | `Omit<HTMLAttributes<HTMLHeadingElement>, "id">` | — | `className`, `children` and the other attributes except `id` (the dialog owns it). |
 
 ### Drawer.Description
-`ref` → `HTMLParagraphElement`. `<p>` (body-s, muted) under the title; its id describes the dialog.
+`ref` → `HTMLParagraphElement`. `<p>` (body-s, muted) under the title; its id describes the dialog. The record's status `Badge.Root`s go here: first in the line, chip tier `s` (20 px), the text wraps under them when narrow.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -128,7 +130,7 @@ No DOM, no ref. State and dismiss policy.
 | `…rest` | `Omit<HTMLAttributes<HTMLElement>, "title">` | — | `children` (the content and an optional `Drawer.Actions`), `className` and the other attributes of the `<section>`. |
 
 ### Drawer.Footer
-`ref` → `HTMLElement`. Renders `<footer>` with the actions, primary last, and an optional `Meta` at the start.
+`ref` → `HTMLElement`. Renders `<footer>` with the actions, primary last; at the start an optional `Drawer.Actions` (an action apart from the main pair) and `Meta`. Stacked, the start comes first and the primary stays last.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -182,7 +184,7 @@ Below 640px of viewport every size is full width and loses its corners.
 | `fill` | equal-width buttons in one row | one full-width action («Понятно») | |
 
 ### tone (Icon)
-`neutral` (default) · `accent` · `success` · `warning` · `danger` · `info` — soft tile fill and icon color, as in Modal. Around the record's picture — an `Avatar.Root` or a `Thumbnail.Root` (found by element type) — there is no tile and no tone: `data-media`, the avatar sized to 40 px, so a person's or an object's card shows its picture in the header.
+`neutral` (default) · `accent` · `success` · `warning` · `danger` · `info` — soft tile fill and icon color, as in Modal. Around the record's picture — an `Avatar.Root` or a `Thumbnail.Root` anywhere inside, also from your own wrapper component (`<ClientAvatar />`) — there is no tile and no tone: `data-media`, and the picture takes the tile's 40 px (avatar `l`, thumbnail `m`) whatever `size` it was given, so every record header has the same mark.
 
 ## States
 | State | Driven by | DOM |
@@ -195,16 +197,29 @@ Below 640px of viewport every size is full width and loses its corners.
 | busy | `Drawer.Guard busy` | Escape, the scrim, the close button and `Drawer.Close` do nothing; the close button and the `Close` child are `disabled` in place |
 | dirty | `Drawer.Guard dirty` | a dismiss opens the «Не сохранять изменения?» ConfirmDialog (`labels.discard*`); its confirm closes the drawer |
 | leaving the tab | `Drawer.Guard busy` or `dirty` | the browser asks before the tab closes or reloads (`beforeunload`), as with `Page.Guard` |
+| title loading | `Drawer.Title loading` | a `Skeleton` holds the title line, `aria-busy` on the `<h2>`; the name fades in under the same element |
 | description loading | `Drawer.Description loading` | a `Skeleton` holds the line, `aria-busy` on the `<p>`; the data fades in under the same element |
 | actions below | the title would get less than 12rem beside `Drawer.Actions` | `data-actions-below` on the header: the actions move under the title and the description |
+| picture mark | an `Avatar.Root` or a `Thumbnail.Root` inside `Drawer.Icon` | `data-media` on the icon, no tile; the picture's `data-size` is the slot's (`l` / `m`) |
+| status in the line | a `Badge.Root` inside `Drawer.Description` | the line is a wrapping flex row, the badges first (`order`), each `data-tier="s"` |
 
 Motion: the scrim fades, the panel slides from its side over `slow` and leaves over `base` (`overlayMotion`); under `prefers-reduced-motion` it unmounts at once. The drawer has no touch gestures: it is not dragged or swiped away — it closes by its buttons, Escape and the scrim, with the same slide-out.
 
 ## Layout & spacing
+- The header has one anatomy, the same in every drawer, modal and sheet:
+  ```
+  [mark]  Title                                [icon buttons] [⋯] [×]
+          [status badges] description text
+  ```
+  - mark — `Drawer.Icon`: a glyph on the tone tile, or the record's picture (`Avatar.Root`, `Thumbnail.Root`) with no tile; both are 40 px, so the header never changes its height between a person and a setting.
+  - line 1 — `Drawer.Title`, the record's name.
+  - line 2 — `Drawer.Description`: the record's statuses as `Badge.Root`s first, then its text (an email, a handle, «Заказ № 1042 · 3 коробки»). The kit sizes the badges (chip tier `s`, the line's own 20 px), keeps them first and one gap apart, and wraps the text under them on a narrow panel. A status belongs to the record, so it lives on its line, never next to the buttons.
+  - end — `Drawer.Actions`: only buttons — ghost icon buttons, each named and with a Tooltip, and a ⋯ Dropdown for the rest — at the close button's tier, centred on the title's line.
 - A drawer has three zones: `Drawer.Header` (title, the × close button), `Drawer.Body` (the content, the only zone that scrolls) and `Drawer.Footer` (the actions). The footer is not optional decoration — it is where the drawer is finished:
   - read-only details: `Drawer.Close` around `<Button.Root variant="outline" tone="neutral">Закрыть</Button.Root>`, plus the record's main action (solid, last) when it has one;
   - a form: «Отмена» (`Drawer.Close`, outline neutral) and the submit button (solid, last; `type="submit" form={formId}`), `Drawer.Meta` for «Есть несохранённые изменения»;
-  - one acknowledgement: `<Drawer.Footer layout="fill">`.
+  - one acknowledgement: `<Drawer.Footer layout="fill">`;
+  - an action apart from the main pair («Выйти», «Удалить» — the latter through a ConfirmDialog): `Drawer.Actions` inside the footer puts it at the start, at the footer's tier; stacked on a phone it comes first and the primary stays last.
   Both the header × and the footer button stay: the × is the quick way out at the top, the footer is the end of the reading or editing path, where the hand already is.
 - Zone padding `--prime-drawer-padding`; hairlines between header, body and footer.
 - Full viewport height; only the body scrolls, with its own side padding.
@@ -212,8 +227,9 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 - Fields inside get the surface field fill.
 - Titled groups of the body (a record's contacts, its deals, its history): `Drawer.Section label` — an `<h3>` under the drawer's `<h2>` title, an optional `description`, a `Drawer.Actions` at the end of its heading row; content 16 below, sections 32 apart — directly in the body, in a `Tabs.Panel` or in a form, with no spacing wrapper of your own. A group of fields is a `Fieldset`; a page section is `Page.Section`.
 - With a `Drawer.Meta` the buttons stay one row: when the footer runs short the status goes above them first.
-- `Drawer.Actions` keep their place beside the title while it has 12rem; on a phone, where a status and a ⋯ beside the × would fold the title into letters, they move under it by themselves.
-- A record whose data is still loading: the title from the list row, `Drawer.Description loading` and a `Skeleton` body in the data's geometry under a `Crossfade` — not a skeleton of your own in the header.
+- `Drawer.Actions` keep their place beside the title while it has 12rem; on a phone, where the buttons beside the × would fold the title into letters, they move under it by themselves.
+- Opening a record: the header and its tabs come at once, the body as a `Skeleton` in the data's geometry. A record opened from a list row comes with the data the row already has (its title, often its status) at once, and only the rest loads (`Drawer.Description loading`); a record opened by a link knows only its id, so `Drawer.Title loading` holds the title line too. Read-only data swaps under a `Crossfade`; a form gets no `Crossfade` around it — its fields render once the record is there, so typing and focus are never cross-faded. Never a skeleton of your own in the header.
+- Focus on open lands on the panel itself, so a header action (a ⋯ with a Tooltip) is not focused and its tooltip does not pop up; a form that should start typing at once puts `autoFocus` on its first field.
 
 ## Accessibility
 
@@ -229,7 +245,7 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 - `role="dialog"`, `aria-modal="true"`, named by `Drawer.Title` (or `aria-label`), described by `Drawer.Description`.
-- Focus moves into the panel on open and returns to the opener on close, including after a scrim click.
+- On open focus moves to the panel itself (its title and description are read; an `autoFocus` field wins), without the ring after a click; Tab goes on to the first control. On close it returns to the opener, including after a scrim click.
 - The page behind is `inert`, scroll is locked; only the topmost layer reacts.
 - A drawer opened from a Modal stacks above it.
 - No swipe: the close button, `Drawer.Close`, Escape and the scrim are the ways out.
@@ -253,9 +269,11 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 | [structure.tsx](examples/structure.tsx) | Optional parts: an icon tile in the header and one full-width action in the footer — `Drawer.Icon`, `Drawer.Footer`, `layout`. |
 | [sizes.tsx](examples/sizes.tsx) | Every panel width, 360 to 800 px; below 640 px of viewport the panel takes the full width — `size`. |
 | [placement.tsx](examples/placement.tsx) | The panel slides from the right for details and from the left for filters, rounded only on the edge facing the page — `side`. |
-| [header-actions.tsx](examples/header-actions.tsx) | A record card: its status and a ⋯ menu sit in the header before the close button, one tier smaller; on a phone, where the title has no room beside them, they move under it — `Drawer.Actions`. |
+| [header-actions.tsx](examples/header-actions.tsx) | The one header of a record: the avatar, the name, its statuses leading the line under it, and only buttons at the end — `Drawer.Icon`, `Drawer.Description`, `Drawer.Actions`. |
+| [footer-actions.tsx](examples/footer-actions.tsx) | A profile panel: Sign out stands apart at the start of the footer, the main pair keeps the end; on a phone the column puts it first and the primary last — `Drawer.Footer`, `Drawer.Actions`. |
 | [client-card.tsx](examples/client-card.tsx) | A client card from the list: the contact's avatar heads the panel in place of an icon tile, then the details in titled sections, one with its own action — `Drawer.Icon`, `Avatar.Root`, `Drawer.Section`, `Drawer.Actions`. |
 | [loading.tsx](examples/loading.tsx) | A record card that opens before its data arrives: the title comes from the list row, the line under it and the body hold their place in skeletons, then the data fades in — `Drawer.Description`, `loading`. |
+| [link-loading.tsx](examples/link-loading.tsx) | A record opened by a link knows only its id: the title and the line under it hold their place in skeletons, the body keeps the data's geometry, then the name and the data fade in — `Drawer.Title`, `loading`. |
 | [guard.tsx](examples/guard.tsx) | A form that holds the drawer from inside: after an edit Escape, the scrim and Cancel ask before discarding, the footer says so, and saving locks every way out — `Drawer.Guard`, `Drawer.Meta`. |
 | [long-content.tsx](examples/long-content.tsx) | A long body scrolls on its own while the header and the footer stay in place — `Drawer.Body`. |
 | [dismiss.tsx](examples/dismiss.tsx) | An import closes only from its buttons, and not at all while it runs — `closeOnOutsideClick`, `closeOnEscape`. |
@@ -269,15 +287,19 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 - A delete confirmation in a Drawer → use ConfirmDialog.
 - A hand-made heading row (`Typography as="h3"` + buttons) over a group in the body → `Drawer.Section label` with `Drawer.Actions`.
 - A wrapper with its own gap around `Drawer.Section`s inside a `Tabs.Panel` or a form → not needed: sections keep 32 between them in any wrapper.
-- A `Skeleton` placed by hand in `Drawer.Description` while the record loads → `Drawer.Description loading`.
+- A `Skeleton` placed by hand in `Drawer.Title` or `Drawer.Description` while the record loads → their `loading`; a placeholder title that shifts the header when the name arrives → `Drawer.Title loading`.
+- A start-side button («Выйти») put inside `Drawer.Meta` → `Drawer.Actions` inside `Drawer.Footer`; `Meta` is status text only.
 - Busy or unsaved state lifted out of the form into Root props → put `Drawer.Guard` next to the form, inside Content.
 - Clearing the record together with `open` and rendering a skeleton for «no record» → not needed: the panel keeps its last content while it slides out.
-- A Badge or a menu as a custom child of the header text column → put them in `Drawer.Actions`.
+- A status `Badge` in the header's `Drawer.Actions`, beside the buttons → put it in `Drawer.Description`, before the text: the kit sizes it to the line and keeps it first.
+- A menu or a button as a custom child of the header text column → put it in `Drawer.Actions`.
+- A Badge with its own `size` in `Drawer.Description` → leave `size` out: the line gives every header the same chip tier.
+- An avatar wrapped in its own box, or given its own `size`, in `Drawer.Icon` → pass the `Avatar.Root` (or your component that renders it) as it is: the slot drops the tile and sets 40 px.
 - Expecting Enter to submit via `Drawer.Confirm` → Drawer has no Confirm; use a `<form>` with a submit button.
 - `side="top"` or `side="bottom"` → only `left` and `right`; a panel from the bottom edge is a [Sheet](../sheet/COMPONENT.md).
 - Expecting a swipe to close a drawer → it has none; keep the header × and a footer button. A panel that swipes away is a [Sheet](../sheet/COMPONENT.md).
 - Padding on a wrapper inside Body → Body already pads and scrolls.
 
 ## Related
-- **Built from:** the dialog shared with Modal and Sheet (`internal/overlay/DialogParts`), [Button](../button/COMPONENT.md) (close button), [ScrollContainer](../scroll-container/COMPONENT.md) (`Drawer.Body`), [Avatar](../avatar/COMPONENT.md) and [Thumbnail](../thumbnail/COMPONENT.md) (a record's picture in `Drawer.Icon`), [Skeleton](../skeleton/COMPONENT.md) (`Drawer.Description loading`), [ConfirmDialog](../confirm-dialog/COMPONENT.md) (the `Drawer.Guard` discard confirm), `Icon` (the close glyph)
+- **Built from:** the dialog shared with Modal and Sheet (`internal/overlay/DialogParts`), [Button](../button/COMPONENT.md) (close button), [ScrollContainer](../scroll-container/COMPONENT.md) (`Drawer.Body`), `internal/mediaSlot` (a record's Avatar or Thumbnail in `Drawer.Icon`), [Skeleton](../skeleton/COMPONENT.md) (`Drawer.Title loading`, `Drawer.Description loading`), [ConfirmDialog](../confirm-dialog/COMPONENT.md) (the `Drawer.Guard` discard confirm), `Icon` (the close glyph)
 - **See also:** [Modal](../modal/COMPONENT.md) (the same header, body, footer and `Guard` in the centre), [Sheet](../sheet/COMPONENT.md) (the same parts raised from the bottom edge for a short task), [ConfirmDialog](../confirm-dialog/COMPONENT.md) (a destructive confirm), [Sidebar](../../layout/sidebar/COMPONENT.md), [Popover](../popover/COMPONENT.md), [Avatar](../avatar/COMPONENT.md) (a person's picture in `Drawer.Icon`)

package/src/components/drawer/examples/footer-actions.tsx

@@ -0,0 +1,54 @@
+/** A profile panel: Sign out stands apart at the start of the footer, the main pair keeps the end; on a phone the column puts it first and the primary last — `Drawer.Footer`, `Drawer.Actions`. */
+import { Avatar, Button, DescriptionList, Drawer, Icon } from "prime-ui-kit";
+
+const PROFILE = {
+  name: "Игорь Лебедев",
+  role: "Менеджер по продажам",
+  email: "i.lebedev@sev-veter.ru",
+  team: "Продажи · Москва",
+};
+
+export default function DrawerFooterActionsExample() {
+  return (
+    <Drawer.Root>
+      <Drawer.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Открыть профиль
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Content size="s">
+        <Drawer.Header>
+          <Drawer.Icon>
+            <Avatar.Root color="green">
+              <Avatar.Fallback>ИЛ</Avatar.Fallback>
+            </Avatar.Root>
+          </Drawer.Icon>
+          <Drawer.Title>{PROFILE.name}</Drawer.Title>
+          <Drawer.Description>{PROFILE.role}</Drawer.Description>
+        </Drawer.Header>
+        <Drawer.Body>
+          <DescriptionList.Root>
+            <DescriptionList.Item label="Почта">{PROFILE.email}</DescriptionList.Item>
+            <DescriptionList.Item label="Команда">{PROFILE.team}</DescriptionList.Item>
+          </DescriptionList.Root>
+        </Drawer.Body>
+        <Drawer.Footer>
+          <Drawer.Actions>
+            <Button.Root variant="ghost" tone="danger">
+              <Button.Icon>
+                <Icon name="action.logout" />
+              </Button.Icon>
+              Выйти
+            </Button.Root>
+          </Drawer.Actions>
+          <Drawer.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Закрыть
+            </Button.Root>
+          </Drawer.Close>
+          <Button.Root>Изменить</Button.Root>
+        </Drawer.Footer>
+      </Drawer.Content>
+    </Drawer.Root>
+  );
+}

package/src/components/drawer/examples/header-actions.tsx

@@ -1,11 +1,22 @@
-/** A record card: its status and a ⋯ menu sit in the header before the close button, one tier smaller; on a phone, where the title has no room beside them, they move under it — `Drawer.Actions`. */
-import { Badge, Button, DescriptionList, Drawer, Dropdown, Icon } from "prime-ui-kit";
+/** The one header of a record: the avatar, the name, its statuses leading the line under it, and only buttons at the end — `Drawer.Icon`, `Drawer.Description`, `Drawer.Actions`. */
+import {
+  Avatar,
+  Badge,
+  Button,
+  DescriptionList,
+  Drawer,
+  Dropdown,
+  Icon,
+  Tooltip,
+} from "prime-ui-kit";
 
-const DEAL = {
-  title: "Сделка №1042",
-  client: "ООО «Северный ветер»",
-  amount: "480 000 ₽",
-  owner: "Анна Соколова",
+const MEMBER = {
+  name: "Анна Соколова",
+  initials: "АС",
+  email: "a.sokolova@severnyveter.ru",
+  role: "Менеджер",
+  team: "Продажи",
+  since: "12 марта 2024",
 };
 
 export default function DrawerHeaderActionsExample() {
@@ -13,46 +24,56 @@ export default function DrawerHeaderActionsExample() {
     <Drawer.Root>
       <Drawer.Trigger>
         <Button.Root variant="soft" tone="neutral">
-          Открыть сделку
+          Открыть сотрудника
         </Button.Root>
       </Drawer.Trigger>
       <Drawer.Content>
         <Drawer.Header>
-          <Drawer.Title>{DEAL.title}</Drawer.Title>
-          <Drawer.Description>{DEAL.client}</Drawer.Description>
+          <Drawer.Icon>
+            <Avatar.Root color="purple">
+              <Avatar.Fallback>{MEMBER.initials}</Avatar.Fallback>
+            </Avatar.Root>
+          </Drawer.Icon>
+          <Drawer.Title>{MEMBER.name}</Drawer.Title>
+          <Drawer.Description>
+            <Badge.Root color="blue">{MEMBER.role}</Badge.Root>
+            <Badge.Root tone="success">Активна</Badge.Root>
+            {MEMBER.email}
+          </Drawer.Description>
           <Drawer.Actions>
-            <Badge.Root tone="success">Выиграна</Badge.Root>
+            <Tooltip.Root>
+              <Tooltip.Trigger>
+                <Button.Root variant="ghost" tone="neutral" aria-label="Скопировать ссылку">
+                  <Button.Icon>
+                    <Icon name="action.copy" />
+                  </Button.Icon>
+                </Button.Root>
+              </Tooltip.Trigger>
+              <Tooltip.Content>Скопировать ссылку</Tooltip.Content>
+            </Tooltip.Root>
             <Dropdown.Root>
               <Dropdown.Trigger>
-                <Button.Root variant="ghost" tone="neutral" aria-label="Действия со сделкой">
+                <Button.Root variant="ghost" tone="neutral" aria-label="Действия с сотрудником">
                   <Button.Icon>
                     <Icon name="action.more" />
                   </Button.Icon>
                 </Button.Root>
               </Dropdown.Trigger>
               <Dropdown.Content>
-                <Dropdown.Item>Дублировать</Dropdown.Item>
-                <Dropdown.Item>Скопировать ссылку</Dropdown.Item>
+                <Dropdown.Item>Сменить роль</Dropdown.Item>
+                <Dropdown.Item>Сбросить пароль</Dropdown.Item>
                 <Dropdown.Separator />
-                <Dropdown.Item tone="danger">Удалить сделку</Dropdown.Item>
+                <Dropdown.Item tone="danger">Отключить доступ</Dropdown.Item>
               </Dropdown.Content>
             </Dropdown.Root>
           </Drawer.Actions>
         </Drawer.Header>
         <Drawer.Body>
           <DescriptionList.Root>
-            <DescriptionList.Item label="Сумма">{DEAL.amount}</DescriptionList.Item>
-            <DescriptionList.Item label="Ответственный">{DEAL.owner}</DescriptionList.Item>
+            <DescriptionList.Item label="Команда">{MEMBER.team}</DescriptionList.Item>
+            <DescriptionList.Item label="В компании с">{MEMBER.since}</DescriptionList.Item>
           </DescriptionList.Root>
         </Drawer.Body>
-        <Drawer.Footer>
-          <Drawer.Close>
-            <Button.Root variant="outline" tone="neutral">
-              Закрыть
-            </Button.Root>
-          </Drawer.Close>
-          <Button.Root>Выставить счёт</Button.Root>
-        </Drawer.Footer>
       </Drawer.Content>
     </Drawer.Root>
   );

package/src/components/drawer/examples/link-loading.tsx

@@ -0,0 +1,57 @@
+/** A record opened by a link knows only its id: the title and the line under it hold their place in skeletons, the body keeps the data's geometry, then the name and the data fade in — `Drawer.Title`, `loading`. */
+import { Button, Crossfade, DescriptionList, Drawer, Skeleton } from "prime-ui-kit";
+import * as React from "react";
+
+const INVOICE = {
+  title: "Счёт №5521",
+  summary: "ООО «Северный ветер» · до 30 октября",
+  facts: [
+    ["Сумма", "248 000 ₽"],
+    ["Статус", "Ждёт оплаты"],
+    ["Выставлен", "16 октября"],
+  ],
+};
+
+export default function DrawerLinkLoadingExample() {
+  const [loading, setLoading] = React.useState(true);
+
+  const openChange = (open: boolean) => {
+    if (!open) return;
+    setLoading(true);
+    window.setTimeout(() => setLoading(false), 1200);
+  };
+
+  return (
+    <Drawer.Root onOpenChange={openChange}>
+      <Drawer.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          Открыть по ссылке
+        </Button.Root>
+      </Drawer.Trigger>
+      <Drawer.Content>
+        <Drawer.Header>
+          <Drawer.Title loading={loading}>{INVOICE.title}</Drawer.Title>
+          <Drawer.Description loading={loading}>{INVOICE.summary}</Drawer.Description>
+        </Drawer.Header>
+        <Drawer.Body>
+          <Crossfade state={loading ? "loading" : "data"} aria-busy={loading}>
+            <DescriptionList.Root>
+              {INVOICE.facts.map(([term, value]) => (
+                <DescriptionList.Item key={term} label={term}>
+                  {loading ? <Skeleton /> : value}
+                </DescriptionList.Item>
+              ))}
+            </DescriptionList.Root>
+          </Crossfade>
+        </Drawer.Body>
+        <Drawer.Footer>
+          <Drawer.Close>
+            <Button.Root variant="outline" tone="neutral">
+              Закрыть
+            </Button.Root>
+          </Drawer.Close>
+        </Drawer.Footer>
+      </Drawer.Content>
+    </Drawer.Root>
+  );
+}

package/src/components/drawer/examples/screen.tsx

@@ -128,8 +128,8 @@ export default function DrawerScreenExample() {
   return (
     <SmartFilter.Root fields={[]} search={search} onSearchChange={setSearch}>
       <Page.Root>
-        {/* A work screen titles itself in its top bar: the only h1, the counts under it, the search
-          and the one primary action — the Drawer trigger. */}
+        {/* A work screen titles itself in its top bar: the only h1, the counts under it and the one
+          primary action — the Drawer trigger. The table's search lives in the table's toolbar. */}
         <Page.TopBar>
           <Page.Heading>
             <Page.Title>Клиенты</Page.Title>
@@ -138,9 +138,6 @@ export default function DrawerScreenExample() {
               {plural(clients.length - people, COMPANY_WORDS)} и {people} ИП
             </Page.Description>
           </Page.Heading>
-          <Page.Tools aria-label="Клиенты">
-            <SmartFilter.Toolbar />
-          </Page.Tools>
           <Page.Actions>
             <Drawer.Root open={open} onOpenChange={changeOpen}>
               <Drawer.Trigger>
@@ -266,6 +263,7 @@ export default function DrawerScreenExample() {
             rows={shown}
             getRowKey={(row) => row.id}
             paging="none"
+            toolbar={<SmartFilter.Toolbar />}
             empty="Клиентов не найдено"
           />
         </Page.Body>

package/src/components/empty-page/COMPONENT.md

@@ -36,7 +36,7 @@ EmptyPage.Root               centered column; size, layout, tone (role="alert" w
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### EmptyPage.Root
-`ref` → `HTMLDivElement`. A centered column: icon tile, title, description, actions; parts rise in one after another on first render.
+`ref` → `HTMLDivElement`. A centered column: icon tile, title, description, actions; parts rise in one after another when it appears on a page already shown (a search or a filter that came to nothing); one that mounts with its page stands still.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -116,7 +116,7 @@ EmptyPage.Root               centered column; size, layout, tone (role="alert" w
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| first render | mount (not `compact`) | parts rise in (`enterMotion`), `--prime-motion-stagger` apart; collapses under reduced motion |
+| appearing | mounted on its own into a page already shown — a search or a filter that came to nothing (not `compact`) | parts rise in (`enterMotion`), `--prime-motion-stagger` apart; collapses under reduced motion. Mounted with its page, or inside a region that swaps in (`Crossfade`), it stands still |
 | layout | `layout` | `data-layout="fill" \| "compact"` (none for `default`) |
 | size | `size` | `data-size`; controls inside get the same tier |
 | error | `tone="danger"` | `data-tone="danger"`, `role="alert"` (unless a `role` is passed), the icon tile danger |

package/src/components/field-list/COMPONENT.md

@@ -9,7 +9,7 @@
 - A form part where a person adds, edits and removes several records of the same fields: invoice lines, contacts of a client, specs of a plan, recipients.
 - A base value with overrides (a price and its changes by month): the base is the first row, pinned with `getLocked`, each override is a row.
 - A list of short texts in the order a person sets (selling points, checklist items): one column, `reorderable`; each row ends with its remove button and its handle.
-- Dense rows (three or more columns), a touch-heavy screen, or rows that need more than remove and move → `rowActions="menu"`: one «⋯» per row.
+- Every row shows its actions in sight — the remove «×» and, with `reorderable`, the grip after it — however many columns it has (the default `rowActions="buttons"`). `rowActions="menu"` only for a `reorderable` list on a touch-first screen, where «Выше» / «Ниже» in one «⋯» replace a drag; never for a list without `reorderable`, whose menu would hold one item.
 - Small attributes of a record beside its text (an icon, a color): `width="compact"` columns with an icon-only `Select` (`Select.TriggerIcon` and no `Select.Value`) and a `ColorPresets` swatch.
 
 ## When not to use
@@ -83,8 +83,8 @@ Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editabl
 ### rowActions
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `buttons` | a ghost «×» at the row's end and, with `reorderable`, the grip after it; a pinned row: «×» off, then the lock | short lists edited often, a desktop screen, moving rows is a main task | yes |
-| `menu` | one ghost «⋯» per row; its Dropdown holds «Выше», «Ниже» (with `reorderable`), a separator and «Удалить» (danger) | dense rows (three or more columns), a touch-heavy screen, a row that needs more than remove and move | |
+| `buttons` | a ghost «×» at the row's end and, with `reorderable`, the grip after it; a pinned row: «×» off, then the lock | every list: one action (remove) or remove and move, any number of columns | yes |
+| `menu` | one ghost «⋯» per row; its Dropdown holds «Выше», «Ниже» (with `reorderable`), a separator and «Удалить» (danger) | a `reorderable` list on a touch-first screen, where moving by the menu replaces a drag; never without `reorderable` | |
 
 ### width (column)
 | Value | Looks like | Use when | Default |
@@ -182,7 +182,7 @@ Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editabl
 | [variants.tsx](examples/variants.tsx) | The two looks of the same list: the rows on the host surface, or on a fill of their own with side padding — `variant`. |
 | [sizes.tsx](examples/sizes.tsx) | Every tier: the headings, the fields, the handle and the buttons follow the list's size — `size`. |
 | [reorder.tsx](examples/reorder.tsx) | Selling points of a plan in the order of the pricing page: a one-column list has no headings and no numbers, each row ends with its remove button and then its handle, a point moves by the handle or Alt+arrows — `reorderable`, `getLabel`. |
-| [row-menu.tsx](examples/row-menu.tsx) | Payment stages of a project in dense rows: one more-button per row holds move up, move down and remove, the moves are off at the ends and next to the pinned advance, and Alt+arrows on the button move the row too — `rowActions`, `reorderable`, `getLocked`. |
+| [row-menu.tsx](examples/row-menu.tsx) | Payment stages of a project on a touch-first screen, where a drag is awkward: one more-button per row holds move up, move down and remove, the moves are off at the ends and next to the pinned advance, and Alt+arrows on the button move the row too — `rowActions`, `reorderable`, `getLocked`. |
 | [locked.tsx](examples/locked.tsx) | Specs of a plan on one line each: an icon picker and its color side by side in compact columns, the first three specs are pinned with a lock in the handle's place and a remove button that is off and says why, the rest reorder below them — `getLocked`, `width`, `reorderable`. |
 | [base-row.tsx](examples/base-row.tsx) | A plan price and its changes by month in one table: the base price is the first, pinned row whose remove button is off and says why, each change is a row with its month and its price, and the unit sits in the field, not in a heading — `getLocked`, `labels`, `width`. |
 | [limits.tsx](examples/limits.tsx) | Recipients of invoice reminders, from one to three: the last row cannot be removed and the add button says why it is off once the list is full — `min`, `max`, `hint`. |

package/src/components/field-list/examples/row-menu.tsx

@@ -1,4 +1,4 @@
-/** Payment stages of a project in dense rows: one more-button per row holds move up, move down and remove, the moves are off at the ends and next to the pinned advance, and Alt+arrows on the button move the row too — `rowActions`, `reorderable`, `getLocked`. */
+/** Payment stages of a project on a touch-first screen, where a drag is awkward: one more-button per row holds move up, move down and remove, the moves are off at the ends and next to the pinned advance, and Alt+arrows on the button move the row too — `rowActions`, `reorderable`, `getLocked`. */
 import { FieldList, type FieldListColumn, Input } from "prime-ui-kit";
 import * as React from "react";
 

package/src/components/hint/COMPONENT.md

@@ -84,7 +84,7 @@ The hint is always smaller than the field text; use the field's size.
 | State | Driven by | DOM |
 |---|---|---|
 | status | `tone` | `data-tone` with the shared text tone (none for `neutral`, and none while `invalid` or `disabled`); the color eases between tones |
-| error | `invalid` | `data-invalid="true"`; the message drops in over `fast` (fade + `--prime-space-1` from above, no shake, no layout shift) and the color eases from the hint color |
+| error | `invalid` | `data-invalid="true"`; the message drops in over `fast` (fade + `--prime-space-1` from above, no shake, no layout shift) when it arrives on a field already shown — an error the page mounts with stands still and the color eases from the hint color |
 | disabled | `disabled`, or a disabled `Fieldset` around it | `data-disabled="true"` |
 | size | `size`, else the host tier | `data-size` |
 

package/src/components/input/COMPONENT.md

@@ -64,12 +64,14 @@ The trailing side has a fixed CSS `order`, independent of JSX order: value · en
 | `hintTone` | `"neutral" \| "success" \| "warning" \| "danger"` | `"neutral"` | Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger inset ring on the field, `aria-invalid` on the input. A non-empty `error` implies it. |
+| `valid` | `boolean` | — | A confirmed value (a matching repeat, a verified code): a success ring and a drawn check at the field's end, `labels.valid` spoken. `invalid` wins. Pass `false` too: the live region exists only with it. |
 | `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring on `Input.Wrapper` (`data-focus-ring="false"`); focus, keyboard, ARIA and the invalid ring stay. |
 | `counter` | `ReactNode` | — | Right side of the support row, usually `<Input.Counter current max />`. |
 | `reserveSupportRow` | `boolean` | `false` | Always render the support row (min height = hint line height), so an appearing error does not shift the layout. |
 | `id` | `string` | — | Id of the `<input>` (auto-generated when omitted); hint id is `<id>-hint`, error id is `<id>-error`. |
 | `strength` | `boolean` | `false` | A password strength meter for new-password fields: a stepped `ProgressBar` under the field and the level word (weak … hard) in the support row. Follows the value of `Input.Field`. |
-| `getStrength` | `(value: string) => 0 \| 1 \| 2 \| 3 \| 4` | `getPasswordStrength` | Replaces the kit's estimate of `strength`. Return 0 for empty, 1 weak … 4 hard. A hint for the person typing, not a security check. |
+| `getStrength` | `(value: string) => 0 \| 1 \| 2 \| 3 \| 4` | `getPasswordStrength` | Replaces the kit's estimate of `strength`. Return 0 for empty, 1 weak … 4 hard. |
+| `minStrength` | `1 \| 2 \| 3 \| 4` | — | The policy of `strength`: below this level the meter turns danger and the form refuses to submit (`setCustomValidity`), then shows `labels.strengthTooWeak` as the error. |
 | `onCommit` | `(value: string) => void \| Promise<void>` | — | Inline save: fires with a changed value on blur and Enter; Escape reverts. Return a Promise: the field shows a spinner and stays editable; a rejection restores the value — show why through `error`. |
 | `suggestions` | `readonly string[]` | — | Suggestions for free text (a combobox): a list under the box shows those containing the text; a pick goes into the field as typing would. Any text stays allowed; a value from a list only is `Select`. |
 | `closeOnEscape` | `boolean` | `true` | Escape closes the `suggestions` list; the text and the focus stay in the field. |
@@ -202,7 +204,7 @@ Input has no `variant` or `tone`: there is one field treatment (fill, no visible
 - Pointless: `required` and `optional` together; `hint` and `error` together (the error replaces the hint); `invalid` without any message in a form where the user needs to know what is wrong.
 - Forbidden: `focusRing={false}` on regular form fields (WCAG 2.4.7).
 
-**Hierarchy:** keep one size for all fields of a form; mark required/optional consistently; a status of the value goes into the hint, not into the field.
+**Hierarchy:** keep one size for all fields of a form; mark required/optional consistently; a status of the value goes into the hint, not into the field — except a confirmed value (`valid`: a repeated password that matches, a verified email or code), which is a check mark in the field, never a «совпадает» text.
 
 ## States
 | State | Driven by | DOM |
@@ -211,6 +213,7 @@ Input has no `variant` or `tone`: there is one field treatment (fill, no visible
 | focus | keyboard focus on the input | wrapper gets the focus fill and an inset focus ring (`:has(input:focus-visible)`) |
 | no focus ring | `focusRing={false}` | `data-focus-ring="false"` on the wrapper |
 | invalid | `invalid` or non-empty `error` | `data-invalid="true"` on root and wrapper, `aria-invalid="true"` on the input, danger inset ring, danger focus ring; the control shakes once when an error arrives (`data-shake` on the frame) |
+| valid | `valid` (and not invalid: `invalid` or `error` wins) | `data-valid="true"` on the wrapper, a success inset ring; a check (`aria-hidden`) at the end of the field before the end icon and segments pops in and draws its stroke when the value becomes valid, and closes up in place when it goes; a polite live region says `labels.valid` and is in the input's `aria-describedby` while valid |
 | disabled | native `disabled` on `Input.Field`, or a disabled `Fieldset` around it | disabled fill, disabled text and icons, `cursor: not-allowed`, clear button disabled look |
 | read-only | native `readOnly` on `Input.Field` | no hover, default cursor |
 | reserved support row | `reserveSupportRow` | `data-reserve="true"` on the support row |
@@ -218,6 +221,7 @@ Input has no `variant` or `tone`: there is one field treatment (fill, no visible
 | suggesting | `suggestions` + typing, ↓ / ↑ or a click in the field | `role="combobox"`, `aria-expanded="true"` and `aria-controls` on the input; the list fades in under the box (the floating panel's motion) with the matching part of each suggestion marked; the highlight is a fill (`data-highlighted`, `aria-selected`) named by `aria-activedescendant`; closes on a pick, Escape, Tab, blur or a press outside |
 | select segment | a `Select` inside `Input.Wrapper` | `data-field-segment` on the select root, `data-segment="true"` on its trigger: a tinted section (`fill-subtle`) flush with the start edge, a stronger fill on hover and while open, its own inset focus ring; the box's ring stays for the text |
 | strength | `strength` + the value of `Input.Field` | a stepped `ProgressBar` (4 cells, `aria-label` = `labels.strength`) under the field fills one cell after another, weak · easy · medium · hard, toned danger → warning → accent → success; the level word at the end of the support row flows in letter by letter and is announced (`aria-live`); the support row is reserved |
+| below the policy | `strength` + `minStrength` above the level of a non-empty value | the meter and the level word turn danger; `setCustomValidity(labels.strengthTooWeak)` on the input, so the form refuses to submit; after a refused submit the same text is the field's `error` (`aria-invalid`) until the level reaches `minStrength` |
 | saving | `onCommit` returned a pending Promise | `aria-busy="true"` on the input; a `Spinner` at the end of the field (`data-commit="pending"`); the field stays editable and focusable, neighbours are untouched; a live region says `labels.saving` |
 | saved | the Promise resolved (or `onCommit` returned nothing) | the spinner cross-fades into a success check (`data-commit="saved"`) that fades out after a moment; the live region says `labels.saved` |
 | save refused | the Promise rejected | the committed value is put back (unless the person typed on), the status leaves; the owner shows why through `error` |
@@ -230,6 +234,8 @@ Inline save (`onCommit`): the value at focus is the committed one. Blur and Ente
 
 Strength estimate (`strength`, replaced by `getStrength`): every trait adds a point on its own, in any order — lowercase, uppercase, digits, symbols, 10+ and 14+ characters; 0–2 points weak, 3 easy, 4 medium, 5+ hard, and under 8 characters at most easy. The meter follows `Input.Field` controlled or not.
 
+Strength policy (`minStrength`): a non-empty value below the level is invalid for the form (native constraint validation, `labels.strengthTooWeak`), so a submit stops at the field and its error appears; an empty value is left to `required`. The meter tells the person typing; the server still decides what it accepts.
+
 Suggestions (`suggestions`): the list shows the suggestions that contain the typed text (case-insensitive), and nothing when the text already is the only match. A pick writes the suggestion into the input the way typing does, so `onValueChange` (and `onCommit` on blur) receive it; the text is never restricted to the list.
 
 Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontrolled: `defaultValue`. Both are native input props.
@@ -262,6 +268,8 @@ Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontro
 
 - `label` renders a `<label htmlFor>` bound to the input. Without `label`, set `aria-label` on `Input.Field`. A placeholder never replaces the label.
 - Hint and error are linked through `aria-describedby`; the error replaces the hint and sets `aria-invalid="true"`.
+- `valid` adds the id of a polite live region holding `labels.valid` to the input's `aria-describedby`: the state is heard when it arrives and on focus, never by colour alone; the check is `aria-hidden`.
+- `minStrength` uses native constraint validation: below the level the input's `validationMessage` is `labels.strengthTooWeak`, the form refuses to submit, and the message becomes the field's error (`aria-invalid`).
 - `Input.Icon` is decorative (`aria-hidden`). `Input.Affix` and `Input.InlineAffix` are `aria-hidden` in the reading order but describe the input (`aria-describedby`, before the hint): the unit is heard with the field, so the label never repeats it. An `aria-label` on the affix is said instead of its text («рублей» for `₽`).
 - `suggestions` make the input a `combobox` (`aria-autocomplete="list"`, `aria-expanded`, `aria-controls` on the open `listbox`, which the label names); the highlight is `aria-activedescendant`, so focus never leaves the field.
 - A `Select` inside `Input.Wrapper` is the box's start segment: its trigger is named by the select root's `aria-label` and the picked value («Иконка: Звезда»).
@@ -290,6 +298,8 @@ Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontro
 | `strengthEasy` | `"Лёгкий"` | Level word for strength 2. |
 | `strengthMedium` | `"Средний"` | Level word for strength 3. |
 | `strengthHard` | `"Сложный"` | Level word for strength 4. |
+| `strengthTooWeak` | `"Пароль недостаточно надёжный"` | Validation message of a `strength` field below `minStrength`, and its error once a submit was refused. |
+| `valid` | `"Значение подходит"` | Spoken when the field is `valid`; the check mark itself is `aria-hidden`. |
 
 ## Examples
 | Example | Shows |
@@ -302,6 +312,7 @@ Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontro
 | [affixes.tsx](examples/affixes.tsx) | A fixed prefix and suffix flush with the edges and a unit next to the value, heard as a word by a screen reader — `Input.Affix`, `Input.InlineAffix`, `aria-label`. |
 | [without-focus-ring.tsx](examples/without-focus-ring.tsx) | A single search field where the caret and the lighter fill show focus — `focusRing`. |
 | [password-strength.tsx](examples/password-strength.tsx) | A new password with a show toggle and a meter that fills step by step and names the level beside the hint, and a service password measured by the company's own rule — `Input.RevealButton`, `strength`, `getStrength`. |
+| [password-policy.tsx](examples/password-policy.tsx) | A password change under a policy: a new password below the required level turns the meter danger and stops the submit, the repeat gets a check once it matches — `strength`, `minStrength`, `valid`. |
 | [edge-actions.tsx](examples/edge-actions.tsx) | Actions at the field's end: a mail link with a tooltip beside copying the value, and a profile link on a read-only field — `Input.Action`, `Input.CopyButton`. |
 | [inline-edit.tsx](examples/inline-edit.tsx) | Record card fields that save on blur and Enter, revert on Escape and show the server's refusal — `onCommit`, `error`. |
 | [suggestions.tsx](examples/suggestions.tsx) | Where a returned order is kept: free text with the places already used as suggestions — `suggestions`. |
@@ -315,6 +326,8 @@ Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontro
 - `<Input.Field placeholder="Email" />` without a label → add `label` on `Input.Root` or `aria-label` on the field.
 - `<Input.Root disabled>` → `disabled` goes on `Input.Field`.
 - `<Input.Root fullWidth>` → there is no such prop; the root already fills its parent.
+- A success icon in `Input.Icon side="end"` or a «Пароли совпадают» hint for a matching value → `valid` on `Input.Root` (ring, check, spoken state).
+- Checking `strength` levels yourself and setting `error` → `minStrength`.
 - Passing both `hint` and `error` expecting both to show → only the error is shown.
 - Rendering `Input.ClearButton` for an empty field → render it only when there is a value.
 - Setting `className` with a custom border or background on `Input.Wrapper` → the fill comes from the surface context; fields inside Card/Modal already switch.
@@ -327,5 +340,5 @@ Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontro
 - Returning `false` from `onCommit` to refuse → reject the Promise (throw) and set `error`.
 
 ## Related
-- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Tooltip](../tooltip/COMPONENT.md) (`Input.Action`, `Input.CopyButton`), [Spinner](../spinner/COMPONENT.md) (`onCommit`), [ProgressBar](../progress-bar/COMPONENT.md) (`strength`), `Icon` (segments), [VisuallyHidden](../visually-hidden/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md) (the `suggestions` list)
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [Tooltip](../tooltip/COMPONENT.md) (`Input.Action`, `Input.CopyButton`), [Spinner](../spinner/COMPONENT.md) (`onCommit`), [ProgressBar](../progress-bar/COMPONENT.md) (`strength`), `Icon` (segments, the `valid` check), [VisuallyHidden](../visually-hidden/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md) (the `suggestions` list)
 - **See also:** [Textarea](../textarea/COMPONENT.md), [Select](../select/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md) — fields with the same contract