prime-ui-kit 0.15.0 → 0.17.0

package/dist/components/notification/Notification.d.ts

@@ -19,21 +19,44 @@ export declare const NotificationLabelsContext: React.Context<NotificationLabels
 export type NotificationTone = Extract<Tone, "info" | "success" | "warning" | "danger">;
 export type NotificationAction = {
     label: string;
+    /** Runs the action; a toast of `notify()` then leaves with the reason `action`. */
     onClick: () => void;
 };
+/**
+ * Why a toast left: its timer ran out (`timeout`), the close button (`close`), a swipe (`swipe`),
+ * its action button (`action`), a `dismiss()` / `dismissAll()` call (`dismiss`), or a newer toast
+ * pushed it out of a full stack (`overflow`).
+ */
+export type NotificationDismissReason = "timeout" | "close" | "swipe" | "action" | "dismiss" | "overflow";
 /** What a toast shows; shared by `notify()` and the static `NotificationCard`. */
 type NotificationContent = {
-    /** Semantic color and default icon. Default `info`. `danger` and `warning` are announced assertively. */
+    /**
+     * Semantic color and tone icon; `danger` and `warning` are announced assertively.
+     */
     tone?: NotificationTone;
+    /**
+     * The message.
+     */
     title: string;
+    /**
+     * Secondary text under the title.
+     */
     description?: string;
-    /** Default `m`. */
+    /**
+     * Padding, icon and text tier of the card. Without it the tier of the host (a toast of `notify()` sits outside any host: `m`).
+     */
     size?: ControlSize;
-    /** Replaces the tone icon (an `Icon`). */
+    /**
+     * Replaces the tone icon.
+     */
     icon?: React.ReactNode;
-    /** A small counter next to the title. */
+    /**
+     * A counter next to the title (a `Badge` of the same `tone`).
+     */
     badge?: string | number;
-    /** One action button under the text. */
+    /**
+     * One soft button under the text, one tier below the card; on a toast of `notify()` it closes the toast after its `onClick` (reason `action`).
+     */
     action?: NotificationAction;
 };
 export type NotificationOptions = NotificationContent & {
@@ -46,11 +69,10 @@ export type NotificationOptions = NotificationContent & {
     /** Shows the close button. Default `true`. */
     closable?: boolean;
     /**
-     * The toast left: its timer ran out, the close button, a swipe, `dismiss()`, or a newer toast
-     * pushed it out of a full stack. Called once. The place to commit an action the toast offered to
-     * undo («Удалено» with «Отменить»).
+     * The toast left, with the reason. Called once. The place to commit an action the toast offered
+     * to undo («Удалено» with «Отменить»): every reason but `action`.
      */
-    onDismiss?: () => void;
+    onDismiss?: (reason: NotificationDismissReason) => void;
 };
 export type NotificationRecord = NotificationOptions & {
     id: string;
@@ -67,7 +89,9 @@ type CardDomProps = Omit<React.HTMLAttributes<HTMLElement>, "title" | "children"
     ref?: React.Ref<HTMLElement>;
 };
 export type NotificationCardProps = NotificationContent & CardDomProps & {
-    /** Shows the close button and is called on its click. */
+    /**
+     * Shows the close button and is called on its click.
+     */
     onDismiss?: () => void;
 };
 /**
@@ -78,7 +102,7 @@ export declare function NotificationCard({ onDismiss, ...props }: NotificationCa
 type ToastCardProps = {
     item: NotificationRecord;
     paused: boolean;
-    onDismiss: (id: string) => void;
+    onDismiss: (id: string, reason: NotificationDismissReason) => void;
     stackDepth: number;
     stackExpanded: boolean;
 };

package/dist/components/notification/NotificationStore.d.ts

@@ -1,12 +1,21 @@
 import * as React from "react";
 import { type NotificationLabels, type NotificationOptions, type NotificationPosition, type NotificationRecord } from "./Notification";
 export type NotificationProviderProps = {
+    /**
+     * The app.
+     */
     children: React.ReactNode;
-    /** Default position for `notify()` calls without one. Default `top-right`. */
+    /**
+     * Default position for `notify()` calls without one.
+     */
     position?: NotificationPosition;
-    /** Max visible toasts per stack (position × tone). Default 5. */
+    /**
+     * Max toasts per stack; a newer toast pushes the oldest out through its exit (reason `overflow`).
+     */
     max?: number;
-    /** Built-in strings: the close button and the region names per position. */
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<NotificationLabels>;
 };
 type StoreValue = {

package/dist/components/pagination/Pagination.d.ts

@@ -11,21 +11,44 @@ export type PaginationLabels = {
     /** Hidden word between the current and the total page in the compact view («3 из 12»). */
     of: string;
 };
+export declare const PAGINATION_LABELS: PaginationLabels;
 export type PaginationProps = Omit<React.HTMLAttributes<HTMLElement>, "defaultValue" | "onChange"> & {
     ref?: React.Ref<HTMLElement>;
-    /** Current page (1-based), controlled. */
+    /**
+     * Current page (1-based), controlled; clamped to `1…totalPages`.
+     */
     value?: number;
+    /**
+     * Initial page, uncontrolled.
+     */
     defaultValue?: number;
+    /**
+     * Called when a page button or an arrow picks another page.
+     */
     onValueChange?: (page: number) => void;
+    /**
+     * Number of pages. Below `1` nothing is rendered.
+     */
     totalPages: number;
-    /** Pages on each side of the current one before an ellipsis. */
+    /**
+     * Pages on each side of the current one before an ellipsis (when `totalPages > 2·siblingCount+5`).
+     */
     siblingCount?: number;
+    /**
+     * Control tier of the buttons: height 28 · 32 · 36 · 40 · 48. Without it the tier of its host, else `m`.
+     */
     size?: ControlSize;
     /**
-     * Arrows + «current / total» instead of page numbers. `"auto"` fills the parent and switches to
-     * the compact view when the container is narrow.
+     * Always arrows + «current / total» instead of numbers. Without it the nav fills its parent and shows that view only below 22rem of its width.
+     */
+    compact?: boolean;
+    /**
+     * Where the page numbers sit in the width the nav fills: centred under a list, `end` beside a range line (the DataTable footer). The compact view keeps its arrows at the edges.
+     */
+    align?: "start" | "center" | "end";
+    /**
+     * Built-in strings, see Labels.
      */
-    compact?: boolean | "auto";
     labels?: Partial<PaginationLabels>;
 };
-export declare function Pagination({ value, defaultValue, onValueChange, totalPages, siblingCount, size, compact, labels: labelsProp, className, ...rest }: PaginationProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function Pagination({ value, defaultValue, onValueChange, totalPages, siblingCount, size: sizeProp, compact, align, labels: labelsProp, className, ...rest }: PaginationProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | null;

package/dist/components/popover/Popover.d.ts

@@ -1,34 +1,52 @@
 import * as React from "react";
 import { type PositionAlign, type PositionSide } from "../../hooks/usePosition";
-import type { ControlSize } from "../../internal/states";
+import { type FloatingWidth } from "../../internal/overlay/FloatingPanel";
+import { type SlotPartProps } from "../../internal/slot";
+import { type ControlSize } from "../../internal/states";
 export type PopoverRootProps = {
+    /**
+     * Controlled visibility; together with `onOpenChange`.
+     */
     open?: boolean;
+    /**
+     * Initial visibility, uncontrolled.
+     */
     defaultOpen?: boolean;
+    /**
+     * Called on every open and close: trigger, `Popover.Close`, Escape, outside press, code.
+     */
     onOpenChange?: (open: boolean) => void;
-    /** A pointerdown outside the panel and its trigger closes it. Default `true`. */
+    /**
+     * A pointerdown outside the panel and its trigger closes it; focus follows the pointer.
+     */
     closeOnOutsideClick?: boolean;
-    /** Escape closes the panel. Default `true`. */
+    /**
+     * Escape closes the panel and returns focus to the trigger.
+     */
     closeOnEscape?: boolean;
+    /**
+     * ArrowDown and ArrowUp on the trigger open the panel, as on a picker whose trigger reads as a field (a colour, a period); Enter and Space open it either way.
+     */
+    openOnArrow?: boolean;
+    /**
+     * Trigger (or Anchor) and Content.
+     */
     children: React.ReactNode;
 };
-declare function PopoverRoot({ open, defaultOpen, onOpenChange, closeOnOutsideClick, closeOnEscape, children, }: PopoverRootProps): import("react/jsx-runtime").JSX.Element;
+declare function PopoverRoot({ open, defaultOpen, onOpenChange, closeOnOutsideClick, closeOnEscape, openOnArrow, children, }: PopoverRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace PopoverRoot {
     var displayName: string;
 }
-export type PopoverTriggerProps = {
-    /** The element that opens the panel (usually a Button); it receives ref, ARIA and the click handler. */
-    children: React.ReactElement;
-    ref?: React.Ref<HTMLElement>;
-} & Omit<React.HTMLAttributes<HTMLElement>, "children">;
-/** Other props (handlers, ARIA, `ref`) are forwarded to the child, e.g. from a wrapping `Tooltip.Trigger`. */
-declare function PopoverTrigger({ children, ...forwarded }: PopoverTriggerProps): import("react/jsx-runtime").JSX.Element;
+export type PopoverTriggerProps = SlotPartProps;
+/**
+ * Wraps the element that opens the panel (usually a Button): it receives the ref, the ARIA and the
+ * click. Props a wrapping trigger adds (`Tooltip.Trigger`) pass on to the child.
+ */
+declare function PopoverTrigger(props: PopoverTriggerProps): import("react/jsx-runtime").JSX.Element;
 declare namespace PopoverTrigger {
     var displayName: string;
 }
-export type PopoverAnchorProps = {
-    /** The element the panel is positioned against and that does not count as "outside" for dismissal. */
-    children: React.ReactElement;
-};
+export type PopoverAnchorProps = SlotPartProps;
 /**
  * An anchor that is not a trigger: positions the panel against an element (a whole toolbar) and keeps
  * presses on it from closing the panel, but adds no click handler and no ARIA. Open state is driven
@@ -40,10 +58,7 @@ declare function PopoverAnchor({ children }: PopoverAnchorProps): import("react/
 declare namespace PopoverAnchor {
     var displayName: string;
 }
-export type PopoverCloseProps = {
-    /** One element (usually a Button inside the panel); a click closes the panel. */
-    children: React.ReactElement;
-};
+export type PopoverCloseProps = SlotPartProps;
 /**
  * Closes the panel on click (focus returns to the trigger), unless the child's own handler calls
  * `preventDefault()`.
@@ -53,29 +68,37 @@ declare namespace PopoverClose {
     var displayName: string;
 }
 export type PopoverContentProps = Omit<React.HTMLAttributes<HTMLDivElement>, "role"> & {
+    /**
+     * Preferred side; flips to the opposite side when there is no room.
+     */
     side?: PositionSide;
+    /**
+     * Alignment along the trigger. `auto` lines the panel up with the trigger edge that has more room beyond it; `start`, `center` or `end` fix the edge.
+     */
     align?: PositionAlign;
-    /** Tier of the text, padding and the controls inside. */
+    /**
+     * Tier of the text, padding and gap; also the size context of the controls inside.
+     */
     size?: ControlSize;
-    /** The panel is exactly as wide as the trigger (text wraps). */
-    matchTriggerWidth?: boolean;
-    /** Tab cycles inside the panel (forms). Without it Tab past the edges leaves to the trigger and closes. */
+    /**
+     * `auto`: by content, panel minimum to twice that. `trigger`: exactly the trigger. `min-trigger`: `auto`, never narrower than the trigger. `content`: what the content needs. A sheet is full width.
+     */
+    width?: FloatingWidth;
+    /**
+     * Tab cycles inside the panel (forms). Without it Tab past the last (Shift+Tab before the first) stop closes the panel and returns focus to the trigger.
+     */
     trapFocus?: boolean;
     /**
-     * Focus moves into the panel when it opens (`[data-autofocus]`, else the first tab stop, else the
-     * panel). Default: on with `Popover.Trigger`, off with `Popover.Anchor` (a field driving the
-     * panel keeps typing). Turn it on for an anchored panel opened by a command — a Dropdown item
-     * («Переименовать…») — so focus lands in the panel, not back on the menu trigger.
+     * Focus moves into the panel on open (`[data-autofocus]`, else the first tab stop, else the panel). Turn it on for an anchored panel opened by a command, such as a Dropdown item, so focus does not stay on the menu trigger.
      */
     initialFocus?: boolean;
     /**
-     * No inner padding and no gap: rows reach the panel edges (lists with full-width dividers, filter
-     * panels). The content lays out its own spacing and uses inset focus rings.
+     * No inner padding and no gap: rows and dividers reach the panel edges; the content lays out its own spacing.
      */
     flush?: boolean;
     ref?: React.Ref<HTMLDivElement>;
 };
-declare function PopoverContent({ side, align, size, matchTriggerWidth, trapFocus, initialFocus, flush, className, children, ...rest }: PopoverContentProps): import("react/jsx-runtime").JSX.Element;
+declare function PopoverContent({ side, align, size, width, trapFocus, initialFocus, flush, className, children, ...rest }: PopoverContentProps): import("react/jsx-runtime").JSX.Element;
 declare namespace PopoverContent {
     var displayName: string;
 }
@@ -106,7 +129,7 @@ declare namespace PopoverDescription {
 export type PopoverActionsProps = React.HTMLAttributes<HTMLDivElement> & {
     ref?: React.Ref<HTMLDivElement>;
 };
-/** Buttons at the bottom of the panel: at the end, `gap: 8`; stacked full width on a narrow screen. */
+/** Buttons at the bottom of the panel: at the end, `gap: 8`; stacked full width in a bottom sheet. */
 declare function PopoverActions({ className, ...rest }: PopoverActionsProps): import("react/jsx-runtime").JSX.Element;
 declare namespace PopoverActions {
     var displayName: string;

package/dist/components/progress-bar/ProgressBar.d.ts

@@ -4,17 +4,19 @@ import type { ControlSize } from "../../internal/states";
 export type ProgressBarLabels = ProgressSegmentsLabels;
 export type ProgressBarProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
     /**
-     * Visible label above the bar and its accessible name. A `value` bar needs a name: `label`, or
-     * `aria-label` when the text around it already says what is loading.
+     * Visible label above the line and its accessible name; a value bar without it needs `aria-label`.
      */
     label?: string;
-    /** Default `m`. */
+    /**
+     * Line thickness 4 → 8 px (`--prime-control-<tier>-track`, shared with Slider) and label type. Without it the tier of its host, else `m`.
+     */
     size?: ControlSize;
-    /** Shows the rounded filled percentage at the end of the label row (`bar` layout). */
+    /**
+     * Shows the rounded filled percentage at the end of the label row (`aria-hidden`); `bar` layout only.
+     */
     showValue?: boolean;
     /**
-     * The data is on its way: a Skeleton in the bar's geometry (and of the legend or rows), which
-     * cross-fades into the data. The label stays; the root is `aria-busy`.
+     * The data is on its way: a Skeleton in the bar's geometry cross-fades into the data; the label stays. Pass the last known `value` or `segments` (or `0` / `[]`).
      */
     loading?: boolean;
     ref?: React.Ref<HTMLDivElement>;
@@ -27,24 +29,47 @@ type ProgressBarModeProps = (Extract<ProgressModeProps, {
     value: number;
 }> & {
     /**
-     * Draws the scale as `max` equal cells (2–12), each filled whole: a level out of a few
-     * (password strength, a step of onboarding). `value` rounds to a whole cell.
+     * Value mode: draws the scale as `max` equal cells (2–12), each filled whole; `value` rounds to a cell. For a level out of a few: password strength, onboarding steps.
      */
     steps?: boolean;
+    /**
+     * Segments mode: `bar` — every part in one bar; `rows` — a ranking: an `<ol>`, one row per part with label · value · share over its own bar.
+     */
     layout?: never;
+    /**
+     * Segments mode: `rows` only: what 100% is. `sum` — bars and shares of the total (`max` raises it); `max` — the leader is a full bar, shares stay of the total; `first` — bars and shares against the first row (a funnel).
+     */
     scale?: never;
 }) | (SegmentsModeProps & {
+    /**
+     * Value mode: draws the scale as `max` equal cells (2–12), each filled whole; `value` rounds to a cell. For a level out of a few: password strength, onboarding steps.
+     */
     steps?: never;
 } & ({
-    /** `bar`: every part in one bar. Default. */
+    /**
+     * Segments mode: `bar` — every part in one bar; `rows` — a ranking: an `<ol>`, one row per part with label · value · share over its own bar.
+     */
     layout?: "bar";
+    /**
+     * Segments mode: `rows` only: what 100% is. `sum` — bars and shares of the total (`max` raises it); `max` — the leader is a full bar, shares stay of the total; `first` — bars and shares against the first row (a funnel).
+     */
     scale?: never;
 } | {
-    /** `rows`: a ranking — one row per part, «label · value · share» over its own bar. */
+    /**
+     * Segments mode: `bar` — every part in one bar; `rows` — a ranking: an `<ol>`, one row per part with label · value · share over its own bar.
+     */
     layout: "rows";
-    /** What a full bar and 100% mean. Default `sum`. */
+    /**
+     * Segments mode: `rows` only: what 100% is. `sum` — bars and shares of the total (`max` raises it); `max` — the leader is a full bar, shares stay of the total; `first` — bars and shares against the first row (a funnel).
+     */
     scale?: ProgressScale;
+    /**
+     * Segments mode: `none` — one continuous pill; `hairline` — every part and the rest are separate pills. `bar` layout.
+     */
     segmentGap?: never;
+    /**
+     * Segments mode: a legend under the bar, one row per part: color · name · value · share; it becomes the group's description. `bar` layout.
+     */
     legend?: never;
 }));
 /**
@@ -52,5 +77,5 @@ type ProgressBarModeProps = (Extract<ProgressModeProps, {
  * parts of a whole in one bar (`role="group"` named by the distribution) with an optional legend,
  * or `layout="rows"` — a ranking, one labelled bar per part (`<ol>`).
  */
-export declare function ProgressBar(props: ProgressBarProps): import("react/jsx-runtime").JSX.Element;
+export declare function ProgressBar(props: ProgressBarProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 export {};

package/dist/components/progress-circle/ProgressCircle.d.ts

@@ -4,42 +4,61 @@ import type { ControlSize, Tone } from "../../internal/states";
 export type ProgressCircleLabels = ProgressSegmentsLabels;
 type ValueModeProps = {
     /**
-     * Current value, clamped to `0…max`; `null` — under way, the share unknown: a quarter arc that
-     * always turns, no `aria-valuenow`.
+     * Value mode: the current value, clamped to `0…max`; it glides to a new value (`base`). `null` — under way, the share unknown: a quarter arc that always turns, no `aria-valuenow`.
      */
     value: number | null;
-    /** Top of the scale. Default `100`. */
+    /**
+     * Value mode: top of the scale. Segments mode: total capacity; the sum of the parts closes the ring, a larger `max` leaves the rest as track.
+     */
     max?: number;
     /**
-     * Fill color. Default `accent`. `inherit` — the arc in the host's text color over a 32% track of
-     * it, for a ring on a colored host or over media.
+     * Value mode: arc color, telling the outcome. `inherit` — the arc in the host's text color over a 32% track of it, for a ring on a colored host or over media.
      */
     tone?: Tone | "inherit";
-    /** The ring turns at any share (a sync whose share grows). Default `false`; `null` always turns. */
+    /**
+     * Value mode: the ring turns at any share (one turn = 3 × `--prime-motion-loop`; slower under reduced motion, never still) and the arc never drops under 8%: a sync whose share grows. `null` always turns.
+     */
     spin?: boolean;
+    /**
+     * Segments mode: parts in order, `{ value, label?, tone? | color? }`: `tone` names a meaning (default `accent`), `color` a category — its step of the chart palette. Each part's length is its share of `max`.
+     */
     segments?: never;
+    /**
+     * Segments mode: `none` — one continuous ring; `hairline` — every part and the rest are separate round arcs.
+     */
     segmentGap?: never;
+    /**
+     * Segments mode: built-in strings, see Labels.
+     */
     labels?: never;
+    /**
+     * Segments mode: a legend beside the ring (below it when narrow), one row per part: color · name · value · share; with `aria-label` it becomes the group's description. The root turns into the row of ring and legend.
+     */
     legend?: never;
+    /**
+     * Segments mode: display of a part's value in the legend («38 ГБ»).
+     */
     formatValue?: never;
 };
 type SegmentsModeProps = Extract<ProgressModeProps, {
     segments: ProgressSegment[];
 }> & {
+    /**
+     * Value mode: the ring turns at any share (one turn = 3 × `--prime-motion-loop`; slower under reduced motion, never still) and the arc never drops under 8%: a sync whose share grows. `null` always turns.
+     */
     spin?: never;
 };
 export type ProgressCircleProps = Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
-    /** Default `m`. */
+    /**
+     * Diameter 24 · 32 · 48 · 64 · 80 px; the stroke is 1/12 of it. Without it the ring takes the tier of a sized host.
+     */
     size?: ControlSize;
     /**
-     * Centered content: a number, a percent or an `<Icon>`. A changed icon (another `name`) cross-
-     * fades into the new one. Not rendered on `xs`; text only from `m`. A string or number child
-     * stays available as `aria-valuetext`.
+     * Content in the center (number, percent, `Icon`): text from `m`, an icon from `s`, nothing on `xs`. A string or number also becomes `aria-valuetext`.
      */
     children?: React.ReactNode;
     /**
-     * The data is on its way: a Skeleton ring of the same size (and legend rows), which cross-fades
-     * into the data. The root is `aria-busy`.
+     * The data is on its way: a Skeleton ring of the same diameter and stroke (and legend lines) that cross-fades into the data; the inner content waits, the root is `aria-busy`.
      */
     loading?: boolean;
     ref?: React.Ref<HTMLDivElement>;
@@ -50,5 +69,5 @@ export type ProgressCircleProps = Omit<React.HTMLAttributes<HTMLDivElement>, "ch
  * clockwise from the top (`role="group"` described by the distribution), with an optional legend
  * beside the ring.
  */
-export declare function ProgressCircle(props: ProgressCircleProps): import("react/jsx-runtime").JSX.Element;
+export declare function ProgressCircle(props: ProgressCircleProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
 export {};

package/dist/components/radio/Radio.d.ts

@@ -6,33 +6,71 @@ export type RadioGroupLabels = {
     /** Muted marker after the group label when `optional`. */
     optional: string;
 };
+export declare const RADIO_GROUP_LABELS: RadioGroupLabels;
 export type RadioGroupProps = Omit<FieldRootDomProps, "dir"> & {
+    /**
+     * Controlled value (the `value` of the chosen `Radio.Root`).
+     */
     value?: string;
+    /**
+     * Initial value when uncontrolled.
+     */
     defaultValue?: string;
+    /**
+     * Called with the value of the newly chosen option.
+     */
     onValueChange?: (value: string) => void;
-    /** Native `name` shared by the radios; generated when omitted. */
+    /**
+     * Native `name` shared by the radios; generated when omitted.
+     */
     name?: string;
-    /** Tier. Default: the tier of the surrounding control (a form, a panel), else `m`. */
+    /**
+     * Tier of every circle, text, the label and the hint. Without it the group takes the tier of its host (LoginForm, Popover, a panel with a size), else `m`.
+     */
     size?: ControlSize;
+    /**
+     * Disables every option.
+     */
     disabled?: boolean;
-    /** Group heading above the options; names the radiogroup (`aria-labelledby`). */
+    /**
+     * Group heading above the options; names the radiogroup through `aria-labelledby`. Without it, pass `aria-label`.
+     */
     label?: React.ReactNode;
-    /** Red `*` after the label, native `required` on the radios, `aria-required` on the group. */
+    /**
+     * Red `*` after the label, native `required` on the radios and `aria-required` on the group.
+     */
     required?: boolean;
-    /** Muted `labels.optional` marker after the label. */
+    /**
+     * Muted marker right after the label text (`labels.optional`).
+     */
     optional?: boolean;
-    /** Help text under the options. Hidden while `error` is shown. */
+    /**
+     * Help text under the options. Hidden while `error` is shown.
+     */
     hint?: React.ReactNode;
-    /** Error message under the options; implies `invalid`. */
+    /**
+     * Error message under the options; implies `invalid`.
+     */
     error?: React.ReactNode;
-    /** Invalid state for every radio (`aria-invalid` on the group and the inputs). */
+    /**
+     * Danger ring on the unchecked circles and `aria-invalid` on the group and the inputs. A non-empty `error` implies it.
+     */
     invalid?: boolean;
-    /** `vertical` stacks the options, `horizontal` lays them out in a wrapping row. */
+    /**
+     * `vertical` stacks the options; `horizontal` lays them out in a wrapping row. Sets `aria-orientation`.
+     */
     orientation?: "vertical" | "horizontal";
-    /** Id of the `role="radiogroup"` element; generated when omitted. */
+    /**
+     * Id of the `role="radiogroup"` element (generated when omitted); also the default `name`.
+     */
     id?: string;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<RadioGroupLabels>;
-    /** `Radio.Root` options. */
+    /**
+     * The `Radio.Root` options.
+     */
     children?: React.ReactNode;
 };
 /**
@@ -44,13 +82,18 @@ declare namespace RadioGroup {
     var displayName: string;
 }
 export type RadioRootProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "size" | "checked" | "defaultChecked" | "onChange" | "name" | "value"> & {
-    /** Value reported to `Radio.Group` when this option is chosen. */
+    /**
+     * Value reported to the group when this option is chosen.
+     */
     value: string;
-    /** Description under the option text. */
+    /**
+     * Description under the option text, linked through `aria-describedby`.
+     */
     hint?: React.ReactNode;
-    /** `Radio.Label`; without it only the circle renders (give it an `aria-label`). */
+    /**
+     * `Radio.Label`. Without it only the circle renders — give the root an `aria-label`.
+     */
     children?: React.ReactNode;
-    /** The native radio input. */
     ref?: React.Ref<HTMLInputElement>;
 };
 declare function RadioRoot({ id, value, hint, disabled: disabledProp, className, "aria-describedby": ariaDescribedBy, children, ref, ...inputRest }: RadioRootProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/scroll-container/ScrollContainer.d.ts

@@ -8,31 +8,45 @@ export type ScrollContainerAxis = "vertical" | "horizontal" | "both";
  */
 export type ScrollContainerEdges = "fade" | "shadow" | "none";
 export type ScrollContainerProps = React.HTMLAttributes<HTMLElement> & {
-    /** Root element. Default `div`; `AppShell.Main` renders `main`. */
-    as?: "div" | "main" | "aside" | "section" | "nav" | "article";
-    /** Scroll axis. Default `vertical`. */
+    /**
+     * Root element; a landmark tag when the region is one, `pre` for preformatted text (CodeBlock).
+     */
+    as?: "div" | "main" | "aside" | "section" | "nav" | "article" | "pre";
+    /**
+     * Scroll axis; the other axis is clipped (except `both`). On `horizontal` a vertical mouse wheel scrolls the strip sideways.
+     */
     axis?: ScrollContainerAxis;
-    /** `overscroll-behavior`. Default `contain`: nested panels do not chain scroll into the page. */
+    /**
+     * CSS `overscroll-behavior`; `contain` stops scroll chaining into the page.
+     */
     overscrollBehavior?: "auto" | "contain" | "none";
-    /** The edges where more content is hidden, along every scroll axis. Default `fade`. */
+    /**
+     * Edges that hide content: `fade` dissolves them over any background; `shadow` — a soft shadow on the region's own fill (a floating panel, a code well); `none` — plain edges.
+     */
     edges?: ScrollContainerEdges;
-    /** `thin` — the kit's quiet scrollbar (default); `hidden` — no scrollbar (keep `edges`). */
+    /**
+     * `thin` — the kit's quiet scrollbar; `hidden` — no scrollbar, keep `edges` on so the overflow stays visible.
+     */
     scrollbar?: "thin" | "hidden";
-    /** The person cannot scroll the region (wheel, touch, keys, autoscroll); it keeps its place. */
+    /**
+     * The person cannot scroll the region (wheel, touch, keys, a drag's auto-scroll); code still can. Sets `data-lock`.
+     */
     lock?: boolean;
-    /** Scrolling comes to rest on the start of a child (proximity snapping): strips of tiles. */
-    snap?: boolean;
     /**
-     * `end` — a chat or a log: the region starts at the end and stays there while content arrives,
-     * as long as the person is at the end; scrolled away, what they look at stays put. Default `start`.
+     * Scrolling comes to rest on the start of a child: `true` near one (strips of tiles and cards), `"mandatory"` always on one (board columns, a carousel). A Dnd drag inside turns it off; not with `anchor="end"`.
+     */
+    snap?: boolean | "mandatory";
+    /**
+     * `end` — a chat or a log: opens at the end and follows new content while the person is at the end; scrolled away, the view holds still.
      */
     anchor?: "start" | "end";
     /**
-     * The scroll position came near the start (older messages). A returned promise is pending until
-     * it settles: no new call meanwhile, `aria-busy`. Content added above keeps the view in place.
+     * Fires within 120 px of the start, once per approach: load older content. A returned promise blocks repeats and sets `aria-busy`; content added above keeps the view.
      */
     onReachStart?: ScrollEdgeHandler;
-    /** The scroll position came near the end (the next page of a feed); a promise works the same. */
+    /**
+     * The scroll position came within 120 px of the end: load the next page. Same once-per-approach and promise rules as `onReachStart`.
+     */
     onReachEnd?: ScrollEdgeHandler;
     ref?: React.Ref<HTMLElement>;
 };