@ahrowe/ui 0.12.0 → 0.14.0

package/docs/Divider.md

@@ -1,13 +1,15 @@
 # Divider
 
-**When to use:** A horizontal rule that fills the width of its parent — separating sections of content. Optionally label it with text (e.g. "OR", a date, a section name); the line splits around the text, leaving a gap for it.
+**When to use:** A rule that separates sections of content — horizontal by default, filling the width of its parent. Optionally label it with text (e.g. "OR", a date, a section name); the line splits around the text, leaving a gap for it. Set `orientation` to `Vertical` for a vertical line filling the height of its parent instead, e.g. as a separator between two buttons in a `ButtonGroup`.
 
-**Import:** `import { Divider, DividerTextPosition } from '@ahrowe/ui'`
+**Import:** `import { Divider, DividerTextPosition, DividerOrientation } from '@ahrowe/ui'`
 
 **Text position:** `DividerTextPosition.Left` | `DividerTextPosition.Center` (default) | `DividerTextPosition.Right`
 
+**Orientation:** `DividerOrientation.Horizontal` (default) | `DividerOrientation.Vertical`
+
 ```tsx
-import { Divider, DividerTextPosition } from '@ahrowe/ui';
+import { Divider, DividerTextPosition, DividerOrientation } from '@ahrowe/ui';
 
 // Plain line
 <Divider />
@@ -20,6 +22,13 @@ import { Divider, DividerTextPosition } from '@ahrowe/ui';
 
 // Text near the right edge
 <Divider text="March 2026" textPosition={DividerTextPosition.Right} />
+
+// Vertical — fills the height of its (flex/grid) parent, e.g. between two buttons
+<ButtonGroup>
+  <Button>Save</Button>
+  <Divider orientation={DividerOrientation.Vertical} />
+  <Button>Save & new</Button>
+</ButtonGroup>
 ```
 
 **Key props:**
@@ -28,6 +37,9 @@ import { Divider, DividerTextPosition } from '@ahrowe/ui';
 |------|------|-------------|
 | `text` | `ReactNode` | Text (or any node) rendered on the line. Omit for a plain full-width line |
 | `textPosition` | `DividerTextPosition` | Where `text` sits along the line (default `Center`) |
+| `orientation` | `DividerOrientation` | `Horizontal` (default, fills width) or `Vertical` (fills height) |
 | `className` / `style` | | Root element |
 
+**Vertical orientation:** stretches to fill the height of a flex or grid parent (`align-self: stretch`), the same way `Button`s in a `ButtonGroup` do. Outside a flex/grid context, give it an explicit height via `style`, since a vertical line has no natural height of its own the way a horizontal one has a natural width (`100%` of its block-level parent).
+
 **Slots:** `root` `line` (the line segment(s) either side of `text`) `content` (the `text` wrapper)

package/docs/FloatingMenu.md

@@ -29,7 +29,9 @@ import { FloatingMenu, Align } from '@ahrowe/ui';
   <ActionIcon icon={faEllipsis} />
 </FloatingMenu>
 
-// Keep open when clicking inside content
+// Keep open through several interactions with content — a column-visibility toggle where
+// checking one box shouldn't close the whole menu — or when re-clicking the trigger itself
+// (e.g. DatePicker re-clicking its own input) shouldn't close it either
 <FloatingMenu dontCloseOnChildClick content={<Form />}>
   <button>Open form</button>
 </FloatingMenu>
@@ -46,8 +48,10 @@ import { FloatingMenu, Align } from '@ahrowe/ui';
 | `align` | `Align` | Popover alignment relative to trigger |
 | `isOpen` | `boolean` | Controlled open state |
 | `onOpenChange` | `(isOpen: boolean) => void` | Open state change callback |
-| `dontCloseOnChildClick` | `boolean` | Prevent close when clicking inside content |
+| `dontCloseOnChildClick` | `boolean` | Keep the menu open when its own content is clicked, and when the trigger itself is re-clicked while already open (default `false`) |
 
 **Slots:** `root` `trigger` `menu` `menuContainer`
 
