@ahrowe/ui 0.27.0 → 0.29.0

package/dist/types/{package/common → common}/toast/toastProvider.d.ts

@@ -1,8 +1,8 @@
+import { default as React, ReactNode } from 'react';
 import { ToastContextConfig } from './toast.types';
-import { ReactNode } from 'react';
 interface ToastProviderProps extends ToastContextConfig {
     children: ReactNode;
 }
-declare function ToastProvider({ children, position, duration, showRemainingTime, showCloseButton, allowStacking, pauseOnHover, }: ToastProviderProps): import("react/jsx-runtime").JSX.Element;
+declare function ToastProvider({ children, position, duration, showRemainingTime, showCloseButton, allowStacking, pauseOnHover, }: ToastProviderProps): React.JSX.Element;
 export default ToastProvider;
 export type { ToastProviderProps };

package/dist/types/{package/common → common}/tooltip/tooltip.d.ts

@@ -1,2 +1,3 @@
+import { default as React } from 'react';
 import { TooltipProps } from './tooltip.types';
-export default function Tooltip({ variant, message, isVisible, tooltipPosition, onClick, }: TooltipProps): import("react/jsx-runtime").JSX.Element | null;
+export default function Tooltip({ variant, message, isVisible, tooltipPosition, onClick }: TooltipProps): React.JSX.Element | null;

package/dist/types/common/tree/flattenTree.d.ts

@@ -0,0 +1,3 @@
+import { FlatTreeNode, TreeNode, TreeValue } from './tree.types';
+/** The visible nodes in render order. Flat, not nested, deliberately: see docs/Tree.md. */
+export declare function flattenTree(nodes: TreeNode[], expandedKeys: TreeValue[], level?: number, parentKey?: TreeValue | null): FlatTreeNode[];

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

@@ -0,0 +1,3 @@
+export { default } from './tree';
+export { flattenTree } from './flattenTree';
+export * from './tree.types';

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

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { TreeProps } from './tree.types';
+declare function Tree(props: TreeProps): ReactElement;
+export default Tree;

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

@@ -0,0 +1,62 @@
+import { CSSProperties, ReactNode } from 'react';
+import { IconContent } from '../types/icon.types';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
+export type TreeValue = string | number;
+export interface TreeNode {
+    key: TreeValue;
+    label: ReactNode;
+    /** Icon shown before the label. */
+    icon?: IconContent;
+    /** Child nodes. An empty array still renders a toggle, for a branch whose children load later. */
+    children?: TreeNode[];
+    disabled?: boolean;
+}
+/** One visible row produced by `flattenTree`. */
+export interface FlatTreeNode {
+    node: TreeNode;
+    /** Depth from the roots, 0-based. */
+    level: number;
+    parentKey: TreeValue | null;
+    isBranch: boolean;
+    isExpanded: boolean;
+    /** Number of siblings at this level, for `aria-setsize`. */
+    setSize: number;
+    /** 1-based position among those siblings, for `aria-posinset`. */
+    posInSet: number;
+}
+export type TreeSlots = 'root' | 'node' | 'toggle' | 'icon' | 'label' | 'empty';
+export interface TreeProps extends Omit<HtmlProps<HTMLDivElement>, 'onSelect'> {
+    nodes: TreeNode[];
+    /** Controlled set of expanded branch keys. Omit for uncontrolled. */
+    expandedKeys?: TreeValue[];
+    /** Branches expanded initially when uncontrolled (default `[]`). */
+    defaultExpandedKeys?: TreeValue[];
+    onExpandedChange?: (keys: TreeValue[]) => void;
+    /** Controlled selected key. Omit for uncontrolled. */
+    selectedKey?: TreeValue | null;
+    /** Key selected initially when uncontrolled. */
+    defaultSelectedKey?: TreeValue;
+    onSelect?: (key: TreeValue, node: TreeNode) => void;
+    /** Clicking a branch's label toggles it as well as selecting it (default `true`). */
+    expandOnSelect?: boolean;
+    /** Indent per level in px (default `20`). */
+    indent?: number;
+    /** Icon for the expand/collapse toggle. Rotates 90° when open (default a right chevron). */
+    toggleIcon?: IconContent;
+    /**
+     * Sets a fixed viewport height and windows the rows through `VirtualList`, so only the visible
+     * ones are in the DOM. Use it past a few hundred visible nodes. Rows must then be uniform
+     * height: set `--tree-node-height` rather than sizing individual rows.
+     */
+    height?: number | string;
+    /** Row height used by the windowed renderer before measurement (default `32`). */
+    estimatedRowHeight?: number;
+    /** Shown when `nodes` is empty (default `'Nothing here'`). */
+    emptyLabel?: string;
+    disabled?: boolean;
+    'aria-label'?: string;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<TreeSlots>;
+    styles?: SlotStyles<TreeSlots>;
+}

