prime-ui-kit 0.4.1 → 0.5.1

package/dist/layout/app-shell/AppShell.d.ts

@@ -16,6 +16,10 @@ export type AppShellMainProps = {
     className?: string;
     children?: React.ReactNode;
 } & React.HTMLAttributes<HTMLElement>;
+export type AppShellMainInsetProps = {
+    className?: string;
+    children?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
 export type AppShellTemplateProps = {
     fillViewport?: boolean;
     className?: string;
@@ -36,6 +40,10 @@ export declare const AppShell: {
         className?: string;
         children?: React.ReactNode;
     } & React.HTMLAttributes<HTMLElement> & React.RefAttributes<HTMLElement>>;
+    MainInset: React.ForwardRefExoticComponent<{
+        className?: string;
+        children?: React.ReactNode;
+    } & React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
     Template: React.ForwardRefExoticComponent<{
         fillViewport?: boolean;
         className?: string;

package/dist/layout/app-shell/AppShell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AppShell.d.ts","sourceRoot":"","sources":["../../../../src/layout/app-shell/AppShell.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAQ/B,MAAM,MAAM,iBAAiB,GAAG;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,GAAG,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;AAmBzC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,GAAG,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;AAEzC,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,gBAAgB,2CAMtE;kBANQ,WAAW;;;AASpB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,GAAG,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;AAsBtC,MAAM,MAAM,qBAAqB,GAAG;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC;IACrB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,QAAQ,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC;IAC9C,SAAS,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,UAAU,CAAC,CAAC;CACjD,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC,CAAC;AAwBnE,eAAO,MAAM,QAAQ;;uBA7FJ,OAAO;oBACV,MAAM;mBACP,KAAK,CAAC,SAAS;;;;oBAmCd,MAAM;mBACP,KAAK,CAAC,SAAS;;;uBAwBX,OAAO;oBACV,MAAM;QAClB,2CAA2C;aACtC,KAAK,CAAC,SAAS;mBACT,KAAK,CAAC,SAAS;mBACf,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC;oBACjC,IAAI,CAAC,iBAAiB,EAAE,UAAU,CAAC;;CA8BhD,CAAC"}
+{"version":3,"file":"AppShell.d.ts","sourceRoot":"","sources":["../../../../src/layout/app-shell/AppShell.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAW/B,MAAM,MAAM,iBAAiB,GAAG;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,GAAG,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;AAmBzC,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,GAAG,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;AAEzC,iBAAS,WAAW,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,gBAAgB,2CAMtE;kBANQ,WAAW;;;AASpB,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,GAAG,KAAK,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;AAsBtC,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B,GAAG,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;AA+BzC,MAAM,MAAM,qBAAqB,GAAG;IAClC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC;IACrB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,QAAQ,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC;IAC9C,SAAS,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,UAAU,CAAC,CAAC;CACjD,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC,CAAC;AA6BnE,eAAO,MAAM,QAAQ;;uBApIJ,OAAO;oBACV,MAAM;mBACP,KAAK,CAAC,SAAS;;;;oBAmCd,MAAM;mBACP,KAAK,CAAC,SAAS;;;oBAwBd,MAAM;mBACP,KAAK,CAAC,SAAS;;;uBAiCX,OAAO;oBACV,MAAM;QAClB,2CAA2C;aACtC,KAAK,CAAC,SAAS;mBACT,KAAK,CAAC,SAAS;mBACf,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC;oBACjC,IAAI,CAAC,iBAAiB,EAAE,UAAU,CAAC;;CAoChD,CAAC"}

package/dist/layout/index.d.ts

@@ -1,4 +1,4 @@
-export type { AppShellMainProps, AppShellNavProps, AppShellRootProps, AppShellTemplateProps, } from "./app-shell/AppShell";
+export type { AppShellMainInsetProps, AppShellMainProps, AppShellNavProps, AppShellRootProps, AppShellTemplateProps, } from "./app-shell/AppShell";
 export { AppShell } from "./app-shell/AppShell";
 export type { SidebarContentProps, SidebarFooterProps, SidebarGroupLabelProps, SidebarGroupProps, SidebarHeaderMainProps, SidebarHeaderProps, SidebarHeaderRowProps, SidebarIdentityButtonProps, SidebarMenuActionProps, SidebarMenuButtonProps, SidebarMenuIconProps, SidebarMenuItemProps, SidebarMenuLabelProps, SidebarMenuLinkProps, SidebarMenuProps, SidebarMenuRouterLinkProps, SidebarMenuTrailingProps, SidebarNavCategoryCountProps, SidebarNavCategoryLabelProps, SidebarNavCategoryPanelProps, SidebarNavCategoryProps, SidebarNavCategoryTriggerProps, SidebarNavDocTreeProps, SidebarNavPanelBodyProps, SidebarNavPanelHeadingProps, SidebarNavPanelProps, SidebarResponsive, SidebarRootProps, SidebarSize, SidebarTextProps, SidebarToggleButtonProps, } from "./sidebar/Sidebar";
 export { Sidebar, useSidebarContext } from "./sidebar/Sidebar";

package/dist/layout/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/layout/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,0BAA0B,EAC1B,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,0BAA0B,EAC1B,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,EAC5B,4BAA4B,EAC5B,uBAAuB,EACvB,8BAA8B,EAC9B,sBAAsB,EACtB,wBAAwB,EACxB,2BAA2B,EAC3B,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/layout/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,0BAA0B,EAC1B,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EAChB,0BAA0B,EAC1B,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,EAC5B,4BAA4B,EAC5B,uBAAuB,EACvB,8BAA8B,EAC9B,sBAAsB,EACtB,wBAAwB,EACxB,2BAA2B,EAC3B,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,yBAAyB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prime-ui-kit",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "React 19 UI kit: CSS Modules, semantic design tokens (--prime-sys-*), composable components — forms, modals, selects, tables, navigation, overlays. TypeScript, ESM, a11y-oriented.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/components/page-content/COMPONENT.md

@@ -2,27 +2,27 @@
 
 ## About
 
-Semantic **page column** primitives: **`PageContent.Section`** (a **`<section>`** page region without its own outer padding), **`PageContent.Root`** (full padded column with optional **`maxWidth`**), **`PageContent.Title`** → **`<h1>`**, **`PageContent.Description`** with **`measure`**, and **`PageContent.Body`**. Typography uses kit tokens.
+Семантические примитивы **контентной колонки**: **`PageContent.Section`** (регион страницы **`<section>`** без собственных внешних полей), **`PageContent.Root`** (обёртка страницы с опциональным **`maxWidth`**, **без** дублирующих полей к краю колонки), **`PageContent.Title`** → **`<h1>`**, **`PageContent.Description`** с **`measure`**, **`PageContent.Body`**. Типографика — токены кита.
 
-- **Use `PageContent.Section`** when a parent already applies outer padding (e.g. an inset wrapper inside **`AppShell.Main`**, or the same pattern as playground routes) — without wrapping in **`Root`**.
-- **Use `PageContent.Root`** when you need that outer padding and optional **`maxWidth`** (`full` | `readable` | `wide`; default **`full`**).
-- **Use `Description` `measure="full"`** when the parent column is already inset; default **`measure="readable"`** keeps the lead ~65ch for reading.
+- **В приложении с `AppShell.Template`** внешние поля колонки задаёт **`AppShell.MainInset`** (встроен в шаблон). Тогда для маршрута чаще берут **`PageContent.Section`** + **`Header`** / **`Body`**, либо **`PageContent.Root`** только ради **`maxWidth`**, без ожидания «второго» слоя полей.
+- **`PageContent.Root`** — когда нужен **`maxWidth`** (`full` | `readable` | `wide`; по умолчанию **`full`**) и структура шапки/тела; краевые поля **не** входят в корень — их даёт **`MainInset`**.
+- **`Description`** с **`measure="full"`**, если ширину уже ограничивает родитель; по умолчанию **`measure="readable"`** — узкая мера лида ~65ch.
 
 ## Composition
 
-- **`PageContent.Root`** — outer wrapper: padding + optional max-width (`data-max-width`).
-- **`PageContent.Section`** — **`<section>`** without extra outer padding; pair with **`aria-labelledby`** pointing at **`PageContent.Title`** `id`.
-- **`PageContent.Header`** — stacks title + description with spacing.
-- **`PageContent.Title`** — **`<h1>`** (one per route).
-- **`PageContent.Description`** — **`<p>`** lead; **`measure`** controls max width.
-- **`PageContent.Body`** — main blocks below the header (demos, forms, tables).
+- **`PageContent.Root`** — внешняя обёртка: **`maxWidth`** через `data-max-width` (кроме `full`), **padding по краям колонки — 0** (поля у **`AppShell.MainInset`**).
+- **`PageContent.Section`** — **`<section>`**; сочетайте с **`aria-labelledby`** на заголовок **`PageContent.Title`**.
+- **`PageContent.Header`** — заголовок + описание с отступами.
+- **`PageContent.Title`** — **`<h1>`** (один на вью).
+- **`PageContent.Description`** — лид **`<p>`**; **`measure`** — ширина текста.
+- **`PageContent.Body`** — блоки под шапкой.
 
-### Canonical example (inside an inset content column)
+### Canonical example (маршрут внутри `AppShell.Template`)
 
 ```tsx
 import { PageContent } from "prime-ui-kit";
 
-export function DocRouteBody() {
+export function SettingsPage() {
   return (
     <PageContent.Section aria-labelledby="page-heading">
       <PageContent.Header>
@@ -31,18 +31,18 @@ export function DocRouteBody() {
           Manage your workspace profile and notifications.
         </PageContent.Description>
       </PageContent.Header>
-      <PageContent.Body>{/* page blocks */}</PageContent.Body>
+      <PageContent.Body>{/* блоки страницы */}</PageContent.Body>
     </PageContent.Section>
   );
 }
 ```
 
-### Canonical example (standalone column)
+### Canonical example (узкая колонка + `maxWidth`)
 
 ```tsx
 import { PageContent } from "prime-ui-kit";
 
-export function StandalonePage() {
+export function AccountPage() {
   return (
     <PageContent.Root maxWidth="readable">
       <PageContent.Header>
@@ -57,13 +57,13 @@ export function StandalonePage() {
 
 ### Playground
 
-Live demo and API tables: **`playground/sections/PageContentSection.tsx`** — **`Section`** → **`Header`** (**`Title`**, **`Description measure="full"`**) → **`Body`**. There is no **`playground/snippets/page-content/`** tree; the section is the single demo surface.
+Живые примеры и таблицы API: **`playground/sections/PageContentSection.tsx`**.
 
 ## Rules
 
-- Prefer **one** `h1` per view — **`PageContent.Title`**.
-- Do not nest **`PageContent.Root`** inside a region that already applies the same outer padding unless you intentionally want double padding; use **`Section`** instead.
-- **`Description`** defaults to a readable measure; use **`measure="full"`** when the layout already constrains width.
+- На вью — **один** `h1` через **`PageContent.Title`**.
+- **Не** вкладывайте **`PageContent.Root`** в область, где уже есть тот же слой полей, что у **`AppShell.MainInset`** — у корня **нет** своих краевых полей; при необходимости используйте **`Section`**.
+- **`Description`**: по умолчанию узкая мера; **`measure="full"`**, когда колонка уже ограничена снаружи.
 
 ## API
 
@@ -71,53 +71,53 @@ Live demo and API tables: **`playground/sections/PageContentSection.tsx`** — *
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| maxWidth | `full` \| `readable` \| `wide` | `full` | No | Limits the content column; drives `data-max-width` when not `full`. |
-| className | `string` | — | No | Class on the root wrapper. |
-| children | `React.ReactNode` | — | No | Header, body, nested sections. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native `div` attributes, including `ref` (`forwardRef`). |
+| maxWidth | `full` \| `readable` \| `wide` | `full` | No | Ограничение ширины контентной колонки; `data-max-width`, кроме `full`. |
+| className | `string` | — | No | Класс на корневой обёртке. |
+| children | `React.ReactNode` | — | No | Шапка, тело, секции. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
 
 ### PageContent.Section
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| className | `string` | — | No | Class on **`<section>`** (page region without outer padding—use when an inset wrapper or **`PageContent.Root`** already provides margins). |
-| children | `React.ReactNode` | — | No | Usually **`Header`** + **`Body`** (playground routes follow this). |
-| …rest | `React.HTMLAttributes<HTMLElement>` | — | No | Native **`<section>`** attributes, including `ref` (`forwardRef`). |
+| className | `string` | — | No | Класс на **`<section>`**. |
+| children | `React.ReactNode` | — | No | Обычно **`Header`** + **`Body`**. |
+| …rest | `React.HTMLAttributes<HTMLElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
 
 ### PageContent.Header
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| className | `string` | — | No | Class on the header block (title + description). |
-| children | `React.ReactNode` | — | No | Usually **`PageContent.Title`** and **`PageContent.Description`** (`measure` as needed). |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native `div` attributes. |
+| className | `string` | — | No | Класс на блоке шапки. |
+| children | `React.ReactNode` | — | No | **`Title`**, **`Description`**. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Атрибуты `div`. |
 
 ### PageContent.Title
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| className | `string` | — | No | Class on **`<h1>`**. |
-| children | `React.ReactNode` | — | No | Page heading. |
-| …rest | `React.HTMLAttributes<HTMLHeadingElement>` | — | No | Native **`h1`** attributes, including `ref` (`forwardRef`). |
+| className | `string` | — | No | Класс на **`<h1>`**. |
+| children | `React.ReactNode` | — | No | Заголовок страницы. |
+| …rest | `React.HTMLAttributes<HTMLHeadingElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
 
 ### PageContent.Description
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| measure | `readable` \| `full` | `readable` | No | `readable` — ~65ch; `full` — parent width (e.g. when the content column is already inset). |
-| className | `string` | — | No | Class on the lead **`<p>`**. |
-| children | `React.ReactNode` | — | No | Intro text under the title. |
-| …rest | `React.HTMLAttributes<HTMLParagraphElement>` | — | No | Native **`p`** attributes, including `ref` (`forwardRef`). |
+| measure | `readable` \| `full` | `readable` | No | `readable` — ~65ch; `full` — ширина родителя. |
+| className | `string` | — | No | Класс на **`<p>`**. |
+| children | `React.ReactNode` | — | No | Вводный текст. |
+| …rest | `React.HTMLAttributes<HTMLParagraphElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
 
 ### PageContent.Body
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| className | `string` | — | No | Class on the main content wrapper below the header. |
-| children | `React.ReactNode` | — | No | Page content under the header. |
-| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Native `div` attributes. |
+| className | `string` | — | No | Класс на обёртке контента под шапкой. |
+| children | `React.ReactNode` | — | No | Основное содержимое. |
+| …rest | `React.HTMLAttributes<HTMLDivElement>` | — | No | Атрибуты `div`. |
 
 ## Related
 
-- [Typography](../typography/COMPONENT.md) — inline roles elsewhere on the page.
-- [AppShell](../../layout/app-shell/AppShell.tsx) — grid shell (`nav` + **`main`**); page padding is app-level (e.g. **`PageContent.Root`** or a wrapper inside **`main`**).
+- [Typography](../typography/COMPONENT.md) — роли текста на странице.
+- [AppShell](../../layout/app-shell/COMPONENT.md) — сетка и **`MainInset`**.

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

@@ -0,0 +1,90 @@
+# AppShell
+
+## About
+
+Каркас приложения: **сетка** `nav` + **`main`** (прокручиваемая колонка). **`AppShell.Template`** — каноничный способ собрать оболочку: он задаёт **`data-layout-template="app"`** (зазор у колонки nav при открытом **Sidebar** с `sidebarSlot="page-nav"`), **всегда** оборачивает дочерние маршруты в **`AppShell.MainInset`** с едиными полями контентной колонки (**`--prime-sys-spacing-x6`** по вертикали и горизонтали — тот же формат, что в playground до выделения в кит), и при монтировании **внутри React Router** сбрасывает прокрутку **`main`** на смене пути.
+
+**Не** добавляйте второй слой с теми же полями вокруг страницы: используйте **`PageContent.Section`** или **`PageContent.Root`** (без дублирующих внешних отступов у корня — их даёт **`MainInset`**).
+
+## Composition
+
+- **`AppShell.Root`** — корневая сетка; опционально **`fillViewport`** (типично для фиксированной высоты вьюпорта и прокрутки только в **`main`**).
+- **`AppShell.Nav`** — слот навигации (**`data-layout-region="nav"`**).
+- **`AppShell.Main`** — основная колонка (**`<main>`**, **`ScrollContainer`**, **`data-layout-region="main"`**).
+- **`AppShell.MainInset`** — **единый** внутренний отступ контентной колонки; в **`Template`** уже вложен в **`Main`**. Используйте отдельно только в особых маршрутах без **`Template`** (например **`AppShell.Root`** + один **`Main`** + **`MainInset`** без боковой колонки — корень сетки растянет **`main`** на всю ширину).
+- **`AppShell.Template`** — **`Root`** + **`Nav`** + **`Main`**, внутри **`Main`** — **`MainInset`** (дети шаблона) + сброс прокрутки при смене **`pathname`** (только если предок — React Router).
+
+### Canonical example (приложение с сайдбаром)
+
+```tsx
+import { AppShell, Sidebar } from "prime-ui-kit";
+import { Outlet } from "react-router-dom";
+
+export function AppLayout() {
+  return (
+    <AppShell.Template fillViewport nav={<Sidebar.Root /* … */>{/* … */}</Sidebar.Root>}>
+      <Outlet />
+    </AppShell.Template>
+  );
+}
+```
+
+### Canonical example (одна колонка без `nav`, те же поля)
+
+```tsx
+import { AppShell } from "prime-ui-kit";
+
+export function FullWidthMainRoute() {
+  return (
+    <AppShell.Root fillViewport>
+      <AppShell.Main>
+        <AppShell.MainInset>{/* страница */}</AppShell.MainInset>
+      </AppShell.Main>
+    </AppShell.Root>
+  );
+}
+```
+
+## Rules
+
+- Обертка-приложения с **`AppShell.Template`** должна находиться **внутри** **`BrowserRouter`** / **`MemoryRouter`**, чтобы сброс прокрутки работал; в тестах без роутера сброс не подключается (это нормально).
+- **`ref`**, переданный в **`AppShell.Template`**, по-прежнему вешается на элемент **`main`** (как на **`AppShell.Main`**).
+- Не дублируйте классы/обёртки с теми же отступами, что у **`MainInset`**, и не задавайте произвольные «поля страницы» литералами — один источник правды в ките.
+
+## API
+
+### AppShell.Root
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| fillViewport | `boolean` | `false` | No | Растягивает корень на высоту вьюпорта. |
+| className | `string` | — | No | Класс на корневом `div`. |
+| children | `React.ReactNode` | — | No | Обычно `Nav` + `Main`. |
+| …rest | `HTMLAttributes<HTMLDivElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
+
+### AppShell.Template
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| fillViewport | `boolean` | — | No | Пробрасывается в `Root`. |
+| className | `string` | — | No | Класс на `Root`. |
+| nav | `React.ReactNode` | — | **Yes** | Левая колонка (напр. `Sidebar.Root`). |
+| children | `React.ReactNode` | — | No | Контент внутри `MainInset` внутри `main`. |
+| navProps | `Omit<AppShellNavProps, "children">` | — | No | Пропсы на слот навигации. |
+| mainProps | `Omit<AppShellMainProps, "children">` | — | No | Пропсы на `main` (напр. `id`, `tabIndex`). |
+| …rest | `HTMLAttributes<HTMLDivElement>` | — | No | Остальное на `Root` (без `children` / без `ref` на типе — `ref` на `main`). |
+
+### AppShell.MainInset
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| className | `string` | — | No | Доп. класс; поля заданы модулем кита. |
+| children | `React.ReactNode` | — | No | Содержимое колонки. |
+| …rest | `HTMLAttributes<HTMLDivElement>` | — | No | В т.ч. `ref` (`forwardRef`). |
+
+`AppShell.Nav` и `AppShell.Main` — см. исходные типы в **`AppShell.tsx`**.
+
+## Related
+
+- [PageContent](../../components/page-content/COMPONENT.md) — секции и корень страницы внутри инсета.
+- [Sidebar](../sidebar/COMPONENT.md) — навигация в слоте `nav`.

package/src/layout/sidebar/COMPONENT.md

@@ -8,7 +8,7 @@
 
 **When to use**
 
-- Persistent app navigation beside main content, including **`AppShell.Template`** nav slot with **`sidebarSlot="page-nav"`**.
+- Persistent app navigation beside main content, including **`AppShell.Template`** nav slot with **`sidebarSlot="page-nav"`** (контентная колонка получает поля из **`AppShell.MainInset`** внутри шаблона — не дублировать).
 - Desktop width toggle (expanded vs icon rail) with optional tooltips in **`compact`**.
 - Mobile drawer behavior when **`responsive={true}`** (default): overlay, backdrop; **edge**-кнопка **`Sidebar.ToggleButton`** на границе панели и смещается вместе с ней (в т.ч. при закрытии drawer).