@ahrowe/ui 0.11.0 → 0.12.0

package/docs/Slider.md

@@ -0,0 +1,93 @@
+# Slider
+
+**When to use:** Let the user pick a number from a continuous or stepped range by dragging a thumb: volume, brightness, price ranges, zoom, quality presets. For free numeric entry use `NumberInput`; for a few discrete options use `OptionPicker` or `RadioGroup`.
+
+**Import:** `import { Slider } from '@ahrowe/ui'`
+**Types:** `import type { SliderProps, SliderMark } from '@ahrowe/ui'`
+
+```tsx
+import { useState } from 'react';
+import { Slider } from '@ahrowe/ui';
+
+// Controlled
+const [value, setValue] = useState(40);
+<Slider value={value} onChange={setValue} aria-label="Value" />
+
+// Uncontrolled
+<Slider defaultValue={40} onChangeEnd={(v) => save(v)} />
+
+// Value bubble above the thumb
+<Slider value={volume} onChange={setVolume} showValue />
+
+// Custom range, step, and formatting
+<Slider
+  value={price}
+  onChange={setPrice}
+  min={0}
+  max={1000}
+  step={50}
+  showValue
+  formatValue={(v) => `€${v}`}
+/>
+
+// Tick marks (labelled and unlabelled)
+<Slider
+  value={quality}
+  onChange={setQuality}
+  min={0}
+  max={4}
+  step={1}
+  marks={[
+    { value: 0, label: 'Low' },
+    { value: 2, label: 'Medium' },
+    { value: 4, label: 'High' },
+  ]}
+/>
+
+// Larger thumb, themed colours (one-off)
+<Slider
+  value={value}
+  onChange={setValue}
+  size="26px"
+  style={{
+    '--slider-range-color': 'var(--success-color)',
+    '--slider-thumb-color': 'var(--success-color)',
+  } as React.CSSProperties}
+/>
+```
+
+**Interaction:** drag the thumb or click anywhere on the track to jump there. With keyboard focus: `←`/`↓` and `→`/`↑` move by `step`, `Page Up`/`Page Down` by ten steps, `Home`/`End` jump to `min`/`max`. Values always snap to `step`.
+
+**`onChange` vs `onChangeEnd`:** `onChange` fires on every change (each drag move and each key press); `onChangeEnd` fires once the value is committed, on pointer release or on each keyboard step. Use `onChangeEnd` to defer expensive work (a network save, a heavy re-render) until the user settles.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `number` | Controlled value (omit for uncontrolled) |
+| `defaultValue` | `number` | Initial value when uncontrolled (default `min`) |
+| `onChange` | `(value: number) => void` | Fires on every change |
+| `onChangeEnd` | `(value: number) => void` | Fires once the value is committed |
+| `min` | `number` | Minimum (default `0`) |
+| `max` | `number` | Maximum (default `100`) |
+| `step` | `number` | Snap increment (default `1`) |
+| `disabled` | `boolean` | Disable interaction |
+| `marks` | `SliderMark[]` | Tick marks, `{ value, label? }` |
+| `showValue` | `boolean` | Show the current value in a bubble above the thumb |
+| `formatValue` | `(value: number) => ReactNode` | Format the bubble text and `aria-valuetext` |
+| `size` | `string` | Thumb diameter, any CSS length (default `'18px'`) |
+| `aria-label` | `string` | Accessible label |
+
+**Accessibility:** renders `role="slider"` with `aria-valuemin` / `aria-valuemax` / `aria-valuenow` (and `aria-valuetext` when `formatValue` returns a string/number). Give it an `aria-label` (or wire up your own visible label). Respects `prefers-reduced-motion` (no thumb/fill transition).
+
+**Theming:** override these CSS variables theme-wide via `ThemeProvider` or per instance via `style`; each falls back to a built-in default:
+
+| Variable | Falls back to |
+|----------|---------------|
+| `--slider-track-color` | `var(--background-accent-light)` |
+| `--slider-range-color` | `var(--primary-color)` |
+| `--slider-thumb-color` | `var(--primary-color)` |
+| `--slider-thumb-size` | `18px` (also settable per instance via `size`) |
+| `--slider-track-height` | `6px` |
+
+**Slots:** `root` `track` `range` `thumb` `mark` `markLabel` `value`

