prime-ui-kit 0.20.0 → 0.21.0

package/dist/index.js

@@ -88,7 +88,7 @@ import {
   useSidebar,
   useTokenValue,
   useUploadQueue
-} from "./chunks/chunk-W6EGTNG6.js";
+} from "./chunks/chunk-S4H2ZKWJ.js";
 import {
   Avatar,
   Badge,
@@ -123,7 +123,7 @@ import {
   tierMappings,
   tones,
   variants
-} from "./chunks/chunk-3PY52JP3.js";
+} from "./chunks/chunk-S27VR4ON.js";
 import {
   ControlSizeProvider,
   useOptionalControlSize

package/dist/internal/RegionSwap.d.ts

@@ -2,7 +2,8 @@ import * as React from "react";
 type RegionSwapProps = React.HTMLAttributes<HTMLDivElement> & {
     /**
      * Key of what the region shows (`"loading"`, `"ready"`, `"empty"`, `"error"`, a record id). A new
-     * value swaps the old content for the new one; the same value updates in place.
+     * value swaps the old content for the new one; the same value updates in place. `"loading"` is
+     * the loading state: a swap into or out of it never glides the height.
      */
     state: string | number;
     /** The region takes its parent's height and every state fills it; the height never glides. */
@@ -17,25 +18,32 @@ type RegionSwapProps = React.HTMLAttributes<HTMLDivElement> & {
 /**
  * The region swap of the kit (foundation §7 rule 8): a region that changes what it shows (loading /
  * data / empty / error, another record) cross-fades — the old content stays as a leaving layer over
- * the new one and fades out (`swapMotion.swapOut`, `fast` · exit) while the new one fades in
- * (`swapMotion.swapIn`, `base` · enter) — and glides from the old height to the new one, the
- * "height glide" exception of foundation §7 rule 5. Nothing moves on the first render. Focus in
- * the leaving state moves into the new one (`handoffFocus`). Under reduced motion the old state
- * goes at once and the height jumps; the new one still fades in (rule 12). A region with nothing
- * to show takes no room. `Crossfade` is this region, public.
+ * the new one and fades out (`swapMotion.swapOut`, `fast` · exit) while the new one fades in.
+ * Between settled states (data / empty / error, another record) the new one fades in on `base`
+ * (`swapMotion.swapIn`) and the region glides from the old height to the new one, the "height
+ * glide" exception of foundation §7 rule 5. A swap into or out of `"loading"` is a load: the
+ * Skeleton and the data replace each other in place — the height settles in one frame (the old
+ * layer clipped to it) and the fade is short (`swapMotion.settleIn`, `fast`). Nothing moves on the
+ * first render. Focus in the leaving state moves into the new one (`handoffFocus`). Under reduced
+ * motion the old state goes at once and the height jumps; the new one still fades in (rule 12).
+ * A region with nothing to show takes no room. `Crossfade` is this region, public.
  */
 export declare function RegionSwap({ state, fill, onSwap, children, className, ref, ...rest }: RegionSwapProps): import("react/jsx-runtime").JSX.Element;
 type SwapIn = {
     /** Key of the swapped content: it remounts under a new state. `undefined` before the first swap. */
     key: string | undefined;
-    /** The fade-in of the new state (`swapMotion.swapIn`); `undefined` before the first swap. */
+    /**
+     * The fade-in of the new state: `swapMotion.settleIn` into or out of `"loading"`, else
+     * `swapMotion.swapIn`; `undefined` before the first swap.
+     */
     className: string | undefined;
 };
 /**
  * The region swap in place, for a host whose states cannot be laid over each other: a table body
  * (rows leave the table's layout when positioned) or the phrasing content of a button. The new
- * state remounts under `key` and fades in through `className`; nothing fades out and the height
- * does not glide. Nothing moves on the first render. Every other region is a `RegionSwap`.
+ * state remounts under `key` and fades in through `className` (short into or out of `"loading"`);
+ * nothing fades out and the height does not glide. Nothing moves on the first render. Every other
+ * region is a `RegionSwap`.
  */
 export declare function useSwapIn(state: string | number): SwapIn;
 export {};

package/dist/internal/RollingNumber.d.ts

@@ -5,11 +5,13 @@ type RollingNumberProps = {
 };
 /**
  * A number whose digits roll to their new values column by column, like an odometer (foundation §7
- * rule 8: counters ease, they do not flip). The DOM holds the real digits (text, copy, assistive
- * tech and a page without CSS read the value); each digit column draws the 0–9 strip in a
- * pseudo-element. Columns are keyed from the right, so an unchanged digit stays still and a new
- * leading digit appears without rolling. A value that changes by itself every frame (a running
- * percentage) stays plain tabular text: rolling there is noise.
+ * rule 8: counters ease, they do not flip). The DOM holds the value as one run of text — copy, a
+ * page without CSS and assistive tech read it as one word («12», never «1 2»: separate boxes per
+ * digit make a browser split the name) — and an aria-hidden row of columns, with no text of its own,
+ * paints it: each digit column draws the 0–9 strip in a pseudo-element. Columns are keyed from the
+ * right, so an unchanged digit stays still and a new leading digit appears without rolling. A value
+ * that changes by itself every frame (a running percentage) stays plain tabular text: rolling there
+ * is noise.
  */
 export declare function RollingNumber({ children, className }: RollingNumberProps): import("react/jsx-runtime").JSX.Element;
 /**

package/dist/internal/ToolRow.d.ts

@@ -8,6 +8,12 @@ type ToolGroupProps = DivProps;
  * title before its zoom): they wrap inside it.
  */
 export declare function ToolGroup({ className, ...rest }: ToolGroupProps): import("react/jsx-runtime").JSX.Element;
+type ToolCellProps = DivProps;
+/**
+ * A cell the host draws itself, standing in the row as given: a part that comes and goes takes its
+ * presence (`usePartPresence`) on the cell, so the row closes up when it leaves. A fixed cell.
+ */
+export declare function ToolCell({ className, ...rest }: ToolCellProps): import("react/jsx-runtime").JSX.Element;
 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;

package/dist/internal/mediaSlot.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The media slot of a leading mark (`Modal.Icon`, `Drawer.Icon`, `Sheet.Icon`, `Card.Icon`): a box
+ * that is a filled glyph tile, unless the record's picture stands in it. A person or an object
+ * stands for itself, so an `Avatar.Root` or a `Thumbnail.Root` anywhere inside the slot — a direct
+ * child, under a wrapper, or rendered by the consumer's own component — reports itself and takes the
+ * slot's size, the size of the tile it replaces (40): an avatar `l`, a thumbnail `m` (its height).
+ * The report runs in a layout effect, so the tile never paints around a picture.
+ */
+import * as React from "react";
+import type { ControlSize } from "./states";
+/** The sizes a picture takes in the slot: the 40 box of the glyph tile. */
+declare const MEDIA_SLOT_SIZE: {
+    readonly avatar: "l";
+    readonly thumbnail: "m";
+};
+/**
+ * The host side: wraps the slot's children and tells whether a picture stands in it. Children
+ * render inside `provide(…)`.
+ */
+export declare function useMediaSlotHost(): {
+    media: boolean;
+    provide: (children: React.ReactNode) => React.ReactElement;
+};
+/**
+ * The picture side (Avatar.Root, Thumbnail.Root): inside a media slot it reports itself and
+ * returns the size it must take there; outside one, `undefined`.
+ */
+export declare function useMediaSlotSize(kind: keyof typeof MEDIA_SLOT_SIZE): ControlSize | undefined;
+export {};

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

@@ -7,6 +7,7 @@
 import * as React from "react";
 import { type SlotPartProps } from "../slot";
 import type { ControlSize, Tone } from "../states";
+import type { FocusStart } from "./focus";
 /** System strings of a dialog: its close button and the built-in «discard changes?» confirm. */
 export type DialogLabels = {
     /** `aria-label` of the header close button. */
@@ -116,6 +117,8 @@ type DialogPanelProps = React.HTMLAttributes<HTMLDivElement> & {
     enterConfirm?: boolean;
     /** The tier of the controls inside (Modal: `m`); without it they keep the surrounding tier. */
     controlSize?: ControlSize;
+    /** Where focus lands on open (`useModalLayer`): the first tab stop, or the panel (Drawer). */
+    focusStart?: FocusStart;
     ref?: React.Ref<HTMLDivElement>;
 };
 /**
@@ -131,19 +134,32 @@ export type DialogIconProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "child
      */
     tone?: Tone;
     /**
-     * An `Icon` (sized to the m icon), or the record's picture: an `Avatar.Root` (sized to the tile) or a `Thumbnail.Root`.
+     * An `Icon` (sized to the m icon), or the record's picture: an `Avatar.Root` (size `l`) or a `Thumbnail.Root` (size `m`), set by the slot.
      */
     children: React.ReactNode;
     ref?: React.Ref<HTMLSpanElement>;
 };
+/**
+ * The leading mark: a glyph on the tone tile, or the record's picture (an `Avatar.Root` or a
+ * `Thumbnail.Root` anywhere inside, internal/mediaSlot) with no tile, at the tile's 40 box.
+ */
 export declare function DialogIcon({ tone, children, className, ...rest }: DialogIconProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace DialogIcon {
     var displayName: string;
 }
 export type DialogTitleProps = Omit<React.HTMLAttributes<HTMLHeadingElement>, "id"> & {
+    /**
+     * The name loads (a record opened by a link): a `Skeleton` holds the title line and `aria-busy` is set, so the header never moves; the name fades in.
+     */
+    loading?: boolean;
     ref?: React.Ref<HTMLHeadingElement>;
 };
-export declare function DialogTitle({ className, ...rest }: DialogTitleProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The dialog's name. While it loads (`loading`: a record opened by a link knows only its id) a
+ * Skeleton holds the title line, so the header never moves when the name arrives; the name then
+ * fades in under the same element.
+ */
+export declare function DialogTitle({ loading, className, children, ...rest }: DialogTitleProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace DialogTitle {
     var displayName: string;
 }
@@ -157,6 +173,9 @@ export type DialogDescriptionProps = Omit<React.HTMLAttributes<HTMLParagraphElem
 /**
  * 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.
+ * The record's status badges lead it: a Badge inside takes chip tier `s` (one step under the `m`
+ * it provides), the height of the line, and the badges stand before the text whatever the order
+ * they are written in.
  */
 export declare function DialogDescription({ loading, className, children, ...rest }: DialogDescriptionProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace DialogDescription {
@@ -182,8 +201,11 @@ export type DialogActionsProps = React.HTMLAttributes<HTMLDivElement> & {
     ref?: React.Ref<HTMLDivElement>;
 };
 /**
- * A row of controls at the end of the header, before the close button: a status Badge, a ⋯
- * Dropdown, an icon button. Controls inside take tier `s`, the close button's tier.
+ * 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.
  */
 export declare function DialogActions({ className, children, ...rest }: DialogActionsProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace DialogActions {
@@ -227,8 +249,10 @@ export type DialogFooterProps = React.HTMLAttributes<HTMLElement> & {
 };
 /**
  * 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.
+ * An `Actions` holds the start group (an action apart from the main pair) and a `Meta` the status
+ * text, both at the start; the buttons then move as one row at the end: when the line runs short
+ * the start goes above them first, so the buttons never split over two lines while there is room
+ * for them in one. Stacked, the start comes first and the primary stays last.
  */
 export declare function DialogFooter({ layout, className, children, ...rest }: DialogFooterProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace DialogFooter {

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

@@ -5,13 +5,20 @@ export declare function getFocusable(container: HTMLElement): HTMLElement[];
  * reaches it without an added `tabindex`.
  */
 export declare function hasNativeTabStop(el: HTMLElement): boolean;
+/**
+ * Where focus lands in a layer that just opened: `tabStop` — its first tab stop; `container` — the
+ * layer itself (a record panel: the person hears its name and description, and Tab goes on to the
+ * first control).
+ */
+export type FocusStart = "tabStop" | "container";
 /**
  * Moves focus into a layer that just opened, unless focus is already inside (a child `autoFocus`):
  * the first match of `first` (a menu's first enabled item, which is no tab stop of its own), else
- * `[data-autofocus]`, else the first tab stop, else the container itself. `quiet` — a pointer
- * opened the layer: focus lands without the focus ring until the person turns to the keyboard.
+ * `[data-autofocus]`, else per `start` the first tab stop, else the container itself. `quiet` — a
+ * pointer opened the layer: focus lands without the focus ring until the person turns to the
+ * keyboard.
  */
-export declare function focusInto(container: HTMLElement, first?: string, quiet?: boolean): void;
+export declare function focusInto(container: HTMLElement, first?: string, quiet?: boolean, start?: FocusStart): void;
 /**
  * Focuses `el` when it is still in the document. `quiet` — the layer was opened with a pointer:
  * focus returns without the focus ring, also when a key (Escape) closed the layer; the next key
@@ -35,6 +42,14 @@ export declare function handoffFocus(leaving: Element | null | undefined, next:
  * `el` do not count.
  */
 export declare function tabStopBeside(el: Element): HTMLElement | null;
+/**
+ * Whether focus on `el` came from the keyboard, so a part that shows on focus (a tooltip) may
+ * show: the last input was a key (or nothing yet, as `:focus-visible` has it), and `el` is not
+ * focused quietly (a layer a pointer opened or closed). Focus a click causes, or a layer moves after
+ * a click, is no keyboard focus — read from the input itself, since `:focus-visible` is not
+ * reported everywhere (jsdom) and a quiet focus keeps it until the next key.
+ */
+export declare function focusFromKeyboard(el: Element): boolean;
 /**
  * Who opened a layer, to return focus to on close: `element` — the control (or the focused
  * element); `target` — the exact element a press landed on (a picture inside a link, for a layer

package/dist/internal/partPresence.d.ts

@@ -1,4 +1,21 @@
 import * as React from "react";
+type EnterOnAppear<E extends Element> = {
+    /** On the node that appears (the one its host inserts); it may differ from the one that moves. */
+    ref: React.RefCallback<E>;
+    /** Join `enterMotion.*` while true. */
+    entering: boolean;
+};
+/**
+ * Whether a part plays its enter motion (foundation §1 rule 7, §7): only when it appears after its
+ * host is on screen — `active` turns on after the first render (an error, a tab opened again), or
+ * its node is inserted on its own into a host already shown (a banner after an event, a bar that
+ * selection brings, a keyed excerpt that replaces the last). A part that mounts together with its
+ * page, region or overlay is just there. Spread `ref` on the node the host inserts:
+ *
+ *   const appear = useEnterOnAppear<HTMLDivElement>();
+ *   <div ref={useMergedRefs(appear.ref, ref)} className={cx(appear.entering && enterMotion.enter)} />
+ */
+export declare function useEnterOnAppear<E extends Element>(active?: boolean): EnterOnAppear<E>;
 type PartPresenceOptions = {
     /**
      * Whether the host shows the part now. It enters when this turns on after the host's first
@@ -18,8 +35,8 @@ type PartPresence<E extends HTMLElement> = {
  * Presence of an optional part that comes and goes while its host stays (a clear button, a chip
  * row, a remove segment, a change badge): it rises in when it appears (`enterMotion`; the host
  * tunes it with `--enter-*`) and closes up in place when it goes (`leaveInPlace`), so the parts
- * around it glide instead of jumping. Called by the host that owns the condition; spread the
- * result on the part:
+ * around it glide instead of jumping. Called by the host that owns the condition; spread the result
+ * on the part:
  *
  *   const clear = usePartPresence<HTMLButtonElement>({ present: hasValue, axis: "inline" });
  *   {hasValue ? <button ref={clear.ref} className={cx(styles.clear, clear.className)} /> : null}

package/dist/layout/sidebar/Sidebar.d.ts

@@ -374,8 +374,9 @@ export type SidebarAccountProps = Omit<React.ComponentPropsWithoutRef<"button">,
     ref?: React.Ref<HTMLButtonElement>;
 };
 /**
- * The signed-in person at the bottom of the rail: avatar, name, a muted line and a chevron. A
- * button, so it can be a `Dropdown.Trigger` child; in compact mode only the avatar stays.
+ * The signed-in person at the bottom of the rail: avatar, name, a muted line and, as a menu
+ * trigger, a chevron. A button, so it can be a `Dropdown.Trigger` child; in compact mode only the
+ * avatar stays.
  */
 declare function SidebarAccount({ description, className, children, type, ...rest }: SidebarAccountProps): import("react/jsx-runtime").JSX.Element;
 declare namespace SidebarAccount {

package/dist/skill/anti-slop.md

@@ -242,8 +242,8 @@ The same for one value in several units — one heading, the fields in a row, th
 | `<Button.Root onClick={() => location.assign(url)}>` | `<Button.Root asChild><a href={url}>…</a></Button.Root>` or `LinkButton` |
 | a hand-built spinner, shimmer, grey placeholder box or «Loading…» text | `loading` on Button / Select / DataTable; a region: `Skeleton` of its content inside `Crossfade`; no shape to hold: `Spinner` |
 | `{loading ? <Spinner /> : <List />}` — a state that flips | `<Crossfade state={status}>` around the region, `Skeleton` while loading |
-| a search Input + a row of filter Selects above a table | `SmartFilter` next to the table it filters: its toolbar and chips in the table's `toolbar` / `toolbarChips` beside KPI cards, in `Page.Tools` / `Page.Chips` when the table is the page ([where the filters go](composition.md#where-the-filters-go)) |
-| the table's search, filter or «Колонки» in the page's bar above KPI cards | the bar keeps the title, the period that drives every block and the primary action; the table's tools go in its own `toolbar` ([where the filters go](composition.md#where-the-filters-go)) |
+| a search Input + a row of filter Selects above a table | `SmartFilter` with the table it filters: its toolbar and chips in the table's `toolbar` / `toolbarChips` on every page ([where the filters go](composition.md#where-the-filters-go)) |
+| the table's search, filter or «Колонки» in the page's bar, the page that is only the table included | the bar keeps the title, the sections, the view, a period that drives every block and the buttons; the table's tools go in its own `toolbar` ([where the filters go](composition.md#where-the-filters-go)) |
 | a grid of «label: value» text pairs for one record | `DescriptionList.Root` + `DescriptionList.Item` |
 | a Modal hand-built as «Удалить?» with your own pending flag | `ConfirmDialog.Root` with an async `onConfirm` |
 | a `<fieldset>` reset by hand, or `disabled` on every field while saving | `<Fieldset label disabled={saving}>` |
@@ -310,40 +310,38 @@ cell in every row:
 ```
 
 ```tsx good
-// good — a page that is the table, no row actions: the chooser is in the bar, on the state the table reads
+// good — no row actions: the chooser stands beside the table's search, on the state the table reads
+// declare: const FIELDS: Parameters<typeof SmartFilter.Root>[0]["fields"]
 // declare: const orders: { id: string; client: string; total: number }[]
 // declare: const hidden: string[]
 // declare: const setHidden: (hidden: string[]) => void
-<Page.Root>
-  <Page.TopBar>
-    <Page.Heading>
-      <Page.Title>Заказы</Page.Title>
-    </Page.Heading>
-    <Page.Tools>
-      <DataTableColumnsMenu
-        columns={[
-          { id: "id", header: "Заказ", accessor: "id", hideable: false },
-          { id: "client", header: "Клиент", accessor: "client" },
-          { id: "total", header: "Сумма", accessor: "total", numeric: true },
-        ]}
-        hiddenColumns={hidden}
-        onHiddenColumnsChange={setHidden}
-      />
-    </Page.Tools>
-  </Page.TopBar>
-  <Page.Body>
-    <DataTable
-      columns={[
-        { id: "id", header: "Заказ", accessor: "id", hideable: false },
-        { id: "client", header: "Клиент", accessor: "client" },
-        { id: "total", header: "Сумма", accessor: "total", numeric: true },
-      ]}
-      hiddenColumns={hidden}
-      rows={orders}
-      getRowKey={(row) => row.id}
-    />
-  </Page.Body>
-</Page.Root>
+<SmartFilter.Root fields={FIELDS}>
+  <DataTable
+    columns={[
+      { id: "id", header: "Заказ", accessor: "id", hideable: false },
+      { id: "client", header: "Клиент", accessor: "client" },
+      { id: "total", header: "Сумма", accessor: "total", numeric: true },
+    ]}
+    hiddenColumns={hidden}
+    rows={orders}
+    getRowKey={(row) => row.id}
+    toolbar={
+      <>
+        <SmartFilter.Toolbar />
+        <DataTableColumnsMenu
+          columns={[
+            { id: "id", header: "Заказ", accessor: "id", hideable: false },
+            { id: "client", header: "Клиент", accessor: "client" },
+            { id: "total", header: "Сумма", accessor: "total", numeric: true },
+          ]}
+          hiddenColumns={hidden}
+          onHiddenColumnsChange={setHidden}
+        />
+      </>
+    }
+    toolbarChips={<SmartFilter.Chips />}
+  />
+</SmartFilter.Root>
 ```
 
 ## 7b. A top bar out of its groups
@@ -409,13 +407,13 @@ Buttons in two places, buttons with only text:
 </Page.Actions>
 ```
 
-`SmartFilter.Root` inside the bar:
+`SmartFilter.Root` inside the bar of a page whose filter narrows several views (a board and its list):
 
 ```tsx partial
 // bad — the filter's state wraps one group, its chips land outside it
 <Page.TopBar>
   <SmartFilter.Root fields={FIELDS}>
-    <Page.Tools aria-label="Заказы">
+    <Page.Tools aria-label="Сделки">
       <SmartFilter.Toolbar />
     </Page.Tools>
   </SmartFilter.Root>
@@ -429,9 +427,9 @@ Buttons in two places, buttons with only text:
   <Page.Root>
     <Page.TopBar>
       <Page.Heading>
-        <Page.Title>Заказы</Page.Title>
+        <Page.Title>Сделки</Page.Title>
       </Page.Heading>
-      <Page.Tools aria-label="Заказы">
+      <Page.Tools aria-label="Сделки">
         <SmartFilter.Toolbar />
       </Page.Tools>
       <Page.Chips>

package/dist/skill/api-contract.md

@@ -25,7 +25,7 @@ import type { ControlSize, PaletteColor, TextTone, Tone, Variant } from "prime-u
 | Text value | native `value` / `onChange` + `onValueChange(string)` | Input (`Input.Field`), Textarea. |
 | 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`, `columnOrder`, `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. |
+| Open | `open` / `defaultOpen` / `onOpenChange(open)` | ColorPresets, CommandMenu, Composer.Keyboard, 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 `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. |
@@ -168,6 +168,54 @@ export function InviteForm() {
 (`.form { display: grid; gap: var(--prime-space-5); }`.) A full create form with groups, validation,
 loading and a toast: [the Drawer screen](reference/components/drawer/examples/screen.tsx).
 
+### Field outcomes: a mark for success, words for a problem
+
+A field answers a check in one of two ways. Success is quiet; a problem is said.
+
+- **A confirmed value is a mark.** A repeat that matches, a code that passed, a free address: `valid`
+  on the root draws a check at the field's end and says it to a screen reader — no words under the
+  field. Never a `hint` with `hintTone="success"` that writes «Пароли совпадают»: the person reads a
+  sentence to learn that nothing is wrong. `hintTone` stays for the status of a value that is not a
+  check (a deadline that nears).
+- **A problem is words.** `error` says what is wrong and how to fix it, under the field it concerns.
+  Red rings and a shake alone leave the person guessing.
+- **A policy is enforced, not shown.** A new password is `strength` with `minStrength`: below the
+  level the form refuses to submit and says why, the `hint` names the requirement in words («От 10
+  символов, буквы и цифры»), and the server checks the same rule. A meter alone lets the weak
+  password through ([password-policy.tsx](reference/components/input/examples/password-policy.tsx)).
+- **A refused sign-in** marks the e-mail `invalid` and puts the reason on the password as its `error`
+  («Неверная почта или пароль») — one sentence that names neither field as the culprit, no Banner
+  over the form ([LoginForm](reference/components/login-form/COMPONENT.md)).
+
+```tsx partial
+// bad — a meter that lets anything through and a green sentence for a match
+<Input.Root label="Новый пароль" strength>…</Input.Root>
+<Input.Root label="Повторите пароль" hint="Пароли совпадают" hintTone="success">…</Input.Root>
+```
+
+```tsx good
+// good — the policy stops the submit, the match is a check, a mismatch is words
+// declare: const matches: boolean
+// declare: const mismatch: boolean
+<>
+  <Input.Root label="Новый пароль" strength minStrength={3} hint="От 10 символов, буквы и цифры">
+    <Input.Wrapper>
+      <Input.Field type="password" autoComplete="new-password" />
+      <Input.RevealButton />
+    </Input.Wrapper>
+  </Input.Root>
+  <Input.Root
+    label="Повторите пароль"
+    valid={matches}
+    error={mismatch ? "Пароли не совпадают" : undefined}
+  >
+    <Input.Wrapper>
+      <Input.Field type="password" autoComplete="new-password" />
+    </Input.Wrapper>
+  </Input.Root>
+</>
+```
+
 ### Choice controls
 
 Checkbox, Switch and Radio: the root renders the `<label>` with the input and the visible text is
@@ -263,7 +311,7 @@ A standalone destructive action that is easy to redo by hand is `Button.Root hol
 action in `onConfirm` ([the recipe](motion.md#5-recipes)).
 
 `tone="danger"`. A standalone trigger that opens a confirm (danger zone) is `variant="outline"`; inside
-a bar of other actions (DataTable bulk bar, card actions) it is `soft`; in a Dropdown it is the last item
+a bar of other actions (card actions) it is `soft`; in a Dropdown it is the last item
 with `tone="danger"`; an inline remove in a media or file row is `ghost`. The confirm itself is
 [ConfirmDialog](reference/components/confirm-dialog/COMPONENT.md) — never a hand-built Modal: it is a
 Modal `s` with a solid danger confirm (`tone="accent"` for an outward action that destroys nothing, like