prime-ui-kit 0.7.13 → 0.9.1

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

@@ -1,97 +1,146 @@
 # ProgressCircle
 
-**Default `size`:** use **`m`** for the size axis unless the layout explicitly needs another tier.
+**Category:** feedback
+**Kind:** primitive
 
-## Canonical
+> Circular progress — the ring version of ProgressBar: one value or `segments` that split a whole, with status colors and optional content in the center.
 
-- **Playground demos** mirror **`playground/snippets/progress/circle-*.tsx`** (`circle-sizes`, `circle-max-scale`, `circle-states`, `circle-controlled`, `circle-composition`, `circle-a11y-label`); package **`examples/`** follow the same scenarios.
-- **`ProgressCircle`** — circular fraction of a known maximum: **`ProgressCircle.Root`** only (`inline-flex` root, SVG ring + optional centered **`children`**).
-- **Semantics:** SVG has **`role="progressbar"`** with **`aria-valuenow`**, **`aria-valuemin={0}`**, **`aria-valuemax`** (effective max after clamping / safe fallback).
-- **`value`** (required) and **`max`** (default **`100`**) — progress is **fully controlled**; **`value`** is clamped to **`[0, max]`**; if **`max <= 0`**, the scale falls back to **`100`** internally.
-- **`label`** — optional accessible name on the SVG (**`aria-label`**); use when the center has no text or the visible center text does not describe the bar.
-- **`size`:** **`s` | `m` | `l` | `xl`** — diameter and stroke from **`progressCircle`** primitives.
-- **`children`** — optional centered slot (short number, percent, icon); omit for a ring-only indicator (then set **`label`** for a11y).
-- **No indeterminate mode**, no **`disabled` / `loading` / `error`** props — reflect those in surrounding UI or by freezing **`value`**.
-- **Not** a focusable control; **not** polymorphic (**no `asChild`**).
+## When to use
+- 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`).
 
-## Extended
-
-### About
-
-Circular progress: an SVG ring showing **`value` / `max`**, with optional content inside the ring.
-
-- **When to use** — compact share of a known total (percent, steps, seats, quota) where a round indicator reads better than a bar.
-- **When to use** — with **`max`** when the scale is not 0–100 (months in a plan, steps in a wizard, large numeric caps).
-- **When to use** — **`children`** for the focal number or short label in the middle of the ring.
-- **When not to use** — indeterminate or endless spinners without a numeric fraction (no built-in indeterminate API).
-- **When not to use** — as the primary interactive target; pair with [Button](../button/COMPONENT.md) or links for actions.
-- **When not to use** — when a horizontal bar is clearer; see [ProgressBar](../progress-bar/COMPONENT.md).
-
-### Composition
-
-- **`ProgressCircle.Root`** — root **`div`** with **`data-size`**, inner size CSS variable, SVG (**`progressbar`**), then optional **`children`** wrapper centered over the ring.
-- Order: pass **`value`** / **`max`** / **`size`** / **`label`** on **`Root`**; put visual center content in **`children`** when needed.
-
-### Scenarios (see `examples/`; playground: `playground/snippets/progress/circle-*.tsx`)
-
-| Scenario | Approach |
-|----------|----------|
-| Sizes | Same **`value`** across **`size`** **`s`–`xl`** (diameter and stroke from **`progressCircle`**). → [`examples/sizes.tsx`](examples/sizes.tsx) |
-| Non‑100 scale | Same arc fraction for different **`max`** (percent, steps, large totals). → [`examples/max-scale.tsx`](examples/max-scale.tsx) |
-| Value clamping | Empty, partial, full ring; out-of-range **`value`** clamps to **`0`** and **`max`**. → [`examples/states.tsx`](examples/states.tsx) |
-| Controlled value | Drive **`value`** from parent state (polling, upload simulation). → [`examples/controlled.tsx`](examples/controlled.tsx) |
-| Composition | **`children`** for **`Typography`**, icons, short numeric copy. → [`examples/composition.tsx`](examples/composition.tsx) |
-| Accessible name | Set **`label`** when the center has no descriptive text ( **`aria-label`** on SVG). → [`examples/a11y-label.tsx`](examples/a11y-label.tsx) |
-| Dashboard KPI (extra) | Ring inside [Card](../card/COMPONENT.md) **`mini-media`** **`Card.Media`** — no dedicated circle snippet. → [`examples/dashboard-ring.tsx`](examples/dashboard-ring.tsx) |
-
-### Minimal example
+## 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.
 
+## Import
 ```tsx
