prime-ui-kit 0.9.0 → 0.9.1

package/src/components/command-menu/examples/overview.tsx

@@ -0,0 +1,61 @@
+/** A button or ⌘K opens the palette: the query filters the groups by value and keywords, Enter runs the active command — `CommandMenu.Item`, `keywords`. */
+import { Button, CommandMenu, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+export default function CommandMenuOverviewExample() {
+  const [open, setOpen] = React.useState(false);
+  const close = () => setOpen(false);
+
+  React.useEffect(() => {
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "k" && (event.metaKey || event.ctrlKey)) {
+        event.preventDefault();
+        setOpen((value) => !value);
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, []);
+
+  return (
+    <>
+      <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
+        Поиск по приложению · ⌘K
+      </Button.Root>
+      <CommandMenu.Root open={open} onOpenChange={setOpen} aria-label="Поиск по приложению">
+        <CommandMenu.Input placeholder="Попробуйте «отчёт» или «billing»" />
+        <CommandMenu.List>
+          <CommandMenu.Empty />
+          <CommandMenu.Group label="Страницы">
+            <CommandMenu.Item value="дашборд" keywords="home главная" onSelect={close}>
+              <CommandMenu.ItemIcon>
+                <Icon name="nav.dashboard" />
+              </CommandMenu.ItemIcon>
+              Дашборд
+            </CommandMenu.Item>
+            <CommandMenu.Item value="отчёты" keywords="analytics аналитика" onSelect={close}>
+              <CommandMenu.ItemIcon>
+                <Icon name="object.document" />
+              </CommandMenu.ItemIcon>
+              Отчёты
+            </CommandMenu.Item>
+            <CommandMenu.Item value="команда" keywords="people users" onSelect={close}>
+              <CommandMenu.ItemIcon>
+                <Icon name="object.users" />
+              </CommandMenu.ItemIcon>
+              Команда
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+          <CommandMenu.Group label="Настройки">
+            <CommandMenu.Item value="счета и оплата" keywords="billing invoices" onSelect={close}>
+              <CommandMenu.ItemIcon>
+                <Icon name="object.receipt" />
+              </CommandMenu.ItemIcon>
+              Счета и оплата
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+        </CommandMenu.List>
+      </CommandMenu.Root>
+    </>
+  );
+}

package/src/components/command-menu/examples/sizes.tsx

@@ -1,74 +1,53 @@
-/** CommandMenu.Dialog `size` xs → xl: rows, text, icons and the search row follow the tier. Match the density of the app. */
-import { File, Folder } from "lucide-react";
-import { Button, CommandMenu, type ControlSize } from "prime-ui-kit";
+/** Every size tier: rows, text, icons and the search row follow it; match the density of the app — `size`. */
+import { Button, CommandMenu, type ControlSize, Icon } from "prime-ui-kit";
 import * as React from "react";
 
-import styles from "./examples.module.css";
-
 const SIZES: ControlSize[] = ["xs", "s", "m", "l", "xl"];
 
+const FILES = ["Договор поставки.pdf", "Счёт № 1042.pdf", "Акт сверки за сентябрь.pdf"];
+
 export default function CommandMenuSizesExample() {
   const [open, setOpen] = React.useState(false);
   const [size, setSize] = React.useState<ControlSize>("m");
-  const close = () => setOpen(false);
 
   return (
     <>
-      <div className={styles.row}>
-        {SIZES.map((s) => (
-          <Button.Root
-            key={s}
-            size={s}
-            variant="soft"
-            tone="neutral"
-            onClick={() => {
-              setSize(s);
-              setOpen(true);
-            }}
-          >
-            {s}
-          </Button.Root>
-        ))}
-      </div>
-
-      <CommandMenu.Dialog
+      {SIZES.map((tier) => (
+        <Button.Root
+          key={tier}
+          size={tier}
+          variant="soft"
+          tone="neutral"
+          onClick={() => {
+            setSize(tier);
+            setOpen(true);
+          }}
+        >
+          {tier}
+        </Button.Root>
+      ))}
+      <CommandMenu.Root
         open={open}
         onOpenChange={setOpen}
         size={size}
         aria-label="Поиск файлов"
         labels={{ search: "Найти файл" }}
       >
-        <CommandMenu.InputRow>
-          <CommandMenu.Input />
-        </CommandMenu.InputRow>
+        <CommandMenu.Input />
         <CommandMenu.List>
           <CommandMenu.Empty />
-          <CommandMenu.Group heading="Файлы">
-            <CommandMenu.Item value="договор" onSelect={close}>
-              <CommandMenu.ItemIcon as={File} />
-              Договор поставки.pdf
-            </CommandMenu.Item>
-            <CommandMenu.Item value="счёт" onSelect={close}>
-              <CommandMenu.ItemIcon as={File} />
-              Счёт № 1042.pdf
-            </CommandMenu.Item>
-          </CommandMenu.Group>
-          <CommandMenu.Group heading="Папки">
-            <CommandMenu.Item value="бюджет" onSelect={close}>
-              <CommandMenu.ItemIcon as={Folder} />
-              <CommandMenu.ItemText description="Финансы / 2026 / Квартал 3">
-                Бюджет на квартал
-              </CommandMenu.ItemText>
-            </CommandMenu.Item>
-            <CommandMenu.Item value="презентация" onSelect={close}>
-              <CommandMenu.ItemIcon as={Folder} />
-              <CommandMenu.ItemText description="Маркетинг / Запуски">
-                Презентация продукта
-              </CommandMenu.ItemText>
-            </CommandMenu.Item>
+          <CommandMenu.Group label="Файлы">
+            {FILES.map((file) => (
+              <CommandMenu.Item key={file} value={file} onSelect={() => setOpen(false)}>
+                <CommandMenu.ItemIcon>
+                  <Icon name="action.download" />
+                </CommandMenu.ItemIcon>
+                {file}
+              </CommandMenu.Item>
+            ))}
           </CommandMenu.Group>
         </CommandMenu.List>
-      </CommandMenu.Dialog>
+      </CommandMenu.Root>
     </>
   );
 }

package/src/components/command-menu/examples/states.tsx

@@ -1,4 +1,4 @@
-/** A long list that scrolls under the fixed search row, a disabled item hidden from results and custom empty-state texts. Use for picking one entry from a long list by typing. */
+/** A disabled item stays visible but muted and is skipped by the arrows, and an empty result speaks in the words of the task — `disabled`, `labels`. */
 import { Button, CommandMenu } from "prime-ui-kit";
 import * as React from "react";
 
@@ -9,15 +9,8 @@ const CITIES = [
   "Екатеринбург",
   "Казань",
   "Нижний Новгород",
-  "Челябинск",
-  "Красноярск",
   "Самара",
-  "Уфа",
-  "Ростов-на-Дону",
-  "Омск",
   "Краснодар",
-  "Воронеж",
-  "Пермь",
 ];
 
 export default function CommandMenuStatesExample() {
@@ -29,19 +22,16 @@ export default function CommandMenuStatesExample() {
       <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
         Выбрать склад
       </Button.Root>
-
-      <CommandMenu.Dialog
+      <CommandMenu.Root
         open={open}
         onOpenChange={setOpen}
         aria-label="Выбор склада"
-        labels={{ empty: "Склад не найден", emptyHint: "Склада в этом городе пока нет" }}
+        labels={{ empty: "Склад не найден", emptyHint: "В этом городе склада пока нет" }}
       >
-        <CommandMenu.InputRow>
-          <CommandMenu.Input placeholder="Город склада" aria-label="Город склада" />
-        </CommandMenu.InputRow>
+        <CommandMenu.Input placeholder="Город склада" />
         <CommandMenu.List>
           <CommandMenu.Empty />
-          <CommandMenu.Group heading="Склады">
+          <CommandMenu.Group label="Склады">
             {CITIES.map((city) => (
               <CommandMenu.Item key={city} value={city} onSelect={close}>
                 {city}
@@ -52,7 +42,7 @@ export default function CommandMenuStatesExample() {
             </CommandMenu.Item>
           </CommandMenu.Group>
         </CommandMenu.List>
-      </CommandMenu.Dialog>
+      </CommandMenu.Root>
     </>
   );
 }

package/src/components/command-menu/examples/structure.tsx

@@ -0,0 +1,54 @@
+/** Optional parts: a visible title and description, a description line and a key hint in items, and a footer with key hints — `CommandMenu.Title`, `CommandMenu.ItemText`, `CommandMenu.ItemShortcut`, `CommandMenu.Footer`. */
+import { Button, CommandMenu, Icon } from "prime-ui-kit";
+import * as React from "react";
+
+export default function CommandMenuStructureExample() {
+  const [open, setOpen] = React.useState(false);
+  const close = () => setOpen(false);
+
+  return (
+    <>
+      <Button.Root variant="soft" tone="neutral" onClick={() => setOpen(true)}>
+        Быстрые действия
+      </Button.Root>
+      <CommandMenu.Root open={open} onOpenChange={setOpen}>
+        <CommandMenu.Title>Быстрые действия</CommandMenu.Title>
+        <CommandMenu.Description>Создавайте документы и меняйте настройки</CommandMenu.Description>
+        <CommandMenu.Input />
+        <CommandMenu.List>
+          <CommandMenu.Empty />
+          <CommandMenu.Group label="Документы">
+            <CommandMenu.Item value="новый счёт" keywords="invoice" onSelect={close}>
+              <CommandMenu.ItemIcon>
+                <Icon name="object.document" />
+              </CommandMenu.ItemIcon>
+              <CommandMenu.ItemText description="Черновик в разделе «Счета»">
+                Новый счёт
+              </CommandMenu.ItemText>
+              <CommandMenu.ItemShortcut>⌘N</CommandMenu.ItemShortcut>
+            </CommandMenu.Item>
+            <CommandMenu.Item value="профиль" keywords="account" onSelect={close}>
+              <CommandMenu.ItemIcon>
+                <Icon name="action.settings" />
+              </CommandMenu.ItemIcon>
+              <CommandMenu.ItemText description="Имя, почта, пароль">Профиль</CommandMenu.ItemText>
+              <CommandMenu.ItemShortcut>⌘,</CommandMenu.ItemShortcut>
+            </CommandMenu.Item>
+          </CommandMenu.Group>
+        </CommandMenu.List>
+        <CommandMenu.Footer>
+          <CommandMenu.FooterHint
+            keys={[
+              <Icon key="up" name="nav.chevronUp" />,
+              <Icon key="down" name="nav.chevronDown" />,
+            ]}
+          >
+            Навигация
+          </CommandMenu.FooterHint>
+          <CommandMenu.FooterHint keys={["Enter"]}>Выбрать</CommandMenu.FooterHint>
+          <CommandMenu.FooterHint keys={["Esc"]}>Закрыть</CommandMenu.FooterHint>
+        </CommandMenu.Footer>
+      </CommandMenu.Root>
+    </>
+  );
+}

package/src/components/crossfade/COMPONENT.md

@@ -0,0 +1,104 @@
+# Crossfade
+
+**Category:** feedback
+**Kind:** layout
+
+> A region that cross-fades between its states (loading → data → empty → error) and glides to the new height, so the page below does not jump.
+
+Continuous state change is a foundation of the kit (foundation §1 rule 7): a region never flips from
+one state to another. Crossfade is the mechanic for regions; its loading state is a
+[Skeleton](../skeleton/COMPONENT.md) in the shape of the coming content.
+
+## When to use
+- A card, panel or page region that switches between loading, data, empty and error states of its own content — every such region, not only the prominent ones.
+- A detail panel that shows one record at a time: key it by the record id.
+- Any in-place swap of one block for another where an instant flip would be jarring.
+
+## When not to use
+- A table loading, empty or failing → set `loading`, `empty`, `error` on [DataTable](../data-table/COMPONENT.md); its body already cross-fades between them.
+- Content that only updates (new numbers, one more row) → render it in place; keep the same `state`.
+- Panels the user switches between → [Tabs](../tabs/COMPONENT.md).
+- Showing and hiding a block (disclosure) → [Accordion](../accordion/COMPONENT.md).
+- Floating layers → overlays carry their own motion ([Popover](../popover/COMPONENT.md), [Modal](../modal/COMPONENT.md)).
+
+## Import
+```tsx
+import { Crossfade } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Crossfade          <div>; holds the region's height while it changes
+├─ leaving layer   the previous state, laid over the new one while it fades out (aria-hidden, inert)
+└─ current layer   children of the current state, in flow
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Crossfade
+`ref` → `HTMLDivElement`. A region that cross-fades its content when `state` changes and glides to the new height; still on the first render, instant under reduced motion.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `state` | `string \| number` | — (required) | Key of what the region shows: `"loading"`, `"ready"`, `"empty"`, `"error"` or a record id. A new value cross-fades the old content into the new one; the same value updates in place. |
+| `children` | `ReactNode` | — | Content of the current `state`. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `className`, `aria-busy`, `aria-live`, `role` and the other div attributes. |
+
+## Variants
+Crossfade has no variants: one treatment, keyed by `state`.
+
+### state
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| a status (`"loading"`, `"ready"`, `"empty"`, `"error"`) | the old content fades out over the new one fading in; the height glides | a region's screen states | — |
+| a record id | the same cross-fade between two records | a detail panel showing one record at a time | — |
+| the same value with new children | updated in place, no motion | data refreshes inside one state | — |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| first render | mount | one layer, `data-state="open"`, no motion |
+| swapping | `state` changes | previous layer `data-state="closed"`, `aria-hidden`, `inert`, absolutely placed, fades out over `fast` with `exit` easing and unmounts on `animationend` (timeout fallback); the new layer fades in over `base` with `enter` easing |
+| resizing | the new state has another height | root `data-resizing="true"`: height glides from the old to the new value over `base` with `standard` easing, clipped with a `--prime-focus-space` margin, then returns to `auto` |
+| reduced motion | `prefers-reduced-motion: reduce` | instant swap: no leaving layer, no glide |
+
+Motion is opacity only, so nothing shifts under the pointer; the leaving content keeps its instance (no remount, no repeated effects) until it is gone.
+
+## Layout & spacing
+- No padding, gap or fill of its own: it sits where the swapped content would sit (inside `Card.Body`, a page section, a panel).
+- Width follows the parent; height is the current content's height except while gliding.
+- The loading state is a `Skeleton` with the geometry of the data it stands for (same rows, same line heights), so the swap to data changes neither layout nor height.
+
+## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
+- Renders a plain `<div>`; pass `aria-busy` while the region loads and `aria-live` or `role` when its changes must be announced.
+- The leaving layer is `aria-hidden` and `inert`: screen readers and Tab never reach content that is going away.
+- Move focus yourself when the focused control was in the old state (e.g. the retry button of an error).
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A card region that cross-fades between loading, data, empty and error and glides to the new height — `state`. |
+| [record-switch.tsx](examples/record-switch.tsx) | A detail panel keyed by the record id: picking another client cross-fades the details of a different height — `state`. |
+
+## Mistakes
+- A new `state` on every data refresh (`state={Date.now()}`) → key by what the region shows, not by when it was fetched.
+- Switching states with `{loading ? <Spinner /> : <List />}` and no wrapper → wrap the region in `Crossfade state={status}` and show a `Skeleton` of the list while it loads.
+- A spinner block for content of known shape → a `Skeleton` of that shape; a spinner is for loading with no shape to hold (a button, a status line).
+- Wrapping a DataTable to animate its loading / empty / error → the table body already cross-fades; use its props.
+- Hand-written `opacity` transitions or `height` animations for a state swap → Crossfade owns both, with tokens and reduced motion.
+
+## Related
+- **Built from:** —
+- **See also:** [Skeleton](../skeleton/COMPONENT.md), [DataTable](../data-table/COMPONENT.md), [EmptyPage](../empty-page/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), [Banner](../banner/COMPONENT.md)

package/src/components/crossfade/examples/examples.module.css

@@ -0,0 +1,65 @@
+/* Layout of the Crossfade scenarios: semantic tokens only. */
+
+.stack {
+  display: grid;
+  justify-items: start;
+  gap: var(--prime-space-4);
+  width: min(100%, calc(var(--prime-space-24) * 5));
+}
+
+.stack > * {
+  justify-self: stretch;
+}
+
+.stack > :first-child {
+  justify-self: start;
+  max-width: 100%;
+}
+
+/* Placeholder rows share the data rows' geometry: the swap to data does not change the height. */
+.payerBar {
+  width: 55%;
+}
+
+.amountBar {
+  width: 20%;
+}
+
+.list {
+  display: grid;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.listRow {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--prime-space-4);
+  padding-block: var(--prime-space-3);
+  border-bottom: var(--prime-border-width) solid var(--prime-color-border-subtle);
+}
+
+.listRow:last-child {
+  border-bottom: 0;
+}
+
+.amount {
+  font-variant-numeric: tabular-nums;
+}
+
+.facts {
+  display: grid;
+  gap: var(--prime-space-3);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.fact {
+  display: grid;
+  grid-template-columns: calc(var(--prime-space-24) + var(--prime-space-4)) minmax(0, 1fr);
+  align-items: baseline;
+  gap: var(--prime-space-4);
+}

package/src/components/crossfade/examples/overview.tsx

@@ -0,0 +1,102 @@
+/** A card region that cross-fades between loading, data, empty and error and glides to the new height — `state`. */
+import {
+  Button,
+  Card,
+  Crossfade,
+  EmptyPage,
+  Icon,
+  SegmentedControl,
+  Skeleton,
+  Typography,
+} from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Status = "loading" | "ready" | "empty" | "error";
+
+const PAYMENTS = [
+  { id: "p1", payer: "ООО «Гранит»", amount: "₽ 94 750" },
+  { id: "p2", payer: "ИП Орлов Д. С.", amount: "₽ 18 000" },
+  { id: "p3", payer: "АО «Альфа Медиа»", amount: "₽ 380 000" },
+];
+
+export default function CrossfadeOverviewExample() {
+  const [status, setStatus] = React.useState<Status>("ready");
+
+  return (
+    <div className={styles.stack}>
+      <SegmentedControl.Root
+        value={status}
+        onValueChange={(value) => setStatus(value as Status)}
+        aria-label="Состояние блока"
+      >
+        <SegmentedControl.Item value="loading">Загрузка</SegmentedControl.Item>
+        <SegmentedControl.Item value="ready">Данные</SegmentedControl.Item>
+        <SegmentedControl.Item value="empty">Пусто</SegmentedControl.Item>
+        <SegmentedControl.Item value="error">Ошибка</SegmentedControl.Item>
+      </SegmentedControl.Root>
+
+      <Card.Root variant="panel">
+        <Card.Header>
+          <Card.Title as="h3">Поступления за сегодня</Card.Title>
+        </Card.Header>
+        <Card.Body>
+          <Crossfade state={status} aria-busy={status === "loading"}>
+            {status === "loading" ? (
+              <ul className={styles.list}>
+                {PAYMENTS.map((payment) => (
+                  <li key={payment.id} className={styles.listRow}>
+                    <Skeleton className={styles.payerBar} />
+                    <Skeleton className={styles.amountBar} />
+                  </li>
+                ))}
+              </ul>
+            ) : null}
+            {status === "ready" ? (
+              <ul className={styles.list}>
+                {PAYMENTS.map((payment) => (
+                  <li key={payment.id} className={styles.listRow}>
+                    <Typography as="span" variant="body-m">
+                      {payment.payer}
+                    </Typography>
+                    <Typography as="span" variant="body-m" className={styles.amount}>
+                      {payment.amount}
+                    </Typography>
+                  </li>
+                ))}
+              </ul>
+            ) : null}
+            {status === "empty" ? (
+              <EmptyPage.Root size="s" aria-labelledby="payments-empty">
+                <EmptyPage.Icon>
+                  <Icon name="status.success" />
+                </EmptyPage.Icon>
+                <EmptyPage.Title as="h4" id="payments-empty">
+                  Поступлений нет
+                </EmptyPage.Title>
+                <EmptyPage.Description>Новые платежи появятся после выписки.</EmptyPage.Description>
+              </EmptyPage.Root>
+            ) : null}
+            {status === "error" ? (
+              <EmptyPage.Root size="s" role="alert" aria-labelledby="payments-error">
+                <EmptyPage.Icon tone="danger">
+                  <Icon name="status.danger" />
+                </EmptyPage.Icon>
+                <EmptyPage.Title as="h4" id="payments-error">
+                  Выписка не загрузилась
+                </EmptyPage.Title>
+                <EmptyPage.Description>Банк не ответил на запрос.</EmptyPage.Description>
+                <EmptyPage.Actions>
+                  <Button.Root variant="soft" tone="neutral" onClick={() => setStatus("ready")}>
+                    Повторить
+                  </Button.Root>
+                </EmptyPage.Actions>
+              </EmptyPage.Root>
+            ) : null}
+          </Crossfade>
+        </Card.Body>
+      </Card.Root>
+    </div>
+  );
+}

package/src/components/crossfade/examples/record-switch.tsx

@@ -0,0 +1,67 @@
+/** A detail panel keyed by the record id: picking another client cross-fades the details of a different height — `state`. */
+import { Card, Crossfade, SegmentedControl, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const CLIENTS = [
+  {
+    id: "granit",
+    name: "ООО «Гранит»",
+    facts: [
+      ["ИНН", "7704123456"],
+      ["Договор", "№ 14/26 от 12.01.2026"],
+    ],
+  },
+  {
+    id: "orlov",
+    name: "ИП Орлов Д. С.",
+    facts: [["ИНН", "502712345678"]],
+  },
+  {
+    id: "alfa",
+    name: "АО «Альфа Медиа»",
+    facts: [
+      ["ИНН", "7812345670"],
+      ["Договор", "№ 3-РК от 01.03.2025"],
+      ["Менеджер", "Ирина Соколова"],
+      ["Отсрочка", "30 дней"],
+    ],
+  },
+];
+
+export default function CrossfadeRecordSwitchExample() {
+  const [clientId, setClientId] = React.useState(CLIENTS[0].id);
+  const client = CLIENTS.find((item) => item.id === clientId) ?? CLIENTS[0];
+
+  return (
+    <div className={styles.stack}>
+      <SegmentedControl.Root value={clientId} onValueChange={setClientId} aria-label="Клиент">
+        {CLIENTS.map((item) => (
+          <SegmentedControl.Item key={item.id} value={item.id}>
+            {item.name}
+          </SegmentedControl.Item>
+        ))}
+      </SegmentedControl.Root>
+
+      <Card.Root variant="panel">
+        <Card.Body>
+          <Crossfade state={client.id}>
+            <ul className={styles.facts} aria-label={client.name}>
+              {client.facts.map(([term, value]) => (
+                <li key={term} className={styles.fact}>
+                  <Typography as="span" variant="body-s" tone="secondary">
+                    {term}
+                  </Typography>
+                  <Typography as="span" variant="body-m">
+                    {value}
+                  </Typography>
+                </li>
+              ))}
+            </ul>
+          </Crossfade>
+        </Card.Body>
+      </Card.Root>
+    </div>
+  );
+}