@ahrowe/ui 0.11.0 → 0.13.0

package/dist/types/package/common/slider/slider.types.d.ts

@@ -0,0 +1,43 @@
+import { CSSProperties, ReactNode } from 'react';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
+export interface SliderMark {
+    /** Position of the mark, in the same units as `value`. */
+    value: number;
+    /** Optional label rendered under the mark. */
+    label?: ReactNode;
+}
+export type SliderSlots = 'root' | 'track' | 'range' | 'thumb' | 'mark' | 'markLabel' | 'value';
+export interface SliderProps extends HtmlProps {
+    /** Controlled value. Omit for uncontrolled. */
+    value?: number;
+    /** Initial value when uncontrolled (default `min`). */
+    defaultValue?: number;
+    /** Fires on every value change (drag, keyboard, click). */
+    onChange?: (value: number) => void;
+    /** Fires once when the value is committed: pointer release or a keyboard step. */
+    onChangeEnd?: (value: number) => void;
+    /** Minimum value (default `0`). */
+    min?: number;
+    /** Maximum value (default `100`). */
+    max?: number;
+    /** Step increment; values snap to it (default `1`). */
+    step?: number;
+    /** Disable interaction. */
+    disabled?: boolean;
+    /** Tick marks along the track, optionally labelled. */
+    marks?: SliderMark[];
+    /** Show the current value in a bubble above the thumb. */
+    showValue?: boolean;
+    /** Format the value shown in the bubble and announced to assistive tech. */
+    formatValue?: (value: number) => ReactNode;
+    /** Thumb diameter, any CSS length (default `'18px'`). Sets `--slider-thumb-size`. */
+    size?: string;
+    /** Tab index of the thumb (default `0`). */
+    tabIndex?: number;
+    /** Accessible label for the slider. */
+    'aria-label'?: string;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<SliderSlots>;
+    styles?: SlotStyles<SliderSlots>;
+}

package/dist/types/package/common/stepper/stepper.types.d.ts

