prime-ui-kit 0.17.0 → 0.19.0

package/dist/index.js

@@ -46,6 +46,7 @@ import {
   Pagination,
   ProgressCircle,
   Radio,
+  RichText,
   SegmentedControl,
   Sheet,
   Sidebar,
@@ -86,7 +87,7 @@ import {
   useSidebar,
   useTokenValue,
   useUploadQueue
-} from "./chunks/chunk-A4WE3UNC.js";
+} from "./chunks/chunk-WYCTXD63.js";
 import {
   Avatar,
   Badge,
@@ -121,11 +122,11 @@ import {
   tierMappings,
   tones,
   variants
-} from "./chunks/chunk-7WWZYGRC.js";
+} from "./chunks/chunk-RZNGLELR.js";
 import {
   ControlSizeProvider,
   useOptionalControlSize
-} from "./chunks/chunk-2ODXLPW3.js";
+} from "./chunks/chunk-QFHE5GKW.js";
 export {
   Accordion,
   AppShell,
@@ -188,6 +189,7 @@ export {
   ProgressBar,
   ProgressCircle,
   Radio,
+  RichText,
   ScrollContainer,
   SegmentedControl,
   Select,

package/dist/internal/ChoiceField.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { HintTone } from "../components/hint/Hint";
 import { type FieldIds } from "./FieldFrame";
 import type { CheckState, ControlSize } from "./states";
 /** Class of the visually hidden native input that sits on top of the visual control. */
@@ -38,13 +39,14 @@ type ChoiceFieldProps = {
      */
     groupOption?: boolean;
     hint?: React.ReactNode;
+    hintTone?: HintTone;
     error?: React.ReactNode;
     /** The native input (with `choiceInputClass`) followed by its aria-hidden visual. */
     control: React.ReactNode;
     className?: string;
     children?: React.ReactNode;
 };
-export declare function ChoiceField({ ids, size, state, disabled, readOnly, busy, required, optional, optionalLabel, groupOption, hint, error, control, className, children, }: ChoiceFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChoiceField({ ids, size, state, disabled, readOnly, busy, required, optional, optionalLabel, groupOption, hint, hintTone, error, control, className, children, }: ChoiceFieldProps): import("react/jsx-runtime").JSX.Element;
 export type ChoiceLabelProps = React.HTMLAttributes<HTMLSpanElement> & {
     ref?: React.Ref<HTMLSpanElement>;
 };

package/dist/internal/FieldFrame.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+import { type HintTone } from "../components/hint/Hint";
 import type { ControlSize } from "./states";
 /** Field props shared by every framed field (the same contract as `Input.Root`). */
 export type FieldFrameProps = {
@@ -18,6 +19,10 @@ export type FieldFrameProps = {
      * Support text under the field; linked by `aria-describedby`.
      */
     hint?: React.ReactNode;
+    /**
+     * Status color of `hint` («Осталось 12 дней» in `warning`). The words carry the status, the color repeats it; an `error` replaces the hint and its tone. A validation error is `error`, never a `danger` hint.
+     */
+    hintTone?: HintTone;
     /**
      * Error message; replaces the hint and implies `invalid`.
      */
@@ -121,10 +126,11 @@ export declare function useLeavingError(showError: boolean, error: React.ReactNo
  * changes is read, an error the field mounts with is read with the field (`aria-describedby`).
  * An option of a group (`live={false}`) leaves the announcement to the group.
  */
-export declare function FieldSupport({ ids, size, hint, error, leaving, disabled, live, className, textClassName, }: {
+export declare function FieldSupport({ ids, size, hint, hintTone, error, leaving, disabled, live, className, textClassName, }: {
     ids: FieldIds;
     size: ControlSize;
     hint?: React.ReactNode;
+    hintTone?: HintTone;
     error?: React.ReactNode;
     /** The error leaving the slot: the frame's `useLeavingError`. */
     leaving: FieldLeavingError | null;
@@ -166,7 +172,7 @@ type FieldFrameRenderProps = FieldFrameProps & {
  * spaced by the tier's `--field-label-gap` / `--field-hint-gap`. The support row stays mounted
  * (empty and without room when it shows nothing), so its text slot is a polite live region.
  */
-export declare function FieldFrame({ size, ids, label, required, optional, hint, error, disabled, optionalLabel, requiredLabel, group, labelEnd, counter, reserveSupportRow, className, children, ...rest }: FieldFrameRenderProps): import("react/jsx-runtime").JSX.Element;
+export declare function FieldFrame({ size, ids, label, required, optional, hint, hintTone, error, disabled, optionalLabel, requiredLabel, group, labelEnd, counter, reserveSupportRow, className, children, ...rest }: FieldFrameRenderProps): import("react/jsx-runtime").JSX.Element;
 type FieldCounterProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
     current: number;
     max: number;

package/dist/internal/fieldCell.d.ts

@@ -4,7 +4,7 @@ import * as React from "react";
  * a framed field without a `label` of its own takes it as its label (and keeps its own `label`, if
  * any), so every field in a row has a name without a visible label per row. The column heading
  * shows the name once above the rows; the field's label is read, not shown, until the list stacks
- * its rows into blocks in a narrow container (the `prime-field-list` container FieldList sets),
+ * its rows into blocks in a narrow container (the size container of the FieldList body),
  * where each field shows it.
  */
 export type FieldCell = {
@@ -17,6 +17,12 @@ export type FieldCell = {
     hidden: "wide" | "always";
     /** The column is required: the field in the cell is required too (`useFieldFrame`). */
     required: boolean;
+    /**
+     * The row's action the field holds at its end: a one-column list puts each row's remove button
+     * inside its field. A text field (`Input.Wrapper`, `Textarea`) renders it as its last action
+     * segment; a list whose field holds none keeps the remove in a column of its own.
+     */
+    action?: React.ReactNode;
 };
 export declare const FieldCellContext: React.Context<FieldCell | null>;
 export declare function useFieldCell(): FieldCell | null;

package/dist/internal/formatClock.d.ts

@@ -1,4 +1,25 @@
 /** A media position or length: `m:ss`, `h:mm:ss` from an hour on. */
 export declare function formatClock(seconds: number): string;
-/** A time of day: `HH:mm`, 24-hour, in the local zone («09:05»). */
-export declare function formatTimeOfDay(date: Date): string;
+/** A calendar day: the month 0–11, as `Date#getMonth`. */
+type CalendarDay = {
+    year: number;
+    month: number;
+    day: number;
+};
+/** The calendar day and the clock of a moment as a time zone reads it. */
+type ZonedParts = CalendarDay & {
+    /** 0 (Sunday) – 6, as `Date#getDay`. */
+    weekday: number;
+    hours: number;
+    minutes: number;
+};
+/**
+ * The day and the clock of `date` in `timeZone` (an IANA name, `"Asia/Vladivostok"`); without one,
+ * in the browser's zone.
+ */
+export declare function zonedParts(date: Date, timeZone?: string): ZonedParts;
+/** Whole calendar days from `from` to `to` (both read in one zone); never off by a DST hour. */
+export declare function daysBetween(from: CalendarDay, to: CalendarDay): number;
+/** A time of day: `HH:mm`, 24-hour, in `timeZone` or the browser's zone («09:05»). */
+export declare function formatTimeOfDay(date: Date, timeZone?: string): string;
+export {};

package/dist/internal/leaveGuard.d.ts

@@ -0,0 +1,27 @@
+import * as React from "react";
+/** What holds a page: a request runs (`busy`), changes are not saved (`dirty`). */
+type LeaveGuardState = {
+    busy: boolean;
+    dirty: boolean;
+};
+/**
+ * The `onClickCapture` of a navigation item (`Sidebar.Item`, `BottomNav.Item`, a `Breadcrumb.Item`
+ * level), chained before the consumer's own. While a page guard holds, the click stops before any
+ * handler of the item or of its router link runs and before the browser follows `href`: `busy`
+ * holds it, `dirty` asks the guard's confirm, which replays the click once the person agrees.
+ * Router-agnostic: the replay is the same click. A click that opens a new tab or window, or one on
+ * a disabled item, is never held.
+ */
+export declare function leaveGuardCapture(onClickCapture?: React.MouseEventHandler<HTMLElement>): React.MouseEventHandler<HTMLElement>;
+/**
+ * Registers a page guard while mounted: the navigation items ask it through `holdLeave`, and while
+ * it is `busy` or `dirty` the browser asks before the tab closes or reloads (`beforeunload`).
+ */
+export declare function useLeaveGuard({ busy, dirty }: LeaveGuardState, ask: (leave: () => void) => void): void;
+/**
+ * While `hold` is true the browser asks before the tab closes or reloads (`beforeunload`): a page
+ * guard, and a dialog guard (`Modal.Guard`, `Drawer.Guard`, `Sheet.Guard`) whose form is not saved.
+ * `released` lets a leave the person already agreed to go without a second prompt.
+ */
+export declare function useUnloadGuard(hold: boolean, released?: () => boolean): void;
+export {};

package/dist/internal/messageList.d.ts

@@ -66,6 +66,8 @@ export type MessageListContextValue = {
     reactionOptions: readonly MessageReactionOption[] | null;
     /** The reader: joins a reaction's avatars at once when they put it. */
     reader: MessageUser | undefined;
+    /** The zone a message reads its time in; `undefined` — the browser's zone. */
+    timeZone: string | undefined;
     /** Says `text` in the list's polite live region. */
     announce: (text: string) => void;
 };

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

@@ -10,8 +10,9 @@ export type DialogGuardProps = {
 };
 /**
  * Holds a Modal, Drawer or Sheet from inside its content, where the form state lives: put it anywhere in
- * `Content`. Renders nothing but the «discard changes?» confirm when it is asked. Closing from code
- * (`open={false}`) is never held.
+ * `Content`. Renders nothing but the «discard changes?» confirm when it is asked. While `busy` or
+ * `dirty` the browser also asks before the tab closes or reloads, as `Page.Guard` does. Closing from
+ * code (`open={false}`) is never held.
  */
 export declare function DialogGuard({ busy, dirty }: DialogGuardProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace DialogGuard {

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

@@ -148,9 +148,17 @@ export declare namespace DialogTitle {
     var displayName: string;
 }
 export type DialogDescriptionProps = Omit<React.HTMLAttributes<HTMLParagraphElement>, "id"> & {
+    /**
+     * Its data loads: a `Skeleton` holds the line's place and `aria-busy` is set, so the header never moves; the data fades in.
+     */
+    loading?: boolean;
     ref?: React.Ref<HTMLParagraphElement>;
 };
-export declare function DialogDescription({ className, ...rest }: DialogDescriptionProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The line under the title. While its data loads (`loading`) it keeps its place with a Skeleton, so
+ * the header never moves when the data arrives; the data then fades in under the same element.
+ */
+export declare function DialogDescription({ loading, className, children, ...rest }: DialogDescriptionProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace DialogDescription {
     var displayName: string;
 }
@@ -163,9 +171,10 @@ export type DialogHeaderProps = React.HTMLAttributes<HTMLElement> & {
 };
 /**
  * `[Icon] [Title + Description] [Actions] [close]` in one row. Layout is a CSS grid, so child
- * order does not matter; text children stack in the text column.
+ * order does not matter; text children stack in the text column. When the row is too narrow for
+ * the title beside the actions (a phone), the actions move under the text.
  */
-export declare function DialogHeader({ showClose, className, children, ...rest }: DialogHeaderProps): import("react/jsx-runtime").JSX.Element;
+export declare function DialogHeader({ showClose, className, children, ref, ...rest }: DialogHeaderProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace DialogHeader {
     var displayName: string;
 }
@@ -188,15 +197,40 @@ export declare function DialogBody({ className, ...rest }: DialogBodyProps): imp
 export declare namespace DialogBody {
     var displayName: string;
 }
+export type DialogSectionProps = Omit<React.HTMLAttributes<HTMLElement>, "title"> & {
+    /**
+     * The heading of the section; it names the `<section>`.
+     */
+    label: React.ReactNode;
+    /**
+     * One line of context under the heading (body-s).
+     */
+    description?: React.ReactNode;
+    ref?: React.Ref<HTMLElement>;
+};
+/**
+ * A titled group of the dialog body — what `Page.Section` is to a page: an `<h3>` (title-s, one
+ * level under the dialog's `<h2>` title) with an optional description and the dialog's `Actions`
+ * at the end of the heading row, then the content 16 below. Sections stand further apart than the
+ * plain blocks of the body.
+ */
+export declare function DialogSection({ label, description, className, children, ref, ...rest }: DialogSectionProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace DialogSection {
+    var displayName: string;
+}
 export type DialogFooterProps = React.HTMLAttributes<HTMLElement> & {
     /**
-     * `fill`: equal-width buttons in one row; `end`: auto width, at the end. Stacked on phones (viewport below 640 px) and in a dialog narrower than 360 px.
+     * `fill`: equal-width buttons in one row, wrapping rather than cutting a label; `end`: auto width, at the end. Stacked on phones (viewport below 640 px) and in a dialog narrower than 360 px.
      */
     layout?: DialogFooterLayout;
     ref?: React.Ref<HTMLElement>;
 };
-/** Actions in DOM order, primary last. Stacks full width when the dialog is narrower than 360px. */
-export declare function DialogFooter({ layout, className, ...rest }: DialogFooterProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Actions in DOM order, primary last. Stacks full width when the dialog is narrower than 360px.
+ * With a `Meta` the buttons move as one row: when the line runs short the status text goes above
+ * them first, so the buttons never split over two lines while there is room for them in one.
+ */
+export declare function DialogFooter({ layout, className, children, ...rest }: DialogFooterProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace DialogFooter {
     var displayName: string;
 }

package/dist/internal/swatch.d.ts

@@ -86,6 +86,11 @@ type SwatchChipProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> &
  * host's `--prime-icon-size`, with the faint inner edge; `aria-hidden` — the trigger is named.
  */
 export declare function SwatchChip({ value, className, ...rest }: SwatchChipProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * A typed hex color as `#rrggbb` (lowercase): `#` optional, 3 or 6 digits, spaces around ignored;
+ * `null` for anything else.
+ */
+export declare function parseHexColor(text: string): string | null;
 /** Case- and space-insensitive color comparison; `null` means "no color". */
 export declare function sameColor(a: string | null, b: string | null): boolean;
 /**

package/dist/internal/tokenDefaults.d.ts

@@ -6,6 +6,7 @@
  */
 export declare const TOKEN_DEFAULTS: {
     readonly "--prime-gallery-max-size": 360;
+    readonly "--prime-message-sticker": 160;
     readonly "--prime-message-video-note-box": 268;
     readonly "--prime-motion-duration-base": 380;
     readonly "--prime-motion-duration-fast": 230;

package/dist/layout/index.d.ts

@@ -2,7 +2,7 @@ export type { AppShellFooterProps, AppShellMainProps, AppShellNavProps, AppShell
 export { AppShell, useAppShellNav } from "./app-shell/AppShell";
 export type { BottomNavActionProps, BottomNavItemCountProps, BottomNavItemIconProps, BottomNavItemProps, BottomNavLabels, BottomNavRootProps, } from "./bottom-nav/BottomNav";
 export { BottomNav } from "./bottom-nav/BottomNav";
-export type { PageActionsProps, PageBackButtonProps, PageBodyProps, PageCellProps, PageCellRows, PageCellSpan, PageChipsProps, PageDescriptionProps, PageDetailProps, PageGridProps, PageHeaderProps, PageHeadingProps, PageLabels, PageListProps, PageMaxWidth, PageRootProps, PageSectionLayout, PageSectionProps, PageSplitProps, PageTitleProps, PageToolsProps, PageTopBarProps, } from "./page/Page";
+export type { PageActionsProps, PageBackButtonProps, PageBodyProps, PageCellProps, PageCellRows, PageCellSpan, PageChipsProps, PageDescriptionProps, PageDetailProps, PageGridProps, PageGuardProps, PageHeaderProps, PageHeadingProps, PageLabels, PageListProps, PageMaxWidth, PageRootProps, PageSectionProps, PageSplitProps, PageTitleProps, PageToolsProps, PageTopBarProps, } from "./page/Page";
 export { Page } from "./page/Page";
 export type { SidebarAccountProps, SidebarBrandLogoProps, SidebarBrandProps, SidebarContentProps, SidebarFooterProps, SidebarGroupProps, SidebarHeaderProps, SidebarItemActionProps, SidebarItemCountProps, SidebarItemIconProps, SidebarItemProps, SidebarItemShortcutProps, SidebarLabels, SidebarMode, SidebarRootProps, SidebarSubContentProps, SidebarSubProps, SidebarSubTriggerProps, SidebarToggleProps, } from "./sidebar/Sidebar";
 export { Sidebar, useSidebar } from "./sidebar/Sidebar";

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

@@ -6,6 +6,14 @@ export type PageLabels = {
     more: string;
     /** Name of `Page.BackButton` (back from the detail to the list on a narrow split). */
     back: string;
+    /** Title of the confirm `Page.Guard` opens when a person leaves a `dirty` page. */
+    leaveTitle: string;
+    /** Its description. */
+    leaveDescription: string;
+    /** Its confirm button: leave and lose the changes. */
+    leaveConfirm: string;
+    /** Its cancel button: stay on the page. */
+    leaveCancel: string;
 };
 export declare const PAGE_LABELS: PageLabels;
 type DivProps = React.HTMLAttributes<HTMLDivElement> & {
@@ -95,10 +103,14 @@ declare namespace PageTitle {
     var displayName: string;
 }
 export type PageDescriptionProps = React.HTMLAttributes<HTMLParagraphElement> & {
+    /**
+     * Its data is loading: a Skeleton keeps the line's place, so the title never moves; the data then fades in. Sets `aria-busy`.
+     */
+    loading?: boolean;
     ref?: React.Ref<HTMLParagraphElement>;
 };
 /** One line of context that carries data (a period, a count): truncates in the bar, wraps in the flow. */
-declare function PageDescription({ className, children, ...rest }: PageDescriptionProps): import("react/jsx-runtime").JSX.Element;
+declare function PageDescription({ loading, className, children, ...rest }: PageDescriptionProps): import("react/jsx-runtime").JSX.Element;
 declare namespace PageDescription {
     var displayName: string;
 }
@@ -118,9 +130,10 @@ export type PageToolsProps = DivProps;
 /**
  * The page's tools — sections, search and filter, view — as kit controls in the order written.
  * On the bar's first line each keeps its natural width; on a line of their own they fill it:
- * a search (`SmartFilter.Toolbar`, `Input.Root`) takes the room first, switchers share the rest
- * (a `SegmentedControl.Root` is `fullWidth` unless set), and they wrap when one line is not
- * enough. Named (`aria-label`), it is a `group`.
+ * a search (`SmartFilter.Toolbar`, `Input.Root`) takes the room first, switchers and fields share
+ * the rest (a `SegmentedControl.Root` and a `Datepicker.Root` are `fullWidth` unless set; a Select
+ * trigger fills by itself), and they wrap when one line is not enough. Named (`aria-label`), it is
+ * a `group`.
  */
 declare function PageTools({ className, children, ref, ...rest }: PageToolsProps): import("react/jsx-runtime").JSX.Element;
 declare namespace PageTools {
@@ -138,8 +151,6 @@ declare function PageBody({ className, ...rest }: PageBodyProps): import("react/
 declare namespace PageBody {
     var displayName: string;
 }
-/** Where the heading of a section stands: over its content or in a column beside it. */
-export type PageSectionLayout = "stack" | "aside";
 export type PageSectionProps = Omit<React.HTMLAttributes<HTMLElement>, "title"> & {
     /**
      * The visible heading (`h2`); it also names the section.
@@ -149,10 +160,6 @@ export type PageSectionProps = Omit<React.HTMLAttributes<HTMLElement>, "title">
      * One line of context under the heading, in secondary body-s.
      */
     description?: React.ReactNode;
-    /**
-     * `stack` — the heading over the content; `aside` — a ~16rem heading column beside it (a settings page), above it once the content would get narrower than 30rem.
-     */
-    layout?: PageSectionLayout;
     ref?: React.Ref<HTMLElement>;
 };
 /**
@@ -160,16 +167,18 @@ export type PageSectionProps = Omit<React.HTMLAttributes<HTMLElement>, "title">
  * at its end) over its content. Sections stand further apart than the plain blocks of the body,
  * so the air shows where a new topic starts.
  */
-declare function PageSection({ label, description, layout, className, children, ...rest }: PageSectionProps): import("react/jsx-runtime").JSX.Element;
+declare function PageSection({ label, description, className, children, ...rest }: PageSectionProps): import("react/jsx-runtime").JSX.Element;
 declare namespace PageSection {
     var displayName: string;
 }
 export type PageGridProps = DivProps;
 /**
  * The grid of the page's tiles (KPI cards, charts, panels): 12 columns, one gap on both axes.
- * Columns follow the grid's own width, so tiles fold on a narrow panel by themselves.
+ * Columns follow the grid's own width, so tiles fold on a narrow panel by themselves. A wide cell
+ * (span 7–11) written next to a narrow one (span 4–5) forms a pair that a mid-width grid lays out as
+ * 2/3 + 1/3, so the row keeps no hole.
  */
-declare function PageGrid({ className, ...rest }: PageGridProps): import("react/jsx-runtime").JSX.Element;
+declare function PageGrid({ className, children, ...rest }: PageGridProps): import("react/jsx-runtime").JSX.Element;
 declare namespace PageGrid {
     var displayName: string;
 }
@@ -187,11 +196,34 @@ export type PageCellProps = DivProps & {
      */
     rows?: PageCellRows;
 };
-/** One tile place in `Page.Grid`; its child (a Card, a ChartFrame) fills it. */
-declare function PageCell({ span, rows, className, ...rest }: PageCellProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * One tile place in `Page.Grid`; its child (a Card, a ChartFrame) fills it. A `Crossfade` child
+ * fills it too (`fill` unless set), so a tile that swaps its states keeps the row's height.
+ */
+declare function PageCell({ span, rows, className, children, ...rest }: PageCellProps): import("react/jsx-runtime").JSX.Element;
 declare namespace PageCell {
     var displayName: string;
 }
+export type PageGuardProps = {
+    /**
+     * A request runs (a save): a press on those items does nothing until it ends; the browser asks before the tab closes.
+     */
+    busy?: boolean;
+    /**
+     * Changes are not saved: a press on those items asks «leave without saving?»; its confirm (`labels.leaveConfirm`) repeats the press, its cancel keeps the page. The browser asks before the tab closes.
+     */
+    dirty?: boolean;
+};
+/**
+ * Holds the page from where its form state lives: put it anywhere inside the page. While it holds,
+ * a press on a `Sidebar.Item`, a `BottomNav.Item` or a `Breadcrumb.Item` link stops before it
+ * navigates — `busy` holds it, `dirty` asks «leave without saving?» and replays the press once the
+ * person agrees — and the browser asks before the tab closes or reloads. Renders only the confirm.
+ */
+declare function PageGuard({ busy, dirty }: PageGuardProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageGuard {
+    var displayName: string;
+}
 export type PageSplitProps = DivProps & {
     /**
      * The detail is open (a record is chosen), controlled. On a narrow split it takes the place of the list; on a wide one both panes stay.
@@ -255,6 +287,7 @@ export declare const Page: {
     Section: typeof PageSection;
     Grid: typeof PageGrid;
     Cell: typeof PageCell;
+    Guard: typeof PageGuard;
     Split: typeof PageSplit;
     List: typeof PageList;
     Detail: typeof PageDetail;

package/dist/skill/anti-slop.md

@@ -251,6 +251,11 @@ The same for one value in several units — one heading, the fields in a row, th
 | bars of dates drawn by hand, or a DataTable of start / end dates | `Gantt` |
 | a hand-made `<span>` hidden with CSS for screen readers | `<VisuallyHidden>` |
 | a `div` with `overflow: auto` | `ScrollContainer` (`edges`, `scrollbar="hidden"`, `snap`) |
+| `scroll-snap-type` on a strip of cards | `ScrollContainer snap` (`"mandatory"` only where each child fills most of the view) |
+| a flex row of Badges with its own gap | `Badge.Group` |
+| a Switch or a ⋯ button inside a list row, or the row rebuilt as a `div` to hold them | `List.ItemActions` beside the row's element |
+| a heading row (`Typography as="h3"` + buttons) over a group in a Drawer or a Modal | `Drawer.Section label` / `Modal.Section label` with `Drawer.Actions` / `Modal.Actions` |
+| Markdown turned into HTML (`dangerouslySetInnerHTML`, a Markdown library) | `RichText` |
 | an `<img>` with your own radius and loading box | `Thumbnail.Root` / `Avatar.Root` |
 | a lightbox, or a Modal with an `<img>` | `Gallery` (opens `MediaViewer` itself) or `MediaViewer` |
 | a `position: fixed` bottom tab bar | `BottomNav` in `AppShell.Footer` |
@@ -287,6 +292,29 @@ The same for one value in several units — one heading, the fields in a row, th
 />
 ```
 
+A bar above the table for a single button — the column chooser, an export — wastes a row and splits
+the page's actions ([controls of a table](composition.md#controls-of-a-table)):
+
+```tsx partial
+// bad — a toolbar that holds one control
+<DataTable columns={columns} rows={orders} toolbar={<Button.Root>Колонки</Button.Root>} />
+```
+
+```tsx good
+// good — the chooser sits in the header row; the page's own actions live in its top bar
+// declare: const orders: { id: string; client: string; total: number }[]
+<DataTable
+  columns={[
+    { id: "id", header: "Заказ", accessor: "id", hideable: false },
+    { id: "client", header: "Клиент", accessor: "client" },
+    { id: "total", header: "Сумма", accessor: "total", numeric: true },
+  ]}
+  rows={orders}
+  getRowKey={(row) => row.id}
+  columnsMenu
+/>
+```
+
 ## 7b. A top bar out of its groups
 
 The bar lays itself out only from its four groups ([the top bar](composition.md#the-top-bar)); a

package/dist/skill/api-contract.md

@@ -26,13 +26,13 @@ import type { ControlSize, PaletteColor, TextTone, Tone, Variant } from "prime-u
 | Other state | `x` / `defaultX` / `onXChange(x)` | Badge `pressed`; Button `pressed`; ChartFrame `hiddenSeries`; Chat `selected`, `search`; ChatList `search`; ColorPicker `format`; CommandMenu `search`; Composer `recordMode`; DataTable `hiddenColumns`, `page`, `sort`, `selected`, `expanded`, `collapsedGroups`; ExampleFrame `viewport`, `colorScheme`; Gallery `index`; Gantt `scale`; Kanban `columnOrder`; MediaViewer `index`; Message.Media `index`; Select `search`; SmartFilter `search`; VideoNote `playing`, `transcriptExpanded`; VoicePlayer `rate`, `playing`, `transcriptExpanded`; Sidebar `mode`. |
 | Checked | `checked` / `defaultChecked` / `onCheckedChange(checked)` | Checkbox, Dropdown.CheckboxItem, Switch, Thumbnail. |
 | Open | `open` / `defaultOpen` / `onOpenChange(open)` | ColorPresets, CommandMenu, ConfirmDialog, Datepicker, Drawer, Dropdown, Gallery, MediaViewer, Message.Media, Modal, Popover, Select, Sheet, TagSelect, Tooltip, Page.Split, Sidebar, Sidebar.Group, Sidebar.Sub. |
-| Dismiss | `closeOnOutsideClick` (default `true`), `closeOnEscape` (default `true`) | Both on every overlay that opens a layer: the dialogs, the floating panels, the panels of Select, TagSelect, Datepicker and ColorPresets, the off-canvas Sidebar and the reaction bar of a message. `ConfirmDialog` takes both with `closeOnOutsideClick` default `false` (Escape is held while `onConfirm` runs). Tooltip and Notification take neither. A form holds closing with `Modal.Guard` / `Drawer.Guard` / `Sheet.Guard`. |
+| Dismiss | `closeOnOutsideClick` (default `true`), `closeOnEscape` (default `true`) | Both on every overlay that opens a layer: the dialogs, the floating panels, the panels of Select, TagSelect, Datepicker and ColorPresets, the `suggestions` list of Input, the off-canvas Sidebar and the reaction bar of a message. `ConfirmDialog` takes both with `closeOnOutsideClick` default `false` (Escape is held while `onConfirm` runs). Tooltip and Notification take neither. A form holds closing with `Modal.Guard` / `Drawer.Guard` / `Sheet.Guard`. |
 | Selection mode | `multiple` | One vs many (Select, Accordion) — never `type`. `mode` only for structurally different values (Datepicker `single \| range`). |
 | Status words | `selected`, `current`, `pressed` | `current` marks a navigation location (`Sidebar.Item`, `Breadcrumb.Item`) and sets `aria-current`; `pressed` a toggle button. |
 | Flags | `disabled`, `readOnly`, `required`, `optional`, `loading`, `fullWidth` | Same names everywhere. |
 | Focus ring | `focusRing` (default `true`) | Fields only; `false` only where focus is obvious otherwise. |
 | System strings | `labels?: Partial<XLabels>` | aria labels, counters, default texts; Russian defaults; values as `{token}` templates. Visible content goes in children or props. |
-| Structure | `X.Root` + `X.Part` | Only for components with parts. Leaves are single exports: `Typography`, `Kbd`, `Divider`, `Spinner`, `Skeleton`, `Crossfade`, `LinkButton`, `NativeSelect`, `DigitInput`, `Slider`, `TagSelect`, `ColorSwatches`, `CodeBlock`, `ProgressBar`, `ProgressCircle`, `Sparkline`, `Pagination`, `DataTable`, `Gantt`, `Fieldset`, `VisuallyHidden`, `ColorField`, `ExampleFrame`, `VoicePlayer`, `VideoNote`, `ScrollContainer`, `Gallery`, `MediaViewer`. This is the one list; other files link here. A group of roots is `X.Group` (`Radio.Group`, `Avatar.Group`). |
+| Structure | `X.Root` + `X.Part` | Only for components with parts. Leaves are single exports: `Typography`, `Kbd`, `Divider`, `Spinner`, `Skeleton`, `Crossfade`, `LinkButton`, `NativeSelect`, `DigitInput`, `Slider`, `TagSelect`, `ColorSwatches`, `CodeBlock`, `ProgressBar`, `ProgressCircle`, `Sparkline`, `Pagination`, `DataTable`, `Gantt`, `Fieldset`, `VisuallyHidden`, `ColorField`, `ExampleFrame`, `VoicePlayer`, `VideoNote`, `ScrollContainer`, `Gallery`, `MediaViewer`, `RichText`. This is the one list; other files link here. A group of roots is `X.Group` (`Radio.Group`, `Avatar.Group`, `Badge.Group`). |
 | Slots | `X.Trigger`, `X.Close`, `X.Confirm`, `X.Anchor` | Your own button inside, exactly one element child; the slot renders no element and takes no `className` — style the child. A trigger the kit draws itself (`Select.Trigger`, `Accordion.Trigger`) is a real part with `className`. |
 | Icons in parts | `X.Icon`, `X.ItemIcon` | `Button.Icon`, `Input.Icon`, `Sidebar.ItemIcon`, `Dropdown.ItemIcon`… — never an `icon` prop on a component. Only data arrays (`notify()`, `options`) carry `icon: ReactNode`. |
 | DOM state | `data-size`, `data-variant`, `data-tone`, `data-color`, `data-invalid`, `data-disabled`, `data-loading`, `data-state` | Style your wrappers from these, not from class names of kit internals. |
@@ -85,7 +85,7 @@ export function PeriodFilter() {
   resolving. The async events: Input / Textarea `onCommit`, ConfirmDialog `onConfirm`,
   `EmptyPage.RetryButton` and CommandMenu `onRetry`, Button `onConfirm` (`holdToConfirm`), Slider
   `onCommit`, DigitInput `onComplete`, Tabs `onRemove`, Switch `onCheckedChange`, Badge `onRemove`,
-  FileUpload `onValueChange`, TagSelect `onCreate` / `onOptionUpdate` / `onOptionDelete`, DataTable
+  FileUpload and FieldList `onValueChange`, TagSelect `onCreate` / `onOptionUpdate` / `onOptionDelete`, DataTable
   and Dnd `onReorder`, Kanban `onValueChange` / `onColumnOrderChange`, Gantt `onBarChange` /
   `onBarCreate`, Composer `onSend` / `onSendVoice` / `onSendVideoNote`, `Message.Root`
   `onReactionToggle` and `onRetry`, the `onRetry` / `onCancel` of `Message.File`, the
@@ -118,8 +118,11 @@ export function PeriodFilter() {
 - Checkbox, Switch and Radio: [choice controls](#choice-controls) below.
 - `required` → red `*` after the label + native `required`. `optional` → muted «необязательно».
 - Placeholder is an example (`name@company.ru`), never the label.
-- Units and prefixes in affixes are hidden from screen readers — put the meaning into the label or hint
-  too («Бюджет, ₽», «Адрес: prime.app/p/…»).
+- `hintTone` (`success` · `warning` · `danger`) colors the `hint` of a field by the status of its
+  value («Осталось 12 дней» in `warning`); a lone `Hint.Root` takes `tone`. The words carry the
+  status and the color only repeats it; a validation problem is `error`, which replaces the hint.
+- `Input.Affix` and `Input.InlineAffix` describe the input for screen readers (`aria-describedby`),
+  so the label never repeats a unit or a prefix ([a unit lives in one place](ux.md#3-label-economy)).
 - Mark the minority: when most fields are required, mark only the optional ones (`optional`); when most
   are optional, mark the required ones; on a tie mark the required ones. Validate in code either way.
 - Show `error` after the user leaves the field or on submit, not while typing the first character.
@@ -249,7 +252,8 @@ place (a `Banner` for the page; for a region `EmptyPage tone="danger"` — it an
   фильтры»), and the same action keeps the same variant in the header, toolbars and menus. If «Отмена»
   would clash with the action itself («Отменить заказ»), use an unambiguous label («Не отменять»).
 - A control that navigates is a link: `LinkButton href`, `Button.Root asChild` with `<a>` / router
-  `Link`, `Sidebar.Item href` or `asChild`. Never `onClick={() => location.assign(…)}`.
+  `Link`, `Sidebar.Item` / `Breadcrumb.Item` / `List.Item` / `ChatList.Item` `href` or `asChild`. Never
+  `onClick={() => location.assign(…)}`.
 
 ## Destructive actions
 
@@ -291,7 +295,10 @@ export function DeleteProject({ onDelete }: { onDelete: () => Promise<void> }) {
 
 Leaving a form with unsaved changes is the same contract: `Modal.Guard` / `Drawer.Guard` inside the
 content with `dirty` (any dismiss asks «Не сохранять изменения?») and `busy` (nothing closes it while
-it saves).
+it saves); while either holds, the browser also asks before the tab closes or reloads. A form that is the whole page takes `Page.Guard` (`dirty`, `busy`) inside the page: it
+holds a press on `Sidebar.Item`, `BottomNav.Item` and `Breadcrumb.Item` links — router links
+included — and the browser's own close or reload; never a `beforeunload` or a ConfirmDialog on a
+crumb of your own.
 
 ## Providers and helpers