prime-ui-kit 0.20.1 → 0.21.1

package/src/components/input/examples/password-policy.tsx

@@ -0,0 +1,65 @@
+/** 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`. */
+import { Button, Fieldset, Input } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function InputPasswordPolicyExample() {
+  const [password, setPassword] = React.useState("Graphite7");
+  const [repeat, setRepeat] = React.useState("");
+  const [submitted, setSubmitted] = React.useState(false);
+  const [saved, setSaved] = React.useState(false);
+
+  const matches = repeat !== "" && repeat === password;
+
+  return (
+    <form
+      className={styles.form}
+      onSubmit={(event) => {
+        event.preventDefault();
+        setSubmitted(true);
+        setSaved(matches);
+      }}
+    >
+      <Fieldset>
+        <Input.Root label="Новый пароль" hint="Не ниже среднего уровня" strength minStrength={3}>
+          <Input.Wrapper>
+            <Input.Field
+              type="password"
+              autoComplete="new-password"
+              required
+              value={password}
+              onValueChange={(value) => {
+                setPassword(value);
+                setSaved(false);
+              }}
+            />
+            <Input.RevealButton />
+          </Input.Wrapper>
+        </Input.Root>
+        <Input.Root
+          label="Повторите пароль"
+          valid={matches}
+          error={submitted && !matches ? "Пароли не совпадают" : undefined}
+        >
+          <Input.Wrapper>
+            <Input.Field
+              type="password"
+              autoComplete="new-password"
+              value={repeat}
+              onValueChange={(value) => {
+                setRepeat(value);
+                setSaved(false);
+              }}
+            />
+          </Input.Wrapper>
+        </Input.Root>
+      </Fieldset>
+      <div>
+        <Button.Root type="submit" tone={saved ? "success" : "accent"}>
+          {saved ? "Пароль изменён" : "Сменить пароль"}
+        </Button.Root>
+      </div>
+    </form>
+  );
+}

package/src/components/list/COMPONENT.md

