prime-ui-kit 0.14.0 → 0.16.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/page-content/PageContent.d.ts

@@ -1,25 +1,25 @@
 import * as React from "react";
 /** Cap of the page column inside `main`. */
 export type PageContentMaxWidth = "full" | "readable" | "wide";
-export type PageContentRootProps = React.HTMLAttributes<HTMLDivElement> & {
+/** The element of the page column: a plain column, or a `<section>` that a heading names. */
+export type PageContentRootAs = "div" | "section";
+export type PageContentRootProps = React.HTMLAttributes<HTMLElement> & {
+    /**
+     * `section` — the whole app page as a region; name it with `aria-labelledby` → the Title `id`.
+     */
+    as?: PageContentRootAs;
+    /**
+     * Cap of the column, centred: `full` — the whole main; `readable` — the reading measure `--prime-layout-reading-max-width` (42rem); `wide` — the content width `--prime-layout-content-max-width` (75rem).
+     */
     maxWidth?: PageContentMaxWidth;
     /**
-     * The page takes the height of the panel (`AppShell.Root fillViewport`): the body gets what the
-     * header leaves, for a full-height table, board, chat or `PageContent.Split`.
+     * The page takes the height of main (`AppShell.Root fillViewport`) and the body takes what the header leaves: for a full-height table, board, chat or `PageContent.Split`.
      */
     fill?: boolean;
-    ref?: React.Ref<HTMLDivElement>;
-};
-declare function PageContentRoot({ maxWidth, fill, className, ...rest }: PageContentRootProps): import("react/jsx-runtime").JSX.Element;
-declare namespace PageContentRoot {
-    var displayName: string;
-}
-export type PageContentPageProps = React.HTMLAttributes<HTMLElement> & {
     ref?: React.Ref<HTMLElement>;
 };
-/** The whole page as a `<section>` (full panel width): `Header` with the one h1, then `Body`. */
-declare function PageContentPage({ className, ...rest }: PageContentPageProps): import("react/jsx-runtime").JSX.Element;
-declare namespace PageContentPage {
+declare function PageContentRoot({ as: Tag, maxWidth, fill, className, ref, ...rest }: PageContentRootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageContentRoot {
     var displayName: string;
 }
 type DivProps = React.HTMLAttributes<HTMLDivElement> & {
@@ -46,7 +46,9 @@ declare namespace PageContentTitle {
 }
 export type PageContentDescriptionMeasure = "readable" | "full";
 export type PageContentDescriptionProps = React.HTMLAttributes<HTMLParagraphElement> & {
-    /** `readable` — max ~65ch; `full` — the full width of the parent (e.g. an already padded `main`). */
+    /**
+     * `readable` — no wider than the reading measure `--prime-layout-reading-max-width` (42rem); `full` — the full width of the parent.
+     */
     measure?: PageContentDescriptionMeasure;
     ref?: React.Ref<HTMLParagraphElement>;
 };
@@ -62,13 +64,16 @@ declare namespace PageContentBody {
 /** Where the heading of a section stands: over its content or in a column beside it. */
 export type PageContentSectionLayout = "stack" | "aside";
 export type PageContentSectionProps = Omit<React.HTMLAttributes<HTMLElement>, "title"> & {
-    /** The visible heading of the section (an `h2`). */
+    /**
+     * The visible heading (`h2`); it also names the section.
+     */
     label: React.ReactNode;
-    /** One line of context under the heading. */
+    /**
+     * One line of context under the heading, in secondary body-s.
+     */
     description?: React.ReactNode;
     /**
-     * `stack` — the heading over the content; `aside` — a heading column beside the content (a
-     * settings page), dropping above it once the content would get narrower than 30rem.
+     * `stack` — the heading over the content; `aside` — a ~16rem heading column beside it (a settings page), above it once the content would get narrower than 30rem.
      */
     layout?: PageContentSectionLayout;
     ref?: React.Ref<HTMLElement>;
@@ -96,9 +101,13 @@ export type PageContentCellSpan = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 |
 /** Rows a cell spans. */
 export type PageContentCellRows = 1 | 2 | 3 | 4;
 export type PageContentCellProps = DivProps & {
-    /** Columns of 12 on a wide grid; a medium grid rounds to half or full, a narrow one to full. */
+    /**
+     * Columns of 12 on a wide grid (64rem+). Narrower grids round it: see Grid columns in COMPONENT.md.
+     */
     span?: PageContentCellSpan;
-    /** Rows the cell spans; its child fills the height. */
+    /**
+     * Rows the cell spans from 40rem: a chart beside two stacked tiles (`ChartFrame.Plot height="fill"` fills the height).
+     */
     rows?: PageContentCellRows;
 };
 /** One tile place in `PageContent.Grid`; its child (a Card, a ChartFrame) fills it. */
@@ -110,16 +119,23 @@ export type PageContentLabels = {
     /** Name of `PageContent.BackButton` (back from the detail to the list on a narrow split). */
     back: string;
 };
+export declare const PAGE_CONTENT_LABELS: PageContentLabels;
 export type PageContentSplitProps = DivProps & {
     /**
-     * The detail is open (a record is chosen). On a narrow split it takes the place of the list;
-     * on a wide one both panes stay. Controlled.
+     * The detail is open (a record is chosen), controlled. On a narrow split it takes the place of the list; on a wide one both panes stay.
      */
     open?: boolean;
-    /** Initial open state, uncontrolled. */
+    /**
+     * Initial open state, uncontrolled.
+     */
     defaultOpen?: boolean;
-    /** `PageContent.BackButton` closes the detail: `false`. */
+    /**
+     * `PageContent.BackButton` closes the detail (`false`); clear the chosen record there.
+     */
     onOpenChange?: (open: boolean) => void;
+    /**
+     * Built-in strings, see Labels.
+     */
     labels?: Partial<PageContentLabels>;
 };
 /**
@@ -131,16 +147,21 @@ declare function PageContentSplit({ open: openProp, defaultOpen, onOpenChange, l
 declare namespace PageContentSplit {
     var displayName: string;
 }
-export type PageContentListProps = DivProps;
-/** The list pane: a fixed column on a wide split, the whole split while the detail is closed. */
-declare function PageContentList({ className, ref, onFocus, onAnimationEnd, ...rest }: PageContentListProps): import("react/jsx-runtime").JSX.Element;
-declare namespace PageContentList {
-    var displayName: string;
-}
-export type PageContentDetailProps = DivProps;
-/** The detail pane: the rest of a wide split; on a narrow one it replaces the list while open. */
-declare function PageContentDetail({ className, ref, onAnimationEnd, ...rest }: PageContentDetailProps): import("react/jsx-runtime").JSX.Element;
-declare namespace PageContentDetail {
+/** Which pane of the split a panel is. */
+export type PageContentPanelKind = "list" | "detail";
+export type PageContentPanelProps = DivProps & {
+    /**
+     * `list` — the 16–20rem column, or the whole split while closed; going back refocuses its last control. `detail` — the rest, or the whole split while open; focus lands here when it opens.
+     */
+    kind: PageContentPanelKind;
+};
+/**
+ * A pane of the split. `list` — a fixed column on a wide split, the whole split while the detail
+ * is closed; it remembers the control that had focus, so going back returns there. `detail` — the
+ * rest of a wide split; on a narrow one it replaces the list while open.
+ */
+declare function PageContentPanel({ kind, className, ref, onFocus, onAnimationEnd, ...rest }: PageContentPanelProps): import("react/jsx-runtime").JSX.Element;
+declare namespace PageContentPanel {
     var displayName: string;
 }
 export type PageContentBackButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children"> & {
@@ -156,7 +177,6 @@ declare namespace PageContentBackButton {
 }
 export declare const PageContent: {
     Root: typeof PageContentRoot;
-    Page: typeof PageContentPage;
     Header: typeof PageContentHeader;
     Actions: typeof PageContentActions;
     Title: typeof PageContentTitle;
@@ -166,8 +186,7 @@ export declare const PageContent: {
     Grid: typeof PageContentGrid;
     Cell: typeof PageContentCell;
     Split: typeof PageContentSplit;
-    List: typeof PageContentList;
-    Detail: typeof PageContentDetail;
+    Panel: typeof PageContentPanel;
     BackButton: typeof PageContentBackButton;
 };
 export {};

package/dist/components/page-toolbar/PageToolbar.d.ts

@@ -1,13 +1,14 @@
-import * as React from "react";
+import type * as React from "react";
 type DivProps = React.HTMLAttributes<HTMLDivElement> & {
     ref?: React.Ref<HTMLDivElement>;
 };
 export type PageToolbarRootProps = DivProps;
 /**
  * The panel at the top of a page: search and filter, sections, view options and the primary
- * action, with the active filters right under the search. It lays itself out from its own width —
- * one row when wide, stacked rows when narrow — so the slots keep fixed places at any width. Parts
- * may be left out; the JSX order is the Tab order.
+ * action, with the active filters under the top row. It lays itself out from its own width — one
+ * row when wide, stacked rows when narrow — so the slots keep fixed places at any width. Parts may
+ * be left out; whatever the JSX order, the DOM (and Tab) order is Tools, Sections, View, Actions,
+ * Chips. Named (`aria-label`), it is a `group`.
  */
 declare function PageToolbarRoot({ className, children, ref, ...rest }: PageToolbarRootProps): import("react/jsx-runtime").JSX.Element;
 declare namespace PageToolbarRoot {
@@ -20,7 +21,7 @@ declare namespace PageToolbarSections {
     var displayName: string;
 }
 export type PageToolbarToolsProps = DivProps;
-/** Search and filter button (`SmartFilter.Toolbar`): the first slot and the stretchy one, the Chips sit right under it. */
+/** Search and filter button (`SmartFilter.Toolbar`): the first slot and the stretchy one; the Chips sit under the top row. */
 declare function PageToolbarTools({ className, ...rest }: PageToolbarToolsProps): import("react/jsx-runtime").JSX.Element;
 declare namespace PageToolbarTools {
     var displayName: string;
@@ -38,7 +39,7 @@ declare namespace PageToolbarActions {
     var displayName: string;
 }
 export type PageToolbarChipsProps = DivProps;
-/** Active filters (`SmartFilter.Chips`) in their own row right under the search; the row disappears when empty. */
+/** Active filters (`SmartFilter.Chips`) in their own row under the top row; the row disappears when empty. */
 declare function PageToolbarChips({ className, ...rest }: PageToolbarChipsProps): import("react/jsx-runtime").JSX.Element;
 declare namespace PageToolbarChips {
     var displayName: string;

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

@@ -11,21 +11,40 @@ 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;
+    /**
+     * 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, 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, from the panel minimum to twice that. `trigger`: exactly the trigger's width, below the minimum too. `content`: what the content needs, within the viewport. 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 {};