prime-ui-kit 0.9.0 → 0.9.1

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-shell/COMPONENT.md

@@ -1,6 +1,7 @@
 # AppShell
 
 **Category:** layout
+**Kind:** layout
 
 > The app frame: a navigation rail on the canvas and a content panel on the surface.
 
@@ -22,55 +23,58 @@ import { AppShell } from "prime-ui-kit";
 ## Anatomy
 ```
 AppShell.Root                grid: nav column | content panel (bg-surface)
-├── AppShell.Nav             navigation column on the canvas (usually Sidebar.Root)
-├── AppShell.Header          sticky top bar of the panel
-└── AppShell.Main            <main>, scrolls, carries the gutters
+├─ AppShell.Nav              navigation column on the canvas (usually Sidebar.Root)
+├─ AppShell.Header           sticky top bar of the panel
+└─ AppShell.Main             <main>, scrolls, carries the gutters
 AppShell.Template            Root + Nav + Header + Main in one component
 ```
 Every child of Root that is not `AppShell.Nav` is placed into the content panel.
 
 ## API
 
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
 ### AppShell.Root
-`forwardRef` to `<div>`.
+`ref` → `HTMLDivElement`. Grid of the nav column (canvas) and the content panel (surface); every child that is not `AppShell.Nav` goes into the panel.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `fillViewport` | `boolean` | `false` | Shell is exactly the viewport height and only `AppShell.Main` scrolls; otherwise the document scrolls and the nav is sticky. |
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | `AppShell.Nav`, `AppShell.Header`, `AppShell.Main`. |
-
-+ native `<div>` props.
+| `fillViewport` | `boolean` | `false` | The shell is exactly the viewport high and only `AppShell.Main` scrolls; otherwise the document scrolls and the nav is sticky. |
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (Nav, Header, Main), `className` and the other div attributes. |
 
 ### AppShell.Nav
-No ref. A `<div>` grid slot (not a landmark; Sidebar renders the `<nav>`). + native `<div>` props.
+`ref` → `HTMLDivElement`. The navigation column slot (not a landmark: Sidebar renders the `<nav>`).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLDivElement>` | — | `children` (usually `Sidebar.Root`), `className` and the other div attributes. |
 
 ### AppShell.Header
-`forwardRef` to `<header>`. A flex row (gap 12) for breadcrumbs, search and actions. + native `HTMLAttributes<HTMLElement>`.
+`ref` → `HTMLElement`. Sticky `<header>` row of the panel for breadcrumbs, search and actions.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes. |
 
 ### AppShell.Main
-`forwardRef` to `<main>` (a vertical ScrollContainer with `overscroll-behavior: contain`).
+`ref` → `HTMLElement`. The `<main>` with the canonical gutters: a vertical `ScrollContainer`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `contentWidth` | `"contained" \| "full"` | `"full"` | `full`: whole panel with gutters; `contained`: centred column up to `--prime-layout-content-max-width`. |
-| `className` | `string` | — | Extra class. |
-| `children` | `ReactNode` | — | Page content. |
-
-+ native `HTMLAttributes<HTMLElement>`.
+| `contentWidth` | `"contained" \| "full"` | `"full"` | `full` — the whole panel with gutters; `contained` — a centred column up to `--prime-layout-content-max-width`. |
+| `…rest` | `HTMLAttributes<HTMLElement>` | — | `children`, `className` and the other attributes. |
 
 ### AppShell.Template
-`forwardRef` to the `<main>` element. Renders Root, Nav (when `nav` is set), Header (when `header` is set) and Main. Inside a react-router tree it scrolls main to the top on every route change.
+`ref` → the `<main>`. Root + Nav + Header + Main in one; main scrolls to the top when `scrollResetKey` changes.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `nav` | `ReactNode` | — | Navigation column content; without it the panel takes the full width. |
 | `header` | `ReactNode` | — | Header content; no header row when omitted. |
 | `mainProps` | `Omit<AppShellMainProps, "children">` | — | Props for Main (e.g. `contentWidth`). |
-| `fillViewport` | `boolean` | `false` | Passed to Root. |
+| `scrollResetKey` | `unknown` | — | Main scrolls back to the top whenever this value changes; pass the router pathname. |
 | `children` | `ReactNode` | — | Page content inside Main. |
-
-+ other Root props (native `<div>` props on Root).
+| `…rest` | `Omit<AppShellRootProps, "children">` | — | Root props: `fillViewport`, `className` and the div attributes. |
 
 ## Variants
 
@@ -93,10 +97,13 @@ No ref. A `<div>` grid slot (not a landmark; Sidebar renders the `<nav>`). + nat
 | without Nav | Panel takes the full width | Single-page tools, auth screens | |
 | with `AppShell.Header` | Sticky bar at the top of the panel | Breadcrumbs, page actions, mobile menu button | |
 
-**Combinations** — `AppShell.Template` with `nav={<Sidebar.Root …/>}` and `PageContent` inside is the standard app. `contentWidth="contained"` + `PageContent.Root maxWidth="readable"` for docs/articles.
+`AppShell.Template` with `nav={<Sidebar.Root …/>}` and `PageContent` inside is the standard app; `contentWidth="contained"` + `PageContent.Root maxWidth="readable"` for docs and articles.
 
 ## States
-Static layout. DOM: `data-fill-viewport="true"` on Root (only when set), `data-content-width` on Main.
+| State | Driven by | DOM |
+|---|---|---|
+| fixed frame | `fillViewport` | `data-fill-viewport="true"` on Root |
+| content width | `contentWidth` | `data-content-width` on Main |
 
 ## Layout & spacing
 - Two full-height planes edge to edge: no inset, radius, shadow or border — the boundary is the fill change (canvas → surface).
@@ -105,46 +112,33 @@ Static layout. DOM: `data-fill-viewport="true"` on Root (only when set), `data-c
 - The panel is a surface context: fields use the surface field fill, Cards inside become sunken tiles without shadow.
 
 ## Accessibility
