@ahrowe/ui 0.30.0 → 0.32.0

package/docs/Breadcrumb.md

@@ -106,3 +106,5 @@ function Example() {
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Breadcrumb: { separator: '/' } }}`. See [ConfigProvider.md](ConfigProvider.md).
 
 **Slots:** `root` `list` `item` `link` `icon` `separator` `current` `ellipsis` `hiddenList` `hiddenItem`
+
+**Labels:** `showHidden` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `BreadcrumbLabels`.

package/docs/Carousel.md

@@ -103,3 +103,5 @@ Slides announce themselves as the panel each dot controls, or as "slide 2 of 5"
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Carousel: { autoPlay: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
 
 **Slots:** `root` `track` `slide` `prevButton` `nextButton` `dots` `dot`
+
+**Labels:** `previous` `next` `slides` `goToSlide(slide)` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `CarouselLabels`.

package/docs/Chip.md

@@ -56,7 +56,7 @@ import { Chip, ChipContainer, ChipStyleType } from '@ahrowe/ui';
 | `text` | `string` | Chip label |
 | `styleType` | `ChipStyleType` | Colour variant (default `Default`) |
 | `thumbnail` | `string` | Avatar image URL |
-| `removeLabel` | `string` | Accessible name for the remove button. Default: `'Remove'` |
+| `labels.remove` | `string` | Accessible name for the remove button. Default: `'Remove'` |
 | `showRemoveIcon` | `boolean` | Show × icon |
 | `onRemove` | `() => void` | Remove button handler |
 | `onClick` | `() => void` | Makes chip clickable |
@@ -66,3 +66,5 @@ import { Chip, ChipContainer, ChipStyleType } from '@ahrowe/ui';
 | Prop | Type | Description |
 |------|------|-------------|
 | `inline` | `boolean` | Inline layout (default wraps) |
+
+**Labels:** `remove` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; keys merge individually. Type: `ChipLabels`.

package/docs/ColorPicker.md

@@ -50,3 +50,5 @@ Parsing uses the browser's own colour engine, which means it needs a DOM with a
 The inline swatch tracks the theme's text size, since it sits beside a label: `--swatch-size` falls back to `2em`, i.e. 32px at a 16px base, and the gap, the hex overlay and the transparency checkerboard scale with it.
 
 The picker panel deliberately does not. It is a floating control surface with its own fixed layout — a saturation area, sliders and a hex field — and it holds together at a large base font rather than needing to grow with it.
+
+**Labels:** `pickFromScreen` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `ColorPickerLabels`.

package/docs/ConfigProvider.md

@@ -114,3 +114,26 @@ Each entry is a `Partial<...Props>`, so any of that component's props can be def
 `Textarea`, `NumberInput`, and `DatePicker` are built on top of `Input`, so they **also** inherit `Input` defaults for the props they forward to it. Their own component-keyed defaults take precedence for props they handle themselves. Example: with `Input: { alwaysFloatLabel: true }` set, every `Textarea` / `NumberInput` / `DatePicker` floats its label too, without needing a separate entry.
 
 The `ComponentDefaults` type is the source of truth for which keys are currently supported — more components adopt it over time.
+
+## Translating the components
+
+Every string a component renders of its own is set through its `labels` prop, and a `ConfigProvider` sets them for the whole app at once:
+
+```tsx
+<ConfigProvider
+  defaultProps={{
+    Alert: { labels: { dismiss: 'Schließen' } },
+    Modal: { labels: { close: 'Schließen' } },
+    Pagination: { labels: { goToPage: (page) => `Zu Seite ${page}` } },
+    VirtualList: { labels: { selectRow: 'Zeile auswählen', selectAllRows: 'Alle Zeilen auswählen' } },
+  }}
+>
+  <App />
+</ConfigProvider>
+```
+
+**Labels merge per key**, unlike every other default here. An instance that overrides one string keeps the provider's translations for the rest, so `<Alert labels={{ dismiss: 'Weg damit' }} />` under the provider above does not lose anything else Alert might have been given. Anything the component does not produce itself, a `title`, a column `label`, a button's children, is already yours and never appears in `labels`.
+
+`ColorPicker` and `VirtualList` appear in `ComponentDefaults` with their labels only: the first is configured elsewhere, the second has generic props that a per-key default map cannot express. `Toast` is not there at all, because `ToastProvider` is already its app-wide configuration and carries `labels` itself.
+
+Each component's doc lists its own keys under **Labels:**.

package/docs/ConfirmModal.md

@@ -38,9 +38,9 @@ const [isOpen, setIsOpen] = useState(false);
 | `content` | `ReactNode` | Dialog body |
 | `onConfirm` | `() => void \| Promise<void>` | Called when user confirms |
 | `onClose` | `(didSubmit: boolean) => void` | Called on both confirm and cancel |
-| `submitLabel` | `string` | Confirm button label (default `'Confirm'`) |
+| `labels.submit` | `string` | Confirm button label (default `'Confirm'`) |
 | `isDelete` | `boolean` | Render the confirm button with the destructive (delete) style |
-| `actionButtonsProps` | `ActionButtonsProps` | Overrides passed through to the underlying `ActionButtons` (wins over `submitLabel` / `isDelete`) |
+| `actionButtonsProps` | `ActionButtonsProps` | Overrides passed through to the underlying `ActionButtons` (wins over `labels.submit` / `isDelete`) |
 | `children` | `ReactNode` | Alternative to `content` prop |
 
 **Destructive action:**
@@ -51,16 +51,18 @@ const [isOpen, setIsOpen] = useState(false);
   title="Delete item?"
   content="This action cannot be undone."
   isDelete
-  submitLabel="Delete"
+  labels={{ submit: 'Delete' }}
   onConfirm={async () => { await deleteItem(); }}
   onClose={() => setIsOpen(false)}
 />
 ```
 
