@ahrowe/ui 0.30.0 → 0.31.0

package/docs/VirtualList.md

@@ -1,11 +1,11 @@
 # VirtualList
 
-**When to use:** Efficiently render large lists or tables — thousands of rows rendered with a virtualised scroll window so only visible rows are in the DOM. Supports column definitions, row selection, multi-select, column visibility toggling, and infinite scroll.
+**When to use:** Efficiently render large lists or tables — thousands of rows rendered with a virtualised scroll window so only visible rows are in the DOM. Supports column definitions, row selection, multi-select, column sorting, column resizing, column visibility toggling, and infinite scroll.
 
-**Keywords:** data table, virtualized table
+**Keywords:** data table, virtualized table, sort, sorting, order by, ascending, descending, column header click, resize, resizable, drag column edge, column width, autofit
 
 **Import:** `import { VirtualList } from '@ahrowe/ui'`  
-**Types:** `import type { VirtualListProps, VirtualListColumn, VirtualListHandle } from '@ahrowe/ui'`
+**Types:** `import type { VirtualListProps, VirtualListColumn, VirtualListHandle, VirtualListSort } from '@ahrowe/ui'`
 
 **Requires:** `<div id="bodyEnd"></div>` in your app **only if** you use the column-visibility toggle (the gear menu) — its popover is a `FloatingMenu` that renders via portal. Lists without columns, or with `showColumnToggle={false}`, don't need it.
 
@@ -96,6 +96,11 @@ const columns: VirtualListColumn<User>[] = [
 | `toggleLabel` | `ReactNode` | Text shown for this column in the gear menu, overriding `label`. Use for columns with an empty header (e.g. an actions column) so their menu entry isn't blank |
 | `lockVisible` | `boolean` | Column can't be hidden — always visible (overrides `defaultHidden` and any controlled/persisted state), shown checked and disabled in the gear menu |
 | `hideFromToggle` | `boolean` | Omit the column from the gear menu entirely (no entry). Visibility otherwise follows `defaultHidden`/controlled/persisted state; combine with `lockVisible` to keep it always visible and out of the menu. The gear button hides automatically when no column is left to toggle |
+| `sortValue` | `(item) => string \| number \| boolean \| Date \| null \| undefined` | Makes the column sortable **and** lets the list sort `items` itself by this value |
+| `compare` | `(a, b) => number` | Ascending comparator for an order `sortValue` can't express. Also makes the column sortable, and wins over `sortValue` |
+| `sortable` | `boolean` | Makes the header clickable without the list reordering anything: the sort is only reported through `onSortChange`. For server-side / paginated sorting. Ignored when `sortValue` or `compare` is set |
+| `minWidth` | `number` | Floor this column can be dragged to, in px (default `48`) |
+| `resizable` | `boolean` | Set `false` to opt this column out while the list has `resizableColumns` |
 
 ```tsx
 // An actions column: no header, always visible, labelled "Actions" in the gear menu
@@ -120,7 +125,7 @@ const columns: VirtualListColumn<User>[] = [
 | `renderRow` | `(item, index) => ReactNode` | Row render fn — list mode (no columns) |
 | `columns` | `VirtualListColumn<T>[]` | Column definitions — enables table/header mode |
 | `height` | `number \| string` | Scroll viewport height (default `'100%'`) |
-| `estimatedRowHeight` | `number` | Estimated row height before measurement (default `40`) |
+| `estimatedRowHeight` | `number` | Row height assumed before anything has been measured (default `40`). Once rows have been measured, their average is used for the ones that haven't, so this only has to be roughly right |
 | `overscan` | `number` | Extra rows rendered outside the viewport (default `3`) |
 | `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)'`) |