package/dist/types/{package/common → common}/virtualList/virtualList.types.d.ts

@@ -83,6 +83,14 @@ export interface VirtualListProps<T> extends HtmlProps {
     renderRow?: (item: T, index: number) => ReactNode;
     /** Column definitions — presence enables table/header mode. */
     columns?: VirtualListColumn<T>[];
+    /**
+     * Replaces the roles put on the container and rows (default `list`/`listitem`, or `grid`/`row`
+     * with columns). Pass `'none'` for both when the rows carry their own semantics, as `Tree` does.
+     */
+    ariaRoles?: {
+        container: string;
+        row: string;
+    };
     /** Height of the scroll viewport. Defaults to '100%' to fill the parent container. */
     height?: number | string;
     /** Estimated row height before measurement. Default: 40. */

package/dist/types/{package/common → common}/virtualList/virtualRow.d.ts

@@ -14,7 +14,7 @@ export interface VirtualRowProps {
     ariaRowIndex?: number;
     ariaPosInSet?: number;
     ariaSetSize?: number;
-    rowRole: 'row' | 'listitem';
+    rowRole: string;
     reorderable?: boolean;
     /**
      * Native mouse DnD is active for the list. Distinct from `draggable`, which in
@@ -45,5 +45,5 @@ export interface VirtualRowProps {
  * grid (table mode), registering itself with the shared ResizeObserver and
  * carrying all the drag / drop-indicator wiring the parent assigns it.
  */
-declare function VirtualRow({ index, top, padding, columnTemplate, isSelected, showDivider, hover, onClick, observer, ariaRowIndex, ariaPosInSet, ariaSetSize, rowRole, reorderable, mouseDragEnabled, draggable, isDragging, reserveToggleGutter, onMouseDown, onMouseOver, onMouseLeave, onDragStart, onDragOver, onDragEnd, onDrop, onTouchStart, dropPosition, dropIndentPx, dropIndicatorClassName, dropIndicatorStyle, rowClassName, rowStyle, children, }: VirtualRowProps): import("react/jsx-runtime").JSX.Element;
+declare function VirtualRow({ index, top, padding, columnTemplate, isSelected, showDivider, hover, onClick, observer, ariaRowIndex, ariaPosInSet, ariaSetSize, rowRole, reorderable, mouseDragEnabled, draggable, isDragging, reserveToggleGutter, onMouseDown, onMouseOver, onMouseLeave, onDragStart, onDragOver, onDragEnd, onDrop, onTouchStart, dropPosition, dropIndentPx, dropIndicatorClassName, dropIndicatorStyle, rowClassName, rowStyle, children, }: VirtualRowProps): React.JSX.Element;
 export default VirtualRow;

package/dist/types/{package/common → common}/wizard/wizard.d.ts

@@ -1,2 +1,3 @@
+import { default as React } from 'react';
 import { WizardProps } from './wizard.types';
-export default function Wizard({ currentStep, stepCount, renderStep, className, style, classNames, styles: slotStyles, ...rest }: WizardProps): import("react/jsx-runtime").JSX.Element;
+export default function Wizard({ currentStep, stepCount, renderStep, className, style, classNames, styles: slotStyles, ...rest }: WizardProps): React.JSX.Element;

package/dist/types/{package/index.d.ts → index.d.ts}

@@ -75,6 +75,8 @@ export * from './common/klipyPicker';
 export * from './common/loading';
 export { default as Modal } from './common/modal';
 export * from './common/modal';
+export { default as MultiSelect } from './common/multiSelect';
+export * from './common/multiSelect';
 export { default as NumberInput } from './common/numberInput';
 export * from './common/numberInput';
 export { default as OptionPicker } from './common/optionPicker';
@@ -83,6 +85,8 @@ export { default as OtpInput } from './common/otpInput';
 export * from './common/otpInput';
 export { default as Overscroll } from './common/overscroll';
 export * from './common/overscroll';
+export { default as Pagination } from './common/pagination';
+export * from './common/pagination';
 export { default as Popover } from './common/popover';
 export * from './common/popover';
 export { default as ProgressBar } from './common/progressBar';
@@ -138,6 +142,8 @@ export { default as ToastProvider } from './common/toast';
 export * from './common/toast';
 export { default as Tooltip } from './common/tooltip';
 export * from './common/tooltip';
+export { default as Tree } from './common/tree';
+export * from './common/tree';
 export { default as VirtualList } from './common/virtualList';
 export * from './common/virtualList';
 export { default as Wizard } from './common/wizard';

package/dist/types/{package/services → services}/formValidation/index.d.ts

@@ -2,4 +2,4 @@ export { default as FormValidatorGroup } from './FormValidatorGroupWithForm';
 export { default as ValidatableComponent } from './validatableComponent';
 export { useFormValidatorGroup } from './useFormValidatorGroup';
 export { FormValidator, Validators, useFormValidator } from '@ahrowe/form-validation';
-export type { ValidationError, ValidatorFunction, ErrorParser, FormValidatorGroupOptions, InferGroupValues, MergedValues } from '@ahrowe/form-validation';
+export type { ValidationError, ValidatorFunction, ErrorParser, FormValidatorGroupOptions, InferGroupValues, MergedValues, } from '@ahrowe/form-validation';

package/docs/CLAUDE.md

@@ -156,10 +156,12 @@ FontAwesome internals, so they still take an `IconDefinition` only.
 @KlipyPicker.md
 @Loading.md
 @Modal.md
+@MultiSelect.md
 @NumberInput.md
 @OptionPicker.md
 @OtpInput.md
 @Overscroll.md
+@Pagination.md
 @Popover.md
 @ProgressBar.md
 @RadioGroup.md
@@ -186,5 +188,6 @@ FontAwesome internals, so they still take an `IconDefinition` only.
 @Timer.md
 @Toast.md
 @Tooltip.md
+@Tree.md
 @VirtualList.md
 @Wizard.md

package/docs/InputDropdown.md

@@ -58,6 +58,7 @@ interface InputDropdownItem {
 | `value` | `string` | Controlled value |
 | `items` | `InputDropdownItem[]` | Dropdown options |
 | `allowCustomValue` | `boolean` | Allow free-text values not in `items` — the typed text is emitted via `onChange` on every keystroke (default `false`) |
+| `maxItems` | `number` | Maximum number of filtered matches rendered in the list. Further matches are dropped, since the list is narrowed by typing rather than by scrolling. `0` renders all matches. Default `100` |
 | `onSelect` | `(value: string) => void` | Called when an item is picked from the list |
 | `onChange` | `(value: unknown) => void` | Called on every text change |
 | `placeholder` | `string` | |
@@ -68,4 +69,6 @@ interface InputDropdownItem {
 
 **Slots:** `root` `dropdown` `item`
 
+Long lists are handled by capping how many matches are rendered (`maxItems`, default `100`) rather than by virtualizing: only about six rows fit in the scroll box, so anything past the cap is DOM the user never sees. Raise `maxItems` (or set it to `0`) if a list is genuinely meant to be scrolled end to end. For lists too large to pass as `items` at all, fetch on the server, keep the results in your own state and feed them in as `items`.
+
 The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). It flips to open upward automatically when there's no room below, and shifts horizontally to stay within the viewport when the trigger sits near the left or right edge of the screen. It hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view. It also re-measures when its own content changes size while open, so a list that shrinks (e.g. filtered down to fewer entries) stays anchored to the trigger instead of hanging above it.

package/docs/MultiSelect.md

@@ -0,0 +1,100 @@
+# MultiSelect
+
+**When to use:** Pick several options from a list. Selections appear as removable chips in the control, and the list opens in a panel below it. For a single choice use [Dropdown](Dropdown.md); for a handful of options that should stay visible use [OptionPicker](OptionPicker.md) or [Checkbox](Checkbox.md); for type-ahead against one value use [InputDropdown](InputDropdown.md).
+
+**Keywords:** tags, token input, multi-value, pick many, select multiple, facet, chips picker
+
+**Import:** `import { MultiSelect } from '@ahrowe/ui'`  
+**Types:** `import type { MultiSelectProps, MultiSelectItem, MultiSelectValue } from '@ahrowe/ui'`
+
+**Requires:** `<div id="bodyEnd"></div>` in your app — the panel renders through a portal.
+
+```tsx
+import { useState } from 'react';
+import { MultiSelect } from '@ahrowe/ui';
+import type { MultiSelectItem, MultiSelectValue } from '@ahrowe/ui';
+
+const items: MultiSelectItem[] = [
+  { key: 'apple', label: 'Apple' },
+  { key: 'banana', label: 'Banana' },
+  { key: 'fig', label: 'Fig', disabled: true },
+];
+
+// Controlled
+const [value, setValue] = useState<MultiSelectValue[]>([]);
+<MultiSelect items={items} value={value} onChange={setValue} label="Fruit" placeholder="Pick some" />
+
+// Uncontrolled
+<MultiSelect items={items} defaultValue={['apple']} onChange={(value) => console.log(value)} />
+
+// Searchable, for a list too long to scan
+<MultiSelect items={countries} searchable searchPlaceholder="Filter countries…" />
+
+// Tag entry: type a value that isn't in `items` and pick the "add" row
+<MultiSelect items={commonTags} allowCustomValues createLabel={(value) => `Neu: ${value}`} />
+
+// Cap the selection — unselected options disable once the cap is reached
+<MultiSelect items={items} maxSelected={3} />
+
+// Connected to a FormValidator, like Input and Dropdown
+<MultiSelect items={items} formValidator={form.fruit} label="Fruit" />
+
+// Manual error state, when there's no validator
+<MultiSelect items={items} isValid={false} errorMessage="Pick at least one" />
+
+// Always a bottom sheet, rather than only on a small touch screen
+import { Presentation } from '@ahrowe/ui';
+<MultiSelect items={items} presentation={Presentation.Sheet} />
+```
+
+**Value:** `onChange` gets the full new selection as an array of `key`s, in the order the user picked them, and the chips render in that same order. It is never called with a partial change, so `onChange={setValue}` is all a controlled field needs.
+
+**The label floats like `Input`'s.** It rests vertically centred over the control and rises into a notch cut out of the border once the field is focused, open, or has a selection, using the same `fieldset`/`legend` construction and the same `--input-notch-height` geometry as `Input`. A `MultiSelect` sitting next to an `Input` in a form animates with it rather than against it. Set `alwaysFloatLabel` to pin it up, which is what you want when a `placeholder` should always be readable: with a label present the placeholder is otherwise faded in on a delay matching the label's animation, so the two never sit on top of each other. Without a label there is nothing to wait for and it fades in at once.
+
+**Errors:** with a `formValidator` the field stays quiet until it has been touched (the first time the panel closes), then shows the validator's message while the field is hovered or focused, and drops it as soon as the validator is happy again. Without a validator, `isValid` and `errorMessage` are plain props and nothing clears them for you: derive them from your own state, as in `isValid={picked.length > 0}`.
+
+**Height:** a MultiSelect with one row of chips is exactly as tall as an `Input` or `Dropdown` beside it, so a form row lines up. It grows only when the chips wrap onto a second row. The chips render at `0.8em` to fit: a standalone `Chip` is nearly as tall as the whole field, because its remove button carries `ActionIcon`'s padding around a `1em` icon.
+
+**Custom values** (`allowCustomValues`) turn this into a tag input. Anything typed that matches no item's label or key, and isn't already selected, gets an extra row at the bottom of the panel offering to add it; picking that row commits the typed string as its own key and clears the box. It goes through the same highlight and `Enter` path as a normal option, so the keyboard works unchanged, and `maxSelected` still caps it. Because a custom value has no entry in `items`, its chip falls back to showing the value itself. Without `allowCustomValues`, a selected key that isn't in `items` renders no chip at all.
+
+**Item labels are strings, not nodes.** The same text renders twice, in the option row and inside the `Chip`, and `Chip` takes a string. Reach for `Dropdown` when an option needs rich content.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `MultiSelectItem[]` | The options: `{ key, label, disabled? }` |
+| `value` | `MultiSelectValue[]` | Controlled selection (omit for uncontrolled) |
+| `defaultValue` | `MultiSelectValue[]` | Initial selection when uncontrolled (default `[]`) |
+| `onChange` | `(value: MultiSelectValue[]) => void` | Fires with the full new selection |
+| `label` | `string` | Field label. Rests inside the control, floats into the border notch |
+| `alwaysFloatLabel` | `boolean` | Keep the label floating even when empty and unfocused (default `false`) |
+| `placeholder` | `string` | Shown while nothing is selected. With a `label`, it fades in only after the label has finished floating clear |
+| `searchable` | `boolean` | Show a search box in the panel (default `false`) |
+| `allowCustomValues` | `boolean` | Let the user add a value not in `items`. Implies `searchable` |
+| `createLabel` | `(value: string) => string` | Label for the add row (default `Add "…"`) |
+| `searchPlaceholder` | `string` | Placeholder for that box (default `'Search…'`) |
+| `emptyLabel` | `string` | Shown when nothing matches (default `'No matches'`) |
+| `maxSelected` | `number` | Cap the selection; unselected options disable at the cap |
+| `clearable` | `boolean` | Show the clear-all button (default `true`) |
+| `disabled` | `boolean` | Dims the field and blocks interaction |
+| `readOnly` | `boolean` | Shows the selection, allows no changes, no dimming |
+| `presentation` | `Presentation` | Anchored panel, bottom sheet, or sheet only on small touch screens |
+| `formValidator` | `FormValidator \| null` | Owns the value when present. See [FormValidator.md](FormValidator.md) |
+| `errorMessage` | `string` | Manual error, shown in a tooltip when there's no validator |
+| `isValid` | `boolean` | Manual valid state (default `true`) |
+
+**Keyboard:** `↓` or `Enter` opens the panel. `↑`/`↓` move the highlight and wrap around, `Home`/`End` jump to the ends, `Enter` toggles the highlighted option, `Escape` closes. `Backspace` removes the last selection when the search box is empty. With `searchable`, focus moves into the search box on open and the same keys work from there.
+
+**Accessibility:** the control is a `role="combobox"` with `aria-expanded`, `aria-haspopup="listbox"` and `aria-controls`; the panel is a `role="listbox"` with `aria-multiselectable="true"`, and each option carries `aria-selected`. The highlighted option is reported through `aria-activedescendant`, so focus stays on the control (or the search box) rather than moving between options. Each chip's remove button is labelled `Remove <label>`.
+
+**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 |
+|----------|---------------|
+| `--multi-select-min-height` | `calc(1.25em + 14px)`, the same height `Input` and `Dropdown` resolve to |
+| `--multi-select-panel-height` | `260px` |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ MultiSelect: { searchable: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `label` `fieldset` `control` `values` `chip` `placeholder` `clearButton` `icon` `panel` `search` `options` `option` `optionCheck` `optionLabel` `empty`

package/docs/Pagination.md

@@ -0,0 +1,72 @@
+# Pagination
+
+**When to use:** Move through server-paged results a page at a time — a results list, an admin table, a report. For endless scrolling instead, use `InfiniteBlock`; for a long list that's all in memory, use `VirtualList`.
+
+**Keywords:** pager, paging, page numbers, next page, previous page, page navigation, offset, results
+
+**Import:** `import { Pagination } from '@ahrowe/ui'`  
+**Types:** `import type { PaginationProps } from '@ahrowe/ui'`
+
+```tsx
+import { useState } from 'react';
+import { Pagination } from '@ahrowe/ui';
+
+// Controlled — the usual shape, since the page drives a fetch
+const [page, setPage] = useState(1);
+<Pagination total={20} page={page} onChange={setPage} />
+
+// Uncontrolled
+<Pagination total={20} defaultPage={3} onChange={(page) => console.log(page)} />
+
+// Total pages from a row count
+<Pagination total={Math.ceil(rowCount / pageSize)} page={page} onChange={setPage} />
+
+// First/last jump controls outside the previous/next ones
+<Pagination total={50} page={page} onChange={setPage} showEdges />
+
+// Page numbers only, no previous/next
+<Pagination total={20} page={page} onChange={setPage} showControls={false} />
+
+// Narrower — one page either side of the current one is already the default, `0` shows just the current
+<Pagination total={100} page={page} onChange={setPage} siblings={0} />
+
+// Wider window and more pages pinned at each end
+<Pagination total={100} page={page} onChange={setPage} siblings={2} boundaries={2} />
+
+// Disabled while the page's data is loading
+<Pagination total={20} page={page} onChange={setPage} disabled={isLoading} />
+```
+
+**Which pages are shown:** the first and last `boundaries` pages, the current page with `siblings` pages either side, and a `…` wherever a run was collapsed. A gap only appears when it replaces more than one page — collapsing a single page would take the same width and hide a reachable page, so that side lists a fixed-size block instead. With the defaults (`siblings={1}`, `boundaries={1}`) the control is always 7 page slots wide, so it never reflows as the user pages through.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `total` | `number` | Total number of pages (not rows). Renders nothing below `1` |
+| `page` | `number` | Controlled current page, 1-based (omit for uncontrolled). Clamped to `1…total` |
+| `defaultPage` | `number` | Initial page when uncontrolled (default `1`) |
+| `onChange` | `(page: number) => void` | Fires with the new page; not called when the current page is clicked again |
+| `siblings` | `number` | Pages shown either side of the current one (default `1`) |
+| `boundaries` | `number` | Pages always shown at the start and end (default `1`) |
+| `showControls` | `boolean` | Show the previous/next controls (default `true`) |
+| `showEdges` | `boolean` | Show first/last jump controls outside the previous/next ones (default `false`) |
+| `disabled` | `boolean` | Disables every button |
+| `previousIcon` / `nextIcon` | `IconDefinition \| ReactElement` | Override the previous/next icons (default chevrons) |
+| `firstIcon` / `lastIcon` | `IconDefinition \| ReactElement` | Override the first/last icons (default double chevrons) |
+| `aria-label` | `string` | Accessible name for the `<nav>` (default `'Pagination'`) |
+
+**Accessibility:** renders a `<nav>` of `<button>`s. The current page carries `aria-current="page"`; each page button is labelled `Go to page N`, the controls `Go to previous page` / `Go to next page` / `Go to first page` / `Go to last page`. Previous/next are disabled at the respective end rather than hidden, so the control doesn't reflow. The `…` is `aria-hidden`.
+
+**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 |
+|----------|---------------|
+| `--pagination-active-background` | `var(--primary-color)` |
+| `--pagination-active-color` | `var(--text-on-primary)` |
+| `--pagination-size` | `36px` |
+| `--pagination-gap` | `4px` |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Pagination: { showEdges: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `item` `control` `ellipsis`

package/docs/Slider.md

@@ -66,10 +66,13 @@ const [value, setValue] = useState(40);
 
 | 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 |
+| `range` | `boolean` | Two thumbs, working in `[from, to]` pairs |
+| `minRange` | `number` | Smallest gap the thumbs may be pushed to (range mode, default `0`) |
+| `thumbLabels` | `[string, string]` | Accessible name per thumb (range mode, default `'From'`/`'To'`) |
+| `value` | `number \| [number, number]` | Controlled value (omit for uncontrolled) |
+| `defaultValue` | `number \| [number, number]` | Initial value when uncontrolled (default `min`, or `[min, max]` in range mode) |
+| `onChange` | `(value: number \| [number, number]) => void` | Fires on every change, matching the mode |
+| `onChangeEnd` | `(value: number \| [number, number]) => void` | Fires once the value is committed |
 | `min` | `number` | Minimum (default `0`) |
 | `max` | `number` | Maximum (default `100`) |
 | `step` | `number` | Snap increment (default `1`) |
@@ -92,4 +95,31 @@ const [value, setValue] = useState(40);
 | `--slider-thumb-size` | `18px` (also settable per instance via `size`) |
 | `--slider-track-height` | `6px` |
 
+**Range mode:** set `range` for two thumbs and `[from, to]` pairs.
+
+```tsx
+const [price, setPrice] = useState<[number, number]>([20, 80]);
+<Slider range value={price} onChange={setPrice} min={0} max={200} />
+
+// Hold the ends apart, and name each thumb for screen readers
+<Slider range defaultValue={[20, 80]} minRange={10} thumbLabels={['Cheapest', 'Dearest']} />
+```
+
+`range` is a discriminated prop, not a widening of `value`: with `range` the value is a
+`[number, number]` and `onChange` receives one, without it both stay `number`. An existing
+`onChange={(value: number) => …}` therefore keeps compiling untouched.
+
+A thumb never crosses its neighbour. Push one past the other and it stops on it, or on `minRange`
+short of it, which the neighbour wins over the step: a thumb lands exactly on its neighbour rather
+than overshooting to the next step. The fill covers the span between the thumbs instead of running
+from the minimum.
+
+Note `range` the prop (two thumbs) and `range` the slot (the filled part of the track) are
+different things that happen to share a word. The slot means the same in both modes.
+
+**Accessibility:** a single-thumb slider is itself `role="slider"`. A range slider is a
+`role="group"` named by `aria-label`, containing one `role="slider"` per thumb, each with its own
+`aria-valuenow` and each bounded by its neighbour rather than by `min`/`max`, so assistive tech
+announces the limit the thumb actually has. Both thumbs are tabbable and take the same keys.
+
 **Slots:** `root` `track` `range` `thumb` `mark` `markLabel` `value`

package/docs/Tree.md

@@ -0,0 +1,95 @@
+# Tree
+
+**When to use:** A hierarchical list the user can expand, collapse and pick from: categories, nested locations, folder structures, org charts. For a flat list of thousands of rows use [VirtualList](VirtualList.md); for picking several unrelated values use [MultiSelect](MultiSelect.md).
+
+**Keywords:** hierarchy, directory, expand collapse, parent child, drilldown, navigation sidebar, outline, subfolder
+
+**Import:** `import { Tree, flattenTree } from '@ahrowe/ui'`  
+**Types:** `import type { TreeProps, TreeNode, TreeValue, FlatTreeNode } from '@ahrowe/ui'`
+
+```tsx
+import { useState } from 'react';
+import { Tree } from '@ahrowe/ui';
+import type { TreeNode, TreeValue } from '@ahrowe/ui';
+
+const nodes: TreeNode[] = [
+  {
+    key: 'hall-1',
+    label: 'Hall 1',
+    children: [
+      { key: 'bay-a', label: 'Bay A' },
+      { key: 'bay-b', label: 'Bay B' },
+    ],
+  },
+  { key: 'archive', label: 'Archive', disabled: true },
+];
+
+// Controlled selection
+const [selected, setSelected] = useState<TreeValue | null>(null);
+<Tree nodes={nodes} selectedKey={selected} onSelect={setSelected} aria-label="Locations" />
+
+// Uncontrolled, with some branches open to begin with
+<Tree nodes={nodes} defaultExpandedKeys={['hall-1']} defaultSelectedKey="bay-a" />
+
+// Controlled expansion, e.g. to persist it
+<Tree nodes={nodes} expandedKeys={open} onExpandedChange={setOpen} />
+
+// Clicking a branch selects it without opening it
+<Tree nodes={nodes} expandOnSelect={false} />
+
+// Icons per node, and a wider indent
+import { faWarehouse } from '@fortawesome/free-solid-svg-icons';
+<Tree nodes={nodes.map((n) => ({ ...n, icon: faWarehouse }))} indent={40} />
+```
+
+**Branch or leaf:** a node is a branch when it has a `children` array, even an empty one. `children: []` renders a toggle with nothing behind it yet, which is what you want while a branch's contents are still loading; omit `children` entirely for a true leaf.
+
+**Selection is single.** `onSelect` fires with the key and the node itself, so you do not have to look it up again. There is no multi-select or checkbox mode.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `nodes` | `TreeNode[]` | The tree: `{ key, label, icon?, children?, disabled? }` |
+| `expandedKeys` | `TreeValue[]` | Controlled open branches (omit for uncontrolled) |
+| `defaultExpandedKeys` | `TreeValue[]` | Branches open initially when uncontrolled (default `[]`) |
+| `onExpandedChange` | `(keys: TreeValue[]) => void` | Fires with the full new set of open branches |
+| `selectedKey` | `TreeValue \| null` | Controlled selection (omit for uncontrolled) |
+| `defaultSelectedKey` | `TreeValue` | Selection when uncontrolled |
+| `onSelect` | `(key: TreeValue, node: TreeNode) => void` | Fires with the picked key and node |
+| `expandOnSelect` | `boolean` | Clicking a branch's row also toggles it (default `true`) |
+| `indent` | `number` | Pixels per level (default `20`) |
+| `toggleIcon` | `IconDefinition \| ReactElement` | Toggle icon, rotated 90° when open (default a right chevron) |
+| `height` | `number \| string` | Windows the rows through `VirtualList` at this viewport height |
+| `estimatedRowHeight` | `number` | Row height for the windowed renderer (default `32`) |
+| `emptyLabel` | `string` | Shown when `nodes` is empty (default `'Nothing here'`) |
+| `disabled` | `boolean` | Dims the tree and blocks interaction |
+| `aria-label` | `string` | Accessible name for the tree (default `'Tree'`) |
+
+**Keyboard:** `↑`/`↓` move between visible rows. `→` opens a closed branch, then steps into its first child. `←` closes an open branch, then steps out to its parent. `Home`/`End` jump to the ends. `Enter` or `Space` selects.
+
+**Accessibility:** `role="tree"` containing `role="treeitem"` rows. Because the rows render flat rather than nested, each carries `aria-level`, `aria-posinset` and `aria-setsize`; branches also carry `aria-expanded`. Focus uses a roving tabindex, so one row at a time is reachable by Tab, and it is the selected one (or the first, before anything is selected). The toggle is `aria-hidden`, since `aria-expanded` on the row already reports the state.
+
+**Why flat:** the rows are a flattened list, not nested `<div>`s. Keyboard movement becomes a step along one array instead of a tree walk, and a node's accessible name stays its own label rather than absorbing its descendants'.
+
+**Very large trees:** set `height`. `Tree` then windows its rows through [VirtualList](VirtualList.md), so only the ones in view are in the DOM, and it keeps everything else: the ARIA, the expansion, the selection and the keyboard.
+
+```tsx
+<Tree nodes={nodes} height={300} expandedKeys={open} onExpandedChange={setOpen} />
+```
+
+Two things change in that mode. Rows must be a uniform height, so size them with `--tree-node-height` rather than per row. And the tab stop moves from the selected row to the tree itself, because a roving tabindex on a row that is scrolled out of the window would leave the tree with no tab stop at all; tabbing in still lands on the selected row, which is scrolled into view first.
+
+`flattenTree` is exported separately if you want the rows without the component: it returns `FlatTreeNode`s carrying `node`, `level`, `parentKey`, `isBranch`, `isExpanded`, `setSize` and `posInSet`, ready for `VirtualList`'s `items` and `getItemDepth` (which also feeds its `treeReorder` drag-and-drop). You then write the row markup, ARIA and keyboard handling yourself.
+
+**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 |
+|----------|---------------|
+| `--tree-node-height` | `32px` |
+| `--tree-selected-background` | `var(--primary-color)` |
+| `--tree-selected-color` | `var(--text-on-primary)` |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Tree: { indent: 30 } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `node` `toggle` `icon` `label` `empty`

package/docs/VirtualList.md

@@ -139,6 +139,7 @@ const columns: VirtualListColumn<User>[] = [
 | `onLoadMore` | `() => Promise<void>` | Triggered near the bottom, and repeatedly while the rows don't fill the viewport — append items in the handler |
 | `loadMoreThreshold` | `number` | Distance from bottom that triggers `onLoadMore` (default `100`) |
 | `isLoading` | `boolean` | Replaces list body with a full-height spinner |
+| `ariaRoles` | `{ container: string; row: string }` | Replaces the roles put on the container and rows (default `list`/`listitem`, or `grid`/`row` with columns). Pass `'none'` for both when the rows carry their own semantics, as [Tree](Tree.md) does when windowing `treeitem` rows |
 
 Drag-and-drop reordering adds `reorderable`, `treeReorder`, `dragHandle`, and their callbacks — see **Row reordering** below.