@ahrowe/ui 0.26.0 → 0.28.0

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/RoomDrawer.md

@@ -47,6 +47,19 @@ const [plan, setPlan] = useState<FloorPlan>(() => emptyFloorPlan());
 - an opening slides along its wall
 - a room moves every corner it owns
 
+**Hold Ctrl/Cmd while dragging a wall to detach it instead.** The wall comes off the
+corners it shares, the neighbours keep their ends, and a connecting wall grows between
+each old corner and the new one. Use it when a partition joins the wall being moved: a
+plain drag takes the partition's end along with it, a detach drag leaves it where it is.
+
+Pulling a wall off a plain corner is deliberately a no-op on the drawing: the connector
+continues the wall that was already there, so the seam it leaves is straight and is
+dissolved on the spot. Nothing is detached until the wall has moved at least one grid
+step, so a Ctrl-click on a wall is still just a selection toggle. Push the wall back onto
+the line it came off and the corners weld back together, whether that happens in the same
+drag or a later one — the corner that survives is the one that was already there.
+Grabbing a selected wall's midpoint handle always adds a corner, Ctrl or not.
+
 ## Measuring without drawing
 
 The `measure` tool is a ruler. Drag it across the plan and it reports length and angle, snapping to corners, walls and the grid like everything else, with `Shift` for a fixed angle.
@@ -127,6 +140,7 @@ The `snap`, `angleLock` and `showGrid` props seed the toggles; changing one rese
 | `S` / `L` / `G` | Toggle snapping / angle lock / grid |
 | `Ctrl/Cmd+A` | Select everything |
 | `Ctrl/Cmd`-click | Add or remove one thing from the selection |
+| `Ctrl/Cmd`-drag a wall | Detach it from its corners instead of dragging them along |
 | `Shift` (hold) | Momentarily invert angle lock |
 | `Alt` (hold) | Momentarily invert snapping |
 | `Esc` | Cancel the wall chain, or clear the selection |

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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "publishConfig": {
     "access": "public"
   },
@@ -55,7 +55,7 @@
     "build:mcp": "vite build --config vite.mcp.config.ts",
     "preview": "vite preview",
     "gen-barrel": "tsx scripts/gen-barrel.ts",
-    "gc": "bash src/scripts/generateComponent.sh",
+    "gc": "tsx scripts/generate-component.ts",
     "changeset": "changeset",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -101,6 +101,7 @@
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
     "@types/react-syntax-highlighter": "^15.5.13",
+    "@types/three": "^0.186.0",
     "@vitejs/plugin-react": "^6.0.2",
     "@vitest/ui": "^4.1.7",
     "eslint": "^9.39.4",
@@ -118,6 +119,7 @@
     "react-dom": "^19.2.6",
     "react-element-to-jsx-string": "^17.0.1",
     "react-syntax-highlighter": "^16.1.1",
+    "three": "^0.186.0",
     "tsx": "^4.22.3",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.0",