+
+### Keyboard
+No keyboard interaction.
+
+### ARIA
 - Main is the `<main>` landmark and Header is `<header>`; the navigation landmark comes from Sidebar (`<nav>`).
 - Give the page one `<h1>` (PageContent.Title).
-- No keyboard behaviour, no `labels`.
 
-## Examples
-| File | Scenario | When to use this pattern |
-|---|---|---|
-| [with-sidebar.tsx](examples/with-sidebar.tsx) | Sidebar in Nav, breadcrumbs in Header, page with action and metric card in Main, `fillViewport` | Root layout of an app |
-| [contained.tsx](examples/contained.tsx) | No Nav, `Main contentWidth="contained"` with a readable page | Docs, articles, long-read pages |
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
 
-```tsx
-import { AppShell, PageContent, Sidebar } from "prime-ui-kit";
-
-export function Example() {
-  return (
-    <AppShell.Template
-      fillViewport
-      nav={
-        <Sidebar.Root>
-          <Sidebar.Content>
-            <Sidebar.Item active>Обзор</Sidebar.Item>
-          </Sidebar.Content>
-        </Sidebar.Root>
-      }
-    >
-      <PageContent.Section>
-        <PageContent.Header>
-          <PageContent.Title>Обзор</PageContent.Title>
-        </PageContent.Header>
-      </PageContent.Section>
-    </AppShell.Template>
-  );
-}
-```
+No `labels`.
+
+## Examples
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | The app frame: Sidebar in the nav column, breadcrumbs in the sticky header, the page in main; only main scrolls — `fillViewport`. |
+| [contained.tsx](examples/contained.tsx) | A shell without navigation whose main column is centred and capped for long reads — `contentWidth`. |
+| [template.tsx](examples/template.tsx) | Root, nav, header and main in one component; main scrolls back to the top whenever the page changes — `AppShell.Template` with `scrollResetKey`. |
 
 ## Mistakes
 - Adding padding around the page content → Main already has the gutters.
 - Wrapping Main content in another scroll container → Main scrolls (with `fillViewport`) or the document does.
 - A border or shadow between nav and panel → the fill change is the boundary.
 - Putting the Sidebar directly in Root without `AppShell.Nav` → it lands inside the content panel.
+- `AppShell.Template` in a router app without `scrollResetKey` → a new page opens at the old scroll position; pass the pathname.
 
 ## Related
-[Sidebar](../sidebar/COMPONENT.md) · [PageContent](../../components/page-content/COMPONENT.md) · [ScrollContainer](../../components/scroll-container/COMPONENT.md) · [Breadcrumb](../../components/breadcrumb/COMPONENT.md)
+- **Built from:** [ScrollContainer](../../components/scroll-container/COMPONENT.md)
+- **See also:** [Sidebar](../sidebar/COMPONENT.md), [PageContent](../../components/page-content/COMPONENT.md), [Breadcrumb](../../components/breadcrumb/COMPONENT.md)

package/src/layout/app-shell/examples/contained.tsx

@@ -1,4 +1,4 @@
-/** A shell without navigation and `AppShell.Main contentWidth="contained"`: the page column is centred and capped at the content max width. Use for docs, articles and other long-read pages. */
+/** A shell without navigation whose main column is centred and capped for long reads — `contentWidth`. */
 import { AppShell, PageContent, Typography } from "prime-ui-kit";
 
 import styles from "./examples.module.css";
@@ -11,16 +11,16 @@ export default function AppShellContainedExample() {
           <PageContent.Root maxWidth="readable">
             <PageContent.Header>
               {/* In a real app this is PageContent.Title (the page h1). */}
-              <Typography.Root as="h2" variant="heading-m">
+              <Typography as="h2" variant="heading-m">
                 Как подключить оплату
-              </Typography.Root>
+              </Typography>
               <PageContent.Description>Обновлено 1 октября 2026 года.</PageContent.Description>
             </PageContent.Header>
             <PageContent.Body>
-              <Typography.Root as="p" variant="body-l">
+              <Typography as="p" variant="body-l">
                 Откройте раздел «Настройки», выберите «Оплата» и укажите реквизиты. После проверки
                 банк пришлёт подтверждение, и приём платежей включится автоматически.
-              </Typography.Root>
+              </Typography>
             </PageContent.Body>
           </PageContent.Root>
         </AppShell.Main>

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

@@ -14,6 +14,15 @@
     var(--prime-shadow-raised);
 }
 
