prime-ui-kit 0.21.1 → 0.21.3

package/dist/index.js

@@ -75,6 +75,8 @@ import {
   formatFileSize,
   formatMessageDate,
   formatMessageTime,
+  getRichTextSource,
+  getTextEntities,
   getWaveform,
   groupMessages,
   hueOf,
@@ -88,7 +90,7 @@ import {
   useSidebar,
   useTokenValue,
   useUploadQueue
-} from "./chunks/chunk-S4H2ZKWJ.js";
+} from "./chunks/chunk-R5LI5BO3.js";
 import {
   Avatar,
   Badge,
@@ -123,11 +125,11 @@ import {
   tierMappings,
   tones,
   variants
-} from "./chunks/chunk-S27VR4ON.js";
+} from "./chunks/chunk-JO7E6SZQ.js";
 import {
   ControlSizeProvider,
   useOptionalControlSize
-} from "./chunks/chunk-QFHE5GKW.js";
+} from "./chunks/chunk-HMLQCKRL.js";
 export {
   Accordion,
   AppShell,
@@ -231,6 +233,8 @@ export {
   formatMessageDate,
   formatMessageTime,
   getPasswordStrength,
+  getRichTextSource,
+  getTextEntities,
   getWaveform,
   groupMessages,
   hueOf,

package/dist/internal/ToolRow.d.ts

@@ -17,12 +17,14 @@ export declare function ToolCell({ className, ...rest }: ToolCellProps): import(
 type ToolRowProps = DivProps & {
     /** The row has a line of its own: it wraps and its cells fill it by kind. Off — one line, every cell at its natural width. */
     fill?: boolean;
+    /** The edge a filled row gathers its cells at: `end` — tools of the content; `start` — a section's sub-pages under its title. */
+    align?: "start" | "end";
 };
 /**
  * A row of tools as written, each in a cell of its kind: a search grows, switchers and pickers
  * keep their content width beside it and fill a short line, buttons keep their width at the end.
  */
-export declare function ToolRow({ fill, className, children, ...rest }: ToolRowProps): import("react/jsx-runtime").JSX.Element;
+export declare function ToolRow({ fill, align, className, children, ...rest }: ToolRowProps): import("react/jsx-runtime").JSX.Element;
 type ToolChipsProps = DivProps;
 /** The applied filters (`SmartFilter.Chips`) on a line of their own under a tool row; gone while empty. */
 export declare function ToolChips({ className, ...rest }: ToolChipsProps): import("react/jsx-runtime").JSX.Element;

package/dist/internal/barPlan.d.ts

@@ -4,7 +4,7 @@
  * widths it was chosen from (no re-measure loop).
  *
  * The steps, in the order the row gives way:
- * - `one` — heading · tools · actions on one line;
+ * - `one` — heading · tools · actions on one line (never for a section's sub-pages, see `nav`);
  * - `below` — the tools move to a line of their own under the heading and the actions;
  * - `icons-secondary` — the secondary buttons show only their icons;
  * - `icons` — the primary button too;
@@ -30,6 +30,12 @@ export type BarWidths = {
     path: boolean;
     /** Natural width of the tools on one line; 0 — none. */
     tools: number;
+    /**
+     * The tools hold a navigation — a section's sub-pages as route links. They keep a line of their
+     * own from the start: on the first line they would stand where the heading and the actions of
+     * each sub-page leave room, and those differ from one sub-page to the next.
+     */
+    nav: boolean;
     actions: BarAction[];
     /** Width of the «⋯» button. */
     more: number;

package/dist/internal/blockStack.d.ts

@@ -0,0 +1,7 @@
+import * as React from "react";
+/**
+ * Whether the blocks placed here stand in a host's stack of sections: a dialog body says so, and a
+ * `Tabs.Panel` inside it lays out its own blocks the section step apart, the rhythm of the body's
+ * sections — so a tab's blocks need no spacing wrapper of the consumer's.
+ */
+export declare const BlockStackContext: React.Context<boolean>;

package/dist/internal/overlay/DialogParts.d.ts

@@ -201,11 +201,13 @@ export type DialogActionsProps = React.HTMLAttributes<HTMLDivElement> & {
     ref?: React.Ref<HTMLDivElement>;
 };
 /**
- * The buttons at the end of the header, before the close button: ghost icon buttons (each named,
- * with a Tooltip) and a ⋯ Dropdown — never a status, which leads the `Description`. They take tier
- * `s`, the close button's, and sit on the title's line. In the footer
- * it is the start group — an action apart from the main pair («Удалить», «Выйти») — and its
- * buttons keep the footer's tier.
+ * The controls at the end of the header, before the close button: first one switcher that applies
+ * to the whole open tab (a `SegmentedControl`, a `Datepicker` period), then the buttons — ghost icon
+ * buttons (each named, with a Tooltip) and a ⋯ Dropdown — never a status, which leads the
+ * `Description`. They take tier `s`, the close button's, and sit on the title's line; each stands
+ * in a cell that enters and closes up, so a switcher shown only on some tabs never jolts the row.
+ * In the footer it is the start group — an action apart from the main pair («Удалить», «Выйти») —
+ * and its buttons keep the footer's tier.
  */
 export declare function DialogActions({ className, children, ...rest }: DialogActionsProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace DialogActions {
@@ -214,8 +216,8 @@ export declare namespace DialogActions {
 export type DialogBodyProps = React.HTMLAttributes<HTMLDivElement> & {
     ref?: React.Ref<HTMLDivElement>;
 };
-/** The only scrolling zone; header and footer stay put. */
-export declare function DialogBody({ className, ...rest }: DialogBodyProps): import("react/jsx-runtime").JSX.Element;
+/** The only scrolling zone; header and footer stay put. An open layer: its end never scrolls the page. */
+export declare function DialogBody({ className, children, ...rest }: DialogBodyProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace DialogBody {
     var displayName: string;
 }

package/dist/internal/richText.d.ts

@@ -1,10 +1,41 @@
 import * as React from "react";
+/** What a range of a message text is: its format, and the address of a `link`. */
+export type TextEntityType = "bold" | "italic" | "underline" | "strikethrough" | "spoiler" | "code" | "pre" | "link" | "quote";
+/** One formatted range of a plain text: `offset` and `length` in UTF-16 code units. */
+export type TextEntity = {
+    type: TextEntityType;
+    offset: number;
+    length: number;
+    /** The address of a `link`; without it the range itself is the address. */
+    url?: string;
+    /** The language of a `pre` block. */
+    language?: string;
+};
+/** A plain text with its formatted ranges: what a messenger sends and takes. */
+export type FormattedText = {
+    text: string;
+    entities: TextEntity[];
+};
+/**
+ * The plain text and entities of a Markdown source — what a messenger takes: Composer writes
+ * Markdown, the messenger's API wants `{ text, entities }`.
+ */
+export declare function getTextEntities(source: string): FormattedText;
+/**
+ * The Markdown source of a plain text and its entities — to edit a received or stored text in
+ * Composer or a formatting Textarea. Text that would read as markup is escaped (`\*`); a format
+ * the subset cannot hold (`_italic_` inside a word) is dropped, its text kept.
+ */
+export declare function getRichTextSource({ text, entities }: FormattedText): string;
 type RichTextLabels = {
     /** Accessible name of a masked spoiler: its text is not read until it is revealed. */
     spoiler: string;
 };
 type RichTextProps = {
+    /** The Markdown source, or the plain text that `entities` format. */
     source: string;
+    /** Formatted ranges of `source`: it is then plain text, never read as Markdown. */
+    entities?: readonly TextEntity[];
     /** Rendered at the very end of the last line (a chat bubble's meta reserve). */
     end?: React.ReactNode;
     /** Marks every case-insensitive match of this text (a search through a chat). */
@@ -13,5 +44,5 @@ type RichTextProps = {
     labels: RichTextLabels;
 };
 /** A message text with its Markdown subset rendered safely; `end` closes the last text line. */
-export declare function RichText({ source, end, highlight, labels }: RichTextProps): import("react/jsx-runtime").JSX.Element;
+export declare function RichText({ source, entities, end, highlight, labels }: RichTextProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/internal/selectionIndicator.d.ts

@@ -12,11 +12,17 @@ export declare function setFlag(element: HTMLElement, name: `data-${string}`, on
 /**
  * Places the indicator over `target` — its offset box in the parent they share — straight in the
  * DOM, so a resize or a font swap never re-renders the host. With `animate` (a person's choice) a
- * move of a visible indicator glides; every other placement snaps. Without a target the
- * indicator fades out.
+ * move of a visible indicator glides, and an indicator that appears or leaves fades
+ * (`data-fade`); every other placement snaps, and its first one shows it at once: a fade on mount
+ * would leave the selected item without its fill while the host opens (a Drawer sliding in), and
+ * an opacity transition makes the indicator a composited layer that browsers paint over the
+ * item's text inside the row's edge-fade mask until it ends.
  */
 export declare function placeIndicator(indicator: HTMLElement, target: HTMLElement | null, animate: boolean): void;
-/** `onTransitionEnd` of the indicator: the glide is over, so the next layout change snaps. */
+/**
+ * `onTransitionEnd` of the indicator: the glide or the fade is over, so the next layout change
+ * snaps.
+ */
 export declare function endIndicatorGlide(event: Pick<React.TransitionEvent<HTMLElement>, "target" | "currentTarget" | "propertyName">): void;
 /**
  * Scrolls a sideways scroller (never the page: `scrollIntoView` would scroll it too) so `item` is

package/dist/internal/textFormatting.d.ts

@@ -4,7 +4,7 @@
  * the result to its textarea. `internal/richText` renders the same subset.
  */
 /** A formatting command: what the toolbar button or the hotkey applies to the selection. */
-export type TextFormat = "bold" | "italic" | "strikethrough" | "code" | "spoiler" | "link" | "quote";
+export type TextFormat = "bold" | "italic" | "underline" | "strikethrough" | "code" | "spoiler" | "link" | "quote";
 /** Names of the formatting toolbar and of its tools, one per format. */
 export type TextFormattingLabels = Record<TextFormat, string> & {
     /** Accessible name of the formatting toolbar. */
@@ -31,7 +31,7 @@ export declare function diffRange(before: string, after: string): {
     insert: string;
 };
 /**
- * The format a key press asks for: Mod+B · Mod+I · Mod+Shift+X · Mod+E · Mod+Shift+H · Mod+K ·
+ * The format a key press asks for: Mod+B · Mod+I · Mod+U · Mod+Shift+X · Mod+E · Mod+Shift+H · Mod+K ·
  * Mod+Shift+9. The spoiler is not Telegram's Mod+Shift+P: Firefox and Edge reserve it for a private
  * window and never hand it to the page.
  */

package/dist/layout/page/Page.d.ts

@@ -60,7 +60,8 @@ export type PageTopBarProps = React.HTMLAttributes<HTMLElement> & {
  * The page's strip at its top edge, across the panel. Up to four groups in one grid —
  * `Page.Heading`, `Page.Tools`, `Page.Actions` on the first line, `Page.Chips` under them — laid
  * out by one plan chosen from their natural widths (`planBar`): one line while everything fits;
- * then the tools take a line of their own; then the buttons give way to their icons, secondary
+ * then the tools take a line of their own (a section's sub-pages — tools holding a navigation —
+ * always, at the start, so the switch stands still from one sub-page to the next); then the buttons give way to their icons, secondary
  * first, and fold into «⋯»; only then does a heading with a path stack (path over title), and a
  * heading without one truncate. Sticky inside the scroller of
  * the page; while the shell's Sidebar is off-canvas it starts with the menu button. With

package/dist/skill/SKILL.md

@@ -123,8 +123,9 @@ Take a semantic `<Icon name="…" />` first, else a glyph from the full animated
 7. Labels above fields, always — once per column for records in rows (`FieldList`), never numbered
    («Пункт 1»), never repeating their heading. Placeholder is an example value, never the label.
 8. Text through `Typography` roles (`title-m` section, `title-s` group, `body-m` text, `caption` meta;
-   the page title is `Page.Title`, one per page: in the `Page.Heading` of `Page.TopBar` on a work screen, in the flow
-   on a document page or an overview). No custom font sizes.
+   the page title is `Page.Title`, one per page: in the `Page.Heading` of `Page.TopBar` on every screen
+   of data — lists, boards, records, dashboards and analytics alike; in the flow only on a document page
+   with no page tools). No custom font sizes.
 9. Overlays (Modal, ConfirmDialog, Drawer, Sheet, Popover, Dropdown, Tooltip, CommandMenu, Select,
    MediaViewer) come from the kit — never hand-made — and stay mounted: drive them with `open`,
    never `{open && …}`.

package/dist/skill/api-contract.md

@@ -377,7 +377,7 @@ crumb of your own.
 <!-- icons:start -->
 `<Icon name="…" />` names:
 - `nav.*`: `chevronDown`, `chevronLeft`, `chevronRight`, `chevronUp`, `chevronsLeft`, `chevronsUpDown`, `dashboard`, `home`, `itemDot`, `layoutGrid`, `menu`, `sidebarCollapse`, `sidebarExpand`;
-- `action.*`: `add`, `addContact`, `attach`, `check`, `close`, `copy`, `delete`, `download`, `drag`, `edit`, `externalLink`, `eyedropper`, `filter`, `forward`, `login`, `logout`, `more`, `pause`, `pin`, `play`, `react`, `refresh`, `report`, `remove`, `reply`, `search`, `send`, `settings`, `transcribe`, `upload`, `video`, `voice`, `zoomIn`, `zoomOut`;
+- `action.*`: `add`, `addContact`, `attach`, `check`, `close`, `copy`, `delete`, `download`, `drag`, `edit`, `externalLink`, `eyedropper`, `filter`, `forward`, `login`, `logout`, `more`, `openApp`, `pause`, `pin`, `play`, `react`, `refresh`, `report`, `remove`, `reply`, `search`, `send`, `settings`, `transcribe`, `upload`, `video`, `voice`, `zoomIn`, `zoomOut`;
 - `field.*`: `calendar`, `email`, `password.show`, `password.hide`;
 - `format.*`: `bold`, `code`, `italic`, `link`, `list`, `quote`, `spoiler`, `strikethrough`, `underline`;
 - `object.*`: `activity`, `bell`, `bike`, `book`, `cart`, `chart`, `crown`, `disc`, `document`, `file`, `fuel`, `funnel`, `globe`, `headset`, `image`, `inbox`, `key`, `mapPin`, `megaphone`, `message`, `motorbike`, `package`, `phone`, `receipt`, `rocket`, `scale`, `storage`, `tasks`, `trophy`, `truck`, `user`, `users`, `wallet`;
@@ -385,7 +385,8 @@ crumb of your own.
 - `status.*`: `danger`, `emailSent`, `failed`, `favorite`, `info`, `locked`, `muted`, `sound`, `offline`, `pending`, `read`, `sent`, `success`, `trendUp`, `warning`;
 - `theme.*`: `dark`, `light`;
 - `view.*`: `code`, `columns`, `preview`;
-- `viewport.*`: `desktop`, `mobile`, `tablet`.
+- `viewport.*`: `desktop`, `mobile`, `tablet`;
+- `brand.*`: `telegram`, `vk`, `whatsapp`.
 <!-- icons:end -->
 
 Every glyph comes from the kit, in this order:

package/dist/skill/cheatsheet.md

@@ -95,7 +95,7 @@ reference is each component's `COMPONENT.md` ([components.md](components.md)), t
 - A filtered page: `<SmartFilter.Root>` wraps `<Page.Root>` — it draws nothing; not `SmartFilter.Root` inside the bar.
 - No size knob on the title: the bar sizes the heading and gives way by width itself ([the five steps](responsive.md#the-pages-top-bar--pagetopbar)).
 - Sign-in, sign-up, an invite and a password reset are modes of one `/login` screen, one `LoginForm` with the action's icon in `LoginForm.Logo` and the default `align` — not a page per mode, not a centred brand mark ([auth](layouts.md#auth-sign-in-code)).
-- A document page (settings, a long form, help) and an overview (a dashboard) put `<Page.Header>` with its `<Page.Heading>` in the flow — the large title — with an optional `<Page.TopBar collapse>` above it that repeats the title once it scrolls away. One `<Page.Title>` per page — never two titles, never no `<h1>`.
+- A dashboard, analytics or statistics page titles itself in `<Page.TopBar>` like a list — not a bar of tools over a large title in the flow. Only a document page (settings, a long form, help) puts `<Page.Header>` with its `<Page.Heading>` in the flow, with an optional `<Page.TopBar collapse>` above it whose heading holds the path. One `<Page.Title>` per page — never two titles, never no `<h1>`.
 
 ## Cards and surfaces
 

package/dist/skill/checklist.md

@@ -5,7 +5,7 @@ checks.
 
 ## Composition
 - [ ] The screen starts from the closest working screen and keeps its skeleton ([screens](composition.md#screens)).
-- [ ] One `Page.Title` per page, always an `<h1>`: a work screen titles itself in the `Page.Heading` of its `Page.TopBar`, a document page or an overview in a `Page.Header` in the flow ([page skeleton](composition.md#1-page-skeleton)).
+- [ ] One `Page.Title` per page, always an `<h1>`: every screen of data — dashboards and analytics too — titles itself in the `Page.Heading` of its `Page.TopBar`, only a document page in a `Page.Header` in the flow; no `collapse` bar without a heading ([page skeleton](composition.md#1-page-skeleton)).
 - [ ] The top bar holds only this page's groups — `Page.Heading`, `Page.Tools`, `Page.Actions`, `Page.Chips` — no app-wide header or global search ([the top bar](composition.md#the-top-bar)).
 - [ ] A nested record's path ends in its title on one line inside `Page.Heading`; no title row under the path ([the top bar](composition.md#the-top-bar)).
 - [ ] Every button of the page is in one `Page.Actions`, the primary last, each with a `Button.Icon` ([the top bar](composition.md#the-top-bar)).
@@ -14,6 +14,7 @@ checks.
 - [ ] A control stands with what it changes: a table's search, filter, chips and chooser are in its `toolbar` / `toolbarChips` on every page; the bar keeps the title, sections, the view, the shared period and the buttons ([where the filters go](composition.md#where-the-filters-go)).
 - [ ] A table section has an `options` filter field for each categorical column and a `date-range` field per date column, its value in the URL ([where the filters go](composition.md#where-the-filters-go)).
 - [ ] Actions on selected rows are `renderSelectionActions` — one «Действия · N» menu added to the tools row, which stays ([controls of a table](composition.md#controls-of-a-table)).
+- [ ] Creating one of several kinds whose forms differ is a button with a `Dropdown` of kinds (grouped by family), a pick opens that kind's form; no choosing step and «Далее» inside a dialog ([a kind that leads to its own form](choosing.md#a-kind-that-leads-to-its-own-form)).
 - [ ] A Card only for a standalone titled block — never around a table, a single field or the page ([surfaces](composition.md#4-surfaces)).
 - [ ] A titled panel carries its heading in its `Card.Header` and stacks in the flow; no heading column beside a panel ([surfaces](composition.md#4-surfaces)).
 - [ ] A DataTable's row grip and column order follow the rule: grip at the end, columns by `columnOrder` saved with `hiddenColumns` ([choosing](choosing.md#3-pairs-that-are-easy-to-confuse)).
@@ -24,6 +25,9 @@ checks.
 - [ ] Every entity is laid out by its shape: a record is one row or one block ([data shape](ux.md#2-the-shape-of-the-data-decides-the-layout)).
 - [ ] A FieldList row shows its «×» in sight whatever its columns; `rowActions="menu"` only on a reorderable touch-first list; `variant` by the rule ([forms](composition.md#7-forms)).
 - [ ] A section named after a set of records shows the records, with an action per row ([data shape](ux.md#2-the-shape-of-the-data-decides-the-layout)).
+- [ ] Records of one kind are one list in their real order; rows the system fixes are `locked` in it, never a second section ([data shape](ux.md#2-the-shape-of-the-data-decides-the-layout)).
+- [ ] Every heading names what nothing else names: no section over a block with its own title, no first block repeating its tab ([label economy](ux.md#3-label-economy)).
+- [ ] Every hint, limit, counter and range line serves the task; none is on because the prop exists, and a `max` worth knowing is in `hint` ([label economy](ux.md#3-label-economy)).
 - [ ] Labels on a form of rows ≤ columns + the list label; none repeated, numbered or repeating its heading ([label economy](ux.md#3-label-economy)).
 - [ ] No text explains the layout; every hint is two to five words the label and the control leave out, never the obvious outcome ([label economy](ux.md#3-label-economy)).
 - [ ] Every setting sits with what it governs, as a field beside its neighbours; a stored choice is a `Select`, no section holds one setting ([where a setting lives](ux.md#10-where-a-setting-lives)).
@@ -74,6 +78,7 @@ checks.
 - [ ] One secondary action is an icon button with a Tooltip; a «⋯» menu holds two or more ([a menu from two actions](composition.md#a-menu-from-two-actions)).
 - [ ] An entity has one drawer opened from everywhere; permissions lock fields and hide tabs and actions; header actions act on the record, never lead elsewhere ([a record in a drawer](composition.md#a-record-in-a-drawer)).
 - [ ] A record drawer is one form with one «Сохранить» in its footer while dirty and `Drawer.Guard`; no save per section, no unsaved-status text ([a record in a drawer](composition.md#a-record-in-a-drawer)).
+- [ ] A control that changes the whole open tab (a language, a period) is one control in the header's `Drawer.Actions` before the buttons, only on the tabs it applies to ([a record in a drawer](composition.md#a-record-in-a-drawer)).
 - [ ] A drawer loads its tabs' data itself, the history has its own tab, and returning to a tab never shows a skeleton again ([a record in a drawer](composition.md#a-record-in-a-drawer)).
 - [ ] An on/off permission or setting is a `Switch`, a level per entity a `FieldList` of `Select`s, a set of values in a table cell `Badge.Group overflow="count"` ([a flag, a level, a set](choosing.md#a-flag-a-level-a-set)).
 - [ ] The same action has the same label and variant everywhere on the screen ([secondary actions](api-contract.md#secondary-actions)).

package/dist/skill/choosing.md

@@ -42,7 +42,7 @@ under them → its `renderTotals`.
 |---|---|
 | a capability or a setting that is on or off, in a form or applied at once | Switch ([a flag, a level, a set](#a-flag-a-level-a-set)) |
 | items picked out of a set, a consent, an option of the action being sent | Checkbox |
-| exactly one of 2–5 visible options in a form | Radio (`Radio.Group` with `label`) |
+| exactly one of 2–5 visible options, a value of the one form whose other fields stay the same | Radio (`Radio.Group` with `label`); a choice that leads to a different form is a menu, not a field ([a kind that leads to its own form](#a-kind-that-leads-to-its-own-form)) |
 | exactly one of 2–5 modes that change the view right now — never a stored setting | SegmentedControl |
 | one of many (> 5) or a long list; icons, descriptions, search, groups | Select (`Select.Content searchable`) |
 | one record out of thousands for a form field (a client, a contract), searched on the server | Select with `search` / `onSearchChange`, `filter={false}`, `loading`, `hasMore` + `onLoadMore` — never a read-only field that opens a CommandMenu |
@@ -77,7 +77,7 @@ Records with a start and an end compared across time — who is busy when, a pro
 phases and milestones → Gantt (never a DataTable of dates or hand-drawn bars); moved and resized by
 hand through `onBarChange`.
 Chronological events → Timeline (two facts under an event → two `Timeline.ItemMeta`, they stack); a conversation between people (support, a team chat) → Message —
-never a Timeline or a list of Cards styled as bubbles. Code → CodeBlock. A number with its trend over days or weeks (revenue, orders, sign-ups) → Sparkline: the latest value, its change and a line you can scrub; values with a sign by period → Sparkline `variant="bars"`; against a plan → `reference`; missing days → `value: null`; a chart with axes or several series → ChartFrame around a chart library or your own SVG (the panel, legend, tooltip, states and the screen-reader table come from the kit, the colors from `series` / `chartColors` — never status tones); values to read, sort or compare row by row → DataTable, not a chart.
+never a Timeline or a list of Cards styled as bubbles. Code → CodeBlock. A number with its trend over days or weeks (revenue, orders, sign-ups) → Sparkline: the headline value and a line you can scrub; its change badge against the previous period → `compareTo` (`change` for a point-to-point badge while scrubbing, off by default); a metric whose growth is bad (response time, costs, refusals) → `better="lower"`; a share or a conversion in percent → `changeUnit="points"` («+0,5 п. п.», never a percent of a percent); a period figure that is neither the sum nor the mean of the points (a median, unique clients) → `value`; values with a sign by period → Sparkline `variant="bars"`; against a plan → `reference`; missing days → `value: null` in `data`; a chart with axes or several series → ChartFrame around a chart library or your own SVG (the panel, legend, tooltip, states and the screen-reader table come from the kit, the colors from `series` / `chartColors` — never status tones); values to read, sort or compare row by row → DataTable, not a chart.
 
 **Messages.** A whole conversation → `Chat`: `Chat.Root` with `Chat.Header` (avatar, `Chat.Title`,
 `Chat.Description`, `Chat.Actions` with `Chat.SearchButton`), `Chat.Search`, `Chat.Pinned`,
@@ -137,8 +137,8 @@ the rail has no brand header. On phones the off-canvas Sidebar opens from the me
 page's `Page.TopBar` draws by itself; a trigger of your own reads `useAppShellNav()`. There is no
 app-wide header: the bar at the top of the panel is the page's `Page.TopBar` — on a work screen the
 title group (`Page.Heading`), the page's tools (`Page.Tools`), its buttons (`Page.Actions`) and the
-active filters (`Page.Chips`) — [the top bar](composition.md#the-top-bar). A document
-page (settings, a long form, help) or an overview has its large title in the flow (`Page.Header`
+active filters (`Page.Chips`) — [the top bar](composition.md#the-top-bar), on a dashboard as on a
+list. Only a document page (settings, a long form, help) has its large title in the flow (`Page.Header`
 outside the bar), with an optional `Page.TopBar collapse` that repeats it once it scrolls away. A record opened from a table: its own page → DataTable `getRowHref`; in place →
 `onRowClick` + Drawer; a list worked through record by record → `Page.Split` with a `List` of
 the records (tickets, letters, invoices; `current` on the open one; a row's own Switch or menu in
@@ -221,6 +221,77 @@ column, and shows only the ones that have a level.
 </>
 ```
 
+### A kind that leads to its own form
+
+Creating or connecting one of several kinds of record whose forms differ (a Telegram bot or a
+Telegram account, a VK community or a VK account; an invoice or an act) is a fork before the form,
+not a field of it. Ask of the choice: do the fields after it stay the same?
+
+| The choice | Shape |
+|---|---|
+| the fields stay the same; the choice is one more value of the record (a client type, a currency) | a field of the form: `Radio.Group` for 2–5, `Select` for more |
+| each option has its own fields, its own steps or its own service to connect | the action button opens a `Dropdown`: one `Dropdown.Item` per kind (`Dropdown.ItemIcon` with its glyph), in a `Dropdown.Group label` per family when the kinds group (by messenger, by document type); a pick opens that kind's form straight away, titled by the kind («Подключить Telegram-бота»); in ⌘K, one `CommandMenu.Item` per kind |
+
+Never a dialog whose first step is the choice and a «Далее»: the person already said what they
+want by pressing the item, and a dialog that changes its fields under a choice cannot say what it
+will create. One kind only → the button opens its form directly, no menu.
+
+```tsx partial
+// bad — the kind is a first step inside the dialog: two choices and «Далее» before any field
+<Modal.Body>
+  <SegmentedControl.Root label="Мессенджер" defaultValue="telegram">…</SegmentedControl.Root>
+  <Radio.Group label="Что подключить" defaultValue="bot">…</Radio.Group>
+</Modal.Body>
+<Modal.Footer>
+  <Button.Root>Далее</Button.Root>
+</Modal.Footer>
+```
+
+```tsx good
+// good — the button is a menu of kinds grouped by messenger; a pick opens that kind's form
+// declare: const openConnect: (kind: "telegram-bot" | "telegram-account" | "vk-group" | "vk-account") => void
+<Dropdown.Root>
+  <Dropdown.Trigger>
+    <Button.Root>
+      <Button.Icon>
+        <Icon name="action.add" />
+      </Button.Icon>
+      Подключить
+    </Button.Root>
+  </Dropdown.Trigger>
+  <Dropdown.Content>
+    <Dropdown.Group label="Telegram">
+      <Dropdown.Item onSelect={() => openConnect("telegram-bot")}>
+        <Dropdown.ItemIcon>
+          <Icon name="brand.telegram" />
+        </Dropdown.ItemIcon>
+        Бот
+      </Dropdown.Item>
+      <Dropdown.Item onSelect={() => openConnect("telegram-account")}>
+        <Dropdown.ItemIcon>
+          <Icon name="brand.telegram" />
+        </Dropdown.ItemIcon>
+        Аккаунт
+      </Dropdown.Item>
+    </Dropdown.Group>
+    <Dropdown.Group label="ВКонтакте">
+      <Dropdown.Item onSelect={() => openConnect("vk-group")}>
+        <Dropdown.ItemIcon>
+          <Icon name="brand.vk" />
+        </Dropdown.ItemIcon>
+        Сообщество
+      </Dropdown.Item>
+      <Dropdown.Item onSelect={() => openConnect("vk-account")}>
+        <Dropdown.ItemIcon>
+          <Icon name="brand.vk" />
+        </Dropdown.ItemIcon>
+        Аккаунт
+      </Dropdown.Item>
+    </Dropdown.Group>
+  </Dropdown.Content>
+</Dropdown.Root>
+```
+
 ## 3. Pairs that are easy to confuse
 
 | Pair | Rule |
@@ -238,7 +309,7 @@ column, and shows only the ones that have a level.
 | Button / LinkButton | Button does something (submit, open, delete). LinkButton goes somewhere (a URL, «Подробнее», «Все заказы»). |
 | Checkbox / Switch / Radio | Switch: a capability or a setting that is on or off — a permission, a privacy toggle — whether it saves with a form or at once. Checkbox: items picked out of a set, a consent, a one-off option of the action being sent. Radio: one of several, submitted later ([a flag, a level, a set](#a-flag-a-level-a-set)). |
 | Gallery / MediaViewer / Thumbnail | Thumbnail: one picture or video of an object in a list, card or picker (selectable with `checked`). Gallery: an album of 1–10 photos and videos laid out by their ratios; it opens MediaViewer itself. MediaViewer: the full-screen viewer on its own, opened from your own thumbnails or a button (`getOrigin` for the zoom out of the tile). A grid of many images to browse → a CSS grid of Thumbnails, not a Gallery. |
-| Sparkline / ChartFrame | Sparkline: one series as a headline number with its change and a small line or bars you can scrub (`variant="bars"` for signed values). ChartFrame: a panel around a real chart (axes, several series, legend, tooltip, states) drawn by a library or your SVG. Rows to compare → DataTable. |
+| Sparkline / ChartFrame | Sparkline: one series as a headline number and a small line or bars you can scrub, its change badge on request (`variant="bars"` for signed values). ChartFrame: a panel around a real chart (axes, several series, legend, tooltip, states) drawn by a library or your SVG. Rows to compare → DataTable. |
 | VoicePlayer / VideoNote | The same player props (`src`, `duration`, `playing`, transcript, `transfer`). VoicePlayer: audio, a waveform seek slider and a playback rate. VideoNote: a round face-to-camera video with a `poster`; alone in `Message.Root` it is the message. A video with controls → `Thumbnail.Video` / `Message.Media`. |
 | Card / plain section / Grid | Card for a bounded block of related content that stands out (metric, settings panel, side facts). A page section that is the only thing in its region needs no card: `Page.Section label` and the content. Several tiles of one screen → one `Page.Grid` with a `Page.Cell span` each; a grid inside one block (thumbnails, fields) is the block's own CSS. Never wrap a single field, a DataTable or a whole page in a Card. |
 | EmptyPage / empty DataTable | Empty table (no rows yet or nothing matches the filter): the DataTable `empty` prop — headers and toolbar stay. Whole page or region with no data at all (first run): EmptyPage with one action. |

package/dist/skill/components.md

@@ -78,9 +78,9 @@ Show data: labels, people, objects, cards, tables, boards, feeds, code, disclose
 | Gantt | A resource or project schedule: rows of people, rooms, vehicles or tasks with bars on a day / week / month axis, edited by pointer and keyboard. | [COMPONENT.md](reference/components/gantt/COMPONENT.md) · [examples](reference/components/gantt/examples/) |
 | Timeline | An event feed: dots on a thin line, event title and date, an optional amount on the right, grouped under labels. | [COMPONENT.md](reference/components/timeline/COMPONENT.md) · [examples](reference/components/timeline/examples/) |
 | CodeBlock | A static TypeScript / TSX snippet with syntax highlighting, on a filled panel or bare inside a host. | [COMPONENT.md](reference/components/code-block/COMPONENT.md) · [examples](reference/components/code-block/examples/) |
-| RichText | Text in the chat's Markdown subset outside a message — a bot's welcome text, a template, a comment — rendered as elements, never as HTML. | [COMPONENT.md](reference/components/rich-text/COMPONENT.md) · [examples](reference/components/rich-text/examples/) |
+| RichText | Text in the chat's Markdown subset — or a messenger's plain text with its entities — outside a message (a bot's welcome text, a template, a comment), rendered as elements, never as HTML. | [COMPONENT.md](reference/components/rich-text/COMPONENT.md) · [examples](reference/components/rich-text/examples/) |
 | Accordion | Collapsible sections: FAQ, settings groups, checkout steps. | [COMPONENT.md](reference/components/accordion/COMPONENT.md) · [examples](reference/components/accordion/examples/) |
-| Sparkline | A small chart — a smooth line over a fading area, a bare line or bars — with its headline: the value at rest, its change and its date; any point can be scrubbed. | [COMPONENT.md](reference/components/sparkline/COMPONENT.md) · [examples](reference/components/sparkline/examples/) |
+| Sparkline | A small chart — a smooth line over a fading area, a bare line or bars — with its headline: the value at rest, its date and an optional change; any point can be scrubbed. | [COMPONENT.md](reference/components/sparkline/COMPONENT.md) · [examples](reference/components/sparkline/examples/) |
 | ChartFrame | A dashboard panel around any chart — Recharts, ECharts, visx, Chart.js or a hand-drawn SVG — with the title, a headline value, a measured plot area, a series legend, a tooltip body and a data table for screen readers. | [COMPONENT.md](reference/components/chart-frame/COMPONENT.md) · [examples](reference/components/chart-frame/examples/) |
 | DescriptionList | Read-only properties of a record: «label — value» pairs on a `<dl>` that stack by themselves where the room is narrow, with a muted dash for an empty value. | [COMPONENT.md](reference/components/description-list/COMPONENT.md) · [examples](reference/components/description-list/examples/) |