@ahrowe/ui 0.13.0 → 0.14.1

package/docs/KanbanBoard.md

@@ -34,22 +34,147 @@ const items: Record<string, Task> = {
   )}
   onChange={(updatedColumns) => setColumns(updatedColumns)}
 />
+
+// Restrict drag initiation to a handle — needed when a card contains its own
+// interactive controls (buttons, inputs), which would otherwise have their
+// clicks swallowed by the drag listener on the whole card
+<KanbanBoard
+  columns={columns}
+  items={items}
+  dragHandle
+  renderItem={(task, id) => (
+    <div className="task-card">
+      <span data-drag-handle>⠿</span>
+      <strong>{task.title}</strong>
+      <button onClick={() => deleteTask(id)}>Delete</button>
+    </div>
+  )}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Work-in-progress limit — shows a "count/max" badge on the column header and a
+// warning border once it's exceeded. Display-only: KanbanBoard doesn't block the
+// drop itself, so enforce a hard cap (if you want one) inside onChange, by simply
+// not calling setColumns when the destination column would go over its maxItems.
+const columnsWithLimit: KanbanColumnDef[] = [
+  { id: 'inprogress', title: 'In Progress', itemIds: ['task-3'], maxItems: 3 },
+];
+
+// Accessible labels for screen-reader drag announcements — defaults to the card's
+// id when omitted, so this is purely an upgrade for clearer narration
+<KanbanBoard
+  columns={columns}
+  items={items}
+  getItemLabel={(task) => task.title}
+  renderItem={(task, id) => (
+    <div className="task-card">
+      <strong>{task.title}</strong>
+    </div>
+  )}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Freeze a column — cards inside can't be picked up, and nothing can be dropped
+// into it. Use for a workflow rule like "cards in Done can't be moved back out."
+const columnsWithLock: KanbanColumnDef[] = [
+  { id: 'done', title: 'Done', itemIds: ['task-3'], disabled: true },
+];
+
+// Pin an individual card so it can't be dragged, independent of its column —
+// e.g. a task that's locked pending approval
+<KanbanBoard
+  columns={columns}
+  items={items}
+  getItemDisabled={(task) => task.locked === true}
+  renderItem={(task, id) => (
+    <div className="task-card">
+      <strong>{task.title}</strong>
+      {task.locked && <span>🔒</span>}
+    </div>
+  )}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Custom content for an empty column, instead of leaving it blank
+<KanbanBoard
+  columns={columns}
+  items={items}
+  renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
+  renderEmptyColumn={(column) => <span>No tasks in {column.title}</span>}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Custom actions in a column's header — an "add card" button, a column menu — laid
+// out next to the title (and the maxItems count badge, when both are present)
+<KanbanBoard
+  columns={columns}
+  items={items}
+  renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
+  renderColumnActions={(column) => (
+    <button onClick={() => addTaskTo(column.id)} aria-label={`Add task to ${column.title}`}>+</button>
+  )}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Let whole columns be reordered by dragging their header, alongside card dragging.
+// The same onChange receives the reordered columns array — no separate callback needed.
+<KanbanBoard
+  columns={columns}
+  items={items}
+  renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
+  reorderableColumns
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
+
+// Keep every column the same width regardless of card count — opt out of the
+// default shrink-when-empty behaviour
+<KanbanBoard
+  columns={columns}
+  items={items}
+  renderItem={(task) => <div className="task-card"><strong>{task.title}</strong></div>}
+  collapseEmptyColumns={false}
+  onChange={(updatedColumns) => setColumns(updatedColumns)}
+/>
 ```
 
+**Keyboard support:** cards are focusable and can be picked up and moved with the keyboard — Space or Enter to pick up, Space or Enter again to drop, Escape to cancel (reverts to the original position). Arrow keys move the card: Up/Down reorders within its current column; Left/Right moves it into the adjacent column, landing on the nearest card there (or the column itself, if it's empty). This uses a board-aware coordinate getter rather than `dnd-kit`'s generic `sortableKeyboardCoordinates`, which — across multiple per-column `SortableContext`s — can't reliably tell "next card in this column" from "some other column's droppable" and ends up mixing up Up/Down and Left/Right. With `reorderableColumns`, a column's header is focusable the same way — Space/Enter to pick it up, Left/Right to move it, Up/Down does nothing (columns are a single row).
+
+**Column reordering (`reorderableColumns`):** a column's header becomes its drag handle for moving the whole column — dragging the cards area still only moves cards. This shares the same `DndContext` as card dragging (mouse, touch, and keyboard all work the same way), and commits through the same `onChange` — a column move is just a reordering of the `columns` array, same as any other change.
+
+**Screen-reader announcements:** every pick-up, hover, drop, and cancel is announced (e.g. "Picked up card Design mockup.", "Card Design mockup is over the In Progress column."). By default cards are announced by their id — pass `getItemLabel` to announce something meaningful instead (a title, a short description).
+
 **KanbanBoardProps:**
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `columns` | `KanbanColumnDef[]` | Column definitions with `id`, `title`, `itemIds` |
+| `columns` | `KanbanColumnDef[]` | Column definitions with `id`, `title`, `itemIds`, optional `maxItems` |
 | `items` | `Record<string, T>` | Flat map of all items keyed by id |
 | `renderItem` | `(item: T, id: string) => ReactNode` | Render function for each item |
-| `onChange` | `(columns: KanbanColumnDef[]) => void` | Called after every drop — replace state with this value |
+| `onChange` | `(columns: KanbanColumnDef[]) => void` | Called after a drop that actually changes column or order — replace state with this value |
+| `dragHandle` | `boolean` | Restrict drag initiation to elements marked `data-drag-handle` within a card, instead of the whole card. Use when `renderItem` includes interactive content |
+| `getItemLabel` | `(item: T, id: string) => string` | Accessible label for a card, used in screen-reader drag announcements. Defaults to the card's id |
+| `getItemDisabled` | `(item: T, id: string) => boolean` | Returns whether a specific card can't be picked up. Defaults to every card being draggable; independent of a column's own `disabled`. A pinned card stays a valid drop target — other cards can still be reordered before/after it, unlike a card inside a fully frozen (`disabled`) column |
+| `renderEmptyColumn` | `(column: KanbanColumnDef) => ReactNode` | Custom content shown inside a column when it has no cards, instead of leaving it blank |
+| `renderColumnActions` | `(column: KanbanColumnDef) => ReactNode` | Custom actions rendered in a column's header, next to its title (e.g. an "add card" button, a column menu) |
+| `reorderableColumns` | `boolean` | Allow whole columns to be reordered by dragging their header, alongside card dragging (default `false`) |
+| `collapseEmptyColumns` | `boolean` | Shrink a column to a narrow strip once it has no cards (default `true`). Set `false` to keep every column the same width regardless of card count. The collapsed width is set via `--kanban-empty-column-width` (falls back to `140px`) — override it theme-wide via `ThemeProvider`, or per board via `style` |
+| `id` / `role` / `aria-*` / `data-*` | | Passed through to the root element |
+
+`KanbanColumn`'s own props accept the same `id` / `role` / `aria-*` / `data-*` pass-through on its root element.
 
 **KanbanColumnDef:**
 
 ```ts