+/* 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);
+}
+
 /* The shell fills the window frame instead of the viewport. */
 .shell {
   height: 100%;

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

@@ -0,0 +1,72 @@
+/** The app frame: Sidebar in the nav column, breadcrumbs in the sticky header, the page in main; only main scrolls — `fillViewport`. */
+import { AppShell, Breadcrumb, Button, Icon, PageContent, Sidebar, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function AppShellOverviewExample() {
+  return (
+    <div className={styles.stage}>
+      <AppShell.Root fillViewport className={styles.shell}>
+        <AppShell.Nav>
+          {/* A small app window: the icon rail fits every frame width; the toggle widens it. */}
+          <Sidebar.Root offCanvas="never" defaultMode="compact">
+            <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.Toggle variant="header" />
+            </Sidebar.Header>
+            <Sidebar.Content>
+              <Sidebar.Item current>
+                <Sidebar.ItemIcon>
+                  <Icon name="nav.home" />
+                </Sidebar.ItemIcon>
+                Обзор
+              </Sidebar.Item>
+              <Sidebar.Item>
+                <Sidebar.ItemIcon>
+                  <Icon name="nav.layoutGrid" />
+                </Sidebar.ItemIcon>
+                Отчёты
+              </Sidebar.Item>
+            </Sidebar.Content>
+          </Sidebar.Root>
+        </AppShell.Nav>
+        <AppShell.Header>
+          <Breadcrumb.Root>
+            <Breadcrumb.Item href="#crm">CRM</Breadcrumb.Item>
+            <Breadcrumb.Item current>Обзор</Breadcrumb.Item>
+          </Breadcrumb.Root>
+        </AppShell.Header>
+        <AppShell.Main>
+          <PageContent.Section>
+            <PageContent.Header>
+              {/* In a real app this is PageContent.Title (the page h1). */}
+              <Typography as="h2" variant="heading-m">
+                Обзор
+              </Typography>
+              <PageContent.Actions>
+                <Button.Root>
+                  <Button.Icon>
+                    <Icon name="action.add" />
+                  </Button.Icon>
+                  Новая сделка
+                </Button.Root>
+              </PageContent.Actions>
+            </PageContent.Header>
+            <PageContent.Body>
+              <Typography variant="body-m" tone="secondary">
+                Выручка за месяц — 4,8 млн ₽, 37 сделок в работе.
+              </Typography>
+            </PageContent.Body>
+          </PageContent.Section>
+        </AppShell.Main>
+      </AppShell.Root>
+    </div>
+  );
+}

package/src/layout/app-shell/examples/template.tsx

@@ -0,0 +1,54 @@
+/** Root, nav, header and main in one component; main scrolls back to the top whenever the page changes — `AppShell.Template` with `scrollResetKey`. */
+import { AppShell, Icon, PageContent, Sidebar, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const PAGES = [
+  { id: "mailings", label: "Рассылки", icon: "field.email", text: "3 активные кампании." },
+  { id: "calendar", label: "Календарь", icon: "field.calendar", text: "5 событий на неделе." },
+] as const;
+
+export default function AppShellTemplateExample() {
+  // In a router app pass the pathname: `scrollResetKey={useLocation().pathname}`.
+  const [pageId, setPageId] = React.useState<(typeof PAGES)[number]["id"]>("mailings");
+  const page = PAGES.find((item) => item.id === pageId) ?? PAGES[0];
+
+  return (
+    <div className={styles.stage}>
+      <AppShell.Template
+        fillViewport
+        className={styles.shell}
+        scrollResetKey={pageId}
+        nav={
+          <Sidebar.Root offCanvas="never">
+            <Sidebar.Content>
+              {PAGES.map((item) => (
+                <Sidebar.Item
+                  key={item.id}
+                  current={item.id === pageId}
+                  onClick={() => setPageId(item.id)}
+                >
+                  <Sidebar.ItemIcon>
+                    <Icon name={item.icon} />
+                  </Sidebar.ItemIcon>
+                  {item.label}
+                </Sidebar.Item>
+              ))}
+            </Sidebar.Content>
+          </Sidebar.Root>
+        }
+      >
+        <PageContent.Section>
+          <PageContent.Header>
+            {/* In a real app this is PageContent.Title (the page h1). */}
+            <Typography as="h2" variant="heading-m">
+              {page.label}
+            </Typography>
+            <PageContent.Description>{page.text}</PageContent.Description>
+          </PageContent.Header>
+        </PageContent.Section>
+      </AppShell.Template>
+    </div>
+  );
+}