prime-ui-kit 0.15.0 → 0.17.0

package/dist/components/datepicker/Datepicker.d.ts

@@ -1,5 +1,5 @@
 import { type PositionAlign } from "../../hooks/usePosition";
-import { type FieldFrameProps } from "../../internal/FieldFrame";
+import { type FieldFocusRingProps, type FieldFrameProps } from "../../internal/FieldFrame";
 import type { ControlSize } from "../../internal/states";
 import { type CalendarOptions, DatepickerPanel, type DatepickerPanelProps } from "./DatepickerPanel";
 import { type DatepickerRange } from "./datepickerModel";
@@ -14,36 +14,85 @@ export declare function formatDatepickerValue(props: CalendarOptions & ({
     mode: "single";
     value: Date | null;
 })): string | null;
-export type DatepickerRootProps = DatepickerPanelProps & FieldFrameProps & {
+/**
+ * A date as a form submits it, in local time: `yyyy-MM-dd`, with `withTime` `yyyy-MM-ddTHH:mm` —
+ * never `toISOString()`, which shifts the day to UTC.
+ */
+export declare function formatDateValue(date: Date, { withTime }?: {
+    withTime?: boolean;
+}): string;
+export type DatepickerRootProps = DatepickerPanelProps & FieldFrameProps & FieldFocusRingProps & {
+    /**
+     * Field tier (height 28 · 32 · 36 · 40 · 48) and panel tier (day cell 24 · 28 · 32 · 36 · 40). Without it the tier of its host, else `m`.
+     */
     size?: ControlSize;
-    /** Field text without a value; `labels.placeholder` by default. */
+    /**
+     * Field text without a value for this field.
+     */
     placeholder?: string;
-    /** Text before the value in the field, e.g. «С». */
+    /**
+     * Text before the value, e.g. «С».
+     */
     valuePrefix?: string;
+    /**
+     * Controlled visibility of the panel.
+     */
     open?: boolean;
+    /**
+     * Initial visibility, uncontrolled.
+     */
     defaultOpen?: boolean;
+    /**
+     * Field click, Escape, an outside press or an applied value.
+     */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Escape closes the calendar and returns focus to the field.
+     */
+    closeOnEscape?: boolean;
+    /**
+     * A press outside the calendar and the field closes it; focus follows the pointer.
+     */
+    closeOnOutsideClick?: boolean;
+    /**
+     * The field cannot be opened.
+     */
     disabled?: boolean;
-    /** Danger ring and `aria-invalid`; a non-empty `error` implies it. */
+    /**
+     * Danger ring and `aria-invalid` without a message.
+     */
     invalid?: boolean;
-    /** Field stretches to the container width; otherwise it fits the text. */
+    /**
+     * The field stretches to its container; otherwise it fits the text.
+     */
     fullWidth?: boolean;
-    /** Popover alignment to the field. */
+    /**
+     * Popover alignment to the field. `auto` lines the panel up with the trigger edge that has more room beyond it; `start`, `center` or `end` fix it.
+     */
     align?: PositionAlign;
-    /** Id of the field button; generated when omitted. */
+    /**
+     * Id of the field button; generated when omitted.
+     */
     id?: string;
     /**
-     * Submits the value with a form through hidden inputs: `yyyy-MM-dd` (`yyyy-MM-ddTHH:mm` with
-     * `withTime`); a range submits two values under the name, `from` then `to` (empty when open).
+     * Submits the value with a form through hidden inputs: `yyyy-MM-dd` (`yyyy-MM-ddTHH:mm` with `withTime`); a range submits two values under the name, `from` then `to` (empty for an open bound).
      */
     name?: string;
-    /** Accessible name when there is no `label`; the current value is appended. */
+    /**
+     * Name without a `label` (the value is appended) and extra description ids.
+     */
     "aria-label"?: string;
+    /**
+     * Name without a `label` (the value is appended) and extra description ids.
+     */
     "aria-labelledby"?: string;
+    /**
+     * Name without a `label` (the value is appended) and extra description ids.
+     */
     "aria-describedby"?: string;
 };
 /** A field (field system: fill, tier height, rings) with the value; a click opens the panel in a popover. */
-declare function DatepickerRoot(props: DatepickerRootProps): import("react/jsx-runtime").JSX.Element;
+declare function DatepickerRoot(props: DatepickerRootProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
 declare namespace DatepickerRoot {
     var displayName: string;
 }

package/dist/components/datepicker/DatepickerPanel.d.ts

@@ -1,6 +1,6 @@
 import { type Locale } from "date-fns";
 import * as React from "react";
-import type { ControlSize } from "../../internal/states";
+import { type ControlSize } from "../../internal/states";
 import { type DatepickerPreset, type DatepickerRange, type WeekStart } from "./datepickerModel";
 /** System strings and default texts. */
 export type DatepickerLabels = {
@@ -25,48 +25,106 @@ export type DatepickerLabels = {
     presetsTitle: string;
     /** Muted marker after the field label when `optional`. */
     optional: string;
+    /** Read after the field name of a `required` field (its trigger is a button). */
+    required: string;
 };
 export declare const DATEPICKER_LABELS: DatepickerLabels;
 export type CalendarOptions = {
-    /** Tier: day cell = the tier's menu item height (`m` → 32 px), text = the tier's text. */
+    /**
+     * Panel tier (day cell 24 · 28 · 32 · 36 · 40). Without it the tier of its host, else `m`.
+     */
     size?: ControlSize;
-    /** Months side by side; one when there is no room. */
+    /**
+     * Months side by side; one when there is no room.
+     */
     months?: 1 | 2;
-    /** The presets column (`range` only). */
+    /**
+     * Preset column (`range` only): `DEFAULT_DATEPICKER_PRESETS` or picks from `datepickerPresets`; a row above the calendar when narrow.
+     */
     presets?: DatepickerPreset[] | false;
-    /** Step prompt under the calendar: «Выберите начальную дату» / «… конечную дату». */
+    /**
+     * Step prompt under the calendar (`labels.pickStart` / `pickEnd` / `pickDate`).
+     */
     prompt?: boolean;
-    /** Footer with date fields and Reset / Apply. Without it a pick applies at once. */
+    /**
+     * Footer with date fields and Reset / Apply; without it a pick applies at once.
+     */
     footer?: boolean;
-    /** Time fields in the footer (00:00 — 23:59 by default). */
+    /**
+     * Time fields in the footer (00:00 — 23:59 by default).
+     */
     withTime?: boolean;
-    /** Days that cannot be picked (a calendar day is a Date at local midnight). */
+    /**
+     * Days that cannot be picked.
+     */
     isDayDisabled?: (day: Date) => boolean;
-    /** Future days are muted and cannot be picked. */
+    /**
+     * Future days are muted and cannot be picked.
+     */
     disableFuture?: boolean;
-    /** An annual day + month: no year, months wrap around inside `YEARLESS_YEAR`. */
+    /**
+     * An annual day + month: no year, months wrap around inside `YEARLESS_YEAR`.
+     */
     yearless?: boolean;
-    /** «Today» for highlighting, presets and `disableFuture`; the browser's day by default. */
+    /**
+     * «Today» for highlighting, presets and `disableFuture`.
+     */
     today?: Date;
+    /**
+     * date-fns locale of titles, weekdays and day names.
+     */
     locale?: Locale;
+    /**
+     * First day of the week (1 — Monday).
+     */
     weekStartsOn?: WeekStart;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<DatepickerLabels>;
 };
 export type RangeModeProps = {
+    /**
+     * One date or a period; sets the value type.
+     */
     mode: "range";
-    /** Bounds in wall-clock time; `null` — the bound is not set. */
+    /**
+     * Controlled value: a date (`single`) or `{ from, to }` in wall-clock time (`range`); `null` — not set.
+     */
     value?: DatepickerRange;
+    /**
+     * Initial value, uncontrolled.
+     */
     defaultValue?: DatepickerRange;
+    /**
+     * Called when a pick, a preset, Apply or Reset changes the value.
+     */
     onValueChange?: (value: DatepickerRange) => void;
-    /** Value applied by «Сбросить»; an empty range by default. */
+    /**
+     * Value applied by Reset.
+     */
     resetValue?: DatepickerRange;
 };
 export type SingleModeProps = {
+    /**
+     * One date or a period; sets the value type.
+     */
     mode: "single";
+    /**
+     * Controlled value: a date (`single`) or `{ from, to }` in wall-clock time (`range`); `null` — not set.
+     */
     value?: Date | null;
+    /**
+     * Initial value, uncontrolled.
+     */
     defaultValue?: Date | null;
+    /**
+     * Called when a pick, a preset, Apply or Reset changes the value.
+     */
     onValueChange?: (value: Date | null) => void;
-    /** Value applied by «Сбросить»; `null` by default. */
+    /**
+     * Value applied by Reset.
+     */
     resetValue?: Date | null;
 };
 /** Native attributes and `ref` of the element a part renders (the panel card, the field frame). */
@@ -94,11 +152,13 @@ export type DatepickerValue = {
 /** Controlled-or-internal value of either mode (a part never switches its mode). */
 export declare function useDatepickerValue(props: RangeModeProps | SingleModeProps): DatepickerValue;
 /** Calendar panel without a field: inline in a page or a card. */
-export declare function DatepickerPanel(props: DatepickerPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function DatepickerPanel(props: DatepickerPanelProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 export declare namespace DatepickerPanel {
     var displayName: string;
 }
-type PanelViewProps = Omit<CalendarOptions, "labels"> & DatepickerValue & {
+type PanelViewProps = Omit<CalendarOptions, "labels" | "size"> & DatepickerValue & {
+    /** The resolved tier (the Root's or the Panel's `useHostTier`). */
+    size: ControlSize;
     labels: DatepickerLabels;
     /** `Datepicker.Panel`: host content that takes its container's width; otherwise (the Root popover) it sizes to its content. */
     embedded: boolean;

package/dist/components/datepicker/panelLayout.d.ts

@@ -1,17 +1,18 @@
 import type { ControlSize } from "../../internal/states";
-/** Buttons and fields inside the panel sit one tier below the panel (m → s, 32 = the day cell). */
-export declare const STEP_DOWN: Record<ControlSize, ControlSize>;
 /** Panel geometry in px, the same numbers the CSS lays out with. */
 export type PanelMetrics = {
     /** Day cell: `--prime-control-<tier>-item-height`. */
     cell: number;
     /** Gap between months: `--prime-space-6`. */
     monthsGap: number;
-    /** Side padding of `.main` (both sides): `space-3` in the popover, none embedded (the host pads). */
+    /** Side padding of `.main` (both sides): the panel's `--dp-chrome` (none embedded, the host pads). */
     chrome: number;
 };
-/** Reads the panel geometry from the tokens on the document (theme and app overrides apply). */
-export declare function readPanelMetrics(size: ControlSize, embedded: boolean): PanelMetrics;
+/**
+ * Reads the panel geometry from the tokens on the document (theme and app overrides apply); the
+ * padding around the months from the panel's own `--dp-chrome`, the one the CSS pads with.
+ */
+export declare function readPanelMetrics(size: ControlSize, panel: HTMLElement | null): PanelMetrics;
 export type PanelLayoutInput = {
     /** Requested months (`months` prop). */
     months: 1 | 2;
@@ -36,12 +37,6 @@ export type PanelLayout = {
 export declare function resolvePanelLayout({ months, hasPresets, embedded, available, metrics, }: PanelLayoutInput): PanelLayout;
 /** Window width (px) — for the popover panel, which cannot measure itself. */
 export declare function useViewportWidth(enabled: boolean): number | null;
-/**
- * The wheel over an open calendar does not scroll the page under it; scrolling areas inside (the
- * presets list) work as usual. `overscroll-behavior: contain` is not enough: it only holds while
- * the popover itself overflows, and a calendar that fits chains the wheel to the page.
- */
-export declare function useContainScroll(node: HTMLElement | null): void;
 /**
  * Available width of an embedded panel: the content box of its PARENT (ResizeObserver), not the
  * panel's own width (that follows the content) — otherwise «1 or 2 months» would loop. `null` —

package/dist/components/description-list/DescriptionList.d.ts

@@ -1,35 +1,53 @@
 import * as React from "react";
-import { type ControlSize } from "../../internal/states";
+import type { ControlSize } from "../../internal/states";
 export type DescriptionListLabels = {
     /** Visible mark of an empty value (muted, hidden from assistive tech). */
     empty: string;
     /** What assistive tech reads for an empty value. */
     emptyText: string;
 };
+export declare const DESCRIPTION_LIST_LABELS: DescriptionListLabels;
 /**
  * `horizontal` — the label beside its value, stacking when the list is narrower than 24rem;
  * `vertical` — the label above its value at any width.
  */
 export type DescriptionListOrientation = "horizontal" | "vertical";
+/**
+ * `start` — values in their column from its start edge; `end` — each value at the end of its row
+ * in tabular figures, the label at the start (a summary of amounts).
+ */
+export type DescriptionListAlign = "start" | "end";
 export type DescriptionListRootProps = React.HTMLAttributes<HTMLDListElement> & {
-    /** Text and spacing tier. Default: the host tier (a Card, a Drawer form), else `m`. */
+    /**
+     * Label and value type and the gap between pairs; without it the list takes the tier of a sized host (a Drawer, a Modal).
+     */
     size?: ControlSize;
-    /** Default `horizontal`. */
+    /**
+     * `horizontal` — the label in a column beside its value (one third of the width), stacking below 24rem of the list's own width; `vertical` — the label above its value at any width.
+     */
     orientation?: DescriptionListOrientation;
+    /**
+     * `start` — values from the start of their column; `end` — each value at the end of its row in tabular figures, at any width: a summary of amounts (subtotal, tax, total).
+     */
+    align?: DescriptionListAlign;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<DescriptionListLabels>;
     ref?: React.Ref<HTMLDListElement>;
 };
 /** A read-only list of «label — value» pairs: a `<dl>` that adapts to its own width. */
-declare function DescriptionListRoot({ size: sizeProp, orientation, labels, className, children, ...rest }: DescriptionListRootProps): import("react/jsx-runtime").JSX.Element;
+declare function DescriptionListRoot({ size: sizeProp, orientation, align, labels, className, children, ...rest }: DescriptionListRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DescriptionListRoot {
     var displayName: string;
 }
 export type DescriptionListItemProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
-    /** The visible name of the value (`<dt>`). */
+    /**
+     * The visible name of the value (`<dt>`).
+     */
     label: React.ReactNode;
     /**
-     * The value (`<dd>`) and an optional `DescriptionList.ItemAction`. No value (`null`, `""`,
-     * `false`) shows `labels.empty`.
+     * The value (`<dd>`): text, a Badge, a link; plus an optional `DescriptionList.ItemAction`, which goes to the end of the value.
      */
     children?: React.ReactNode;
     ref?: React.Ref<HTMLDivElement>;
@@ -40,14 +58,25 @@ declare namespace DescriptionListItem {
     var displayName: string;
 }
 export type DescriptionListItemActionProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> & {
-    /** Accessible name and tooltip of the action («Копировать», «Позвонить»). */
+    /**
+     * Accessible name and tooltip of the action.
+     */
     label: string;
-    /** The icon (`<Icon name="…" />`). */
+    /**
+     * The icon (`<Icon name="…" />`); with `asChild`, the one link whose children are the icon.
+     */
     children: React.ReactNode;
+    /**
+     * The action is the child link (`mailto:`, another page) with the button look.
+     */
+    asChild?: boolean;
     ref?: React.Ref<HTMLButtonElement>;
 };
-/** A ghost icon Button one tier below the list, with its `label` as the tooltip. */
-declare function DescriptionListItemAction({ label, children, className, ...rest }: DescriptionListItemActionProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The kit row action (`internal/RowAction`): a ghost icon Button one tier below the list, centred
+ * on the value's first line.
+ */
+declare function DescriptionListItemAction({ label, children, ...rest }: DescriptionListItemActionProps): import("react/jsx-runtime").JSX.Element;
 declare namespace DescriptionListItemAction {
     var displayName: string;
 }

package/dist/components/digit-input/DigitInput.d.ts

@@ -1,4 +1,5 @@
-import { type FieldFrameProps, type FieldRootDomProps } from "../../internal/FieldFrame";
+import * as React from "react";
+import { type FieldFocusRingProps, type FieldFrameProps, type FieldRootDomProps } from "../../internal/FieldFrame";
 import type { ControlSize } from "../../internal/states";
 export type DigitInputLabels = {
     /** Accessible name of the group when there is no visible `label`. */
@@ -10,46 +11,76 @@ export type DigitInputLabels = {
     /** The error of a code whose `onComplete` promise rejected without a reason. */
     failed: string;
 };
-export type DigitInputProps = FieldRootDomProps & FieldFrameProps & {
-    /** Number of cells. */
+export declare const DIGIT_INPUT_LABELS: DigitInputLabels;
+export type DigitInputProps = FieldRootDomProps & FieldFrameProps & FieldFocusRingProps & {
+    /**
+     * Number of cells.
+     */
     length?: number;
-    /** Tier. Default: the tier of the surrounding control (a form, a panel), else `m`. */
+    /**
+     * Tier: the cell is a square on its own scale, two steps above the control heights (36 · 40 · 48 · 56 · 64); label and hint follow the field tier. Without it the tier of its host (LoginForm, a panel), else `m`.
+     */
     size?: ControlSize;
     /**
-     * Cells share the container width and grow with it (height stays the tier height, so they become
-     * wider than tall). Default `false`: square cells of the tier size, centered.
+     * Cells share the container width up to 1.5 × their side (the row centres beyond that) and keep the tier height; otherwise square cells and the field hugs them.
      */
     fullWidth?: boolean;
-    /** Name of the hidden input that carries the joined code in a native form submit. */
+    /**
+     * Name of a hidden input that carries the joined code in a native form submit.
+     */
     name?: string;
-    /** Splits the cells into groups of this size with a wider gap between them (`3` → 123 456). */
+    /**
+     * Splits the cells into groups of this size with a wider gap (`3` → 123 456).
+     */
     groupSize?: number;
-    /** Hides the digits (PIN): cells are `type="password"`. */
+    /**
+     * Hides the digits (PIN): cells are `type="password"`.
+     */
     mask?: boolean;
-    /** Focuses the first empty cell on mount. */
+    /**
+     * Focuses the first empty cell on mount.
+     */
     autoFocus?: boolean;
+    /**
+     * Controlled code; non-digits are dropped, extra digits cut to `length`.
+     */
     value?: string;
+    /**
+     * Initial code when uncontrolled.
+     */
     defaultValue?: string;
+    /**
+     * Called with the joined digits on every change.
+     */
     onValueChange?: (value: string) => void;
     /**
-     * Called once when the last empty cell is filled. Return the check's promise: the cells wait
-     * read-only and quiet (`aria-busy`); resolve — the `success` look; reject — the code clears,
-     * the field shakes in the reason (the rejection's message, else `labels.failed`) as its error,
-     * and the reason is announced. Typing again takes the error away.
+     * Called once when the last empty cell is filled (typing, paste or autofill). Return the check's promise: the cells wait read-only; resolve — the `success` look; reject — the code clears and the reason shows as the error.
      */
     onComplete?: (value: string) => void | Promise<void>;
+    /**
+     * Disables the fieldset and every cell.
+     */
     disabled?: boolean;
-    /** Invalid state: danger ring on every cell. A non-empty `error` implies it. */
+    /**
+     * Danger ring and danger digits on every cell, `aria-invalid`. A non-empty `error` implies it.
+     */
     invalid?: boolean;
     /**
-     * The code was accepted (after the server checked it): the cells turn success one after
-     * another. Say it in words too (`hint`), never by color alone.
+     * The code was accepted (after the server checked it): the cells turn success one after another. Ignored while invalid. Say it in words too (`hint`).
      */
     success?: boolean;
-    /** Id of the first cell (the label points at it); generated when omitted. */
+    /**
+     * Id of the first cell (the label points at it); hint id is `<id>-hint`, error id is `<id>-error`.
+     */
     id?: string;
+    /**
+     * Merged before the hint/error ids on the group.
+     */
     "aria-describedby"?: string;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<DigitInputLabels>;
 };
 /** A one-time code or PIN split into cells, with the field label, hint and error. */
-export declare function DigitInput({ length, size: sizeProp, fullWidth, name, groupSize, mask, autoFocus, value: valueProp, defaultValue, onValueChange, onComplete, disabled: disabledProp, invalid, success, focusRing, label, required, optional, hint, error, id, "aria-describedby": ariaDescribedBy, labels: labelsProp, className, ...rest }: DigitInputProps): import("react/jsx-runtime").JSX.Element;
+export declare function DigitInput({ length, size: sizeProp, fullWidth, name, groupSize, mask, autoFocus, value: valueProp, defaultValue, onValueChange, onComplete, disabled: disabledProp, invalid, success, focusRing, label, required, optional, hint, error, id, "aria-describedby": ariaDescribedBy, labels: labelsProp, className, ...rest }: DigitInputProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;

package/dist/components/divider/Divider.d.ts

@@ -1,15 +1,25 @@
-import type * as React from "react";
+import * as React from "react";
 import type { ControlSize } from "../../internal/states";
 export type DividerOrientation = "horizontal" | "vertical";
 export type DividerAlign = "start" | "center" | "end";
 export type DividerProps = React.HTMLAttributes<HTMLDivElement> & {
-    /** Default `horizontal`. */
+    /**
+     * `vertical` stretches to the height of its flex row and sets `aria-orientation`.
+     */
     orientation?: DividerOrientation;
-    /** Position of the label (children) on the line. Default `center`. */
+    /**
+     * Position of the label on the line; `start` reads as a section heading.
+     */
     align?: DividerAlign;
-    /** Tier of the label: type, gap and icon size. Default `m`. */
+    /**
+     * Tier of the label: type, gap and icon size. Without it the tier of the content around (a menu, a panel with a size), else `m`.
+     */
     size?: ControlSize;
+    /**
+     * The line stands off its neighbours by the tier gap; a vertical one is one text line tall, centred in its row (a header, a toolbar).
+     */
+    inset?: boolean;
     ref?: React.Ref<HTMLDivElement>;
 };
 /** A hairline with an optional label; `role="separator"` unless the consumer overrides `role`. */
-export declare function Divider({ orientation, align, size, children, className, role, ...rest }: DividerProps): import("react/jsx-runtime").JSX.Element;
+export declare function Divider({ orientation, align, size: sizeProp, inset, children, className, role, ...rest }: DividerProps): import("react/jsx-runtime").JSX.Element;