prime-ui-kit 0.3.1 → 0.4.0

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

@@ -1,24 +1,48 @@
 # ProgressCircle
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Default `size`:** use **`m`** for the size axis unless the layout explicitly needs another tier.
 
-## About
+## Canonical
 
-Circular progress indicator: an SVG ring with `progressbar` semantics and optional centered content inside the ring.
+- **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`**).
 
-- **Use** when you need a compact fraction of a known maximum (percent, steps, seats vs capacity) in a round layout.
-- **Use** with **`max`** when the scale is not 0–100 (e.g. 12 months, 60 seats).
-- **Use** **`children`** for a short label or number in the center when it should match the visual focus of the ring.
-- **Do not use** for indeterminate or endless loading without a numeric fraction; there is no indeterminate mode in the API.
-- **Do not use** as the primary focus target or form control; the SVG is informational and not keyboard-focusable.
-- **Do not use** expecting a polymorphic root or `asChild`; the implementation is a fixed wrapper with SVG plus optional inner slot.
+## Extended
 
-## Composition
+### About
 
-- **`ProgressCircle`** exposes **`Root`** only (`ProgressCircle.Root`).
-- **`ProgressCircle.Root`** — root `div` (`inline-flex`), sets **`data-size`** and a CSS variable for the inner slot size.
-- **SVG** — **`role="progressbar"`** with track and fill circles; fill length follows **`value`** / **`max`**.
-- **Optional `children`** — when present, rendered in an inner container centered over the ring; omit when the ring alone is enough.
+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
 
@@ -30,16 +54,14 @@ export function Example() {
 }
 ```
 
-## Rules
+### Rules
 
-- Progress is **always driven by props**: pass **`value`** on each render; there is no internal stored progress state.
-- **`value`** is clamped to **`[0, max]`**; negative values become `0`, values above **`max`** become **`max`**.
-- If **`max <= 0`**, the implementation uses **`100`** as the scale to avoid division by zero.
-- Set **`label`** when the SVG needs an accessible name and the center has no suitable visible text (it maps to **`aria-label`** on the SVG).
-- The SVG exposes **`aria-valuenow`**, **`aria-valuemin={0}`**, and **`aria-valuemax`** equal to the effective maximum.
-- There are no **`disabled`**, **`loading`**, or **`error`** props; reflect those with surrounding UI or by freezing **`value`** updates.
-- Root is **`inline-flex`** and does not stretch to full width; place it inside your own flex or grid layout when aligning with other content.
-- One visual style only; scale appearance with **`size`** (`s`–`xl` from progress-circle primitives).
+- 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
 
