prime-ui-kit 0.7.11 → 0.9.0

package/src/components/slider/COMPONENT.md

@@ -1,86 +1,132 @@
 # Slider
 
-**Default sizing:** when designing screens and examples, start with **`m`** for `size` wherever a size axis exists unless the scenario explicitly needs another value.
+**Category:** selection
 
-## About
+> A slider for picking an approximate numeric value within a range, with an optional label and value readout.
 
-A horizontal range control built on the native `input type="range"`, with optional text label and kit sizing (`s`–`xl`).
+## When to use
+- An approximate value where the position matters more than the exact number: volume, brightness, opacity, a price ceiling.
+- A bounded numeric setting with a coarse `step` (25%, 0.5 stars).
+- Next to a number input when users need both dragging and exact entry (controlled, shared state).
 
-**When to use**
+## When not to use
+- An exact number that users type (quantity, amount) → use [Input](../input/COMPONENT.md) with `type="number"` instead.
+- One of a few named levels (low / medium / high) → use [SegmentedControl](../segmented-control/COMPONENT.md) or [Radio](../radio/COMPONENT.md) instead.
+- A two-handle range (from–to) → not supported; use two inputs.
+- On/off → use [Switch](../switch/COMPONENT.md) instead.
 
-- Picking a number along a continuous or stepped interval: volume, brightness, percentages, temperature bands, or filter caps (for example a maximum price).
-- When native range keyboard and pointer behavior is enough and you want minimal custom logic.
-
-**When not to use**
-
-- Vertical sliders — the implementation is horizontal only.
-- When you need thumb labels, icons, or other slots on the track — compose with surrounding layout and text.
-- Built-in error, required, loading, or read-only modes — use form primitives and hints around the control.
-- A small set of fixed choices — prefer radio or segmented controls instead of a continuous range.
+## Import
+```tsx
+import { Slider } from "prime-ui-kit";
+```
 
-## Composition
+## Anatomy
+```
+Slider.Root
+├─ header row (only with `label` or `showValue`)
+│  ├─ Label            from `label`, linked to the input
+│  └─ <output>         from `showValue`, formatted value
+└─ <input type="range">
+```
+Single part: everything is configured by `Slider.Root` props.
 
-- **`Slider`** is a single-part API: **`Slider.Root`** wraps **`ControlSizeProvider`**, an optional **`label`** (linked to the input with `htmlFor` / `id`), and one styled **`input type="range"`**.
-- The root `div` carries **`data-size`** from **`size`**; there are no other exported subcomponents.
+## API
 
