prime-ui-kit 0.9.0 → 0.9.1

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

@@ -1,105 +1,146 @@
 # ProgressCircle
 
 **Category:** feedback
+**Kind:** primitive
 
-> Circular progress indicator: a track, a rounded arc and optional content in the center.
+> Circular progress — the ring version of ProgressBar: one value or `segments` that split a whole, with status colors and optional content in the center.
 
 ## When to use
 - Compact metrics and goals in cards and dashboards (84% of plan).
-- Progress where horizontal space is short: table cells, list rows, avatars of tasks.
-- A value on a custom scale shown as a ring ("7/12").
+- 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`).
 
 ## When not to use
 - Progress with a label and width to spare (uploads, imports) → use [ProgressBar](../progress-bar/COMPONENT.md).
-- Several parts or shares → use [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md).
-- Unknown duration → use a loading state (e.g. `Button` `loading`); ProgressCircle is always determinate.
+- 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.
 
 ## Import
 ```tsx
-import { ProgressCircle } from "prime-ui-kit";
+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)
 ```
 
 ## API
 
-### ProgressCircle.Root
-Leaf component. `forwardRef` to the root `HTMLDivElement`. No native props passthrough.
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### ProgressCircle
+`ref` → `HTMLDivElement` (the root). Props of both modes; pass either `value` (value mode) or `segments` (segments mode), never both.
+
+| 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`. |
+| `aria-label` | `string` | — | Accessible name of the ring (set on the svg). Always pass it. |
+| `…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.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `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"` | Arc color, telling the outcome. |
+
+### ProgressCircle · segments mode
+The svg is `role="group"`: parts clockwise from the top, described by the distribution text.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` | `number` | — (required) | Current value; clamped to `0…max`. At `0` the arc is hidden. |
-| `max` | `number` | `100` | Top of the scale; `<= 0` falls back to `100`. |
-| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Diameter and stroke width. |
-| `tone` | `"accent" \| "success" \| "warning" \| "danger"` | `"accent"` | Arc color. |
-| `label` | `string` | — | `aria-label` of the `role="progressbar"` svg. Always pass it: it is the only way to name the ring (no `aria-labelledby`, no native props), even when a visible caption sits next to it. |
-| `children` | `ReactNode` | — | Centered content: percentage, fraction, icon. Not rendered on `xs` / `s`. A string or number child also becomes `aria-valuetext` (and the visual copy is `aria-hidden`). |
-| `className` | `string` | — | Class on the root. |
+| `segments` | `ProgressSegment[]` | — (required) | Parts in order, `{ value, label?, tone? }` (`tone` default `accent`); 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. |
+| `labels` | `Partial<ProgressCircleLabels>` | — | Built-in strings, see Labels. |
 
 ## Variants
 
 ### size
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `xs` | 24 diameter, 3px stroke, no inner content | Inline in text or table cells | |
-| `s` | 32 diameter, 4px stroke, no inner content | List rows, compact cards | |
-| `m` | 48 diameter, 4px stroke, inner text 12/16 medium | KPI tiles | yes |
-| `l` | 64 diameter, 6px stroke, inner text 16/24 medium | Dashboard cards | |
-| `xl` | 80 diameter, 8px stroke, inner text 18/24 medium | Hero metrics | |
+| `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 | |
 
-### tone
+The stroke is always 1/12 of the diameter.
+
+### tone (value mode or each segment)
 | Value | Looks like | Use when | Default |
 |---|---|---|---|
-| `accent` | Accent arc on a `fill-strong` track | Neutral progress toward a goal | yes |
-| `success` | Success arc | Goal reached | |
-| `warning` | Warning arc | At risk, quota almost used | |
-| `danger` | Danger arc | Failed, far behind | |
-
-**Combinations**
-- Recommended: `m` with "NN%" inside and a caption next to the ring; `success` + a check icon at 100%.
-- Pointless: `children` on `xs`/`s` (not rendered) — use `label` and a caption outside.
-- Avoid: long text inside the ring; it is clipped to the inner circle.
+| `accent` | accent arc on a `fill-strong` track | progress toward a goal, the main share | yes |
+| `neutral` | `text-secondary` arc | quiet background work, «other» share | |
+| `success` | success arc | goal reached, done share | |
+| `warning` | warning arc | at risk, quota almost used | |
+| `danger` | danger arc | failed, overdue share | |
+| `info` | info arc | informational processes (sync, indexing) | |
+
+### segmentGap
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `none` | one continuous ring, flat joints; with free capacity the filled share has round caps | parts of a single process | yes |
+| `hairline` | every part and the free rest are separate round arcs; no track | distinct categories | |
 
 ## States
 | State | Driven by | DOM |
 |---|---|---|