@@ -128,10 +133,18 @@ const columns: VirtualListColumn<User>[] = [
 | `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 |
+| `onRowClick` | `(item, index) => void` | Row click handler, also fired by `Enter` on the active row |
+| `keyboardNavigation` | `boolean` | Arrow-key navigation over the rows (default `true`). See **Keyboard** |
 | `multiSelect` | `boolean` | Enable checkbox multi-select column |
 | `selectedKeys` | `Set<string \| number>` | Controlled multi-select keys |
 | `onSelectionChange` | `(keys) => void` | Multi-select change callback |
+| `sort` | `VirtualListSort \| null` | Controlled sort. `null` is source order |
+| `defaultSort` | `VirtualListSort \| null` | Initial sort, uncontrolled (default `null`) |
+| `onSortChange` | `(sort) => void` | Fires on every header click with the next step of the cycle |
+| `resizableColumns` | `boolean` | Let the user drag column edges to resize (see **Column resizing**) |
+| `columnWidths` | `Record<string, number>` | Controlled column widths in px, keyed by column key |
+| `onColumnWidthsChange` | `(widths) => void` | Called with the full width map after every resize or auto-fit |
+| `resetColumnWidthsLabel` | `ReactNode` | Text of the gear-menu reset entry (default `'Reset column widths'`) |
 | `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 |
@@ -143,6 +156,108 @@ const columns: VirtualListColumn<User>[] = [
 
 Drag-and-drop reordering adds `reorderable`, `treeReorder`, `dragHandle`, and their callbacks — see **Row reordering** below.
 
+**Sorting:** a column becomes sortable as soon as it carries `sortValue`, `compare` or `sortable`. Its header turns into a button that cycles ascending, descending, unsorted, and carries `aria-sort` for screen readers.
+
+Who reorders the data is the column's decision:
+
+- **`sortValue` / `compare`**: the list sorts `items` itself. For data you hold in full, in memory.
+- **`sortable`**: the list only reports the click through `onSortChange` and never touches `items`. Use this whenever the rows are paginated or fetched per sort (`onLoadMore`), where sorting the rows loaded so far would silently order part of the data.
+
+```tsx
+// Sorted by the list
+const columns: VirtualListColumn<User>[] = [
+  { key: 'name', label: 'Name', width: { type: 'flex' }, renderCell: (u) => u.name, sortValue: (u) => u.name },
+  { key: 'joined', label: 'Joined', width: { type: 'fit' }, renderCell: (u) => u.joined, sortValue: (u) => new Date(u.joined) },
+];
+
+<VirtualList items={users} columns={columns} defaultSort={{ key: 'name', direction: 'asc' }} height={500} />
+
+// Sorted by the server: the header only reports, the query does the work
+const serverColumns: VirtualListColumn<User>[] = [
+  { key: 'name', label: 'Name', width: { type: 'flex' }, renderCell: (u) => u.name, sortable: true },
+];
+
+const [sort, setSort] = useState<VirtualListSort | null>(null);
+
+<VirtualList
+  items={page}
+  columns={serverColumns}
+  sort={sort}
+  onSortChange={(next) => { setSort(next); refetch({ sort: next }); }}
+  height={500}
+/>
+```
+
+`null` and `undefined` (and `NaN`) `sortValue`s always sort last, in both directions, so empty cells stay at the bottom of the table. Strings are compared with a locale collator using numeric ordering, so `Order 2` comes before `Order 10`, and case and accents don't split otherwise-equal values. Rows that compare equal keep their original order. A `compare` function is used as given and negated for descending, so the empty-values rule doesn't apply to it.
+
+**Sorting and row reordering are mutually exclusive.** While a sort is active, `reorderable` and `treeReorder` are switched off (with a console warning), because a drop position would be overwritten by the next sort pass. Clear the sort to drag rows again.
+
+**Column resizing:** set `resizableColumns` and every column gets a grab strip on its trailing edge.
+
+- **Drag** it to resize. The column follows the pointer exactly, and `Escape` mid-drag cancels back to the width it started at.
+- **Double-click** it to fit the column to its widest cell. Only rendered rows can be measured, so this fits what is on screen, not the whole data set.
+- **Keyboard**: `Alt` plus the arrow keys on the focused header cell, 10px a press (`Alt+Shift` for 1px). `Alt+Home` goes to the column's minimum, `Alt+End` auto-fits. The strip itself is a mouse affordance and is not a tab stop.
+- **Undo it**: once anything has been resized, the gear menu grows a **Reset column widths** entry, and the same thing is on the imperative handle as `resetColumnWidths()`. Both also clear the saved widths.
+
+That entry is the only text this component renders of its own, so it is the only string a localised app has to pass: `resetColumnWidthsLabel="Spaltenbreiten zurücksetzen"`. Everything else in the table comes from your columns and cells.
+
+```tsx
+<VirtualList
+  items={rows}
+  columns={columns}
+  resizableColumns
+  persistColumnsKey="invoices"   // widths are saved with the column visibility
+  height={500}
+/>
+```
+
+**The first resize freezes the layout.** Every visible column is pinned to the width it already has, so nothing moves at that moment, and from then on the table is exact pixels rather than `flex`/`fit` tracks. This is what makes a drag follow the cursor one to one: with `fr` tracks the other columns would absorb the difference, and the dragged edge would stop moving the moment they hit their minimum. The table may then be wider than its container, in which case it scrolls horizontally.
+
+Two consequences worth knowing:
+
+- A `fit` column stops re-measuring once the layout is frozen. Its width is the user's from then on, which is the point: measurement only ever grows a column, so it would undo every drag that made one narrower.
+- A column revealed from the gear menu after the freeze starts at 160px, since there is nothing measured to go on. Double-click its handle to fit it.
+
+Widths ride along with `persistColumnsKey`, in the same `localStorage` entry as the visible columns. Entries saved before this existed still load. For full control, drive `columnWidths` and `onColumnWidthsChange` yourself: as with any controlled prop, a width the consumer doesn't accept snaps back once the drag ends.
+
+Resizing is a pointer and keyboard interaction. There is no touch gesture for it, because a horizontal drag at a row edge belongs to scrolling; double-click auto-fit works everywhere.
+
+**Keyboard:** the table takes **two tab stops** in total, whatever its size: the rows, then the header. (The rows come first because the element carrying their stop is the header's ancestor, and a focusable ancestor always precedes its descendants.)
+
+Rows, with the list focused:
+
+| Key | Does |
+|-----|------|
+| `↑` `↓` | Move the active row, scrolling it into view only if it isn't already |
+| `Home` `End` | First or last row |
+| `PageUp` `PageDown` | A viewport at a time |
+| `Enter` | Fire `onRowClick` for the active row, or step into it when the list has no `onRowClick` |
+| `Space` | Toggle the active row's selection (`multiSelect` only) |
+| `F2` | Step into the active row: focus its first control |
+| `Escape` | Step back out of a row to the list, making that row the active one |
+
+The list keeps the focus and points at the active row with `aria-activedescendant`, rather than moving focus onto the row: a virtualized row unmounts when it scrolls out of the window, which would strand the focus. For the same reason the per-row checkboxes are not tab stops.
+
+Keys are ignored while the focus is inside a cell, so an input, a `Dropdown` or a button in a row keeps its own. `F2` and `Escape` are the way in and back out; `Escape` is left alone when the cell's own content already handled it, so closing a `Dropdown` does not also leave the row.
+
+**Controls inside rows are not tab stops.** The list holds them at `tabindex="-1"` and puts back the ones of the row being used, so `Tab` walks that row and then leaves the list. Without that, every control in every *rendered* row is a stop, the set changes as the list scrolls, and tabbing through a long list drops out of it at an arbitrary row, because the next one isn't in the DOM yet when the browser looks for the next stop. Entering a row happens with `F2`, with `Enter` when the list has no `onRowClick`, or simply by clicking a control. A `tabindex` you set yourself is restored exactly as it was, and an element you already parked at `-1` stays parked.
+
+The row being used also stays mounted while it holds the focus, even once it scrolls out of the window, so scrolling can't drop the focus to the document body. Set `keyboardNavigation={false}` for a list whose rows bring their own key handling, as [Tree](Tree.md) does.
+
+Because `role="list"` is not a composite role, the active row is only announced in table mode. In list mode, pass `ariaRoles={{ container: 'listbox', row: 'option' }}` (or another composite pair) to have it announced there too.
+
+The header is the second stop, and one stop however many columns it has.
+
+| Key | Does |
+|-----|------|
+| `←` `→` | Move between the select-all box, the column headers and the column menu |
+| `Home` `End` | Jump to the first or last of those |
+| `Enter` `Space` | Sort the focused column, or toggle select-all on its cell |
+| `Alt` + `←` `→` | Resize the focused column by 10px (`Alt+Shift` by 1px) |
+| `Alt` + `Home` `End` | Take the focused column to its minimum width, or fit it to its content |
+
+Focus sits on the header cell rather than on the sort button inside it, so every key a column understands is in one place and a column costs one stop instead of three.
+
 **Imperative handle (`ref`):**
 
 Pass a `ref` typed as `VirtualListHandle` to control the list imperatively:
@@ -159,12 +274,15 @@ const listRef = useRef<VirtualListHandle>(null);
 listRef.current?.scrollToKey(user.id, { align: 'center' });
 ```
 
+**Reach for `scrollToKey` unless you actually mean a position.** A key survives sorting, filtering and reloading, because it belongs to the row rather than to where the row happens to sit. `scrollToIndex` is for the cases where there is no row yet: a jump box, "row 500", a scrollbar of your own. Its index is zero-based and counts the **rendered** order, so on a sorted list it is not the index in your `items` array.
+
 | Method | Signature | Description |
 |--------|-----------|-------------|
-| `scrollToIndex` | `(index, options?) => void` | Scroll so the row at `index` is visible. `options`: `{ align?: 'start' \| 'center' \| 'end'; behavior?: ScrollBehavior }` |
+| `scrollToIndex` | `(index, options?) => void` | Scroll so the row at `index` is visible. `options`: `{ align?: 'start' \| 'center' \| 'end'; behavior?: ScrollBehavior }`. A jump into rows that have never been rendered re-aims itself as their real heights are measured, so it lands on the row you asked for rather than on estimated arithmetic. Input of your own during the jump cancels it |
 | `scrollToKey` | `(key, options?) => void` | Scroll to the row whose `getItemKey` matches `key` (no-op if not found) |
 | `scrollToTop` | `(options?) => void` | Scroll back to the top |
 | `getScrollElement` | `() => HTMLDivElement \| null` | The underlying scroll container, for advanced use |
+| `resetColumnWidths` | `() => void` | Drop every user-set column width, returning the table to the widths its columns declare, and clear them from `persistColumnsKey` storage |
 | `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 |
 
 **Row reordering:** two modes, both drag-and-drop, both mouse and touch. Set exactly one:
@@ -246,6 +364,6 @@ interface TreeDropTarget {
 
 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`
+**Slots:** `root` `header` `headerCell` `headerSort` `sortIcon` `resizeHandle` `headerToggle` `togglePopover` `toggleItem` `toggleReset` `body` `row` `cell` `selectCell` `activeRow` `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.30.0",
+  "version": "0.31.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "components",