prime-ui-kit 0.14.0 → 0.16.0

package/src/components/chat/examples/states.tsx

@@ -1,9 +1,7 @@
 /** The first load of a conversation: bubble-shaped placeholders on both sides stand in the list's place, then cross-fade into the messages — `loading`. */
-import { Button, Card, Chat, Message } from "prime-ui-kit";
+import { Button, Card, Chat, Message, Typography } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./examples.module.css";
-
 const LOAD_MS = 1500;
 
 const MESSAGES = [
@@ -67,8 +65,8 @@ export default function ChatStatesExample() {
   }, [loading]);
 
   return (
-    <div className={styles.live}>
-      <div className={styles.liveBar}>
+    <div>
+      <div>
         <Button.Root
           variant="soft"
           tone="neutral"
@@ -77,24 +75,27 @@ export default function ChatStatesExample() {
         >
           Открыть заново
         </Button.Root>
+        <Card.Root>
+          <Chat.Root>
+            <Chat.Messages aria-label="Переписка с ООО «Вектор»" loading={loading}>
+              {MESSAGES.map((message) => (
+                <Message.Root
+                  key={message.id}
+                  value={message.id}
+                  direction={message.direction}
+                  time={message.time}
+                  status={message.direction === "outgoing" ? "read" : undefined}
+                >
+                  <Message.Text>{message.text}</Message.Text>
+                </Message.Root>
+              ))}
+            </Chat.Messages>
+          </Chat.Root>
+        </Card.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          loading
+        </Typography>
       </div>
-      <Card.Root className={styles.short}>
-        <Chat.Root>
-          <Chat.Messages aria-label="Переписка с ООО «Вектор»" loading={loading}>
-            {MESSAGES.map((message) => (
-              <Message.Root
-                key={message.id}
-                value={message.id}
-                direction={message.direction}
-                time={message.time}
-                status={message.direction === "outgoing" ? "read" : undefined}
-              >
-                <Message.Text>{message.text}</Message.Text>
-              </Message.Root>
-            ))}
-          </Chat.Messages>
-        </Chat.Root>
-      </Card.Root>
     </div>
   );
 }

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