-| size / tone | props | `data-size`, `data-tone` on the root |
-| empty | `value` 0 | arc hidden (opacity 0), track only |
-| value | `value`, `max` | `aria-valuenow`, `aria-valuemin="0"`, `aria-valuemax`; the arc animates (none under `prefers-reduced-motion`) |
+| 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 |
 
-Always controlled: pass the current `value`.
+Always controlled: pass the current `value` or `segments`.
 
 ## Layout & spacing
-- `display: inline-flex`, does not shrink; place it in a row with its caption using `--prime-space-3` gap, or above a caption with `--prime-space-2`.
-- Diameters sit on the 4px grid (rem based).
+- `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.
 
 ## Accessibility
-- The svg has `role="progressbar"` with `aria-valuenow/min/max`; `label` is its only accessible name — always set it.
-- String/number children are read as `aria-valuetext`; non-text children (icons) should be `aria-hidden`.
-- ProgressCircle has no `labels`.
 
-## Examples
-| File | Scenario | When to use this pattern |
+### Keyboard
+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.
+- 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`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| Key | Default | Used for |
 |---|---|---|
-| [goals-card.tsx](examples/goals-card.tsx) | `m` rings with percentage and captions in a card, three tones | KPI tiles |
-| [sizes.tsx](examples/sizes.tsx) | `xs`…`xl`, no inner text on `xs`/`s` | Picking a size |
-| [values-and-tones.tsx](examples/values-and-tones.tsx) | 0, accent, success with an icon, warning, danger, `max={12}` | Outcome colors and custom scales |
+| `empty` | `"Нет сегментов"` | Accessible text when `segments` is empty. |
+| `allEmpty` | `"Все сегменты пусты"` | Accessible text when every segment is 0. |
 
