prime-ui-kit 0.3.1 → 0.3.2

package/src/components/popover/COMPONENT.md

@@ -1,6 +1,6 @@
 # Popover
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Default sizing:** when designing screens and examples, start with **`m`** for `size` (where a size axis exists) unless the scenario explicitly needs another value.
 
 ## About
 
@@ -22,13 +22,13 @@ A composite “anchor + portaled panel”: clicking the trigger toggles a non-mo
 ### Minimal example
 
 ```tsx
-import { Popover } from "prime-ui-kit";
+import { Button, Popover } from "prime-ui-kit";
 
 export function Example() {
   return (
     <Popover.Root>
       <Popover.Trigger asChild>
-        <button type="button">Open</button>
+        <Button.Root type="button">Open</Button.Root>
       </Popover.Trigger>
       <Popover.Content insetPadding="x2" insetGap="x3">
         Panel
@@ -38,6 +38,60 @@ export function Example() {
 }
 ```
 
+### Canonical panel (reference)
+
+Typical English recipe: stroke **`Button.Root`** trigger, **`insetPadding` / `insetGap`**, and short body copy. Source of truth (stays in sync with the snippet mindset below): **`examples/canonical-panel.tsx`**.
+
+```tsx
+import { Button, Popover, Typography } from "prime-ui-kit";
+
+export function ShippingEstimatePopover() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <Button.Root mode="stroke" size="m" variant="neutral">
+          View details
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom" size="m">
+        <Typography.Root as="p" variant="body-small" weight="semibold">
+          Shipping estimate
+        </Typography.Root>
+        <Typography.Root as="p" variant="body-small">
+          Arrives Tuesday–Thursday for metro addresses. Rural routes may add one business day.
+        </Typography.Root>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}
+```
+
+### Example files in `examples/`
+
+Runnable demos live next to this file. Imports use **`"prime-ui-kit"`** so the same snippets work in an app after installing the package.
+
+| File | Intent |
+|------|--------|
+| `canonical-panel.tsx` | Default composition: stroke trigger, inset spacing, short copy |
+| `date-trigger.tsx` | Date-style trigger label; native **`type="date"`** field; **`trapFocus`** |
+| `rich-content.tsx` | Badges, **`Divider`**, **`Hint`** — denser non-modal panel |
+| `placement.tsx` | **`side`** and **`align`** grid; flip behavior called out in copy |
+| `form-in-popover.tsx` | Controlled root, small form, **`trapFocus`**, submit closes |
+
+Broader Russian demos and layout variants: **`playground/snippets/popover/`** (for example `composition.tsx`, `placement.tsx`, `controlled.tsx`).
+
+### Extended usage
+
+- **Controlled popovers:** pass **`open`** and **`onOpenChange`** on **`Popover.Root`**; keep **`Popover.Trigger`** and **`Popover.Content`** as siblings. Close from inside the panel by calling the same setter or relying on outside click / Escape.
+- **Forms and focus:** set **`trapFocus={true}`** on **`Popover.Content`** when several controls should keep Tab cycles inside the panel (see **`examples/form-in-popover.tsx`** and **`examples/date-trigger.tsx`**).
+- **Match trigger width:** use **`sameMinWidthAsTrigger`** when the panel should align visually with a full-width or fixed-width anchor (still bounded by max width and viewport).
+- **Nested Select:** portaled Select listbox clicks owned by the panel are not treated as outside closes (see `isPortaledSelectListboxOwnedByContainer` in implementation).
+- **Density:** tune **`size`** on **`Popover.Content`** for nested controls and **`insetPadding` / `insetGap`** for internal vertical rhythm; optional **`className`** on **`Content`** for scoped layout hooks.
+
+### Note for LLMs
+
+When generating **Popover** markup for this library: (1) **`Popover.Trigger`** accepts **exactly one** child element—no fragments or multiple nodes. (2) Prefer **`Button.Root`**, **`LinkButton.Root`**, or another kit control as the trigger so sizing and focus styles stay on the design-system tier. (3) Only **`side="top"`** and **`side="bottom"`** are valid; do not assume left/right anchoring. (4) For copy-paste starting points, mirror **`examples/canonical-panel.tsx`**, then adapt **`date-trigger.tsx`**, **`rich-content.tsx`**, **`placement.tsx`**, or **`form-in-popover.tsx`**. (5) Do not wrap kit components to restyle them; use **`size`**, **`variant`**, **`mode`**, **`insetPadding`**, **`insetGap`**, and documented props only.
+
 ## Rules
 
 - **Uncontrolled:** use `defaultOpen` on `Popover.Root` for the initial open state after mount.