@@ -60,7 +60,7 @@ ChatList.Root                 <div> column filling its host (container `chat-lis
 | `hasMore` | `boolean` | `false` | More dialogs exist: a placeholder row ends the list and `onLoadMore` runs near the end. |
 | `onLoadMore` | `() => void \| Promise<void>` | — | The reader came near the end while `hasMore`: append the next dialogs. A promise is awaited before the next call. |
 | `empty` | `ReactNode` | — | The empty state without a search (an `EmptyPage` with an action). Default: «Нет диалогов». |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Row tier: height, text, avatar, glyphs and the search field. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Row tier: height, text, avatar, glyphs and the search field. Without it the tier of the host. |
 | `now` | `Date` | — | «Now» for the times of the rows. Default: the moment of the render. |
 | `formatTime` | `(date: Date, now: Date) => string` | `formatChatTime` | Display of a row's `Date` time: «14:32» today, «пн» this week, «12 мар», «12.03.2025». |
 | `labels` | `Partial<ChatListLabels>` | — | Built-in strings, see Labels. |
@@ -81,6 +81,8 @@ ChatList.Root                 <div> column filling its host (container `chat-lis
 | `draft` | `string` | — | The reader's unsent text: the preview shows «Черновик:» in danger and the text. |
 | `onClick` | `(event: MouseEvent<HTMLButtonElement>) => void` | — | Runs before the dialog opens; `preventDefault()` keeps it closed. |
 | `href` | `string` | — | Renders an `<a>` instead of a `<button>` (a dialog with its own URL). |
+| `target` | `string` | — | Where the `<a>` opens (`href` only). |
+| `rel` | `string` | — | Relationship of the `<a>` (`href` only). |
 | `children` | `ReactNode` | — | `ChatList.ItemIcon`, `ChatList.ItemText`, `ChatList.ItemDescription`, `ChatList.ItemMenu`. |
 | `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `className` and the native attributes of the row element. |
 
@@ -163,13 +165,13 @@ The search field takes the tier too; counts are one tier down (the Badge's own r
 | loading | `loading` | six placeholder `List` rows (`inert`, `aria-hidden`), the scroller `aria-busy`; cross-fade into the list |
 | empty | `items` empty | `EmptyPage layout="compact"` («Нет диалогов» or `empty`); with a query «Ничего не найдено» |
 | more | `hasMore` | one placeholder row after the list; `onLoadMore` near the end (`aria-busy` while its promise runs) |
-| menu | right click, long press, Shift+F10 | the row's `ChatList.ItemMenu` in a `Dropdown` anchored at the point; `data-menu="true"` rows take no callout or text selection |
+| menu | right click, long press, Shift+F10 | the row's `ChatList.ItemMenu` in a `Dropdown` anchored to the row (`Dropdown.Anchor`) at the point pressed, or under the row from the keyboard (`anchorPoint`); focus returns to the row; the row stays rendered while the menu is open; `data-menu="true"` rows take no callout or text selection |
 | reorder | a new order of `items` | rows glide from their old places (`transform`, `--prime-motion-duration-base`); new rows rise in (`enterMotion`); rows removed with nothing else changed close up in place |
 
 Root attribute: `data-size`. Every motion honours reduced motion (durations collapse, glides and ghosts are skipped).
 
 ## Layout & spacing
-- The root is a flex column that fills its host's height: put it straight into a `Card.Root` or a `PageContent.List` pane with a height; the scroller takes the rest under the search field.
+- The root is a flex column that fills its host's height: put it straight into a `Card.Root` or a `PageContent.Panel kind="list"` pane with a height; the scroller takes the rest under the search field.
 - One inset all round, the panel's 4px: the search field and the rows stand 4px from every edge of the host, so in a card (radius 12) their 8px corners follow the card's (nested radius = outer − padding). Rows stand 4px apart (a margin inside each `<li>`, so the virtual window measures rows with their space); the last row's margin is the inset below it.
 - A row: avatar · name and preview · time over the counts. The name and the preview truncate; glyphs, the time and the counts never do.
 - From 100 dialogs only the rows around the view render; spacers hold the rest of the height. The row with the Tab stop and the row with an open menu stay rendered.
@@ -179,6 +181,8 @@ Root attribute: `data-size`. Every motion honours reduced motion (durations coll
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Enters the list at one stop — the open dialog (or where the focus was last); the next Tab leaves the list. |
@@ -189,6 +193,8 @@ Root attribute: `data-size`. Every motion honours reduced motion (durations coll
 | `Escape` | In the search field clears the query; in the menu closes it and returns the focus to the row. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The list is a `<ul>` named «Диалоги» (`labels.list`); each row an `<li>` with a button, or a link with `href`.
 - The open dialog is `aria-current="true"` on a button, `"page"` on a link. Selection does not follow the focus: arrows only move it (a dialog may load a conversation); Enter, Space and a click open.
 - The row is named by its content: the name, glyphs with a `label` («Без звука», a verified mark), the preview, the delivery mark («Прочитано»), the time, then «упоминание» and «непрочитанных: 3» instead of the bare badges; the avatar is `aria-hidden`.
@@ -227,7 +233,6 @@ Root attribute: `data-size`. Every motion honours reduced motion (durations coll
 | `file` | `"Файл"` | Media word: `kind="file"`. |
 | `location` | `"Геопозиция"` | Media word: `kind="location"`. |
 | `contact` | `"Контакт"` | Media word: `kind="contact"`. |
-| `menu` | `"Действия с диалогом"` | `aria-label` of the point the row menu opens from. |
 
 ## Examples
 | Example | Shows |
@@ -238,6 +243,7 @@ Root attribute: `data-size`. Every motion honours reduced motion (durations coll
 | [search.tsx](examples/search.tsx) | The search field filters dialogs by name and by the last message, marks the match in both, says how many were found and shows a quiet state when none match — `defaultSearch`, `onSearchChange`. |
 | [live.tsx](examples/live.tsx) | A live inbox: a client types, then writes — the preview turns into the typing line and back, the count rolls up and the dialog glides to the top; opening it clears the count — `typing`, `unread`, `items`. |
 | [long-list.tsx](examples/long-list.tsx) | A sales inbox of a thousand dialogs: only the rows around the view render, arrows walk through all of them, and the next page loads as the end comes near — `hasMore`, `onLoadMore`. |
+| [links.tsx](examples/links.tsx) | Dialogs with their own address: every row is a link the router opens, the time reads as how long ago, and the list is named for its queue — `href`, `formatTime`, `labels`. |
 | [states.tsx](examples/states.tsx) | Loading and empty: placeholder rows in the rows' geometry cross-fade into the dialogs; a new workspace without dialogs shows its own empty state with an action — `loading`, `empty`. |
 | [controlled.tsx](examples/controlled.tsx) | The open dialog lives in the screen: a row opens it beside the list, and a next-unread button opens the next one from outside — `value`, `onValueChange`. |
 | [narrow.tsx](examples/narrow.tsx) | At phone width long names and previews truncate while the time and counts stay whole; a pane squeezed under 240px keeps only the names and the counts — `ChatList.Root`, `search`. |
@@ -252,5 +258,5 @@ Root attribute: `data-size`. Every motion honours reduced motion (durations coll
 - Deleting from the menu without a question → open a `ConfirmDialog` from the menu item.
 
 ## Related
-- **Built from:** [List](../list/COMPONENT.md) (rows, current fill, focus, touch height), [Input](../input/COMPONENT.md) (search), [ScrollContainer](../scroll-container/COMPONENT.md), [Crossfade](../crossfade/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Badge](../badge/COMPONENT.md) (counts), [Dropdown](../dropdown/COMPONENT.md) (row menu), [Dnd](../dnd/COMPONENT.md) (the glide of a new order)
+- **Built from:** [List](../list/COMPONENT.md) (rows, current fill, focus, touch height), [Input](../input/COMPONENT.md) (search), [ScrollContainer](../scroll-container/COMPONENT.md), [Crossfade](../crossfade/COMPONENT.md), [Skeleton](../skeleton/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Badge](../badge/COMPONENT.md) (counts), [Dropdown](../dropdown/COMPONENT.md) (row menu), [VisuallyHidden](../visually-hidden/COMPONENT.md), `useFlipList` (the glide of a new order)
 - **See also:** [Chat](../chat/COMPONENT.md), [Message](../message/COMPONENT.md), [Avatar](../avatar/COMPONENT.md), [PageContent](../page-content/COMPONENT.md), [ConfirmDialog](../confirm-dialog/COMPONENT.md)

package/src/components/chat-list/examples/examples.module.css

@@ -14,14 +14,6 @@
   block-size: calc(var(--prime-space-24) * 3);
 }
 
-/* sizes: a caption above each tier's list. */
-.tier {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-2);
-  inline-size: min(100%, calc(var(--prime-space-24) * 4));
-}
-
 /* A pane with its controls above it. */
 .stage {
   display: flex;

package/src/components/chat-list/examples/links.tsx

@@ -0,0 +1,72 @@
+/** Dialogs with their own address: every row is a link the router opens, the time reads as how long ago, and the list is named for its queue — `href`, `formatTime`, `labels`. */
+import { Avatar, Card, ChatList, hueOf } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const NOW = new Date(2026, 9, 14, 15, 0);
+const at = (day: number, hour: number, minute: number) => new Date(2026, 9, day, hour, minute);
+
+const DIALOGS = [
+  {
+    id: "t-1042",
+    name: "ООО «Вектор»",
+    initials: "ВК",
+    preview: "Не можем выгрузить счёт в 1С",
+    at: at(14, 14, 52),
+    unread: 2,
+  },
+  {
+    id: "t-1039",
+    name: "ООО «Гранит»",
+    initials: "ГР",
+    preview: "Акт сверки подписан",
+    at: at(14, 12, 5),
+    unread: 0,
+  },
+  {
+    id: "t-1031",
+    name: "ИП Козлов",
+    initials: "ИК",
+    preview: "Подключите, пожалуйста, ЭДО",
+    at: at(12, 11, 40),
+    unread: 0,
+  },
+];
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+/** A support queue reads waiting time: «8 мин», «3 ч», «2 дн». */
+const formatAgo = (date: Date, now: Date) => {
+  const passed = now.getTime() - date.getTime();
+  if (passed < HOUR) return `${Math.max(1, Math.round(passed / MINUTE))} мин`;
+  if (passed < DAY) return `${Math.round(passed / HOUR)} ч`;
+  return `${Math.round(passed / DAY)} дн`;
+};
+
+export default function ChatListLinksExample() {
+  return (
+    <Card.Root className={styles.short}>
+      <ChatList.Root
+        labels={{ list: "Обращения" }}
+        items={DIALOGS}
+        getKey={(item) => item.id}
+        value="t-1042"
+        now={NOW}
+        formatTime={formatAgo}
+        renderItem={(item) => (
+          <ChatList.Item href={`/support/tickets/${item.id}`} time={item.at} unread={item.unread}>
+            <ChatList.ItemIcon>
+              <Avatar.Root color={hueOf(item.id)}>
+                <Avatar.Fallback>{item.initials}</Avatar.Fallback>
+              </Avatar.Root>
+            </ChatList.ItemIcon>
+            <ChatList.ItemText>{item.name}</ChatList.ItemText>
+            <ChatList.ItemDescription>{item.preview}</ChatList.ItemDescription>
+          </ChatList.Item>
+        )}
+      />
+    </Card.Root>
+  );
+}

package/src/components/chat-list/examples/live.tsx

@@ -65,34 +65,37 @@ const INCOMING = [
 const TYPING_MS = 1600;
 
 export default function ChatListLiveExample() {
-  const [dialogs, setDialogs] = React.useState(DIALOGS);
-  const [dialogId, setDialogId] = React.useState<string | null>("vector");
+  // The dialogs and the open one in one state: a message that arrives later reads which dialog is
+  // open then, not when it was sent.
+  const [inbox, setInbox] = React.useState<{ dialogs: Dialog[]; open: string | null }>({
+    dialogs: DIALOGS,
+    open: "vector",
+  });
+  const { dialogs, open: dialogId } = inbox;
   const [step, setStep] = React.useState(0);
   const [busy, setBusy] = React.useState(false);
 
-  const patch = (id: string, next: Partial<Dialog>) =>
-    setDialogs((current) => current.map((item) => (item.id === id ? { ...item, ...next } : item)));
+  const patch = (id: string, next: (item: Dialog, open: string | null) => Partial<Dialog>) =>
+    setInbox((current) => ({
+      ...current,
+      dialogs: current.dialogs.map((item) =>
+        item.id === id ? { ...item, ...next(item, current.open) } : item,
+      ),
+    }));
 
   const receive = () => {
     const message = INCOMING[step % INCOMING.length];
     if (!message) return;
     setStep(step + 1);
     setBusy(true);
-    patch(message.id, { typing: true });
+    patch(message.id, () => ({ typing: true }));
     window.setTimeout(() => {
-      setDialogs((current) =>
-        current.map((item) =>
-          item.id === message.id
-            ? {
-                ...item,
-                typing: false,
-                preview: message.text,
-                at: new Date(),
-                unread: item.id === dialogId ? 0 : item.unread + 1,
-              }
-            : item,
-        ),
-      );
+      patch(message.id, (item, open) => ({
+        typing: false,
+        preview: message.text,
+        at: new Date(),
+        unread: item.id === open ? 0 : item.unread + 1,
+      }));
       setBusy(false);
     }, TYPING_MS);
   };
@@ -111,10 +114,14 @@ export default function ChatListLiveExample() {
           items={shown}
           getKey={(item) => item.id}
           value={dialogId}
-          onValueChange={(id) => {
-            setDialogId(id);
-            patch(id, { unread: 0 });
-          }}
+          onValueChange={(id) =>
+            setInbox((current) => ({
+              open: id,
+              dialogs: current.dialogs.map((item) =>
+                item.id === id ? { ...item, unread: 0 } : item,
+              ),
+            }))
+          }
           renderItem={(item) => (
             <ChatList.Item time={item.at} unread={item.unread} typing={item.typing}>
               <ChatList.ItemIcon>

package/src/components/chat-list/examples/sizes.tsx

@@ -1,8 +1,6 @@
 /** Every size tier: row height, text, avatar, glyphs and the search field follow the tier — `size`. */
 import { Avatar, Card, ChatList, hueOf, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 const NOW = new Date(2026, 9, 14, 15, 0);
@@ -28,12 +26,9 @@ const DIALOGS = [
 
 export default function ChatListSizesExample() {
   return (
-    <>
+    <div>
       {SIZES.map((size) => (
-        <div key={size} className={styles.tier}>
-          <Typography as="span" variant="caption" tone="muted">
-            {size}
-          </Typography>
+        <div key={size}>
           <Card.Root>
             <ChatList.Root
               size={size}
@@ -54,8 +49,11 @@ export default function ChatListSizesExample() {
               )}
             />
           </Card.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
         </div>
       ))}
-    </>
+    </div>
   );
 }

package/src/components/chat-list/examples/states.tsx

@@ -1,9 +1,7 @@
 /** Loading and empty: placeholder rows in the rows' geometry cross-fade into the dialogs; a new workspace without dialogs shows its own empty state with an action — `loading`, `empty`. */
-import { Avatar, Button, Card, ChatList, EmptyPage, hueOf, Icon } from "prime-ui-kit";
+import { Avatar, Button, Card, ChatList, EmptyPage, hueOf, Icon, Typography } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./examples.module.css";
-
 const NOW = new Date(2026, 9, 14, 15, 0);
 
 const DIALOGS = [
@@ -59,19 +57,17 @@ export default function ChatListStatesExample() {
   }, [loading]);
 
   return (
-    <>
-      <div className={styles.stage}>
-        <div className={styles.bar}>
-          <Button.Root
-            variant="soft"
-            tone="neutral"
-            loading={loading}
-            onClick={() => setLoading(true)}
-          >
-            Обновить
-          </Button.Root>
-        </div>
-        <Card.Root className={styles.short}>
+    <div>
+      <div>
+        <Button.Root
+          variant="soft"
+          tone="neutral"
+          loading={loading}
+          onClick={() => setLoading(true)}
+        >
+          Обновить
+        </Button.Root>
+        <Card.Root>
           <ChatList.Root
             items={loading ? [] : DIALOGS}
             getKey={(item) => item.id}
@@ -80,28 +76,36 @@ export default function ChatListStatesExample() {
             renderItem={renderDialog}
           />
         </Card.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          loading
+        </Typography>
+      </div>
+      <div>
+        <Card.Root>
+          <ChatList.Root
+            items={[] as Dialog[]}
+            getKey={(item) => item.id}
+            renderItem={renderDialog}
+            empty={
+              <EmptyPage.Root layout="compact">
+                <EmptyPage.Icon>
+                  <Icon name="object.message" />
+                </EmptyPage.Icon>
+                <EmptyPage.Title>Диалогов пока нет</EmptyPage.Title>
+                <EmptyPage.Description>
+                  Клиенты появятся здесь, когда напишут в чат на сайте.
+                </EmptyPage.Description>
+                <EmptyPage.Actions>
+                  <Button.Root variant="soft">Настроить виджет</Button.Root>
+                </EmptyPage.Actions>
+              </EmptyPage.Root>
+            }
+          />
+        </Card.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          empty
+        </Typography>
       </div>
-      <Card.Root className={styles.short}>
-        <ChatList.Root
-          items={[] as Dialog[]}
-          getKey={(item) => item.id}
-          renderItem={renderDialog}
-          empty={
-            <EmptyPage.Root layout="compact">
-              <EmptyPage.Icon>
-                <Icon name="object.message" />
-              </EmptyPage.Icon>
-              <EmptyPage.Title>Диалогов пока нет</EmptyPage.Title>
-              <EmptyPage.Description>
-                Клиенты появятся здесь, когда напишут в чат на сайте.
-              </EmptyPage.Description>
-              <EmptyPage.Actions>
-                <Button.Root variant="soft">Настроить виджет</Button.Root>
-              </EmptyPage.Actions>
-            </EmptyPage.Root>
-          }
-        />
-      </Card.Root>
-    </>
+    </div>
   );
 }

package/src/components/checkbox/COMPONENT.md

@@ -28,7 +28,7 @@ Checkbox.Root          field grid; ref and input props go to the native input
 │  └─ Checkbox.Label   the visible text (optional)
 └─ hint | error        support text under the text column (`hint`, `error`)
 
-Checkbox.Indicator     the box alone, no input — a mark inside option / menu rows (used without Root)
+Checkbox.Indicator     the box alone, no input — a mark inside option / menu rows and toggle tiles (used without Root)
 ```
 `<Checkbox.Root aria-label="…" />` without `Checkbox.Label` is a valid bare control (table rows).
 
@@ -45,8 +45,10 @@ Checkbox.Indicator     the box alone, no input — a mark inside option / menu r
 | `defaultChecked` | `boolean` | `false` | Initial state when uncontrolled. |
 | `onCheckedChange` | `(checked: boolean) => void` | — | Called with the new state on every toggle (not while `readOnly`). |
 | `indeterminate` | `boolean` | `false` | Mixed state (a partial «select all»): a bar instead of the check; wins over `checked` visually and sets the native `indeterminate`. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier of the box, the text and the gap. Without it the tier of its host (a form, a panel, a table), else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the box, the text and the gap. Without it the tier of its host (a form, a panel, a table), else `m`. |
 | `shape` | `"square" \| "circle"` | `"square"` | Outline of the box: `square` is the rounded square; `circle` is a full circle (a selection mark in lists and chats). Size, the check draw-in, the indeterminate bar and states are the same. |
+| `optional` | `boolean` | `false` | Muted `labels.optional` after the label text; the field may stay off. |
+| `labels` | `Partial<CheckboxLabels>` | — | Built-in strings, see Labels. |
 | `hint` | `ReactNode` | — | Help text under the label text. Hidden while `error` is shown. |
 | `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
 | `invalid` | `boolean` | `false` | Danger ring on the unchecked box and `aria-invalid`. A non-empty `error` implies it. |
@@ -56,13 +58,17 @@ Checkbox.Indicator     the box alone, no input — a mark inside option / menu r
 | `aria-describedby` | `string` | — | Merged before the hint/error ids. |
 | `children` | `ReactNode` | — | `Checkbox.Label`. Without it only the box renders — give the root an `aria-label`. |
 | `className` | `string` | — | Class on the field `<div>`. |
-| `…rest` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size" \| "checked" \| "defaultChecked" \| "onChange">` | — | `name`, `value`, `required`, `aria-label`, `onBlur`… on the native input. |
+| `…rest` | `Omit<InputHTMLAttributes<HTMLInputElement>, "type" \| "size" \| "checked" \| "defaultChecked" \| "onChange">` | — | `name`, `value`, `required` (also a red `*` after the text), `aria-label`, `onBlur`… on the native input. |
 
 ### Checkbox.Label
 `ref` → `HTMLSpanElement`. The visible text in the text column of the label row. Native `<span>` props.
 
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+
 ### Checkbox.Indicator
-`ref` → `HTMLSpanElement`. The box alone, without an input (`aria-hidden`, no focus or clicks) for rows that carry the state themselves: `role="option"` + `aria-selected`, `role="menuitemcheckbox"` + `aria-checked`.
+`ref` → `HTMLSpanElement`. The box alone, without an input (`aria-hidden`, no focus or clicks) for rows that carry the state themselves: `role="option"` + `aria-selected`, `role="menuitemcheckbox"` + `aria-checked`, a toggle `<button>` + `aria-pressed`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -101,6 +107,7 @@ The circle changes only the outline (`--prime-radius-full`); the check draw-in,
 | `indeterminate` | accent box with a horizontal bar | a parent checkbox over a partially selected group | `false` |
 | `invalid` | danger ring on the unchecked box | the message is shown elsewhere; otherwise pass `error` | `false` |
 | `disabled` | muted box, dimmed text and hint | the option is unavailable | `false` |
+| `optional` | muted `labels.optional` after the text | a form where most fields are required | `false` |
 
 **Combinations**
 - `indeterminate` only on a parent checkbox that controls a group; leaf options never use it.
@@ -123,40 +130,46 @@ Root also carries `data-size`; the box carries `data-shape`. Controlled: `checke
 
 ## Layout & spacing
 - Grid `[box][text]`; the hint or error sits under the text column, not under the box.
-- Checkboxes in a vertical list: gap `--prime-space-3`; separate fields: `--prime-space-5`; group → actions `--prime-space-8`.
+- Checkboxes in a column: a label-less [Fieldset](../fieldset/COMPONENT.md) stacks them at the form rhythm (name it with `aria-label`); the form around the group spaces it from its actions.
 - Long labels wrap (`overflow-wrap: anywhere`); the field shrinks to its content with `max-width: 100%`.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves focus to the checkbox. |
 | `Space` | Toggles it. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - A native `<input type="checkbox">` (visually hidden over the box, so validation bubbles point at it), wrapped by the `<label>` row.
 - `aria-invalid` is set when invalid; `aria-describedby` = your ids + the hint or the error id.
 - Without visible text, pass `aria-label` on `Checkbox.Root` (it lands on the input).
-- `required` goes to the native input; no asterisk is drawn — state it in the text or the hint.
-- `Checkbox.Indicator` is `aria-hidden`; the host row carries `aria-selected` / `aria-checked`.
+- `required` goes to the native input and draws a red `*` after the text; the `*` is `aria-hidden`, the input reports the requirement.
+- `Checkbox.Indicator` is `aria-hidden`; the host row carries `aria-selected` / `aria-checked` / `aria-pressed`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-No `labels`.
+| Key | Default | Used for |
+|---|---|---|
+| `optional` | `"необязательно"` | Marker after the label when `optional`. |
 
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | A checkbox with its label; a click anywhere on the row toggles it. |
+| [overview.tsx](examples/overview.tsx) | A checkbox with its label; a click anywhere on the row toggles it — `Checkbox.Label`, `defaultChecked`. |
 | [variants.tsx](examples/variants.tsx) | The rounded square next to the circle, in three states — `shape`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size; the box and the text follow the control tier — `size`. |
-| [states.tsx](examples/states.tsx) | Every state side by side, each labelled by its prop — `checked`, `indeterminate`, `invalid`, `disabled`. |
-| [without-label.tsx](examples/without-label.tsx) | Bare boxes in table rows, named by `aria-label` and submitted with `name` and `value`. |
-| [indicator.tsx](examples/indicator.tsx) | The box alone in a multi-select list: the option row carries `aria-selected`, the box only shows it — `Checkbox.Indicator`. |
+| [states.tsx](examples/states.tsx) | Every state side by side, each labelled by its prop — `defaultChecked`, `indeterminate`, `readOnly`, `invalid`, `disabled`. |
+| [without-label.tsx](examples/without-label.tsx) | Bare boxes in table rows, named for assistive tech and submitted with the form — `aria-label`, `name`, `value`. |
+| [indicator.tsx](examples/indicator.tsx) | The box alone on selectable tiles: the toggle button carries `aria-pressed`, the box only shows it — `Checkbox.Indicator`. |
 | [controlled.tsx](examples/controlled.tsx) | The parent owns the selection; «select all» turns indeterminate on a partial one — `checked`, `onCheckedChange`, `indeterminate`. |
-| [in-form.tsx](examples/in-form.tsx) | Consent in a sign-up form: a hint under the text, an error after a submit without the tick — `required`, `hint`, `error`. |
+| [in-form.tsx](examples/in-form.tsx) | Consent in a sign-up form: the required tick and an optional subscription, a hint under the text, an error after a submit without the tick — `required`, `optional`, `hint`, `error`. |
 
 ## Mistakes
 - `<Checkbox.Root onChange={…}>` → use `onCheckedChange={(checked) => …}`.
@@ -167,5 +180,5 @@ No `labels`.
 - `style` on `Checkbox.Root` expecting to style the field → it goes to the hidden input; use `className`.
 
 ## Related
-- **Built from:** [Hint](../hint/COMPONENT.md) (`hint`, `error`); the row is a native `<label>`
+- **Built from:** [Label](../label/COMPONENT.md) (the `required` / `optional` marks), [Hint](../hint/COMPONENT.md) (`hint`, `error`), [VisuallyHidden](../visually-hidden/COMPONENT.md); the row is a native `<label>`
 - **See also:** [Radio](../radio/COMPONENT.md), [Switch](../switch/COMPONENT.md), [SegmentedControl](../segmented-control/COMPONENT.md); `Checkbox.Indicator` inside [Select](../select/COMPONENT.md) and [TagSelect](../tag-select/COMPONENT.md) rows

package/src/components/checkbox/examples/controlled.tsx

@@ -1,5 +1,5 @@
 /** The parent owns the selection; «select all» turns indeterminate on a partial one — `checked`, `onCheckedChange`, `indeterminate`. */
-import { Checkbox } from "prime-ui-kit";
+import { Checkbox, Fieldset } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
@@ -11,7 +11,7 @@ export default function CheckboxControlledExample() {
   const all = selected.length === DOCUMENTS.length;
 
   return (
-    <div className={styles.list}>
+    <Fieldset aria-label="Документы к отправке">
       <Checkbox.Root
         checked={all}
         indeterminate={selected.length > 0 && !all}
@@ -22,20 +22,22 @@ export default function CheckboxControlledExample() {
         </Checkbox.Label>
       </Checkbox.Root>
       <div className={styles.nested}>
-        {DOCUMENTS.map((document) => (
-          <Checkbox.Root
-            key={document}
-            checked={selected.includes(document)}
-            onCheckedChange={(checked) =>
-              setSelected((current) =>
-                checked ? [...current, document] : current.filter((item) => item !== document),
-              )
-            }
-          >
-            <Checkbox.Label>{document}</Checkbox.Label>
-          </Checkbox.Root>
-        ))}
+        <Fieldset aria-label="Документы">
+          {DOCUMENTS.map((document) => (
+            <Checkbox.Root
+              key={document}
+              checked={selected.includes(document)}
+              onCheckedChange={(checked) =>
+                setSelected((current) =>
+                  checked ? [...current, document] : current.filter((item) => item !== document),
+                )
+              }
+            >
+              <Checkbox.Label>{document}</Checkbox.Label>
+            </Checkbox.Root>
+          ))}
+        </Fieldset>
       </div>
-    </div>
+    </Fieldset>
   );
 }