prime-ui-kit 0.15.0 → 0.16.0

package/dist/skill/reference/components/label/COMPONENT.md

@@ -6,7 +6,7 @@
 > Field label (native `<label>`) with required and optional markers.
 
 ## When to use
-- Above a control that has no built-in `label` prop: a custom control, or a hand-built field where you wire the ids yourself.
+- Above a control that has no built-in `label` prop (an embedded `Datepicker.Panel`, a custom control), where you wire the ids yourself.
 - When a label needs an icon (`Label.Icon`) or an inline clarification (`Label.Description`).
 
 ## When not to use
@@ -37,19 +37,28 @@ Label.Root            <label>: text, then the required `*` or the optional marke
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Size of the paired field: xs/s 12/16 · m 13/20 · l/xl 14/20, weight 500. Without it the tier of its host, else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Size of the paired field: xs/s 12/16 · m 13/20 · l/xl 14/20, weight 500. Without it the tier of its host, else `m`; the label provides its tier to the icons inside. |
 | `required` | `boolean` | — | Appends a red `*` (`aria-hidden`). Put native `required` on the control itself. |
 | `optional` | `boolean` | — | Appends the muted optional marker (`labels.optional`). |
-| `disabled` | `boolean` | — | Disabled color for the text and the markers, `aria-disabled`. |
+| `disabled` | `boolean` | — | Disabled color for the text and the markers, `aria-disabled`. A disabled `Fieldset` around the label sets it too. |
+| `secondary` | `boolean` | — | Quieter: secondary text on one line, cut with an ellipsis — a column heading under the group's own label (FieldList). |
 | `labels` | `Partial<LabelLabels>` | — | Built-in strings, see Labels. |
 | `htmlFor` | `string` | — | Id of a native control. For a custom control give the label an `id` and set `aria-labelledby` on the control. |
 | `…rest` | `Omit<LabelHTMLAttributes<HTMLLabelElement>, "size">` | — | `id`, `className` and the other label attributes. |
 
 ### Label.Icon
-`ref` → `HTMLSpanElement`. A muted, non-shrinking icon slot (`aria-hidden`) before the text; kit icons take the label size. Native `<span>` props.
+`ref` → `HTMLSpanElement`. A muted, non-shrinking `<span>` icon slot (`aria-hidden`) before the text; kit icons take the label size.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
 
 ### Label.Description
-`ref` → `HTMLSpanElement`. Regular-weight muted text in the same line (units, context); part of the accessible name. Native `<span>` props.
+`ref` → `HTMLSpanElement`. A regular-weight muted `<span>` in the same line (units, context); part of the accessible name.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
 
 ## Variants
 Label has no `variant` or `tone`.
@@ -70,7 +79,8 @@ Label has no `variant` or `tone`.
 |---|---|---|---|
 | `required` | Red `*` right after the text | Most fields are optional — mark the required ones | — |
 | `optional` | Muted regular «необязательно» right after the text | Most fields are required — mark the optional ones | — |
-| `disabled` | Text, `*`, marker, description and icon in disabled color | The paired control is disabled | — |
+| `disabled` | Text, `*`, marker, description and icon in disabled color | The paired control is disabled (a disabled `Fieldset` around sets it) | — |
+| `secondary` | Secondary text on one line, cut with an ellipsis | A column heading under the group's own label (FieldList) | — |
 
 **Combinations**
 - Recommended: mark the minority of fields in a form; `Label.Description` for units («₽, без НДС»).
@@ -80,21 +90,26 @@ Label has no `variant` or `tone`.
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| disabled | `disabled` | `data-disabled="true"`, `aria-disabled="true"` |
-| size | `size` | `data-size` |
+| disabled | `disabled`, or a disabled `Fieldset` around it | `data-disabled="true"`, `aria-disabled="true"` |
+| secondary | `secondary` | `data-secondary="true"` |
+| size | `size`, else the host tier | `data-size` |
 
-The label has no hover or focus state; clicking it focuses the control bound with `htmlFor`.
+The label has no hover or focus state; clicking it focuses the control bound with `htmlFor`. Its color eases between the states. Disabled sets `--label-dimmed`, which every marker and the description read; a field frame sets it on its label when the native control inside is disabled and nothing passed `disabled` (a state only CSS sees).
 
 ## Layout & spacing