package/docs/Stepper.md

@@ -1,6 +1,6 @@
 # Stepper
 
-**When to use:** Step progress indicator — multi-step forms, onboarding flows, checkout wizards. Shows completed, current, and upcoming steps, and (vertically) can expand a collapsible body under the active step.
+**When to use:** Step progress indicator for multi-step forms, onboarding flows, and checkout wizards. Shows completed, current, and upcoming steps, and (vertically) can expand a collapsible body under the active step.
 
 **Import:** `import { Stepper } from '@ahrowe/ui'`
 **Types:** `import type { StepperStep, StepperProps } from '@ahrowe/ui'`
@@ -36,7 +36,7 @@ const steps = [
   onStepClicked={(stepIndex) => setCurrentStep(stepIndex)}
 />
 
-// Rich steps — icon, description, error, optional
+// Rich steps: icon, description, error, optional
 <Stepper
   currentStep={2}
   steps={[
@@ -46,7 +46,7 @@ const steps = [
   ]}
 />
 
-// Vertical wizard with collapsible bodies — only the active step's body is open
+// Vertical wizard with collapsible bodies (only the active step's body is open)
 <Stepper
   alignment={StepperAlignment.Vertical}
   collapse={StepperCollapse.ActiveOnly}
@@ -80,7 +80,7 @@ const steps = [
 | `currentStep` | `number` | Zero-based active step index |
 | `alignment` | `StepperAlignment \| 'horizontal' \| 'vertical'` | Layout direction (default `Horizontal`) |
 | `styleType` | `StepperStyleType` | Marker/connector preset (default `Default`) |
-| `collapse` | `StepperCollapse` | Which `content` bodies are expanded — vertical only (default `None`) |
+| `collapse` | `StepperCollapse` | Which `content` bodies are expanded. Vertical only (default `None`) |
 | `labelPlacement` | `StepperLabelPlacement` | Label position; default `Bottom` (horizontal) / `Right` (vertical). An out-of-orientation value falls back to that default |
 | `onStepClicked` | `(stepIndex: number) => void` | Navigate on step click. Linear: only completed steps are clickable; with `nonLinear`, any enabled step except the current one |
 | `nonLinear` | `boolean` | Allow clicking any step, not just completed ones |
@@ -88,7 +88,7 @@ const steps = [
 
 **Collapse (vertical `content`):** `None` keeps every body open; `ActiveOnly` opens just the current step's body (classic vertical wizard); `Completed` collapses completed bodies while keeping the current and upcoming ones open. Bodies animate their height and respect `prefers-reduced-motion`. Horizontal steppers don't render inline `content` and ignore `collapse`.
 
-**Theming:** these are theme variables (typed on `ThemeVariables`) — set them theme-wide via `ThemeProvider`'s `variables`, or per instance via `style`, without fighting specificity. Each falls back to a built-in default when unset:
+**Theming:** these are theme variables (typed on `ThemeVariables`). Set them theme-wide via `ThemeProvider`'s `variables`, or per instance via `style`, without fighting specificity. Each falls back to a built-in default when unset:
 
 | Variable | Falls back to |
 |----------|---------------|
@@ -105,7 +105,7 @@ const steps = [
 | `--stepper-text-on-marker` | `var(--text-on-primary)` |
 
 ```tsx
-// Theme-wide, via ThemeProvider — circular pink markers, thicker connectors
+// Theme-wide, via ThemeProvider: circular pink markers, thicker connectors
 const theme: Theme = {
   id: 'brand',
   variables: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "publishConfig": {
     "access": "public"
   },