@@ -89,5 +143,15 @@ export function Example() {
 - [Select](../select/COMPONENT.md), [Dropdown](../dropdown/COMPONENT.md) — nested overlays; Select listbox clicks are treated as inside the popover when owned by the panel.
 - [Input](../input/COMPONENT.md), [Textarea](../textarea/COMPONENT.md), [Checkbox](../checkbox/COMPONENT.md), [Switch](../switch/COMPONENT.md) — fields inside the panel.
 - [Typography](../typography/COMPONENT.md), [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — text and labels in the panel.
+- [Badge](../badge/COMPONENT.md), [Divider](../divider/COMPONENT.md) — structured panel chrome.
 - [Modal](../modal/COMPONENT.md) — blocking modal flow.
 - [Tooltip](../tooltip/COMPONENT.md) — short hover/focus hint without an action panel.
+
+</think>
+<think>
+I made a mistake in Related - Switch should link to COMPONENT.md not Switch.tsx
+</think>
+
+
+<｜tool▁calls▁begin｜><｜tool▁call▁begin｜>
+Glob

package/src/components/popover/examples/canonical-panel.tsx

@@ -0,0 +1,24 @@
+import { Button, Popover, Typography } from "prime-ui-kit";
+
+/**
+ * Canonical panel: stroke trigger, inset spacing, and a short description inside the portaled surface.
+ */
+export default function CanonicalPanelExample() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <Button.Root mode="stroke" size="m" variant="neutral">
+          View details
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom" size="m">
+        <Typography.Root as="p" variant="body-small" weight="semibold">
+          Shipping estimate
+        </Typography.Root>
+        <Typography.Root as="p" variant="body-small">
+          Arrives Tuesday–Thursday for metro addresses. Rural routes may add one business day.
+        </Typography.Root>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

package/src/components/popover/examples/date-trigger.tsx

@@ -0,0 +1,33 @@
+import { Button, Input, Popover, Typography } from "prime-ui-kit";
+
+/**
+ * Date-oriented trigger: formatted label on the anchor, native date input inside the panel.
+ */
+export default function DateTriggerExample() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <Button.Root aria-label="Choose due date" mode="stroke" size="m" variant="neutral">
+          Due · Mar 27, 2025
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content
+        align="start"
+        insetGap="x3"
+        insetPadding="x2"
+        side="bottom"
+        size="m"
+        trapFocus
+      >
+        <Typography.Root as="p" variant="body-small" weight="semibold">
+          Adjust due date
+        </Typography.Root>
+        <Input.Root hint="Uses the control size from Popover.Content." label="Due date" size="m">
+          <Input.Wrapper>
+            <Input.Field defaultValue="2025-03-27" name="dueDate" type="date" />
+          </Input.Wrapper>
+        </Input.Root>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

package/src/components/popover/examples/form-in-popover.tsx

@@ -0,0 +1,79 @@
+import { Button, Input, Popover, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+/**
+ * Short form inside the panel: enable trapFocus when multiple fields need a tight tab cycle.
+ */
+export default function FormInPopoverExample() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Trigger asChild>
+        <Button.Root mode="stroke" size="m" variant="neutral">
+          Quick edit
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content
+        align="start"
+        insetGap="x3"
+        insetPadding="x2"
+        side="bottom"
+        size="m"
+        trapFocus
+      >
+        <form
+          style={{ width: "min(22rem, 100vw)" }}
+          onSubmit={(e) => {
+            e.preventDefault();
+            setOpen(false);
+          }}
+        >
+          <Typography.Root as="p" variant="body-small" weight="semibold">
+            Workspace label
+          </Typography.Root>
+          <div
+            style={{
+              display: "flex",
+              flexDirection: "column",
+              gap: "var(--prime-sys-spacing-x3)",
+              marginTop: "var(--prime-sys-spacing-x2)",
+            }}
+          >
+            <Input.Root label="Display name" size="m">
+              <Input.Wrapper>
+                <Input.Field autoComplete="organization" name="displayName" type="text" />
+              </Input.Wrapper>
+            </Input.Root>
+            <Input.Root label="Slug" hint="Lowercase, no spaces." size="m">
+              <Input.Wrapper>
+                <Input.Field name="slug" type="text" />
+              </Input.Wrapper>
+            </Input.Root>
+          </div>
+          <div
+            style={{
+              display: "flex",
+              justifyContent: "flex-end",
+              gap: "var(--prime-sys-spacing-x2)",
+              marginTop: "var(--prime-sys-spacing-x3)",
+            }}
+          >
+            <Button.Root
+              mode="stroke"
+              size="m"
+              type="button"
+              variant="neutral"
+              onClick={() => setOpen(false)}
+            >
+              Cancel
+            </Button.Root>
+            <Button.Root size="m" type="submit" variant="primary">
+              Save
+            </Button.Root>
+          </div>
+        </form>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

package/src/components/popover/examples/placement.tsx

@@ -0,0 +1,42 @@
+import { Button, Popover, Typography } from "prime-ui-kit";
+
+type Demo = { label: string; side: "top" | "bottom"; align: "start" | "center" | "end" };
+
+const demos: Demo[] = [
+  { label: "Bottom · start", side: "bottom", align: "start" },
+  { label: "Bottom · center", side: "bottom", align: "center" },
+  { label: "Bottom · end", side: "bottom", align: "end" },
+  { label: "Top · start", side: "top", align: "start" },
+];
+
+/**
+ * Preferred side and alignment; the kit may flip at the viewport edge.
+ */
+export default function PlacementExample() {
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexWrap: "wrap",
+        gap: "var(--prime-sys-spacing-x3)",
+        alignItems: "flex-start",
+      }}
+    >
+      {demos.map(({ label, side, align }) => (
+        <Popover.Root key={label}>
+          <Popover.Trigger asChild>
+            <Button.Root mode="stroke" size="m" style={{ minWidth: "10rem" }} variant="neutral">
+              {label}
+            </Button.Root>
+          </Popover.Trigger>
+          <Popover.Content align={align} insetGap="x2" insetPadding="x2" side={side} size="m">
+            <Typography.Root as="p" variant="body-small">
+              <code>side=&quot;{side}&quot;</code>, <code>align=&quot;{align}&quot;</code>. Near the
+              viewport edge the panel may flip to stay on screen.
+            </Typography.Root>
+          </Popover.Content>
+        </Popover.Root>
+      ))}
+    </div>
+  );
+}