@@ -168,7 +168,7 @@ Root attributes: `data-size`, `role="list"` (the list style reset would drop the
 - Text and description truncate with an ellipsis; give a long `List.ItemText` a `title` with the full text.
 - On a coarse pointer a row is at least the touch target (44px).
 - Reorderable (`onReorder`): an `xs` handle box ends each row, 4px after the row element and its `List.ItemActions` (inline-end: on the left in RTL); the row keeps its own padding and fill, so every row's handle stands on one line.
-- `List.ItemActions`: the controls one tier below the row, 4px apart, as far from the row's edge as from its top and bottom — the end edge, or the start edge with `side="start"`, where the row's own padding then parts the controls from its icon or text.
+- `List.ItemActions`: the controls one tier below the row, 4px apart, as far from the row's edge as a control box of that tier stands from its top and bottom — at any row height: one line, with `List.ItemDescription`, with an avatar, the touch row. The end edge, or the start edge with `side="start"`, where the row's own padding then parts the controls from its icon or text.
 - One toggle place per row: a plain row ends with its toggle (label first); a reorderable row leads with it (`side="start"`) and ends with the grip — never a toggle between the label and the grip.
 - A colour dot in `List.ItemIcon` is the large `Badge.Dot` (8px) centred in an icon-wide box, so the text lines up with the rows that carry icons.
 

package/src/components/login-form/COMPONENT.md

@@ -6,7 +6,7 @@
 > A sign-in card with a logo, title, provider buttons and a form; covers sign-in, sign-up, password reset and code confirmation.
 
 ## When to use
-- A standalone sign-in, sign-up, password-reset or one-time-code screen of a product.
+- The one auth screen of a product: sign-in, sign-up, an invite (set a password by a link), a password reset and a one-time code are its modes (`/login?invite=…`), each the same card with another header and form — never a page of its own per mode.
 - The same flow inside a [Modal](../modal/COMPONENT.md) (`flat`) when sign-in is opened over a page.
 - Any short authentication step where one card holds a header, optional provider buttons, 1–5 fields and one primary action.
 
@@ -140,8 +140,8 @@ Every part is optional except `Root`, `Title` and `Form`. Fields, buttons, divid
 ### align
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `start` | accent icon tile on the left, title over description to its right, left-aligned footer | product screens, sign-in over a page, inside a Modal | yes |
-| `center` | round logo, centered title, description and footer | a standalone brand-first sign-in screen | |
+| `start` | accent icon tile on the left, title over description to its right, left-aligned footer | every auth screen of a product and sign-in over a page: the tile holds the icon of the action (`action.login`), the title names it | yes |
+| `center` | round logo, centered title, description and footer | a public brand page outside the product, where the mark is the point | |
 
 ### Flags
 | Value | Looks like | Use when | Default |
@@ -149,7 +149,7 @@ Every part is optional except `Root`, `Title` and `Form`. Fields, buttons, divid
 | `flat` | card fill, no shadow | inside a Modal or any other surface | `false` |
 
 **Combinations**
-- Recommended: one `size` on Root only (fields and buttons follow it); `hint` / `error` on fields for validation; a refused sign-in as `invalid` on the fields it concerns plus a [VisuallyHidden](../visually-hidden/COMPONENT.md) live region with the reason.
+- Recommended: one `size` on Root only (fields and buttons follow it); `hint` / `error` on fields for validation; a refused sign-in as `invalid` on the e-mail and the reason in words as the password field's `error` («Неверная почта или пароль»).
 - Avoid: a [Banner](../banner/COMPONENT.md) in the form; more than one primary button; provider buttons in `solid` (they compete with the submit); a Card around LoginForm.
 
 ## States
@@ -159,14 +159,14 @@ LoginForm has no state of its own. Compose them:
 |---|---|---|
 | submitting | `loading` on the submit Button; the fields in a `Fieldset disabled`, the submit Button outside it | `aria-busy` on the button; native `disabled` on the `<fieldset>`, the fields in their disabled look |
 | field error | `error` / `invalid` on `Input.Root`, `error` on `DigitInput` | `aria-invalid`, the error under the field |
-| refused sign-in | `invalid` on the fields it concerns (they shake once); `VisuallyHidden live="assertive"`, mounted from the start in `LoginForm.Form`, gets the reason | `aria-invalid` on the fields; `role="alert"` on the hidden region |
+| refused sign-in | `invalid` on the e-mail, `error` with the reason on the password (both shake once) | `aria-invalid` on the fields; the error in the password's support row, announced by its live region |
 
 Root carries `data-size`, `data-align` and `data-flat`.
 
 ## Layout & spacing
 - header → body `--prime-space-8` (gap on Root); provider buttons → divider → form `--prime-space-4`; field → field → submit `--prime-space-5`; submit → back action `--prime-space-3`; form → footer `--prime-space-6`.
 - Spacing is `gap` on parents; no margins between parts.
-- The card has no border, takes the full width up to the small modal width. To center it on a page, wrap it in your own flex container on the page.
+- The card has no border, takes the full width up to the small modal width and centres itself in a wider block. Put it on a centring canvas of your own (a grid with `place-items: center` and `min-height: 100dvh`); a `Crossfade` that swaps the page's states (loading / form / expired link) goes around the card inside that canvas, without `fill`.
 - The form is a Card, a layer of the surface ladder (`data-depth`): on the page it is white in light with the raised whisper, fields inside are one step off it.
 
 ## Accessibility
@@ -185,7 +185,7 @@ Root carries `data-size`, `data-align` and `data-flat`.
 - The logo is decorative; with an `aria-label` it is the product mark image (`role="img"`).
 - Give `LoginForm.Form` an `aria-label` (or `aria-labelledby` pointing to the title id) so the form is a landmark.
 - Fields use `autoComplete` (`email`, `current-password`, `new-password`, `one-time-code`) so password managers and OTP autofill work.
-- Field errors come from the fields (`aria-invalid`, described by the error). A refused sign-in has no Banner: the fields it concerns take `invalid` and an always-mounted `VisuallyHidden live="assertive"` says why.
+- Field errors come from the fields (`aria-invalid`, described by the error). A refused sign-in has no Banner: the e-mail takes `invalid` and the `error` of the password says why, announced by the support row of the field.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -195,24 +195,26 @@ No `labels`.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | Sign in with a provider button, e-mail and password, a «forgot password» link and a sign-up link under a centered header with the product's named mark — `align`, `LoginForm.Logo`, `LoginForm.Actions`, `LoginForm.Form`, `LoginForm.Footer`. |
+| [overview.tsx](examples/overview.tsx) | Sign in with a provider button, e-mail and password, a «forgot password» link and a sign-up link under a header that names the action: its icon tile on the left, the title and one line beside it — `LoginForm.Logo`, `LoginForm.Actions`, `LoginForm.Form`, `LoginForm.Footer`. |
 | [sizes.tsx](examples/sizes.tsx) | Padding, gaps and text roles of the card follow the tier; the fields and buttons take the same one — `size`. |
 | [structure.tsx](examples/structure.tsx) | The minimal form: no logo, description or footer, no shadow for a host that already is a surface and a second-level title under the host page's own heading — `flat`, `as`. |
 | [register.tsx](examples/register.tsx) | Sign-up: four fields in one column, a strength meter on the new password and a mismatch shown as the field error — `strength`, `error`, `LoginForm.Form`. |
 | [forgot-password.tsx](examples/forgot-password.tsx) | Password reset request: one field, the primary action and a quiet way back — `LoginForm.Actions`. |
 | [reset-password.tsx](examples/reset-password.tsx) | A new password after the e-mail link: a strength meter on the first field and a mismatch error under the second one — `strength`, `error`. |
 | [verification-code.tsx](examples/verification-code.tsx) | The second step with a one-time code: a rejected code shows its error under the cells, resend is a quiet action — `DigitInput`, `LoginForm.Actions`. |
-| [states.tsx](examples/states.tsx) | The submit cycle: the button is busy while the request runs, a refused sign-in marks both fields, which shake once, and a hidden live region says why — `loading`, `invalid`, `VisuallyHidden`. |
+| [states.tsx](examples/states.tsx) | The submit cycle: the button is busy while the request runs, a refused sign-in marks both fields, which shake once, and the password field says why in words — `loading`, `invalid`, `error`. |
 | [narrow.tsx](examples/narrow.tsx) | On a phone-width screen the card keeps its padding, the header wraps and the buttons stay full width — `LoginForm.Form`. |
 
 ## Mistakes
 - A separate block of your own for provider buttons → put them in `LoginForm.Actions`.
 - `disabled` on every field while the request runs → one [Fieldset](../fieldset/COMPONENT.md) `disabled` around the fields; keep the submit Button outside it so it shows `loading`.
-- A danger Banner above the fields for a refused sign-in → `invalid` on the fields and the reason in a `VisuallyHidden live="assertive"`; a sign-in or sign-up form has no banners.
+- A danger Banner above the fields for a refused sign-in → `invalid` on the e-mail and the reason as the password's `error`; a sign-in or sign-up form has no banners. A refusal shown only by red rings and a shake → the same `error`: a person needs the words.
+- A product mark centred over the title on the product's own sign-in → `align="start"` (the default) with the action's icon in `LoginForm.Logo`.
+- A separate page for an invite or a reset → a mode of the auth screen, the same card.
 - A placeholder instead of a field label → pass `label` to the field.
 - A Card around LoginForm → the root already is the card; use `flat` inside another surface.
 - Repeating the card `size` on every field and button → set it once on Root; fields and buttons follow it.
 
 ## Related
 - **Built from:** [Card](../card/COMPONENT.md) (the surface), [Typography](../typography/COMPONENT.md) (`Title`, `Description`, `Footer`), the icon tile (`iconBox` `.tile`, the `start` logo)
-- **See also:** [Input](../input/COMPONENT.md), [Fieldset](../fieldset/COMPONENT.md) (disables the fields while signing in), [Button](../button/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Divider](../divider/COMPONENT.md), [DigitInput](../digit-input/COMPONENT.md), [VisuallyHidden](../visually-hidden/COMPONENT.md), [Modal](../modal/COMPONENT.md)
+- **See also:** [Input](../input/COMPONENT.md), [Fieldset](../fieldset/COMPONENT.md) (disables the fields while signing in), [Button](../button/COMPONENT.md), [LinkButton](../link-button/COMPONENT.md), [Divider](../divider/COMPONENT.md), [DigitInput](../digit-input/COMPONENT.md), [Modal](../modal/COMPONENT.md)

package/src/components/login-form/examples/overview.tsx

@@ -1,17 +1,17 @@
-/** Sign in with a provider button, e-mail and password, a «forgot password» link and a sign-up link under a centered header with the product's named mark — `align`, `LoginForm.Logo`, `LoginForm.Actions`, `LoginForm.Form`, `LoginForm.Footer`. */
+/** Sign in with a provider button, e-mail and password, a «forgot password» link and a sign-up link under a header that names the action: its icon tile on the left, the title and one line beside it — `LoginForm.Logo`, `LoginForm.Actions`, `LoginForm.Form`, `LoginForm.Footer`. */
 import { Button, Divider, Icon, Input, LinkButton, LoginForm } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
 export default function LoginFormOverviewExample() {
   return (
-    <LoginForm.Root align="center">
+    <LoginForm.Root>
       <LoginForm.Header>
-        <LoginForm.Logo aria-label="Маршрут">
-          <Icon name="action.send" />
+        <LoginForm.Logo>
+          <Icon name="action.login" />
         </LoginForm.Logo>
         <LoginForm.Title>Войти в аккаунт</LoginForm.Title>
-        <LoginForm.Description>Введите данные для входа в кабинет</LoginForm.Description>
+        <LoginForm.Description>Через SSO компании или по рабочей почте</LoginForm.Description>
       </LoginForm.Header>
       <LoginForm.Body>
         <LoginForm.Actions>

package/src/components/login-form/examples/states.tsx

@@ -1,5 +1,5 @@
-/** The submit cycle: the button is busy while the request runs, a refused sign-in marks both fields, which shake once, and a hidden live region says why — `loading`, `invalid`, `VisuallyHidden`. */
-import { Button, Fieldset, Icon, Input, LoginForm, VisuallyHidden } from "prime-ui-kit";
+/** The submit cycle: the button is busy while the request runs, a refused sign-in marks both fields, which shake once, and the password field says why in words — `loading`, `invalid`, `error`. */
+import { Button, Fieldset, Icon, Input, LoginForm } from "prime-ui-kit";
 import * as React from "react";
 
 export default function LoginFormStatesExample() {
@@ -30,9 +30,6 @@ export default function LoginFormStatesExample() {
             }, 1200);
           }}
         >
-          <VisuallyHidden live="assertive">
-            {failed ? "Неверный email или пароль" : ""}
-          </VisuallyHidden>
           <Fieldset disabled={pending}>
             <Input.Root label="Email" required invalid={failed}>
               <Input.Wrapper>
@@ -44,7 +41,11 @@ export default function LoginFormStatesExample() {
                 />
               </Input.Wrapper>
             </Input.Root>
-            <Input.Root label="Пароль" required invalid={failed}>
+            <Input.Root
+              label="Пароль"
+              required
+              error={failed ? "Неверная почта или пароль" : undefined}
+            >
               <Input.Wrapper>
                 <Input.Field
                   type="password"

package/src/components/message/COMPONENT.md

@@ -233,11 +233,11 @@ Content parts in short: `Message.Media` — a [Gallery](../gallery/COMPONENT.md)
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes. |
 
 ### Message.Actions
-`ref` → `HTMLDivElement`. A row of a bot's inline keyboard under the bubble: `Button.Root` children share it equally at the message's width (the bubble widens to it). Several make several rows; such a message has no tail.
+`ref` → `HTMLDivElement`. A row of a bot's inline keyboard under the bubble: `Button.Root` keys (`soft` `neutral` by default) share one line equally, long labels ellipsize. A link key gets the link mark; a key whose `onClick` returns a promise loads until it settles.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` — the `Button.Root`s of the row (`variant="soft" tone="neutral"`, `asChild` for a link); `className`. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` — the `Button.Root`s of the row (`asChild` for a link); `className`. |
 
 ### Message.Menu
 `ref` → `HTMLDivElement`. The context menu: a `Dropdown.Content` of the `Dropdown.Item`s you write; the kit adds «Выбрать» when the chat has a selection. Opens on right click, long press and from the keyboard.
@@ -363,7 +363,7 @@ The list-level settings a message reads — the group chat's author header and a
 - `Message.Text` wraps anywhere; the meta stands at the end of its last line.
 - Round controls (download, cancel, retry, play) are a Button `shape="circle"`: hover, press, focus ring and the touch area follow the circle. A file's action is its round tile (48): the transfer disk (`internal/transferDisk`, `xl`) with its ring, the retry or the download stand on it — never a separate button beside the name. Every transfer, either way (media, file, video note, voice), is that one disk.
 - `Message.Typing` is the last row of a list; a chat puts it there itself (`Chat.Root typing`).
-- **A bot's inline keyboard** (`Message.Actions`): each part is a row under the bubble, `--prime-space-1` below it and between rows and buttons, on the chat's own surface (outside the bubble's fill). The keyboard is as wide as the message: the column takes the wider of the bubble and the keyboard (up to the bubble's cap) and the bubble widens to it, so their edges line up. Buttons share a row equally (`flex: 1 1 0`); a row too narrow for its labels wraps them. The expected look is `Button.Root variant="soft" tone="neutral"` at the host tier; `asChild` turns one into a link. A message with a keyboard has no tail: the keyboard closes it.
+- **A bot's inline keyboard** (`Message.Actions`): each part is a row under the bubble, `--prime-space-1` below it and between rows and keys, on the chat's own surface (outside the bubble's fill). The keyboard is as wide as the message: the column takes the wider of the bubble and the keyboard (up to the bubble's cap) and the bubble widens to it, so their edges line up. A row is one line, as in Telegram: its keys share it equally (`flex: 1 1 0`, each key `fullWidth`), and a label longer than its share ellipsizes. Keys keep the control radius; the last row's outer bottom corners take the bubble's (`--prime-message-radius`), so the keyboard closes the message. A key is `Button.Root` `variant="soft" tone="neutral"` at the host tier unless it sets its own: Telegram's button `style` maps onto `tone` — `primary` → `accent`, `success`, `danger` (`variant="solid"` for a filled key). A custom emoji before the label is a `Button.Icon`. A link key (`asChild` around an `<a href>`) carries the link mark (`action.externalLink`, `xs`) at its top-end corner, out of the label's flow. A callback key whose `onClick` returns a promise is `loading` until it settles: the spinner takes its leading icon's place or covers the label, the width never changes. A message with a keyboard has no tail: the keyboard closes it.
 
 ## Accessibility
 
@@ -506,7 +506,7 @@ The list-level settings a message reads — the group chat's author header and a
 | [location.tsx](examples/location.tsx) | A place on a map picture from your map service with a pin, the place and its address, and a live location of a courier on its way — `Message.Location`, `href`, `live`. |
 | [contact.tsx](examples/contact.tsx) | A shared contact: initials or a photo, name and phone, with the actions to write or save — `Message.Contact`, `phone`. |
 | [link-preview.tsx](examples/link-preview.tsx) | A message with a link and the card of the page under it: site, title, description and picture — `Message.LinkPreview`, `site`, `image`. |
-| [bot-actions.tsx](examples/bot-actions.tsx) | A bot's message with an inline keyboard: rows of buttons under the bubble at its width, sharing each row equally, one of them a link — `Message.Actions`, `asChild`. |
+| [bot-actions.tsx](examples/bot-actions.tsx) | A bot's message with an inline keyboard: one-line rows whose keys share the row equally, a coloured key with an icon that loads while its promise runs, a link with its mark — `Message.Actions`, `tone`, `Button.Icon`, `asChild`. |
 | [sticker.tsx](examples/sticker.tsx) | Stickers in a conversation: a picture by its address and a video sticker in your own player, no bubble, the time on a pill over the corner — `Message.Sticker`, `src`, `loading`. |
 | [preview.tsx](examples/preview.tsx) | A bot's welcome message as its settings page shows it: the same bubble with its keyboard, nothing in it pressed or opened, the time in the zone of the profile — `preview`, `timeZone`. |
 | [narrow.tsx](examples/narrow.tsx) | At phone width bubbles take up to 85% of the chat, long words and links wrap inside, an album keeps its rows — `Message.Root`, `Message.Media`. |
@@ -534,5 +534,5 @@ The list-level settings a message reads — the group chat's author header and a
 - A bot's buttons placed inside `Message.Text`, or a row of buttons of your own under a message → `Message.Actions` with `Button.Root` children: one row per part, at the message's width.
 
 ## Related
-- **Built from:** [Dropdown](../dropdown/COMPONENT.md) (`Message.Menu`), [ScrollContainer](../scroll-container/COMPONENT.md) (the floating panel of the reaction bar), [Gallery](../gallery/COMPONENT.md) (`Message.Media`), [Avatar](../avatar/COMPONENT.md) (`Avatar.Group` + `Avatar.Overflow` in reaction chips), [Badge](../badge/COMPONENT.md) (the «Трансляция» mark of a live location), [Thumbnail](../thumbnail/COMPONENT.md) (the map, the link preview picture, a file's preview), [Button](../button/COMPONENT.md) (retry, the transfer disk, `shape="circle"`, the buttons of `Message.Actions`), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` in selection mode), [Spinner](../spinner/COMPONENT.md) (pending transfers and transcripts), [Skeleton](../skeleton/COMPONENT.md) (a sticker while it loads), Icon (status ticks, file glyphs, `action.forward`, `action.refresh`); `internal/messagePart` (the contract of content parts), `internal/messageList` (the contract with a chat's list), `internal/palette` (`hueOf`), `internal/Disclosure` (the reactions row, transcripts), `bubbleMorph` (every size change as one stroke), `bubbleHug` (a bubble of text as wide as its widest line), `internal/transferDisk` (the transfer of a file), `internal/mediaPill` (the meta, the author's pill), `internal/HighlightMatch` (search marks), `internal/richText` (Markdown), [VisuallyHidden](../visually-hidden/COMPONENT.md)
+- **Built from:** [Dropdown](../dropdown/COMPONENT.md) (`Message.Menu`), [ScrollContainer](../scroll-container/COMPONENT.md) (the floating panel of the reaction bar), [Gallery](../gallery/COMPONENT.md) (`Message.Media`), [Avatar](../avatar/COMPONENT.md) (`Avatar.Group` + `Avatar.Overflow` in reaction chips), [Badge](../badge/COMPONENT.md) (the «Трансляция» mark of a live location), [Thumbnail](../thumbnail/COMPONENT.md) (the map, the link preview picture, a file's preview), [Button](../button/COMPONENT.md) (retry, the transfer disk, `shape="circle"`, the buttons of `Message.Actions`), [Checkbox](../checkbox/COMPONENT.md) (`Checkbox.Indicator` in selection mode), [Spinner](../spinner/COMPONENT.md) (pending transfers and transcripts), [Skeleton](../skeleton/COMPONENT.md) (a sticker while it loads), Icon (status ticks, file glyphs, `action.forward`, `action.refresh`, `action.externalLink` — the link mark of a key); `internal/messagePart` (the contract of content parts), `internal/messageList` (the contract with a chat's list), `internal/palette` (`hueOf`), `internal/Disclosure` (the reactions row, transcripts), `bubbleMorph` (every size change as one stroke), `bubbleHug` (a bubble of text as wide as its widest line), `internal/transferDisk` (the transfer of a file), `internal/mediaPill` (the meta, the author's pill), `internal/HighlightMatch` (search marks), `internal/richText` (Markdown), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Chat](../chat/COMPONENT.md) — the conversation the messages stand in; [Gallery](../gallery/COMPONENT.md) — the album of `Message.Media`; [VideoNote](../video-note/COMPONENT.md) — the round video message; [VoicePlayer](../voice-player/COMPONENT.md) — the content of a voice message; [Composer](../composer/COMPONENT.md) — the input under the list; [RichText](../rich-text/COMPONENT.md) — the text of `Message.Text` outside a message; [Timeline](../timeline/COMPONENT.md)

package/src/components/message/examples/bot-actions.tsx

@@ -1,51 +1,70 @@
-/** A bot's message with an inline keyboard: rows of buttons under the bubble at its width, sharing each row equally, one of them a link — `Message.Actions`, `asChild`. */
-import { Button, Message } from "prime-ui-kit";
+/** A bot's message with an inline keyboard: one-line rows whose keys share the row equally, a coloured key with an icon that loads while its promise runs, a link with its mark — `Message.Actions`, `tone`, `Button.Icon`, `asChild`. */
+import { Button, Icon, Message } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 const INVOICE_URL = "https://vector.example/invoices/4821";
+const CONFIRM_DELAY_MS = 1200;
 
 export default function MessageBotActionsExample() {
-  const [answer, setAnswer] = React.useState<string | null>(null);
+  const [decision, setDecision] = React.useState<string | null>(null);
+
+  // A callback key: the bot answers after a round trip, the key loads until then.
+  const confirm = () =>
+    new Promise<void>((resolve) => {
+      window.setTimeout(() => {
+        setDecision("Отгрузка подтверждена, машина выезжает в 16:30.");
+        resolve();
+      }, CONFIRM_DELAY_MS);
+    });
 
   return (
     <div className={styles.thread}>
-      <Message.Root value="bot-order" time="15:02">
+      <Message.Root value="bot-order" time="15:02" edited={decision !== null}>
         <Message.Author>Бот склада</Message.Author>
         <Message.Text>
-          Заказ № 4821 собран: 12 позиций на 184 300 ₽. Подтвердите отгрузку до 16:00.
+          {decision ??
+            "Заказ № 4821 собран: 12 позиций на 184 300 ₽. Подтвердите отгрузку до 16:00."}
         </Message.Text>
+        {decision === null ? (
+          <Message.Actions>
+            <Button.Root tone="success" onClick={confirm}>
+              <Button.Icon>
+                <Icon name="action.check" />
+              </Button.Icon>
+              Подтвердить
+            </Button.Root>
+            <Button.Root tone="danger" onClick={() => setDecision("Отгрузка отменена.")}>
+              Отменить
+            </Button.Root>
+          </Message.Actions>
+        ) : null}
+        {decision === null ? (
+          <Message.Actions>
+            <Button.Root onClick={() => setDecision("Состав заказа открыт для правки.")}>
+              Изменить состав
+            </Button.Root>
+            <Button.Root onClick={() => setDecision("Отгрузка перенесена на завтра.")}>
+              Перенести
+            </Button.Root>
+          </Message.Actions>
+        ) : null}
+        {decision === null ? (
+          <Message.Actions>
+            <Button.Root onClick={() => setDecision("Менеджер свяжется с вами.")}>
+              Связаться с менеджером
+            </Button.Root>
+          </Message.Actions>
+        ) : null}
         <Message.Actions>
-          <Button.Root variant="soft" tone="neutral" onClick={() => setAnswer("Подтвердить заказ")}>
-            Подтвердить заказ
-          </Button.Root>
-          <Button.Root variant="soft" tone="neutral" onClick={() => setAnswer("Изменить")}>
-            Изменить
-          </Button.Root>
-        </Message.Actions>
-        <Message.Actions>
-          <Button.Root
-            variant="soft"
-            tone="neutral"
-            onClick={() => setAnswer("Связаться с менеджером")}
-          >
-            Связаться с менеджером
-          </Button.Root>
-        </Message.Actions>
-        <Message.Actions>
-          <Button.Root variant="soft" tone="neutral" asChild>
+          <Button.Root asChild>
             <a href={INVOICE_URL} target="_blank" rel="noreferrer">
               Открыть счёт
             </a>
           </Button.Root>
         </Message.Actions>
       </Message.Root>
-      {answer ? (
-        <Message.Root value="reply" direction="outgoing" time="15:03" status="sent">
-          <Message.Text>{answer}</Message.Text>
-        </Message.Root>
-      ) : null}
     </div>
   );
 }

package/src/components/modal/COMPONENT.md

@@ -29,13 +29,14 @@ Modal.Root                    state and dismiss policy (no DOM)
     ├── (grab handle)         as a phone sheet with `closeOnOutsideClick`: aria-hidden bar, a drag starts here
     ├── Modal.Guard           no DOM: holds the dialog (busy / dirty) from inside
     ├── Modal.Header          grid: [Icon] [Title + Description] [Actions] [close button]
-    │   ├── Modal.Icon        40 tile with a tone fill; no tile around an Avatar.Root / Thumbnail.Root
-    │   ├── Modal.Title       <h2>, names the dialog
-    │   ├── Modal.Description <p>, describes the dialog
-    │   └── Modal.Actions     row of tier-s controls before the close button
+    │   ├── Modal.Icon        40 tile with a tone fill; the record's Avatar / Thumbnail with no tile, 40
+    │   ├── Modal.Title       line 1: <h2>, names the dialog; `loading` holds it with a skeleton
+    │   ├── Modal.Description line 2: <p>, describes the dialog; status Badges lead it (tier s)
+    │   └── Modal.Actions     buttons only (icon buttons, a ⋯ Dropdown), tier s, on the title's line
     ├── Modal.Body            the only scrolling zone
     │   └── Modal.Section     <section>: <h3> label, description, Modal.Actions at the heading's end
     └── Modal.Footer          actions, primary last
+        ├── Modal.Actions     the start group: an action apart from the main pair
         ├── Modal.Meta        <p>, muted status at the start
         ├── Modal.Close       clones its child; closes on click
         └── Modal.Confirm     clones its child; Enter clicks it
@@ -84,19 +85,19 @@ No DOM, no ref. State and dismiss policy.
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `className` and the other attributes of the `<header>`. |
 
 ### Modal.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 `Modal.Section` heading. Controls inside take tier `s`.
+`ref` → `HTMLDivElement`. Header buttons only (icon buttons, a ⋯ Dropdown; a status goes in `Modal.Description`), tier `s`, on the title's line; under it below 12rem; at the end of a `Modal.Section` heading. In `Modal.Footer`: the start group at the footer tier.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `children` and the other attributes of the row. |
 
 ### Modal.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. |
 
 ### Modal.Title
@@ -104,10 +105,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). |
 
 ### Modal.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 |
 |---|---|---|---|
@@ -131,7 +133,7 @@ No DOM, no ref. State and dismiss policy.
 | `…rest` | `Omit<HTMLAttributes<HTMLElement>, "title">` | — | `children` (the content and an optional `Modal.Actions`), `className` and the other attributes of the `<section>`. |
 
 ### Modal.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 `Modal.Actions` (an action apart from the main pair) and `Meta`. Stacked, the start comes first and the primary stays last.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -198,7 +200,7 @@ With a `Modal.Meta` the footer is a row in any layout: the status takes the free
 | `danger` | `danger-soft` tile, danger icon | A warning about a risky step | |
 | `info` | `info-soft` tile, info icon | Informational notices | |
 
-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.
+Around the record's picture — an `Avatar.Root` or a `Thumbnail.Root` anywhere inside, also from your own wrapper component — 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.
 
 ### Flags
 | Value | Looks like | Use when | Default |
@@ -227,8 +229,11 @@ Around the record's picture — an `Avatar.Root` or a `Thumbnail.Root` (found by
 | busy | `Modal.Guard busy` | Escape, the scrim, a swipe, the close button and `Modal.Close` do nothing; the close button and the `Close` child are `disabled` in place |
 | dirty | `Modal.Guard dirty` | a dismiss opens the «Не сохранять изменения?» ConfirmDialog (`labels.discard*`); its confirm closes the dialog; a swipe past the threshold glides back and asks the same |
 | leaving the tab | `Modal.Guard busy` or `dirty` | the browser asks before the tab closes or reloads (`beforeunload`), as with `Page.Guard` |
+| title loading | `Modal.Title loading` | a `Skeleton` holds the title line, `aria-busy` on the `<h2>`; the name fades in under the same element |
 | description loading | `Modal.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 `Modal.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 `Modal.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 `Modal.Description` | the line is a wrapping flex row, the badges first (`order`), each `data-tier="s"` |
 | sheet | a centred dialog on a phone viewport | `data-sheet` on the dialog: the bottom-sheet surface, the grab handle while it swipes |
 | swiping | as a phone sheet, a drag down from the handle or the header (with `closeOnOutsideClick`; without it there is no handle and no swipe) | `data-swiping` and `--swipe-offset` on the dialog while the pointer drags it; past 30% of its height or on a flick it closes, otherwise it glides back; a busy `Modal.Guard` sets `data-swipe-disabled` and the handle takes no drag |
 | placement | `placement` on Content | `data-placement` on the dialog |
@@ -238,6 +243,16 @@ Loading or disabled actions use the Button props (`loading`, `disabled`) inside
 Motion (`overlayMotion`): the scrim fades in and out over `base`; the dialog fades and scales from 0.98 over `base` and leaves over `fast`; as a bottom sheet it slides up over `slow` and down over `base`. Content stays mounted until the exit ends; under `prefers-reduced-motion` it unmounts at once.
 
 ## Layout & spacing
+- The header has one anatomy, the same in every modal, drawer and sheet:
+  ```
+  [mark]  Title                                [icon buttons] [⋯] [×]
+          [status badges] description text
+  ```
+  - mark — `Modal.Icon`: a glyph on the tone tile, or the record's picture (`Avatar.Root`, `Thumbnail.Root`, also inside your own wrapper component) with no tile; both are 40 px.
+  - line 1 — `Modal.Title`; `loading` holds it with a Skeleton while the name loads.
+  - line 2 — `Modal.Description`: the record's statuses as `Badge.Root`s first, then the text. The kit sizes the badges (chip tier `s`, the line's 20 px), keeps them first and one gap apart, and wraps the text under them on a narrow panel.
+  - end — `Modal.Actions`: only buttons — ghost icon buttons with a Tooltip and a ⋯ Dropdown — at the close button's tier, centred on the title's line; a status never goes here.
+- An action apart from the main pair («Удалить» of a record, «Выйти»): `Modal.Actions` inside `Modal.Footer` puts it at the start, at the footer's tier; stacked on a phone it comes first and the primary stays last.
 - Dialog padding `--prime-modal-padding` (24) on every zone; header 24 top / 20 bottom, body 20 with a 16 gap between blocks, footer 20 top / 24 bottom.
 - Max height = viewport minus `--prime-modal-viewport-padding` on both sides; only the body scrolls.
 - Tabs in the header: a `Tabs.List` inside `Modal.Header` (with `Tabs.Root` around the header and the body) spans the header's last row. The header becomes the tab strip, edge to edge and without the hairline; the active tab is the body rising into it, the panels sit in the body.
@@ -282,7 +297,7 @@ Motion (`overlayMotion`): the scrim fades in and out over `base`; the dialog fad
 | Example | Shows |
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A trigger opens a dialog with a title, a field and two actions; Enter presses the confirm — `Modal.Trigger`, `Modal.Confirm`. |
-| [structure.tsx](examples/structure.tsx) | Optional parts: an icon tile with a header-only notice, and a header with a status before the close button and a footer with no body between them — `Modal.Icon`, `Modal.Actions`, `Modal.Footer`. |
+| [structure.tsx](examples/structure.tsx) | Optional parts: an icon tile with a header-only notice, and a header whose status leads the line under the title, with a footer and no body between them — `Modal.Icon`, `Modal.Description`, `Modal.Footer`. |
 | [sizes.tsx](examples/sizes.tsx) | Every width; xs, s and m fill the footer with equal buttons, l and xl align them to the end — `size`. |
 | [long-content.tsx](examples/long-content.tsx) | A long body in titled sections scrolls on its own while the header and the footer stay in place; the primary closes the dialog and is the Enter target — `Modal.Body`, `Modal.Section`, `Modal.Confirm`. |
 | [custom-container.tsx](examples/custom-container.tsx) | The dialog portals into a given node instead of the document body — `container`. |
@@ -301,9 +316,13 @@ Motion (`overlayMotion`): the scrim fades in and out over `base`; the dialog fad
 - A hand-made heading row (`Typography as="h3"` + buttons) over a group in the body → `Modal.Section label` with `Modal.Actions`.
 - Busy or unsaved state lifted out of the form into Root props → put `Modal.Guard` next to the form, inside Content.
 - `key` or a conditional around `Modal.Root` to reset a form → the dialog unmounts at once, without its exit; keep the Root mounted and drive `open`.
+- A status `Badge` in the header's `Modal.Actions`, beside the buttons → put it in `Modal.Description`, before the text: the kit sizes it to the line and keeps it first.
+- A Badge with its own `size` in `Modal.Description` → leave `size` out: the line gives every header the same chip tier.
+- A `Skeleton` placed by hand in `Modal.Title` or `Modal.Description` → their `loading`.
+- A start-side button («Выйти», «Удалить») put inside `Modal.Meta` → `Modal.Actions` inside `Modal.Footer`; `Meta` is status text only.
 - Scrolling wrapper inside Modal.Body → Body already scrolls.
 - Long multi-section forms in a modal → use Drawer.
 
 ## Related
-- **Built from:** the dialog shared with Drawer and Sheet (`internal/overlay/DialogParts`, `internal/overlay/ModalDialog`), [Button](../button/COMPONENT.md) (header close button), [ScrollContainer](../scroll-container/COMPONENT.md) (`Modal.Body`), [Avatar](../avatar/COMPONENT.md) and [Thumbnail](../thumbnail/COMPONENT.md) (a record's picture in `Modal.Icon`), [Skeleton](../skeleton/COMPONENT.md) (`Modal.Description loading`), [ConfirmDialog](../confirm-dialog/COMPONENT.md) (the `Modal.Guard` discard confirm), `Icon` (the close glyph)
+- **Built from:** the dialog shared with Drawer and Sheet (`internal/overlay/DialogParts`, `internal/overlay/ModalDialog`), [Button](../button/COMPONENT.md) (header close button), [ScrollContainer](../scroll-container/COMPONENT.md) (`Modal.Body`), `internal/mediaSlot` (a record's Avatar or Thumbnail in `Modal.Icon`), [Skeleton](../skeleton/COMPONENT.md) (`Modal.Description loading`), [ConfirmDialog](../confirm-dialog/COMPONENT.md) (the `Modal.Guard` discard confirm), `Icon` (the close glyph)
 - **See also:** [ConfirmDialog](../confirm-dialog/COMPONENT.md) (a destructive confirm built on Modal `s`), [Drawer](../drawer/COMPONENT.md) (the same header, body, footer and `Guard` at the edge), [Popover](../popover/COMPONENT.md), [CommandMenu](../command-menu/COMPONENT.md)

package/src/components/modal/examples/structure.tsx

@@ -1,4 +1,4 @@
-/** Optional parts: an icon tile with a header-only notice, and a header with a status before the close button and a footer with no body between them — `Modal.Icon`, `Modal.Actions`, `Modal.Footer`. */
+/** Optional parts: an icon tile with a header-only notice, and a header whose status leads the line under the title, with a footer and no body between them — `Modal.Icon`, `Modal.Description`, `Modal.Footer`. */
 import { Badge, Button, Icon, Modal } from "prime-ui-kit";
 
 export default function ModalStructureExample() {
@@ -33,11 +33,9 @@ export default function ModalStructureExample() {
           <Modal.Header>
             <Modal.Title>Опубликовать «Бизнес 2026»?</Modal.Title>
             <Modal.Description>
+              <Badge.Root color="gray">Черновик</Badge.Root>
               Новые клиенты увидят тариф сразу после публикации.
             </Modal.Description>
-            <Modal.Actions>
-              <Badge.Root color="gray">Черновик</Badge.Root>
-            </Modal.Actions>
           </Modal.Header>
           <Modal.Footer>
             <Modal.Close>

package/src/components/segmented-control/COMPONENT.md

@@ -25,8 +25,8 @@ import { SegmentedControl } from "prime-ui-kit";
 ## Anatomy
 ```
 SegmentedControl.Root                 field frame: label row · track · support row (hint | error)
-└─ (track)                            role="radiogroup"; sliding thumb, switcher row, keyboard
-   └─ SegmentedControl.Item           role="radio" button, one option
+└─ (track)                            role="radiogroup" (role="navigation" with link items); sliding thumb, switcher row, keyboard
+   └─ SegmentedControl.Item           role="radio" button, one option; the consumer's link with `asChild`
       ├─ SegmentedControl.Icon        icon slot (optional; icon-only → square segment)
       ├─ SegmentedControl.Label       title, one line (optional; plain text becomes the label)
       ├─ SegmentedControl.Count       counter Badge after the label (optional)
@@ -63,13 +63,14 @@ The root is a field root: `className`, `ref` and the native attributes land on t
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange" \| "dir">` | — | `aria-label` / `aria-labelledby` / `aria-describedby` and `onKeyDown` go to the radiogroup (a prevented key skips the kit's handling); `className`, `data-*` and the other attributes to the field frame `<div>`. |
 
 ### SegmentedControl.Item
-`ref` → `HTMLButtonElement`. One option, a `<button role="radio">` with roving `tabIndex`; plain text is wrapped in a `SegmentedControl.Label`.
+`ref` → `HTMLButtonElement`, or the child element with `asChild`. One option, a `<button role="radio">` with roving `tabIndex`; plain text is wrapped in a `SegmentedControl.Label`. With `asChild` the segment is the consumer's link.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `value` | `string` | — (required) | Option value compared with the root value. |
 | `disabled` | `boolean` | `false` | Disables this option; arrow keys skip it. |
 | `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | — | Palette hue: a dot before the content; while selected the thumb takes a soft fill of the hue with a ring of it. |
+| `asChild` | `boolean` | `false` | The single child (a router `<Link>`) becomes the segment. A row of links is a navigation: links in the Tab order, the one matching `value` current, no arrow keys. |
 | `children` | `ReactNode` | — (required) | Text, `Icon`, `Label`, `Count`, `Description`. Only an icon → square segment; give it `aria-label`. |
 | `className` | `string` | — | Class on the segment button. |
 | `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value" \| "type" \| "role">` | — | `aria-label`, `onClick` (runs first and can `preventDefault()` the selection), `className` and the other button attributes. |
@@ -141,6 +142,7 @@ Track is `fill-muted` with a faint 1px ring; the selected segment is a floating
 |---|---|---|---|
 | `fullWidth` | fills the container; single-line segments tend to equal widths, a long label keeps its own width and the row scrolls when they do not fit; two-line segments grow from their content | modals, mobile panels, overview strips | off |
 | `disabled` | every segment disabled, thumb `fill-muted-hover` without shadow | the choice is temporarily unavailable | off |
+| `asChild` (Item) | the same segment; the consumer's element (a router `<Link>`) renders it | route sections («Сотрудники / Роли») that must be real links | off |
 | icon-only (only `SegmentedControl.Icon`) | square segment (`data-icon-only`) | toolbar view toggles; needs `aria-label` | — |
 
 Colour all items or none; do not give an item and its Count the same hue; prefer content width or two-line segments over `fullWidth` with many long labels.
@@ -157,6 +159,7 @@ Colour all items or none; do not give an item and its Count the same hue; prefer
 | required | `required` | red `*` after the label, `aria-required="true"` on the radiogroup |
 | optional | `optional` | a muted `labels.optional` marker after the label |
 | support row reserved | `reserveSupportRow` | the support row stays rendered while empty, so an error arriving shifts nothing |
+| link row | an Item with `asChild` | track `role="navigation"`; each link in the Tab order, no arrow-key selection; the segment matching `value` `aria-current="page"` and `data-state="checked"` |
 | focus-visible | keyboard | focus ring inside the segment |
 | compact | row wider than the container at the tier's padding | row `data-collapse="compact"`: single-line segments tighten their padding by one step, so a row a few pixels too wide keeps its last segment and count whole; if it still does not fit (and not every segment has an icon) it scrolls |
 | collapsed | even the compact row does not fit and every segment has an icon | row `data-collapse="icon"`: titles, counts and descriptions leave the row, segments turn square; a `VisuallyHidden` copy of the title names each segment and a `Tooltip` shows it |
@@ -180,10 +183,10 @@ Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `dat
 
 | Key | Action |
 |---|---|
-| `ArrowRight` · `ArrowDown` | Next option, wrapping and skipping disabled ones; focus and selection move together. |
+| `ArrowRight` · `ArrowDown` | Next option, wrapping and skipping disabled ones; focus and selection move together (not in a row of links). |
 | `ArrowLeft` · `ArrowUp` | Previous option. |
 | `Home` · `End` | First and last enabled option. |
-| `Tab` | Enters the group on the selected option (or the first enabled one) and leaves it. |
+| `Tab` | Enters the group on the selected option (or the first enabled one) and leaves it; in a row of links it moves from link to link. |
 
 ### ARIA
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -191,6 +194,7 @@ Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `dat
 - The track is `role="radiogroup"`, named by `label` (`aria-labelledby`); without a label give the root `aria-label`. `aria-disabled` when disabled.
 - Hint and error are linked through `aria-describedby`; an error sets `aria-invalid="true"`, `required` sets `aria-required="true"`.
 - Items are `<button role="radio" aria-checked>` with roving `tabIndex`.
+- With an `asChild` item the track is `role="navigation"` (named the same way), the links keep their role and the current one has `aria-current="page"`; `required` and `invalid` do not apply.
 - Two-line items: `aria-labelledby` = label (+ count), `aria-describedby` = description; plain text is the label, so every reference resolves.
 - Icons are `aria-hidden`; icon-only items need `aria-label` (and a Tooltip for sighted users). In a row collapsed to icons a `VisuallyHidden` copy of the title names the segment and a `Tooltip` shows it.
 
@@ -212,6 +216,7 @@ Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `dat
 | [full-width.tsx](examples/full-width.tsx) | The group fills its column; segments tend to equal widths and a long label keeps its own — `fullWidth`. |
 | [scroll.tsx](examples/scroll.tsx) | Segments never wrap: in a column narrower than the row it scrolls with edge fades and brings the chosen segment into view — `defaultValue`. |
 | [two-line.tsx](examples/two-line.tsx) | A label and a counter on the first line, a metric on the second — `SegmentedControl.Label`, `SegmentedControl.Count`, `SegmentedControl.Description`. |
+| [router.tsx](examples/router.tsx) | Router links as the segments: the current route is the value, each segment is a link and the row is a navigation; render it inside a router — `asChild`, `value`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the choice and updates other content from it — `value`, `onValueChange`. |
 | [in-form.tsx](examples/in-form.tsx) | An expense form: the choice is a labelled field with a hint, checked on submit, its error leaves as soon as a segment is chosen; an optional choice beside it — `label`, `hint`, `required`, `error`, `optional`. |
 
@@ -225,5 +230,5 @@ Item DOM: `data-state`, `data-disabled`, `data-icon-only`, `data-two-line`, `dat
 - Expecting segments to wrap on narrow screens → they scroll; use `fullWidth` or fewer options.
 
 ## Related
-- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (`internal/SwitcherScroller`, the row), [Badge](../badge/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md) (the title of a collapsed segment), [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [VisuallyHidden](../visually-hidden/COMPONENT.md); `internal/selectionIndicator` (the thumb)
+- **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (`internal/SwitcherScroller`, the row), [Badge](../badge/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md) (the title of a collapsed segment), [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [VisuallyHidden](../visually-hidden/COMPONENT.md); `internal/selectionIndicator` (the thumb), `internal/interactiveElement` (a link segment, `asChild`)
 - **See also:** [Tabs](../tabs/COMPONENT.md), [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md), [ButtonGroup](../button-group/COMPONENT.md), [Tooltip](../tooltip/COMPONENT.md)