prime-ui-kit 0.3.1 → 0.4.0

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

@@ -0,0 +1,42 @@
+import { Button, Popover, Typography } from "prime-ui-kit";
+
+import styles from "./popover-examples.module.css";
+
+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 `align`; the kit may flip at the viewport edge.
+ */
+export default function PlacementExample() {
+  return (
+    <div className={styles.placementGrid}>
+      {demos.map(({ label, side, align }) => (
+        <Popover.Root key={label}>
+          <Popover.Trigger asChild>
+            <Button.Root
+              className={styles.placementTrigger}
+              mode="stroke"
+              size="m"
+              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/popover-examples.module.css

@@ -0,0 +1,104 @@
+.sizesRow {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: flex-start;
+  gap: var(--prime-sys-spacing-x3);
+}
+
+.placementGrid {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--prime-sys-spacing-x3);
+}
+
+.placementTrigger {
+  min-width: 10rem;
+}
+
+.controlledRow {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--prime-sys-spacing-x3);
+}
+
+.stateLine {
+  margin: 0;
+}
+
+.compositionHeader {
+  display: flex;
+  align-items: center;
+  gap: var(--prime-sys-spacing-x2);
+}
+
+.headerIcon {
+  width: var(--prime-sys-size-control-m-icon);
+  height: var(--prime-sys-size-control-m-icon);
+  flex-shrink: 0;
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.checkboxStack {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: var(--prime-sys-spacing-x3);
+}
+
+.fullWidthTrigger {
+  width: 100%;
+  justify-content: center;
+}
+
+.narrowColumn {
+  width: min(12rem, 100%);
+}
+
+.textLinkTrigger {
+  margin: 0;
+  border: none;
+  padding: 0;
+  background: none;
+  font: inherit;
+  font-size: var(--prime-sys-size-control-m-text);
+  font-weight: var(--prime-sys-typography-weight-medium);
+  color: var(--prime-sys-color-content-accent);
+  text-decoration: underline;
+  text-underline-offset: 0.2em;
+  cursor: pointer;
+  text-align: inherit;
+}
+
+.textLinkTrigger:focus-visible {
+  outline: 2px solid var(--prime-sys-color-border-focus);
+  outline-offset: 2px;
+  border-radius: var(--prime-sys-shape-radius-s);
+}
+
+.panelTextMuted {
+  margin: 0;
+  max-width: 22rem;
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.flushText {
+  margin: 0;
+  max-width: 18rem;
+  color: var(--prime-sys-color-content-secondary);
+}
+
+.triggerWide {
+  width: 14rem;
+  justify-content: space-between;
+}
+
+.formPanel {
+  width: min(22rem, 100vw);
+}
+
+.actionsRow {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--prime-sys-spacing-x2);
+}

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/popover/examples/sizes.tsx

@@ -0,0 +1,30 @@
+import { Button, Popover } from "prime-ui-kit";
+
+import styles from "./popover-examples.module.css";
+
+const sizes = ["s", "m", "l", "xl"] as const;
+
+/**
+ * Content `size` tier: padding, min width, and helper text scale (`ControlSizeProvider`).
+ */
+export default function PopoverSizesExample() {
+  return (
+    <div className={styles.sizesRow}>
+      {sizes.map((size) => (
+        <Popover.Root key={size}>
+          <Popover.Trigger asChild>
+            <Button.Root mode="stroke" size="m" variant="neutral">
+              Size {size}
+            </Button.Root>
+          </Popover.Trigger>
+          <Popover.Content align="start" insetGap="x2" insetPadding="x2" side="bottom" size={size}>
+            <p className={styles.panelTextMuted}>
+              Panel with <code>size=&quot;{size}&quot;</code>: padding, min width, and type scale
+              from the control tier.
+            </p>
+          </Popover.Content>
+        </Popover.Root>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,36 @@
+import { Button, Popover } from "prime-ui-kit";
+
+import styles from "./popover-examples.module.css";
+
+/**
+ * `defaultOpen` for initially visible panel; disabled trigger does not open the popover.
+ */
+export default function PopoverStatesExample() {
+  return (
+    <div className={styles.sizesRow}>
+      <Popover.Root defaultOpen>
+        <Popover.Trigger asChild>
+          <Button.Root mode="stroke" size="m" variant="neutral">
+            Starts open
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom" size="m">
+          <p className={styles.panelTextMuted}>
+            <code>defaultOpen</code> on the root — initial open state without lifting state up.
+          </p>
+        </Popover.Content>
+      </Popover.Root>
+
+      <Popover.Root>
+        <Popover.Trigger asChild>
+          <Button.Root disabled mode="stroke" size="m" variant="neutral">
+            Trigger disabled
+          </Button.Root>
+        </Popover.Trigger>
+        <Popover.Content align="start" insetGap="x3" insetPadding="x2" side="bottom" size="m">
+          <p className={styles.panelTextMuted}>Panel never opens while the button is disabled.</p>
+        </Popover.Content>
+      </Popover.Root>
+    </div>
+  );
+}

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

@@ -1,22 +1,58 @@
 # 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).
+
+### Playground (`playground/sections/ProgressBarSection.tsx`)
+
+The section renders snippets from **`playground/snippets/progress/`** (bar demos only):
+
+| Demo (section) | Snippet | What it shows |
+|----------------|---------|----------------|
+| Размеры | [`bar-sizes.tsx`](../../../playground/snippets/progress/bar-sizes.tsx) | **`size`** **`s`**, **`m`**, **`l`**, **`xl`**, each with a **`label`** (track height and label scale from control-size tokens). |
+| Values | [`bar-values.tsx`](../../../playground/snippets/progress/bar-values.tsx) | **`value`** **`0`**, **`25`**, **`75`**, **`100`** without **`label`**. |
+| With label | [`bar-label.tsx`](../../../playground/snippets/progress/bar-label.tsx) | **`value={60}`**, **`label="Profile completion"`** (same English copy as the snippet; section preview matches this structure). |
+
+Other bar-only snippets in the same folder (**`bar-full-width`**, **`bar-states`**, **`bar-controlled`**, **`bar-composition`**) are not mounted in **`ProgressBarSection`**; they follow the same **`@/components/progress-bar`** import style for local dev.
+
+### Example files in `examples/`
+
+Imports use **`"prime-ui-kit"`** so the same patterns work in an app. **`sizes`**, **`values`**, and **`labeled`** mirror the three playground frames above (same structure; English labels in **`sizes`** where the snippet uses Russian).
+
+| File | Scenario |
+|------|----------|
+| [`sizes.tsx`](examples/sizes.tsx) | **`size`** ladder **`s`–`xl`** with labels (`snippets/progress/bar-sizes.tsx`). |
+| [`values.tsx`](examples/values.tsx) | **`value`** 0 / 25 / 75 / 100, no **`label`** (`snippets/progress/bar-values.tsx`). |
+| [`labeled.tsx`](examples/labeled.tsx) | **`label`** + **`aria-labelledby`** wiring (`snippets/progress/bar-label.tsx`). |
+| [`upload-progress.tsx`](examples/upload-progress.tsx) | Controlled **`value`** from progress percent; filename and actions in surrounding copy. |
+| [`step-progress.tsx`](examples/step-progress.tsx) | **`value`** / **`max`** as step *k* of *n*. |
+| [`indeterminate-busy-state.tsx`](examples/indeterminate-busy-state.tsx) | Unknown duration: **`Button`** **`loading`**, not an indeterminate **`ProgressBar`**. |
+| [`wizard-composition.tsx`](examples/wizard-composition.tsx) | **Typography** + bar + muted helper (aligned with **`bar-composition.tsx`** idea; app-ready English). |
 
 ### Minimal example
 
@@ -28,15 +64,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 +78,24 @@ 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).
+- Playground bar frames: **`playground/sections/ProgressBarSection.tsx`** uses **`bar-sizes`**, **`bar-values`**, **`bar-label`**; **`examples/sizes`**, **`examples/values`**, **`examples/labeled`** mirror those three for **`prime-ui-kit`** consumers.

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; `aria-labelledby` references the label (playground: `snippets/progress/bar-label.tsx`). */
+export default function ProgressBarLabeledExample() {
+  return <ProgressBar.Root value={60} label="Profile completion" />;
+}

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/sizes.tsx

@@ -0,0 +1,13 @@
+import { ProgressBar } from "prime-ui-kit";
+
+/** 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" />
+    </>
+  );
+}

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/values.tsx

@@ -0,0 +1,13 @@
+import { ProgressBar } from "prime-ui-kit";
+
+/** Determinate fill at 0%, 25%, 75%, and 100% without labels (playground: `snippets/progress/bar-values.tsx`). */
+export default function ProgressBarValuesExample() {
+  return (
+    <>
+      <ProgressBar.Root value={0} />
+      <ProgressBar.Root value={25} />
+      <ProgressBar.Root value={75} />
+      <ProgressBar.Root value={100} />
+    </>
+  );
+}

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>
+  );
+}