package/src/components/popover/examples/rich-content.tsx

@@ -0,0 +1,39 @@
+import { Badge, Button, Divider, Hint, Popover, Typography } from "prime-ui-kit";
+
+/**
+ * Rich panel: badges, section divider, supporting hint — still a lightweight non-modal surface.
+ */
+export default function RichContentExample() {
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <Button.Root mode="ghost" size="m" variant="neutral">
+          Release notes
+        </Button.Root>
+      </Popover.Trigger>
+      <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom" size="m">
+        <div style={{ display: "flex", flexWrap: "wrap", gap: "var(--prime-sys-spacing-x2)" }}>
+          <Badge.Root color="green" size="m" variant="light">
+            Stable
+          </Badge.Root>
+          <Badge.Root color="blue" size="m" variant="stroke">
+            v2.4
+          </Badge.Root>
+        </div>
+        <Typography.Root as="p" variant="body-small" weight="semibold">
+          What changed
+        </Typography.Root>
+        <Typography.Root as="p" variant="body-small">
+          Command menu now respects nested Select listboxes without closing the panel on outside
+          detection.
+        </Typography.Root>
+        <Divider.Root size="m" variant="text">
+          Heads-up
+        </Divider.Root>
+        <Hint.Root size="m" variant="default">
+          Prefer Modal when the flow must block the page or trap focus by default.
+        </Hint.Root>
+      </Popover.Content>
+    </Popover.Root>
+  );
+}

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

