prime-ui-kit 0.10.0 → 0.11.1

package/src/components/popover/COMPONENT.md

@@ -54,22 +54,23 @@ No DOM, no ref. Open state and dismiss policy.
 | `children` | `ReactNode` | — (required) | Trigger (or Anchor) and Content. |
 
 ### Popover.Trigger · Popover.Anchor · Popover.Close
-No DOM: clone the single child and merge `ref` and `onClick`. Trigger toggles the panel and adds `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`, `data-state` (the child's own `id` wins); Anchor only positions the panel and keeps presses on it from dismissing (open state comes from `open`; focus stays in the anchor on open); Close closes the panel (focus back on the trigger) unless the child's handler calls `preventDefault()`. Other props given to Trigger (handlers, ARIA, `ref`) reach the child, so a wrapping `Tooltip.Trigger` keeps working.
+No DOM: clone the single child and merge `ref` and `onClick`. Trigger toggles the panel and sets its ARIA; Anchor only positions the panel (open state comes from `open`); Close closes the panel.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactElement` | — (required) | One element, usually a Button (Anchor: any element, e.g. a toolbar). |
 
 ### Popover.Content
-`ref` → `HTMLDivElement`. Portal + `role="dialog"` on the floating surface (a ScrollContainer); renders while open and during its exit animation. Named by `Popover.Title`, else by the trigger. Opened from a Trigger, focus moves into the panel (`[data-autofocus]`, else the first tab stop, else the panel). Below 640px of viewport a panel opened from a Trigger (not an Anchor) is a bottom sheet: a scrim, a grab handle, swipe down to close (with `closeOnOutsideClick`), page scroll locked.
+`ref` → `HTMLDivElement`. Portal + `role="dialog"` floating panel that scrolls inside, named by `Popover.Title`. Below 640px of viewport, opened from a Trigger, it is a bottom sheet.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Preferred side; flips to the opposite side when there is no room. |
-| `align` | `"start" \| "center" \| "end"` | `"start"` | Alignment along the trigger; shifts inside the viewport. |
+| `align` | `"auto" \| "start" \| "center" \| "end"` | `"auto"` | 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. |
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier of the text, padding and gap; also the size context of the controls inside. |
 | `matchTriggerWidth` | `boolean` | `false` | The panel is exactly as wide as the trigger and its text wraps. |
 | `trapFocus` | `boolean` | `false` | 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. |
+| `initialFocus` | `boolean` | `true with Trigger, false with Anchor` | 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. |
 | `flush` | `boolean` | `false` | No inner padding and no gap: rows and dividers reach the panel edges; the content lays out its own spacing. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "role">` | — | `className` and the other attributes of the panel. |
 
@@ -96,9 +97,10 @@ Title uses the tier text size with title weight; Description uses the tier label
 | `side="bottom"` | Below the trigger, `--prime-panel-offset` away | Default | yes |
 | `side="top"` | Above the trigger | Triggers near the bottom of the screen | |
 | `side="left"` / `"right"` | Beside the trigger, aligned along its height | Triggers in a side rail or a narrow column | |
-| `align="start"` | Start edges aligned | Default | yes |
+| `align="auto"` | Lined up with the trigger edge that has more room: near the end of the screen the end edges meet and the panel grows toward the start, near the start the other way; below the trigger, flipping to the top without room | Default — triggers anywhere | yes |
+| `align="end"` | End edges aligned: the panel grows toward the start | The panel must line up with the end of a block whatever room there is | |
 | `align="center"` | Centred on the trigger | Small icon triggers | |
-| `align="end"` | End edges aligned | Triggers at the end of a toolbar | |
+| `align="start"` | Start edges aligned: the panel grows toward the end | The panel must line up with the start of a block whatever room there is | |
 
 ### Flags
 | Value | Looks like | Use when | Default |
@@ -125,6 +127,8 @@ Title uses the tier text size with title weight; Description uses the tier label
 
 There is no `disabled` on Popover: a disabled trigger never opens it.
 
+Motion (`overlayMotion`): the panel grows out of the side that faces its trigger and fades, in and out over `fast`; as a sheet it slides up over `slow` and down over `base`. Content stays mounted until the exit ends; under `prefers-reduced-motion` it unmounts at once.
+
 ## Layout & spacing
 - Width is `max-content` between `--prime-panel-min-width` and twice that, never wider than the viewport; give forms an explicit width with `className`.
 - Max height follows the free space on the resolved side; the panel scrolls inside.
@@ -142,7 +146,9 @@ There is no `disabled` on Popover: a disabled trigger never opens it.
 
 ### ARIA
 - The panel is `role="dialog"` without `aria-modal`, named by `Popover.Title` (else by the trigger) and described by `Popover.Description`.
-- The trigger gets `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`.
+- The trigger gets `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` and `data-state`; the child's own `id` wins. Other props given to `Popover.Trigger` (handlers, ARIA, `ref`) reach the child, so a wrapping `Tooltip.Trigger` keeps working.
+- Opened from a Trigger, focus moves into the panel: `[data-autofocus]`, else the first tab stop, else the panel. Opened at a `Popover.Anchor`, focus stays in the anchor (`initialFocus` moves it in), and presses on the anchor do not dismiss the panel.
+- `Popover.Close` closes the panel and returns focus to the trigger, unless the child's own `onClick` calls `preventDefault()`.
 - An outside press closes the panel without moving focus back to the trigger: focus follows the pointer (foundation §8).
 - Only the topmost layer reacts: a Select open inside the panel closes first.
 
@@ -160,11 +166,13 @@ No `labels`.
 | [placement.tsx](examples/placement.tsx) | Every side and alignment relative to the trigger; near the viewport edge the panel flips and shifts — `side`, `align`. |
 | [match-trigger-width.tsx](examples/match-trigger-width.tsx) | In a narrow column the panel takes the exact width of a full-width trigger and its text wraps — `matchTriggerWidth`. |
 | [flush.tsx](examples/flush.tsx) | A notification list whose rows and dividers reach the panel edges; each row brings its own padding — `flush`. |
+| [from-menu.tsx](examples/from-menu.tsx) | A menu command opens a panel at the same button: the rename item shows a form anchored to the menu button and focus lands in its field, not back on that button — `Popover.Anchor`, `initialFocus`. |
 | [dismiss.tsx](examples/dismiss.tsx) | A destructive confirm that closes only from its buttons, and not at all while the request runs — `closeOnOutsideClick`, `closeOnEscape`. |
 | [controlled-open.tsx](examples/controlled-open.tsx) | The parent owns the open state: another button opens the panel from code and its own button closes it — `open`, `onOpenChange`. |
 | [in-form.tsx](examples/in-form.tsx) | An invite form in a panel: Tab stays inside, the role list does not count as an outside click, an invalid email shakes the field and keeps the panel open until it is fixed — `trapFocus`, `error`. |
 
 ## Mistakes
+- A Popover opened from a Dropdown item with `Popover.Anchor` and no `initialFocus` → focus returns to the menu button and the panel is out of keyboard reach; set `initialFocus`.
 - A hint of a few words in a Popover → use Tooltip (hover / focus, no interactive content).
 - A form without `trapFocus` → add it so Tab stays in the panel.
 - Closing from inside through your own `open` state only → wrap the button in `Popover.Close`.
@@ -172,4 +180,4 @@ No `labels`.
 
 ## Related
 - **Built from:** [ScrollContainer](../scroll-container/COMPONENT.md) (the panel)
-- **See also:** [Tooltip](../tooltip/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [Modal](../modal/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [ColorPicker](../color-picker/COMPONENT.md)
+- **See also:** [Tooltip](../tooltip/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md), [Modal](../modal/COMPONENT.md), [Drawer](../drawer/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [ColorPicker](../color-picker/COMPONENT.md)

package/src/components/popover/examples/examples.module.css

@@ -42,3 +42,8 @@
   justify-content: flex-end;
   padding: var(--prime-space-1);
 }
+
+/* from-menu.tsx: the anchor box around the menu button. */
+.anchor {
+  display: inline-flex;
+}

package/src/components/popover/examples/from-menu.tsx

@@ -0,0 +1,56 @@
+/** A menu command opens a panel at the same button: the rename item shows a form anchored to the menu button and focus lands in its field, not back on that button — `Popover.Anchor`, `initialFocus`. */
+import { Button, Dropdown, Icon, Input, Popover } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function PopoverFromMenuExample() {
+  const [renaming, setRenaming] = React.useState(false);
+  const [name, setName] = React.useState("Запуск в регионах");
+
+  return (
+    <Popover.Root open={renaming} onOpenChange={setRenaming}>
+      <Popover.Anchor>
+        <span className={styles.anchor}>
+          <Dropdown.Root>
+            <Dropdown.Trigger>
+              <Button.Root variant="ghost" tone="neutral" aria-label="Действия с проектом">
+                <Button.Icon>
+                  <Icon name="action.more" />
+                </Button.Icon>
+              </Button.Root>
+            </Dropdown.Trigger>
+            <Dropdown.Content>
+              <Dropdown.Item onSelect={() => setRenaming(true)}>Переименовать…</Dropdown.Item>
+              <Dropdown.Item>Дублировать</Dropdown.Item>
+            </Dropdown.Content>
+          </Dropdown.Root>
+        </span>
+      </Popover.Anchor>
+      <Popover.Content className={styles.panel} initialFocus trapFocus>
+        <form
+          className={styles.stack}
+          onSubmit={(event) => {
+            event.preventDefault();
+            setName(String(new FormData(event.currentTarget).get("name") ?? name));
+            setRenaming(false);
+          }}
+        >
+          <Input.Root label="Название проекта">
+            <Input.Wrapper>
+              <Input.Field name="name" defaultValue={name} />
+            </Input.Wrapper>
+          </Input.Root>
+          <Popover.Actions>
+            <Popover.Close>
+              <Button.Root variant="soft" tone="neutral">
+                Отмена
+              </Button.Root>
+            </Popover.Close>
+            <Button.Root type="submit">Сохранить</Button.Root>
+          </Popover.Actions>
+        </form>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

package/src/components/progress-bar/COMPONENT.md

@@ -3,18 +3,20 @@
 **Category:** status
 **Kind:** primitive
 
-> Linear progress: one value on a native `<progress>`, or `segments` that split a whole (storage by type, task statuses), with a label, a percentage and status colors.
+> Linear progress: one value on a native `<progress>`, `segments` that split a whole (storage by type, leads by source) with an optional legend, or a ranking of rows (top cities, a funnel).
 
 ## When to use
 - Determinate progress of an operation: file upload, import, export (`value`).
 - How much of a quota or a set of steps is done («Профиль: 3 из 5 шагов») (`value` + `max`).
-- How a whole splits into parts: used space by file type, tasks by status (`segments`, `max`).
+- How a whole splits into parts: used space by file type, tasks by status (`segments`, `max`); categories wear `color`, meanings wear `tone`; `legend` adds color · name · value · share.
+- A ranking «label · value · share — bar»: top cities, reasons, funnel steps (`layout="rows"`, `scale`).
 - Per-row progress inside lists (FileUpload rows render it).
 
 ## When not to use
 - A compact radial indicator or KPI ring → use [ProgressCircle](../progress-circle/COMPONENT.md) (same `value` / `segments` API).
 - Unknown duration → use [Spinner](../spinner/COMPONENT.md); ProgressBar has no indeterminate mode.
 - Navigation through wizard steps → use [Stepper](../stepper/COMPONENT.md).
+- A trend over time → use [Sparkline](../sparkline/COMPONENT.md) or a chart on `chartColors`.
 
 ## Import
 ```tsx
@@ -23,10 +25,13 @@ import { ProgressBar, type ProgressSegment } from "prime-ui-kit";
 
 ## Anatomy
 ```
-ProgressBar              <div>; size, tone (value mode)
+ProgressBar              <div>; size, tone (value mode), aria-busy while loading
 ├─ header                label (ellipsis) + percentage (showValue, aria-hidden)
 └─ value mode:           <progress> (transparent, for assistive tech) + drawn line
    segments mode:        <div role="group"> — parts pill + free rest; hidden distribution text
+   └─ legend             <ul>: swatch · name · value · share per part (legend)
+   rows layout:          <ol> — per part: label · value · share over its own bar
+   loading:              Skeleton bar (+ legend / row lines) in the same geometry
 ```
 
 ## API
@@ -40,7 +45,8 @@ ProgressBar              <div>; size, tone (value mode)
 |---|---|---|---|
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Line thickness 4 → 8 px (`--prime-control-<tier>-track`, shared with Slider) and label type. |
 | `label` | `string` | — | Visible label above the line and its accessible name; a value bar without it needs `aria-label`. |
-| `showValue` | `boolean` | `false` | Shows the rounded filled percentage at the end of the label row (`aria-hidden`). |
+| `showValue` | `boolean` | `false` | Shows the rounded filled percentage at the end of the label row (`aria-hidden`); `bar` layout only. |
+| `loading` | `boolean` | `false` | 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` / `[]`). |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className`, `data-*` and the other div attributes on the root; `aria-label` names the bar when there is no `label`. |
 
 ### ProgressBar · value mode
@@ -51,16 +57,20 @@ A native `<progress>` (transparent, for assistive tech) under the drawn line.
 | `value` | `number` | — (required) | The current value, clamped to `0…max`. |
 | `max` | `number` | `100` | Top of the scale. |
 | `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"accent"` | Fill color, telling the outcome. |
-| `steps` | `boolean` | `false` | Draws the scale as `max` equal cells (2–12), each filled whole; `value` rounds to a cell. In one change the cells go one after another — from the start when filling, from the end when emptying. For a level out of a few: password strength, onboarding steps. |
+| `steps` | `boolean` | `false` | 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. |
 
 ### ProgressBar · segments mode
-A `role="group"` bar of parts, named by `label` and described by the distribution text.
+A `role="group"` bar of parts, named by `label` and described by the legend or the distribution text; with `layout="rows"` an `<ol>` named by `label`.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `segments` | `ProgressSegment[]` | — (required) | Parts in order, `{ value, label?, tone? }` (`tone` default `accent`); each part's width is its share of `max`. |
+| `segments` | `ProgressSegment[]` | — (required) | Parts in order, `{ value, label?, tone? \| color? }`: `tone` names a meaning (default `accent`), `color` a category, as in its charts. Each part's width is its share of `max`. |
 | `max` | `number` | — | Total capacity. Default: the sum of the parts; a larger `max` leaves the rest as track. |
-| `segmentGap` | `"none" \| "hairline"` | `"none"` | `none` — one continuous pill; `hairline` — every part and the rest are separate pills. |
+| `segmentGap` | `"none" \| "hairline"` | `"none"` | `none` — one continuous pill; `hairline` — every part and the rest are separate pills. `bar` layout. |
+| `legend` | `boolean` | `false` | A legend under the bar, one row per part: color · name · value · share; it becomes the group's description. `bar` layout. |
+| `formatValue` | `(value: number) => string` | `Russian digit groups` | Display of a part's value in the legend and the rows («1 840 000 ₽»). |
+| `layout` | `"bar" \| "rows"` | `"bar"` | `bar` — every part in one bar; `rows` — a ranking: an `<ol>`, one row per part with label · value · share over its own bar. |
+| `scale` | `"sum" \| "max" \| "first"` | `"sum"` | `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). |
 | `labels` | `Partial<ProgressBarLabels>` | — | Built-in strings, see Labels. |
 
 ## Variants
@@ -75,6 +85,26 @@ A `role="group"` bar of parts, named by `label` and described by the distributio
 | `danger` | danger fill | failed or interrupted operation, overdue share | |
 | `info` | info fill | informational processes (sync, indexing) | |
 
+### color (each segment, instead of tone)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `blue` · `orange` · `teal` · `yellow` · `pink` · `green` · `purple` · `red` | the hue's step of the chart palette (`--prime-color-chart-1…8`, `--hue-chart`) | categories with no meaning of good or bad: sources, platforms, regions — the same color the category has in charts | |
+| `gray` | `--prime-color-chart-other` | the «Прочее» share | |
+| `sky` | the palette's sky solid (no chart step: it sits too close to blue) | only when the category is sky elsewhere in the product | |
+
+### layout (segments mode)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `bar` | every part in one bar, optional legend under it | parts of one whole | yes |
+| `rows` | one row per part: label · value · share over its own bar | a ranking: top cities, reasons, funnel steps | |
+
+### scale (`rows`)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `sum` | bars and shares of the total | parts of a whole («доля от всех заказов») | yes |
+| `max` | the leader is a full bar, shares of the total | a top list where the gap to the leader matters | |
+| `first` | bars and shares against the first row | a funnel: each step as a share of the first | |
+
 ### segmentGap
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
@@ -94,13 +124,17 @@ A `role="group"` bar of parts, named by `label` and described by the distributio
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `showValue` | secondary `NN%` at the end of the header | uploads, quotas — the user tracks the number | `false` |
+| `legend` | rows of swatch · name · value · share under the bar | a distribution the reader compares in numbers | `false` |
+| `loading` | a Skeleton bar (and legend or row lines) in the same geometry | the data is on its way | `false` |
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
 | tone / size | props | `data-tone` (value mode), `data-size` on the root |
 | value | `value`, `max` | native `value` / `max`; the drawn pill slides by `translate` over `slow` + `standard`, RTL aware |
-| segments | `segments`, `max`, `segmentGap` | `data-segment-gap` on the group, `data-tone` per part; widths animate by `flex-grow` over `slow` |
+| segments | `segments`, `max`, `segmentGap` | `data-segment-gap` on the group, `data-tone` or `data-color` per part; widths animate by `flex-grow` over `slow` |
+| rows | `layout="rows"`, `scale` | `data-layout="rows"` on the root, an `<ol>`; each bar slides like the value pill |
+| loading | `loading` | `aria-busy` on the root; Skeletons in place of the bar, the legend or the rows; the data cross-fades in (`swapMotion`) |
 | steps | `steps` (value mode) | `data-steps="true"` on the bar; `max` cells (2–12), filled ones `data-filled`; a cell fills from its start edge (`base` · emphasized), cells of one change go half a stagger step apart — from the start when filling, from the end when emptying |
 | empty segments | `segments` empty or all `0` | only the track; accessible text `labels.empty` / `labels.allEmpty` |
 | reduced motion | `prefers-reduced-motion` | fill, widths and cells change instantly |
@@ -109,7 +143,9 @@ Always controlled: pass the current `value` or `segments` on every render.
 
 ## Layout & spacing
 - `width: 100%` of the parent; the header is a row with the label (ellipsis) and the value.
-- Label → line: the tier `label-gap` (`--prime-space-1` xs/s, `--prime-space-2` m–xl).
+- Label → line: the tier `label-gap` (`--prime-space-1` xs/s, `--prime-space-2` m–xl). The label is primary, medium weight; the percentage secondary, tabular numbers.
+- Bar → legend `--prime-space-3` (12). Rows (`layout="rows"`) are 12 apart, each header 4 above its bar: the label (secondary, truncates) takes the free width, the value (primary, medium) and the share (muted, at least 4ch) line up at the end in tabular numbers.
+- `hairline` gaps and `steps` cells are ¾ of the line thickness apart.
 - Stack several bars with `--prime-space-4`–`--prime-space-5`.
 
 ## Accessibility
@@ -119,9 +155,11 @@ No keyboard interaction.
 
 ### ARIA
 - Value mode: native `<progress>` — role `progressbar` with value and max.
-- Segments mode: `role="group"`; its text lists the shares of `max` («Видео: 38%, Документы: 21%»). With `label` (or `aria-label`) the group is named by it and described by the distribution; without a name the distribution is the name.
+- Segments mode: `role="group"`; its text lists the shares of `max` («Видео: 38%, Документы: 21%»). With `label` (or `aria-label`) the group is named by it and described by the distribution — or by the legend when `legend` is on; without a name the distribution is the name.
+- Rows: an `<ol>` named by `label`; each row reads as text («Москва 1 284 52%»), the bars are `aria-hidden`.
+- A category color always sits beside its name (legend, row), so color is never the only cue.
 - Without `label`, pass `aria-label`, otherwise a value bar has no accessible name.
-- The `showValue` percentage is `aria-hidden`.
+- The `showValue` percentage is `aria-hidden`; while `loading` the root is `aria-busy` and the Skeletons are `aria-hidden`.
 
 ### Labels
 <!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
@@ -137,8 +175,11 @@ No keyboard interaction.
 | [overview.tsx](examples/overview.tsx) | An import in progress with its name and percentage — `value`, `label`, `showValue`. |
 | [variants.tsx](examples/variants.tsx) | Every fill color; the tone tells the outcome, not the progress — `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Every tier: the line grows from 4 to 8 px like the Slider track — `size`. |
+| [states.tsx](examples/states.tsx) | Loading takes the bar's own geometry, so the data lands without a jump — `loading`. |
 | [custom-max.tsx](examples/custom-max.tsx) | A scale of steps instead of percent: 3 of 5 profile steps — `max`. |
 | [segments.tsx](examples/segments.tsx) | Parts of a whole in one bar: joined or separate pills, free capacity up to `max` and an empty list — `segments`, `segmentGap`, `max`. |
+| [legend.tsx](examples/legend.tsx) | Shares of categories in their chart colors with a legend of color · name · value · share — `color`, `legend`, `formatValue`. |
+| [ranking.tsx](examples/ranking.tsx) | Rankings as rows of label · value · share over a bar: top cities against the leader and a funnel against its first step — `layout`, `scale`. |
 | [steps.tsx](examples/steps.tsx) | The scale as whole cells that fill one after another: 2 of 5 onboarding steps, forward and back — `steps`, `max`. |
 | [milestone.tsx](examples/milestone.tsx) | A rare milestone: the last invoice of the quarter fills the bar, the tone turns success and a short confetti burst marks it — `value`, `tone`, `celebrate()`. |
 
@@ -149,7 +190,10 @@ No keyboard interaction.
 - A «Свободно» segment for free space → pass `max`; the rest stays track.
 - `showValue` with a count scale («3 из 5») → put the count into `label`.
 - A fake value as a spinner → use [Spinner](../spinner/COMPONENT.md).
+- Categories (sources, platforms) painted with `tone` → `tone` says good or bad; categories take `color`, the same as in their charts.
+- The number written into `label` of each row of a hand-built ranking → `layout="rows"` with `formatValue`.
+- A grey box while the data loads → `loading` draws the Skeleton in the bar's geometry.
 
 ## Related
-- **Built from:** —
+- **Built from:** [Skeleton](../skeleton/COMPONENT.md)
 - **See also:** [ProgressCircle](../progress-circle/COMPONENT.md), [Slider](../slider/COMPONENT.md), [FileUpload](../file-upload/COMPONENT.md), [Spinner](../spinner/COMPONENT.md)

package/src/components/progress-bar/examples/legend.tsx

@@ -0,0 +1,28 @@
+/** Shares of categories in their chart colors with a legend of color · name · value · share — `color`, `legend`, `formatValue`. */
+import { ProgressBar, type ProgressSegment } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const DEALS_BY_SOURCE: ProgressSegment[] = [
+  { value: 1_840_000, label: "Сайт", color: "blue" },
+  { value: 1_120_000, label: "Входящие звонки", color: "orange" },
+  { value: 640_000, label: "Партнёры", color: "teal" },
+  { value: 310_000, label: "Выставки", color: "yellow" },
+  { value: 190_000, label: "Прочее", color: "gray" },
+];
+
+const formatRubles = (value: number) => `${value.toLocaleString("ru-RU")} ₽`;
+
+export default function ProgressBarLegendExample() {
+  return (
+    <div className={styles.column}>
+      <ProgressBar
+        segments={DEALS_BY_SOURCE}
+        segmentGap="hairline"
+        label="Сделки за октябрь по источникам"
+        legend
+        formatValue={formatRubles}
+      />
+    </div>
+  );
+}

package/src/components/progress-bar/examples/ranking.tsx

@@ -0,0 +1,28 @@
+/** Rankings as rows of label · value · share over a bar: top cities against the leader and a funnel against its first step — `layout`, `scale`. */
+import { ProgressBar, type ProgressSegment } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const CITIES: ProgressSegment[] = [
+  { value: 1_284, label: "Москва" },
+  { value: 642, label: "Санкт-Петербург" },
+  { value: 318, label: "Казань" },
+  { value: 204, label: "Екатеринбург" },
+  { value: 96, label: "Новосибирск" },
+];
+
+const FUNNEL: ProgressSegment[] = [
+  { value: 2_400, label: "Заявка" },
+  { value: 1_380, label: "Квалификация" },
+  { value: 620, label: "Предложение" },
+  { value: 214, label: "Сделка" },
+];
+
+export default function ProgressBarRankingExample() {
+  return (
+    <div className={styles.column}>
+      <ProgressBar layout="rows" scale="max" segments={CITIES} label="Заказы по городам" />
+      <ProgressBar layout="rows" scale="first" segments={FUNNEL} label="Воронка за квартал" />
+    </div>
+  );
+}

package/src/components/progress-bar/examples/states.tsx

@@ -0,0 +1,43 @@
+/** Loading takes the bar's own geometry, so the data lands without a jump — `loading`. */
+import { ProgressBar, type ProgressSegment, Typography } from "prime-ui-kit";
+
+const SOURCES: ProgressSegment[] = [
+  { value: 412, label: "Сайт", color: "blue" },
+  { value: 268, label: "Звонки", color: "orange" },
+  { value: 120, label: "Партнёры", color: "teal" },
+];
+
+export default function ProgressBarStatesExample() {
+  return (
+    <>
+      <div>
+        <div>
+          <ProgressBar value={64} label="Импорт контактов" showValue />
+          <Typography as="span" variant="caption" tone="muted">
+            value
+          </Typography>
+        </div>
+        <div>
+          <ProgressBar value={0} label="Импорт контактов" loading />
+          <Typography as="span" variant="caption" tone="muted">
+            loading
+          </Typography>
+        </div>
+      </div>
+      <div>
+        <div>
+          <ProgressBar segments={SOURCES} label="Лиды по источникам" legend />
+          <Typography as="span" variant="caption" tone="muted">
+            legend
+          </Typography>
+        </div>
+        <div>
+          <ProgressBar segments={SOURCES} label="Лиды по источникам" legend loading />
+          <Typography as="span" variant="caption" tone="muted">
+            legend · loading
+          </Typography>
+        </div>
+      </div>
+    </>
+  );
+}

package/src/components/progress-circle/COMPONENT.md

@@ -9,12 +9,14 @@
 - Compact metrics and goals in cards and dashboards (84% of plan).
 - Progress where horizontal space is short: table cells, list rows.
 - A value on a custom scale shown as a ring («7/12»).
-- A compact breakdown of a whole: tasks by status, storage by type (`segments`).
+- A compact breakdown of a whole: tasks by status, storage by type (`segments`); categories in their chart colors (`color`) with a `legend` beside the ring.
+- A named process whose share is not known yet (`value={null}`) or that turns while its share grows (`spin`), with an icon in the center that changes with its state.
 
 ## When not to use
 - Progress with a label and width to spare (uploads, imports) → use [ProgressBar](../progress-bar/COMPONENT.md).
 - A breakdown with many parts or long labels → [ProgressBar](../progress-bar/COMPONENT.md) with `segments`.
-- Unknown duration → use [Spinner](../spinner/COMPONENT.md); ProgressCircle is always determinate.
+- An anonymous «busy» mark inside a control or a region (a button, a select, a list) → [Spinner](../spinner/COMPONENT.md): it sizes like an icon and is a `status`.
+- A ring you can press (cancel, retry, download) → [Button](../button/COMPONENT.md) `shape="circle"` with `progress`; ProgressCircle is never interactive.
 
 ## Import
 ```tsx
@@ -23,10 +25,15 @@ import { ProgressCircle, type ProgressSegment } from "prime-ui-kit";
 
 ## Anatomy
 ```
-ProgressCircle           <div>; size, tone (value mode), children in the center
-├─ svg                   role="progressbar" (value) or role="group" (segments); track + arcs
-├─ description           visually hidden distribution (segments with aria-label)
-└─ inner                 children in the hole of the ring (not on xs / s)
+ProgressCircle           <div>; size, tone (value mode), children in the center, aria-busy while loading
+├─ svg                   the kit ring (internal/ring, data weight); role="progressbar" (value) or
+│                        role="group" (segments); track + arcs
+│                        (loading: a Skeleton ring of the same diameter and stroke)
+├─ description           visually hidden distribution (segments with aria-label, no legend)
+└─ inner                 children in the hole of the ring, a changed icon cross-fades
+                         (not on xs, text not on s, not while loading)
+
+with legend:             <div data-legend> — a row: the ring box + <ul> legend (swatch · name · value · share)
 ```
 
 ## API
@@ -39,27 +46,31 @@ ProgressCircle           <div>; size, tone (value mode), children in the center
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Diameter 24 · 32 · 48 · 64 · 80 px; the stroke is 1/12 of it. |
-| `children` | `ReactNode` | — | Content in the center (number, percent, `Icon`). Not rendered on `xs` / `s`; a string or number stays available as `aria-valuetext`. |
+| `children` | `ReactNode` | — | 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`. |
 | `aria-label` | `string` | — | Accessible name of the ring (set on the svg). Always pass it. |
+| `loading` | `boolean` | `false` | 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`. |
 | `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className`, `data-*` and the other div attributes on the root. |
 
 ### ProgressCircle · value mode
-The svg is `role="progressbar"`: a track and one round-capped arc.
+The svg is `role="progressbar"`: a track and one round-capped arc from 12 o'clock.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` | `number` | — (required) | The current value, clamped to `0…max`. |
+| `value` | `number \| null` | — (required) | 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`. |
+| `spin` | `boolean` | `false` | 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. |
 | `max` | `number` | `100` | Top of the scale. |
-| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info"` | `"accent"` | Arc color, telling the outcome. |
+| `tone` | `"neutral" \| "accent" \| "success" \| "warning" \| "danger" \| "info" \| "inherit"` | `"accent"` | 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. |
 
 ### ProgressCircle · segments mode
-The svg is `role="group"`: parts clockwise from the top, described by the distribution text.
+The svg is `role="group"`: parts clockwise from the top, described by the legend or the distribution text.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `segments` | `ProgressSegment[]` | — (required) | Parts in order, `{ value, label?, tone? }` (`tone` default `accent`); each part's length is its share of `max`. |
+| `segments` | `ProgressSegment[]` | — (required) | 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`. |
 | `max` | `number` | — | Total capacity. Default: the sum of the parts (they close the ring); a larger `max` leaves the rest as track. |
 | `segmentGap` | `"none" \| "hairline"` | `"none"` | `none` — one continuous ring; `hairline` — every part and the rest are separate round arcs. |
+| `legend` | `boolean` | `false` | A legend beside the ring (below it when the row is narrow), one row per part: color · name · value · share; it becomes the group's description. The root turns into the row of ring and legend. |
+| `formatValue` | `(value: number) => string` | `Russian digit groups` | Display of a part's value in the legend («38 ГБ»). |
 | `labels` | `Partial<ProgressCircleLabels>` | — | Built-in strings, see Labels. |
 
 ## Variants
@@ -68,12 +79,12 @@ The svg is `role="group"`: parts clockwise from the top, described by the distri
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
 | `xs` | 24 diameter, no inner content | inline in text or table cells | |
-| `s` | 32 diameter, no inner content | list rows, compact cards | |
-| `m` | 48 diameter, inner text 12/16 | KPI tiles | yes |
-| `l` | 64 diameter, inner text 16/24 | dashboard cards | |
-| `xl` | 80 diameter, inner text 18/24 | hero metrics, breakdowns | |
+| `s` | 32 diameter, an icon 16 in the center, no text | list rows, compact cards | |
+| `m` | 48 diameter, inner text 12/16, icon 20 | KPI tiles | yes |
+| `l` | 64 diameter, inner text 16/24, icon 24 | dashboard cards | |
+| `xl` | 80 diameter, inner text 18/24, icon 32 | hero metrics, breakdowns | |
 
-The stroke is always 1/12 of the diameter.
+The stroke is always 1/12 of the diameter (the kit ring's `data` weight). These diameters are a data scale, separate from the control heights of a circle Button.
 
 ### tone (value mode or each segment)
 | Value | Looks like | Use when | Default |
@@ -84,6 +95,21 @@ The stroke is always 1/12 of the diameter.
 | `warning` | warning arc | at risk, quota almost used | |
 | `danger` | danger arc | failed, overdue share | |
 | `info` | info arc | informational processes (sync, indexing) | |
+| `inherit` (value mode) | the arc in the host's text color over a 32% track of it; the center text inherits it too | a ring on a colored host or over media | |
+
+### color (each segment, instead of tone)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `blue` · `orange` · `teal` · `yellow` · `pink` · `green` · `purple` · `red` | the hue's step of the chart palette (`--prime-color-chart-1…8`) | categories: channels, sources, regions — the color they have in charts | |
+| `gray` | `--prime-color-chart-other` | the «Прочее» share | |
+| `sky` | the palette's sky solid (no chart step) | only when the category is sky elsewhere | |
+
+### Flags
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `spin` (value mode) | the ring turns at any share, the arc never under 8% | a process whose share grows while it runs (a sync) | `false` |
+| `legend` | swatch · name · value · share rows beside the ring, below it when narrow | a breakdown read in numbers | `false` |
+| `loading` | a Skeleton ring (and legend lines) of the same geometry | the data is on its way | `false` |
 
 ### segmentGap
 | Value | Looks like | Use when | Default |
@@ -96,15 +122,23 @@ The stroke is always 1/12 of the diameter.
 |---|---|---|
 | size / tone | props | `data-size`, `data-tone` (value mode) on the root |
 | empty | `value` 0, or `segments` empty / all 0 | arc hidden, track only |
-| value | `value`, `max` | `aria-valuenow`, `aria-valuemin="0"`, `aria-valuemax`; the arc glides by `stroke-dashoffset` over `slow` |
-| segments | `segments`, `max`, `segmentGap` | `data-segment-gap` on the svg, `data-tone` on every arc and cap; arcs glide by dash, caps by `rotate` |
-| reduced motion | `prefers-reduced-motion` | arcs change instantly |
+| value | `value`, `max` | `aria-valuenow`, `aria-valuemin="0"`, `aria-valuemax`; `--ring-value` on the svg, the arc glides by `stroke-dashoffset` over `base` |
+| share unknown | `value={null}` | no `aria-valuenow`; `data-spin` on the svg: a quarter arc turning (one turn = 3 × `--prime-motion-loop`); a share that arrives glides out of the quarter |
+| spinning | `spin` | `data-spin` on the svg: the whole svg turns (a compositor transform) while the share glides on its own; the arc is at least 8% |
+| icon change | a new icon in `children` (another `name`) | the old one shrinks to 0.6 and fades, the new one grows in (`fast`) and plays its gesture once; a changing number updates in place |
+| segments | `segments`, `max`, `segmentGap` | `data-segment-gap` on the svg, `data-tone` or `data-color` on every arc and cap; arcs glide by dash, caps by `rotate` |
+| legend | `legend` | `data-legend` on the root, which becomes a wrapping row of the ring and the `<ul>` |
+| loading | `loading` | `aria-busy` on the root; a Skeleton ring (mask of the stroke) and legend lines; the data cross-fades in (`swapMotion`) |
+| reduced motion | `prefers-reduced-motion` | arcs and icons change instantly; a turning ring turns twice as slow and never stops |
 
 Always controlled: pass the current `value` or `segments`.
 
 ## Layout & spacing
-- `display: inline-flex`, never shrinks; a caption sits next to it with `--prime-space-3` or under it with `--prime-space-2`.
-- Diameters sit on the 4px grid (`--prime-space-6…20`); the ring geometry is in viewBox units.
+- `display: inline-flex`, never shrinks (with `legend` the root is a block `flex` row); a caption sits next to it with `--prime-space-3` or under it with `--prime-space-2`.
+- Diameters sit on the 4px grid (`--prime-space-6…20`); the ring is placed in CSS (an svg without a viewBox), lengths along it are percent of the circle.
+- Inner content sits in the hole (5/6 of the diameter, clipped), primary, medium weight, tabular numbers.
+- With `legend` the root is a wrapping row: the ring and the legend `--prime-space-5` (20) apart; the legend takes the rest of the row (basis 192) and drops below the ring when that does not fit.
+- `hairline` arcs are ¾ of the stroke apart; arcs start at 12 o'clock and run clockwise.
 
 ## Accessibility
 
@@ -112,8 +146,11 @@ Always controlled: pass the current `value` or `segments`.
 No keyboard interaction.
 
 ### ARIA
-- Value mode: the svg is `role="progressbar"` with `aria-valuenow` / `-min` / `-max`; a string or number child becomes `aria-valuetext`.
-- Segments mode: the svg is `role="group"`; with `aria-label` it is described by the distribution («Видео: 38%, Документы: 21%»), without it the distribution is its name.
+- Value mode: the svg is `role="progressbar"` with `aria-valuenow` / `-min` / `-max`; a string or number child becomes `aria-valuetext`. With `value={null}` there is no `aria-valuenow` — the share is unknown.
+- The turn never stops under reduced motion (twice as slow): it is the only sign the work goes on.
+- Segments mode: the svg is `role="group"`; with `aria-label` it is described by the distribution («Видео: 38%, Документы: 21%») or by the legend, without it the distribution is its name.
+- A category color always sits beside its name in the legend, so color is never the only cue.
+- While `loading` the root is `aria-busy` and the Skeletons are `aria-hidden`.
 - Always pass `aria-label`: a caption next to the ring is not linked to it.
 - The inner text is `aria-hidden` when it is already the `aria-valuetext`.
 
@@ -131,16 +168,22 @@ No keyboard interaction.
 | [overview.tsx](examples/overview.tsx) | A plan ring with the percentage in the center, named for screen readers — `value`, `aria-label`. |
 | [variants.tsx](examples/variants.tsx) | Every arc color; the tone tells the outcome, not the progress — `tone`. |
 | [sizes.tsx](examples/sizes.tsx) | Diameters 24 to 80 px; the center text is not rendered on `xs` and `s` — `size`. |
+| [states.tsx](examples/states.tsx) | Loading is a Skeleton ring of the same diameter and stroke; the number in the centre waits for the data — `loading`. |
 | [inner-content.tsx](examples/inner-content.tsx) | The center holds a percentage, a count on its own scale or an icon — `children`, `max`. |
+| [under-way.tsx](examples/under-way.tsx) | An import whose share is not known yet turns a quarter arc, then fills and swaps its icon; a sync turns while its share grows — `value`, `spin`, `children`. |
 | [segments.tsx](examples/segments.tsx) | Parts of a whole clockwise from the top: a closed ring, free capacity up to `max`, separate arcs and an empty list — `segments`, `segmentGap`. |
+| [legend.tsx](examples/legend.tsx) | A ring of category shares with a legend beside it, in the categories' chart colors — `color`, `legend`, `formatValue`. |
 
 ## Mistakes
 - No `aria-label` (even with a visible caption) → screen readers get an unnamed progressbar.
-- Text inside an `xs` / `s` ring → it is not rendered; show it outside.
+- Text inside an `xs` / `s` ring → it is not rendered; show it outside (an icon shows from `s`).
+- A fake indeterminate ring (`value={25}` plus a CSS rotation) → `value={null}`.
+- `onClick` on the ring to cancel → a [Button](../button/COMPONENT.md) `shape="circle"` with `progress`.
 - `value` and `segments` together → a type error; pick one mode.
 - `tone` on the root with `segments` → set `tone` on each segment.
 - Long text inside the ring → it is clipped to the inner circle.
+- Categories painted with `tone` → use `color`; a hand-built legend beside the ring → `legend`.
 
 ## Related
-- **Built from:** —
-- **See also:** [ProgressBar](../progress-bar/COMPONENT.md), [Card](../card/COMPONENT.md), [Spinner](../spinner/COMPONENT.md)
+- **Built from:** [Skeleton](../skeleton/COMPONENT.md), `internal/ring` (the ring drawing, shared with Spinner and the circle Button), `internal/glyphSwap` (the center cross-fade)
+- **See also:** [ProgressBar](../progress-bar/COMPONENT.md), [Card](../card/COMPONENT.md), [Spinner](../spinner/COMPONENT.md), [Button](../button/COMPONENT.md)

package/src/components/progress-circle/examples/examples.module.css

@@ -9,6 +9,11 @@
   gap: var(--prime-space-6);
 }
 
+/* A dashboard card as wide as a short form: the legend sits beside the ring or drops under it. */
+.card {
+  width: min(100%, var(--prime-modal-width-s));
+}
+
 .item {
   display: flex;
   flex-direction: column;