@@ -49,7 +71,7 @@ export function Example() {
 |------|------|---------|----------|-------------|
 | 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 width from `progressCircle` primitives |
+| 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` |
@@ -57,7 +79,19 @@ export function Example() {
 
 ## Related
 
-- [ProgressBar](../progress-bar/COMPONENT.md) — linear fraction of a maximum when a horizontal bar fits better.
-- [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md) — multiple proportional segments on one track.
-- [Typography](../typography/COMPONENT.md) — captions and units beside or around the ring.
-- [Button](../button/COMPONENT.md) — cancel, retry, or other actions next to a long-running task.
+- [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.

package/src/components/progress-circle/examples/a11y-label.tsx

@@ -0,0 +1,33 @@
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+/**
+ * No text in the ring: the accessible name comes from `label` (`aria-label` on the SVG).
+ * Pair with visible copy beside the ring when the UI needs a readable caption.
+ * Playground: `snippets/progress/circle-a11y-label.tsx`.
+ */
+export default function A11yLabelExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "center",
+      }}
+    >
+      <ProgressCircle.Root value={62} max={100} size="m" label="Data sync, 62 percent complete" />
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: "var(--prime-sys-spacing-s)",
+        }}
+      >
+        <ProgressCircle.Root value={4} max={12} size="s" label="Subscription month 4 of 12" />
+        <Typography.Root as="span" variant="body-small">
+          Subscription · month 4 of 12
+        </Typography.Root>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,66 @@
+import { IconCheck, IconCircleDot, IconDownload, ProgressCircle, Typography } from "prime-ui-kit";
+
+/** Center slot: icon, short label, and numeric breakdowns (playground: `snippets/progress/circle-composition.tsx`). */
+export default function CompositionExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        gap: "var(--prime-sys-spacing-m)",
+        alignItems: "center",
+      }}
+    >
+      <ProgressCircle.Root value={72} max={100} size="xl">
+        <div
+          style={{
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "center",
+            gap: "var(--prime-sys-spacing-xs)",
+          }}
+        >
+          <IconCircleDot size="l" aria-hidden />
+          <Typography.Root as="span" variant="body-small" weight="medium">
+            On track
+          </Typography.Root>
+        </div>
+      </ProgressCircle.Root>
+      <ProgressCircle.Root value={33} max={80} size="l">
+        <div
+          style={{
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "center",
+            gap: "var(--prime-sys-spacing-xs)",
+          }}
+        >
+          <Typography.Root as="span" variant="body-large" weight="semibold">
+            33
+          </Typography.Root>
+          <Typography.Root as="span" variant="body-compact" tone="muted">
+            of 80
+          </Typography.Root>
+        </div>
+      </ProgressCircle.Root>
+      <ProgressCircle.Root value={65} max={100} size="m">
+        <div
+          style={{
+            display: "flex",
+            flexDirection: "column",
+            alignItems: "center",
+            gap: "var(--prime-sys-spacing-xs)",
+          }}
+        >
+          <IconDownload size="m" aria-hidden />
+          <Typography.Root as="span" variant="body-compact" weight="medium">
+            65%
+          </Typography.Root>
+        </div>
+      </ProgressCircle.Root>
+      <ProgressCircle.Root value={100} max={100} size="s">
+        <IconCheck size="s" aria-hidden />
+      </ProgressCircle.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,53 @@
+import { Button, ProgressCircle, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+/** Parent-owned `value` — typical for polling, uploads, or simulations (playground: `snippets/progress/circle-controlled.tsx`). */
+export default function ControlledExample() {
+  const [value, setValue] = React.useState(35);
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        gap: "var(--prime-sys-spacing-l)",
+      }}
+    >
+      <ProgressCircle.Root value={value} max={100} size="l">
+        <Typography.Root as="span" variant="body-small" weight="medium">
+          {value}%
+        </Typography.Root>
+      </ProgressCircle.Root>
+      <div
+        style={{
+          display: "flex",
+          flexWrap: "wrap",
+          gap: "var(--prime-sys-spacing-s)",
+          alignItems: "center",
+          justifyContent: "center",
+        }}
+      >
+        <Button.Root
+          mode="stroke"
+          size="s"
+          type="button"
+          onClick={() => setValue((v) => Math.max(0, v - 10))}
+        >
+          −10
+        </Button.Root>
+        <Button.Root
+          mode="stroke"
+          size="s"
+          type="button"
+          onClick={() => setValue((v) => Math.min(100, v + 10))}
+        >
+          +10
+        </Button.Root>
+        <Button.Root mode="lighter" size="s" type="button" onClick={() => setValue(0)}>
+          Reset
+        </Button.Root>
+      </div>
+    </div>
+  );
+}

package/src/components/progress-circle/examples/dashboard-ring.tsx

@@ -0,0 +1,36 @@
+import { Card, Icon, ProgressCircle, Typography } from "prime-ui-kit";
+
+/** KPI tile with a ring in `Card.Media` — extended pattern; no matching `circle-*` playground snippet. */
+export default function DashboardRingExample() {
+  return (
+    <Card.Root variant="mini-media">
+      <Card.IconBox aria-hidden>
+        <Icon name="nav.layoutGrid" aria-hidden />
+      </Card.IconBox>
+      <Card.Stack>
+        <Card.Label>Quarter target</Card.Label>
+        <Card.Value>68%</Card.Value>
+      </Card.Stack>
+      <Card.Media>
+        <div
+          style={{
+            display: "flex",
+            justifyContent: "center",
+            paddingBlock: "var(--prime-sys-spacing-s)",
+          }}
+        >
+          <ProgressCircle.Root
+            value={68}
+            max={100}
+            size="m"
+            label="Quarter target, 68 percent complete"
+          >
+            <Typography.Root as="span" variant="body-small" weight="medium">
+              68%
+            </Typography.Root>
+          </ProgressCircle.Root>
+        </div>
+      </Card.Media>
+    </Card.Root>
+  );
+}

package/src/components/progress-circle/examples/max-scale.tsx

@@ -0,0 +1,61 @@
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+/** Same fill ratio with different `max` scales (percent, steps, large quotas) (playground: `snippets/progress/circle-max-scale.tsx`). */
+export default function MaxScaleExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        gap: "var(--prime-sys-spacing-xl)",
+        alignItems: "flex-end",
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          gap: "var(--prime-sys-spacing-s)",
+        }}
+      >
+        <Typography.Root as="span" variant="body-compact" tone="muted">
+          45 of 100
+        </Typography.Root>
+        <ProgressCircle.Root value={45} max={100} size="m">
+          45%
+        </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">
+          3 of 5 steps
+        </Typography.Root>
+        <ProgressCircle.Root value={3} max={5} size="m">
+          3/5
+        </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">
+          750 of 1000
+        </Typography.Root>
+        <ProgressCircle.Root value={750} max={1000} size="m">
+          75%
+        </ProgressCircle.Root>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,77 @@
+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() {
+  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>
+  );
+}

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

@@ -0,0 +1,95 @@
+import { ProgressCircle, Typography } from "prime-ui-kit";
+
+/**
+ * Typical fill levels and clamping: `value` is clamped to `[0, max]`; if `max <= 0`, scale falls back to `100`.
+ * Playground: `snippets/progress/circle-states.tsx`.
+ */
+export default function StatesExample() {
+  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">
+          value 0
+        </Typography.Root>
+        <ProgressCircle.Root value={0} size="m">
+          0%
+        </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">
+          value 50
+        </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">
+          value 100
+        </Typography.Root>
+        <ProgressCircle.Root value={100} size="m">
+          100%
+        </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">
+          value −20 → 0
+        </Typography.Root>
+        <ProgressCircle.Root value={-20} size="m">
+          clamp
+        </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">
+          value 140, max 100
+        </Typography.Root>
+        <ProgressCircle.Root value={140} max={100} size="m">
+          full
+        </ProgressCircle.Root>
+      </div>
+    </div>
+  );
+}