prime-ui-kit 0.13.1 → 0.15.0

package/dist/skill/reference/components/dnd/examples/table.tsx

@@ -0,0 +1,113 @@
+/** A project estimate as a table: each stage is its own body of rows under a heading row that never moves, a row is carried by its grip within a stage or into another, and the rows stay table rows — `as`, `header`, `kind`, `handle`. */
+import { Dnd, moveBefore, Typography, VisuallyHidden } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Line = { id: string; title: string; hours: number };
+type Stage = { id: string; title: string; lines: Line[] };
+
+const ESTIMATE: Stage[] = [
+  {
+    id: "analysis",
+    title: "Обследование",
+    lines: [
+      { id: "interviews", title: "Интервью с отделом продаж", hours: 12 },
+      { id: "processes", title: "Описание процессов", hours: 20 },
+    ],
+  },
+  {
+    id: "setup",
+    title: "Настройка",
+    lines: [
+      { id: "roles", title: "Роли и права доступа", hours: 8 },
+      { id: "import", title: "Перенос клиентской базы", hours: 16 },
+      { id: "training", title: "Обучение менеджеров", hours: 6 },
+    ],
+  },
+];
+
+/** Moves line `id` in front of `beforeId` (`null` — last) in stage `to`, from whichever stage holds it. */
+const moveLine = (stages: Stage[], id: string, beforeId: string | null, to: string) => {
+  const line = stages.flatMap((stage) => stage.lines).find((item) => item.id === id);
+  if (!line) return stages;
+  return stages.map((stage) => {
+    const rest = stage.lines.filter((item) => item.id !== id);
+    if (stage.id !== to) return { ...stage, lines: rest };
+    return { ...stage, lines: moveBefore([...rest, line], id, beforeId, (item) => item.id) };
+  });
+};
+
+export default function DndTableExample() {
+  const [stages, setStages] = React.useState(ESTIMATE);
+
+  return (
+    <Dnd.Root>
+      <table className={styles.table}>
+        <caption className={styles.caption}>
+          <Typography as="span" variant="title-s">
+            Смета внедрения CRM
+          </Typography>
+        </caption>
+        <thead>
+          <tr>
+            <th scope="col" className={styles.grip}>
+              <VisuallyHidden>Порядок</VisuallyHidden>
+            </th>
+            <th scope="col" className={styles.cell}>
+              <Typography as="span" variant="caption" tone="muted">
+                Работа
+              </Typography>
+            </th>
+            <th scope="col" className={styles.numeric}>
+              <Typography as="span" variant="caption" tone="muted">
+                Часы
+              </Typography>
+            </th>
+          </tr>
+        </thead>
+        {stages.map((stage) => (
+          <Dnd.Sortable
+            key={stage.id}
+            as="tbody"
+            kind="estimate-line"
+            handle
+            aria-label={stage.title}
+            items={stage.lines}
+            getId={(line) => line.id}
+            getLabel={(line) => line.title}
+            onReorder={(id, beforeId) =>
+              setStages((current) => moveLine(current, id, beforeId, stage.id))
+            }
+            header={
+              <tr>
+                <th scope="colgroup" colSpan={3} className={styles.groupCell}>
+                  <Typography as="span" variant="body-m">
+                    {stage.title}
+                  </Typography>
+                </th>
+              </tr>
+            }
+            renderItem={(line) => (
+              <Dnd.SortableItem id={line.id}>
+                <td className={styles.grip}>
+                  <Dnd.Handle />
+                </td>
+                <td className={styles.cell}>
+                  <Typography as="span" variant="body-m">
+                    {line.title}
+                  </Typography>
+                </td>
+                <td className={styles.numeric}>
+                  <Typography as="span" variant="body-m">
+                    {line.hours}
+                  </Typography>
+                </td>
+              </Dnd.SortableItem>
+            )}
+          />
+        ))}
+      </table>
+    </Dnd.Root>
+  );
+}

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

