prime-ui-kit 0.9.0 → 0.9.2

package/src/components/typography/examples/variants.tsx

@@ -1,49 +1,50 @@
-/** One `variant="body-m"` line with each `weight`, the extreme `tracking` values and `tone="secondary"`. Use to see how the override props change a role. */
-import { Divider, Typography } from "prime-ui-kit";
+/** Every text role from display to caption and code, then every text color on body text — `variant`, `tone`. */
+import { Typography, type TypographyRole } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
+const ROLES: TypographyRole[] = [
+  "display-l",
+  "display-m",
+  "display-s",
+  "heading-l",
+  "heading-m",
+  "heading-s",
+  "title-l",
+  "title-m",
+  "title-s",
+  "body-l",
+  "body-m",
+  "body-s",
+  "caption",
+  "code",
+];
 
-const line = "Съешь же ещё этих мягких французских булок да выпей чаю";
+const TONES = ["default", "secondary", "muted", "accent", "success", "warning", "danger"] as const;
 
 export default function TypographyVariantsExample() {
   return (
-    <div className={styles.scaleList}>
-      <div className={styles.scaleRow}>
-        <Typography.Root variant="body-m" weight="regular">
-          {line}
-        </Typography.Root>
-        <Divider.Root align="start">weight regular</Divider.Root>
-      </div>
-      <div className={styles.scaleRow}>
-        <Typography.Root variant="body-m" weight="medium">
-          {line}
-        </Typography.Root>
-        <Divider.Root align="start">weight medium</Divider.Root>
-      </div>
-      <div className={styles.scaleRow}>
-        <Typography.Root variant="body-m" weight="semibold">
-          {line}
-        </Typography.Root>
-        <Divider.Root align="start">weight semibold</Divider.Root>
-      </div>
-      <div className={styles.scaleRow}>
-        <Typography.Root variant="body-m" tracking="tighter">
-          {line}
-        </Typography.Root>
-        <Divider.Root align="start">tracking tighter</Divider.Root>
-      </div>
-      <div className={styles.scaleRow}>
-        <Typography.Root variant="body-m" tracking="wide">
-          {line}
-        </Typography.Root>
-        <Divider.Root align="start">tracking wide</Divider.Root>
-      </div>
-      <div className={styles.scaleRow}>
-        <Typography.Root variant="body-m" tone="secondary">
-          {line}
-        </Typography.Root>
-        <Divider.Root align="start">tone secondary — вторичный цвет текста</Divider.Root>
-      </div>
-    </div>
+    <>
+      {ROLES.map((variant) => (
+        <div key={variant}>
+          <div>
+            <Typography variant={variant}>Выручка за март</Typography>
+            <Typography as="span" variant="caption" tone="muted">
+              {variant}
+            </Typography>
+          </div>
+        </div>
+      ))}
+      {TONES.map((tone) => (
+        <div key={tone}>
+          <div>
+            <Typography variant="body-m" tone={tone}>
+              Оплата по счёту № 4821 получена
+            </Typography>
+            <Typography as="span" variant="caption" tone="muted">
+              body-m · {tone}
+            </Typography>
+          </div>
+        </div>
+      ))}
+    </>
   );
 }

package/src/components/typography/examples/weights.tsx