-- Label → field: the tier `label-gap` (`--prime-control-<size>-label-gap`: `--prime-space-1` on xs/s, `--prime-space-2` on m–xl) — the same gap fields use for their built-in label.
+- Label → field: the tier `--field-label-gap` (4 on xs/s, 8 on m–xl) — the same gap fields use for their built-in label. The text comes from the field tier (`--field-label-size`, `--field-label-lh`).
 - Inline-flex, wraps long text (`overflow-wrap: anywhere`); markers are separated by `--prime-space-1`.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 No keyboard interaction.
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - Bind with `htmlFor` to a native control, or set `id` on the label and `aria-labelledby` on a custom control (a `role="radiogroup"`, a `fieldset` of cells).
 - The `*` is `aria-hidden`; requiredness must come from the control (`required`).
 - The optional marker and `Label.Description` are visible text and part of the accessible name; `Label.Icon` is `aria-hidden`.
@@ -109,7 +124,7 @@ No keyboard interaction.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | A standalone label above a hand-built field, linked to its input through `htmlFor` and `id`. |
+| [overview.tsx](examples/overview.tsx) | A label above a calendar that has no label of its own, naming it through `id` and `aria-labelledby` — `id`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size; the label takes the size of the field below it — `size`. |
 | [states.tsx](examples/states.tsx) | A default label next to a disabled one; the markers dim with the text — `disabled`. |
 | [with-icon.tsx](examples/with-icon.tsx) | A muted icon before the text, sized by the label — `Label.Icon`. |

package/dist/skill/reference/components/label/examples/examples.module.css

@@ -1,16 +1,8 @@
 /* Layout of the Label scenarios: semantic tokens only. */
 
-/* overview.tsx: label → control gap of the m tier, like a field's own label. */
+/* overview.tsx, structure.tsx: a label above what it names, at the m-tier label gap. */
 .field {
-  display: flex;
-  flex-direction: column;
-  align-items: flex-start;
+  display: grid;
+  justify-items: start;
   gap: var(--prime-control-m-label-gap);
 }
-
-/* structure.tsx: one label per row, its caption under it. */
-.structure {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-4);
-}

package/dist/skill/reference/components/label/examples/overview.tsx

@@ -1,20 +1,16 @@
-/** A standalone label above a hand-built field, linked to its input through `htmlFor` and `id`. */
-import { Input, Label } from "prime-ui-kit";
+/** A label above a calendar that has no label of its own, naming it through `id` and `aria-labelledby` — `id`. */
+import { Datepicker, Label } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
 export default function LabelOverviewExample() {
-  const inputId = React.useId();
+  const labelId = React.useId();
 
   return (
     <div className={styles.field}>
-      <Label.Root htmlFor={inputId}>Название проекта</Label.Root>
-      <Input.Root id={inputId}>
-        <Input.Wrapper>
-          <Input.Field defaultValue="Редизайн личного кабинета" />
-        </Input.Wrapper>
-      </Input.Root>
+      <Label.Root id={labelId}>Дата отгрузки</Label.Root>
+      <Datepicker.Panel mode="single" role="group" aria-labelledby={labelId} />
     </div>
   );
 }

package/dist/skill/reference/components/label/examples/structure.tsx

