@ahrowe/ui 0.27.0 → 0.28.0

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

@@ -29,6 +29,9 @@ import { FlipProps } from '../flip/flip.types';
 import { OptionPickerProps } from '../optionPicker/optionPicker.types';
 import { TimerProps } from '../timer/timer.types';
 import { OtpInputProps } from '../otpInput/otpInput.types';
+import { MultiSelectProps } from '../multiSelect/multiSelect.types';
+import { PaginationProps } from '../pagination/pagination.types';
+import { TreeProps } from '../tree/tree.types';
 import { RoomDrawerProps } from '../roomDrawer/roomDrawer.types';
 import { RoomViewerProps } from '../roomViewer/roomViewer.types';
 import { FloatingMenuProps, Presentation } from '../floatingMenu/floatingMenu.types';
@@ -79,6 +82,9 @@ export interface ComponentDefaults {
     OptionPicker?: Partial<OptionPickerProps>;
     Timer?: Partial<TimerProps>;
     OtpInput?: Partial<OtpInputProps>;
+    MultiSelect?: Partial<MultiSelectProps>;
+    Pagination?: Partial<PaginationProps>;
+    Tree?: Partial<TreeProps>;
     RoomDrawer?: Partial<RoomDrawerProps>;
     RoomViewer?: Partial<RoomViewerProps>;
     FloatingMenu?: Partial<FloatingMenuProps>;

package/dist/types/package/common/floatingMenu/useFloatingPosition.d.ts

@@ -13,17 +13,15 @@ export interface UseFloatingPositionArgs {
     placement?: 'top' | 'bottom';
 }
 /**
- * Keeps a portaled, `position: fixed` popup anchored to a trigger element: tracks the
- * trigger across scroll/resize on every real scrolling ancestor, flips above the trigger
- * when there's no room below, and hides (not closes) the popup when the trigger itself
+ * Keeps a portaled, `position: fixed` popup anchored to a trigger element: flips above the
+ * trigger when there's no room below, and hides (not closes) the popup when the trigger itself
  * scrolls behind a clipping ancestor — matching Floating UI's autoUpdate + hide middleware.
  * It also shifts the popup horizontally to stay within the viewport: `align`/RTL-style CSS
  * only positions the panel relative to the anchor's own box and has no awareness of where
  * that box actually sits on screen, so a trigger near a screen edge would otherwise let the
  * panel overflow it with no correction.
  *
- * Position/visibility are written straight to the DOM via refs, not through React state:
- * going through setState -> re-render -> commit adds a round-trip that lags behind the
- * browser's own scroll painting by at least a frame.
+ * `useAnchorTracking` supplies the lifecycle around this: mount wait, ancestor resolution, and
+ * re-running on scroll, viewport resize and panel size changes.
  */
 export declare function useFloatingPosition({ isOpen, triggerRef, anchorRef, panelRef, flipClassName, placement }: UseFloatingPositionArgs): void;

package/dist/types/package/common/hooks/useAnchorTracking.d.ts

@@ -0,0 +1,40 @@
+import { RefObject } from 'react';
+export interface UseAnchorTrackingArgs {
+    isOpen: boolean;
+    /** The element the popup is anchored to. Its scrollable ancestors are what get tracked. */
+    triggerRef: RefObject<HTMLElement | null>;
+    /**
+     * Every element the positioning maths needs. Tracking starts only once all of them, plus the
+     * trigger, are mounted. Read fresh on each setup, so an inline array literal is fine.
+     */
+    elementRefs: RefObject<HTMLElement | null>[];
+    /**
+     * Positions the popup. Called once on setup and then on every scroll, resize and tracked size
+     * change. Reads the caller's own refs for everything beyond the two arguments.
+     */
+    update: (trigger: HTMLElement, ancestors: HTMLElement[]) => void;
+    /**
+     * Elements whose own size changes must re-run `update`: a popup whose content changes size
+     * while open (a filtered list shrinking, an async list loading in) otherwise keeps coordinates
+     * computed for its old height and ends up detached from the trigger. Re-read on every update,
+     * since a panel can mount a commit later than the element it hangs off.
+     */
+    resizeRefs?: RefObject<HTMLElement | null>[];
+    /** Hands the popup's elements back as they were found. Runs when tracking stops. */
+    teardown?: () => void;
+    /** Values that must restart tracking, and so re-run `update`, when they change. */
+    deps?: readonly unknown[];
+}
+/**
+ * The lifecycle half of anchoring a portaled, `position: fixed` popup to a trigger: waits for the
+ * elements to mount, resolves the trigger's scrolling ancestors once, and re-runs the caller's
+ * positioning on every scroll, viewport resize and tracked size change until it closes.
+ *
+ * Callers supply only the geometry (`update`) and the inline styles to clear again (`teardown`);
+ * `useFloatingPosition` and `usePopoverPosition` are both built on this.
+ *
+ * Position is deliberately written straight to the DOM by the caller rather than through React
+ * state: going through setState -> re-render -> commit adds a round-trip that lags behind the
+ * browser's own scroll painting by at least a frame.
+ */
+export declare function useAnchorTracking({ isOpen, triggerRef, elementRefs, update, resizeRefs, teardown, deps, }: UseAnchorTrackingArgs): void;

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

@@ -19,6 +19,12 @@ export interface InputDropdownProps extends Omit<HtmlProps, 'onSelect'> {
      * instead of only when an item is picked from the list.
      */
     allowCustomValue?: boolean;
+    /**
+     * Maximum number of filtered items rendered in the list. Matches beyond this
+     * are dropped (the user narrows by typing, not by scrolling). `0` renders all
+     * matches. Default `100`.
+     */
+    maxItems?: number;
     onSelect?: (value: string) => void;
     onChange?: (value: unknown) => void;
     placeholder?: string;

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

@@ -0,0 +1,2 @@
+export { default } from './multiSelect';
+export * from './multiSelect.types';

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

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

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

@@ -0,0 +1,62 @@
+import { CSSProperties } from 'react';
+import { FormValidator } from '../../services/formValidation';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
+import { Presentation } from '../floatingMenu/floatingMenu.types';
+export type MultiSelectValue = string | number;
+export interface MultiSelectItem {
+    key: MultiSelectValue;
+    /** Visible text. A string, not a `ReactNode`, because it also renders inside a `Chip`. */
+    label: string;
+    /** Disable just this option. */
+    disabled?: boolean;
+}
+export type MultiSelectSlots = 'root' | 'label' | 'fieldset' | 'control' | 'values' | 'chip' | 'placeholder' | 'clearButton' | 'icon' | 'panel' | 'search' | 'options' | 'option' | 'optionCheck' | 'optionLabel' | 'empty';
+export interface MultiSelectProps extends Omit<HtmlProps<HTMLDivElement>, 'onChange' | 'value' | 'defaultValue'> {
+    /** The selectable options. */
+    items: MultiSelectItem[];
+    /** Controlled selection. Omit for uncontrolled. */
+    value?: MultiSelectValue[];
+    /** Initial selection when uncontrolled (default `[]`). */
+    defaultValue?: MultiSelectValue[];
+    /** Fires with the full new selection, in the order the items were picked. */
+    onChange?: (value: MultiSelectValue[]) => void;
+    /** Field label. Rests inside the control and floats up into the border notch, like `Input`. */
+    label?: string;
+    /** Keep the label floating even when the field is empty and unfocused (default `false`). */
+    alwaysFloatLabel?: boolean;
+    /** Shown while nothing is selected. With a `label`, only once the label has floated clear. */
+    placeholder?: string;
+    /** Show a search box in the panel that filters the options (default `false`). */
+    searchable?: boolean;
+    /**
+     * Let the user add a value that isn't in `items` by typing it and picking the "add" row that
+     * appears. Implies `searchable`, since the search box is where the value is typed. The new
+     * value becomes its own key, so `onChange` reports it as a plain string.
+     */
+    allowCustomValues?: boolean;
+    /** Label for the row that adds a typed value (default `Add "…"`). */
+    createLabel?: (value: string) => string;
+    /** Placeholder for the search box (default `'Search…'`). */
+    searchPlaceholder?: string;
+    /** Text shown in the panel when no option matches (default `'No matches'`). */
+    emptyLabel?: string;
+    /** Cap the number of selections. Unselected options disable once the cap is reached. */
+    maxSelected?: number;
+    /** Show a button that clears the whole selection (default `true`). */
+    clearable?: boolean;
+    disabled?: boolean;
+    /** Show the selection but allow no changes, without the dimming `disabled` applies. */
+    readOnly?: boolean;
+    /** Where the panel opens: anchored to the control, as a bottom sheet, or a sheet only on a
+     * small touch screen. Forwarded to `Popover`. */
+    presentation?: Presentation;
+    formValidator?: FormValidator | null;
+    /** Manual error message shown in a tooltip (used when there's no `formValidator`). */
+    errorMessage?: string;
+    /** Manual valid state when not using a `formValidator` (default `true`). */
+    isValid?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<MultiSelectSlots>;
+    styles?: SlotStyles<MultiSelectSlots>;
+}

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

@@ -0,0 +1,2 @@
+export { default } from './pagination';
+export * from './pagination.types';

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

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { PaginationProps } from './pagination.types';
+declare function Pagination(props: PaginationProps): ReactElement | null;
+export default Pagination;

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

@@ -0,0 +1,30 @@
+import { CSSProperties } from 'react';
+import { IconContent } from '../types/icon.types';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
+export type PaginationSlots = 'root' | 'item' | 'control' | 'ellipsis';
+export interface PaginationProps extends Omit<HtmlProps<HTMLElement>, 'onChange'> {
+    /** Total number of pages. Nothing renders below `1`. */
+    total: number;
+    /** Controlled current page, 1-based (omit for uncontrolled). */
+    page?: number;
+    /** Initial page when uncontrolled (default `1`). */
+    defaultPage?: number;
+    onChange?: (page: number) => void;
+    /** Pages shown either side of the current one (default `1`). */
+    siblings?: number;
+    /** Pages always shown at the start and end (default `1`). */
+    boundaries?: number;
+    /** Show the previous/next controls (default `true`). */
+    showControls?: boolean;
+    /** Show first/last jump controls outside the previous/next ones (default `false`). */
+    showEdges?: boolean;
+    disabled?: boolean;
+    previousIcon?: IconContent;
+    nextIcon?: IconContent;
+    firstIcon?: IconContent;
+    lastIcon?: IconContent;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<PaginationSlots>;
+    styles?: SlotStyles<PaginationSlots>;
+}

package/dist/types/package/common/popover/usePopoverPosition.d.ts

@@ -17,7 +17,9 @@ export interface UsePopoverPositionArgs {
  * Positions a portaled, `position: fixed` popover on any of the four sides of its trigger with
  * start/center/end cross-axis alignment. Flips to the opposite side when the preferred one has no
  * room, shifts back on-screen along the cross axis, points the arrow at the trigger centre, and
- * hides (not closes) the panel once the trigger scrolls behind a clipping ancestor. Position is
- * written straight to the DOM via refs — going through setState lags the browser's scroll paint.
+ * hides (not closes) the panel once the trigger scrolls behind a clipping ancestor.
+ *
+ * `useAnchorTracking` supplies the lifecycle around this: mount wait, ancestor resolution, and
+ * re-running on scroll, viewport resize and panel size changes.
  */
 export declare function usePopoverPosition({ isOpen, placement, align, offset, triggerRef, floatingRef, panelRef, arrowRef, }: UsePopoverPositionArgs): void;

package/dist/types/package/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/package/common/tree/index.d.ts

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

package/dist/types/package/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/package/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/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/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

package/dist/types/package/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/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`