@@ -0,0 +1,31 @@
+/** One role with its weight, tracking or italic overridden — `weight`, `tracking`, `italic`. */
+import { Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const LINE = "Отчёт по выручке за первый квартал";
+
+export default function TypographyWeightsExample() {
+  return (
+    <div className={styles.stack}>
+      <Typography variant="body-m" weight="regular">
+        {LINE} · regular
+      </Typography>
+      <Typography variant="body-m" weight="medium">
+        {LINE} · medium
+      </Typography>
+      <Typography variant="body-m" weight="semibold">
+        {LINE} · semibold
+      </Typography>
+      <Typography variant="body-m" tracking="tighter">
+        {LINE} · tracking tighter
+      </Typography>
+      <Typography variant="body-m" tracking="wide">
+        {LINE} · tracking wide
+      </Typography>
+      <Typography variant="body-m" italic>
+        {LINE} · italic
+      </Typography>
+    </div>
+  );
+}

package/src/layout/app-header/COMPONENT.md

@@ -0,0 +1,178 @@
+# AppHeader
+
+**Category:** page
+**Kind:** layout
+
+> The bar at the top of the app's content panel: where you are, global search and a few actions.
+
+## When to use
+- The top row of an app built on [AppShell](../app-shell/COMPONENT.md): the section title or the path, the ⌘K search entry, notifications, the account, one primary action.
+- The phone header: the menu button that opens the off-canvas Sidebar, the title, search as an icon.
+
+## When not to use
+- The page heading, its description and page actions inside main → use [PageContent](../../components/page-content/COMPONENT.md) (`PageContent.Title` is the `<h1>`).
+- Tabs, filters and search for the data on the page → use [PageToolbar](../../components/page-toolbar/COMPONENT.md).
+- App navigation → use [Sidebar](../sidebar/COMPONENT.md) and, on a phone, [BottomNav](../bottom-nav/COMPONENT.md); the header holds at most the menu button.
+- The search dialog itself → use [CommandMenu](../../components/command-menu/COMPONENT.md); `AppHeader.Search` only opens it.
+
+## Import
+```tsx
+import { AppHeader } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+AppHeader.Root               <header>, one sticky row as high as the Sidebar brand row
+├─ AppHeader.Start           leading zone, takes the free width
+│  ├─ AppHeader.MenuButton   opens the off-canvas Sidebar (below 768px by default)
+│  ├─ AppHeader.Separator    short vertical line between groups (a back Button | a Breadcrumb)
+│  └─ AppHeader.Title        name, truncates (or a Breadcrumb instead)
+│     ├─ AppHeader.Icon      decorative glyph on a tile shaped like a soft button m
+│     └─ AppHeader.Description  muted caption under the name
+├─ AppHeader.Search          field-looking button that opens the CommandMenu
+└─ AppHeader.Actions         trailing buttons: notifications, account, primary action
+```
+
+## API
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### AppHeader.Root
+`ref` → `HTMLElement`. The `<header>` bar at the top of the content panel: one row as high as the Sidebar brand row, on the panel surface with no divider, sticky with the top safe-area inset (static below 480px of viewport height); inline padding is the shell gutter, so it lines up with the page in main (16 outside a shell). Its controls are size `m`; icon buttons inside are `soft` (a light fill), not `ghost`. A container (`prime-app-header`): below 36rem the icon tile and the description go and the search folds into an icon.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `labels` | `Partial<AppHeaderLabels>` | — | Built-in strings, see Labels. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children` (`AppHeader.Start`, `AppHeader.Search`, `AppHeader.Actions`), `className` and the other attributes. |
+
+### AppHeader.Start
+`ref` → `HTMLDivElement`. The leading zone that takes the free width: the menu button, a back button, the title or a Breadcrumb.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### AppHeader.Title
+`ref` → `HTMLDivElement`. Where you are: an optional `AppHeader.Icon`, the name (title-s, truncates) and an optional `AppHeader.Description` under it — the anatomy of the Sidebar brand. Not a heading: the page `<h1>` is PageContent.Title.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (the name, `AppHeader.Icon`, `AppHeader.Description` in any order), `className` and the other div attributes. |
+
+### AppHeader.Icon
+`ref` → `HTMLSpanElement`. Decorative glyph before the title (`aria-hidden`) on a tile shaped like the bar's soft buttons: control m square (36), its radius and the subtle fill.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children` (an `Icon`), `className` and the other span attributes. |
+
+### AppHeader.Description
+`ref` → `HTMLSpanElement`. Muted caption under the title (a workspace, a period); hidden on a narrow header.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLSpanElement>` | — | `children`, `className` and the other span attributes. |
+
+### AppHeader.Separator
+`ref` → `HTMLDivElement`. A short vertical `Divider` (20) between groups in a zone — a back button and the path — with 16 of air on each side.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `Omit<DividerProps, "orientation" \| "children">` | — | `className` and the other div attributes. |
+
+### AppHeader.Search
+`ref` → `HTMLButtonElement`. The global search entry: a `<button type="button">` drawn as a field (search icon, placeholder text, key hint) that opens your CommandMenu. Below 36rem of header width it folds into a square button named by its text.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | The placeholder text; also the accessible name. |
+| `shortcut` | `ReactNode` | `"⌘K"` | The key hint at the end (a `Kbd`, hidden from assistive tech); `null` hides it. Bind the key yourself. |
+| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `className` and the other button attributes. |
+
+### AppHeader.Actions
+`ref` → `HTMLDivElement`. The trailing row of buttons: notifications, the account, one primary action. Never wraps.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children`, `className` and the other div attributes. |
+
+### AppHeader.MenuButton
+`ref` → `HTMLButtonElement`. A soft neutral icon `Button` named by `labels.menu` that opens the off-canvas Sidebar; wire `onClick` and `aria-expanded`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `show` | `"narrow" \| "always"` | `"narrow"` | `narrow` — only below 768px, where a Sidebar with `offCanvas="auto"` leaves the layout; `always` — on every width (`offCanvas="always"`). |
+| `…rest` | `ButtonHTMLAttributes<HTMLButtonElement>` | — | `onClick`, `aria-expanded`, `aria-label` (replaces `labels.menu`), `className` and the other button attributes. |
+
+## Variants
+
+### show (MenuButton)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `narrow` | The menu button shows only below 768px | Sidebar with `offCanvas="auto"` | yes |
+| `always` | The menu button on every width | Sidebar with `offCanvas="always"`, or you decide visibility yourself | |
+
+### Structure
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `AppHeader.Title` | Icon, name and a caption under it, like the Sidebar brand | A top-level section | |
+| Breadcrumb in Start | A soft back button, `AppHeader.Separator` and the path | A nested record page | |
+| with `AppHeader.Search` | A field-looking button with a key hint between Start and Actions | The app has a CommandMenu | |
+| with `AppHeader.Actions` | A row of buttons at the end | Notifications, account, one primary action | |
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| narrow header | header width below 36rem (container `prime-app-header`) | the icon tile and the description hide; the search folds into a square button, its text stays as the name |
+| menu button hidden | `show="narrow"` and viewport from 768px | `data-show="narrow"` on MenuButton |
+| short viewport | viewport below 480px high (a phone on its side) | Root stops sticking |
+
+## Layout & spacing
+- Row min height = control m + `--prime-space-2` (44), padding-block `--prime-space-3` (the top grows to the safe-area inset): 68 in all, the height of the Sidebar header, so the brand and the title share one line.
+- Inline padding: the shell gutters (16 → 24 → 32, the same as `AppShell.Main`) in the shell's panel, so the header lines up with the page; `--prime-space-4` elsewhere.
+- Icon buttons are `soft` neutral (MenuButton is), never `ghost`: the search folds into a filled square too, so every button on the bar has a shape.
+- Gaps: `--prime-space-3` between zones, `--prime-space-2` inside Start and Actions; `AppHeader.Separator` adds `--prime-space-2` on each side (16 in all) and is 20 high.
+- `AppHeader.Icon` is a 36 tile with the radius and fill of a soft neutral button m, so it lines up with the buttons on the bar.
+- On the panel surface with no divider or shadow (depth from fill); `z-index: --prime-z-sticky`.
+- Search: up to 288 wide, shrinks first; field tier m and the surface field fill. Controls inside are size `m`.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Moves through the menu button, the path links, the search and the actions in reading order. |
+| `Enter` · `Space` | Presses the focused button: opens the menu, the search or runs the action. |
+
+### ARIA
+- Root is a `<header>`: the banner landmark when it sits at the top level of the page.
+- Search is a button named by its text; the key hint is `aria-hidden`, and the app binds the shortcut.
+- MenuButton is named by `labels.menu`; pass `aria-expanded` (whether the Sidebar is open).
+- Title is not a heading: the page `<h1>` stays with PageContent.Title.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
+|---|---|---|
+| `menu` | `"Открыть меню"` | Name of `AppHeader.MenuButton`. |
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | The top bar of a screen: where you are, global search, notifications and the primary action — `AppHeader.Title`, `AppHeader.Search`, `AppHeader.Actions`. |
+| [breadcrumbs.tsx](examples/breadcrumbs.tsx) | A nested page: a back button, a separator and the path instead of a title, actions on the record at the end — `AppHeader.Separator`, `AppHeader.Actions`. |
+| [in-app-shell.tsx](examples/in-app-shell.tsx) | The header in the app frame: one row with the Sidebar brand across the two planes, sticky over main — `AppShell`, `Sidebar.Brand`. |
+| [narrow.tsx](examples/narrow.tsx) | On a phone: the menu button opens the navigation, the description goes and the search folds into an icon — `AppHeader.MenuButton`, `show`. |
+
+## Mistakes
+- A border or shadow under the header → it sits on the panel surface; the fill is the boundary.
+- `AppHeader.Title` as the page `<h1>` → the heading belongs to PageContent.Title in main.
+- A real text input for global search → `AppHeader.Search` opens the CommandMenu, where typing happens.
+- More than three actions → keep one primary action; the rest go into the page or a Dropdown.
+- A hand-made menu button with a media query → `AppHeader.MenuButton` follows the Sidebar breakpoint.
+- `ghost` icon buttons in the header → `variant="soft" tone="neutral"`: a light fill gives each button a shape on the bar.
+
+## Related
+- **Built from:** [Button](../../components/button/COMPONENT.md), [Kbd](../../components/kbd/COMPONENT.md), [Divider](../../components/divider/COMPONENT.md), Icon (`action.search`, `nav.menu`)
+- **See also:** [AppShell](../app-shell/COMPONENT.md), [Sidebar](../sidebar/COMPONENT.md), [PageContent](../../components/page-content/COMPONENT.md), [PageToolbar](../../components/page-toolbar/COMPONENT.md), [CommandMenu](../../components/command-menu/COMPONENT.md), [Breadcrumb](../../components/breadcrumb/COMPONENT.md)

package/src/layout/app-header/examples/breadcrumbs.tsx

@@ -0,0 +1,36 @@
+/** A nested page: a back button, a separator and the path instead of a title, actions on the record at the end — `AppHeader.Separator`, `AppHeader.Actions`. */
+import { AppHeader, Breadcrumb, Button, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function AppHeaderBreadcrumbsExample() {
+  return (
+    <div className={styles.window}>
+      <AppHeader.Root>
+        <AppHeader.Start>
+          <Button.Root variant="soft" tone="neutral" aria-label="Назад к клиентам">
+            <Button.Icon>
+              <Icon name="nav.chevronLeft" />
+            </Button.Icon>
+          </Button.Root>
+          <AppHeader.Separator />
+          <Breadcrumb.Root>
+            <Breadcrumb.Item href="#crm">CRM</Breadcrumb.Item>
+            <Breadcrumb.Item href="#clients">Клиенты</Breadcrumb.Item>
+            <Breadcrumb.Item current>ООО «Север»</Breadcrumb.Item>
+          </Breadcrumb.Root>
+        </AppHeader.Start>
+        <AppHeader.Actions>
+          <Button.Root variant="soft" tone="neutral">
+            Экспорт
+          </Button.Root>
+          <Button.Root variant="soft" tone="neutral" aria-label="Ещё действия">
+            <Button.Icon>
+              <Icon name="action.more" />
+            </Button.Icon>
+          </Button.Root>
+        </AppHeader.Actions>
+      </AppHeader.Root>
+    </div>
+  );
+}

package/src/layout/app-header/examples/examples.module.css

@@ -0,0 +1,47 @@
+/* Layout of the AppHeader scenarios: an app window and a phone-wide screen. Semantic tokens only. */
+
+/* The top of an app window: the content panel surface with the header on it. */
+.window {
+  box-sizing: border-box;
+  width: 100%;
+  overflow: hidden;
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-bg-surface);
+  box-shadow:
+    0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
+    var(--prime-shadow-raised);
+}
+
+/* narrow.tsx: the same window, phone-wide, so the header folds its search. */
+.phone {
+  width: min(100%, var(--prime-drawer-width-s));
+  margin-inline: auto;
+}
+
+/* in-app-shell.tsx: a whole app window with the rail on the canvas. */
+.stage {
+  box-sizing: border-box;
+  display: flex;
+  width: 100%;
+  height: calc(var(--prime-space-24) * 4);
+  overflow: hidden;
+  border-radius: var(--prime-card-radius);
+  background: var(--prime-color-bg-canvas);
+  box-shadow:
+    0 0 0 var(--prime-border-width) var(--prime-color-border-subtle),
+    var(--prime-shadow-raised);
+}
+
+/* The shell fills the window frame instead of the viewport. */
+.shell {
+  height: 100%;
+}
+
+/* The product mark inside `Sidebar.BrandLogo`: an accent tile with a glyph. */
+.logo {
+  display: grid;
+  place-items: center;
+  border-radius: var(--prime-radius-m);
+  background: var(--prime-color-accent-default);
+  color: var(--prime-color-accent-fg);
+}

package/src/layout/app-header/examples/in-app-shell.tsx

@@ -0,0 +1,70 @@
+/** The header in the app frame: one row with the Sidebar brand across the two planes, sticky over main — `AppShell`, `Sidebar.Brand`. */
+import { AppHeader, AppShell, Icon, PageContent, Sidebar, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const ORDERS = [
+  "№ 4821 · ООО «Север» · 84 000 ₽",
+  "№ 4820 · ИП Котов · 12 500 ₽",
+  "№ 4819 · ООО «Вектор» · 230 000 ₽",
+  "№ 4818 · АО «Меридиан» · 47 900 ₽",
+  "№ 4817 · ООО «Полюс» · 9 800 ₽",
+  "№ 4816 · ИП Белова · 156 000 ₽",
+];
+
+export default function AppHeaderInAppShellExample() {
+  return (
+    <div className={styles.stage}>
+      <AppShell.Root fillViewport className={styles.shell}>
+        <AppShell.Nav>
+          <Sidebar.Root offCanvas="never">
+            <Sidebar.Header>
+              <Sidebar.Brand href="#home" description="Отдел продаж">
+                <Sidebar.BrandLogo>
+                  <span className={styles.logo}>
+                    <Icon name="nav.layoutGrid" />
+                  </span>
+                </Sidebar.BrandLogo>
+                Acme CRM
+              </Sidebar.Brand>
+            </Sidebar.Header>
+            <Sidebar.Content>
+              <Sidebar.Item>
+                <Sidebar.ItemIcon>
+                  <Icon name="nav.home" />
+                </Sidebar.ItemIcon>
+                Обзор
+              </Sidebar.Item>
+              <Sidebar.Item current>
+                <Sidebar.ItemIcon>
+                  <Icon name="object.package" />
+                </Sidebar.ItemIcon>
+                Заказы
+              </Sidebar.Item>
+            </Sidebar.Content>
+          </Sidebar.Root>
+        </AppShell.Nav>
+        <AppHeader.Root>
+          <AppHeader.Start>
+            <AppHeader.Title>
+              Заказы
+              <AppHeader.Description>128 в работе</AppHeader.Description>
+            </AppHeader.Title>
+          </AppHeader.Start>
+          <AppHeader.Search>Поиск</AppHeader.Search>
+        </AppHeader.Root>
+        <AppShell.Main>
+          <PageContent.Section>
+            <PageContent.Body>
+              {ORDERS.map((order) => (
+                <Typography key={order} variant="body-m">
+                  {order}
+                </Typography>
+              ))}
+            </PageContent.Body>
+          </PageContent.Section>
+        </AppShell.Main>
+      </AppShell.Root>
+    </div>
+  );
+}

package/src/layout/app-header/examples/narrow.tsx

@@ -0,0 +1,29 @@
+/** On a phone: the menu button opens the navigation, the description goes and the search folds into an icon — `AppHeader.MenuButton`, `show`. */
+import { AppHeader, Button, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function AppHeaderNarrowExample() {
+  return (
+    <div className={`${styles.window} ${styles.phone}`}>
+      <AppHeader.Root>
+        <AppHeader.Start>
+          {/* `always`: this frame is phone-wide on any screen; in an app keep the default `narrow`. */}
+          <AppHeader.MenuButton show="always" aria-expanded={false} />
+          <AppHeader.Title>
+            Заказы
+            <AppHeader.Description>128 в работе</AppHeader.Description>
+          </AppHeader.Title>
+        </AppHeader.Start>
+        <AppHeader.Search>Поиск заказов</AppHeader.Search>
+        <AppHeader.Actions>
+          <Button.Root variant="soft" tone="neutral" aria-label="Новый заказ">
+            <Button.Icon>
+              <Icon name="action.add" />
+            </Button.Icon>
+          </Button.Root>
+        </AppHeader.Actions>
+      </AppHeader.Root>
+    </div>
+  );
+}

package/src/layout/app-header/examples/overview.tsx

@@ -0,0 +1,36 @@
+/** The top bar of a screen: where you are, global search, notifications and the primary action — `AppHeader.Title`, `AppHeader.Search`, `AppHeader.Actions`. */
+import { AppHeader, Button, Icon } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function AppHeaderOverviewExample() {
+  return (
+    <div className={styles.window}>
+      <AppHeader.Root>
+        <AppHeader.Start>
+          <AppHeader.Title>
+            <AppHeader.Icon>
+              <Icon name="nav.dashboard" />
+            </AppHeader.Icon>
+            Обзор
+            <AppHeader.Description>Отдел продаж · октябрь</AppHeader.Description>
+          </AppHeader.Title>
+        </AppHeader.Start>
+        <AppHeader.Search>Поиск заказов и клиентов</AppHeader.Search>
+        <AppHeader.Actions>
+          <Button.Root variant="soft" tone="neutral" aria-label="Уведомления">
+            <Button.Icon>
+              <Icon name="object.bell" />
+            </Button.Icon>
+          </Button.Root>
+          <Button.Root>
+            <Button.Icon>
+              <Icon name="action.add" />
+            </Button.Icon>
+            Новый заказ
+          </Button.Root>
+        </AppHeader.Actions>
+      </AppHeader.Root>
+    </div>
+  );
+}