prime-ui-kit 0.7.11 → 0.9.0

package/src/components/progress-bar/examples/file-upload.tsx

@@ -0,0 +1,52 @@
+/** Live file uploads in a card: progress grows, finished files turn `success`, a failed one `danger`. Use it for per-item progress of background operations. */
+import { Button, ProgressBar, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+type Upload = { name: string; size: string; progress: number; failed?: boolean };
+
+const initial: Upload[] = [
+  { name: "отчёт-сентябрь.pdf", size: "2,4 МБ", progress: 100 },
+  { name: "прайс-лист.xlsx", size: "860 КБ", progress: 35 },
+  { name: "фото-склада.zip", size: "48 МБ", progress: 62, failed: true },
+];
+
+export default function ProgressBarFileUploadExample() {
+  const [files, setFiles] = React.useState(initial);
+
+  React.useEffect(() => {
+    const id = window.setInterval(() => {
+      setFiles((prev) =>
+        prev.map((f) =>
+          f.failed || f.progress >= 100 ? f : { ...f, progress: Math.min(100, f.progress + 7) },
+        ),
+      );
+    }, 500);
+    return () => window.clearInterval(id);
+  }, []);
+
+  return (
+    <div className={styles.card}>
+      <div className={styles.cardHeader}>
+        <Typography.Root as="h3" variant="title-s">
+          Загрузка файлов
+        </Typography.Root>
+        <Button.Root variant="ghost" tone="neutral" size="s" onClick={() => setFiles(initial)}>
+          Заново
+        </Button.Root>
+      </div>
+      {files.map((f) => {
+        const tone = f.failed ? "danger" : f.progress >= 100 ? "success" : "accent";
+        return (
+          <div key={f.name} className={styles.file}>
+            <ProgressBar.Root value={f.progress} tone={tone} label={f.name} showValue />
+            <Typography.Root as="span" variant="caption" tone="muted" className={styles.meta}>
+              {f.failed ? "Сбой соединения" : f.size}
+            </Typography.Root>
+          </div>
+        );
+      })}
+    </div>
+  );
+}

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

@@ -1,13 +1,16 @@
-import { ProgressBar } from "prime-ui-kit";
+/** Sizes xs–xl with `label` and `showValue`: the track is 4px for xs–m and 8px for l–xl, the label follows the control tier. Match the size to the surrounding text. */
+import { type ControlSize, ProgressBar } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const sizes: ControlSize[] = ["xs", "s", "m", "l", "xl"];
 
-/** Four sizes: track height and label scale from `--prime-sys-size-control-{s|m|l|xl}-*` (playground: `snippets/progress/bar-sizes.tsx`). */
 export default function ProgressBarSizesExample() {
   return (
-    <>
-      <ProgressBar.Root size="s" value={30} label="Size s" />
-      <ProgressBar.Root size="m" value={40} label="Size m" />
-      <ProgressBar.Root size="l" value={50} label="Size l" />
-      <ProgressBar.Root size="xl" value={60} label="Size xl" />
-    </>
+    <div className={styles.stack}>
+      {sizes.map((size) => (
+        <ProgressBar.Root key={size} size={size} value={64} label={`Размер ${size}`} showValue />
+      ))}
+    </div>
   );
 }

package/src/components/progress-bar/examples/values-and-tones.tsx

@@ -0,0 +1,17 @@
+/** 0, partial and 100; `tone` success / warning / danger; `max` for a "3 of 5 steps" scale. Use the tone to show the outcome, not the progress itself. */
+import { ProgressBar } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function ProgressBarValuesAndTonesExample() {
+  return (
+    <div className={styles.stack}>
+      <ProgressBar.Root value={0} label="Ещё не начато" showValue />
+      <ProgressBar.Root value={42} label="Загрузка" showValue />
+      <ProgressBar.Root value={100} tone="success" label="Готово" showValue />
+      <ProgressBar.Root value={86} tone="warning" label="Квота почти исчерпана" showValue />
+      <ProgressBar.Root value={30} tone="danger" label="Импорт прерван" showValue />
+      <ProgressBar.Root value={3} max={5} label="Профиль: 3 из 5 шагов" />
+    </div>
+  );
+}

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

@@ -1,97 +1,105 @@
 # ProgressCircle
 
-**Default `size`:** use **`m`** for the size axis unless the layout explicitly needs another tier.
+**Category:** feedback
 
-## Canonical
+> Circular progress indicator: a track, a rounded arc 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, avatars of tasks.
+- A value on a custom scale shown as a ring ("7/12").
 
-## Extended
+## 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.
 
-### 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`)
+## Import
+```tsx
+import { ProgressCircle } from "prime-ui-kit";
+```
 
-| 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) |
+## API
 