@@ -10,9 +10,9 @@ export declare enum StepperAlignment {
 export declare enum StepperStyleType {
     /** Numbered markers, filled solid on completion (the default look). */
     Default = "default",
-    /** Numbered markers that stay ringed when completed — a coloured check, no solid fill. */
+    /** Numbered markers that stay ringed when completed (a coloured check, no solid fill). */
     Outlined = "outlined",
-    /** Minimal dots without numbers — compact onboarding / carousel style. */
+    /** Minimal dots without numbers, for a compact onboarding or carousel style. */
     Dots = "dots"
 }
 /**
@@ -48,11 +48,11 @@ export interface StepperStep {
     content?: React.ReactNode;
     /** FontAwesome icon shown in the marker instead of the step number. */
     icon?: IconDefinition;
-    /** Marks the step as errored — recolours the marker with `--stepper-error-color`. */
+    /** Marks the step as errored, recolouring the marker with `--stepper-error-color`. */
     error?: boolean;
     /** `true` renders an "Optional" hint; a node renders custom hint text. */
     optional?: boolean | React.ReactNode;
-    /** Disables this step — never clickable, dimmed. */
+    /** Disables this step: never clickable, dimmed. */
     disabled?: boolean;
 }
 export interface StepperProps extends HtmlProps {
@@ -66,7 +66,7 @@ export interface StepperProps extends HtmlProps {
     hideLabels?: boolean;
     /** Visual preset for markers and connectors (default `Default`). */
     styleType?: StepperStyleType;
-    /** Which step bodies are expanded — vertical `content` only (default `None`). */
+    /** Which step bodies are expanded. Vertical `content` only (default `None`). */
     collapse?: StepperCollapse;
     /** Label position relative to the marker (default: horizontal `Bottom`, vertical `Right`). */
     labelPlacement?: StepperLabelPlacement;

package/dist/types/package/common/themeProvider/theme.types.d.ts

@@ -74,6 +74,16 @@ export interface ThemeVariables {
     '--background-card-elevated'?: string;
     '--background-card-outlined'?: string;
     '--background-card-filled'?: string;
+    /** Slider track (unfilled) colour. Falls back to --background-accent-light. */
+    '--slider-track-color'?: string;
+    /** Slider filled-range colour. Falls back to --primary-color. */
+    '--slider-range-color'?: string;
+    /** Slider thumb colour. Falls back to --primary-color. */
+    '--slider-thumb-color'?: string;
+    /** Slider thumb diameter. Falls back to 18px (also settable per instance via the `size` prop). */
+    '--slider-thumb-size'?: string;
+    /** Slider track thickness. Falls back to 6px. */
+    '--slider-track-height'?: string;
     /** Step marker diameter. Falls back to 40px. */
     '--stepper-marker-size'?: string;
     /** Step marker corner radius. Falls back to --default-border-radius. */

package/dist/types/package/index.d.ts

@@ -3,6 +3,8 @@ export * from './common/accordion';
 export * from './common/actionButtons';
 export { default as ActionIcon } from './common/actionIcon';
 export * from './common/actionIcon';
+export { default as Alert } from './common/alert';
+export * from './common/alert';
 export { default as AnimatedLogo } from './common/animatedLogo';
 export * from './common/animatedLogo';
 export { default as AnimatedText } from './common/animatedText';
@@ -13,10 +15,14 @@ export { default as Badge } from './common/badge';
 export * from './common/badge';
 export { default as BodyEnd } from './common/bodyEnd';
 export * from './common/bodyEnd';
+export { default as Breadcrumb } from './common/breadcrumb';
+export * from './common/breadcrumb';
 export { default as Button } from './common/button';
 export * from './common/button';
 export { default as Card } from './common/card';
 export * from './common/card';
+export { default as Carousel } from './common/carousel';
+export * from './common/carousel';
 export { default as Checkbox } from './common/checkbox';
 export * from './common/checkbox';
 export { default as Chip } from './common/chip';
@@ -74,6 +80,8 @@ export { default as ProgressBar } from './common/progressBar';
 export * from './common/progressBar';
 export { default as RadioGroup } from './common/radioGroup';
 export * from './common/radioGroup';
+export { default as Rating } from './common/rating';
+export * from './common/rating';
 export { default as Ripple } from './common/ripple';
 export * from './common/ripple';
 export { default as RoomDrawer } from './common/roomDrawer';
@@ -88,6 +96,8 @@ export { default as SectionHeader } from './common/sectionHeader';
 export * from './common/sectionHeader';
 export { default as Skeleton } from './common/skeleton';
 export * from './common/skeleton';
+export { default as Slider } from './common/slider';
+export * from './common/slider';
 export { default as Stepper } from './common/stepper';
 export * from './common/stepper';
 export { default as Sticky } from './common/sticky';

package/docs/Alert.md

@@ -0,0 +1,64 @@
+# Alert
+
+**When to use:** A persistent inline status message, used for form-level errors, page/section banners, empty-config warnings, and "here's what changed" notices. Unlike `Toast`, it isn't portaled or auto-dismissed, and it stays in the page's normal flow for as long as its consumer renders it. Use `Toast` instead for a transient, corner-anchored notification.
+
+**Import:** `import { Alert, AlertStyleType } from '@ahrowe/ui'`
+
+**Style variants:** `AlertStyleType.Default` | `AlertStyleType.Info` | `AlertStyleType.Success` | `AlertStyleType.Warn` | `AlertStyleType.Error`
+
+```tsx
+import { Alert, AlertStyleType } from '@ahrowe/ui';
+
+// Default, neutral message
+<Alert>A default, neutral message.</Alert>
+
+// Semantic variants
+<Alert styleType={AlertStyleType.Info}>Here's something worth knowing.</Alert>
+<Alert styleType={AlertStyleType.Success}>Your changes were saved.</Alert>
+<Alert styleType={AlertStyleType.Warn}>Your storage is almost full.</Alert>
+<Alert styleType={AlertStyleType.Error}>Something went wrong. Please try again.</Alert>
+
+// With a title
+<Alert styleType={AlertStyleType.Warn} title="Storage almost full">
+  You've used 92% of your available space. Free up room or upgrade your plan.
+</Alert>
+
+// Dismissible: the consumer owns visibility. onClose is called on click,
+// so stop rendering the Alert (or flip your own state) to actually hide it
+const [visible, setVisible] = useState(true);
+{visible && (
+  <Alert
+    styleType={AlertStyleType.Info}
+    title="New feature available"
+    onClose={() => setVisible(false)}
+  >
+    Try out the new dashboard layout from your account settings.
+  </Alert>
+)}
+
+// Without the leading icon
+<Alert styleType={AlertStyleType.Success} hideIcon>
+  A minimal message with no leading icon.
+</Alert>
+
+// Custom icon, overriding the styleType default
+import { faRocket } from '@fortawesome/free-solid-svg-icons';
+<Alert styleType={AlertStyleType.Info} icon={faRocket}>
+  Shipping a new release tonight.
+</Alert>
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `ReactNode` | Optional bold heading above the description |
+| `children` | `ReactNode` | The message body |
+| `styleType` | `AlertStyleType` | Colour variant and default icon (default `Default`) |
+| `icon` | `IconDefinition` | Overrides the default FontAwesome icon for `styleType` |
+| `hideIcon` | `boolean` | Hide the leading icon entirely |
+| `onClose` | `() => void` | Shows a close button and is called when it's clicked. `Alert` doesn't hide itself, so stop rendering it (or update your own state) in the handler |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Alert: { hideIcon: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `icon` `content` `title` `description` `closeButton`

package/docs/AnimatedText.md

@@ -59,6 +59,10 @@ import { AnimatedText, AnimatedTextVariant, AnimatedTextUnit } from '@ahrowe/ui'
 // A marker-style highlight block wipes in behind the text, once
 <AnimatedText text="Marked as important" variant={AnimatedTextVariant.Highlight} />
 
+// Plays immediately on mount instead of waiting for it to scroll into view
+// (default behaviour) — e.g. a hero headline that's already above the fold
+<AnimatedText text="Welcome back" triggerOnView={false} />
+
 // Changing `text` (or `variant`/`unit`/`staggerDelay`/`duration`) automatically replays,
 // so no key is needed for that. A key is only needed to replay with the exact same text again:
 <AnimatedText key={replayKey} text="Hello there" />
@@ -74,6 +78,7 @@ import { AnimatedText, AnimatedTextVariant, AnimatedTextUnit } from '@ahrowe/ui'
 | `unit` | `AnimatedTextUnit` | Whether entrance/loop variants stagger by letter or by whole word (default `Letter`). Ignored by `Shine`/`Highlight` |
 | `staggerDelay` | `number` | Delay in ms between each unit's animation start. Applies to every variant except `Shine`/`Highlight`, which animate as a single run (default `40`) |
 | `duration` | `number` | Duration in ms of one animation cycle: a single unit's entrance for `RiseUp`/`BlurIn`/`Bounce`/`Glitch` (default `500`), one bob cycle for `Wave` (default `1200`), one sweep of the highlight for `Shine` (default `2000`), or the one-shot wipe-in for `Highlight` (default `600`). Ignored by `Typewriter` and `Scramble`, since each unit resolves instantly; use `staggerDelay` to control their pacing |
+| `triggerOnView` | `boolean` | When `true` (default), the animation doesn't start until the component first scrolls into the viewport. Set `false` to play immediately on mount |
 
 **Word mode:** with `unit={AnimatedTextUnit.Word}`, each whole word animates as one block instead of each letter animating individually; `staggerDelay` then applies between words. Words are split on whitespace, and consecutive spaces collapse to one.
 

package/docs/Breadcrumb.md

@@ -0,0 +1,106 @@
+# Breadcrumb
+
+**When to use:** A trail showing the current page's position within a hierarchy, with links back to each ancestor, such as a file browser path, a category/subcategory drill-down, or a multi-level settings page. The last item is always rendered as the current page and isn't clickable.
+
+**Import:** `import { Breadcrumb } from '@ahrowe/ui'`
+**Types:** `import type { BreadcrumbItem, BreadcrumbProps } from '@ahrowe/ui'`
+
+```tsx
+import { Breadcrumb } from '@ahrowe/ui';
+import type { BreadcrumbItem } from '@ahrowe/ui';
+
+const items: BreadcrumbItem[] = [
+  { label: 'Home', href: '/' },
+  { label: 'Documents', href: '/documents' },
+  { label: 'Report.pdf' }, // last item: rendered as the current page, not a link
+];
+
+<Breadcrumb items={items} />
+
+// With leading icons
+import { faHouse, faFolder } from '@fortawesome/free-solid-svg-icons';
+
+<Breadcrumb
+  items={[
+    { label: 'Home', href: '/', icon: faHouse },
+    { label: 'Projects', href: '/projects', icon: faFolder },
+    { label: 'Current project' },
+  ]}
+/>
+
+// Client-side routing (e.g. react-router): keep href for a real, right-clickable link,
+// and use onClick to intercept the native navigation with the router's own navigate()
+import { useNavigate } from 'react-router-dom';
+
+function Example() {
+  const navigate = useNavigate();
+  return (
+    <Breadcrumb
+      items={[
+        {
+          label: 'Home',
+          href: '/',
+          onClick: (event) => {
+            event.preventDefault();
+            navigate('/');
+          },
+        },
+        { label: 'Current page' },
+      ]}
+    />
+  );
+}
+
+// A disabled crumb: dimmed, not clickable, regardless of href/onClick
+<Breadcrumb
+  items={[
+    { label: 'Home', href: '/' },
+    { label: 'Archived', href: '/archived', disabled: true },
+    { label: 'Old report' },
+  ]}
+/>
+
+// Custom separator (default is a chevron icon)
+<Breadcrumb items={items} separator="/" />
+
+// Long trails: collapse the middle behind a clickable ellipsis once items.length
+// exceeds maxItems. The ellipsis counts as one of the visible slots, so maxItems={3}
+// on a 4-item trail shows: Home / ... / Settings. Clicking the ellipsis opens a menu
+// (via FloatingMenu) listing the hidden items.
+<Breadcrumb
+  items={[
+    { label: 'Home', href: '/' },
+    { label: 'Invoices', href: '/invoices' },
+    { label: 'Editor', href: '/invoices/editor' },
+    { label: 'Settings' },
+  ]}
+  maxItems={3}
+/>
+```
+
+**Requires:** `<div id="bodyEnd"></div>` in your HTML when `maxItems` is used and the trail actually collapses (the hidden-items menu is a `FloatingMenu`, which renders via portal).
+
+**BreadcrumbItem:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Optional stable key; falls back to the item's index |
+| `label` | `ReactNode` | The crumb's text |
+| `href` | `string` | Renders the crumb as a real `<a>`. Omit to render a plain clickable element (with `onClick`) or static text |
+| `icon` | `IconDefinition` | Optional leading FontAwesome icon |
+| `onClick` | `(event: MouseEvent) => void` | Click handler. Works alongside `href`: call `event.preventDefault()` to stop the native navigation and hand off to a client-side router's own navigate function (see the react-router example above). Also works on its own, with no `href` |
+| `disabled` | `boolean` | Dims the crumb and makes it non-interactive, regardless of `href`/`onClick` |
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `BreadcrumbItem[]` | The crumbs, in order. The last one is always rendered as the current page |
+| `separator` | `ReactNode` | Overrides the default chevron separator between items |
+| `maxItems` | `number` | Collapses the middle items behind a clickable ellipsis once `items.length` exceeds this. The ellipsis counts as one of the visible slots, alongside the always-shown first item (so `maxItems={3}` shows first item, ellipsis, last item) |
+
+**Collapsing behaviour:** the hidden count grows and shrinks by exactly however many items are actually over the limit, rather than always jumping to the same minimal first/ellipsis/last shape. A trail with 11 items and `maxItems={10}` hides only 2 items, not the whole middle, so the trail doesn't visually lurch as one more level of navigation pushes it just over the limit.
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Breadcrumb: { separator: '/' } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `list` `item` `link` `icon` `separator` `current` `ellipsis` `hiddenList` `hiddenItem`

package/docs/CLAUDE.md

@@ -95,13 +95,16 @@ Slot keys per component are documented in each component's doc file below.
 @Accordion.md
 @ActionButtons.md
 @ActionIcon.md
+@Alert.md
 @AnimatedLogo.md
 @AnimatedText.md
 @Avatar.md
 @Badge.md
 @BodyEnd.md
+@Breadcrumb.md
 @Button.md
 @Card.md
+@Carousel.md
 @Checkbox.md
 @Chip.md
 @ColorPicker.md
@@ -133,6 +136,7 @@ Slot keys per component are documented in each component's doc file below.
 @Popover.md
 @ProgressBar.md
 @RadioGroup.md
+@Rating.md
 @Ripple.md
 @RoomDrawer.md
 @RoomViewer.md
@@ -140,6 +144,7 @@ Slot keys per component are documented in each component's doc file below.
 @SearchInput.md
 @SectionHeader.md
 @Skeleton.md
+@Slider.md
 @Stepper.md
 @Sticky.md
 @Switch.md

package/docs/Carousel.md

@@ -0,0 +1,67 @@
+# Carousel
+
+**When to use:** A slide track for stepping through a set of items one at a time, with arrows, dots, and drag/swipe support, plus optional autoplay. Slides are plain children, so any content works (images, cards, mixed content), not just a fixed image-gallery shape.
+
+**Import:** `import { Carousel } from '@ahrowe/ui'`
+**Types:** `import type { CarouselProps } from '@ahrowe/ui'`
+
+```tsx
+import { Carousel } from '@ahrowe/ui';
+
+// Uncontrolled, looping by default, with arrows, dots, and swipe all on
+<Carousel>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+  <div>Slide 3</div>
+</Carousel>
+
+// Controlled
+const [index, setIndex] = useState(0);
+<Carousel currentIndex={index} onChange={setIndex}>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+  <div>Slide 3</div>
+</Carousel>
+
+// Autoplay, paused on hover/focus by default, with dots hidden
+<Carousel autoPlay autoPlayInterval={4000} showDots={false}>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+</Carousel>
+
+// Bounded instead of looping: arrows disable at the first/last slide
+<Carousel loop={false}>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+</Carousel>
+
+// No swipe/drag, arrows only
+<Carousel swipeable={false} showDots={false}>
+  <div>Slide 1</div>
+  <div>Slide 2</div>
+</Carousel>
+```
+
+Pass slides as direct children (an array or a set of sibling elements), not through a component that returns a fragment internally. `Carousel` reads its immediate children via `React.Children`, so a wrapper component's own children aren't visible to it. If slides come from a `.map()`, spread the array straight into `Carousel`, the same way `children` normally works in React.
+
+**Interaction:** drag or swipe the track to move between slides (committing past roughly 20% of the container's width, or releasing further than that snaps to the next/previous slide; a shorter drag springs back). Left/right arrow keys move between slides when focus is anywhere inside the carousel.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | The slides, one per direct child |
+| `currentIndex` | `number` | Controlled active slide index |
+| `defaultIndex` | `number` | Initial active slide index when uncontrolled (default `0`) |
+| `onChange` | `(index: number) => void` | Called whenever the active slide changes, from arrows, dots, keyboard, drag, or autoplay |
+| `loop` | `boolean` | Wrap from the last slide to the first and back (default `true`) |
+| `autoPlay` | `boolean` | Automatically advance on a timer (default `false`) |
+| `autoPlayInterval` | `number` | Autoplay delay in ms (default `4000`) |
+| `pauseOnHover` | `boolean` | Pause autoplay while hovered or focused (default `true`) |
+| `showArrows` | `boolean` | Show the prev/next buttons (default `true`); hidden automatically with one slide or none |
+| `showDots` | `boolean` | Show the position dots (default `true`); hidden automatically with one slide or none |
+| `swipeable` | `boolean` | Allow dragging/swiping the track (default `true`) |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Carousel: { autoPlay: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `track` `slide` `prevButton` `nextButton` `dots` `dot`

package/docs/ColorPicker.md

@@ -36,3 +36,5 @@ import { ColorPicker } from '@ahrowe/ui';
 | `onChange` | `(hex: string) => void` | Called with new hex on change |
 | `showInput` | `boolean` | Show hex text input |
 | `inline` | `boolean` | Render picker inline instead of as a popover |
+
+An eyedropper button is shown automatically next to the hex input on browsers that support the native `EyeDropper` API (Chromium-based desktop/Android browsers). It lets the user sample a colour from anywhere on screen, not just within the page. It's hidden entirely on unsupported browsers (Firefox, Safari, iOS) — no prop needed.

package/docs/Rating.md

@@ -0,0 +1,72 @@
+# Rating
+
+**When to use:** A star rating input or display, for review scores, feedback prompts, and quality indicators. Use `readOnly` to just show an existing rating (e.g. a product's average score) rather than collect one.
+
+**Import:** `import { Rating } from '@ahrowe/ui'`
+**Types:** `import type { RatingProps } from '@ahrowe/ui'`
+
+```tsx
+import { useState } from 'react';
+import { Rating } from '@ahrowe/ui';
+
+// Controlled
+const [value, setValue] = useState(3);
+<Rating value={value} onChange={setValue} />
+
+// Uncontrolled
+<Rating defaultValue={4} onChange={(value) => console.log(value)} />
+
+// Half-star increments
+<Rating defaultValue={3.5} allowHalf />
+
+// A different number of stars
+<Rating defaultValue={6} max={10} />
+
+// Read-only, for displaying an existing rating (e.g. a product card)
+<Rating value={4} readOnly />
+
+// Disabled
+<Rating value={2} disabled />
+
+// Larger, via font-size (sizing is em-based, like Switch and Avatar)
+<Rating defaultValue={4} style={{ fontSize: 32 }} />
+
+// Custom icon
+import { faHeart } from '@fortawesome/free-solid-svg-icons';
+<Rating defaultValue={3} icon={faHeart} />
+
+// Disable click-to-clear (clicking the currently-selected star normally resets to 0)
+<Rating value={value} onChange={setValue} allowClear={false} />
+```
+
+**Interaction:** click, tap, or drag/swipe across the stars to set the rating, on any pointer type (mouse, touch, pen) via the Pointer Events API. Dragging updates the preview live and commits on release, which is the natural gesture on mobile rather than requiring a precise tap on one star. A plain click/tap on the currently-selected star clears it to `0` (set `allowClear={false}` to keep it fixed instead); a drag that happens to end back near its starting value doesn't clear, since that's a different gesture from a deliberate re-tap. With keyboard focus: `←`/`↓` and `→`/`↑` move by one star (or half a star with `allowHalf`), `Home`/`End` jump to `0`/`max`.
+
+**Sizing:** there's no dedicated size prop, `font-size` scales the whole control (like `Switch` and `Avatar`). The root sizes to its content (`width: fit-content`) rather than stretching to fill a flex/grid ancestor, since the click/drag position is measured against the root's own width.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `number` | Controlled value (omit for uncontrolled) |
+| `defaultValue` | `number` | Initial value when uncontrolled (default `0`) |
+| `onChange` | `(value: number) => void` | Fires when the rating changes, from a click or keyboard input |
+| `max` | `number` | Number of stars (default `5`) |
+| `allowHalf` | `boolean` | Allow half-star increments (default `false`) |
+| `allowClear` | `boolean` | Clicking the currently-selected star resets the value to `0` (default `true`) |
+| `readOnly` | `boolean` | Display only, not focusable or interactive |
+| `disabled` | `boolean` | Dims the control and disables interaction |
+| `icon` | `IconDefinition` | Overrides the default star icon |
+| `aria-label` | `string` | Accessible label (default `'Rating'`) |
+
+**Accessibility:** renders `role="slider"` with `aria-valuemin`/`aria-valuemax`/`aria-valuenow`/`aria-valuetext`, matching `Slider`'s pattern.
+
+**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 |
+|----------|---------------|
+| `--rating-filled-color` | `var(--primary-color)` |
+| `--rating-empty-color` | `var(--background-accent-light)` |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Rating: { allowHalf: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `item` `iconEmpty` `iconFilled`

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: {