@ahrowe/ui 0.8.0 → 0.10.0

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

@@ -1,19 +1,75 @@
 import { default as React } from 'react';
+import { IconDefinition } from '@fortawesome/fontawesome-svg-core';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
-export type StepperAlignment = 'horizontal' | 'vertical';
-export type StepperSlots = 'root' | 'entry' | 'entryNumber' | 'entryLabel' | 'connector';
+/** Layout direction of the stepper. */
+export declare enum StepperAlignment {
+    Horizontal = "horizontal",
+    Vertical = "vertical"
+}
+/** Visual preset for the step markers and connectors. */
+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. */
+    Outlined = "outlined",
+    /** Minimal dots without numbers — compact onboarding / carousel style. */
+    Dots = "dots"
+}
+/**
+ * Which step bodies (`step.content`) are expanded. Only affects vertical
+ * steppers with per-step `content`; ignored otherwise.
+ */
+export declare enum StepperCollapse {
+    /** Every step body stays expanded. */
+    None = "none",
+    /** Only the current step's body is expanded (classic vertical wizard). */
+    ActiveOnly = "activeOnly",
+    /** Completed (past) step bodies collapse; current and upcoming stay expanded. */
+    Completed = "completed"
+}
+/**
+ * Where the label block sits relative to the marker. Horizontal steppers use
+ * `Top`/`Bottom`; vertical steppers use `Left`/`Right`. An out-of-orientation
+ * value falls back to that orientation's default.
+ */
+export declare enum StepperLabelPlacement {
+    Top = "top",
+    Bottom = "bottom",
+    Left = "left",
+    Right = "right"
+}
+export type StepperSlots = 'root' | 'entry' | 'entryNumber' | 'entryLabel' | 'connector' | 'description' | 'content' | 'optional' | 'icon';
 export interface StepperStep {
-    label: string;
+    /** Primary label for the step. */
+    label: React.ReactNode;
+    /** Secondary line shown under the label. */
+    description?: React.ReactNode;
+    /** Collapsible body content, rendered under the label (vertical only). */
+    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`. */
+    error?: boolean;
+    /** `true` renders an "Optional" hint; a node renders custom hint text. */
+    optional?: boolean | React.ReactNode;
+    /** Disables this step — never clickable, dimmed. */
+    disabled?: boolean;
 }
 export interface StepperProps extends HtmlProps {
     steps?: StepperStep[];
     currentStep?: number;
-    alignment?: StepperAlignment;
+    alignment?: StepperAlignment | 'horizontal' | 'vertical';
     onStepClicked?: ((index: number) => void) | null;
     /** Allow clicking any step, not just completed ones. */
     nonLinear?: boolean;
-    /** Hide the label text beneath each step entry. */
+    /** Hide the label text (and description) beneath each step entry. */
     hideLabels?: boolean;
+    /** Visual preset for markers and connectors (default `Default`). */
+    styleType?: StepperStyleType;
+    /** 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;
     className?: string;
     style?: React.CSSProperties;
     classNames?: SlotClassNames<StepperSlots>;

package/dist/types/package/common/sticky/stickyStack.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Coordinates every mounted `Sticky` so ones that overlap horizontally stack
+ * underneath each other (in DOM order) instead of pinning to the same spot.
+ * Non-overlapping ones (e.g. side-by-side halves under a full-width one) land
+ * at the same top instead of being pushed down by each other.
+ */
+export interface StickyStackMetrics {
+    /** Current (unstuck-flow) top of the root element, from getBoundingClientRect. */
+    top: number;
+    left: number;
+    width: number;
+    contentHeight: number;
+}
+export interface StickyStackEntry {
+    node: HTMLElement;
+    offsetTop: number;
+    disabled: boolean;
+    getMetrics: () => StickyStackMetrics | null;
+}
+export interface StickyStackResult {
+    isStuck: boolean;
+    /** Effective `top` to pin at while stuck — offsetTop plus the height of any stuck, overlapping entries above it. */
+    top: number;
+}
+type ResultListener = (result: StickyStackResult) => void;
+declare class StickyStack {
+    private entries;
+    private listeners;
+    private results;
+    private rafId;
+    private listenerCount;
+    schedule: () => void;
+    register(entry: StickyStackEntry, onChange: ResultListener): symbol;
+    updateEntry(id: symbol, patch: Partial<Pick<StickyStackEntry, 'offsetTop' | 'disabled'>>): void;
+    unregister(id: symbol): void;
+    recompute: () => void;
+    private startListening;
+    private stopListening;
+}
+export declare const stickyStack: StickyStack;
+export {};

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

@@ -74,6 +74,28 @@ export interface ThemeVariables {
     '--background-card-elevated'?: string;
     '--background-card-outlined'?: string;
     '--background-card-filled'?: string;
+    /** Step marker diameter. Falls back to 40px. */
+    '--stepper-marker-size'?: string;
+    /** Step marker corner radius. Falls back to --default-border-radius. */
+    '--stepper-marker-radius'?: string;
+    /** Idle (upcoming) marker/connector colour. Falls back to --primary-lighter. */
+    '--stepper-idle-color'?: string;
+    /** Current-step marker colour. Falls back to --primary-color. */
+    '--stepper-active-color'?: string;
+    /** Completed-step marker fill/colour. Falls back to --primary-color. */
+    '--stepper-done-color'?: string;
+    /** Errored-step marker colour. Falls back to --error-color. */
+    '--stepper-error-color'?: string;
+    /** Completed connector colour. Falls back to --primary-color. */
+    '--stepper-connector-color'?: string;
+    /** Completed connector thickness. Falls back to 3px. */
+    '--stepper-connector-thickness'?: string;
+    /** Not-yet-reached connector thickness. Falls back to 1px. */
+    '--stepper-connector-idle-thickness'?: string;
+    /** Gap between marker and label, and grid column gap. Falls back to 12px. */
+    '--stepper-gap'?: string;
+    /** Text/check colour on a filled marker. Falls back to --text-on-primary. */
+    '--stepper-text-on-marker'?: string;
     [key: string]: string | undefined;
 }
 export interface Theme {

package/dist/types/package/common/utils/scrollAncestors.d.ts

@@ -0,0 +1,2 @@
+export declare function getScrollableAncestors(el: HTMLElement): HTMLElement[];
+export declare function isHiddenByAnyAncestor(rect: DOMRect, ancestors: HTMLElement[]): boolean;

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

@@ -5,6 +5,8 @@ export { default as ActionIcon } from './common/actionIcon';
 export * from './common/actionIcon';
 export { default as AnimatedLogo } from './common/animatedLogo';
 export * from './common/animatedLogo';
+export { default as AnimatedText } from './common/animatedText';
+export * from './common/animatedText';
 export { default as Avatar } from './common/avatar';
 export * from './common/avatar';
 export { default as Badge } from './common/badge';
@@ -66,8 +68,12 @@ export { default as OptionPicker } from './common/optionPicker';
 export * from './common/optionPicker';
 export { default as Overscroll } from './common/overscroll';
 export * from './common/overscroll';
+export { default as Popover } from './common/popover';
+export * from './common/popover';
 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 Ripple } from './common/ripple';
 export * from './common/ripple';
 export { default as RoomDrawer } from './common/roomDrawer';

package/docs/AnimatedText.md

@@ -0,0 +1,94 @@
+# AnimatedText
+
+**When to use:** Decorative text entrance or emphasis effect, for hero headlines, empty-state messages, "premium"/"new" callouts, loading/decoding states. Not for body copy that needs to stay readable while animating in bulk; keep it to short strings.
+
+**Import:** `import { AnimatedText, AnimatedTextVariant, AnimatedTextUnit } from '@ahrowe/ui'`
+
+**Style variants:** `AnimatedTextVariant.RiseUp` (default) | `AnimatedTextVariant.BlurIn` | `AnimatedTextVariant.Bounce` | `AnimatedTextVariant.Typewriter` | `AnimatedTextVariant.Scramble` | `AnimatedTextVariant.Glitch` | `AnimatedTextVariant.Wave` | `AnimatedTextVariant.Shine` | `AnimatedTextVariant.Highlight`
+
+**Units (every variant but `Shine`/`Highlight`):** `AnimatedTextUnit.Letter` (default) | `AnimatedTextUnit.Word`
+
+```tsx
+import { AnimatedText, AnimatedTextVariant, AnimatedTextUnit } from '@ahrowe/ui';
+
+// Default: letters rise up, staggered left to right, once
+<AnimatedText text="Welcome back" />
+
+// Faster/slower stagger between letters
+<AnimatedText text="Fast" staggerDelay={15} />
+<AnimatedText text="Slow" staggerDelay={120} />
+
+// Faster/slower per-letter entrance
+<AnimatedText text="Snappy" duration={200} />
+
+// Stagger by word instead of by letter
+<AnimatedText text="One word after another" unit={AnimatedTextUnit.Word} staggerDelay={150} />
+
+// Fades in from a blur
+<AnimatedText text="Fading into focus" variant={AnimatedTextVariant.BlurIn} />
+
+// Drops in from above with a spring overshoot
+<AnimatedText text="Bouncing into place" variant={AnimatedTextVariant.Bounce} />
+
+// Typed one letter at a time, with a blinking cursor at the end
+<AnimatedText text="Typed one letter at a time" variant={AnimatedTextVariant.Typewriter} staggerDelay={60} />
+
+// Typewriter, word by word instead of letter by letter
+<AnimatedText
+  text="Typed word by word"
+  variant={AnimatedTextVariant.Typewriter}
+  unit={AnimatedTextUnit.Word}
+  staggerDelay={250}
+/>
+
+// Resolves from random characters to the real text, left to right
+<AnimatedText text="Decoding the message" variant={AnimatedTextVariant.Scramble} staggerDelay={60} />
+
+// Briefly RGB-splits and jitters before settling
+<AnimatedText text="System malfunction" variant={AnimatedTextVariant.Glitch} />
+
+// Continuously bobs in a travelling wave, on a loop
+<AnimatedText text="Riding the wave" variant={AnimatedTextVariant.Wave} />
+
+// A highlight sweeps across the text, looping
+<AnimatedText text="Premium feature" variant={AnimatedTextVariant.Shine} />
+
+// Slower sweep
+<AnimatedText text="Slow shine" variant={AnimatedTextVariant.Shine} duration={3000} />
+
+// A marker-style highlight block wipes in behind the text, once
+<AnimatedText text="Marked as important" variant={AnimatedTextVariant.Highlight} />
+
+// 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" />
+<button onClick={() => setReplayKey((k) => k + 1)}>Replay</button>
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `text` | `string` | The text to animate (required) |
+| `variant` | `AnimatedTextVariant` | Which animation plays (default `RiseUp`) |
+| `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 |
+
+**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.
+
+**Typewriter:** each letter (or word) pops in instantly at its staggered delay, with no entrance easing, since it's meant to read as being typed rather than animated in. Untyped units aren't rendered at all yet (rather than pre-rendered invisible), so the blinking cursor always tracks right after the last thing actually "typed"; it stays solid while typing and starts blinking once the sequence finishes.
+
+**Scramble:** every unit starts as a run of random characters (matching the unit's own length, so words keep their shape) and locks in to the real value left to right, one `staggerDelay` apart; still-scrambling units keep flickering between random characters until their turn. Spaces are never scrambled.
+
+**Glitch:** a brief RGB-channel split (`--error-color` / `--info-color`) and positional jitter, settling to the normal render partway through the entrance.
+
+**Wave:** the only other continuously looping variant besides `Shine`. Every unit bobs up and down forever, and each unit's `animation-delay` is a *negative* offset (`-index * staggerDelay`), which starts it already mid-cycle so the whole string reads as a travelling wave from the first frame instead of every letter bobbing in lockstep.
+
+**Shine vs. Highlight:** both animate the whole string as a single run (no letter/word splitting, `unit` is ignored) rather than staggering units, since a highlighter mark is naturally one continuous stroke, not a letter-by-letter reveal. `Shine` loops a light gradient through the text's own color, forever. `Highlight` wipes a solid marker-style background block in behind the (already fully-opaque) text once, and stays, closer to literally highlighting the text than lighting it up.
+
+**Replaying:** every variant automatically replays whenever `text`, `variant`, `unit`, `staggerDelay`, or `duration` changes. CSS entrance variants would otherwise just hold their `animation-fill-mode: forwards` end state and silently swap letters underneath it, so the animated markup remounts on any of those changes to keep the animation and the text in sync. To replay with the exact same text (e.g. a manual "Replay" button), change the component's own `key`; that's the only case not already covered automatically.
+
+**Accessibility:** the full `text` is always exposed to assistive tech via a visually-hidden node; the animated markup is `aria-hidden`. Respects `prefers-reduced-motion`: every variant renders the plain, fully-visible final state immediately with no animation (no blur, no bounce, no scrambling, no bobbing, no cursor blink, no shine sweep, no highlight wipe).
+
+**Slots:** `letter`, each animated unit's span, for every variant but `Shine`/`Highlight` (where it's the single animated text run). `cursor`, the blinking cursor, `Typewriter` only.

package/docs/CLAUDE.md

@@ -96,6 +96,7 @@ Slot keys per component are documented in each component's doc file below.
 @ActionButtons.md
 @ActionIcon.md
 @AnimatedLogo.md
+@AnimatedText.md
 @Avatar.md
 @Badge.md
 @BodyEnd.md
@@ -129,7 +130,9 @@ Slot keys per component are documented in each component's doc file below.
 @NumberInput.md
 @OptionPicker.md
 @Overscroll.md
+@Popover.md
 @ProgressBar.md
+@RadioGroup.md
 @Ripple.md
 @RoomDrawer.md
 @RoomViewer.md

package/docs/ConfigProvider.md

@@ -58,7 +58,7 @@ So a global default only fills in props a given instance left out — any instan
 
 Each entry is a `Partial<...Props>`, so any of that component's props can be defaulted:
 
-- **Form inputs:** `Input` · `Textarea` · `NumberInput` · `Dropdown` · `InputDropdown` · `Checkbox` · `Switch` · `DatePicker`
+- **Form inputs:** `Input` · `Textarea` · `NumberInput` · `Dropdown` · `InputDropdown` · `Checkbox` · `Switch` · `RadioGroup` · `DatePicker`
 - **Display:** `Button` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Accordion` · `Divider`
 - **Overlays:** `ConfirmModal`
 

package/docs/Popover.md

@@ -0,0 +1,61 @@
+# Popover
+
+**When to use:** A floating panel anchored to a trigger — profile cards, quick forms, action menus, help panels, filter dropdowns. Reach for `Tooltip` for plain text hints, `FloatingMenu` for a menu that mirrors the trigger width; use `Popover` when you need free content on any side with an arrow.
+
+**Import:** `import { Popover } from '@ahrowe/ui'`
+
+```tsx
+import { Popover, PopoverPlacement, PopoverAlign, PopoverTrigger } from '@ahrowe/ui';
+
+// Basic — children is the trigger, content is the panel body
+<Popover content={<ProfileCard />}>
+  <button>Open</button>
+</Popover>
+
+// Placement + alignment
+<Popover placement={PopoverPlacement.Right} align={PopoverAlign.Start} content={<Menu />}>
+  <ActionIcon icon={faEllipsis} />
+</Popover>
+
+// Hover trigger, no arrow
+<Popover trigger={PopoverTrigger.Hover} withArrow={false} content="Quick info">
+  <span>Hover me</span>
+</Popover>
+
+// Controlled open state
+<Popover isOpen={open} onOpenChange={setOpen} content={<Form onDone={() => setOpen(false)} />}>
+  <button>Edit</button>
+</Popover>
+```
+
+**PopoverPlacement enum:** `PopoverPlacement.Top` | `Bottom` | `Left` | `Right` — the preferred side; auto-flips to the opposite side when there's no room.
+
+**PopoverAlign enum:** `PopoverAlign.Start` | `Center` | `End` — cross-axis alignment against the trigger.
+
+**PopoverTrigger enum:** `PopoverTrigger.Click` | `Hover` | `Focus`.
+
+**Key props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `content` | `ReactNode` | — | Panel body |
+| `children` | `ReactNode` | — | Trigger element |
+| `placement` | `PopoverPlacement` | `Bottom` | Preferred side |
+| `align` | `PopoverAlign` | `Center` | Cross-axis alignment |
+| `trigger` | `PopoverTrigger` | `Click` | What opens the popover |
+| `isOpen` | `boolean` | — | Controlled open state (omit for uncontrolled) |
+| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled |
+| `onOpenChange` | `(isOpen: boolean) => void` | — | Open-state change callback |
+| `offset` | `number` | `10` | Gap in px between trigger and panel |
+| `withArrow` | `boolean` | `true` | Render the arrow pointing at the trigger |
+| `closeOnOutsideClick` | `boolean` | `true` | Close on click outside (ignored for hover trigger) |
+| `closeOnEscape` | `boolean` | `true` | Close on Escape |
+| `openDelay` | `number` | `100` | Hover open delay in ms |
+| `closeDelay` | `number` | `120` | Hover close delay in ms |
+| `disabled` | `boolean` | `false` | Prevent opening |
+
+**Slots:** `root` `trigger` `floating` `panel` `arrow`
+
+Requires a `<div id="bodyEnd"></div>` at the app root — the panel is portaled there, same as `Tooltip` and `FloatingMenu`.
+
+**Keyboard & focus (click trigger):** the panel is portaled to the end of the DOM, so Tab can't reach it naturally. When the panel has focusable content, opening it (click trigger only) moves focus to the first focusable element and the panel gets `role="dialog"`. Tabbing past the last element closes the popover and moves focus to the element after the trigger; Shift+Tab past the first element, and Escape, close it and return focus to the trigger. This is non-modal — focus is not trapped, and hover/focus triggers don't steal focus. Popovers with only static content don't manage focus or claim the dialog role.

package/docs/RadioGroup.md

@@ -0,0 +1,76 @@
+# RadioGroup
+
+**When to use:** Single-choice selection from a small, always-visible set of options — plan pickers, shipping methods, yes/no/maybe, settings with 2–5 mutually exclusive choices. Prefer `Dropdown` when the list is long, and `OptionPicker` for a compact segmented control.
+
+**Import:** `import { RadioGroup, RadioGroupOrientation } from '@ahrowe/ui'`
+**Types:** `import type { RadioOption, RadioGroupProps, RadioValue } from '@ahrowe/ui'`
+
+Follows the ARIA `radiogroup` pattern: one roving tab stop, arrow keys move focus **and** selection (skipping disabled options and wrapping around), Space/Enter selects the focused option.
+
+```tsx
+import { RadioGroup, RadioGroupOrientation, FormValidator } from '@ahrowe/ui';
+import type { RadioOption } from '@ahrowe/ui';
+
+const options: RadioOption[] = [
+  { value: 'free', label: 'Free' },
+  { value: 'pro', label: 'Pro' },
+  { value: 'team', label: 'Team', disabled: true },
+];
+
+// Controlled
+<RadioGroup options={options} value={plan} onChange={(v) => setPlan(v as string)} />
+
+// Uncontrolled with an initial value
+<RadioGroup options={options} defaultValue="free" />
+
+// Horizontal layout
+<RadioGroup options={options} value={plan} onChange={setPlan} orientation={RadioGroupOrientation.Horizontal} />
+
+// Per-option descriptions
+<RadioGroup
+  options={[
+    { value: 'standard', label: 'Standard', description: '3–5 business days, free' },
+    { value: 'express', label: 'Express', description: 'Next business day, €9.90' },
+  ]}
+  value={shipping}
+  onChange={setShipping}
+/>
+
+// With FormValidator
+const planValidator = new FormValidator<string | null>(null, [Validators.required()]);
+<RadioGroup options={options} formValidator={planValidator} />
+```
+
+**RadioGroupOrientation enum:** `RadioGroupOrientation.Vertical` (default) | `RadioGroupOrientation.Horizontal`
+
+**RadioOption:**
+
+```ts
+interface RadioOption {
+  value: string | number;
+  label?: ReactNode;        // falls back to `value`
+  description?: ReactNode;  // secondary text under the label
+  disabled?: boolean;       // disable just this option
+}
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `options` | `RadioOption[]` | The selectable options |
+| `value` | `string \| number` | Controlled selected value |
+| `defaultValue` | `string \| number` | Initial value when uncontrolled |
+| `onChange` | `(value, event?) => void` | Fires with the newly selected value |
+| `orientation` | `RadioGroupOrientation` | Layout direction (default `Vertical`) |
+| `disabled` | `boolean` | Disable the whole group |
+| `size` | `string` | Diameter of the radio circle (default `'18px'`) |
+| `formValidator` | `FormValidator` | Connects to form validation |
+| `errorMessage` | `string` | Manual error message (when not using a `formValidator`) |
+| `isValid` | `boolean` | Manual valid state (default `true`) |
+
+**Validation:** like `Input`, an errored group shows an error `Tooltip` and turns its unselected circles red. With a `formValidator` the error surfaces only after the field is *touched* (focus leaves the group), then on focus or hover; requires `<div id="bodyEnd"></div>` at the app root for the tooltip portal.
+
+**Global defaults:** adopts `ConfigProvider` — e.g. `defaultProps={{ RadioGroup: { orientation: RadioGroupOrientation.Horizontal } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `option` `radio` `dot` `label` `description`

package/docs/Stepper.md

@@ -1,11 +1,19 @@
 # Stepper
 
-**When to use:** Step progress indicator — multi-step forms, onboarding flows, checkout wizards. Shows completed, current, and upcoming steps.
+**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.
 
 **Import:** `import { Stepper } from '@ahrowe/ui'`
+**Types:** `import type { StepperStep, StepperProps } from '@ahrowe/ui'`
+
+**Enums:**
+- `StepperAlignment`: `Horizontal` (default) | `Vertical`
+- `StepperStyleType`: `Default` (filled numbered markers) | `Outlined` (numbered markers that stay ringed when completed) | `Dots` (minimal dots, no numbers)
+- `StepperCollapse`: `None` (default) | `ActiveOnly` | `Completed`
+- `StepperLabelPlacement`: `Top` | `Bottom` | `Left` | `Right`
 
 ```tsx
-import { Stepper } from '@ahrowe/ui';
+import { Stepper, StepperAlignment, StepperStyleType, StepperCollapse } from '@ahrowe/ui';
+import { faUser, faCreditCard } from '@fortawesome/free-solid-svg-icons';
 
 const steps = [
   { label: 'Account' },
@@ -16,22 +24,107 @@ const steps = [
 // Horizontal (default)
 <Stepper steps={steps} currentStep={1} />
 
-// Vertical
+// Style presets
+<Stepper steps={steps} currentStep={1} styleType={StepperStyleType.Outlined} />
+<Stepper steps={steps} currentStep={1} styleType={StepperStyleType.Dots} hideLabels />
+
+// Vertical, clickable
 <Stepper
   steps={steps}
   currentStep={currentStep}
-  alignment="vertical"
+  alignment={StepperAlignment.Vertical}
   onStepClicked={(stepIndex) => setCurrentStep(stepIndex)}
 />
+
+// Rich steps — icon, description, error, optional
+<Stepper
+  currentStep={2}
+  steps={[
+    { label: 'Account', icon: faUser, description: 'Login details' },
+    { label: 'Payment', icon: faCreditCard, error: true },
+    { label: 'Review', optional: true },
+  ]}
+/>
+
+// Vertical wizard with collapsible bodies — only the active step's body is open
+<Stepper
+  alignment={StepperAlignment.Vertical}
+  collapse={StepperCollapse.ActiveOnly}
+  currentStep={step}
+  onStepClicked={setStep}
+  steps={[
+    { label: 'Account', description: 'Login details', content: <AccountForm /> },
+    { label: 'Profile', description: 'About you',      content: <ProfileForm /> },
+    { label: 'Confirm', description: 'Finish',         content: <ConfirmStep /> },
+  ]}
+/>
 ```
 
+**StepperStep:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `label` | `ReactNode` | Primary step label |
+| `description` | `ReactNode` | Secondary line under the label |
+| `content` | `ReactNode` | Collapsible body under the label (vertical only) |
+| `icon` | `IconDefinition` | FontAwesome icon in the marker, replacing the number |
+| `error` | `boolean` | Recolours the marker with `--stepper-error-color`; suppresses the checkmark |
+| `optional` | `boolean \| ReactNode` | `true` → an "Optional" hint; a node → custom hint text |
+| `disabled` | `boolean` | Never clickable, dimmed |
+
 **Key props:**
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `steps` | `object[]` | Array of step objects with `label` |
+| `steps` | `StepperStep[]` | The steps to render |
 | `currentStep` | `number` | Zero-based active step index |
-| `alignment` | `'horizontal' \| 'vertical'` | Layout direction |
-| `onStepClicked` | `(stepIndex: number) => void` | Navigate on step click |
+| `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`) |
+| `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 |
+| `hideLabels` | `boolean` | Hide labels, descriptions, and (vertical) content |
+
+**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:
+
+| Variable | Falls back to |
+|----------|---------------|
+| `--stepper-marker-size` | `40px` |
+| `--stepper-marker-radius` | `var(--default-border-radius)` |
+| `--stepper-idle-color` | `var(--primary-lighter)` |
+| `--stepper-active-color` | `var(--primary-color)` |
+| `--stepper-done-color` | `var(--primary-color)` |
+| `--stepper-error-color` | `var(--error-color)` |
+| `--stepper-connector-color` | `var(--primary-color)` |
+| `--stepper-connector-thickness` (completed connectors) | `3px` |
+| `--stepper-connector-idle-thickness` (not-yet-reached connectors) | `1px` |
+| `--stepper-gap` | `12px` |
+| `--stepper-text-on-marker` | `var(--text-on-primary)` |
+
+```tsx
+// Theme-wide, via ThemeProvider — circular pink markers, thicker connectors
+const theme: Theme = {
+  id: 'brand',
+  variables: {
+    '--stepper-marker-radius': '50%',
+    '--stepper-active-color': '#e91e63',
+    '--stepper-connector-thickness': '4px',
+  },
+};
+
+// Or one-off on a single stepper via style
+<Stepper
+  steps={steps}
+  currentStep={1}
+  style={{
+    '--stepper-marker-radius': '50%',
+    '--stepper-active-color': '#e91e63',
+    '--stepper-connector-thickness': '4px',
+  } as React.CSSProperties}
+/>
+```
 
-**Note:** Legacy JSX component — check [package/common/stepper/stepper.jsx](../common/stepper/stepper.jsx) for additional props.
+**Slots:** `root` `entry` `entryNumber` `entryLabel` `connector` `description` `content` `optional` `icon`

package/docs/Sticky.md

@@ -26,10 +26,21 @@ import { Sticky } from '@ahrowe/ui';
 <Sticky disabled={isEditing}>
   <Header />
 </Sticky>
+
+// Two Stickies that overlap horizontally automatically stack — the second
+// pins below the first's height instead of on top of it
+<Sticky offsetTop={0}>
+  <TopBar />
+</Sticky>
+<Sticky offsetTop={0}>
+  <FilterBar />
+</Sticky>
 ```
 
 **How it works:** while stuck, the content switches to `position: fixed` (measured to keep the same width and horizontal position) and a placeholder of the same height takes its place in the flow. It tracks scroll on the window *and* any ancestor scroll container, so it works inside scrollable panels too — it always pins to the top of the viewport (offset by `offsetTop`).
 
+**Stacking:** every mounted `Sticky` coordinates automatically, no extra markup needed. When more than one is stuck at the same time, a later one (in DOM order) that horizontally overlaps an earlier stuck one pins below it — `offsetTop` plus the overlapping ones' heights — instead of both landing on the same spot. Stickies that don't overlap horizontally (e.g. two half-width ones side by side under a full-width one) land at the same `top`, next to each other, rather than pushing each other down.
+
 **Key props:**
 
 | Prop | Type | Description |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },
@@ -50,6 +50,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
+    "build:demo": "vite build --base=/packages/ui/demo/ --outDir dist-demo",
     "build:lib": "vite build --config vite.lib.config.ts",
     "build:mcp": "vite build --config vite.mcp.config.ts",
     "preview": "vite preview",