-### Canonical example
+### Slider.Root
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number` | — | Controlled value (clamped to `[min, max]`); use with `onValueChange`. |
+| `defaultValue` | `number` | `min` | Initial value in uncontrolled mode (clamped). |
+| `onValueChange` | `(value: number) => void` | — | Called on every thumb move. |
+| `min` | `number` | `0` | Lower bound. |
+| `max` | `number` | `100` | Upper bound. |
+| `step` | `number` | `1` | Step of the native range; fractional steps work. |
+| `label` | `ReactNode` | — | Visible label (`Label`), linked to the input via `htmlFor`. Without it, pass `aria-label`. |
+| `showValue` | `boolean` | `false` | Shows the current value at the end of the label row (tabular numbers). |
+| `formatValue` | `(value: number) => string` | — | Formats the shown value and sets `aria-valuetext` (e.g. `` (v) => `${v} °C` ``). |
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Size tier of the thumb and the label row. |
+| `disabled` | `boolean` | — | Disables the input; mutes track, fill and value. |
+| `aria-label` | `string` | — | Accessible name when there is no visible `label`. |
+| `className` | `string` | — | Class on the root `div`. |
+
+No other native props, no `name`, no ref forwarding.
+
+## Variants
+No `variant`/`tone`/`color`. Axes: `size`, `showValue` (visual flag).
+
+### size
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 14px thumb, 4px track, 12/16 label | dense filter panels | |
+| `s` | 16px thumb, 4px track, 12/16 label | compact side panels | |
+| `m` | 18px thumb, 4px track, 13/20 label | regular forms and settings | yes |
+| `l` | 20px thumb, 4px track, 14/20 label | spacious settings pages | |
+| `xl` | 24px thumb, 8px track, 14/20 label | touch-first screens | |
+
+### showValue
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `false` | no readout; the header shows only the label | the position is self-explanatory (volume) or the value is shown elsewhere (a paired input) | yes |
+| `true` | value at the right end of the label row, `text-secondary`, tabular nums | the number matters (price, temperature, percent) | |
+
+**Combinations**
+- `showValue` + `formatValue` for any value with a unit; `formatValue` alone only changes `aria-valuetext`.
+- Neither `label` nor `aria-label` → forbidden (unnamed control).
+- A paired number input with `showValue` → redundant; drop `showValue`.
+
+**Sizes** — the root is always 100% wide; the tier changes only the thumb, label/value text and (at `xl`) the track thickness. Use the same tier as the other fields of the form.
+
+**Hierarchy** — sliders in a settings card are spaced `--prime-space-6`; a related switch can disable a slider (see [display-settings.tsx](examples/display-settings.tsx)).
+
+## States
+| State | Driven by | DOM | Looks like |
+|---|---|---|---|
+| default | — | `data-size` | track `fill-strong`, fill `accent-default` up to the value, thumb `control-thumb` with a hairline edge and `shadow-overlay` |
+| hover | pointer | — | soft `accent-soft` halo (4px) around the thumb |
+| active | dragging | — | thumb scales to 110% |
+| focus-visible | keyboard | — | outer focus ring around the thumb |
+| disabled | `disabled` | `data-disabled="true"` on root, native `disabled` | track `fill-muted`, fill `text-disabled`, flat thumb `fill-strong`, value `text-disabled`, `cursor: not-allowed` |
+
+Controlled: `value` + `onValueChange`. Uncontrolled: `defaultValue` (falls back to `min`).
+
+## Layout & spacing
+- Always full width of its container; place it in a grid column to limit width.
+- Label row → track: tier `label-gap`; label and value are on one baseline, value pinned right.
+- Between sliders in a form: `--prime-space-5`; in a settings card: `--prime-space-6`.
+- With a paired input: grid `minmax(0, 1fr) auto-width column`, `align-items: end`, gap `--prime-space-4`.
+
+## Accessibility
+- Native `<input type="range">`: Arrow keys change by `step`, Page Up / Page Down by a larger step, Home / End jump to the ends.
+- `label` is a `<label htmlFor>`; otherwise `aria-label` is required.
+- `formatValue` sets `aria-valuetext`, so screen readers announce the unit.
+- The visual `<output>` is `aria-hidden` (the value is announced by the input).
+- No `labels` keys.
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [sizes.tsx](examples/sizes.tsx) | All size tiers with label and value | Matching the form tier |
+| [states.tsx](examples/states.tsx) | Minimum, middle, maximum, disabled | Reference for fill and disabled |
+| [value-format.tsx](examples/value-format.tsx) | `showValue` + `formatValue` (°C, ₽, %) | Values with units |
+| [basic.tsx](examples/basic.tsx) | One labelled slider with value | Checking contrast on any surface |
+| [controlled.tsx](examples/controlled.tsx) | `value` + `onValueChange` shared with a number Input | Drag plus exact entry |
+| [range-step.tsx](examples/range-step.tsx) | Custom `min`/`max`/`step`, fractional step, `aria-label` only | Bounded settings |
+| [display-settings.tsx](examples/display-settings.tsx) | Card with sliders and a Switch that disables one | Settings panels |
 
 ```tsx
 import { Slider } from "prime-ui-kit";
 
