prime-ui-kit 0.15.0 → 0.16.0

package/dist/skill/reference/components/dropdown/examples/states.tsx

@@ -1,35 +1,43 @@
 /** A regular, a disabled and a destructive item; arrow keys skip the disabled one — `disabled`, `tone`. */
-import { Button, Dropdown, Icon } from "prime-ui-kit";
+import { Button, Dropdown, Icon, Typography } from "prime-ui-kit";
 
 export default function DropdownStatesExample() {
   return (
-    <Dropdown.Root>
-      <Dropdown.Trigger>
-        <Button.Root variant="soft" tone="neutral">
-          Документ
-        </Button.Root>
-      </Dropdown.Trigger>
-      <Dropdown.Content>
-        <Dropdown.Item>
-          <Dropdown.ItemIcon>
-            <Icon name="action.copy" />
-          </Dropdown.ItemIcon>
-          Дублировать
-        </Dropdown.Item>
-        <Dropdown.Item disabled>
-          <Dropdown.ItemIcon>
-            <Icon name="status.locked" />
-          </Dropdown.ItemIcon>
-          Архивировать — нет прав
-        </Dropdown.Item>
-        <Dropdown.Separator />
-        <Dropdown.Item tone="danger">
-          <Dropdown.ItemIcon>
-            <Icon name="action.delete" />
-          </Dropdown.ItemIcon>
-          Удалить
-        </Dropdown.Item>
-      </Dropdown.Content>
-    </Dropdown.Root>
+    <div>
+      <div>
+        <Dropdown.Root>
+          <Dropdown.Trigger>
+            <Button.Root variant="soft" tone="neutral">
+              Документ
+            </Button.Root>
+          </Dropdown.Trigger>
+          <Dropdown.Content>
+            <Dropdown.Item>
+              <Dropdown.ItemIcon>
+                <Icon name="action.copy" />
+              </Dropdown.ItemIcon>
+              Дублировать
+            </Dropdown.Item>
+            <Dropdown.Item disabled>
+              <Dropdown.ItemIcon>
+                <Icon name="status.locked" />
+              </Dropdown.ItemIcon>
+              Архивировать
+              <Dropdown.ItemDescription>Доступно владельцу документа</Dropdown.ItemDescription>
+            </Dropdown.Item>
+            <Dropdown.Separator />
+            <Dropdown.Item tone="danger">
+              <Dropdown.ItemIcon>
+                <Icon name="action.delete" />
+              </Dropdown.ItemIcon>
+              Удалить
+            </Dropdown.Item>
+          </Dropdown.Content>
+        </Dropdown.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          disabled · tone="danger"
+        </Typography>
+      </div>
+    </div>
   );
 }

package/dist/skill/reference/components/empty-page/COMPONENT.md