-```tsx
-import { ProgressCircle } from "prime-ui-kit";
-
-export function PlanProgress() {
-  return (
-    <ProgressCircle.Root value={84} label="Выполнение плана">
-      84%
-    </ProgressCircle.Root>
-  );
-}
-```
+## Examples
+| Example | Shows |
+|---|---|
+| [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`. |
+| [inner-content.tsx](examples/inner-content.tsx) | The center holds a percentage, a count on its own scale or an icon — `children`, `max`. |
+| [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`. |
 
 ## Mistakes
-- No `label` (even with a visible caption next to the ring) → screen readers get an unnamed progressbar; a caption is not linked to the ring, so always pass `label`.
-- Text inside an `xs`/`s` ring → it is not rendered; show it outside.
-- `tone="info"` → not supported; use `accent`.
+- 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.
+- `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.
 
 ## Related
-- [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md).
-- [Card](../card/COMPONENT.md) — typical host for KPI rings.
+- **Built from:** —
+- **See also:** [ProgressBar](../progress-bar/COMPONENT.md), [Card](../card/COMPONENT.md), [Spinner](../spinner/COMPONENT.md)

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

@@ -1,9 +1,9 @@
-/* Layout helpers for the ProgressCircle examples. Layout and card surface tokens only. */
+/* Layout of the ProgressCircle scenarios: semantic tokens only. */
 
+/* Several rings in one line; captions of different rings share one baseline. */
 .row {
   display: flex;
   flex-wrap: wrap;
-  /* Captions of different-sized circles share one baseline. */
   align-items: flex-end;
   justify-content: center;
   gap: var(--prime-space-6);
@@ -15,40 +15,3 @@
   align-items: center;
   gap: var(--prime-space-2);
 }
-
-/* 40rem goals card. */
-.card {
-  box-sizing: border-box;
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-space-4);
-  width: min(100%, calc(var(--prime-space-20) * 8));
-  padding: var(--prime-card-padding-m);
-  border-radius: var(--prime-card-radius);
-  background: var(--prime-color-card-bg);
-  box-shadow: var(--prime-card-shadow);
-}
-
-/* Goal columns of at least 10rem. */
-.goals {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(min(100%, calc(var(--prime-space-20) * 2)), 1fr));
-  gap: var(--prime-space-4);
-}
-
-.goal {
-  display: flex;
-  align-items: center;
-  gap: var(--prime-space-3);
-  min-width: 0;
-}
-
-.goalText {
-  display: flex;
-  flex-direction: column;
-  min-width: 0;
-}
-
-.meta {
-  font-variant-numeric: tabular-nums;
-}

package/src/components/progress-circle/examples/inner-content.tsx

@@ -0,0 +1,35 @@
+/** The center holds a percentage, a count on its own scale or an icon — `children`, `max`. */
+import { Icon, ProgressCircle, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function ProgressCircleInnerContentExample() {
+  return (
+    <div className={styles.row}>
+      <div className={styles.item}>
+        <ProgressCircle size="l" value={45} aria-label="Загрузка отчёта">
+          45%
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Отчёт
+        </Typography>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle size="l" value={7} max={12} aria-label="Оплачено месяцев">
+          7/12
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Подписка
+        </Typography>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle size="l" value={100} tone="success" aria-label="Онбординг завершён">
+          <Icon name="action.check" />
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Онбординг
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/progress-circle/examples/overview.tsx

@@ -0,0 +1,10 @@
+/** A plan ring with the percentage in the center, named for screen readers — `value`, `aria-label`. */
+import { ProgressCircle } from "prime-ui-kit";
+
+export default function ProgressCircleOverviewExample() {
+  return (
+    <ProgressCircle value={84} aria-label="Выполнение плана">
+      84%
+    </ProgressCircle>
+  );
+}

package/src/components/progress-circle/examples/segments.tsx

@@ -0,0 +1,64 @@
+/** Parts of a whole clockwise from the top: a closed ring, free capacity up to `max`, separate arcs and an empty list — `segments`, `segmentGap`. */
+import { ProgressCircle, type ProgressSegment, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const REVIEW: ProgressSegment[] = [
+  { value: 40, label: "Принято", tone: "success" },
+  { value: 35, label: "На проверке", tone: "warning" },
+  { value: 25, label: "Отклонено", tone: "danger" },
+];
+
+const SPRINT: ProgressSegment[] = [
+  { value: 12, label: "Готово", tone: "success" },
+  { value: 6, label: "В работе" },
+];
+
+const STORAGE: ProgressSegment[] = [
+  { value: 38, label: "Видео" },
+  { value: 21, label: "Документы", tone: "success" },
+  { value: 12, label: "Архивы", tone: "warning" },
+];
+
+export default function ProgressCircleSegmentsExample() {
+  return (
+    <div className={styles.row}>
+      <div className={styles.item}>
+        <ProgressCircle size="xl" segments={REVIEW} aria-label="Заявки">
+          100
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Заявки
+        </Typography>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle size="xl" segments={SPRINT} max={30} aria-label="Спринт">
+          18/30
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Спринт
+        </Typography>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle
+          size="xl"
+          segments={STORAGE}
+          max={100}
+          segmentGap="hairline"
+          aria-label="Хранилище"
+        >
+          71%
+        </ProgressCircle>
+        <Typography as="span" variant="caption" tone="muted">
+          Хранилище
+        </Typography>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle size="xl" segments={[]} aria-label="Нет данных" />
+        <Typography as="span" variant="caption" tone="muted">
+          Нет данных
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/progress-circle/examples/sizes.tsx

@@ -1,21 +1,19 @@
-/** Diameters 24 · 32 · 48 · 64 · 80 on the 4px grid; inner text from caption to title-l, none on xs/s. Always pass `label`; on xs/s show the value outside the ring. */
+/** Diameters 24 to 80 px; the center text is not rendered on `xs` and `s` — `size`. */
 import { ProgressCircle, Typography } from "prime-ui-kit";
 
-import styles from "./examples.module.css";
-
-const sizes = ["xs", "s", "m", "l", "xl"] as const;
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
 export default function ProgressCircleSizesExample() {
   return (
-    <div className={styles.row}>
-      {sizes.map((size) => (
-        <div key={size} className={styles.item}>
-          <ProgressCircle.Root size={size} value={72} label={`Выполнено, размер ${size}`}>
-            {size === "xs" || size === "s" ? null : "72%"}
-          </ProgressCircle.Root>
-          <Typography.Root as="span" variant="code" tone="muted">
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <ProgressCircle size={size} value={72} aria-label="Выполнено">
+            72%
+          </ProgressCircle>
+          <Typography as="span" variant="caption" tone="muted">
             {size}
-          </Typography.Root>
+          </Typography>
         </div>
       ))}
     </div>

package/src/components/progress-circle/examples/variants.tsx

@@ -0,0 +1,28 @@
+/** Every arc color; the tone tells the outcome, not the progress — `tone`. */
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+const TONES = [
+  { tone: "accent", label: "Загрузка", value: 45 },
+  { tone: "success", label: "Готово", value: 100 },
+  { tone: "warning", label: "Квота", value: 88 },
+  { tone: "danger", label: "Сбой импорта", value: 20 },
+  { tone: "info", label: "Синхронизация", value: 30 },
+  { tone: "neutral", label: "Индексация", value: 55 },
+] as const;
+
+export default function ProgressCircleVariantsExample() {
+  return (
+    <div>
+      {TONES.map(({ tone, label, value }) => (
+        <div key={tone}>
+          <ProgressCircle value={value} tone={tone} aria-label={label}>
+            {`${value}%`}
+          </ProgressCircle>
+          <Typography as="span" variant="caption" tone="muted">
+            {tone}
+          </Typography>
+        </div>
+      ))}
+    </div>
+  );
+}