-export function Example() {
-  return (
-    <Slider.Root label="Output level" min={0} max={100} step={1} defaultValue={50} />
-  );
+export function VolumeSlider() {
+  return <Slider.Root label="Громкость" showValue defaultValue={60} />;
 }
 ```
 
-### Playground-aligned examples
-
-**`playground/sections/SliderSection.tsx`** and **`playground/snippets/slider/`** define the demo order and code shown in the playground (Russian UI copy in snippets). Matching runnable package examples (imports from **`"prime-ui-kit"`**) live next to this file:
-
-| Playground block | Snippet | Example file |
-|------------------|---------|--------------|
-| Sizes | `sizes.tsx` | `sizes.tsx` |
-| States | `states.tsx` | `states.tsx` |
-| Controlled | `controlled.tsx` | `controlled.tsx` |
-| Composition | `composition.tsx` | `composition.tsx` |
-| Full width | `full-width.tsx` | `full-width.tsx` |
-| Features (range / step) | `features.tsx` | `features.tsx` |
-
-Shared layout for controlled and full-width demos: **`examples/examples.module.css`**.
-
-**LLM note:** Prefer reading the runnable files under `./examples/*.tsx` for full scenarios and prop combinations; this page keeps the contract (rules + API tables) authoritative.
-
-## Rules
-
-- **Controlled:** pass **`value`** and **`onChange`**. **Uncontrolled:** pass **`defaultValue`**, or omit both value props — the effective initial value is **`min`**, clamped to **`[min, max]`**.
-- **`min`**, **`max`**, and **`step`** default to **`0`**, **`100`**, and **`1`**; fractional **`step`** values are allowed.
-- Displayed value is **clamped** to **`[min, max]`**; non-numeric input updates are ignored.
-- With **`label`**, the visible label is associated via **`id`** / **`htmlFor`**. Without **`label`**, set **`aria-label`** (or an external accessible name) so assistive technologies get a proper name.
-- **`disabled`** sets the native **`disabled`** state on the range input.
-- There is no **`asChild`** or portal behavior; focus and **`focus-visible`** styling follow the native control and theme.
-
-## API
-
-### Slider.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| value | `number` | — | No | Controlled value; use with **`onChange`** for external state |
-| defaultValue | `number` | — | No | Initial value when uncontrolled; clamped to **`[min, max]`**; if omitted, the internal initial value is **`min`** |
-| min | `number` | `0` | No | Minimum for the native `type="range"` |
-| max | `number` | `100` | No | Maximum for the native `type="range"` |
-| step | `number` | `1` | No | Step increment (may be fractional) |
-| disabled | `boolean` | — | No | Blocks input and lowers track opacity |
-| onChange | `(value: number) => void` | — | No | Fires when the value changes after user input (pointer, touch, or native range keys) |
-| label | `string` | — | No | Text above the track; creates an associated **`label`** with **`htmlFor`** on the input |
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | No | Track height, thumb, and label type scale from one control token tier |
-| className | `string` | — | No | Extra class on the root container |
-| aria-label | `string` | — | No | Accessible name when there is no visible **`label`** |
+## Mistakes
+- `<Slider.Root onChange={…}>` → use `onValueChange`.
+- `formatValue` without `showValue` expecting a visible unit → add `showValue`.
+- No `label` and no `aria-label` → add one.
+- `value={[20, 80]}` for a range → only a single number is supported.
+- Expecting it to submit in a form → there is no `name`; keep the value in state and submit it yourself.
 
 ## Related
-
-- [Label](../label/COMPONENT.md)
-- [Hint](../hint/COMPONENT.md)
-- [DigitInput](../digit-input/COMPONENT.md)
+[Input](../input/COMPONENT.md) · [SegmentedControl](../segmented-control/COMPONENT.md) · [Switch](../switch/COMPONENT.md) · [Label](../label/COMPONENT.md)

package/src/components/slider/examples/basic.tsx

@@ -0,0 +1,6 @@
+/** A single labelled slider with its value. Use it to check the track and thumb on canvas, cards and floating layers. */
+import { Slider } from "prime-ui-kit";
+
+export default function SliderBasicExample() {
+  return <Slider.Root label="Громкость" showValue defaultValue={60} />;
+}

package/src/components/slider/examples/controlled.tsx

@@ -1,23 +1,43 @@
-import { Slider } from "prime-ui-kit";
+/** A controlled slider sharing one value with a number input. Use it when users need both rough dragging and exact keyboard entry. */
+import { Input, Slider } from "prime-ui-kit";
 import * as React from "react";
 
 import styles from "./examples.module.css";
 
-/** Controlled pair `value` + `onChange`; mirror the current value in adjacent copy. */
+const MIN = 0;
+const MAX = 100;
+
 export default function SliderControlledExample() {
-  const [level, setLevel] = React.useState(62);
+  const [discount, setDiscount] = React.useState(15);
 
   return (
-    <div className={styles.controlledColumn}>
-      <Slider.Root
-        label="Reserve level"
-        value={level}
-        onChange={setLevel}
-        min={0}
-        max={100}
-        step={1}
-      />
-      <span className={styles.valueHint}>Current value: {level}%</span>
+    <div className={styles.column}>
+      <div className={styles.withInput}>
+        <Slider.Root
+          label="Скидка"
+          min={MIN}
+          max={MAX}
+          value={discount}
+          onValueChange={setDiscount}
+          formatValue={(v) => `${v}%`}
+        />
+        <Input.Root>
+          <Input.Wrapper>
+            <Input.Field
+              type="number"
+              min={MIN}
+              max={MAX}
+              aria-label="Скидка, %"
+              value={discount}
+              onChange={(e) => {
+                const next = Number(e.target.value);
+                if (!Number.isNaN(next)) setDiscount(Math.min(MAX, Math.max(MIN, next)));
+              }}
+            />
+            <Input.InlineAffix side="end">%</Input.InlineAffix>
+          </Input.Wrapper>
+        </Input.Root>
+      </div>
     </div>
   );
 }

package/src/components/slider/examples/display-settings.tsx

@@ -0,0 +1,41 @@
+/** A display settings card with formatted sliders where an «auto brightness» switch disables the brightness slider. Use it for settings panels with dependent controls. */
+import { Card, Slider, Switch } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+export default function SliderDisplaySettingsExample() {
+  const [auto, setAuto] = React.useState(false);
+
+  return (
+    <Card.Root variant="panel" className={styles.card}>
+      <Card.SectionHeader>
+        <Card.SectionTitle>Экран и звук</Card.SectionTitle>
+      </Card.SectionHeader>
+      <Card.Body>
+        <div className={styles.settings}>
+          <Switch.Root checked={auto} onCheckedChange={setAuto}>
+            <Switch.Label>Автояркость</Switch.Label>
+            <Switch.Hint>Подстраивается под освещение.</Switch.Hint>
+          </Switch.Root>
+          <Slider.Root
+            label="Яркость"
+            defaultValue={70}
+            disabled={auto}
+            showValue
+            formatValue={(v) => `${v}%`}
+          />
+          <Slider.Root
+            label="Размер текста"
+            min={12}
+            max={24}
+            defaultValue={16}
+            showValue
+            formatValue={(v) => `${v} px`}
+          />
+          <Slider.Root label="Громкость уведомлений" defaultValue={40} showValue />
+        </div>
+      </Card.Body>
+    </Card.Root>
+  );
+}

package/src/components/slider/examples/examples.module.css

@@ -1,37 +1,42 @@
-.stack {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-m);
-}
+/* Example layout: semantic tokens only. */
 