@@ -1,22 +1,42 @@
 # ProgressBar
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Default `size`:** use **`m`** for the size axis unless the layout explicitly needs another tier.
 
-## About
+## Canonical
 
-A horizontal completion indicator built on the native `progress` element: fill is driven by `value` and `max`, with optional text label and `size` for track density.
+- **`ProgressBar`** — horizontal determinate meter: only **`ProgressBar.Root`** is public; it wraps a native **`<progress>`** (role **`progressbar`**) and optional **`label`**.
+- **`value`** is **required** and clamped to **`[0, max]`**; **`max`** defaults to **`100`** (if **`max <= 0`**, **`100`** is used).
+- **`size`:** **`s` | `m` | `l` | `xl`** — track height and label scale (**`ProgressBarSize`**).
+- **Not indeterminate:** the API does not omit **`value`** or set an indeterminate native state — for unknown duration, use loading patterns on controls (for example [Button](../button/COMPONENT.md) **`loading`** + **`Button.Spinner`**) or other kit feedback; see **`examples/indeterminate-busy-state.tsx`**.
+- **A11y:** with **`label`**, **`aria-labelledby`** references the label **`span`**; the bar is not focusable.
+- **No `disabled` / `loading` / `error`** on the root — hide or mute the block at screen level if needed.
 
-- **Use** for determinate tasks—uploads, downloads, or any operation where progress maps to a numeric range.
-- **Use** in multi-step flows when the user should see how far they are through a bounded sequence (steps, checklist, wizard).
-- **Use** with a `label` when the bar needs a short visible name tied to the meter for assistive tech.
-- **Do not use** for indeterminate or endless “busy” feedback; this API always requires a numeric `value` (use a spinner or another pattern instead).
-- **Do not use** for vertical or circular meters; the track is horizontal only—for a circular indicator in the kit, see Related.
-- **Do not use** expecting extra native attributes on the inner `progress`; they are not forwarded—wrap the component if you need custom markup.
+## Extended
 
-## Composition
+### About
 
-- **`ProgressBar`** is a single-part namespace: only **`ProgressBar.Root`** is public.
-- **`ProgressBar.Root`** renders a wrapper `div` with `data-size`, an optional **`label`** as a `span` with a generated `id`, and a native **`<progress>`** for the track. The bar spans the full width of its container.
+`ProgressBar` is a horizontal completion indicator for operations that map to a numeric range: file transfer, form steps, or any bounded task.
+
+- **When to use** — uploads, downloads, or sync where you can compute **`value`** and **`max`**.
+- **When to use** — multi-step flows where “step *k* of *n*” should match a single fill (**`value={k}`**, **`max={n}`**).
+- **When to use** — when a short visible name should be tied to the meter for sighted users and assistive tech (**`label`**).
+- **When not to use** — indeterminate or endless busy states without a numeric model; prefer **`Button`** **`loading`**, spinners, or other patterns.
+- **When not to use** — vertical or circular meters; for a ring indicator see [ProgressCircle](../progress-circle/COMPONENT.md).
+- **When not to use** — when you need extra native attributes on **`<progress>`** beyond what the wrapper sets; they are not forwarded — compose or wrap at the app layer if required.
+
+### Composition
+
+- **`ProgressBar.Root`** — outer **`div`** with **`data-size`**, optional **`label`** (**`<span>`** + generated **`id`**), then **`<progress>`** with **`value`**, **`max`**, and **`className`** on the track. Width follows the parent (full width of the container).
+
+### Scenarios (see `examples/`)
+
+| Scenario | Approach |
+|----------|----------|
+| Labeled meter | Set **`label`** so copy sits above the track and **`aria-labelledby`** is wired. → [`examples/labeled.tsx`](examples/labeled.tsx) |
+| Upload / download | Update **`value`** from bytes (or percent); keep filename or status in [Typography](../typography/COMPONENT.md) around the bar. → [`examples/upload-progress.tsx`](examples/upload-progress.tsx) |
+| Step progress | **`value`** = current step, **`max`** = total steps; label like “Step *k* of *n*”. → [`examples/step-progress.tsx`](examples/step-progress.tsx) |
+| Indeterminate / unknown duration | Do **not** force **`ProgressBar`** without a real **`value`**; use **`Button`** **`loading`** (and optional muted copy). → [`examples/indeterminate-busy-state.tsx`](examples/indeterminate-busy-state.tsx) |
+| Wizard / report block | Stack **Typography** + **`ProgressBar.Root`** + muted helper text. → [`examples/wizard-composition.tsx`](examples/wizard-composition.tsx) |
 
 ### Minimal example
 
