prime-ui-kit 0.14.0 → 0.16.0

package/dist/index.js

@@ -70,6 +70,7 @@ import {
   chartColors,
   datepickerPresets,
   formatChatTime,
+  formatDateValue,
   formatDatepickerValue,
   formatFileSize,
   formatMessageDate,
@@ -82,11 +83,12 @@ import {
   moveBefore,
   resolveSmartFilterValues,
   suspendTransitions,
+  useAppShellNav,
   useNotifications,
   useSidebar,
   useTokenValue,
   useUploadQueue
-} from "./chunks/chunk-SYEX7OVT.js";
+} from "./chunks/chunk-6TPHKCUJ.js";
 import {
   Avatar,
   Badge,
@@ -100,6 +102,7 @@ import {
   Icon,
   Input,
   Label,
+  OVERLAY_CONTENT_SIZE,
   Popover,
   ProgressBar,
   ScrollContainer,
@@ -109,6 +112,7 @@ import {
   Thumbnail,
   Tooltip,
   VisuallyHidden,
+  compactTier,
   controlSizes,
   createIcon,
   dataStates,
@@ -116,13 +120,14 @@ import {
   paletteColors,
   stepDown,
   textTones,
+  tierMappings,
   tones,
   variants
-} from "./chunks/chunk-WXKRUVSE.js";
+} from "./chunks/chunk-4PSQ64S4.js";
 import {
   ControlSizeProvider,
   useOptionalControlSize
-} from "./chunks/chunk-Q3BFRQHZ.js";
+} from "./chunks/chunk-U3Q2I3MY.js";
 export {
   Accordion,
   AppHeader,
@@ -179,6 +184,7 @@ export {
   NativeSelect,
   NotificationCard,
   NotificationProvider,
+  OVERLAY_CONTENT_SIZE,
   PageContent,
   PageToolbar,
   Pagination,
@@ -213,11 +219,13 @@ export {
   applyTheme,
   celebrate,
   chartColors,
+  compactTier,
   controlSizes,
   createIcon,
   dataStates,
   datepickerPresets,
   formatChatTime,
+  formatDateValue,
   formatDatepickerValue,
   formatFileSize,
   formatMessageDate,
@@ -234,7 +242,9 @@ export {
   stepDown,
   suspendTransitions,
   textTones,
+  tierMappings,
   tones,
+  useAppShellNav,
   useNotifications,
   useOptionalControlSize,
   useSidebar,

package/dist/internal/AnchorRectContext.d.ts

@@ -1,6 +1,6 @@
 import * as React from "react";
 /** The box a floating layer is placed against (viewport px). */
-export type AnchorRect = Pick<DOMRectReadOnly, "top" | "left" | "right" | "bottom" | "width" | "height">;
+type AnchorRect = Pick<DOMRectReadOnly, "top" | "left" | "right" | "bottom" | "width" | "height">;
 /**
  * Maps an anchor's border box to the part of it that is actually visible. A layout whose rows are
  * wider than what it shows (the compact Sidebar rail keeps full-width rows and clips them to the
@@ -19,3 +19,4 @@ export type FloatingBoundaryResolver = (anchor: HTMLElement) => Pick<AnchorRect,
 export declare const FloatingBoundaryProvider: React.Provider<FloatingBoundaryResolver | null>;
 /** The boundary resolver of the nearest region that confines its layers, or `null`. */
 export declare function useFloatingBoundaryResolver(): FloatingBoundaryResolver | null;
+export {};

package/dist/internal/ChartTooltip.d.ts

@@ -1,7 +1,7 @@
 import * as React from "react";
 import type { AnchorPoint } from "../hooks/usePosition";
 export type { AnchorPoint };
-export type ChartTooltipProps = React.HTMLAttributes<HTMLDivElement> & {
+type ChartTooltipProps = React.HTMLAttributes<HTMLDivElement> & {
     /** The point the content belongs to («8 окт», «Неделя 41»), over the content. */
     label?: React.ReactNode;
     /**

package/dist/internal/CheckMark.d.ts

@@ -1,4 +1,4 @@
-export type CheckMarkState = "checked" | "unchecked" | "indeterminate";
+import type { CheckState } from "./states";
 /**
  * The kit's check and indeterminate bar, drawn in with a stroke reveal (foundation §7 rule 8: a
  * check draws in, it does not pop). Both paths stay in the DOM so the mark animates both ways;
@@ -7,6 +7,6 @@ export type CheckMarkState = "checked" | "unchecked" | "indeterminate";
  * `pathLength` on the paths.
  */
 export declare function CheckMark({ state, className }: {
-    state: CheckMarkState;
+    state: CheckState;
     className?: string;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/internal/ChoiceField.d.ts

@@ -1,23 +1,42 @@
-import type * as React from "react";
+import * as React from "react";
 import { type FieldIds } from "./FieldFrame";
-import type { ControlSize, DataState } from "./states";
+import type { CheckState, ControlSize } from "./states";
 /** Class of the visually hidden native input that sits on top of the visual control. */
 export declare const choiceInputClass: string;
 /**
  * Class of the visual control (box, circle, track): fill, hover, press, checked, focus ring,
- * invalid and disabled come from the field state. A host tunes the fills with `--choice-bg*`.
- * Outside a field (`Checkbox.Indicator`) the element's own `data-state` / `data-disabled` drive it.
+ * invalid and disabled come from the field state. Outside a field (`Checkbox.Indicator`) the element's own `data-state` / `data-disabled` drive it.
  */
 export declare const choiceVisualClass: string;
-/** `--prime-choice-size` / gap / text of the tier in `data-size` on the same element. */
-export declare const choiceTierClass: string;
+/**
+ * The square box of a checkbox or a radio: the tier's choice size (`--field-choice`), the mark
+ * centred in it. The host sets only its corner radius and draws the mark or the dot.
+ */
+export declare const choiceBoxClass: string;
+/**
+ * The track of a sliding control (Switch), joined next to `choiceVisualClass`: the fill changes at
+ * the thumb's pace, and a disabled «on» keeps a soft accent.
+ */
+export declare const choiceTrackClass: string;
 type ChoiceFieldProps = {
     ids: FieldIds;
     size: ControlSize;
-    state: Extract<DataState, "checked" | "unchecked" | "indeterminate">;
+    state: CheckState;
     disabled: boolean;
     /** The state is shown but does not change: no hover or press. */
     readOnly?: boolean;
+    /** A change is being saved (a promise from the handler): no press. */
+    busy?: boolean;
+    /** Red `*` after the text (`LabelMarks`); the native input carries `required`. */
+    required?: boolean;
+    /** Muted `optionalLabel` after the text. */
+    optional?: boolean;
+    optionalLabel?: string;
+    /**
+     * An option of a group (a radio in `Radio.Group`): the group frame shakes and announces its
+     * error, the option does neither.
+     */
+    groupOption?: boolean;
     hint?: React.ReactNode;
     error?: React.ReactNode;
     /** The native input (with `choiceInputClass`) followed by its aria-hidden visual. */
@@ -25,10 +44,10 @@ type ChoiceFieldProps = {
     className?: string;
     children?: React.ReactNode;
 };
-export declare function ChoiceField({ ids, size, state, disabled, readOnly, 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, error, control, className, children, }: ChoiceFieldProps): import("react/jsx-runtime").JSX.Element;
 export type ChoiceLabelProps = React.HTMLAttributes<HTMLSpanElement> & {
     ref?: React.Ref<HTMLSpanElement>;
 };
-/** The visible text of a choice; it sits in the text column of the label row. */
-export declare function ChoiceLabel({ className, ...rest }: ChoiceLabelProps): import("react/jsx-runtime").JSX.Element;
+/** The visible text of a choice; it sits in the text column of the label row, marks after it. */
+export declare function ChoiceLabel({ className, children, ...rest }: ChoiceLabelProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/internal/ControlSizeContext.d.ts

@@ -15,3 +15,19 @@ export declare function useOptionalControlSize(): ControlSize | undefined;
  * popover, a table), else `m`.
  */
 export declare function useControlSize(sizeProp: ControlSize | undefined): ControlSize;
+type HostTier = {
+    /** The resolved tier: the root's own `size`, else the tier of its host, else `m`. */
+    size: ControlSize;
+    /** Wraps the root's subtree so its parts and the kit controls inside take the same tier. */
+    provide: (children: React.ReactNode) => React.ReactElement;
+};
+/**
+ * The tier of a sized root (foundation §6): it resolves like `useControlSize` and provides the
+ * result to everything inside. Every root that has `size` calls it instead of defaulting to `m`,
+ * so a sized host (a form, a panel, a popover) sizes the whole tree under it.
+ *
+ *   const tier = useHostTier(sizeProp);
+ *   return tier.provide(<div data-size={tier.size}>{children}</div>);
+ */
+export declare function useHostTier(sizeProp: ControlSize | undefined): HostTier;
+export {};

package/dist/internal/Disclosure.d.ts

@@ -1,15 +1,44 @@
-import type * as React from "react";
-export type DisclosureProps = React.HTMLAttributes<HTMLDivElement> & {
+import * as React from "react";
+type DisclosureOptions = {
     open: boolean;
-    /** Classes of the clip (a host that lets focus rings reach past it widens it). */
-    clipClassName?: string;
+    /**
+     * Open on mount plays the opening, as a part that arrives with its host (a new table row's
+     * detail). Without it an open disclosure stands open on mount.
+     */
+    appear?: boolean;
+};
+type DisclosureParts = {
+    /** Props of the element that folds: its class, `data-state`, `data-mounted` and a ref. */
+    root: {
+        className: string;
+        "data-state": "open" | "closed";
+        "data-mounted": "" | undefined;
+        ref: React.RefCallback<HTMLElement>;
+    };
+    /** Props of the clip, the one child of the root that holds the content. */
+    clip: {
+        className: string;
+    };
+};
+/**
+ * The fold of a part that opens and closes in place, for hosts whose root must be their own
+ * element (a `<td>` of a detail row, a list item): spread `root` on the element that folds and
+ * `clip` on its one child. `Disclosure` is this on two `<div>`s.
+ *
+ * The transitions switch on one frame after mount (`data-mounted`), so a state the host settles
+ * right after mounting (a restored group, the first reaction) stands still; with `appear`, an
+ * open one starts closed and opens on that frame instead.
+ */
+export declare function useDisclosure({ open, appear }: DisclosureOptions): DisclosureParts;
+type DisclosureProps = React.HTMLAttributes<HTMLDivElement> & DisclosureOptions & {
     ref?: React.Ref<HTMLDivElement>;
 };
 /**
  * A part that opens and closes in place: its height glides (`0fr ↔ 1fr`) while its content fades
- * and slides on the same clock — one stroke both ways. Always mounted; closed, the content keeps its
- * last state and leaves the accessibility tree once the close has played. The host sets the clock
- * with `--disclosure-duration` / `--disclosure-ease` (see `disclosure.module.css`). An open one on
- * its first render stands open: nothing plays on mount.
+ * and slides on the same clock — one stroke both ways. Always mounted; closed, the content keeps
+ * its last state and leaves the accessibility tree once the close has played. The host sets the
+ * clocks with `--disclosure-*` (see `disclosure.module.css`). An open one on its first render
+ * stands open unless `appear`.
  */
-export declare function Disclosure({ open, clipClassName, className, children, ...rest }: DisclosureProps): import("react/jsx-runtime").JSX.Element;
+export declare function Disclosure({ open, appear, className, children, ref, ...rest }: DisclosureProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/internal/FieldAction.d.ts

@@ -1,21 +1,28 @@
 import * as React from "react";
 export type FieldActionButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" | "children"> & {
-    /** Accessible name and tooltip («Позвонить», «Открыть профиль»). */
+    /**
+     * Accessible name and tooltip («Позвонить», «Открыть профиль»).
+     */
     label: string;
-    /** Renders the one child (an `<a href>`, a router link) with the segment's look and behaviour. */
+    /**
+     * Renders the one child (an `<a href>`, a router link) with the segment's look; `disabled` becomes `aria-disabled`.
+     */
     asChild?: boolean;
-    /** The glyph, or with `asChild` the element that carries it. */
+    /**
+     * The glyph (`<Icon name>`), or with `asChild` the element that carries it.
+     */
     children: React.ReactNode;
     ref?: React.Ref<HTMLButtonElement>;
 };
 /**
- * A segment without a tooltip, for a kit control whose glyph says it all (Input's clear and
- * reveal): the name stays accessible, nothing floats over the field.
+ * A named icon action at the field's edge. The glyph cross-fades when it changes (`GlyphSwap`:
+ * reveal ⇄ hide, copy → check). With a tooltip by default; `tooltip={false}` for a kit control
+ * whose glyph says it all (Input's clear and reveal): the name stays accessible, nothing floats
+ * over the field.
  */
-export declare function FieldActionSegment(props: FieldActionButtonProps): import("react/jsx-runtime").JSX.Element;
-/** A named icon action at the field's edge with a tooltip. */
-export declare function FieldActionButton(props: FieldActionButtonProps): import("react/jsx-runtime").JSX.Element;
-export type CopyState = "idle" | "copied" | "error";
+export declare function FieldActionButton({ label, asChild, tooltip, className, disabled, type, children, ref, ...rest }: FieldActionButtonProps & {
+    tooltip?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
 export type FieldCopyLabels = {
     /** Name and tooltip of the copy button. */
     copy: string;
@@ -24,14 +31,15 @@ export type FieldCopyLabels = {
     /** Name, tooltip and announcement when the clipboard refuses. */
     copyError: string;
 };
-export type FieldCopyButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" | "children" | "type"> & {
+type FieldCopyButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" | "children" | "type"> & {
     /** Reads the text to copy at the moment of the press. */
     getText: () => string;
     labels: FieldCopyLabels;
     ref?: React.Ref<HTMLButtonElement>;
 };
 /**
- * Copies a field's value: the copy glyph morphs into a check (both stay mounted and cross-fade in
- * place), the name and tooltip switch to `copied`, a polite live region repeats it.
+ * Copies a field's value: the copy glyph cross-fades into a check, the name and tooltip switch to
+ * `copied`, a polite live region repeats it.
  */
 export declare function FieldCopyButton({ getText, labels, onClick, ...rest }: FieldCopyButtonProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/internal/FieldCommit.d.ts

@@ -1,18 +1,14 @@
 import * as React from "react";
+import { type ValueControl } from "./controlValue";
+import { type AsyncHandler } from "./usePendingChanges";
 /**
  * Saves one field on its own (inline editing of a record card). Returns nothing for a sync save or
  * a Promise: while it is pending the field shows a spinner and stays editable; a rejection puts the
  * last committed value back (the owner shows why through `error` or a notification).
  */
-export type FieldCommitHandler = (value: string) => void | Promise<void>;
+export type FieldCommitHandler = AsyncHandler<[value: string]>;
 /** `idle` · `pending` (a Promise is running) · `saved` (a brief quiet confirmation). */
-export type FieldCommitState = "idle" | "pending" | "saved";
-type CommitControl = HTMLInputElement | HTMLTextAreaElement;
-/**
- * Writes a value into a native control the way typing does, so React's `onChange` (and the owner's
- * `onValueChange`) receive it whether the field is controlled or not.
- */
-export declare function setControlValue(control: CommitControl, value: string): void;
+type FieldCommitState = "idle" | "pending" | "saved";
 export type FieldCommit = {
     state: FieldCommitState;
     /** Commits the control's value when it differs from the last committed one. */
@@ -27,7 +23,7 @@ export type FieldCommit = {
  * saves a changed value; Escape reverts; a rejected save restores the committed value unless the
  * person has typed on since. Unchanged values never fire. `onCommit` undefined → inert.
  */
-export declare function useFieldCommit(controlRef: React.RefObject<CommitControl | null>, onCommit: FieldCommitHandler | undefined): FieldCommit;
+export declare function useFieldCommit(controlRef: React.RefObject<ValueControl | null>, onCommit: FieldCommitHandler | undefined): FieldCommit;
 export type FieldCommitLabels = {
     /** Read while a save is pending. */
     saving: string;
@@ -35,8 +31,9 @@ export type FieldCommitLabels = {
     saved: string;
 };
 /**
- * The commit status at the field's edge: a spinner while saving, then a check that fades out. A
- * polite live region says «saving» / «saved»; the glyphs are hidden from assistive tech.
+ * The commit status at the field's edge: a spinner while saving, then a check that cross-fades in
+ * its place (`GlyphSwap`) and leaves. The slot enters and leaves with `enterMotion`. A polite live
+ * region says «saving» / «saved»; the glyphs are hidden from assistive tech.
  */
 export declare function FieldCommitStatus({ state, labels, className, }: {
     state: FieldCommitState;

package/dist/internal/FieldFrame.d.ts

@@ -2,18 +2,36 @@ import * as React from "react";
 import type { ControlSize } from "./states";
 /** Field props shared by every framed field (the same contract as `Input.Root`). */
 export type FieldFrameProps = {
+    /**
+     * Field label above; names the input.
+     */
     label?: React.ReactNode;
-    /** Red `*` after the label; the control gets native `required` / `aria-required`. */
+    /**
+     * Red `*` after the label and `aria-required` on the input.
+     */
     required?: boolean;
-    /** Muted `labels.optional` marker after the label. */
+    /**
+     * Muted `labels.optional` after the label.
+     */
     optional?: boolean;
+    /**
+     * Support text under the field; linked by `aria-describedby`.
+     */
     hint?: React.ReactNode;
-    /** Error message; replaces the hint in the same slot and implies `invalid`. */
+    /**
+     * Error message; replaces the hint and implies `invalid`.
+     */
     error?: React.ReactNode;
+};
+/**
+ * `focusRing` of a field whose box draws the focus ring (Input, Select, Datepicker…): `false`
+ * hides only the visual ring — focus, keyboard and ARIA are unchanged, the error ring still shows
+ * (WCAG 2.4.7: only where focus is otherwise obvious). The host passes it as `data-focus-ring` on
+ * the box (`fieldSurface` reads `"false"`). Group controls (SegmentedControl, Slider…) have none.
+ */
+export type FieldFocusRingProps = {
     /**
-     * Draws the focus ring on the field (default). `false` sets `data-focus-ring="false"` on it and
-     * hides only the visual ring — focus, keyboard and ARIA are unchanged, the error ring still shows.
-     * Turn it off only where focus is otherwise obvious; WCAG 2.4.7.
+     * `false` hides only the visual focus ring on the field box (`data-focus-ring="false"`); focus, keyboard, ARIA and the invalid ring stay.
      */
     focusRing?: boolean;
 };
@@ -27,12 +45,33 @@ export type FieldFrameProps = {
 export type FieldRootDomProps = Omit<React.HTMLAttributes<HTMLDivElement>, "id" | "children" | "defaultValue" | "defaultChecked" | "onChange"> & {
     ref?: React.Ref<HTMLDivElement>;
 };
+type ControlAriaOptions = {
+    /** The control's role (default `textbox`). */
+    role?: string;
+    /** Id of the element that shows the value, read after the field name (a picker's text). */
+    textId?: string;
+    /** The value as text, appended to a consumer `aria-label` («Дата: 12.03.2026»). */
+    text?: string;
+    /** The consumer's `aria-label`: replaces the label as the name. */
+    ariaLabel?: string;
+    /** The consumer's `aria-labelledby`: replaces the label as the name. */
+    ariaLabelledBy?: string;
+};
+type ControlAria = {
+    "aria-label": string | undefined;
+    "aria-labelledby": string | undefined;
+    "aria-describedby": string | undefined;
+    "aria-invalid": true | undefined;
+    "aria-required": true | undefined;
+};
 export type FieldIds = {
     controlId: string;
     /** Id of the label element (rendered only when `label` is set). */
     labelId: string;
     hintId: string;
     errorId: string;
+    /** Id of the frame's required word (`requiredLabel`) for a control without `aria-required`. */
+    requiredId: string;
     /** `aria-describedby` of the control: caller ids + hint or error. */
     describedBy: string | undefined;
     /** `aria-labelledby` for a group control: the label id when a label renders, else `undefined`. */
@@ -40,36 +79,72 @@ export type FieldIds = {
     showHint: boolean;
     showError: boolean;
     invalid: boolean;
+    /** The field's own `required`, or a required FieldList column around it. */
+    required: boolean;
+    /**
+     * The name, description, invalid and required attributes of the control, in one place: the
+     * label (or a FieldList column heading) names it with the value text after it; a consumer
+     * `aria-label` / `aria-labelledby` replaces the label; a role without `aria-required` (a
+     * `button` trigger) is described by the frame's required word instead.
+     */
+    controlAria: (options?: ControlAriaOptions) => ControlAria;
 };
 /** Ids, visible slots and validation state of a framed field. */
-export declare function useFieldFrame(explicitId: string | undefined, { label, hint, error, invalid, }: {
+export declare function useFieldFrame(explicitId: string | undefined, { label, hint, error, invalid, required, }: {
     label?: React.ReactNode;
     hint?: React.ReactNode;
     error?: React.ReactNode;
     invalid?: boolean;
+    required?: boolean;
 }, ariaDescribedBy?: string): FieldIds;
 /**
- * `data-shake` of a field root: the control shakes once when the field turns invalid or its error
+ * `data-shake` of a frame: the control shakes once when the field turns invalid or its error
  * message changes (foundation §7, rule 14) — never for an error it mounts with. The value
  * alternates between `odd` and `even` so a new error restarts the keyframes.
  */
 export declare function useErrorShake(invalid: boolean, error: React.ReactNode): "odd" | "even" | undefined;
-/**
- * The error that has just been fixed, kept on screen while it fades out (`fast`, `exit`) so the
- * message leaves as smoothly as it arrived; the hint takes the slot after it. `null` when nothing
- * is leaving. Reduced motion drops it at once.
- */
-export declare function useLeavingError(showError: boolean, error: React.ReactNode): {
+/** An error leaving the support slot (`useLeavingError`). */
+type FieldLeavingError = {
     node: React.ReactNode;
     onExitEnd: (event: React.SyntheticEvent<Element>) => void;
-} | null;
-/** Class of the leaving error message (`useLeavingError`), for frames that render their own row. */
-export declare const leavingErrorClass: string;
-type FieldFrameRenderProps = Omit<FieldFrameProps, "focusRing"> & {
+};
+/**
+ * The error that has just been fixed, kept on screen while it leaves (`enterMotion.exit`) so the
+ * message goes as smoothly as it arrived; the hint takes the slot after it. `null` when nothing is
+ * leaving. Reduced motion drops it at once.
+ */
+export declare function useLeavingError(showError: boolean, error: React.ReactNode): FieldLeavingError | null;
+/**
+ * The text slot of a support row, shared by every frame (FieldFrame, the choice rows): the error
+ * (it replaces the hint), the error that has just been fixed while it leaves, or the hint. The slot
+ * stays mounted while the field is, so it is a polite live region: an error that arrives or
+ * 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, }: {
+    ids: FieldIds;
+    size: ControlSize;
+    hint?: React.ReactNode;
+    error?: React.ReactNode;
+    /** The error leaving the slot: the frame's `useLeavingError`. */
+    leaving: FieldLeavingError | null;
+    disabled?: boolean;
+    live?: boolean;
+    /** The slot element. */
+    className?: string;
+    /** The hint or error text inside it. */
+    textClassName?: string;
+}): import("react/jsx-runtime").JSX.Element;
+type FieldFrameRenderProps = FieldFrameProps & {
     size: ControlSize;
     ids: FieldIds;
     disabled?: boolean;
     optionalLabel: string;
+    /**
+     * The word a control without `aria-required` (a `button` trigger) is described by when required
+     * (`ids.controlAria`); rendered visually hidden as `ids.requiredId`.
+     */
+    requiredLabel?: string;
     /**
      * The control is a group (radiogroup, fieldset), not a labelable element: the label gets no
      * `htmlFor`; the group names itself with `aria-labelledby={ids.labelId}`.
@@ -88,9 +163,10 @@ type FieldFrameRenderProps = Omit<FieldFrameProps, "focusRing"> & {
 } & Omit<React.HTMLAttributes<HTMLDivElement>, "children" | "className">;
 /**
  * Label row · control · support row (hint | error on the left, an optional counter on the right),
- * spaced by the tier's `label-gap` / `hint-gap`.
+ * 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, group, labelEnd, counter, reserveSupportRow, className, children, ...rest }: FieldFrameRenderProps): import("react/jsx-runtime").JSX.Element;
+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;
 type FieldCounterProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> & {
     current: number;
     max: number;
@@ -99,6 +175,9 @@ type FieldCounterProps = Omit<React.HTMLAttributes<HTMLSpanElement>, "children">
     label: string;
     ref?: React.Ref<HTMLSpanElement>;
 };
-/** `14/40` for the eye, `labels.counter` for screen readers; danger when `current > max`. */
+/**
+ * `14/40` for the eye (hidden from assistive tech), `labels.counter` for screen readers through a
+ * polite live region; danger when `current > max`.
+ */
 export declare function FieldCounter({ current, max, size, label, className, ...rest }: FieldCounterProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/internal/MenuGroup.d.ts

@@ -1,6 +1,8 @@
 import * as React from "react";
 export type MenuGroupProps = Omit<React.HTMLAttributes<HTMLDivElement>, "role"> & {
-    /** Visible heading of the group; names it for screen readers. */
+    /**
+     * Heading of the group (caption, muted); also its accessible name.
+     */
     label?: React.ReactNode;
     ref?: React.Ref<HTMLDivElement>;
 };

package/dist/internal/MorphText.d.ts

@@ -1,4 +1,4 @@
-export type MorphTextProps = {
+type MorphTextProps = {
     children: string;
     className?: string;
 };
@@ -11,3 +11,4 @@ export type MorphTextProps = {
  * updates in place).
  */
 export declare function MorphText({ children: text, className }: MorphTextProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/internal/ProgressLegend.d.ts

@@ -1,6 +1,6 @@
 import { type ProgressSegment } from "./progressSegments";
-import type { ControlSize } from "./states";
-export type ProgressLegendProps = {
+import { type ControlSize } from "./states";
+type ProgressLegendProps = {
     segments: ProgressSegment[];
     /** 100% of a share (the resolved scale of the distribution). */
     scale: number;
@@ -16,3 +16,4 @@ export declare function ProgressLegendSkeleton({ rows, size, className, }: {
     size: ControlSize;
     className?: string;
 }): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/internal/RegionSwap.d.ts

@@ -0,0 +1,41 @@
+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.
+     */
+    state: string | number;
+    /** The region takes its parent's height and every state fills it; the height never glides. */
+    fill?: boolean;
+    /**
+     * After a swap, once the new state is in the document (focus already handed off from a leaving
+     * state): a host that moves focus or scrolls on a swap does it here.
+     */
+    onSwap?: (state: string | number) => void;
+    ref?: React.Ref<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.
+ */
+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. */
+    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`.
+ */
+export declare function useSwapIn(state: string | number): SwapIn;
+export {};

package/dist/internal/RollingNumber.d.ts

@@ -1,4 +1,4 @@
-export type RollingNumberProps = {
+type RollingNumberProps = {
     /** The formatted value («4 812 350 ₽», «12», «−3,4%»); digits roll, other characters stay put. */
     children: string | number;
     className?: string;
@@ -12,3 +12,12 @@ export type RollingNumberProps = {
  * percentage) stays plain tabular text: rolling there is noise.
  */
 export declare function RollingNumber({ children, className }: RollingNumberProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * A copy of a host carried elsewhere (Dnd's overlay, flying while the real item is hidden) shows
+ * what the host shows now: the copy's rolling digit columns take the destination's values and roll
+ * in flight. Matched from the right, as the number keys its columns; a new leading digit appears
+ * on settle. Returns whether the copy now shows the same number (as many columns on both sides) —
+ * else the caller copies the content as it stands.
+ */
+export declare function carryRolling(copy: Element, destination: Element): boolean;
+export {};