-### Minimal example
+### ProgressCircle.Root
+Leaf component. `forwardRef` to the root `HTMLDivElement`. No native props passthrough.
+
+| 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. |
+
+## 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 | |
+
+### tone
+| 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.
+
+## 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`) |
+
+Always controlled: pass the current `value`.
+
+## 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).
+
+## 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 |
+|---|---|---|
+| [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 |
 
 ```tsx
 import { ProgressCircle } from "prime-ui-kit";
 
-export function Example() {
-  return <ProgressCircle.Root value={40} />;
+export function PlanProgress() {
+  return (
+    <ProgressCircle.Root value={84} label="Выполнение плана">
+      84%
+    </ProgressCircle.Root>
+  );
 }
 ```
 
-### 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.
-
-## 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` |
+## 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`.
 
 ## 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.
+- [ProgressBar](../progress-bar/COMPONENT.md), [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md).
+- [Card](../card/COMPONENT.md) — typical host for KPI rings.

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

@@ -0,0 +1,54 @@
+/* Layout helpers for the ProgressCircle examples. Layout and card surface tokens only. */
+
+.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);
+}
+
+.item {
+  display: flex;
+  flex-direction: column;
+  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/goals-card.tsx

@@ -0,0 +1,37 @@
+/** Quarter goals in a card: an `m` ring with the percentage inside and a caption next to it. Use it for compact KPI tiles. */
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const goals = [
+  { title: "Выручка", value: 84, note: "₽ 4,2 из 5 млн", tone: "accent" },
+  { title: "Новые клиенты", value: 100, note: "312 из 300", tone: "success" },
+  { title: "Обращения", value: 61, note: "SLA 61% в срок", tone: "warning" },
+] as const;
+
+export default function ProgressCircleGoalsCardExample() {
+  return (
+    <div className={styles.card}>
+      <Typography.Root as="h3" variant="title-s">
+        Цели на IV квартал
+      </Typography.Root>
+      <div className={styles.goals}>
+        {goals.map((g) => (
+          <div key={g.title} className={styles.goal}>
+            <ProgressCircle.Root value={g.value} tone={g.tone} label={g.title}>
+              {`${g.value}%`}
+            </ProgressCircle.Root>
+            <span className={styles.goalText}>
+              <Typography.Root as="span" variant="body-s">
+                {g.title}
+              </Typography.Root>
+              <Typography.Root as="span" variant="caption" tone="muted" className={styles.meta}>
+                {g.note}
+              </Typography.Root>
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

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

@@ -1,77 +1,23 @@
+/** 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. */
 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() {
+import styles from "./examples.module.css";
+
+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 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">
+            {size}
+          </Typography.Root>
+        </div>
+      ))}
     </div>
   );
 }

package/src/components/progress-circle/examples/values-and-tones.tsx

@@ -0,0 +1,56 @@
+/** `tone` colors the arc; at `0` only the track remains; `max` changes the scale (7 of 12); the center holds text or an icon. Always pass `label`: it is the ring's only accessible name. */
+import { Check } from "lucide-react";
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+function Caption({ children }: { children: string }) {
+  return (
+    <Typography.Root as="span" variant="caption" tone="muted">
+      {children}
+    </Typography.Root>
+  );
+}
+
+export default function ProgressCircleValuesAndTonesExample() {
+  return (
+    <div className={styles.row}>
+      <div className={styles.item}>
+        <ProgressCircle.Root size="l" value={0} label="Не начато">
+          0%
+        </ProgressCircle.Root>
+        <Caption>0</Caption>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle.Root size="l" value={45} label="В процессе">
+          45%
+        </ProgressCircle.Root>
+        <Caption>default</Caption>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle.Root size="l" value={100} tone="success" label="Готово">
+          <Check aria-hidden />
+        </ProgressCircle.Root>
+        <Caption>success</Caption>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle.Root size="l" value={88} tone="warning" label="Квота">
+          88%
+        </ProgressCircle.Root>
+        <Caption>warning</Caption>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle.Root size="l" value={20} tone="danger" label="Сбой">
+          20%
+        </ProgressCircle.Root>
+        <Caption>danger</Caption>
+      </div>
+      <div className={styles.item}>
+        <ProgressCircle.Root size="l" value={7} max={12} label="Месяцев оплачено">
+          7/12
+        </ProgressCircle.Root>
+        <Caption>max=12</Caption>
+      </div>
+    </div>
+  );
+}