-{ id: string; title: string; itemIds: string[] }
+{
+  id: string;
+  title: string;
+  itemIds: string[];
+  maxItems?: number; // work-in-progress limit — display-only, see above
+  disabled?: boolean; // freezes the column — cards inside can't be dragged, nothing can drop in
+}
 ```
 
+**Note on item ids:** don't give a card an id starting with `column-` — the board uses that prefix internally to identify a column's own droppable (the empty space above/below its cards) versus a specific card. A colliding card id is silently misread as a column reference, and drops involving it silently no-op instead of throwing, so the bug can be easy to miss.
+
 **Slots (KanbanBoard):** `dragOverlay`  
-**Slots (KanbanColumn):** `header` `items`
+**Slots (KanbanColumn):** `header` `items` `count` (the `count/maxItems` badge, only rendered when `maxItems` is set) `placeholder` (the `renderEmptyColumn` wrapper, only rendered when the column has no cards and `renderEmptyColumn` is set) `actions` (the `renderColumnActions` wrapper, only rendered when `renderColumnActions` is set)

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/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.13.0",
+  "version": "0.14.1",
   "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 $INIT_CWD process.argv",
+    "gc": "bash src/scripts/generateComponent.sh",
     "changeset": "changeset",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -84,7 +84,6 @@
     "@mona-health/react-input-mask": "^3.0.3",
     "classnames": "^2.5.1",
     "downshift": "^9.3.3",
-    "prop-types": "^15.8.1",
     "react-number-format": "^5.4.5",
     "zod": "^4.4.3"
   },
@@ -101,7 +100,6 @@
     "@types/node": "^25.9.1",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
-    "@types/react-helmet": "^6.1.11",
     "@types/react-syntax-highlighter": "^15.5.13",
     "@vitejs/plugin-react": "^6.0.2",
     "@vitest/ui": "^4.1.7",