@@ -40,7 +40,7 @@ EmptyPage.Root               centered column; size, layout, tone (role="alert" w
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Icon tile, title type and padding; given to the controls inside. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Icon tile, title type and padding; given to the controls inside. Without it the tier of its host, else `m`. |
 | `layout` | `"default" \| "fill" \| "compact"` | `"default"` | `default` sizes by content; `fill` stretches to the parent's height and centers; `compact` — a quiet state inside a menu or list: smaller text and icon, no entrance motion. |
 | `tone` | `"neutral" \| "danger"` | `"neutral"` | `neutral` — nothing here (yet); `danger` — the region failed to load: the icon tile turns danger and the root is `role="alert"` unless you pass a `role`. |
 | `labels` | `Partial<EmptyPageLabels>` | — | Built-in strings, see Labels. |
@@ -51,15 +51,22 @@ EmptyPage.Root               centered column; size, layout, tone (role="alert" w
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `tone` | `"neutral" \| "accent" \| "danger"` | `the root's `tone`` | `neutral` — no data yet, `accent` — a first run and a call to start, `danger` — a failed load. |
+| `tone` | `"neutral" \| "accent" \| "danger"` | the root's `tone` | `neutral` — no data yet, `accent` — a first run and a call to start, `danger` — a failed load. |
 | `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the icon), `className` and the other div attributes. |
 
-### EmptyPage.Title · EmptyPage.Description
-`ref` → the element. `<h2>` (or `as`) and `<p>`, both capped at the reading width.
+### EmptyPage.Title
+`ref` → the element. An `<h2>` (or `as`) capped at the reading width.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `as` | `"h2" \| "h3" \| "h4" \| "p"` | `"h2"` | Tag that fits the outline; the look does not change. `p` inside menus, lists and table cells. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `id` (for `aria-labelledby`), `className` and the other attributes. |
+
+### EmptyPage.Description
+`ref` → `HTMLParagraphElement`. A `<p>` capped at the reading width.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `as` | `"h2" \| "h3" \| "h4" \| "p"` | `"h2"` | Title: tag that fits the outline; the look does not change. `p` inside menus, lists and table cells. |
 | `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `id` (for `aria-labelledby`), `className` and the other attributes. |
 
 ### EmptyPage.Actions
@@ -124,15 +131,19 @@ EmptyPage.Root               centered column; size, layout, tone (role="alert" w
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Enter` · `Space` | On `EmptyPage.RetryButton`: retry the load; while the retry runs the button is loading and ignores presses. |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - `tone="danger"` makes the root `role="alert"`, so the failure is announced when it appears; a `role` you pass replaces it.
 - The title is an `<h2>` (`as` picks `h3` / `h4` by the outline, `p` inside menus, lists and table cells); link the root to it with `aria-labelledby` when the empty state replaces a whole region.
 - In a filtered menu or list set `role="status"`, so screen readers announce «Ничего не найдено».
-- The icon is decorative: pass it with `aria-hidden`.
+- `EmptyPage.Icon` is `aria-hidden`: the tile is decorative, the title says what the state is.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -149,11 +160,11 @@ EmptyPage.Root               centered column; size, layout, tone (role="alert" w
 | [sizes.tsx](examples/sizes.tsx) | Every tier changes the icon tile, the title and the padding; buttons in Actions take the same size — `size`. |
 | [data-region.tsx](examples/data-region.tsx) | An empty data region: the empty state stretches over the rest of a card with a header — `layout`. |
 | [region-error.tsx](examples/region-error.tsx) | A data region that failed to load: the error state takes the region, the retry shows its loading until the data cross-fades in; its text comes from labels — `tone`, `layout`, `EmptyPage.RetryButton`, `onRetry`, `labels`. |
-| [compact.tsx](examples/compact.tsx) | The quiet empty state of a search panel: no entrance motion, smaller text, a paragraph title, one action — `layout`, `as`. |
-| [narrow.tsx](examples/narrow.tsx) | In a 320 px side panel the text wraps under the tile and the actions wrap to a second line. |
+| [compact.tsx](examples/compact.tsx) | The quiet empty state of a search popover: no entrance motion, smaller text, a paragraph title, one action — `layout`, `as`. |
+| [narrow.tsx](examples/narrow.tsx) | In a 320 px side panel the text wraps under the tile and the actions wrap to a second line — `EmptyPage.Actions`. |
 
 ## Mistakes
-- Buttons in a non-`m` EmptyPage without `size` → they take the root's tier from context; do not pass another one.
+- A `size` on the Buttons of a sized EmptyPage → leave it out: they take the root's tier from context.
 - A failed load drawn as a neutral empty state → `tone="danger"` on the root; the icon follows.
 - A hand-made «Повторить» with its own pending flag → `EmptyPage.RetryButton` with an async `onRetry`.
 - Clearing the error the moment the retry starts → keep the error state until the retry settles; the button shows the wait.

package/dist/skill/reference/components/empty-page/examples/compact.tsx

@@ -1,23 +1,33 @@
-/** The quiet empty state of a search panel: no entrance motion, smaller text, a paragraph title, one action — `layout`, `as`. */
-import { Button, EmptyPage, Icon } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+/** The quiet empty state of a search popover: no entrance motion, smaller text, a paragraph title, one action — `layout`, `as`. */
+import { Button, EmptyPage, Icon, Popover } from "prime-ui-kit";
 
 export default function EmptyPageCompactExample() {
   return (
-    <div className={styles.panel}>
-      <EmptyPage.Root layout="compact" size="s" role="status">
-        <EmptyPage.Icon>
-          <Icon name="action.search" />
-        </EmptyPage.Icon>
-        <EmptyPage.Title as="p">Ничего не найдено</EmptyPage.Title>
-        <EmptyPage.Description>Нет клиентов с названием «Северный»</EmptyPage.Description>
-        <EmptyPage.Actions>
-          <Button.Root variant="soft" tone="neutral" size="s">
-            Сбросить поиск
-          </Button.Root>
-        </EmptyPage.Actions>
-      </EmptyPage.Root>
-    </div>
+    <Popover.Root>
+      <Popover.Trigger>
+        <Button.Root variant="soft" tone="neutral">
+          <Button.Icon>
+            <Icon name="action.search" />
+          </Button.Icon>
+          Клиенты по запросу «Северный»
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content size="s" aria-label="Клиенты по запросу «Северный»">
+        <EmptyPage.Root layout="compact" role="status">
+          <EmptyPage.Icon>
+            <Icon name="action.search" />
+          </EmptyPage.Icon>
+          <EmptyPage.Title as="p">Ничего не найдено</EmptyPage.Title>
+          <EmptyPage.Description>Нет клиентов с названием «Северный»</EmptyPage.Description>
+          <EmptyPage.Actions>
+            <Popover.Close>
+              <Button.Root variant="soft" tone="neutral">
+                Сбросить поиск
+              </Button.Root>
+            </Popover.Close>
+          </EmptyPage.Actions>
+        </EmptyPage.Root>
+      </Popover.Content>
+    </Popover.Root>
   );
 }

package/dist/skill/reference/components/empty-page/examples/examples.module.css

@@ -1,53 +1,10 @@
 /* Layout of the EmptyPage scenarios: semantic tokens only. */
 
-/* sizes.tsx, variants.tsx: cells of 16rem that wrap; an odd last cell stays centered. */
-.grid {
-  display: flex;
-  flex-wrap: wrap;
-  align-items: flex-start;
-  justify-content: center;
-  gap: var(--prime-space-6);
-  width: 100%;
-  min-width: 0;
-}
-
-.grid > * {
-  flex: 0 1 calc(var(--prime-space-16) * 4);
-  min-width: 0;
-}
-
 /* data-region.tsx, region-error.tsx: the Card's minimum height that the state fills. */
 .region {
   min-height: calc(var(--prime-space-24) * 3);
 }
 
-/* region-error.tsx: the loaded rows — client and amount at the two ends. */
-.list {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-3);
-  margin: 0;
-  padding: 0;
-  list-style: none;
-}
-
-.row {
-  display: flex;
-  justify-content: space-between;
-  gap: var(--prime-space-4);
-  min-width: 0;
-}
-
-/* compact.tsx: a floating panel (menu / listbox) the compact empty state sits in. */
-.panel {
-  box-sizing: border-box;
-  width: min(100%, var(--prime-panel-min-width));
-  padding: var(--prime-panel-padding);
-  border-radius: var(--prime-panel-radius);
-  background: var(--prime-color-layer-floating-bg);
-  box-shadow: var(--prime-shadow-overlay);
-}
-
 /* narrow.tsx: a 320px side panel (the Card's width). */
 .narrow {
   width: min(100%, calc(var(--prime-space-20) * 4));

package/dist/skill/reference/components/empty-page/examples/narrow.tsx

@@ -1,4 +1,4 @@
-/** In a 320 px side panel the text wraps under the tile and the actions wrap to a second line. */
+/** In a 320 px side panel the text wraps under the tile and the actions wrap to a second line — `EmptyPage.Actions`. */
 import { Button, Card, EmptyPage, Icon } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -15,10 +15,10 @@ export default function EmptyPageNarrowExample() {
           Под выбранные регион и категорию никто не подходит. Ослабьте фильтры.
         </EmptyPage.Description>
         <EmptyPage.Actions>
-          <Button.Root variant="outline" tone="neutral" size="s">
+          <Button.Root variant="outline" tone="neutral">
             Сбросить фильтры
           </Button.Root>
-          <Button.Root size="s">Пригласить поставщика</Button.Root>
+          <Button.Root>Пригласить поставщика</Button.Root>
         </EmptyPage.Actions>
       </EmptyPage.Root>
     </Card.Root>

package/dist/skill/reference/components/empty-page/examples/region-error.tsx

@@ -1,5 +1,5 @@
 /** A data region that failed to load: the error state takes the region, the retry shows its loading until the data cross-fades in; its text comes from labels — `tone`, `layout`, `EmptyPage.RetryButton`, `onRetry`, `labels`. */
-import { Button, Card, Crossfade, EmptyPage, Icon, Skeleton, Typography } from "prime-ui-kit";
+import { Button, Card, Crossfade, DescriptionList, EmptyPage, Icon, Skeleton } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
@@ -72,18 +72,13 @@ export default function EmptyPageRegionErrorExample() {
               </EmptyPage.Actions>
             </EmptyPage.Root>
           ) : (
-            <ul className={styles.list}>
+            <DescriptionList.Root align="end">
               {INVOICES.map((invoice) => (
-                <li key={invoice.id} className={styles.row}>
-                  <Typography as="span" variant="body-m">
-                    {invoice.client}
-                  </Typography>
-                  <Typography as="span" variant="body-m" tone="secondary">
-                    {invoice.amount}
-                  </Typography>
-                </li>
+                <DescriptionList.Item key={invoice.id} label={invoice.client}>
+                  {invoice.amount}
+                </DescriptionList.Item>
               ))}
-            </ul>
+            </DescriptionList.Root>
           )}
         </Crossfade>
       </Card.Body>

package/dist/skill/reference/components/empty-page/examples/sizes.tsx

@@ -1,24 +1,24 @@
 /** Every tier changes the icon tile, the title and the padding; buttons in Actions take the same size — `size`. */
 import { Button, EmptyPage, Icon } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function EmptyPageSizesExample() {
   return (
-    <div className={styles.grid}>
+    <div>
       {SIZES.map((size) => (
-        <EmptyPage.Root key={size} size={size} aria-labelledby={`empty-size-${size}`}>
-          <EmptyPage.Icon>
-            <Icon name="object.document" />
-          </EmptyPage.Icon>
-          <EmptyPage.Title id={`empty-size-${size}`}>Счетов нет · {size}</EmptyPage.Title>
-          <EmptyPage.Description>Выставленные счета появятся здесь.</EmptyPage.Description>
-          <EmptyPage.Actions>
-            <Button.Root size={size}>Выставить счёт</Button.Root>
-          </EmptyPage.Actions>
-        </EmptyPage.Root>
+        <div key={size}>
+          <EmptyPage.Root size={size} aria-labelledby={`empty-size-${size}`}>
+            <EmptyPage.Icon>
+              <Icon name="object.document" />
+            </EmptyPage.Icon>
+            <EmptyPage.Title id={`empty-size-${size}`}>Счетов нет · {size}</EmptyPage.Title>
+            <EmptyPage.Description>Выставленные счета появятся здесь.</EmptyPage.Description>
+            <EmptyPage.Actions>
+              <Button.Root>Выставить счёт</Button.Root>
+            </EmptyPage.Actions>
+          </EmptyPage.Root>
+        </div>
       ))}
     </div>
   );

package/dist/skill/reference/components/empty-page/examples/variants.tsx

@@ -1,43 +1,47 @@
 /** The tone tells why the area is empty: no data yet, a first run, or a failed load with a retry — `tone`, `EmptyPage.RetryButton`. */
 import { Button, EmptyPage, Icon } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
 /** A retry that answers after a second, as a slow server would. */
 const retryInbox = () => new Promise<void>((resolve) => window.setTimeout(resolve, 1000));
 
 export default function EmptyPageVariantsExample() {
   return (
-    <div className={styles.grid}>
-      <EmptyPage.Root size="s" aria-labelledby="tone-neutral">
-        <EmptyPage.Icon>
-          <Icon name="object.inbox" />
-        </EmptyPage.Icon>
-        <EmptyPage.Title id="tone-neutral">Входящих нет</EmptyPage.Title>
-        <EmptyPage.Description>Новые заявки появятся здесь.</EmptyPage.Description>
-      </EmptyPage.Root>
+    <div>
+      <div>
+        <EmptyPage.Root size="s" aria-labelledby="tone-neutral">
+          <EmptyPage.Icon>
+            <Icon name="object.inbox" />
+          </EmptyPage.Icon>
+          <EmptyPage.Title id="tone-neutral">Входящих нет</EmptyPage.Title>
+          <EmptyPage.Description>Новые заявки появятся здесь.</EmptyPage.Description>
+        </EmptyPage.Root>
+      </div>
 
-      <EmptyPage.Root size="s" aria-labelledby="tone-accent">
-        <EmptyPage.Icon tone="accent">
-          <Icon name="object.rocket" />
-        </EmptyPage.Icon>
-        <EmptyPage.Title id="tone-accent">Создайте первый проект</EmptyPage.Title>
-        <EmptyPage.Description>Проекты объединяют задачи, файлы и команду.</EmptyPage.Description>
-        <EmptyPage.Actions>
-          <Button.Root>Создать проект</Button.Root>
-        </EmptyPage.Actions>
-      </EmptyPage.Root>
+      <div>
+        <EmptyPage.Root size="s" aria-labelledby="tone-accent">
+          <EmptyPage.Icon tone="accent">
+            <Icon name="object.rocket" />
+          </EmptyPage.Icon>
+          <EmptyPage.Title id="tone-accent">Создайте первый проект</EmptyPage.Title>
+          <EmptyPage.Description>Проекты объединяют задачи, файлы и команду.</EmptyPage.Description>
+          <EmptyPage.Actions>
+            <Button.Root>Создать проект</Button.Root>
+          </EmptyPage.Actions>
+        </EmptyPage.Root>
+      </div>
 
-      <EmptyPage.Root size="s" tone="danger" aria-labelledby="tone-danger">
-        <EmptyPage.Icon>
-          <Icon name="status.offline" />
-        </EmptyPage.Icon>
-        <EmptyPage.Title id="tone-danger">Не удалось загрузить</EmptyPage.Title>
-        <EmptyPage.Description>Сервер не ответил. Проверьте соединение.</EmptyPage.Description>
-        <EmptyPage.Actions>
-          <EmptyPage.RetryButton onRetry={retryInbox} />
-        </EmptyPage.Actions>
-      </EmptyPage.Root>
+      <div>
+        <EmptyPage.Root size="s" tone="danger" aria-labelledby="tone-danger">
+          <EmptyPage.Icon>
+            <Icon name="status.offline" />
+          </EmptyPage.Icon>
+          <EmptyPage.Title id="tone-danger">Не удалось загрузить</EmptyPage.Title>
+          <EmptyPage.Description>Сервер не ответил. Проверьте соединение.</EmptyPage.Description>
+          <EmptyPage.Actions>
+            <EmptyPage.RetryButton onRetry={retryInbox} />
+          </EmptyPage.Actions>
+        </EmptyPage.Root>
+      </div>
     </div>
   );
 }

package/dist/skill/reference/components/example-frame/COMPONENT.md

@@ -21,9 +21,11 @@ import { ExampleFrame } from "prime-ui-kit";
 
 ## Anatomy
 ```
-ExampleFrame               frame: toolbar + preview stage or code pane
+ExampleFrame               frame: toolbar + the pane (a region swap between preview and code)
 ├─ (toolbar)               SegmentedControl Preview / Code, theme Button, copy Button, device SegmentedControl
-└─ (stage)                 children, laid out by previewLayout
+└─ (pane)
+   ├─ (stage)              preview: a sideways ScrollContainer with children, laid out by previewLayout
+   └─ (code pane)          code: a focusable ScrollContainer section with the CodeBlock
 ```
 
 ## API
@@ -36,7 +38,7 @@ ExampleFrame               frame: toolbar + preview stage or code pane
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `code` | `string` | — (required) | Source shown on the code pane (TS / TSX highlighting via CodeBlock) and copied by the copy button. |
-| `previewLayout` | `"default" \| "stack" \| "stack-narrow" \| "full" \| "row" \| "matrix"` | `"default"` | How the preview lays out its children, so snippets need no wrapper divs (see Variants). |
+| `previewLayout` | `"default" \| "stack" \| "stack-narrow" \| "full" \| "row" \| "matrix" \| "matrix-wide"` | `"default"` | How the preview lays out its children, so snippets need no wrapper divs (see Variants). |
 | `viewport` | `"desktop" \| "tablet" \| "mobile"` | — | Preview width (controlled). |
 | `defaultViewport` | `"desktop" \| "tablet" \| "mobile"` | `"desktop"` | Initial preview width (uncontrolled). |
 | `onViewportChange` | `(viewport: "desktop" \| "tablet" \| "mobile") => void` | — | Called with the new width from the device switch. |
@@ -55,11 +57,12 @@ ExampleFrame               frame: toolbar + preview stage or code pane
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `default` | single block centered in the stage | one component | yes |
-| `stack` | centered column, gap 16, children capped at 640px (`10 × --prime-space-16`) so `width: 100%` blocks stay centered; a child with `fullWidth` or a table stretches | several blocks one under another | |
+| `stack` | centered column, gap 16, children capped at the stack measure (`10 × --prime-space-16`) so `width: 100%` blocks stay centered; a child with `fullWidth` or a table stretches | several blocks one under another | |
 | `stack-narrow` | column, children capped at `7 × --prime-space-16` and centered | forms and narrow columns | |
 | `full` | column, gap 16, every child takes the whole stage width | page structure: app shells, page regions | |
 | `row` | centered wrapping row, gap 12, extra vertical padding | a few buttons or controls side by side | |
 | `matrix` | centered grid of labelled cells: each direct child is a row, its children are cells (specimen above its caption); columns (up to 12) line up across rows, are never narrower than their content and grow to 320 / 160 / 128px for 1 / 2 / 3+ columns, so width-less specimens (Slider, `width: 100%` blocks) get a real cell; centered vertically too; when the grid is wider than the stage (a phone frame) each row wraps its cells, centered (`data-matrix-wrap` on the stage) | variant, size and state matrices | |
+| `matrix-wide` | the same rows of labelled cells, one cell under another, each as wide as the stage up to the stack measure (`10 × --prime-space-16`), the caption under the specimen | matrices of specimens as wide as their container: tabs, toolbars, tables | |
 
 ### viewport
 | Value | Looks like | Use when | Default |
@@ -74,12 +77,17 @@ ExampleFrame               frame: toolbar + preview stage or code pane
 | `light` | stage and code pane in the light theme | default | yes |
 | `dark` | stage and code pane in the dark theme (`data-theme="dark"`), switched without color transitions | checking dark mode | |
 
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `showThemeToggle` | the light / dark button in the toolbar; off, the frame keeps its `colorScheme` and shows no toggle | a page that owns the theme of its frames, or a demo that only reads in one scheme | on |
+
 Frame look: the chrome is a layer of the surface ladder (`data-depth`, one above its host) with a `border-subtle` hairline and `radius-xl`; the stage and code pane are wells with `radius-l` (16 − 4 padding = 12). Both wells carry `data-theme`, so each is a page of its own: layer 0 of its scheme, and surfaces in the example count from there.
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| pane | toolbar switch (internal, starts at Preview) | preview stage or code pane is rendered; the device switch shows only with the preview |
+| pane | toolbar switch (internal, starts at Preview) | preview stage or code pane is rendered; the switch cross-fades the two and glides the height (`internal/RegionSwap`); the device switch shows only with the preview |
 | viewport | `viewport` / `defaultViewport` | `data-viewport` on the preview viewport |
 | theme | `colorScheme` / `defaultColorScheme` | `data-theme` on the stage and code pane |
 | layout | `previewLayout` | `data-preview-layout` on the stage |
@@ -87,20 +95,24 @@ Frame look: the chrome is a layer of the surface ladder (`data-depth`, one above
 
 ## Layout & spacing
 - The frame is `max-width: 100%`; long code lines scroll inside the code pane instead of widening the page. The code pane is at most `min(512px, 70vh)` high and scrolls both ways.
-- The stage is at least 160 high with `--prime-space-6` / `--prime-space-4` padding; content wider than it is clipped (`matrix` wraps its rows instead).
-- The toolbar wraps below 40rem of frame width; below 25rem the visible device labels are hidden (icons stay, each option keeps a screen-reader name).
+- The stage is at least 160 high with `--prime-space-6` / `--prime-space-4` padding; content wider than it scrolls inside it under edge shadows (`matrix` wraps its rows instead).
+- The toolbar wraps when it does not fit on one line; narrower than 8 × `--prime-space-20` (measured on the toolbar) the two switches stack, each across the toolbar with `fullWidth` segments. When even then the device titles do not fit, the device switch drops them by itself (icons stay, each option keeps its name).
 - The device width switches at once: `max-width` is layout, so it does not animate.
 - Stack frames one per demo block; spacing between blocks comes from the page.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves through the switches, the theme and copy buttons and the code pane. |
 | `ArrowLeft` · `ArrowRight` | Choose the pane or the width inside a switch (SegmentedControl). |
 
 ### ARIA
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 - The pane and device switches are radio groups named by `labels.paneSwitch` and `labels.viewportSwitch`.
 - The theme and copy buttons are icon-only Buttons with `aria-label`; after copying the label becomes `labels.copied`.
 - The code pane is a focusable `section` with `aria-label` from `labels.codeRegion`, so keyboard users can scroll it.
@@ -129,7 +141,7 @@ Frame look: the chrome is a layer of the surface ladder (`data-depth`, one above
 |---|---|
 | [overview.tsx](examples/overview.tsx) | A live example next to its source, with the pane, width, theme and copy controls — `code`, `previewLayout`. |
 | [initial-view.tsx](examples/initial-view.tsx) | A matrix frame that opens at phone width in the dark theme with no theme switch and counts code copies — `previewLayout`, `defaultViewport`, `defaultColorScheme`, `showThemeToggle`, `onCopy`. |
-| [controlled.tsx](examples/controlled.tsx) | Frames of one page share the preview width and theme: the parent owns both — `viewport`, `colorScheme`. |
+| [controlled.tsx](examples/controlled.tsx) | Frames of one page share the preview width and theme: the parent owns both — `viewport`, `onViewportChange`, `colorScheme`. |
 
 ## Mistakes
 - Wrapping several preview items in an extra `div` with flex styles → use `previewLayout="row"` or `"stack"`.
@@ -137,5 +149,5 @@ Frame look: the chrome is a layer of the surface ladder (`data-depth`, one above
 - Expecting `colorScheme` to change the page theme → it only themes the frame's stage and code pane.
 
 ## Related
-- **Built from:** [SegmentedControl](../segmented-control/COMPONENT.md), [Button](../button/COMPONENT.md), [CodeBlock](../code-block/COMPONENT.md), Icon (`view.*`, `viewport.*`, `theme.*`, `action.copy`, `action.check`)
+- **Built from:** [SegmentedControl](../segmented-control/COMPONENT.md), [Button](../button/COMPONENT.md), [CodeBlock](../code-block/COMPONENT.md), [ScrollContainer](../scroll-container/COMPONENT.md) (the stage, the code pane), Icon (`view.*`, `viewport.*`, `theme.*`, `action.copy`, `action.check`), [AppShell](../../layout/app-shell/COMPONENT.md) (its boundary: a header or a Sidebar in the preview stays in it); `internal/RegionSwap` (the pane switch)
 - **See also:** [Card](../card/COMPONENT.md)

package/dist/skill/reference/components/example-frame/examples/controlled.tsx

@@ -1,8 +1,8 @@
-/** Frames of one page share the preview width and theme: the parent owns both — `viewport`, `colorScheme`. */
+/** Frames of one page share the preview width and theme: the parent owns both — `viewport`, `onViewportChange`, `colorScheme`. */
 import { Button, ExampleFrame, type ExampleFrameViewport, Input } from "prime-ui-kit";
 import * as React from "react";
 
-const BUTTON_CODE = "<Button.Root>Сохранить</Button.Root>";
+const BUTTON_CODE = "<Button.Root>Создать счёт</Button.Root>";
 const INPUT_CODE = `<Input.Root label="Рабочая почта">
   <Input.Wrapper>
     <Input.Field placeholder="name@company.ru" />
@@ -22,7 +22,7 @@ export default function ExampleFrameControlledExample() {
         colorScheme={scheme}
         onColorSchemeChange={setScheme}
       >
-        <Button.Root>Сохранить</Button.Root>
+        <Button.Root>Создать счёт</Button.Root>
       </ExampleFrame>
       <ExampleFrame
         code={INPUT_CODE}

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

@@ -39,7 +39,7 @@ A leaf: rows come from `value` through `renderItem`, which returns one element p
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
 ### FieldList
-Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editable list of records of one shape: column headings once, a row of fields per record (`<ol>`), remove per row, add under the rows; rows stack under 480 px.
+Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editable list of records of one shape: column headings once, a row of fields per record (`<ol>`), remove per row, add under the rows; rows stack in a container under 30rem.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -61,7 +61,7 @@ Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editabl
 | `hint` | `ReactNode` | — | Help text under the list; hidden while `error` shows. |
 | `error` | `ReactNode` | — | A problem of the list as a whole («Добавьте хотя бы одну позицию»); a field's own error goes on that field. |
 | `disabled` | `boolean` | `false` | Disables every field, handle and button; a disabled `Fieldset` around it sets it too. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the headings, buttons and the kit fields that read the host tier. Without it the host tier, else `m`. |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | host tier, else `"m"` | Tier of the headings, buttons and the kit fields that read the host tier. Without it the host tier, else `m`. |
 | `labels` | `Partial<FieldListLabels>` | — | Built-in strings, see Labels. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>` (field-root rule: `className`, `ref` and the rest → frame, `id` → control). |
 
@@ -98,18 +98,21 @@ Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editabl
 | pinned row | `getLocked(item)` | `data-locked="true"` on the `<li>`; a lock, no remove button |
 | invalid | `error` (the list), a field's own `error` | the list's message under the add row; a field's under the field in its row |
 | disabled | `disabled` (or a disabled Fieldset) | `data-disabled="true"` on the frame; fields, handles and buttons disabled through the kit's disabled context |
-| stacked | container narrower than 480 px | heading row hidden, each row's fields in one column with their labels shown |
+| stacked | container narrower than 30rem | heading row hidden, each row's fields in one column with their labels shown |
+| rows come and go | the add button, a remove button, a new `value` | a row the data adds rises in once (`enterMotion`), a removed one closes up in place and the rows below glide up (`listPresence`); the heading row rises in with the first row and closes up with the last (`partPresence`); the first render stays still |
 
 ## Layout & spacing
 - Rows 12 apart (`--prime-space-3`); columns 12 apart; the heading row sits at the tier's label gap above the first row.
-- Every row and the heading row share one track list: `[lead] [columns] [end]`; the lead fits the grip, the end fits a remove button of the tier.
+- Every row and the heading row share one track list: `[lead] [columns] [end]`; the lead is one `xs` control wide (the grip or the lock), the end fits a remove button of the tier.
 - The handle, the lock and the remove button stand on the middle of the first line of fields, so a field's error under it grows the row downwards only.
 - The add button lines up with the first column of fields, 12 under the last row.
-- Under 480 px of its own width (a container query): rows stack, fields 16 apart inside a row, rows 24 apart.
+- Under 30rem of its own width (a container query): rows stack, fields 16 apart inside a row, rows 24 apart.
 
 ## Accessibility
 
 ### Keyboard
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 | Key | Action |
 |---|---|
 | `Tab` | Moves through the fields of a row, then to its remove button and on. |
@@ -117,11 +120,14 @@ Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editabl
 | `Alt + ↑` · `Alt + ↓` | With `reorderable`, moves the row up or down (from its handle). |
 
 ### ARIA
-- The rows are an `<ol>` named by the list `label` (`aria-labelledby`); the list gives each row its position.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+- The rows are an `<ol role="list">` named by the list `label` (`aria-labelledby`); the list gives each row its position, and the role keeps it under `list-style: none` in WebKit.
 - The heading row is `aria-hidden`: each field in a cell carries its column heading as its own label, read but not shown on wide rows.
+- The `<ol>` is described by the list's `hint` and `error` (`aria-describedby`), which speak for every row.
 - In a narrow container the heading row goes and each field's label shows above it.
 - The remove button is «Удалить {row}», the handle «Переместить {row}»: the row's name from `getLabel`, else its number.
-- A pinned row has a lock in place of the handle and no remove button; without `reorderable` the lock is an image named «Закреплена».
+- A pinned row has a lock in place of the handle and no remove button; without `reorderable` the lock is Dnd's lock (an image named «Закреплена»).
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -161,5 +167,5 @@ Generic `FieldList<T>`; `ref` → `HTMLDivElement` (the field frame). An editabl
 - A grip, a remove button and an add button drawn by hand around a `.map()` of fields → FieldList.
 
 ## Related
-- **Built from:** [Button](../button/COMPONENT.md) (add, remove), [Dnd](../dnd/COMPONENT.md) (`reorderable`: `Dnd.Sortable`, `Dnd.Handle`), [Label](../label/COMPONENT.md) (headings), `Icon` (lock), the field frame (label, hint, error)
+- **Built from:** [Button](../button/COMPONENT.md) (add, remove), [Dnd](../dnd/COMPONENT.md) (`reorderable`: `Dnd.Sortable`, `Dnd.Handle`; the lock of a pinned row), [Label](../label/COMPONENT.md) (headings), the field frame (label, [Hint](../hint/COMPONENT.md) for the hint and error), [VisuallyHidden](../visually-hidden/COMPONENT.md)
 - **See also:** [Input](../input/COMPONENT.md), [Select](../select/COMPONENT.md) (icon-only trigger), [ColorPicker](../color-picker/COMPONENT.md) (`ColorPresets`), [Fieldset](../fieldset/COMPONENT.md), [DataTable](../data-table/COMPONENT.md)