-**Nested overlays in `content`:** a click anywhere inside `content` never closes the menu on its own — including inside a nested overlay that renders through its own portal (e.g. a `Dropdown` or another `FloatingMenu` used inside `content`), even though that overlay's DOM lives outside `content`'s own subtree. Closing on a selection is opt-in: have the handler that reacts to the selection call `onOpenChange(false)` (or your own state setter) explicitly, the way a calendar's day-selection handler would, while a nested month/year `Dropdown` inside the same menu is left alone.
+**Closing behaviour:** by default, clicking anywhere in `content` closes the menu — including inside a nested overlay that renders through its own portal (e.g. a `Dropdown` or another `FloatingMenu` used inside `content`), even though that overlay's DOM lives outside `content`'s own subtree. Re-clicking the trigger while open is a clean toggle: it closes the menu (unless `dontCloseOnChildClick` is set, in which case it's a no-op — the trigger owns its own open/close entirely, so it never fights with an outside-click check). Set `dontCloseOnChildClick` when `content` needs several interactions before the user is done (a multi-checkbox toggle, a color picker's slider, a calendar) — the consumer is then responsible for closing explicitly, e.g. calling `onOpenChange(false)` from the handler that reacts to a final selection.
+
+**Keyboard:** the menu is portaled to the end of the DOM, so Tab can't reach it in visual order on its own. When `content` has real focusable elements, Escape closes the menu and returns focus to the trigger; Tab past the last focusable element (or Shift+Tab past the first) closes the menu and continues focus as if it sat right after the trigger. This doesn't include auto-focusing the first element on open — content ranges from menus to live controls (e.g. `ColorPicker`'s hue slider), where grabbing focus on open would let a stray arrow-key press change a value the user never touched. A consumer that wants that (like `SplitButton` focusing its first enabled action) implements it itself.

package/docs/Input.md

@@ -17,14 +17,13 @@ const emailValidator = new FormValidator('', [Validators.required(), Validators.
 // Password
 <Input label="Password" type={InputType.Password} value={pw} onChange={setPw} />
 
-// Search with clear button
+// Search — clear button appears automatically once there's a value, and clears itself;
+// onClearClicked is optional, only needed to react to the clear beyond the value itself
 <Input
   type={InputType.Search}
   label="Search"
   value={query}
   onChange={setQuery}
-  showCancel
-  onClearClicked={() => setQuery('')}
 />
 
 // Multiline (textarea)
@@ -38,10 +37,34 @@ const emailValidator = new FormValidator('', [Validators.required(), Validators.
 
 // Row layout
 <Input label="Name" isRow value={name} onChange={setName} />
+
+// Custom icon on the left instead of the default right — the field's padding, the material
+// label (resting and floated), and the native placeholder all shift out of its way automatically
+<Input
+  label="Search"
+  icon={<FontAwesomeIcon icon={faMagnifyingGlass} />}
+  iconPosition={InputIconPosition.Left}
+  value={query}
+  onChange={setQuery}
+/>
+
+// A decorative type icon (Email/Phone/Edit) on the left, no custom icon needed
+<Input label="Email" type={InputType.Email} iconPosition={InputIconPosition.Left} />
+
+// A custom icon replaces Email's built-in envelope outright — there's nothing functional to lose
+<Input label="Email" type={InputType.Email} icon={<FontAwesomeIcon icon={faAt} />} />
 ```
 
 **InputType enum:** `Edit` | `Phone` | `Email` | `Iban` | `Date` | `HasNoIcon` | `Search` | `Password`
 
+**InputIconPosition enum:** `Left` | `Right` — which side the input's icon renders on, whichever icon is currently showing (built-in type icon or custom `icon`). Defaults to `Left` for `Email`/`Phone`/`Search` once `useMatLabelStyle` is off (their historical placement), `Right` otherwise; pass it explicitly to move any type's icon to either side regardless of `useMatLabelStyle`.
+
+**Custom icon vs. built-in type icon:** passing `icon` alongside a decorative type (`Edit`, `Phone`, `Email`) replaces that type's built-in icon outright, since there's nothing functional attached to it to lose. `Search` and `Password` ignore `icon` — their icon is functional (clear button, show/hide toggle), not decorative, so it always renders regardless of whether `icon` is set.
+
+**Search clear icon:** `InputType.Search` shows a magnifying glass that animates into a clear (×) button once the field has a value, rather than the browser's own native search-cancel decoration, which is suppressed so it doesn't clash with the theme.
+
+**Mobile keyboard layout:** `Email`, `Phone`, and `Search` each set the matching `inputMode` (`email` / `tel` / `search`), so mobile browsers show the right on-screen keyboard — an `@`-and-`.com` layout for email, a numeric dial pad for phone, a "Go"/search action key for search. `Email`'s native `type` is deliberately left as `text` rather than `email`, to avoid the browser's own "please match the requested format" validation UI fighting the `formValidator`-driven error tooltip this component already shows — `inputMode="email"` alone is enough to get the correct keyboard. Pass `inputMode` directly to override the computed default for any other case.
+
 **Key props:**
 
 | Prop | Type | Description |
@@ -58,12 +81,13 @@ const emailValidator = new FormValidator('', [Validators.required(), Validators.
 | `rows` | `number` | Textarea row count |
 | `autoResize` | `boolean` | Textarea grows with content |
 | `suffix` | `string \| ReactNode` | Right-side suffix |
-| `icon` | `ReactElement` | Custom icon element, positioned absolute on the right (the field is padded to match); clickable via `onIconClick` |
+| `icon` | `ReactElement` | Custom icon, positioned absolute on the side set by `iconPosition`; clickable via `onIconClick`. Replaces the built-in icon for `Edit`/`Phone`/`Email`; ignored for `Search`/`Password` (see below) |
+| `iconPosition` | `InputIconPosition` | Side the input's icon renders on — built-in or custom, whichever is showing (see enum above for the default). On the left, the material label (resting and floated) and the fieldset notch shift right to clear it too |
 | `onIconClick` | `() => void` | Click handler for the custom `icon` |
 | `upperRightLabel` | `string \| ReactNode` | Small label above right |
-| `showCancel` | `boolean` | Show clear icon when focused |
+| `showCancel` | `boolean` | Show clear icon when focused (ignored for `InputType.Search`, which always shows it once there's a value — see below) |
 | `alwaysShowCancel` | `boolean` | Always show clear icon |
-| `onClearClicked` | `() => void` | Clear button handler |
+| `onClearClicked` | `() => void` | Called after the clear button clears the value. Optional — clicking clear always empties the field itself, whether or not this is set |
 | `isRow` | `boolean` | Horizontal layout |
 | `labelInBorder` | `boolean` | Label inside fieldset border |
 | `alwaysFloatLabel` | `boolean` | Keep the material label floated in the border notch even when empty and unfocused, so an empty field reads as blank instead of showing the label as if it were a value. Only applies with `useMatLabelStyle` (default) |

package/docs/NumberInput.md

@@ -55,3 +55,5 @@ const priceValidator = new FormValidator<number | undefined>(undefined, [Validat
 | `readOnly` | `boolean` | Make the field read-only — typing is blocked, and the arrow steppers (`showArrows`) and ↑/↓ keys are disabled. Default: `false` |
 | `placeholder` | `string` | |
 | `error` | `string` | Manual error message |
+
+**Mobile keyboard layout:** shows the numeric on-screen keyboard automatically (`inputMode="numeric"` when `decimalScale={0}`, `"decimal"` otherwise, so a decimal separator key is available whenever fractional values are allowed). Pass `inputMode` directly to override.

package/docs/Rating.md

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

package/docs/SearchInput.md

@@ -33,6 +33,12 @@ import { SearchInput } from '@ahrowe/ui';
 />
 ```
 
+**Theming:** override theme-wide via `ThemeProvider`'s `variables`; no built-in fallback, so it's unset in the default theme until set:
+
+| Variable | Falls back to |
+|----------|---------------|
+| `--search-input-color` | *(none — unset by default)* |
+
 **Key props:**
 
 | Prop | Type | Description |

package/docs/SplitButton.md

@@ -0,0 +1,79 @@
+# SplitButton
+
+**When to use:** A primary action button with a small attached dropdown for closely related secondary actions, e.g. "Save ▾" opening "Save as draft" / "Save and close". Built from `Button`, `ButtonGroup`, and `FloatingMenu` internally, rather than a mechanism of its own.
+
+**Import:** `import { SplitButton } from '@ahrowe/ui'`
+**Types:** `import type { SplitButtonAction, SplitButtonProps } from '@ahrowe/ui'`
+
+**Requires:** `<div id="bodyEnd"></div>` in your HTML (the actions menu renders via `FloatingMenu`, which portals).
+
+```tsx
+import { SplitButton } from '@ahrowe/ui';
+import type { SplitButtonAction } from '@ahrowe/ui';
+
+const actions: SplitButtonAction[] = [
+  { id: 'draft', label: 'Save as draft', onClick: () => saveDraft() },
+  { id: 'close', label: 'Save and close', onClick: () => saveAndClose() },
+];
+
+<SplitButton actions={actions} onClick={() => save()}>
+  Save
+</SplitButton>
+
+// Destructive style, matching Button's own style variants
+import { ButtonStyleType } from '@ahrowe/ui';
+
+<SplitButton
+  actions={[{ id: 'archive', label: 'Archive instead', onClick: () => archive() }]}
+  styleType={ButtonStyleType.Delete}
+  onClick={() => deleteItem()}
+>
+  Delete
+</SplitButton>
+
+// A disabled action within the menu
+<SplitButton
+  actions={[
+    { id: 'draft', label: 'Save as draft', onClick: () => saveDraft() },
+    { id: 'archive', label: 'Archive instead', onClick: () => archive(), disabled: true },
+  ]}
+  onClick={() => save()}
+>
+  Save
+</SplitButton>
+
+// Loading / disabled — both the primary and trigger button reflect the state
+<SplitButton actions={actions} onClick={() => save()} isLoading>
+  Save
+</SplitButton>
+<SplitButton actions={actions} onClick={() => save()} disabled>
+  Save
+</SplitButton>
+```
+
+**SplitButtonAction:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `string` | Stable key for the action |
+| `label` | `ReactNode` | Text shown in the dropdown |
+| `onClick` | `() => void` | Called when the action is picked; the dropdown closes automatically afterward |
+| `disabled` | `boolean` | Dims the action and prevents it from firing |
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | The primary button's label |
+| `onClick` | `(event) => void \| Promise<void>` | The primary button's click handler |
+| `actions` | `SplitButtonAction[]` | Secondary actions shown in the dropdown |
+| `styleType` | `ButtonStyleType` | Visual variant, shared by both the primary and trigger button (default `Primary`) |
+| `size` | `ButtonSize` | Size variant, shared by both buttons |
+| `disabled` | `boolean` | Disables both the primary and trigger button |
+| `isLoading` | `boolean` | Shows a spinner on the primary button (same as `Button`'s own `isLoading`) |
+
+**`isLoading` vs. `disabled`:** `isLoading` only affects the primary button — the trigger and its menu stay usable while the primary action is in flight, e.g. to cancel via a menu action. To lock the whole control during the async action instead, pass both: `isLoading={isSaving} disabled={isSaving}`. Setting `disabled` also closes the menu if it happened to be open already, and blocks any in-flight click on a menu action.
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ SplitButton: { styleType: ButtonStyleType.Default } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `primaryButton` `triggerButton` `menu` `menuItem`

package/docs/VirtualList.md

@@ -58,7 +58,7 @@ const columns: VirtualListColumn<User>[] = [
 <VirtualList
   items={items}
   columns={columns}
-  onLoadMore={async () => { await fetchNextPage(); }}
+  onLoadMore={hasMore ? async () => { await fetchNextPage(); } : undefined}
   isLoading={isInitialLoading}
   height="100%"
 />
@@ -123,6 +123,7 @@ const columns: VirtualListColumn<User>[] = [
 | `rowGap` | `number \| string` | Gap between rows — number = px; string = any CSS length (`'1em'`, `'var(--spacing-s)'`). Default `0` |
 | `rowPadding` | `number \| string` | Padding on every row — number = px; string = any CSS padding value (`'8px 12px'`, `'var(--spacing-s)'`) |
 | `showDivider` | `boolean` | Row divider lines (default `true`) |
+| `rowHover` | `boolean` | Highlight rows on hover (default `true`). Set `false` when the row content brings its own hover affordance (e.g. a `Card` per row) so the two don't fight |
 | `getItemKey` | `(item, index) => string \| number` | Stable key per item |
 | `selectedKey` | `string \| number \| null` | Controlled single-select key |
 | `onRowClick` | `(item, index) => void` | Row click handler |
@@ -132,10 +133,13 @@ const columns: VirtualListColumn<User>[] = [
 | `showColumnToggle` | `boolean` | Show gear button to show/hide columns (default `true` when columns present) |
 | `visibleColumnKeys` | `string[]` | Controlled visible column keys |
 | `onVisibleColumnsChange` | `(keys) => void` | Column visibility change callback |
-| `onLoadMore` | `() => Promise<void>` | Triggered near the bottom — append items in the handler |
+| `persistColumnsKey` | `string` | Save column visibility to `localStorage` under this key and restore it on the next mount of a list using the same key. Uncontrolled mode only (ignored alongside `visibleColumnKeys`); columns added since the settings were saved fall back to their `defaultHidden` |
+| `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 |
 
+Drag-and-drop reordering adds `reorderable`, `treeReorder`, `dragHandle`, and their callbacks — see **Row reordering** below.
+
 **Imperative handle (`ref`):**
 
 Pass a `ref` typed as `VirtualListHandle` to control the list imperatively:
@@ -160,6 +164,85 @@ listRef.current?.scrollToKey(user.id, { align: 'center' });
 | `getScrollElement` | `() => HTMLDivElement \| null` | The underlying scroll container, for advanced use |
 | `recalculateColumns` | `() => void` | Re-measure `fit` columns on the next layout. Only needed after an out-of-band content change that doesn't flow through a new `items` array or `columns` set — those re-measure automatically, as does content first appearing in a cell |
 
-**Slots:** `root` `header` `headerCell` `headerToggle` `togglePopover` `toggleItem` `body` `row` `cell` `selectCell` `loadingIndicator`
+**Row reordering:** two modes, both drag-and-drop, both mouse and touch. Set exactly one:
+
+- **`reorderable`** — flat reorder. Rows move **live** as you drag, so `onReorder` fires repeatedly and you apply each move immediately.
+- **`treeReorder`** — drop `before`, `after`, or `inside` another row. Rows do **not** move during the drag; a drop indicator is shown and `onTreeDrop` fires **once** on release.
+
+If both are set, `treeReorder` wins. In either mode, pass `getItemKey` so rows keep their measured heights across the reorder.
+
+```tsx
+// Flat: onReorder fires live, on every position change
+const [rows, setRows] = useState(initialRows);
+
+<VirtualList
+  items={rows}
+  renderRow={(row) => <div>{row.label}</div>}
+  getItemKey={(row) => row.id}
+  reorderable
+  onReorder={(from, to) => setRows((prev) => move(prev, from, to))}
+  height={400}
+/>
+```
+
+The list is always a flat array, including in tree mode. Keep the real tree in your own state, flatten the expanded nodes into `items` tagging each with its depth, and re-flatten after applying a drop:
+
+```tsx
+// Tree: onTreeDrop fires once, on release
+<VirtualList
+  items={flattenedRows}                        // each row carries its own depth
+  renderRow={(row) => (
+    <div style={{ paddingLeft: row.depth * 24 }}>
+      <span data-drag-handle>⠿</span>
+      {row.label}
+    </div>
+  )}
+  getItemKey={(row) => row.id}
+  getItemDepth={(row) => row.depth}
+  isGroup={(row) => row.hasChildren}           // only groups offer an `inside` drop
+  treeReorder
+  dragHandle
+  treeIndentPx={24}                            // match the row content's per-level padding
+  onTreeDrop={(dragKey, target) => applyDrop(dragKey, target)}
+  height={400}
+/>
+```
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `reorderable` | `boolean` | Flat drag-to-reorder. The whole row is draggable unless `dragHandle` is set |
+| `onReorder` | `(fromIndex, toIndex) => void` | Fires **live** during a flat drag, once per position change. Apply it straight away |
+| `treeReorder` | `boolean` | Tree drag-and-drop: `before` / `after` / `inside` drops instead of a flat move. Wins over `reorderable` |
+| `onTreeDrop` | `(dragKey, target: TreeDropTarget) => void` | Fires **once** on release. Never called when the target is the dragged node itself or one of its descendants |
+| `getItemDepth` | `(item, index) => number` | Each row's depth in the tree, `0` = root (default `0` for every row). Aligns the drop indicator and blocks dropping a node into its own subtree |
+| `isGroup` | `(item, index) => boolean` | Whether a row can take children, i.e. whether hovering its middle third offers an `inside` drop (default `false`, leaf) |
+| `treeIndentPx` | `number` | Px per depth level used to indent the `before`/`after` drop line so it lines up with where the dropped content starts (default `24`) |
+| `dragHandle` | `boolean` | Only elements marked `data-drag-handle` start a drag, instead of the whole row. Applies to both modes, mouse and touch |
+| `longPressDelay` | `number` | Touch only: press-and-hold duration in ms before drag mode arms, so a normal swipe still scrolls (default `400`) |
+
+**`TreeDropTarget`** (`import type { TreeDropTarget, TreeDropPosition } from '@ahrowe/ui'`):
+
+```ts
+interface TreeDropTarget {
+  key: string | number;                          // getItemKey of the row dropped on
+  position: 'before' | 'inside' | 'after';       // TreeDropPosition
+}
+```
+
+`before`/`after` place the dragged node as a sibling at the target's depth; `inside` makes it a child (only offered when `isGroup` is true for that row).
+
+**Use `dragHandle` for rows containing inputs or other interactive controls.** Without it the whole row is draggable, which swallows clicking, typing, and text selection inside those controls. Render a handle in the row yourself and mark it: `<span data-drag-handle>⠿</span>`. With `dragHandle` the grab cursor is yours to style on the handle; without it, the list puts it on the whole row.
+
+**Touch:** a press-and-hold of `longPressDelay` lifts a floating copy of the row that follows your finger, with auto-scroll near the list's top and bottom edges. A swipe before the hold completes scrolls the list as normal instead of starting a drag. With `dragHandle`, only a press that starts on the handle arms it, so the rest of the row stays tappable.
+
+**Lazy loading:** `onLoadMore` fires when the user scrolls within `loadMoreThreshold` px of the bottom, **and** repeatedly whenever the rows don't fill the list's viewport. That second trigger matters because a list shorter than its own height can't be scrolled at all, so a first batch smaller than the viewport would otherwise be the last batch ever loaded. The list keeps asking for pages until the content overflows; each row count is asked at most once, so the loop ends as soon as a call appends nothing. Gate the prop on your own "has more" flag to skip even that last probe:
+
+```tsx
+<VirtualList items={items} onLoadMore={hasMore ? loadNextPage : undefined} height={600} />
+```
+
+This needs the list to have a **bounded height** (the default `height="100%"` inside a sized parent, or an explicit `height`). With a height that grows with its content, there is no empty space to detect and only the scroll trigger applies. Nothing fires while `isLoading` is set, and only one load runs at a time.
+
+**Slots:** `root` `header` `headerCell` `headerToggle` `togglePopover` `toggleItem` `body` `row` `cell` `selectCell` `loadingIndicator` `dropIndicator` `columnChip`
 
 **In-row popovers:** Rows support inline popover content that overflows the row's bottom edge — e.g. a `Dropdown`, `InputDropdown`, `Tooltip`, or `FloatingMenu` whose list opens below its trigger. All four render their popover through a `BodyEnd` portal and track their trigger's position directly, so they always escape row/cell clipping and paint above the rows below, regardless of focus — no special CSS is needed on the row or cell for this. Cells still clip their own content by default (ellipsis / neighbour-spill guard); that's unaffected. This works in both list mode (`renderRow`) and table mode (`columns`). Stop the row's click handler from firing when interacting with the control (`onClick={(e) => e.stopPropagation()}` on the cell) if the row is also selectable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "publishConfig": {
     "access": "public"
   },