-import { ProgressCircle } from "prime-ui-kit";
-
-export function Example() {
-  return <ProgressCircle.Root value={40} />;
-}
+import { ProgressCircle, type ProgressSegment } from "prime-ui-kit";
 ```
 
-### Rules
-
-- Progress is **always prop-driven** — no internal stored progress.
-- **`value`** clamped to **`[0, max]`**; negatives → **`0`**, above **`max`** → **`max`**.
-- If **`max <= 0`**, internal scale uses **`100`** to avoid division by zero.
-- **`label`** maps to **`aria-label`** on the SVG; prefer visible **`children`** text that describes the bar when it fully names the task.
-- Root is **`inline-flex`** — align inside your own flex or grid row when pairing with captions.
-- One visual style; scale with **`size`** only.
+## 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
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `number` | — | Yes | Current value; clamped to `[0, max]` |
-| max | `number` | `100` | No | Upper bound; if `max <= 0`, `100` is used |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Diameter and stroke from `progressCircle` primitives |
-| label | `string` | — | No | Accessible name for the SVG (`aria-label`) |
-| children | `React.ReactNode` | — | No | Centered content inside the ring |
-| className | `string` | — | No | Extra class on the root `div` |
-| ref | `React.Ref<HTMLDivElement>` | — | No | Ref on the root `div` |
+<!-- 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 |
+|---|---|---|---|
+| `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, 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 | |
+
+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 | 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` (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` 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.
+
+## Accessibility
+
+### 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 |
+|---|---|---|
+| `empty` | `"Нет сегментов"` | Accessible text when `segments` is empty. |
+| `allEmpty` | `"Все сегменты пусты"` | Accessible text when every segment is 0. |
+
+## 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 `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) — linear fraction when a horizontal bar fits better.
-- [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md) — multiple segments on one track.
-- [Card](../card/COMPONENT.md) — KPI tiles; **`mini-media`** **`Card.Media`** for rings or thin progress.
-- [Typography](../typography/COMPONENT.md) — captions and units beside or under the ring.
-
-## LLM note
-
-- **Playground circle snippets:** `circle-sizes`, `circle-max-scale`, `circle-states`, `circle-controlled`, `circle-composition`, `circle-a11y-label` under **`playground/snippets/progress/`** — keep **`COMPONENT.md`** and **`examples/`** aligned with them.
-- Export: **`import { ProgressCircle } from "prime-ui-kit"`** — **`ProgressCircle.Root`** only (object namespace).
-- **`ProgressCircleRootProps`**: **`value`** (required), **`max?`** (default 100), **`size?`** (default **`m`**), **`label?`**, **`children?`**, **`className?`**, **`ref`** → **`HTMLDivElement`**.
-- **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`**.
-- SVG: **`role="progressbar"`**, **`aria-valuenow`**, **`aria-valuemin={0}`**, **`aria-valuemax`** = effective max; **`aria-label`** from **`label`** when provided.
-- **No** indeterminate, **no** `disabled`/`loading`/`error` props — control **`value`** and surrounding UI instead.
-- **No** `asChild` / polymorphic root — fixed **`div`** + SVG + optional inner **`div`** for **`children`**.
-- When the center is empty or non-descriptive, require **`label`** for an accessible name.
-- Prefer [ProgressBar](../progress-bar/COMPONENT.md) for linear indeterminate or strip layouts unless the design specifically needs a ring.
+- **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

@@ -0,0 +1,17 @@
+/* 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;
+  align-items: flex-end;
+  justify-content: center;
+  gap: var(--prime-space-6);
+}
+
+.item {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--prime-space-2);
+}

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,77 +1,21 @@
+/** Diameters 24 to 80 px; the center text is not rendered on `xs` and `s` — `size`. */
 import { ProgressCircle, Typography } from "prime-ui-kit";
 
-/** Four ring sizes: diameter and stroke from `progressCircle` primitives (playground: `snippets/progress/circle-sizes.tsx`). */
-export default function SizesExample() {
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+export default function ProgressCircleSizesExample() {
   return (
-    <div
-      style={{
-        display: "flex",
-        flexWrap: "wrap",
-        gap: "var(--prime-sys-spacing-xl)",
-        alignItems: "flex-end",
-        justifyContent: "center",
-      }}
-    >
-      <div
-        style={{
-          display: "flex",
-          flexDirection: "column",
-          alignItems: "center",
-          gap: "var(--prime-sys-spacing-s)",
-        }}
-      >
-        <Typography.Root as="span" variant="body-compact" tone="muted">
-          Size s
-        </Typography.Root>
-        <ProgressCircle.Root value={50} size="s">
-          50%
-        </ProgressCircle.Root>
-      </div>
-      <div
-        style={{
-          display: "flex",
-          flexDirection: "column",
-          alignItems: "center",
-          gap: "var(--prime-sys-spacing-s)",
-        }}
-      >
-        <Typography.Root as="span" variant="body-compact" tone="muted">
-          Size m
-        </Typography.Root>
-        <ProgressCircle.Root value={50} size="m">
-          50%
-        </ProgressCircle.Root>
-      </div>
-      <div
-        style={{
-          display: "flex",
-          flexDirection: "column",
-          alignItems: "center",
-          gap: "var(--prime-sys-spacing-s)",
-        }}
-      >
-        <Typography.Root as="span" variant="body-compact" tone="muted">
-          Size l
-        </Typography.Root>
-        <ProgressCircle.Root value={50} size="l">
-          50%
-        </ProgressCircle.Root>
-      </div>
-      <div
-        style={{
-          display: "flex",
-          flexDirection: "column",
-          alignItems: "center",
-          gap: "var(--prime-sys-spacing-s)",
-        }}
-      >
-        <Typography.Root as="span" variant="body-compact" tone="muted">
-          Size xl
-        </Typography.Root>
-        <ProgressCircle.Root value={50} size="xl">
-          50%
-        </ProgressCircle.Root>
-      </div>
+    <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>
+        </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>
+  );
+}