@@ -5,7 +5,7 @@ import styles from "./examples.module.css";
 
 export default function LabelStructureExample() {
   return (
-    <div className={styles.structure}>
+    <>
       <div className={styles.field}>
         <Label.Root required>ИНН</Label.Root>
         <Typography as="span" variant="caption" tone="muted">
@@ -27,6 +27,6 @@ export default function LabelStructureExample() {
           Label.Description
         </Typography>
       </div>
-    </div>
+    </>
   );
 }

package/dist/skill/reference/components/link-button/COMPONENT.md

@@ -9,9 +9,11 @@
 - Navigation to another page or URL inside text, cards, forms and footers.
 - Secondary navigation next to a Button of the same size («Войти по паролю» beside «Продолжить»).
 - Quiet service links in footers and metadata (`tone="neutral"`).
+- A trail of links, such as the path to the current page (`tone="muted"`).
+- A link inside running text (`inline`): it takes the text's type and keeps its underline.
 - External links (`target="_blank"` + `rel="noopener noreferrer"`).
 - A router link with the link look (`asChild` around the router's `<Link>`).
-- An inline action inside running text that must read as a link («Отправить ещё раз», «выберите файл») — `asChild` around a `<button type="button">`.
+- An inline action inside running text that must read as a link («Отправить ещё раз», «выберите файл») — `asChild inline` around a `<button type="button">`.
 
 ## When not to use
 - An action without a URL outside running text (save, open a dialog) → use [Button](../button/COMPONENT.md) with `variant="ghost"`.
@@ -26,7 +28,7 @@ import { LinkButton } from "prime-ui-kit";
 
 ## Anatomy
 ```
-LinkButton   <a> (without href when disabled, or the child with asChild); tone, size; size tier for nested icons
+LinkButton   <a href> (without href when disabled, or the child with asChild); tone, size, inline; size tier for nested icons
 └─ children  text and optional Icon before or after it
 ```
 
@@ -39,12 +41,14 @@ LinkButton   <a> (without href when disabled, or the child with asChild); tone,
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tone` | `"accent" \| "neutral"` | `"accent"` | `accent` — a regular link; `neutral` — secondary text, primary on hover, for footers and metadata. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Control tier: text 12 · 13 · 14 · 16 · 18, line height and icon size. Without it the tier of its host (a form, a panel, a hint), else `m`. |
-| `disabled` | `boolean` | `false` | Renders `<a role="link" aria-disabled="true" tabIndex={-1}>` without `href` and swallows the click; `id`, `aria-*` and the other native props stay. |
-| `asChild` | `boolean` | `false` | Merges the link look onto its single child instead of rendering `<a>`: a router link, or a `<button type="button">` for an inline action that is not navigation. `disabled` becomes `aria-disabled` and swallows the click. |
-| `children` | `ReactNode` | — | Text and optional `Icon`s before or after it; the text is the accessible name. |
-| `…rest` | `AnchorHTMLAttributes<HTMLAnchorElement>` | — | `href`, `target`, `rel`, `download`, `onClick`, `className`, `aria-*` and the other anchor attributes. |
+| `href` | `string` | — | The destination. Required without `asChild`; with `asChild` the child carries its own target. |
+| `tone` | `"accent" \| "neutral" \| "muted"` | `"accent"` | `accent` — a regular link; `neutral` — secondary text for footers and metadata; `muted` — muted text with no underline, for trails such as a breadcrumb. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Control tier: text 12 · 13 · 14 · 16 · 18, line height and icon size. Without it the tier of its host (a form, a panel, a hint), else `m`. |
+| `inline` | `boolean` | `false` | A link inside running text: it takes the text's type, wraps with it and keeps its underline drawn. |
+| `disabled` | `boolean` | `false` | Renders `<a role="link" aria-disabled="true">` without `href`, out of the Tab order, and swallows the click; `id`, `aria-*` and the other native props stay. |
+| `asChild` | `boolean` | `false` | Merges the link look onto its single child instead of rendering `<a>`: a router link, or a `<button type="button">` for an inline action that is not navigation. |
+| `children` | `ReactNode` | — | Text and optional `Icon`s before or after it; the text is the accessible name. With `asChild`, the one child element. |
+| `…rest` | `Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href">` | — | `target`, `rel`, `download`, `onClick`, `className`, `aria-*` and the other anchor attributes. |
 
 ## Variants
 
@@ -53,6 +57,7 @@ LinkButton   <a> (without href when disabled, or the child with asChild); tone,
 |---|---|---|---|
 | `accent` | accent text, medium weight; on hover `accent-hover` and an underline appears | regular links in text, forms and cards | yes |
 | `neutral` | secondary text; on hover primary text + underline | footers, metadata, dense service navigation | |
+| `muted` | muted text; on hover primary text, never underlined | trails: the path to the current page | |
 
 ### size
 | Value | Looks like | Use when | Default |
@@ -68,6 +73,7 @@ Match the link size to the surrounding text or to the Button it sits next to. Av
 ### Flags
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
+| `inline` | the running text's size, line height and weight; wraps with the text; underline always drawn | a link inside a sentence | off |
 | `disabled` | `text-disabled`, no underline, `cursor: not-allowed` | a destination is temporarily unavailable | off |
 | `asChild` | the link look on the child (router link, `<button>`; button chrome removed) | router links; inline actions in text | off |
 
@@ -76,31 +82,37 @@ Match the link size to the surrounding text or to the Button it sits next to. Av
 |---|---|---|
 | hover | pointer | hover color + underline (`text-decoration-color: currentColor`) |
 | focus-visible | keyboard | outer focus ring with `--prime-focus-offset`, radius `--prime-radius-xs` |
-| disabled | `disabled` | `<a role="link">` without `href`, `aria-disabled="true"`, `tabIndex=-1`, `data-disabled="true"`; with `asChild` the child gets `aria-disabled="true"` and `data-disabled="true"`, keeps its own focusability, and its click is swallowed |
+| disabled | `disabled` | `<a role="link">` without `href` (so out of the Tab order), `aria-disabled="true"`, `data-disabled="true"`; with `asChild` the child gets `aria-disabled="true"`, `data-disabled="true"` and `tabIndex=-1`, a link child loses its `href`, and its click is swallowed |
 
-Root attributes: `data-size`, `data-tone`, `data-disabled` (only when disabled).
+Root attributes: `data-size`, `data-tone`, `data-inline` (only when inline), `data-disabled` (only when disabled).
 
 Motion: the color and the underline fade in over `fast` (the underline is always drawn, transparent at rest, 1px thick and 3px below the text).
 
 ## Layout & spacing
-- Inline in text: put a space before it (`{" "}`) and keep the text's size.
-- Next to a Button: same `size`, `justify-content: space-between` or `gap: var(--prime-space-3)`.
-- Footer link rows: `gap: var(--prime-space-2) var(--prime-space-4)`, wrap allowed.
-- `max-width: 100%`; `display: inline-flex` with icon and text centered.
+- Inline in text: `inline`, with a space before it (`{" "}`); the link takes the text's type.
+- Next to a Button: same `size`, 12px apart or pushed to the far edge.
+- Footer link rows: 8px between rows, 16px between links, wrap allowed.
+- `max-width: 100%`; `display: inline-flex` with icon and text centered (`inline`: `display: inline`).
+- Text, line height and icon come from the shared tier table (`internal/fieldTier`).
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
-| `Enter` | Follows the link (native `<a>`). |
-| `Tab` | Moves focus; a disabled link is skipped. |
+| `Enter` | Follows the link (native `<a>`). With `asChild` on a `<button>`, `Enter` and `Space` run its action. |
+| `Tab` | Moves focus; a disabled link is skipped, the `asChild` child too (`tabIndex=-1`). |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - A native `<a>`: announced as a link, named by its text.
 - The disabled state is a non-focusable `<a role="link" aria-disabled="true">` without `href`; it keeps `id` and `aria-*`.
 - With `asChild` the child gives the role and name: a router link, or a `<button>` for an action.
 - Icons are decorative; say «новая вкладка» in the text or `aria-label` for external links.
+- `inline` keeps the underline drawn, so a link in text never rests on color alone.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -110,8 +122,8 @@ No `labels`.
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | A link inside running text that keeps the text's size — `href`. |
-| [variants.tsx](examples/variants.tsx) | A regular link and a quiet one for footers and metadata — `tone`. |
+| [overview.tsx](examples/overview.tsx) | A link inside running text takes the text's type and keeps its underline — `href`, `inline`. |
+| [variants.tsx](examples/variants.tsx) | A regular link, a quiet one for footers and metadata, a muted one for trails — `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier; text and icon follow the control tier, xs 12 to xl 18 — `size`. |
 | [states.tsx](examples/states.tsx) | A disabled link drops `href` and leaves the Tab order, in both tones — `disabled`. |
 | [with-icon.tsx](examples/with-icon.tsx) | An icon before or after the text; `Icon` without a size takes the link tier — `Icon`. |
@@ -119,10 +131,11 @@ No `labels`.
 | [as-child.tsx](examples/as-child.tsx) | The link look on a button for an inline action that is not navigation — `asChild`. |
 
 ## Mistakes
-- `<LinkButton onClick={save}>` without `href` → an `<a>` without a URL is not a button: use `<Button.Root variant="ghost">`, or `<LinkButton asChild><button type="button">` inside running text.
+- `<LinkButton onClick={save}>` without `href` → an `<a>` without a URL is not a button (the type requires `href`): use `<Button.Root variant="ghost">`, or `<LinkButton asChild inline><button type="button">` inside running text.
+- A link in a sentence without `inline` → it keeps the control tier and hides its underline at rest; add `inline`.
 - `target="_blank"` without `rel="noopener noreferrer"` → add `rel`.
 - Wrapping a LinkButton in an `<a>` → pass `href` directly.
 
 ## Related
-- **Built from:** —
+- **Built from:** `internal/interactiveElement`, `internal/fieldClasses` (the tier table)
 - **See also:** [Button](../button/COMPONENT.md), [Breadcrumb](../breadcrumb/COMPONENT.md), [Typography](../typography/COMPONENT.md)

package/dist/skill/reference/components/link-button/examples/as-child.tsx

@@ -8,7 +8,7 @@ export default function LinkButtonAsChildExample() {
   return (
     <Typography variant="body-m" tone="secondary">
       {sent ? "Письмо отправлено повторно." : "Не пришло письмо со счётом?"}{" "}
-      <LinkButton asChild>
+      <LinkButton asChild inline>
         <button type="button" onClick={() => setSent(true)}>
           Отправить ещё раз
         </button>

package/dist/skill/reference/components/link-button/examples/external-link.tsx

@@ -5,7 +5,7 @@ export default function LinkButtonExternalLinkExample() {
   return (
     <Typography variant="body-m" tone="secondary">
       Тарифы и лимиты описаны в{" "}
-      <LinkButton href="https://example.com/docs" target="_blank" rel="noopener noreferrer">
+      <LinkButton href="https://example.com/docs" target="_blank" rel="noopener noreferrer" inline>
         документации (новая вкладка)
       </LinkButton>
       .

package/dist/skill/reference/components/link-button/examples/overview.tsx

@@ -1,11 +1,13 @@
-/** A link inside running text that keeps the text's size — `href`. */
+/** A link inside running text takes the text's type and keeps its underline — `href`, `inline`. */
 import { LinkButton, Typography } from "prime-ui-kit";
 
 export default function LinkButtonOverviewExample() {
   return (
     <Typography variant="body-m" tone="secondary">
       Ссылка для входа отправлена на почту. Не пришло письмо?{" "}
-      <LinkButton href="#resend">Отправить ещё раз</LinkButton>
+      <LinkButton href="#resend" inline>
+        Отправить ещё раз
+      </LinkButton>
     </Typography>
   );
 }

package/dist/skill/reference/components/link-button/examples/variants.tsx

@@ -1,7 +1,7 @@
-/** A regular link and a quiet one for footers and metadata — `tone`. */
+/** A regular link, a quiet one for footers and metadata, a muted one for trails — `tone`. */
 import { LinkButton, Typography } from "prime-ui-kit";
 
-const TONES = ["accent", "neutral"] as const;
+const TONES = ["accent", "neutral", "muted"] as const;
 
 export default function LinkButtonVariantsExample() {
   return (

package/dist/skill/reference/components/list/COMPONENT.md

@@ -3,16 +3,17 @@
 **Category:** navigation
 **Kind:** navigation
 
-> A selectable navigation list of rows: the master half of a list + detail screen (conversations, tickets, mail, records).
+> A selectable navigation list of rows: the master half of a list + detail screen (tickets, mail, records).
 
 ## When to use
-- The list side of a list + detail screen (`PageContent.Split` → `PageContent.List`): dialogs, tickets, letters, invoices worked through one by one; the open one is `current`.
+- The list side of a list + detail screen (`PageContent.Split` → `PageContent.Panel kind="list"`): tickets, letters, invoices worked through one by one; the open one is `current`.
 - A short column of records that each open something — a page (`href`, `asChild` with a router link) or a detail pane (`onClick`).
 - A short list the team puts in order (funnel stages, queues, priorities) — `onReorder`, a `value` per item.
 
 ## When not to use
 - App sections → use [Sidebar](../../layout/sidebar/COMPONENT.md) (wide) and [BottomNav](../../layout/bottom-nav/COMPONENT.md) (phone).
 - Panels of one screen → use [Tabs](../tabs/COMPONENT.md).
+- Conversations of a messenger or an inbox (a preview, «печатает…», unread counts) → use [ChatList](../chat-list/COMPONENT.md).
 - Many records compared by columns, sorted, filtered or selected in bulk → use [DataTable](../data-table/COMPONENT.md).
 - A static list of facts inside a card (no selection, nothing opens) → use `Card.List` of [Card](../card/COMPONENT.md) `variant="list"`.
 - Picking a value from options → use [Select](../select/COMPONENT.md) or [Radio](../radio/COMPONENT.md); a menu of commands → [Dropdown](../dropdown/COMPONENT.md).
@@ -24,9 +25,9 @@ import { List } from "prime-ui-kit";
 
 ## Anatomy
 ```
-List.Root                   <ul aria-label>; size → row tier (ControlSizeProvider); onReorder → Dnd.Sortable <ul>
+List.Root                   <ul aria-label>; size (else the host tier) → row tier; onReorder → Dnd.Sortable <ul>
 └─ List.Item                <li> with a full-width <button> | <a href> | asChild element; current, disabled
-   │                         value; with onReorder: Dnd.Handle (or a Spinner while saving) before the row element
+   │                         value; with onReorder: Dnd.Handle (busy while saving) before the row element
    ├─ List.ItemIcon         leading Avatar.Root / Icon (aria-hidden); after the text — a trailing glyph
    ├─ List.ItemText         primary line, truncates
    ├─ List.ItemDescription  second line, muted, truncates
@@ -43,10 +44,10 @@ List.Root                   <ul aria-label>; size → row tier (ControlSizeProvi
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Row tier: height, text, icon and avatar size; counts take one tier down. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Row tier: height, text, icon and avatar size; counts take one tier down. Without it the tier of its host, else `m`. |
 | `onReorder` | `(id: string, beforeId: string \| null) => void \| Promise<void>` | — | Rows reorder by a leading handle (drag, touch hold, Alt + ↑ / ↓): item `value` `id` goes before `beforeId` (`null` = last). Apply with `moveBefore`; a returned promise keeps the row busy, a rejection moves it back. |
 | `labels` | `Partial<ListLabels>` | — | Built-in strings, see Labels. |
-| `aria-label` | `string` | — | Name of the list for screen readers («Диалоги»), when no visible heading names it. |
+| `aria-label` | `string` | — | Name of the list for screen readers («Обращения»), when no visible heading names it. |
 | `children` | `ReactNode` | — | `List.Item`s. |
 | `…rest` | `HTMLAttributes<HTMLUListElement>` | — | `className` and the other `ul` attributes. |
 
@@ -59,13 +60,15 @@ List.Root                   <ul aria-label>; size → row tier (ControlSizeProvi
 | `current` | `boolean` | `false` | The open record: the selected fill and `aria-current` — `"true"` on a button, `"page"` on a link. |
 | `onClick` | `(event: MouseEvent<HTMLButtonElement>) => void` | — | Opens the record; not called while `disabled`. |
 | `href` | `string` | — | Renders an `<a>` instead of a `<button>`; dropped while `disabled`. |
+| `target` | `string` | — | Where the `<a>` opens (`href` only). |
+| `rel` | `string` | — | Relationship of the `<a>` (`href` only). |
 | `asChild` | `boolean` | `false` | Renders the single child (a router link) as the row; its children are the content. |
 | `disabled` | `boolean` | `false` | Muted and out of the Tab order: a disabled button, or `aria-disabled` and no navigation on a link. |
 | `children` | `ReactNode` | — | `List.ItemIcon`, `List.ItemText`, `List.ItemDescription`, `List.ItemMeta`, `List.ItemCount`; loose text becomes the text line. |
 | `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `className` and native attributes of the row element (`target`, `rel` on a link). |
 
 ### List.ItemIcon
-`ref` → `HTMLSpanElement`. Leading `aria-hidden` slot: an `Avatar.Root` sized to the tier, or an `Icon`. After the text it is a trailing glyph.
+`ref` → `HTMLSpanElement`. Leading `aria-hidden` slot: an `Avatar.Root` (without its own `size` it takes the row tier), or an `Icon`. After the text it is a trailing glyph.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -135,13 +138,14 @@ A second line or an avatar makes a row taller than the one-line height; the vert
 | focus-visible | keyboard | the focus ring inside the row edge |
 | disabled | `disabled` | `disabled` on a button; `aria-disabled="true"`, no `href` on a link, `tabindex="-1"` on an `asChild` element; `data-disabled="true"`; disabled text; in a reorderable list the handle is disabled and the row holds its place |
 | reorderable | `onReorder` | `data-reorderable="true"` on the root (a `Dnd.Sortable` `<ul>`); each `<li>` is a sortable item (`data-dnd-item` = `value`) with a leading `Dnd.Handle`; drag by the handle (a touch hold on touch), Alt + ↑ / ↓ from the handle or the row; a lifted row leaves a dashed gap in the row's radius, its neighbours glide, the copy (handle and row, in the row's padding and radius) follows the pointer and sets down in its new place without a jump |
-| saving a move | `onReorder` returned a pending promise | the row stays in its new place, `aria-busy="true"`, a `Spinner` stands in for the handle, the row content dims to 0.6 (`--prime-motion-duration-fast` both ways); a rejection glides the row back |
+| saving a move | `onReorder` returned a pending promise | the row stays in its new place, `aria-busy="true"`, the handle is busy (Dnd: a spinner in the disabled grip), the row content dims to 0.6 (`--prime-motion-fade-fast` both ways); a rejection glides the row back |
+| rows come and go | the data adds or takes out a `List.Item` (`value`, else its key) | a new row rises in once (`enterMotion`), a removed one closes up in place (`listPresence`); the first render stays still |
 
-Root attribute: `data-size`. The fill changes on `background-color` with `--prime-motion-duration-xfast` both ways (0 under reduced motion).
+Root attributes: `data-size`, `role="list"` (the list style reset would drop the list semantics in WebKit). The fill changes on `background-color` with `--prime-motion-fade-xfast` both ways (a fade: reduced motion keeps it).
 
 ## Layout & spacing
 - The root fills its container (`width: 100%`); rows are 4px apart, each row a full-width button with the tier radius and field padding.
-- Put the list on a surface: a `Card.Root` pane in `PageContent.List`, with a `ScrollContainer` around it when it is long — the list never scrolls by itself.
+- Put the list on a surface: a `Card.Root` pane in `PageContent.Panel kind="list"`, with a `ScrollContainer` around it when it is long — the list never scrolls by itself.
 - Row: leading icon · body (text over description) · trail. Beside two lines the trail stacks — meta on top, count below; beside one line they sit in a row.
 - 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).
@@ -150,6 +154,8 @@ Root attribute: `data-size`. The fill changes on `background-color` with `--prim
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves focus between rows; a disabled row is skipped. |
@@ -157,6 +163,8 @@ Root attribute: `data-size`. The fill changes on `background-color` with `--prim
 | `Alt + ↑` · `Alt + ↓` | With `onReorder`, moves the row one place up or down (from its handle or the row). |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `<ul>` named by `aria-label` (or `aria-labelledby` to a visible heading); each row is an `<li>` with a button or link.
 - The open record: `aria-current="true"` on a button (a selection inside the screen), `aria-current="page"` on a link (`href`, `asChild`) — the link points at the current URL. A router link may set it itself.
 - The row's name is its text, description, meta and count, in that order; the leading icon or avatar is `aria-hidden` — the text names the row.
@@ -173,17 +181,17 @@ Root attribute: `data-size`. The fill changes on `background-color` with `--prim
 ## Examples
 | Example | Shows |
 |---|---|
-| [overview.tsx](examples/overview.tsx) | Support dialogs with a preview, the time and the unread count; a click opens a dialog and makes it the current row — `current`, `onClick`. |
+| [overview.tsx](examples/overview.tsx) | A support ticket queue with the client, the last update and the open count; a click opens a ticket and makes it the current row — `current`, `onClick`. |
 | [sizes.tsx](examples/sizes.tsx) | Every size tier: row height, text, icon and count follow the tier — `size`. |
 | [states.tsx](examples/states.tsx) | The open record, a regular row and an unavailable one — `current`, `disabled`. |
-| [with-icon.tsx](examples/with-icon.tsx) | Leading avatars of clients and icons of queues; the slot sizes the avatar to the row tier — `List.ItemIcon`. |
-| [overflow.tsx](examples/overflow.tsx) | A long inbox in a pane of a fixed height: the list scrolls in a ScrollContainer and long names and previews truncate. |
+| [with-icon.tsx](examples/with-icon.tsx) | Leading avatars of clients and icons of queues; an avatar takes the row tier — `List.ItemIcon`. |
+| [overflow.tsx](examples/overflow.tsx) | A long inbox in a pane of a fixed height: the list scrolls in a ScrollContainer and long names and previews truncate — `List.ItemText`, `List.ItemDescription`. |
 | [as-link.tsx](examples/as-link.tsx) | Rows as links to the invoice pages: a plain link, or your router link through the slot — `href`, `asChild`. |
 | [reorder.tsx](examples/reorder.tsx) | Funnel stages in the team's order: a stage moves by its handle or Alt+arrows and is saved on the server — `onReorder`, `value`. |
 
 ## Mistakes
 - Rows hand-drawn from `Button.Root variant="ghost"` with a `soft` current → `List.Item current`.
-- An `Avatar.Root size="s"` in `List.ItemIcon` to fit the row → leave `size` out; the slot sizes the avatar to the tier.
+- An `Avatar.Root size="s"` in `List.ItemIcon` to fit the row → leave `size` out; an avatar without its own `size` takes the row tier.
 - A list as app navigation → Sidebar; as tabs of a screen → Tabs.
 - Several rows `current` at once → one open record; bulk selection belongs to DataTable.
 - A long list without a scroller → wrap it in `ScrollContainer` inside the pane.
@@ -191,5 +199,5 @@ Root attribute: `data-size`. The fill changes on `background-color` with `--prim
 - `onReorder` that rolls the order back itself on an error → return the promise; a rejection moves the row back.
 
 ## Related
-- **Built from:** [Badge](../badge/COMPONENT.md) (`List.ItemCount`), [Dnd](../dnd/COMPONENT.md) (`onReorder`: `Dnd.Sortable`, `Dnd.Handle`), [Spinner](../spinner/COMPONENT.md) (a move being saved)
-- **See also:** [PageContent](../page-content/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Tabs](../tabs/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Card](../card/COMPONENT.md), [Avatar](../avatar/COMPONENT.md)
+- **Built from:** [Badge](../badge/COMPONENT.md) (`List.ItemCount`), [Avatar](../avatar/COMPONENT.md) (`List.ItemIcon` gives an avatar the row tier), [Dnd](../dnd/COMPONENT.md) (`onReorder`: `Dnd.Sortable`, the busy `Dnd.Handle`)
+- **See also:** [PageContent](../page-content/COMPONENT.md), [Sidebar](../../layout/sidebar/COMPONENT.md), [Tabs](../tabs/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [Card](../card/COMPONENT.md)

package/dist/skill/reference/components/list/examples/examples.module.css

@@ -8,11 +8,3 @@
 .scroll {
   height: calc(var(--prime-space-24) * 3);
 }
-
-/* sizes: a caption above each tier's list. */
-.tier {
-  display: flex;
-  width: min(100%, calc(var(--prime-space-24) * 4));
-  flex-direction: column;
-  gap: var(--prime-space-2);
-}

package/dist/skill/reference/components/list/examples/overflow.tsx

@@ -1,4 +1,4 @@
-/** A long inbox in a pane of a fixed height: the list scrolls in a ScrollContainer and long names and previews truncate. */
+/** A long inbox in a pane of a fixed height: the list scrolls in a ScrollContainer and long names and previews truncate — `List.ItemText`, `List.ItemDescription`. */
 import { Card, List, ScrollContainer } from "prime-ui-kit";
 import * as React from "react";
 

package/dist/skill/reference/components/list/examples/overview.tsx

@@ -1,59 +1,60 @@
-/** Support dialogs with a preview, the time and the unread count; a click opens a dialog and makes it the current row — `current`, `onClick`. */
+/** A support ticket queue with the client, the last update and the open count; a click opens a ticket and makes it the current row — `current`, `onClick`. */
 import { Card, List } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
-const DIALOGS = [
+const TICKETS = [
   {
-    id: "granit",
+    id: "T-4821",
+    subject: "Счёт без НДС",
     client: "ООО «Гранит»",
-    preview: "Счёт № 4821 пришёл без НДС",
-    time: "15:02",
-    unread: 2,
+    updated: "15:02",
+    open: 2,
   },
   {
-    id: "leto",
+    id: "T-4817",
+    subject: "Перенос доставки на среду",
     client: "ООО «Лето»",
-    preview: "Можно перенести доставку на среду?",
-    time: "13:40",
-    unread: 0,
+    updated: "13:40",
+    open: 0,
   },
   {
-    id: "kozlov",
+    id: "T-4809",
+    subject: "Подключение ЭДО",
     client: "ИП Козлов",
-    preview: "Подключите, пожалуйста, ЭДО",
-    time: "вчера",
-    unread: 1,
+    updated: "вчера",
+    open: 1,
   },
   {
-    id: "sever",
+    id: "T-4796",
+    subject: "Акт сверки за сентябрь",
     client: "АО «Северсталь-Сервис»",
-    preview: "Акт сверки за сентябрь подписан",
-    time: "6 окт",
-    unread: 0,
+    updated: "6 окт",
+    open: 0,
   },
 ];
 
 export default function ListOverviewExample() {
-  const [dialogId, setDialogId] = React.useState("granit");
+  const [ticketId, setTicketId] = React.useState("T-4821");
 
   return (
     <Card.Root className={styles.pane}>
       <Card.Body>
-        <List.Root aria-label="Диалоги">
-          {DIALOGS.map((dialog) => (
+        <List.Root aria-label="Обращения">
+          {TICKETS.map((ticket) => (
             <List.Item
-              key={dialog.id}
-              current={dialog.id === dialogId}
-              onClick={() => setDialogId(dialog.id)}
+              key={ticket.id}
+              value={ticket.id}
+              current={ticket.id === ticketId}
+              onClick={() => setTicketId(ticket.id)}
             >
-              <List.ItemText>{dialog.client}</List.ItemText>
-              <List.ItemDescription>{dialog.preview}</List.ItemDescription>
-              <List.ItemMeta>{dialog.time}</List.ItemMeta>
-              {dialog.unread > 0 ? (
-                <List.ItemCount color="blue">{dialog.unread}</List.ItemCount>
-              ) : null}
+              <List.ItemText>{ticket.subject}</List.ItemText>
+              <List.ItemDescription>
+                {ticket.id} · {ticket.client}
+              </List.ItemDescription>
+              <List.ItemMeta>{ticket.updated}</List.ItemMeta>
+              {ticket.open > 0 ? <List.ItemCount color="blue">{ticket.open}</List.ItemCount> : null}
             </List.Item>
           ))}
         </List.Root>