prime-ui-kit 0.10.0 → 0.11.0

package/dist/skill/foundations.md

@@ -0,0 +1,186 @@
+# Foundations — do it this way
+
+Condensed from the kit's design contract (`docs/foundation.md` in the kit repository). Use semantic
+tokens `--prime-*` only.
+
+## 1. 4px grid
+
+Every spacing, height, padding and gap is a multiple of 4. Spacing tokens: `--prime-space-N` = N × 4px.
+
+| Token | px | Token | px |
+|---|---|---|---|
+| `--prime-space-1` | 4 | `--prime-space-7` | 28 |
+| `--prime-space-2` | 8 | `--prime-space-8` | 32 |
+| `--prime-space-3` | 12 | `--prime-space-10` | 40 |
+| `--prime-space-4` | 16 | `--prime-space-12` | 48 |
+| `--prime-space-5` | 20 | `--prime-space-14` / `-16` | 56 / 64 |
+| `--prime-space-6` | 24 | `--prime-space-20` / `-24` | 80 / 96 |
+
+Off-grid values exist only inside the kit (1px hairline, 2px focus ring). Never in your CSS.
+
+The only places a raw length is allowed: `@media` / `@container` conditions (tokens cannot be used
+there) and props a component documents as a CSS length string, e.g. DataTable column `width: "14rem"`.
+
+## 2. Proximity scale
+
+Things that belong together sit closer than things that do not.
+
+| Between | Gap | Token |
+|---|---|---|
+| label → field | 4–8 | built into fields (`label` prop) — do not add |
+| field → hint/error | 4 | built into fields — do not add |
+| a hand-built field (your own control + `Label.Root` + `Hint.Root`) | label 4–8, hint 4 | `--prime-control-<size>-label-gap`, `--prime-control-<size>-hint-gap` |
+| group heading → its fields | 16 | `--prime-space-4` |
+| field → field in a form | 20 | `--prime-space-5` |
+| inline controls in a row (buttons, filters) | 8 | `--prime-space-2` |
+| switch → switch in a settings list | 20 | `--prime-space-5` |
+| group → group (fieldset, form section) | 32 | `--prime-space-8` |
+| card → card in a grid | 16 | `--prime-space-4` |
+| section → section on a page | 40 | `--prime-space-10` — `PageContent.Body` already does it |
+
+`PageContent.Body` already spaces its direct blocks (cards, tables, sections) 40 apart and `AppShell.Main`
+already carries the page gutters — do not add your own outer padding.
+
+## 3. Size axis
+
+`size: "xs" | "s" | "m" | "l" | "xl"`, default `m` (height 28 · 32 · 36 · 40 · 48).
+
+- Controls of one size line up exactly: Button, Input, Select, Datepicker, SegmentedControl, Tabs.
+- One row = one size. A toolbar of `s` controls is all `s`.
+- Dense tables/toolbars: `s`. Normal screens: `m`. Hero / marketing CTA: `l`.
+- Badges/Kbd inside a control use one step smaller (`m` control → `s` badge).
+- Tables: controls inside cells (Button, Select, Input) use one tier below the table (`m` table → `s`).
+  Row height is a minimum: two-line cells and avatars grow the row by themselves — never set row or
+  cell heights in CSS. Column dividers and the sort icon position come from DataTable; do not restyle
+  them.
+
+## 4. Fill, not lines
+
+- Surfaces stand on one ladder: the page (layer 0) and four nested layers, each one lightness step
+  from its parent. Light: gray page, white card, deeper layers alternate gray / white. Dark: a
+  near-black page, every nested layer a step lighter. Floating layers (menus, popovers, modals,
+  drawers) sit a step above a card, with a shadow.
+- Inside `AppShell` the content panel is the page (gray in light) and a Card on it is layer 1 — white,
+  with the raised whisper; the Sidebar rail beside it is its own layer 1 surface, so it never merges
+  with the content. Fields, chips, neutral buttons and segmented tracks are
+  always one step off the layer they sit on. The kit sets every depth itself (`data-depth`) — just
+  nest components, never set backgrounds yourself.
+- Separate blocks by fill and air. Hairlines (`Divider`) only inside a block: list rows, table rows,
+  between a form and its footer.
+- A card inside a card becomes the next layer automatically — use it sparingly; usually a section
+  heading inside one card is better. The ladder stops at layer 4.
+- Your own bounded block is a `Card` (it takes the right layer wherever it lands). A plain tile with
+  no controls inside may use `background: var(--prime-color-layer-nested)` and
+  `border-radius: var(--prime-card-radius)`; never a transparent box with a border, never a
+  hard-coded `--prime-color-layer-2-bg`.
+
+## 5. Nested radius
+
+Inner radius = outer radius − padding. Panel 12 with padding 4 → items 8. Use `--prime-radius-*`
+(`xs 4 · s 6 · m 8 · l 12 · xl 16 · full`), `--prime-card-radius`, `--prime-panel-radius`.
+
+## 6. tone and color
+
+- `tone` is meaning: `neutral · accent · success · warning · danger · info`. Destructive is `danger`.
+- `color` is decoration from the palette: `gray · blue · green · orange · red · yellow · purple · sky ·
+  pink · teal` — Badge, Avatar, Thumbnail, SegmentedControl dots, count badges of Tabs,
+  SegmentedControl, Sidebar and BottomNav, FileUpload format badges, Timeline dots, TagSelect tags,
+  Kanban column counts, Gantt bars, the author hue of a chat (`Message.Author`). Use one hue per meaning
+  across the product (e.g. «Оплачен» is always green): keep one `Record<Status, PaletteColor>` map.
+- Never convey meaning by color alone: a status badge has text.
+
+### Charts and categorical colors
+
+A chart color does one job, and the job picks the colors:
+
+| Job | Use | Never |
+|---|---|---|
+| identity — which category or series (platforms, sources, regions, teams) | the categorical palette `--prime-color-chart-1…8` (blue, orange, teal, yellow, pink, green, purple, red), `chart-other` for «Прочее»; in kit parts `color` (a ProgressBar / ProgressCircle share, a legend swatch) | `tone`: success / danger read as good / bad |
+| meaning — good, at risk, failed (a status share, a target met) | `tone` | a chart hue |
+| magnitude — how much (heatmap cells) | `--prime-color-chart-scale-1…5` (one hue, near the ground → full); text on steps 4–5 `--prime-color-chart-scale-fg`, on 1–3 `text-primary` | a rainbow |
+
+- Assign series in the palette order and never cycle; a ninth series folds into «Прочее»
+  (`chart-other`). Color follows the entity, not its rank: a filter that hides a series does not
+  repaint the others.
+- One category keeps one hue everywhere: a palette `color` maps to its chart step (`blue` →
+  `chart-1`, `orange` → `chart-2`, `teal` → `chart-3`, `yellow` → `chart-4`, `pink` → `chart-5`,
+  `green` → `chart-6`, `purple` → `chart-7`, `red` → `chart-8`, `gray` → `chart-other`), so a
+  ProgressBar share and a line in a chart library match. `sky` has no chart step (it sits too close to
+  blue).
+- The palette is validated in both themes (OKLCH lightness band, chroma, colour-blind and
+  normal-vision separation of neighbours, ≥ 3:1 on the layer grounds). In scatter-like charts, where
+  any two marks can meet, keep to the first three series or facet.
+- A chart library takes the colors as strings: `chartColors.series[i]`, `chartColors.grid`,
+  `chartColors.axis`, `chartColors.scale[i]` (each a `var(--prime-color-chart-*)`, so the theme
+  switches without a re-render). Gridlines are `chart-grid`, the axis line `chart-axis`, axis labels
+  `text-muted`; values and legends wear text tokens, never the series color.
+- Every chart with two or more series has a legend (ProgressBar / ProgressCircle `legend`,
+  `ChartFrame.Legend`) or direct labels; one series needs none — its title names it. One y-axis per chart: two measures of
+  different scale are two charts.
+- The kit ships no chart library: Sparkline for a trend in a tile, ProgressBar / ProgressCircle for
+  shares and rankings, and for axes and several series a library of your choice (or your own SVG)
+  inside ChartFrame: it brings the panel, the axis-label type, the legend, the tooltip body, the
+  loading / empty / error states and a data table for screen readers, and hands the plot its size
+  and the series colors.
+
+## 7. Typography
+
+| Role | Size/LH | Use |
+|---|---|---|
+| `caption` | 12/16 | meta, table head, timestamps |
+| `body-s` | 13/20 | secondary text, dense UI |
+| `body-m` | 14/20 | default text |
+| `body-l` | 16/24 | reading text |
+| `title-s` | 14/20 600 | card title, group heading inside a card or form |
+| `title-m` | 16/24 600 | page section heading without a card, modal title |
+| `title-l` | 18/24 600 | large block title |
+| `heading-s` | 20/28 600 | page sub-heading |
+| `heading-m` | 24/32 600 | page title (`PageContent.Title`) |
+| `heading-l` | 30/36 600 | marketing / auth title |
+| `display-*` | 36–60 | hero numbers only |
+| `code` | 13/20 mono | identifiers, inline code |
+
+`variant` is required on `Typography`. Weights only 400/500/600. Numbers in tables, prices, dates:
+tabular (the kit does it in DataTable `numeric` columns and `Card.Value`; your own amounts take
+`font-variant-numeric: tabular-nums`). Reading text max width `--prime-layout-reading-max-width`
+(`PageContent.Root maxWidth="readable"`). Secondary text uses `tone="secondary"`/`"muted"` on
+`Typography`, not a lighter custom color.
+
+## 8. Hierarchy through air
+
+Important content gets more space; secondary content is grouped tighter. Do not put everything on one
+level of air: a page with uniform 16px gaps everywhere reads as a list of unrelated things.
+
+## 9. Responsive
+
+- Flexbox for rows/stacks, Grid for two-dimensional layouts; spacing via `gap`.
+- Must work from 320px and at 400% zoom; the full rules are in [responsive.md](responsive.md).
+- Viewport breakpoints 640 · 768 · 1024 · 1280 (`max-width: 639px` for "below 640"), only for the app
+  frame. Components adapt to their own container — do not re-implement that.
+- Touch follows input, not width: your `:hover` styles only inside `@media (hover: hover)`; nothing is
+  hover-only; the kit keeps field text at 16px and gives small controls a 44px hit area on coarse
+  pointers — do not wrap kit fields to change that.
+- Flex children with text: `min-width: 0` + ellipsis or `overflow-wrap: anywhere`.
+- Wide tables on phones: they scroll inside themselves with edge shadows; `stickyFirstColumn`, a column
+  chooser through `hiddenColumns`; never let the page scroll sideways.
+- Card grids: `grid-template-columns: repeat(auto-fill, minmax(min(100%, calc(var(--prime-space-16) * 4)), 1fr))`.
+- A page panel with sections, filter and search, view and the primary action is `PageToolbar`.
+- Sticky parts come from the kit: `AppHeader` (with the `PageToolbar` in `AppHeader.Tools`), the
+  DataTable head and `stickyFirstColumn`, the Gantt header and first column — each sticks inside its
+  own scroller, and the top ones let go on screens lower than 480px. Never a `position: sticky` bar of your own.
+
+## 10. Focus and motion
+
+Never remove focus rings, never set `outline: none`. Kit components ship their motion (press, toggle,
+selection glide, open/close, label morph, rolling counters) — never re-implement or override it. Motion
+of your own elements — when to move at all, the tokens, the rules and recipes — is
+[motion.md](motion.md).
+
+## 11. State changes are continuous
+
+Nothing on screen flips from one state to another. Kit controls already move into their new state.
+Every region you build that changes what it shows — loading → data → empty → error, one record →
+another — renders its content inside `<Crossfade state={status}>`: the old state fades out, the new
+one fades in, the height glides. The loading state is a `<Skeleton>` in the data's geometry (same
+rows, gaps and line heights), so the swap moves nothing; a `Spinner` only where there is no shape to
+hold. Data already on screen stays during a refresh (`aria-busy`), it does not go back to a skeleton.