-**Global defaults:** `ConfirmModal` supports `ConfigProvider` — set a default `submitLabel` (or any other prop) app-wide:
+**Global defaults:** `ConfirmModal` supports `ConfigProvider` — set a default `labels.submit` (or any other prop) app-wide:
 
 ```tsx
-<ConfigProvider defaultProps={{ ConfirmModal: { submitLabel: 'OK' } }}>
+<ConfigProvider defaultProps={{ ConfirmModal: { labels: { submit: 'OK' } } }}>
   <App />
 </ConfigProvider>
 ```
+
+**Labels:** `submit` `cancel` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; keys merge individually. Type: `ConfirmModalLabels`.

package/docs/DatePicker.md

@@ -6,7 +6,8 @@
 
 **Keyboard:** the day grid uses a roving tab stop (the selected day, or today, or the 1st — one Tab reaches it, not every day individually); arrow keys move by day (`←`/`→`) or by week (`↑`/`↓`), crossing into the adjacent month automatically when they run past the edge, and Enter/Space selects the focused day.
 
-**Import:** `import { DatePicker } from '@ahrowe/ui'`
+**Import:** `import { DatePicker } from '@ahrowe/ui'`  
+**Types:** `import type { DatePickerProps } from '@ahrowe/ui'`
 
 ```tsx
 import { DatePicker, FormValidator } from '@ahrowe/ui';

package/docs/EmptyState.md

@@ -28,3 +28,5 @@ import { faInbox } from '@fortawesome/free-solid-svg-icons';
 | `icon` | `IconDefinition \| ReactElement` | Icon shown above the message — FontAwesome icon or any React element |
 | `children` | `ReactNode` | Message body (defaults to `"No entries available"`) |
 | `className` | `string` | Root element class |
+
+**Labels:** `empty` — the text this component renders of its own. Pass `labels` to override it, on the component or app-wide through `ConfigProvider`; keys merge individually. Type: `EmptyStateLabels`.

package/docs/FormValidatorGroup.md

@@ -38,7 +38,7 @@ function ProfileForm({ user, onSaved }) {
       <Input label="Name"  formValidator={form.group.name} />
       <Input label="Email" type={InputType.Email} formValidator={form.group.email} />
       <ActionButtons
-        submitLabel="Save"
+        labels={{ submit: 'Save' }}
         onSubmit={form.submit}
         isSubmitButtonLoading={form.isSubmitting}
         isSubmitButtonDisabled={!form.isDirty}

package/docs/Input.md

@@ -125,6 +125,8 @@ The stored value is the formatted one, spaces included, so strip them before a l
 
 **Slots:** `label` `container` `input` `suffix` `upperRightLabel` `fieldset`
 
+**Labels:** `clear` `clearSearch` `showPassword` `hidePassword` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `InputLabels`.
+
 ## Browser autofill
 
 `autoComplete` is the plain HTML attribute and is passed straight through — use `'one-time-code'`, `'new-password'`, `'street-address'` and the rest as you would on a bare `<input>`. Input does **not** set it: autofill and password managers are usability and accessibility features, and a plain field has no suggestion list of its own for them to collide with.

package/docs/KlipyPicker.md

@@ -41,3 +41,5 @@ import { KlipyPicker } from '@ahrowe/ui';
 | `selected` | `string \| null` | Currently selected GIF id (for visual highlight) |
 | `onSelect` | `(preview: KlipyResult \| null) => void \| Promise<void>` | Fires when a GIF is picked; `null` when cleared |
 | `className` | `string` | Root element class |
+
+**Labels:** `search` — the text this component renders of its own. Pass `labels` to override it, on the component or app-wide through `ConfigProvider`; keys merge individually. Type: `KlipyPickerLabels`.

package/docs/Modal.md

@@ -71,3 +71,5 @@ A sheet-presented Modal takes 90% of the screen height rather than the 70% a men
 The panel also takes the full native `div` attribute set (`id`, `role`, `aria-*`, `data-*`, …). Pass `aria-label` when using `hideHeader`, since there is then no title to label the dialog with.
 
 **Slots:** `container` `backdrop` `modal` `header` `title` `closeButton` `body`
+
+**Labels:** `close` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `ModalLabels`.

package/docs/MultiSelect.md

@@ -28,10 +28,10 @@ const [value, setValue] = useState<MultiSelectValue[]>([]);
 <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…" />
+<MultiSelect items={countries} searchable labels={{ 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}`} />
+<MultiSelect items={commonTags} allowCustomValues labels={{ create: (value) => `Neu: ${value }}`} />
 
 // Cap the selection — unselected options disable once the cap is reached
 <MultiSelect items={items} maxSelected={3} />
@@ -72,9 +72,9 @@ import { Presentation } from '@ahrowe/ui';
 | `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'`) |