@@ -28,15 +48,11 @@ export function Example() {
 }
 ```
 
-## Rules
+### Rules
 
-- **`value`** is required and clamped to **`[0, max]`**; negative values become `0`, values above `max` become `max`.
-- **`max`** defaults to **`100`**; if **`max <= 0`**, the implementation uses **`100`** as the effective maximum.
-- **`size`** defaults to **`m`**; allowed values are **`s`**, **`m`**, **`l`**, **`xl`** (`ProgressBarSize`).
-- There is no **`disabled`**, **`loading`**, or **`error`** prop—mute or hide the block at the screen level if needed.
-- Native **`progress`** exposes the **`progressbar`** role with **`value`** / **`max`** to the accessibility tree; with **`label`**, **`aria-labelledby`** points at the label element.
-- The bar is not interactive and is not keyboard-focusable; keep focus on real controls nearby.
-- “Controlled” usage is just React state passed into **`value`**; there is no separate uncontrolled mode with an internal store.
+- **Controlled usage** — pass React state into **`value`**; there is no internal uncontrolled store.
+- **Refs** — **`ref`** targets the native **`<progress>`** element.
+- **Clamping** — negative **`value`** becomes **`0`**; **`value > max`** becomes **`max`**.
 
 ## API
 
@@ -46,14 +62,23 @@ export function Example() {
 |------|------|---------|----------|-------------|
 | `value` | `number` | — | Yes | Current value; clamped to `[0, max]` after `max` is normalized. |
 | `max` | `number` | `100` | No | Upper bound; if `max <= 0`, `100` is used. |
-| `label` | `string` | — | No | Text above the track; when set, the progress element gets `aria-labelledby` referencing the label. |
+| `label` | `string` | — | No | Text above the track; `aria-labelledby` references this element when set. |
 | `size` | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Track height and label typography scale. |
 | `className` | `string` | — | No | Class on the outer wrapper around the label and `progress`. |
 | `ref` | `React.Ref<HTMLProgressElement>` | — | No | Ref to the native `progress` element. |
 
 ## Related
 
-- [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md) — stacked proportional segments (e.g. status mix) instead of a single value.
-- [ProgressCircle](../progress-circle/COMPONENT.md) — circular determinate indicator when layout calls for a ring or compact numeric emphasis.
+- [SegmentedProgressBar](../segmented-progress-bar/COMPONENT.md) — multiple proportional segments instead of one value.
+- [ProgressCircle](../progress-circle/COMPONENT.md) — circular determinate indicator.
 - [Typography](../typography/COMPONENT.md) — headings and supporting copy around a status block.
-- [Button](../button/COMPONENT.md) — cancel, pause, or actions next to the bar.
+- [Button](../button/COMPONENT.md) — cancel, pause, or **`loading`** next to long-running work.
+
+## LLM note
+
+- Export: **`import { ProgressBar } from "prime-ui-kit"`** — **`ProgressBar.Root`** only.
+- **`ProgressBarRootProps`**: **`value`** (required), **`max?`**, **`label?`**, **`size?`**, **`className?`**, **`ref?`** — no `disabled`, `loading`, or indeterminate flag.
+- **`size`** literals: **`s`**, **`m`**, **`l`**, **`xl`** — default **`m`**.
+- **`value`** is always required; do not suggest omitting **`value`** for a “loading” bar — use **Button** **`loading`** / **`Button.Spinner`** or another pattern.
+- Native **`<progress>`** is not a props bag: extra attributes are **not** forwarded from **`ProgressBar.Root`**.
+- Step flows: **`value={currentStep}`**, **`max={totalSteps}`** (not necessarily 0–100).

package/src/components/progress-bar/examples/indeterminate-busy-state.tsx

@@ -0,0 +1,21 @@
+import { Button, Typography } from "prime-ui-kit";
+
+import s from "./progress-bar-examples.module.css";
+
+/**
+ * `ProgressBar.Root` always requires a numeric `value` — it cannot represent a native indeterminate meter.
+ * For unknown duration, use loading affordances on the relevant control (and optional supporting text).
+ */
+export default function ProgressBarIndeterminateBusyExample() {
+  return (
+    <div className={s.stack}>
+      <Typography.Root variant="body-small" tone="muted">
+        Preparing your workspace…
+      </Typography.Root>
+      <Button.Root type="button" loading variant="neutral" mode="stroke" size="m">
+        <Button.Spinner />
+        Please wait
+      </Button.Root>
+    </div>
+  );
+}

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

@@ -0,0 +1,6 @@
+import { ProgressBar } from "prime-ui-kit";
+
+/** Visible label above the track; the native `progress` gets `aria-labelledby` for the same text. */
+export default function ProgressBarLabeledExample() {
+  return <ProgressBar.Root value={60} max={100} label="Profile completion" size="m" />;
+}

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

@@ -0,0 +1,22 @@
+/* Examples: layout only; colors/spacing from semantic tokens. */
+
+.stack {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-m);
+  min-width: 0;
+}
+
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-sys-spacing-s);
+  max-width: 28rem;
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-x2);
+  margin-top: var(--prime-sys-spacing-s);
+}

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

@@ -0,0 +1,23 @@
+import { ProgressBar, Typography } from "prime-ui-kit";
+
+import s from "./progress-bar-examples.module.css";
+
+/** Map the current step index and total steps to `value` / `max` so the bar matches “step k of n”. */
+export default function ProgressBarStepProgressExample() {
+  const currentStep = 2;
+  const totalSteps = 5;
+
+  return (
+    <div className={s.stack}>
+      <Typography.Root variant="body-large" weight="semibold">
+        Account setup
+      </Typography.Root>
+      <ProgressBar.Root
+        value={currentStep}
+        max={totalSteps}
+        label={`Step ${currentStep} of ${totalSteps}`}
+        size="m"
+      />
+    </div>
+  );
+}

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

@@ -0,0 +1,27 @@
+import { ProgressBar, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import s from "./progress-bar-examples.module.css";
+
+/** Determinate upload: drive `value` from bytes transferred; keep filename and percent in surrounding copy. */
+export default function ProgressBarUploadExample() {
+  const [loaded, setLoaded] = React.useState(0);
+  const total = 100;
+
+  return (
+    <div className={s.card}>
+      <Typography.Root variant="body-small" tone="muted">
+        quarterly-report.pdf
+      </Typography.Root>
+      <ProgressBar.Root value={loaded} max={total} label={`Upload progress: ${loaded}%`} size="m" />
+      <div className={s.actions}>
+        <button type="button" onClick={() => setLoaded((n) => Math.max(0, n - 20))}>
+          −20%
+        </button>
+        <button type="button" onClick={() => setLoaded((n) => Math.min(total, n + 20))}>
+          +20%
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/components/progress-bar/examples/wizard-composition.tsx

@@ -0,0 +1,18 @@
+import { ProgressBar, Typography } from "prime-ui-kit";
+
+import s from "./progress-bar-examples.module.css";
+
+/** Stack heading, bar, and muted helper copy — typical block in a wizard or long-running task panel. */
+export default function ProgressBarWizardCompositionExample() {
+  return (
+    <div className={s.card}>
+      <Typography.Root variant="body-large" weight="semibold">
+        Generating report
+      </Typography.Root>
+      <ProgressBar.Root value={72} max={100} label="Collecting data" size="m" />
+      <Typography.Root variant="body-small" tone="muted">
+        Usually under five minutes; you can return to the task list.
+      </Typography.Root>
+    </div>
+  );
+}