package/dist/skill/layouts.md

@@ -0,0 +1,262 @@
+# Layouts — app frame, page wrappers, auth
+
+Every screen sits in one frame: `AppShell.Root` with Nav / `AppHeader` / Main (the content panel is the page,
+the nav rail one layer above it) → `PageContent` (header + body). `AppShell.Main` carries the page gutters
+and `PageContent.Body` spaces its blocks 40 apart, so your code adds **no outer padding and no
+margins**. Your CSS only lays out the inside of a block (grids, rows) with `gap` on `--prime-space-*`.
+
+The page recipes are whole, working screens in [patterns/](patterns/) — start from the closest one
+([the list](composition.md#patterns)) and keep its skeleton. The rules behind them are in [composition.md](composition.md).
+
+## App frame (once per app)
+
+Every `Sidebar.Item` gets a `Sidebar.ItemIcon` (in compact mode only icons remain) and is a link:
+`href`, or `asChild` with the router's `NavLink`; `current` marks the current page (`aria-current`), a
+router link sets it itself. Counters go in `Sidebar.ItemCount`. Below 768px the Sidebar becomes an
+off-canvas panel — the app must render a menu button that opens it, otherwise navigation is unreachable
+on phones. `AppHeader` is the top bar of the panel on every width: `AppHeader.MenuButton` shows itself
+below 768px (the Sidebar's own breakpoint), the title says where you are, `AppHeader.Search` opens the
+CommandMenu and folds into an icon on a narrow header. Its row is as high as the Sidebar brand row, so
+the brand and the title read as one line.
+
+```tsx
+import { AppHeader, AppShell, Icon, NotificationProvider, Sidebar } from "prime-ui-kit";
+import { type ReactNode, useState } from "react";
+
+type AppLayoutProps = { title: string; onSearch: () => void; children: ReactNode };
+
+export function AppLayout({ title, onSearch, children }: AppLayoutProps) {
+  const [menuOpen, setMenuOpen] = useState(false);
+  return (
+    <NotificationProvider>
+      <AppShell.Root fillViewport>
+        <AppShell.Nav>
+          <Sidebar.Root open={menuOpen} onOpenChange={setMenuOpen}>
+            <Sidebar.Header>
+              <Sidebar.Brand href="/" description="Интернет-магазин">
+                <Sidebar.BrandLogo>
+                  <Icon name="object.cart" />
+                </Sidebar.BrandLogo>
+                Магазин
+              </Sidebar.Brand>
+              <Sidebar.Toggle variant="header" />
+            </Sidebar.Header>
+            <Sidebar.Content>
+              <Sidebar.Group label="Продажи">
+                <Sidebar.Item href="/" current>
+                  <Sidebar.ItemIcon>
+                    <Icon name="nav.dashboard" />
+                  </Sidebar.ItemIcon>
+                  Обзор
+                </Sidebar.Item>
+                <Sidebar.Item href="/orders">
+                  <Sidebar.ItemIcon>
+                    <Icon name="object.cart" />
+                  </Sidebar.ItemIcon>
+                  Заказы
+                  <Sidebar.ItemCount>12</Sidebar.ItemCount>
+                </Sidebar.Item>
+                <Sidebar.Item href="/clients">
+                  <Sidebar.ItemIcon>
+                    <Icon name="object.users" />
+                  </Sidebar.ItemIcon>
+                  Клиенты
+                </Sidebar.Item>
+              </Sidebar.Group>
+            </Sidebar.Content>
+            <Sidebar.Footer>
+              <Sidebar.Item href="/settings">
+                <Sidebar.ItemIcon>
+                  <Icon name="action.settings" />
+                </Sidebar.ItemIcon>
+                Настройки
+              </Sidebar.Item>
+            </Sidebar.Footer>
+          </Sidebar.Root>
+        </AppShell.Nav>
+        <AppHeader.Root>
+          <AppHeader.Start>
+            <AppHeader.MenuButton aria-expanded={menuOpen} onClick={() => setMenuOpen(true)} />
+            <AppHeader.Title>{title}</AppHeader.Title>
+          </AppHeader.Start>
+          {/* Opens the app's CommandMenu; bind ⌘K to the same handler. */}
+          <AppHeader.Search onClick={onSearch}>Поиск заказов и клиентов</AppHeader.Search>
+        </AppHeader.Root>
+        <AppShell.Main>{children}</AppShell.Main>
+      </AppShell.Root>
+    </NotificationProvider>
+  );
+}
+```
+
+Phone navigation for 2–6 main sections is a `BottomNav.Root` in `AppShell.Footer` (the last child of
+`AppShell.Root`, or the Template `footer` prop) — never in Main, never `position: fixed`, never behind
+your own media query. The shell hides the footer while the Sidebar rail is on screen and shows it
+while the Sidebar is off-canvas, so the bar and the rail never appear together.
+
+Next.js App Router: the package is marked `"use client"`, but a server component cannot dot into it
+(`<Button.Root>`) or pass it callbacks. Put `AppLayout` and every screen in a file that starts with
+`"use client"` and render them from `app/layout.tsx` and the pages; import `bundle.css` in the root
+layout and put `data-theme` on `<html>` there.
+
+A nested record page keeps its `Breadcrumb` at the top of `PageContent.Header`, above the title
+([patterns/detail-page.tsx](patterns/detail-page.tsx)) — not in `AppHeader`. `AppHeader.Actions` holds at most notifications, the account and one primary action; page
+actions stay in `PageContent.Actions`. With `offCanvas="always"` pass `show="always"` to the menu button.
+
+### The page title in the header
+
+A page that wants all its height for the work (a board, a chat, a dense register) may drop the
+heading row in main and let the header carry the page — one or the other, never both:
+
+- `AppHeader.Title as="h1"` is the page's only `<h1>` (the description stays outside its name);
+  main then has no `PageContent.Header`.
+- The page's tools — sections, the period, filters, the page's primary action — go into
+  `AppHeader.Tools` as a `PageToolbar.Root`: the header's second row, full width, sticky with it. The
+  toolbar lays itself out from that width (one row when wide, two on a phone), so the tools wrap
+  under the title instead of squeezing it. `AppHeader.Actions` keeps notifications and the account.
+
+```tsx
+import { AppHeader, Button, Icon, PageToolbar, SegmentedControl } from "prime-ui-kit";
+
+type DealsHeaderProps = { view: string; onViewChange: (view: string) => void };
+
+export function DealsHeader({ view, onViewChange }: DealsHeaderProps) {
+  return (
+    <AppHeader.Root>
+      <AppHeader.Start>
+        <AppHeader.Title as="h1">Сделки</AppHeader.Title>
+      </AppHeader.Start>
+      <AppHeader.Tools>
+        <PageToolbar.Root aria-label="Сделки">
+          <PageToolbar.Sections>
+            <SegmentedControl.Root
+              fullWidth
+              value={view}
+              onValueChange={onViewChange}
+              aria-label="Вид"
+            >
+              <SegmentedControl.Item value="board">Доска</SegmentedControl.Item>
+              <SegmentedControl.Item value="list">Список</SegmentedControl.Item>
+            </SegmentedControl.Root>
+          </PageToolbar.Sections>
+          <PageToolbar.Actions>
+            <Button.Root>
+              <Button.Icon>
+                <Icon name="action.add" />
+              </Button.Icon>
+              Новая сделка
+            </Button.Root>
+          </PageToolbar.Actions>
+        </PageToolbar.Root>
+      </AppHeader.Tools>
+    </AppHeader.Root>
+  );
+}
+```
+
+With React Router put `<Outlet />` as the child and pass `NavLink` through `Sidebar.Item asChild`
+(see `src/layout/sidebar/examples/router.tsx`).
+
+## Navigation structure (the sidebar's content)
+
+The sidebar is the product's map: people scan it, remember where things are and come back. Build it
+from what people do, not from how the backend is split. The full guide with the reasoning is in
+[Sidebar COMPONENT.md → Building the navigation](reference/layout/sidebar/COMPONENT.md#building-the-navigation).
+
+| Level | Kit part | Rule |
+|---|---|---|
+| Everyday places | `Sidebar.Group` without `label` at the top | 2–4 items (Обзор, Входящие); never folded |
+| Category of work | `Sidebar.Group label collapsible` | 3–7 items by frequency; label is one short word with a distinct start (the rail shows its first letters); fold only long or rarely used groups |
+| Views of one section | `Sidebar.Sub` | 2–6 children; the parent only discloses (overview page = first child); one level only |
+| Meta | `Sidebar.Footer` | help, settings, then `Sidebar.Account` with its menu last |
+
+- Icons on every top-level item and sub-list parent, distinct shapes; none on sub-list children.
+- `Sidebar.ItemCount` plain for information (12 new); `color` only when it asks for action (3
+  unanswered, 2 overdue) — it becomes a dot on the rail and on every folded parent, so keep it rare:
+  red for blocked or overdue, blue for new or unread.
+- `persistKey` on `Sidebar.Root` keeps the rail mode and folded groups across reloads; give groups an
+  `id` when labels are translated.
+
+## Page wrapper
+
+- App pages with actions (dashboard, list, detail): `PageContent.Section` — the full width of the panel.
+- Settings and long forms: `PageContent.Root maxWidth="wide"` with a heading column + panel per section
+  ([patterns/settings-page.tsx](patterns/settings-page.tsx)), or `maxWidth="readable"` for a single
+  narrow column of fields.
+- Long reading text (terms, help): `PageContent.Root maxWidth="readable"`.
+- A page as high as the panel (a log, a board, a chat): `AppShell.Root fillViewport` +
+  `PageContent.Root fill`; the body passes its free height to a filling child — DataTable
+  `scrollHeight="fill"`, Crossfade `fill`, `PageContent.Split`. Never compute heights from `100vh`.
+- List + detail (mail, a messenger, a ticket queue): `PageContent.Split` with `PageContent.List` and
+  `PageContent.Detail` in a filling page. Side by side from 48rem of the split's own width, one pane
+  at a time below it with `PageContent.BackButton` first in the detail's header; `open` is «a record
+  is chosen». Each pane gives its last child the free height: a Card with its own `ScrollContainer`
+  (`anchor="end"` for a thread). Details that open over a table and close again are a Drawer instead.
+
+## Which pattern to start from
+
+The table of screens and their patterns lives in [composition.md](composition.md#patterns).
+
+A short form (≤ 4 fields: rename, invite, confirm with a reason) belongs in a `Modal` with the same
+form rules: `Modal.Body` holds the `<form id>`, `Modal.Footer` holds Cancel + submit with `form={id}`
+(see [modal/examples/in-form.tsx](reference/components/modal/examples/in-form.tsx)).
+
+## Multi-step form
+
+`Stepper.Root` (controlled `value`) above one Card that shows the current step's fields; actions
+«Назад» (`variant="soft" tone="neutral"`) and «Далее» / «Готово» at the bottom of the card
+(`Card.Footer`). Mark a failed step with `Stepper.Item status="danger"`. See
+`src/components/stepper/examples/controlled.tsx` and `states.tsx`.
+
+## Auth (sign in, code)
+
+No AppShell. `LoginForm` is the whole card: logo, title, provider buttons, the form and the footer link;
+center it on the canvas. Code step: `DigitInput` inside `LoginForm.Form`. Scenarios for sign-up, password
+reset and code confirmation are in `src/components/login-form/examples/`.
+
+```tsx
+import { Button, Icon, Input, LinkButton, LoginForm } from "prime-ui-kit";
+import styles from "./SignIn.module.css";
+
+export function SignIn() {
+  return (
+    <main className={styles.page}>
+      <LoginForm.Root align="center">
+        <LoginForm.Header>
+          <LoginForm.Logo>
+            <Icon name="object.package" />
+          </LoginForm.Logo>
+          <LoginForm.Title>Вход</LoginForm.Title>
+          <LoginForm.Description>Отправим код на рабочую почту</LoginForm.Description>
+        </LoginForm.Header>
+        <LoginForm.Body>
+          <LoginForm.Form onSubmit={(event) => event.preventDefault()}>
+            <Input.Root label="Рабочая почта" required>
+              <Input.Wrapper>
+                <Input.Field type="email" autoComplete="email" placeholder="name@company.ru" />
+              </Input.Wrapper>
+            </Input.Root>
+            <Button.Root type="submit" fullWidth>
+              Получить код
+            </Button.Root>
+          </LoginForm.Form>
+          <LoginForm.Footer>
+            Нет аккаунта? <LinkButton href="/signup">Зарегистрироваться</LinkButton>
+          </LoginForm.Footer>
+        </LoginForm.Body>
+      </LoginForm.Root>
+    </main>
+  );
+}
+```
+
+```css
+/* SignIn.module.css */
+.page {
+  display: grid;
+  place-items: center;
+  min-height: 100dvh;
+  padding: var(--prime-space-4);
+  background: var(--prime-color-layer-current);
+}
+```