prime-ui-kit 0.9.0 → 0.9.1

package/src/components/empty-page/examples/icon-tones.tsx

@@ -1,6 +1,5 @@
-/** `EmptyPage.Icon tone`: `neutral` — no data yet, `accent` — first run and a call to start, `danger` — failed to load. Pick the tone by why the area is empty. */
-import { CloudOff, Inbox, Rocket } from "lucide-react";
-import { Button, EmptyPage } from "prime-ui-kit";
+/** The tile tone tells why the area is empty: no data yet, a first run, or a failed load — `tone`. */
+import { Button, EmptyPage, Icon } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
 
@@ -9,7 +8,7 @@ export default function EmptyPageIconTonesExample() {
     <div className={styles.grid}>
       <EmptyPage.Root size="s" aria-labelledby="tone-neutral">
         <EmptyPage.Icon tone="neutral">
-          <Inbox aria-hidden />
+          <Icon name="object.inbox" />
         </EmptyPage.Icon>
         <EmptyPage.Title id="tone-neutral">Входящих нет</EmptyPage.Title>
         <EmptyPage.Description>Новые заявки появятся здесь.</EmptyPage.Description>
@@ -17,7 +16,7 @@ export default function EmptyPageIconTonesExample() {
 
       <EmptyPage.Root size="s" aria-labelledby="tone-accent">
         <EmptyPage.Icon tone="accent">
-          <Rocket aria-hidden />
+          <Icon name="object.rocket" />
         </EmptyPage.Icon>
         <EmptyPage.Title id="tone-accent">Создайте первый проект</EmptyPage.Title>
         <EmptyPage.Description>Проекты объединяют задачи, файлы и команду.</EmptyPage.Description>
@@ -28,7 +27,7 @@ export default function EmptyPageIconTonesExample() {
 
       <EmptyPage.Root size="s" aria-labelledby="tone-danger">
         <EmptyPage.Icon tone="danger">
-          <CloudOff aria-hidden />
+          <Icon name="status.offline" />
         </EmptyPage.Icon>
         <EmptyPage.Title id="tone-danger">Не удалось загрузить</EmptyPage.Title>
         <EmptyPage.Description>Сервер не ответил. Проверьте соединение.</EmptyPage.Description>

package/src/components/empty-page/examples/narrow.tsx

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

package/src/components/empty-page/examples/{no-results.tsx → overview.tsx}

@@ -1,12 +1,11 @@
-/** An empty search result with the basic parts: Icon, Title (`h2`), Description and Actions. Use it when filters or a query return nothing. */
-import { Search } from "lucide-react";
-import { Button, EmptyPage } from "prime-ui-kit";
+/** An empty search result: icon, title, description and two actions — `EmptyPage.Icon`, `EmptyPage.Actions`. */
+import { Button, EmptyPage, Icon } from "prime-ui-kit";
 
-export default function EmptyPageNoResultsExample() {
+export default function EmptyPageOverviewExample() {
   return (
     <EmptyPage.Root aria-labelledby="empty-search-title">
       <EmptyPage.Icon>
-        <Search aria-hidden />
+        <Icon name="action.search" />
       </EmptyPage.Icon>
       <EmptyPage.Title id="empty-search-title">Ничего не найдено</EmptyPage.Title>
       <EmptyPage.Description>

package/src/components/empty-page/examples/sizes.tsx

@@ -1,30 +1,24 @@
-/** Sizes xs–xl change the icon tile, title size and padding; pass the same `size` to the buttons in Actions. Use small sizes inside cards and tables, large ones for whole pages. */
-import { FileText } from "lucide-react";
-import { Button, type ControlSize, EmptyPage, Typography } from "prime-ui-kit";
+/** 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: ControlSize[] = ["xs", "s", "m", "l", "xl"];
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function EmptyPageSizesExample() {
   return (
     <div className={styles.grid}>
-      {sizes.map((size) => (
-        <div key={size} className={styles.group}>
-          <Typography.Root variant="code" tone="muted">
-            size="{size}"
-          </Typography.Root>
-          <EmptyPage.Root size={size} aria-labelledby={`empty-size-${size}`}>
-            <EmptyPage.Icon>
-              <FileText aria-hidden />
-            </EmptyPage.Icon>
-            <EmptyPage.Title id={`empty-size-${size}`}>Счетов нет</EmptyPage.Title>
-            <EmptyPage.Description>Выставленные счета появятся здесь.</EmptyPage.Description>
-            <EmptyPage.Actions>
-              <Button.Root size={size}>Выставить счёт</Button.Root>
-            </EmptyPage.Actions>
-          </EmptyPage.Root>
-        </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>
   );

package/src/components/example-frame/COMPONENT.md

@@ -1,6 +1,7 @@
 # ExampleFrame
 
 **Category:** infrastructure
+**Kind:** layout
 
 > A documentation frame: live preview, source code and device width in one block.
 
@@ -19,34 +20,34 @@ import { ExampleFrame } from "prime-ui-kit";
 ```
 
 ## Anatomy
-- `ExampleFrame.Root` — the frame: toolbar (pane switch Preview / Code, theme toggle, copy button, device switch) and either the preview stage or the code pane.
-  - `ExampleFrame.Stage` — marks the content shown in the preview. Without a Stage all `children` are previewed.
+```
+ExampleFrame               frame: toolbar + preview stage or code pane
+├─ (toolbar)               SegmentedControl Preview / Code, theme Button, copy Button, device SegmentedControl
+└─ (stage)                 children, laid out by previewLayout
+```
 
 ## API
 
-### ExampleFrame.Root
-Does not forward a ref; no native props.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `code` | `string` | — (required) | Source shown on the code pane (TS/TSX highlighting via CodeBlock) and copied by the copy button. |
-| `children` | `ReactNode` | — | Preview content; if an `ExampleFrame.Stage` is among the children, only its children are previewed. |
-| `className` | `string` | — | Extra class on the frame. |
-| `colorScheme` | `"light" \| "dark"` | — | Preview theme, controlled. |
-| `defaultColorScheme` | `"light" \| "dark"` | `"light"` | Initial preview theme, uncontrolled. |
-| `onColorSchemeChange` | `(scheme: "light" \| "dark") => void` | — | Called when the theme toggle is pressed. |
-| `viewport` | `"desktop" \| "tablet" \| "mobile"` | — | Preview width, controlled. |
-| `defaultViewport` | `"desktop" \| "tablet" \| "mobile"` | `"desktop"` | Initial preview width, uncontrolled. |
-| `onViewportChange` | `(v: "desktop" \| "tablet" \| "mobile") => void` | — | Called when the device switch changes. |
-| `showThemeToggle` | `boolean` | `true` | Show the light/dark toggle in the toolbar. |
-| `onCopy` | `() => void` | — | Called after `code` was copied to the clipboard. |
-| `previewLayout` | `ExampleFramePreviewLayout` | `"default"` | How preview children are laid out (see Variants). |
-| `labels` | `Partial<ExampleFrameLabels>` | see Accessibility | Toolbar and region strings. |
+### ExampleFrame
+`ref` → `HTMLDivElement`. The documentation frame: a toolbar (pane switch, theme toggle, copy button, device switch) above the preview stage or the code pane.
 
-### ExampleFrame.Stage
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | — (required) | Content rendered only in the preview. |
+| `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). |
+| `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. |
+| `colorScheme` | `"light" \| "dark"` | — | Theme of the stage and code pane (controlled); the page theme is untouched. |
+| `defaultColorScheme` | `"light" \| "dark"` | `"light"` | Initial theme (uncontrolled). |
+| `onColorSchemeChange` | `(scheme: "light" \| "dark") => void` | — | Called with the new theme from the theme toggle. |
+| `showThemeToggle` | `boolean` | `true` | Show the light / dark toggle in the toolbar. |
+| `onCopy` | `() => void` | — | Called after `code` was copied to the clipboard. |
+| `labels` | `Partial<ExampleFrameLabels>` | — | Built-in strings, see Labels. |
+| `children` | `ReactNode` | — | Preview content, laid out by `previewLayout`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "onCopy">` | — | `className` and the other attributes of the frame `<div>`. |
 
 ## Variants
 
@@ -54,13 +55,11 @@ Does not forward a ref; no native props.
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `default` | single block centered in the stage | one component | yes |
-| `stack` | centered column, gap 16; a child with `fullWidth` or a table stretches | several blocks one under another | |
-| `stack-center` | centered column, gap 12 | short centered items | |
+| `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-narrow` | column, children capped at `7 × --prime-space-16` and centered | forms and narrow columns | |
-| `dense-stack` | column from the top, gap 4, scrolls past a max height | long lists | |
+| `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 | |
-| `row-start` | wrapping row aligned to the start, gap 12 | toolbars, start-aligned controls | |
-| `row-wrap` | centered wrapping row, items aligned to the top, gap 8 | many small items (badges, tags) | |
+| `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; scrolls when wider than the stage | variant, size and state matrices | |
 
 ### viewport
 | Value | Looks like | Use when | Default |
@@ -80,55 +79,55 @@ Frame look: `bg-sunken` chrome with a `border-subtle` hairline and `radius-xl`;
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| pane | toolbar switch (internal state, starts at Preview) | preview stage or code pane is rendered |
+| pane | toolbar switch (internal, starts at Preview) | preview stage or code pane is rendered |
 | 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 |
-| copy | copy button | its `aria-label` switches to `labels.copied` / `labels.copyError` for 2 s |
-
-Controlled: pass `colorScheme` / `viewport` with their change handlers (e.g. to sync all frames on a page); uncontrolled: `default*` props.
+| copy | copy button | its `aria-label` switches to `labels.copied` / `labels.copyError` for 2 s; on success the copy glyph cross-fades to a check (`data-copy-state`) |
 
 ## Layout & spacing
 - The frame is `max-width: 100%`; long code lines scroll inside the code pane instead of widening the page.
-- The toolbar wraps below 640px of frame width; below 400px the device labels are visually hidden (icons stay).
-- Stack frames one per demo block; spacing between blocks comes from the page (`var(--prime-space-10)`–`var(--prime-space-12)` between sections).
+- 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 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
-- Pane and device switches are SegmentedControls (radio groups); the theme and copy buttons are icon-only Buttons with `aria-label`.
-- The code pane is a focusable `section` (`tabIndex=0`) with `aria-label` from `labels.codeRegion`, so keyboard users can scroll it.
 
-| `labels` key | Default | Used for |
-|---|---|---|
-| `preview` | `"Превью"` | Preview pane option |
-| `code` | `"Код"` | Code pane option |
-| `desktop` | `"Десктоп"` | desktop width option |
-| `tablet` | `"Планшет"` | tablet width option |
-| `mobile` | `"Телефон"` | phone width option |
-| `copy` | `"Копировать код"` | copy button `aria-label` |
-| `copied` | `"Скопировано"` | copy button after success |
-| `copyError` | `"Не удалось скопировать"` | copy button after failure |
-| `themeDark` | `"Включить тёмную тему"` | theme toggle in light mode |
-| `themeLight` | `"Включить светлую тему"` | theme toggle in dark mode |
-| `codeRegion` | `"Код примера"` | `aria-label` of the code pane |
+### Keyboard
+| 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). |
 
-## Examples
-| File | Scenario | When to use this pattern |
+### ARIA
+- 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.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
 |---|---|---|
-| [basic.tsx](examples/basic.tsx) | Preview + code with the full toolbar and a `row` layout | documentation pages |
+| `paneSwitch` | `"Вид примера"` | `aria-label` of the Preview / Code switch. |
+| `preview` | `"Превью"` | Preview pane option. |
+| `code` | `"Код"` | Code pane option. |
+| `viewportSwitch` | `"Ширина превью"` | `aria-label` of the device switch. |
+| `desktop` | `"Десктоп"` | Desktop width option. |
+| `tablet` | `"Планшет"` | Tablet width option. |
+| `mobile` | `"Телефон"` | Phone width option. |
+| `copy` | `"Копировать код"` | Copy button `aria-label`. |
+| `copied` | `"Скопировано"` | Copy button after success. |
+| `copyError` | `"Не удалось скопировать"` | Copy button after a failure. |
+| `themeDark` | `"Включить тёмную тему"` | Theme toggle in the light theme. |
+| `themeLight` | `"Включить светлую тему"` | Theme toggle in the dark theme. |
+| `codeRegion` | `"Код примера"` | `aria-label` of the code pane. |
 
-```tsx
-import { Button, ExampleFrame } from "prime-ui-kit";
-
-export function SaveButtonDemo() {
-  return (
-    <ExampleFrame.Root code="<Button.Root>Сохранить</Button.Root>">
-      <ExampleFrame.Stage>
-        <Button.Root>Сохранить</Button.Root>
-      </ExampleFrame.Stage>
-    </ExampleFrame.Root>
-  );
-}
-```
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A live example next to its source, with the pane, width, theme and copy controls — `code`, `previewLayout`. |
+| [controlled.tsx](examples/controlled.tsx) | Frames of one page share the preview width and theme: the parent owns both — `viewport`, `colorScheme`. |
 
 ## Mistakes
 - Wrapping several preview items in an extra `div` with flex styles → use `previewLayout="row"` or `"stack"`.
@@ -136,6 +135,5 @@ export function SaveButtonDemo() {
 - Expecting `colorScheme` to change the page theme → it only themes the frame's stage and code pane.
 
 ## Related
-- [CodeBlock](../code-block/COMPONENT.md)
-- [SegmentedControl](../segmented-control/COMPONENT.md)
-- [Card](../card/COMPONENT.md)
+- **Built from:** [SegmentedControl](../segmented-control/COMPONENT.md), [Button](../button/COMPONENT.md), [CodeBlock](../code-block/COMPONENT.md), Icon (`view.*`, `viewport.*`, `theme.*`, `action.copy`, `action.check`)
+- **See also:** [Card](../card/COMPONENT.md)

package/src/components/example-frame/examples/controlled.tsx

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

package/src/components/example-frame/examples/overview.tsx

@@ -0,0 +1,16 @@
+/** A live example next to its source, with the pane, width, theme and copy controls — `code`, `previewLayout`. */
+import { Button, ExampleFrame } from "prime-ui-kit";
+
+const CODE = `<Button.Root variant="soft" tone="neutral">Отмена</Button.Root>
+<Button.Root>Сохранить</Button.Root>`;
+
+export default function ExampleFrameOverviewExample() {
+  return (
+    <ExampleFrame code={CODE} previewLayout="row">
+      <Button.Root variant="soft" tone="neutral">
+        Отмена
+      </Button.Root>
+      <Button.Root>Сохранить</Button.Root>
+    </ExampleFrame>
+  );
+}