@@ -212,6 +212,7 @@ Motion: the scrim fades, the panel slides from its side over `slow` and leaves o
 | [dismiss.tsx](examples/dismiss.tsx) | An import closes only from its buttons, and not at all while it runs — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the state and opens the drawer from a link, without a trigger — `open`, `onOpenChange`. |
 | [in-form.tsx](examples/in-form.tsx) | A settings form in the panel: the footer button submits the form and an empty name shakes the field and keeps it open until it is filled — `Drawer.Body`, `Drawer.Footer`, `error`. |
+| [screen.tsx](examples/screen.tsx) | A create form in a Drawer opened from the primary action in the app header: grouped fields, errors on submit with focus on the first invalid field, a loading submit, a toast and the new row in the list — `Drawer.Trigger`, `Drawer.Guard`. |
 
 ## Mistakes
 - A drawer without `Drawer.Footer` → add one: «Закрыть» for details, «Отмена» + the submit button for a form. The header × alone is not the end of the panel.

package/dist/skill/reference/components/drawer/examples/dismiss.tsx

@@ -19,7 +19,7 @@ export default function DrawerDismissExample() {
       open={open}
       onOpenChange={setOpen}
       closeOnOutsideClick={false}
-      closeOnEscape={!importing}
+      closeOnEscape={false}
     >
       <Drawer.Trigger>
         <Button.Root variant="soft" tone="neutral">
@@ -27,7 +27,9 @@ export default function DrawerDismissExample() {
         </Button.Root>
       </Drawer.Trigger>
       <Drawer.Content size="s">
-        <Drawer.Header showClose={!importing}>
+        {/* While the import runs, the guard keeps «Отмена» in place, disabled. */}
+        <Drawer.Guard busy={importing} />
+        <Drawer.Header showClose={false}>
           <Drawer.Title>Импорт товаров</Drawer.Title>
           <Drawer.Description>catalog-october.xlsx · 1 240 строк</Drawer.Description>
         </Drawer.Header>
@@ -41,7 +43,7 @@ export default function DrawerDismissExample() {
         </Drawer.Body>
         <Drawer.Footer>
           <Drawer.Close>
-            <Button.Root variant="outline" tone="neutral" disabled={importing}>
+            <Button.Root variant="outline" tone="neutral">
               Отмена
             </Button.Root>
           </Drawer.Close>

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

@@ -6,16 +6,3 @@
   flex-direction: column;
   gap: var(--prime-space-5);
 }
-
-/* overview.tsx: a term / value grid. */
-.details {
-  display: grid;
-  grid-template-columns: auto 1fr;
-  gap: var(--prime-space-2) var(--prime-space-4);
-  margin: 0;
-}
-
-.details dd {
-  margin: 0;
-  font-variant-numeric: tabular-nums;
-}

package/dist/skill/reference/components/drawer/examples/header-actions.tsx

@@ -1,7 +1,5 @@
 /** A record card: its status and a ⋯ menu sit in the header before the close button, one tier smaller — `Drawer.Actions`. */
-import { Badge, Button, Drawer, Dropdown, Icon } from "prime-ui-kit";
-
-import styles from "./examples.module.css";
+import { Badge, Button, DescriptionList, Drawer, Dropdown, Icon } from "prime-ui-kit";
 
 const DEAL = {
   title: "Сделка №1042",
@@ -42,12 +40,10 @@ export default function DrawerHeaderActionsExample() {
           </Drawer.Actions>
         </Drawer.Header>
         <Drawer.Body>
-          <dl className={styles.details}>
-            <dt>Сумма</dt>
-            <dd>{DEAL.amount}</dd>
-            <dt>Ответственный</dt>
-            <dd>{DEAL.owner}</dd>
-          </dl>
+          <DescriptionList.Root>
+            <DescriptionList.Item label="Сумма">{DEAL.amount}</DescriptionList.Item>
+            <DescriptionList.Item label="Ответственный">{DEAL.owner}</DescriptionList.Item>
+          </DescriptionList.Root>
         </Drawer.Body>
         <Drawer.Footer>
           <Drawer.Close>

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

@@ -1,8 +1,5 @@
 /** Order details next to the list: the three zones of every drawer — a header with a close button, a read-only body and a footer with Close and the main action — `Drawer.Trigger`, `Drawer.Body`, `Drawer.Footer`. */
-import { Button, Drawer, Typography } from "prime-ui-kit";
-import * as React from "react";
-
-import styles from "./examples.module.css";
+import { Button, DescriptionList, Drawer } from "prime-ui-kit";
 
 const DETAILS = [
   { term: "Клиент", value: "Анна Смирнова" },
@@ -25,22 +22,13 @@ export default function DrawerOverviewExample() {
           <Drawer.Description>Оформлен 3 октября</Drawer.Description>
         </Drawer.Header>
         <Drawer.Body>
-          <dl className={styles.details}>
+          <DescriptionList.Root>
             {DETAILS.map(({ term, value }) => (
-              <React.Fragment key={term}>
-                <dt>
-                  <Typography as="span" variant="body-m" tone="muted">
-                    {term}
-                  </Typography>
-                </dt>
-                <dd>
-                  <Typography as="span" variant="body-m">
-                    {value}
-                  </Typography>
-                </dd>
-              </React.Fragment>
+              <DescriptionList.Item key={term} label={term}>
+                {value}
+              </DescriptionList.Item>
             ))}
-          </dl>
+          </DescriptionList.Root>
         </Drawer.Body>
         <Drawer.Footer>
           <Drawer.Close>

package/dist/skill/reference/components/drawer/examples/screen.tsx

@@ -0,0 +1,298 @@
+/** A create form in a Drawer opened from the primary action in the app header: grouped fields, errors on submit with focus on the first invalid field, a loading submit, a toast and the new row in the list — `Drawer.Trigger`, `Drawer.Guard`. */
+import {
+  AppHeader,
+  Badge,
+  Button,
+  Checkbox,
+  DataTable,
+  type DataTableColumn,
+  Drawer,
+  Fieldset,
+  Icon,
+  Input,
+  PageContent,
+  PageToolbar,
+  Radio,
+  Select,
+  SmartFilter,
+  Textarea,
+  useNotifications,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./screen.module.css";
+
+type Client = { id: string; name: string; kind: "company" | "person"; manager: string };
+type Errors = Partial<Record<"name" | "inn" | "email", string>>;
+
+const MANAGERS = ["Анна Климова", "Илья Петров", "Марат Хасанов"];
+
+const CLIENTS: Client[] = [
+  { id: "c1", name: "ООО «Северный ветер»", kind: "company", manager: "Анна Климова" },
+  { id: "c2", name: "АО «Техностиль»", kind: "company", manager: "Илья Петров" },
+  { id: "c3", name: "ИП Соколова М. А.", kind: "person", manager: "Анна Климова" },
+];
+
+const COLUMNS: DataTableColumn<Client>[] = [
+  { id: "name", header: "Клиент", accessor: "name" },
+  {
+    id: "kind",
+    header: "Тип",
+    cell: (row) =>
+      row.kind === "company" ? (
+        <Badge.Root color="blue">Компания</Badge.Root>
+      ) : (
+        <Badge.Root color="purple">ИП</Badge.Root>
+      ),
+  },
+  { id: "manager", header: "Менеджер", accessor: "manager" },
+];
+
+const CLIENT_WORDS = ["клиент", "клиента", "клиентов"] as const;
+const COMPANY_WORDS = ["компания", "компании", "компаний"] as const;
+
+/** «1 клиент», «3 клиента», «5 клиентов». */
+const plural = (count: number, [one, few, many]: readonly [string, string, string]) => {
+  const tens = count % 100;
+  const ones = count % 10;
+  if (tens >= 11 && tens <= 14) return `${count} ${many}`;
+  if (ones === 1) return `${count} ${one}`;
+  if (ones >= 2 && ones <= 4) return `${count} ${few}`;
+  return `${count} ${many}`;
+};
+
+function validate(data: FormData): Errors {
+  const errors: Errors = {};
+  const name = String(data.get("name") ?? "").trim();
+  const inn = String(data.get("inn") ?? "").replace(/\s/g, "");
+  const email = String(data.get("email") ?? "").trim();
+  if (!name) errors.name = "Введите название клиента";
+  if (!/^\d{10}(\d{2})?$/.test(inn)) errors.inn = "ИНН — 10 цифр для компании или 12 для ИП";
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
+    errors.email = "Введите почту в формате name@company.ru";
+  return errors;
+}
+
+export default function DrawerScreenExample() {
+  const { notify } = useNotifications();
+  const formId = React.useId();
+  const [clients, setClients] = React.useState(CLIENTS);
+  const [open, setOpen] = React.useState(false);
+  const [errors, setErrors] = React.useState<Errors>({});
+  const [saving, setSaving] = React.useState(false);
+  const [dirty, setDirty] = React.useState(false);
+  const [manager, setManager] = React.useState(MANAGERS[0]);
+  const [search, setSearch] = React.useState("");
+
+  // Drawer.Guard holds every way out while saving and asks before an edited form is discarded.
+  const changeOpen = (next: boolean) => {
+    setOpen(next);
+    if (!next) {
+      setErrors({});
+      setDirty(false);
+    }
+  };
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const form = event.currentTarget;
+    const data = new FormData(form);
+    const found = validate(data);
+    setErrors(found);
+    const firstInvalid = (["name", "inn", "email"] as const).find((key) => found[key]);
+    if (firstInvalid) {
+      form.querySelector<HTMLInputElement>(`[name="${firstInvalid}"]`)?.focus();
+      return;
+    }
+    setSaving(true);
+    window.setTimeout(() => {
+      const name = String(data.get("name")).trim();
+      setClients((list) => [
+        {
+          id: `c${list.length + 1}`,
+          name,
+          kind: data.get("kind") === "person" ? "person" : "company",
+          manager,
+        },
+        ...list,
+      ]);
+      setSaving(false);
+      setDirty(false);
+      setOpen(false);
+      notify({ tone: "success", title: "Клиент добавлен", description: name });
+    }, 900);
+  };
+
+  const query = search.trim().toLowerCase();
+  const shown = clients.filter((client) => client.name.toLowerCase().includes(query));
+  const people = clients.filter((client) => client.kind === "person").length;
+
+  return (
+    <>
+      {/* The page lives in the app header: the only h1, the counts under it, search and the one
+          primary action — the Drawer trigger — in the tools row; main has no PageContent.Header. */}
+      <AppHeader.Root>
+        <AppHeader.Start>
+          <AppHeader.Title>
+            Клиенты
+            <AppHeader.Description>
+              {plural(clients.length, CLIENT_WORDS)} ·{" "}
+              {plural(clients.length - people, COMPANY_WORDS)} и {people} ИП
+            </AppHeader.Description>
+          </AppHeader.Title>
+        </AppHeader.Start>
+        <AppHeader.Tools>
+          <SmartFilter.Root fields={[]} search={search} onSearchChange={setSearch}>
+            <PageToolbar.Root aria-label="Клиенты">
+              <PageToolbar.Tools>
+                <SmartFilter.Toolbar />
+              </PageToolbar.Tools>
+              <PageToolbar.Actions>
+                <Drawer.Root open={open} onOpenChange={changeOpen}>
+                  <Drawer.Trigger>
+                    <Button.Root>
+                      <Button.Icon>
+                        <Icon name="action.add" />
+                      </Button.Icon>
+                      Новый клиент
+                    </Button.Root>
+                  </Drawer.Trigger>
+                  <Drawer.Content>
+                    <Drawer.Header>
+                      <Drawer.Title>Новый клиент</Drawer.Title>
+                      <Drawer.Description>
+                        Появится в списке и в выборе клиента при выставлении счёта.
+                      </Drawer.Description>
+                    </Drawer.Header>
+                    <Drawer.Body>
+                      <Drawer.Guard busy={saving} dirty={dirty} />
+                      <form
+                        id={formId}
+                        className={styles.form}
+                        noValidate
+                        onSubmit={submit}
+                        onChange={() => setDirty(true)}
+                      >
+                        <Fieldset label="Реквизиты" disabled={saving}>
+                          <Radio.Group
+                            name="kind"
+                            label="Тип клиента"
+                            defaultValue="company"
+                            orientation="horizontal"
+                          >
+                            <Radio.Root value="company">
+                              <Radio.Label>Компания</Radio.Label>
+                            </Radio.Root>
+                            <Radio.Root value="person">
+                              <Radio.Label>ИП</Radio.Label>
+                            </Radio.Root>
+                          </Radio.Group>
+                          <Input.Root label="Название" error={errors.name}>
+                            <Input.Wrapper>
+                              <Input.Field
+                                name="name"
+                                placeholder="ООО «Ромашка»"
+                                autoComplete="organization"
+                              />
+                            </Input.Wrapper>
+                          </Input.Root>
+                          <div className={styles.pair}>
+                            <Input.Root label="ИНН" error={errors.inn} reserveSupportRow>
+                              <Input.Wrapper>
+                                <Input.Field
+                                  name="inn"
+                                  inputMode="numeric"
+                                  placeholder="7704512908"
+                                />
+                              </Input.Wrapper>
+                            </Input.Root>
+                            <Input.Root label="КПП" optional reserveSupportRow>
+                              <Input.Wrapper>
+                                <Input.Field
+                                  name="kpp"
+                                  inputMode="numeric"
+                                  placeholder="770401001"
+                                />
+                              </Input.Wrapper>
+                            </Input.Root>
+                          </div>
+                        </Fieldset>
+                        <Fieldset label="Контакты" disabled={saving}>
+                          <Input.Root
+                            label="Почта для счетов"
+                            error={errors.email}
+                            hint="На неё уйдут счета и акты"
+                          >
+                            <Input.Wrapper>
+                              <Input.Icon side="start">
+                                <Icon name="field.email" />
+                              </Input.Icon>
+                              <Input.Field
+                                name="email"
+                                type="email"
+                                placeholder="billing@company.ru"
+                              />
+                            </Input.Wrapper>
+                          </Input.Root>
+                          <Select.Root
+                            label="Менеджер"
+                            value={manager}
+                            onValueChange={(next) => {
+                              setManager(next);
+                              setDirty(true);
+                            }}
+                          >
+                            <Select.Trigger>
+                              <Select.Value />
+                            </Select.Trigger>
+                            <Select.Content>
+                              {MANAGERS.map((name) => (
+                                <Select.Item key={name} value={name}>
+                                  {name}
+                                </Select.Item>
+                              ))}
+                            </Select.Content>
+                          </Select.Root>
+                          <Textarea.Root name="note" label="Комментарий" optional rows={2} />
+                          <Checkbox.Root
+                            name="invite"
+                            defaultChecked
+                            hint="Клиент увидит свои счета и акты онлайн"
+                          >
+                            <Checkbox.Label>Пригласить в личный кабинет</Checkbox.Label>
+                          </Checkbox.Root>
+                        </Fieldset>
+                      </form>
+                    </Drawer.Body>
+                    <Drawer.Footer>
+                      <Drawer.Close>
+                        <Button.Root variant="outline" tone="neutral">
+                          Отмена
+                        </Button.Root>
+                      </Drawer.Close>
+                      <Button.Root type="submit" form={formId} loading={saving}>
+                        Добавить клиента
+                      </Button.Root>
+                    </Drawer.Footer>
+                  </Drawer.Content>
+                </Drawer.Root>
+              </PageToolbar.Actions>
+            </PageToolbar.Root>
+          </SmartFilter.Root>
+        </AppHeader.Tools>
+      </AppHeader.Root>
+
+      <PageContent.Root>
+        <PageContent.Body>
+          <DataTable
+            columns={COLUMNS}
+            rows={shown}
+            getRowKey={(row) => row.id}
+            paging="none"
+            empty="Клиентов не найдено"
+          />
+        </PageContent.Body>
+      </PageContent.Root>
+    </>
+  );
+}

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

@@ -8,15 +8,11 @@
   max-width: calc(var(--prime-space-24) * 3);
 }
 
-/* overview.tsx: a list row — the record on the left, its actions button at the end. */
+/* overview.tsx: the record on the left, its actions button at the end. */
 .row {
   display: flex;
   align-items: center;
   justify-content: space-between;
   gap: var(--prime-space-4);
   width: min(100%, calc(var(--prime-space-24) * 4));
-  padding-block: var(--prime-space-1);
-  padding-inline: var(--prime-space-4) var(--prime-space-1);
-  border-radius: var(--prime-radius-l);
-  background: var(--prime-color-layer-nested);
 }

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

@@ -148,7 +148,7 @@ EmptyPage.Root               centered column; size, layout, tone (role="alert" w
 | [variants.tsx](examples/variants.tsx) | The tone tells why the area is empty: no data yet, a first run, or a failed load with a retry — `tone`, `EmptyPage.RetryButton`. |
 | [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 — `tone`, `layout`, `EmptyPage.RetryButton`, `onRetry`. |
+| [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. |
 

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

@@ -1,4 +1,4 @@
-/** A data region that failed to load: the error state takes the region, the retry shows its loading until the data cross-fades in — `tone`, `layout`, `EmptyPage.RetryButton`, `onRetry`. */
+/** 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 * as React from "react";
 
@@ -53,7 +53,13 @@ export default function EmptyPageRegionErrorExample() {
           {state === "loading" ? (
             <Skeleton lines={3} />
           ) : state === "error" ? (
-            <EmptyPage.Root layout="fill" size="s" tone="danger" aria-labelledby="invoices-error">
+            <EmptyPage.Root
+              layout="fill"
+              size="s"
+              tone="danger"
+              labels={{ retry: "Загрузить снова" }}
+              aria-labelledby="invoices-error"
+            >
               <EmptyPage.Icon>
                 <Icon name="status.offline" />
               </EmptyPage.Icon>

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

@@ -59,7 +59,7 @@ ExampleFrame               frame: toolbar + preview stage or code pane
 | `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; scrolls when wider than the stage | variant, size and state matrices | |
+| `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 | |
 
 ### viewport
 | Value | Looks like | Use when | Default |
@@ -87,7 +87,7 @@ 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` scrolls instead).
+- 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 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.
@@ -128,6 +128,7 @@ Frame look: the chrome is a layer of the surface ladder (`data-depth`, one above
 | Example | Shows |
 |---|---|
 | [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`. |
 
 ## Mistakes

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

@@ -0,0 +1,44 @@
+/** 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`. */
+import { Badge, ExampleFrame, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+const STATUSES = [
+  { color: "gray", label: "Черновик" },
+  { color: "blue", label: "На ревью" },
+  { color: "green", label: "Опубликован" },
+] as const;
+
+const CODE = STATUSES.map(
+  ({ color, label }) => `<Badge.Root color="${color}">${label}</Badge.Root>`,
+).join("\n");
+
+export default function ExampleFrameInitialViewExample() {
+  const [copies, setCopies] = React.useState(0);
+
+  return (
+    <>
+      <ExampleFrame
+        code={CODE}
+        previewLayout="matrix"
+        defaultViewport="mobile"
+        defaultColorScheme="dark"
+        showThemeToggle={false}
+        onCopy={() => setCopies((count) => count + 1)}
+      >
+        <div>
+          {STATUSES.map(({ color, label }) => (
+            <div key={color}>
+              <Badge.Root color={color}>{label}</Badge.Root>
+              <Typography as="span" variant="caption" tone="muted">
+                {color}
+              </Typography>
+            </div>
+          ))}
+        </div>
+      </ExampleFrame>
+      <Typography variant="body-s" tone="secondary">
+        Код скопирован: {copies}
+      </Typography>
+    </>
+  );
+}