-.row {
-  display: flex;
-  justify-content: space-between;
-  align-items: baseline;
-  gap: var(--prime-sys-spacing-m);
+.sizesGrid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, calc(var(--prime-space-16) * 2)), 1fr));
+  align-items: end;
+  gap: var(--prime-space-6) var(--prime-space-5);
+  width: 100%;
 }
 
-.muted {
-  margin: 0;
-  color: var(--prime-sys-color-content-secondary);
+.column {
+  display: grid;
+  gap: var(--prime-space-5);
+  width: 100%;
+  max-width: var(--prime-modal-width-s);
 }
 
-.controlledColumn {
-  display: flex;
-  flex-direction: column;
-  gap: var(--prime-sys-spacing-x2);
+.pair {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(min(100%, var(--prime-panel-min-width)), 1fr));
+  align-items: end;
+  gap: var(--prime-space-6) var(--prime-space-5);
   width: 100%;
-  max-width: 20rem;
-  box-sizing: border-box;
+  max-width: var(--prime-modal-width-m);
 }
 
-.valueHint {
-  margin: 0;
-  font-size: var(--prime-sys-typography-sizeScale-xs);
-  line-height: var(--prime-sys-typography-lineHeightScale-xs);
-  color: var(--prime-sys-color-content-secondary);
+.withInput {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) var(--prime-space-24);
+  align-items: end;
+  gap: var(--prime-space-4);
+}
+
+.card {
+  width: 100%;
+  max-width: var(--prime-modal-width-s);
 }
 
-.narrowColumn {
-  width: min(12rem, 100%);
+.settings {
+  display: grid;
+  gap: var(--prime-space-6);
 }

package/src/components/slider/examples/range-step.tsx

@@ -0,0 +1,29 @@
+/** Custom min, max and step (including a fractional step) and a slider named only by aria-label. Use it for bounded numeric settings. */
+import { Slider } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+export default function SliderRangeStepExample() {
+  return (
+    <div className={styles.column}>
+      <Slider.Root label="Этаж" min={1} max={25} defaultValue={7} showValue />
+      <Slider.Root
+        label="Готовность, шаг 25"
+        step={25}
+        defaultValue={50}
+        showValue
+        formatValue={(v) => `${v}%`}
+      />
+      <Slider.Root
+        label="Рейтинг от"
+        min={1}
+        max={5}
+        step={0.5}
+        defaultValue={4}
+        showValue
+        formatValue={(v) => `★ ${v.toFixed(1)}`}
+      />
+      <Slider.Root min={0} max={100} defaultValue={30} aria-label="Масштаб карты" />
+    </div>
+  );
+}

package/src/components/slider/examples/sizes.tsx

@@ -1,15 +1,16 @@
+/** All five size tiers with a label and value: thumb, label and value text grow with the tier. Use it to match the slider to the form's control size. */
 import { Slider } from "prime-ui-kit";
 
-/**
- * Four `size` values (`s`–`xl`): track height, thumb, and label type ramp stay on one control token tier.
- */
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
 export default function SliderSizesExample() {
   return (
-    <>
-      <Slider.Root size="s" label="Size s" defaultValue={30} />
-      <Slider.Root size="m" label="Size m" defaultValue={40} />
-      <Slider.Root size="l" label="Size l" defaultValue={50} />
-      <Slider.Root size="xl" label="Size xl" defaultValue={60} />
-    </>
+    <div className={styles.sizesGrid}>
+      {SIZES.map((size) => (
+        <Slider.Root key={size} size={size} label={`Размер ${size}`} showValue defaultValue={40} />
+      ))}
+    </div>
   );
 }

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

@@ -1,11 +1,15 @@
+/** Sliders at the minimum, in the middle, at the maximum and disabled. Use it as a reference for the fill and the disabled look. */
 import { Slider } from "prime-ui-kit";
 
-/** Default interaction vs `disabled`: lower opacity and no pointer/keyboard input on the range control. */
+import styles from "./examples.module.css";
+
 export default function SliderStatesExample() {
   return (
-    <>
-      <Slider.Root label="Volume" defaultValue={45} />
-      <Slider.Root label="Disabled example" defaultValue={35} disabled />
-    </>
+    <div className={styles.pair}>
+      <Slider.Root label="Минимум" showValue defaultValue={0} />
+      <Slider.Root label="Середина" showValue defaultValue={50} />
+      <Slider.Root label="Максимум" showValue defaultValue={100} />
+      <Slider.Root label="Отключено" showValue defaultValue={35} disabled />
+    </div>
   );
 }

package/src/components/slider/examples/value-format.tsx

@@ -0,0 +1,44 @@
+/** showValue in the label row and formatValue for units (°C, ₽, %) that also become aria-valuetext. Use it whenever the number needs a unit. */
+import { Slider } from "prime-ui-kit";
+
+import styles from "./examples.module.css";
+
+const rub = new Intl.NumberFormat("ru-RU", {
+  style: "currency",
+  currency: "RUB",
+  maximumFractionDigits: 0,
+});
+
+export default function SliderValueFormatExample() {
+  return (
+    <div className={styles.column}>
+      <Slider.Root label="Громкость" showValue defaultValue={64} />
+      <Slider.Root
+        label="Температура"
+        min={16}
+        max={30}
+        defaultValue={22}
+        showValue
+        formatValue={(v) => `${v} °C`}
+      />
+      <Slider.Root
+        label="Бюджет в месяц"
+        min={0}
+        max={200000}
+        step={5000}
+        defaultValue={45000}
+        showValue
+        formatValue={(v) => rub.format(v)}
+      />
+      <Slider.Root
+        label="Прозрачность слоя"
+        min={0}
+        max={1}
+        step={0.05}
+        defaultValue={0.8}
+        showValue
+        formatValue={(v) => `${Math.round(v * 100)}%`}
+      />
+    </div>
+  );
+}