+| `labels.create` | `(value: string) => string` | Label for the add row (default `Add "…"`) |
+| `labels.searchPlaceholder` | `string` | Placeholder for that box (default `'Search…'`) |
+| `labels.empty` | `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 |
@@ -98,3 +98,5 @@ import { Presentation } from '@ahrowe/ui';
 **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`
+
+**Labels:** `clearSelection` `create(value)` `searchPlaceholder` `empty` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `MultiSelectLabels`.

package/docs/NumberInput.md

@@ -74,8 +74,8 @@ const priceValidator = new FormValidator<number | undefined>(undefined, [Validat
 | `min` | `number` | Lower bound — see the note below |
 | `max` | `number` | Upper bound — see the note below |
 | `arrowsLayout` | `'auto' \| 'stacked' \| 'split'` | Stepper layout. Default: `'auto'` |
-| `increaseLabel` | `string` | Accessible name for the increase button. Default: `'Increase'` |
-| `decreaseLabel` | `string` | Accessible name for the decrease button. Default: `'Decrease'` |
+| `labels.increase` | `string` | Accessible name for the increase button. Default: `'Increase'` |
+| `labels.decrease` | `string` | Accessible name for the decrease button. Default: `'Decrease'` |
 
 **Steppers (`showArrows`):** two layouts, picked by `arrowsLayout`:
 
@@ -124,3 +124,5 @@ const qty = new FormValidator<number | undefined>(undefined, [inRange(10, 100)])
 ```
 
 **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.
+
+**Labels:** `increase` `decrease` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; keys merge individually. Type: `NumberInputLabels`.

package/docs/OtpInput.md

@@ -91,6 +91,8 @@ const codeValidator = new FormValidator('', [Validators.required(), Validators.m
 
 **Slots:** `root` `label` `inputs` `input` `separator`
 
+**Labels:** `field` `digit(position, length)` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `OtpInputLabels`.
+
 ## Sizing
 
 The code boxes, the digit inside them, the gaps and the separator all scale with the theme's text, so the field stays in proportion with its label.

package/docs/Pagination.md

@@ -70,3 +70,5 @@ const [page, setPage] = useState(1);
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Pagination: { showEdges: true } }}`. See [ConfigProvider.md](ConfigProvider.md).
 
 **Slots:** `root` `item` `control` `ellipsis`
+
+**Labels:** `goToPage(page)` `first` `previous` `next` `last` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `PaginationLabels`.

package/docs/RoomDrawer.md

@@ -373,3 +373,5 @@ The previous `RoomDrawer` had no data contract at all: `RoomDrawerProps` was `{
 - Removing a corner was a double-click, which was undiscoverable and impossible on touch. Select it and press `Delete` instead.
 
 **Slots:** `root` `toolbar` `toolButton` `toolIcon` `viewControls` `viewButton` `zoomLabel` `canvasWrapper` `canvas` `grid` `rooms` `roomFill` `roomLabel` `walls` `wallBody` `openings` `opening` `overlay` `measureLine` `floorBar` `floorTab` `inspector` `inspectorLabel` `inspectorField` `hint`
+
+**Labels:** every string the drawer's own chrome renders, including `tools`, `storeyHeightHint` and `sillHeightHint`. Type: `RoomDrawerLabels`.

package/docs/SplitButton.md

@@ -79,3 +79,5 @@ import { ButtonStyleType } from '@ahrowe/ui';
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ SplitButton: { styleType: ButtonStyleType.Default } }}`. See [ConfigProvider.md](ConfigProvider.md).
 
 **Slots:** `root` `primaryButton` `triggerButton` `menu` `menuItem`
+
+**Labels:** `moreActions` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `SplitButtonLabels`.

package/docs/Timer.md

@@ -140,6 +140,8 @@ function Example() {
 
 **Slots:** `root` `ringWrapper` `ringSvg` `ringTrack` `ringProgress` `ripples` `ripple` `display` `time` `label` `controls` `addButton` `removeButton` `pauseButton` `cancelButton`
 
+**Labels:** `cancel` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `TimerLabels`.
+
 ## Sizing
 
 The ring follows the theme's text size, because the readout inside it does: `--timer-size` falls back to `10em`, i.e. 160px at a 16px base, and the gaps and padding around it are `em` too. The `size` prop still wins where it is given.

package/docs/Toast.md

@@ -75,6 +75,8 @@ showToast('Done', {
 
 **Slots:** `root` `icon` `content` `closeButton` `progressBar`
 
+**Labels:** `close` — the dismiss button's screen-reader name. Set it on `ToastProvider` for the whole app (`labels={{ close: 'Schließen' }}`), or per toast through the `showToast` options. Type: `ToastLabels`.
+
 ## Sizing
 
 A toast is sized and spaced by its font: the padding, the gap, the body copy, the icon, the close button, the variant accent bar and the progress bar all scale with the theme's text, as does the gap between stacked toasts.

package/docs/Tree.md

@@ -62,7 +62,7 @@ import { faWarehouse } from '@fortawesome/free-solid-svg-icons';
 | `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'`) |
+| `labels.empty` | `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'`) |
 
@@ -93,3 +93,5 @@ Two things change in that mode. Rows must be a uniform height, so size them with
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Tree: { indent: 30 } }}`. See [ConfigProvider.md](ConfigProvider.md).
 
 **Slots:** `root` `node` `toggle` `icon` `label` `empty`
+
+**Labels:** `empty` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; keys merge individually. Type: `TreeLabels`.

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,17 @@ 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 |
 | `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 +155,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.
+
+Its text, like every other string the table renders of its own, is set through `labels` (see below): `labels={{ resetColumnWidths: 'Spaltenbreiten zurücksetzen' }}`.
+
+```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 +273,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 +363,8 @@ 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`
+
+**Labels:** `selectRow` `selectAllRows` `toggleColumns` `columnsHidden(count)` `resetColumnWidths` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `VirtualListLabels`.
 
 **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/docs/Wizard.md

@@ -26,8 +26,7 @@ const [step, setStep] = useState(0);
 />
 
 <ActionButtons
-  submitLabel={step < STEPS.length - 1 ? 'Next' : 'Finish'}
-  cancelLabel={step > 0 ? 'Back' : 'Cancel'}
+  labels={{ submit: step < STEPS.length - 1 ? 'Next' : 'Finish', cancel: step > 0 ? 'Back' : 'Cancel' }}
   onSubmit={() => step < STEPS.length - 1 ? setStep(step + 1) : handleFinish()}
   onClose={() => step > 0 ? setStep(step - 1) : handleCancel()}
 />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "components",