@ahrowe/ui 0.36.0 → 0.37.0

package/docs/Hooks.md

@@ -0,0 +1,232 @@
+# Hooks
+
+**When to use:** Standalone React hooks the library uses internally and publishes for the same jobs in your own code: keyboard shortcuts, media queries, the mobile keyboard's viewport, scroll-edge detection, swipe-to-dismiss, and the Escape / focus-trap / scroll-lock behaviour behind a custom overlay.
+
+**Keywords:** hotkey, keybinding, keyboard shortcut, cmd+k, command palette, breakpoint, responsive, touch device, on-screen keyboard, focus trap, scroll lock, swipe
+
+**Import:** `import { useHotkeys, formatHotkey, useMediaQuery, useCoarsePointer, useVisualViewportSize, useScrollEdges, useSwipeDismiss, useOverlay, tabbablesIn } from '@ahrowe/ui'`
+**Types:** `import type { HotkeyMap, HotkeyHandler, UseHotkeysOptions, VisualViewportSize, ScrollEdges, ScrollEdgesOptions, UseSwipeDismissOptions, UseSwipeDismissResult, UseOverlayArgs } from '@ahrowe/ui'`
+
+---
+
+## useHotkeys
+
+Keyboard shortcuts for a whole app or for one element.
+
+```tsx
+import { useHotkeys } from '@ahrowe/ui';
+
+function App() {
+  const [isPaletteOpen, setPaletteOpen] = useState(false);
+
+  useHotkeys({
+    'mod+k': () => setPaletteOpen(true),
+    'mod+shift+d': () => toggleDarkMode(),
+    '?': () => setHelpOpen(true),
+    Escape: () => setPaletteOpen(false),
+  });
+}
+```
+
+The map is read through a ref at event time, so an inline object literal is fine: no handler needs
+`useCallback` and no combo needs `useMemo`.
+
+**Combo syntax** — modifiers and the key joined by `+`, case-insensitive:
+
+| Part | Means |
+| ---- | ----- |
+| `mod` | Cmd on Apple platforms, Ctrl everywhere else |
+| `ctrl` / `control` | Ctrl |
+| `meta` / `cmd` / `command` | Cmd (Win key) |
+| `alt` / `option` | Alt |
+| `shift` | Shift |
+| the key | any `event.key` value, lower-cased: `k`, `1`, `escape`, `arrowup`, `enter` |
+
+Aliases for keys that are awkward to write: `esc`, `space`, `plus`, `up`, `down`, `left`, `right`.
+
+Two rules worth knowing:
+
+- **Shift is only compared when the combo names it.** `'?'` matches, even though `?` is typed with
+  Shift on most layouts.
+- **The key is matched against the keycap as well as the event.** `'mod+1'` matches Ctrl+Shift+1,
+  and `'alt+k'` matches on a Mac, where Alt+K produces `˚` rather than `k`.
+
+**Options**
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `enabled` | `boolean` | `true` | Attach the listener at all. Suspends every combo at once |
+| `target` | `RefObject<HTMLElement \| null>` | window | Scope the shortcuts to one element |
+| `enableInFields` | `boolean` | `false` | Let a combo fire while a text field or `contenteditable` has focus. Only combos the field would otherwise consume are held back: a single character, or an editing key (`arrowup`, `home`, `backspace`, `enter`, `tab`, …). Anything carrying Ctrl, Cmd or Alt fires regardless, and so do `f2`, `escape` and the other keys a field does not use |
+| `preventDefault` | `boolean` | `true` | Call `preventDefault()` on a match, so `mod+s` does not also open the browser's save dialog |
+
+Shortcuts keep firing while a `Modal` or `Drawer` is open, which is usually what a command palette
+wants. Pass `enabled` for the ones that should not:
+
+```tsx
+useHotkeys({ n: createRecord }, { enabled: !isModalOpen });
+```
+
+A held key repeats, as it does natively. Check `event.repeat` in the handler to ignore repeats.
+
+### formatHotkey
+
+The same combo written for the reader, so a hint beside a button cannot contradict what the binding
+listens for:
+
+```tsx
+formatHotkey('mod+shift+k'); // '⇧⌘K' on an Apple platform, 'Ctrl+Shift+K' elsewhere
+formatHotkey('f2'); // 'F2'
+```
+
+This is what `Menu` uses to draw the shortcut on an entry, from the same string `menuHotkeys`
+turns into a binding, see [Menu.md](Menu.md). A combo it cannot parse is handed back unchanged. The platform is read at call
+time, so a server-rendered page renders the non-Apple spelling.
+
+## useMediaQuery
+
+`true` while the query matches, re-rendering on every change. Backed by `useSyncExternalStore`, so
+it hydrates from the server's answer (`false`) instead of making the first client render disagree
+with the server's HTML.
+
+```tsx
+const isWide = useMediaQuery('(min-width: 1024px)');
+const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
+```
+
+Prefer this over reading `window.innerWidth`: a resize listener re-renders on every pixel, a media
+query only when the answer changes.
+
+## useCoarsePointer
+
+`true` when the primary pointing device is touch — `useMediaQuery('(pointer: coarse)')`.
+
+```tsx
+const isTouch = useCoarsePointer();
+```
+
+Use it for affordances, not for layout: a touchscreen laptop is a coarse pointer at desktop width.
+For "is this a phone", ask for both, as `Presentation.Auto` does — see [ConfigProvider.md](ConfigProvider.md).
+
+## useVisualViewportSize
+
+Tracks `window.visualViewport`, so layout can react to the mobile on-screen keyboard opening.
+`window.innerHeight` and CSS `vh` stay pinned to the full layout viewport and do not.
+
+```tsx
+const { height, offsetTop } = useVisualViewportSize();
+
+<div style={{ height, transform: `translateY(${offsetTop}px)` }} />;
+```
+
+Falls back to `window.innerHeight` / `0` where the API is missing.
+
+## useScrollEdges
+
+Which edges of a scroll container currently hide content, so the boundary can be marked — most
+often by fading it.
+
+```tsx
+const listRef = useRef<HTMLDivElement>(null);
+const { hasStart, hasEnd } = useScrollEdges(listRef, { axis: 'vertical' });
+
+<div ref={listRef} data-fade-top={hasStart} data-fade-bottom={hasEnd}>
+  {items}
+</div>;
+```
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `axis` | `'vertical' \| 'horizontal'` | `'vertical'` | Which axis to measure |
+| `isEnabled` | `boolean` | `true` | Pass `false` while the element is hidden |
+
+For the ready-made fade, use [ScrollFade.md](ScrollFade.md) instead.
+
+## useSwipeDismiss
+
+Swipe-to-dismiss on any element. Attaches its own pointer listeners to the node, so there is
+nothing to spread but the ref.
+
+```tsx
+const { ref, isDragging } = useSwipeDismiss<HTMLDivElement>({
+  onDismiss: () => remove(notification.id),
+  axis: 'x',
+});
+
+<div ref={ref}>{notification.message}</div>;
+```
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `onDismiss` | `() => void` | — | Called once the swipe commits, after the exit transition |
+| `axis` | `'x' \| 'y'` | `'x'` | Which axis the drag tracks |
+| `distanceThreshold` | `number` | `80` | px past which releasing commits, regardless of speed |
+| `velocityThreshold` | `number` | `0.5` | px/ms past which releasing commits, regardless of distance |
+| `mobileOnly` | `boolean` | `true` | Restrict the gesture to coarse pointers. On a mouse a drag is more likely a text selection |
+| `disabled` | `boolean` | `false` | Attach no listeners at all |
+
+`isDragging` is `true` for the duration of a drag — use it to pause an auto-dismiss timer.
+
+`ref` is a **callback ref**, not a ref object: the hook has to know when the node changes, and an
+element unmounted and rendered again is a different node. Attach it with `ref={ref}` as above. To
+keep a ref of your own on the same element, call both from one callback:
+
+```tsx
+<div
+  ref={(node) => {
+    ref(node);
+    myRef.current = node;
+  }}
+/>
+```
+
+## useOverlay
+
+The three behaviours every blocking overlay needs: Escape to dismiss, a focus trap, and a scroll
+lock on the page behind it. `Modal`, `Drawer` and `Popover` are built on it, and they all share one
+stack: a custom overlay using this hook nests correctly with theirs, so Escape closes only the
+innermost layer and the page stays locked until the last one closes.
+
+```tsx
+function CustomOverlay({ isOpen, onClose, children }) {
+  const panelRef = useRef<HTMLDivElement>(null);
+  useOverlay({ isActive: isOpen, containerRef: panelRef, onEscape: onClose });
+
+  if (!isOpen) return null;
+  return (
+    <div ref={panelRef} role="dialog" aria-modal="true">
+      {children}
+    </div>
+  );
+}
+```
+
+| Arg | Type | Default | Description |
+| --- | ---- | ------- | ----------- |
+| `isActive` | `boolean` | — | Everything below is set up while this is true |
+| `containerRef` | `RefObject<HTMLElement \| null>` | — | The panel. Focus is trapped inside it |
+| `onEscape` | `() => void` | — | Called when Escape is pressed while this is the topmost layer. Omit to not handle Escape |
+| `trapFocus` | `boolean` | `true` | Keep Tab inside the panel, and restore focus on close |
+| `lockScroll` | `boolean` | `true` | Prevent the page behind it from scrolling |
+
+Reach for [Modal.md](Modal.md) or [Drawer.md](Drawer.md) first; this is for an overlay they do not cover.
+
+## tabbablesIn
+
+The tabbable descendants of an element, in DOM order. An element taken out of the tab order with
+`tabindex="-1"` is skipped, whatever it is, so a roving-tabindex list reads as the one tab stop it
+actually is.
+
+```tsx
+const focusables = tabbablesIn(panelRef.current);
+focusables[0]?.focus();
+```
+
+## Also exported
+
+Hooks documented with the thing they belong to:
+
+- `useTheme` — the active theme, see [ThemeProvider.md](ThemeProvider.md)
+- `useComponentDefaults`, `useLabels` — see [ConfigProvider.md](ConfigProvider.md)
+- `useFormValidator` — see [FormValidator.md](FormValidator.md)
+- `useFormValidatorGroup` — see [FormValidatorGroup.md](FormValidatorGroup.md)

package/docs/Loading.md

@@ -1,27 +1,68 @@
-# Loading (IconLoading / SpinnerLoading)
+# Loading (SpinnerLoading)
 
-**When to use:** Loading indicators for async operations — page loads, data fetching, button actions (when not using Button's built-in `isLoading`).
+**When to use:** A loading indicator for async operations: page loads, data fetching, or covering a region while it refreshes. For a button use `Button`'s built-in `isLoading`, and for placeholder content that mirrors the shape of what is coming use [Skeleton.md](Skeleton.md).
 
-**Keywords:** busy, waiting, activity indicator, throbber
+**Keywords:** busy, waiting, activity indicator, throbber, progress, async, fetching, overlay
 
-**Import:** `import { IconLoading, SpinnerLoading } from '@ahrowe/ui'`
+**Import:** `import { SpinnerLoading } from '@ahrowe/ui'`
 
 ```tsx
-import { IconLoading, SpinnerLoading } from '@ahrowe/ui';
+import { SpinnerLoading } from '@ahrowe/ui';
 
-// Animated icon loader (uses FontAwesome spinner style)
-{isLoading && <IconLoading />}
-
-// Circular spinner
+// Default: a 70x70 circular spinner stroked in var(--primary-color)
 {isLoading && <SpinnerLoading />}
 
-// With custom className
+// Sized through className
 <SpinnerLoading className="my-spinner" />
 ```
 
-**Notes:**
-- `IconLoading` — icon-style spinner, small footprint, good inline with text
-- `SpinnerLoading` — circular progress ring, good for full-area loading states
-- Both components accept `className` for sizing/positioning
+```css
+.my-spinner {
+  width: 24px;
+  height: 24px;
+}
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `className` | `string` | Root `svg` element. This is also how you size it |
+
+## Covering a region while it loads
+
+`SpinnerLoading` is the indicator only. To overlay it on content, centre it in a positioned parent:
+
+```tsx
+<div className="panel">
+  <YourContent />
+  {isLoading && (
+    <div className="panel-overlay">
+      <SpinnerLoading className="my-spinner" />
+    </div>
+  )}
+</div>
+```
+
+```css
+.panel {
+  position: relative;
+}
+
+.panel-overlay {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  pointer-events: none;
+}
+```
+
+Drop the `pointer-events: none` if the overlay should also block interaction with what is underneath, and add a translucent `background` if it should dim it.
+
+For a branded loading screen rather than a generic spinner, [AnimatedLogo.md](AnimatedLogo.md) draws an SVG mark and sits in the same overlay.
+
+**Note:** the spinner animates continuously even under `prefers-reduced-motion`. A frozen spinner would say the app has hung, which is the opposite of what it is there to communicate.
 
-Check [package/common/loading/](https://github.com/AndreasWeinzierl/ahrowe-ui/tree/master/package/common/loading) for full prop details.
+**Slots:** none. The root `svg` takes `className`.

package/docs/Menu.md

@@ -4,7 +4,7 @@
 
 **Keywords:** context menu, action menu, overflow menu, kebab menu, three dots, popup menu, right click, anchored list
 
-**Import:** `import { Menu } from '@ahrowe/ui'`  
+**Import:** `import { Menu, menuHotkeys } from '@ahrowe/ui'`  
 **Types:** `import type { MenuProps, MenuEntry, MenuAction } from '@ahrowe/ui'`
 
 **Requires:** `<div id="bodyEnd"></div>` in your app: the menu is portalled there, like every other anchored panel in the library.
@@ -15,7 +15,7 @@ import type { MenuEntry } from '@ahrowe/ui';
 import { faPen, faCopy, faTrash } from '@fortawesome/free-solid-svg-icons';
 
 const items: MenuEntry[] = [
-  { id: 'edit', label: 'Edit', icon: faPen, shortcut: '⌘E' },
+  { id: 'edit', label: 'Edit', icon: faPen, shortcut: 'mod+e' },
   { id: 'duplicate', label: 'Duplicate', icon: faCopy },
   { separator: true },
   { id: 'delete', label: 'Delete', icon: faTrash, danger: true },
@@ -34,6 +34,28 @@ const items: MenuEntry[] = [
 { heading: 'This document' }                                              // a label over what follows
 ```
 
+**Shortcuts are drawn, not bound.** A `shortcut` is a combo in [useHotkeys](Hooks.md) spelling, and the menu writes it on the trailing edge for the platform the reader is on: `mod+s` shows as `⌘S` on an Apple one and `Ctrl+S` everywhere else. So there is one spelling per shortcut and a hand-written `'⌘S'` can no longer be wrong on Windows.
+
+Listening for it is yours, because only your app knows what else is listening: if it already binds `⌘S` and the menu bound it too, both would fire and the action would run twice. `menuHotkeys` turns the same entries into a map for `useHotkeys`, so the one spelling covers the hint and the binding:
+
+```tsx
+import { Menu, menuHotkeys, useHotkeys } from '@ahrowe/ui';
+
+const items: MenuEntry[] = [
+  { id: 'save', label: 'Save', shortcut: 'mod+s', onClick: save },
+  { id: 'rename', label: 'Rename', shortcut: 'f2', onClick: rename },
+];
+
+// Whenever the page is up, which is what a shortcut on a menu item usually means:
+// ⌘S in a File menu works without opening the File menu.
+useHotkeys(menuHotkeys(items, run));
+
+// Or only while the menu is open, if that is what you want:
+useHotkeys(menuHotkeys(items, run), { enabled: isOpen });
+```
+
+It runs each entry the way clicking it does, its own `onClick` then `onAction`, and leaves out a `disabled` entry and any entry with no `shortcut`. Bind them yourself instead if the actions already live in a keymap of your own; the menu does not mind either way.
+
 An action runs its own `onClick` first, then `onAction` on the menu, then the menu closes. Use whichever of the two fits: a handler per entry when they are unrelated, `onAction` when they funnel into one place.
 
 ```tsx
@@ -95,7 +117,7 @@ Separators and headings are never focused. The trigger is given `aria-haspopup`,
 | `id` | `string` | Stable id, also what `onAction` reports |
 | `label` | `ReactNode` | What the entry says |
 | `icon` | `IconContent` | Leading icon |
-| `shortcut` | `ReactNode` | Hint on the trailing edge, e.g. `⌘K`. Display only: binding it is yours |
+| `shortcut` | `string` | A combo in `useHotkeys` spelling, e.g. `'mod+k'`. Shown on the trailing edge, written for the platform. Binding it is yours, see `menuHotkeys` |
 | `disabled` | `boolean` | Not clickable, and skipped by the arrow keys |
 | `danger` | `boolean` | Renders in the destructive colour |
 | `onClick` | `() => void` | Runs before `onAction` |

package/docs/Popover.md

@@ -77,4 +77,6 @@ Only a `Click` trigger presents as a sheet. `Hover` and `Focus` open something s
 
 Requires a `<div id="bodyEnd"></div>` at the app root — the panel is portaled there, same as `Tooltip` and `Menu`.
 
+**Scrolling:** where the browser supports CSS anchor positioning, including the trigger's transforms, the panel is anchored to the trigger in CSS, so it moves with a scrolling trigger in the same frame instead of catching up a frame later. Firefox resolves anchors without transforms, so it keeps the pixel positioning. While it is open the trigger carries an inline `anchor-name`, added to any inline one it already has; an `anchor-name` your stylesheet gives the trigger is overridden for that time.
+
 **Keyboard & focus (click trigger):** the panel is portaled to the end of the DOM, so Tab can't reach it naturally. When the panel has focusable content and the keyboard opened it (Enter or Space on the trigger, or ArrowDown/ArrowUp), focus moves to the first focusable element and the panel gets `role="dialog"`; a pointer click leaves the focus where it already is. `focusOnOpen` forces either. Tabbing past the last element closes the popover and moves focus to the element after the trigger; Shift+Tab past the first element, and Escape, close it and return focus to the trigger. This is non-modal: focus is not trapped, and hover/focus triggers don't steal focus. Escape closes only the innermost open layer, so a popover inside a `Modal` closes on the first press and leaves the modal open. Popovers with only static content don't manage focus or claim the dialog role.

package/docs/Sticky.md

@@ -2,7 +2,7 @@
 
 **When to use:** Pin a piece of content to the top of the viewport once the page scrolls past it — section headers, toolbars, filter bars, table headers. The content sticks while its original position is above the fold and releases the moment that position scrolls back into view. A placeholder preserves the original space, so nothing below jumps when it detaches.
 
-**Keywords:** sticky header, pinned toolbar, scroll container, app shell, scrollable panel
+**Keywords:** sticky header, pinned toolbar, scroll container, app shell, scrollable panel, stop at the end, confine, within a section, unpin, release
 
 **Import:** `import { Sticky } from '@ahrowe/ui'`
 
@@ -36,6 +36,19 @@ const headerRef = useRef<HTMLElement>(null);
   <Content />
 </div>
 
+// Let it go once the section it labels ends, instead of pinning down the page.
+// A toolbar and a header pointed at the same boundary leave together.
+const section = useRef<HTMLDivElement>(null);
+<div ref={section}>
+  <Sticky boundary={section} boundaryInset={120}>
+    <Toolbar />
+  </Sticky>
+  <Sticky boundary={section} boundaryInset={120}>
+    <TableHeader />
+  </Sticky>
+  <Rows />
+</div>
+
 // React to the stuck state (e.g. add a shadow)
 <Sticky onStuckChange={(stuck) => setElevated(stuck)}>
   <Toolbar />
@@ -60,6 +73,12 @@ const headerRef = useRef<HTMLElement>(null);
 
 **`stickToScrollParent`:** by default `Sticky` always pins relative to the browser viewport, which can overlap other fixed/pinned chrome (e.g. an app header) that sits outside the element's own scroll container. Set `stickToScrollParent` to pin relative to the nearest ancestor with its own scrollbar (`overflow-y: auto`/`scroll`/`overlay`) instead — found once on mount by walking up from the root. Falls back to the viewport if no scrollable ancestor is found. Combine with `offsetTop` for extra spacing from that container's top (e.g. its own internal header).
 
+**`boundary`:** without it the content stays pinned for as long as the page scrolls, which is right for an app bar and wrong for anything that labels a section: a table header outlives its table and ends up captioning whatever scrolls under it next. Point `boundary` at the element the content belongs to, and once that element's bottom edge reaches the pinned content, the content is pushed up with it and leaves the screen together with it. This is what native `position: sticky` gets from its containing block, which a `position: fixed` implementation has no equivalent of, and it works whether the pin is relative to the viewport or to a `stickToScrollParent` container.
+
+**A group confined to one boundary leaves as one block.** Several `Sticky` elements stacked on top of each other and pointed at the same boundary are all lifted by the same amount, the largest any of them needs, so they keep their spacing and the lowest one's bottom edge lands on the boundary. Letting each clamp its own bottom edge instead would pile them all onto that edge and slide the lower ones up through the ones above.
+
+**`boundaryInset`** decides how much of the boundary's lower end stays uncovered while the content leaves. At `0` the content rests on the very bottom edge, so the last stretch of the boundary, as tall as the pinned content itself, is hidden underneath it for the whole exit: a table header ends up floating over nothing with its final rows behind it. Set it to how much you want to stay in sight, which for a table header is a few rows, and the content lifts off that much earlier and keeps that gap all the way out.
+
 **Stacking:** every mounted `Sticky` coordinates automatically, no extra markup needed. When more than one is stuck at the same time, a later one (in DOM order) that horizontally overlaps an earlier stuck one pins below it — `offsetTop` plus the overlapping ones' heights — instead of both landing on the same spot. Stickies that don't overlap horizontally (e.g. two half-width ones side by side under a full-width one) land at the same `top`, next to each other, rather than pushing each other down.
 
 **Key props:**
@@ -70,6 +89,8 @@ const headerRef = useRef<HTMLElement>(null);
 | `offsetTop` | `number` | Distance in px from the top of the viewport the content sticks to (default `0`). Ignored if `offsetElement` is set |
 | `offsetElement` | `RefObject<HTMLElement \| null>` | Element to stick below (e.g. a fixed/pinned header outside this library) — its live height is used as the offset instead of a fixed `offsetTop` |
 | `stickToScrollParent` | `boolean` | Stick to the top of the nearest scrollable ancestor instead of the browser viewport (default `false`). Falls back to the viewport if no scrollable ancestor is found |
+| `boundary` | `RefObject<HTMLElement \| null>` | Element the content is confined to. Once its bottom edge reaches the pinned content, the content rides it up and off screen instead of staying pinned over what follows. Several Stickies sharing one leave together |
+| `boundaryInset` | `number` | How much of the boundary's lower end stays uncovered while the content leaves, in px (default `0`). At `0` the last stretch, as tall as the content, is hidden under it for the whole exit. Ignored without `boundary` |
 | `zIndex` | `number` | z-index applied while stuck (default `20`) |
 | `disabled` | `boolean` | Disable sticking — content stays in normal flow |
 | `onStuckChange` | `(isStuck: boolean) => void` | Fired whenever the stuck state flips |

package/docs/VirtualList.md

@@ -2,7 +2,7 @@
 
 **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, sort, sorting, order by, ascending, descending, column header click, resize, resizable, drag column edge, column width, autofit
+**Keywords:** data table, virtualized table, sort, sorting, order by, ascending, descending, column header click, resize, resizable, drag column edge, column width, autofit, double scrollbar, nested scroll, window scrolling, spreadsheet, data entry grid, editable grid
 
 **Import:** `import { VirtualList } from '@ahrowe/ui'`  
 **Types:** `import type { VirtualListProps, VirtualListColumn, VirtualListHandle, VirtualListSort } from '@ahrowe/ui'`
@@ -124,7 +124,8 @@ const columns: VirtualListColumn<User>[] = [
 | `items` | `T[]` | Data array (required) |
 | `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%'`) |
+| `height` | `number \| string` | Scroll viewport height (default `'100%'`). Ignored with `scrollParent` |
+| `scrollParent` | `'nearest' \| 'window' \| HTMLElement \| (() => HTMLElement \| null)` | Drop the list's own scrollbar and virtualize against this scrollport instead — see **No scroll of its own** |
 | `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` |
@@ -135,6 +136,7 @@ const columns: VirtualListColumn<User>[] = [
 | `selectedKey` | `string \| number \| null` | Controlled single-select key |
 | `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** |
+| `tabAcrossRows` | `boolean` | Let `Tab` carry on into the next row instead of leaving the list at the end of the current one (default `false`). See **Keyboard** |
 | `multiSelect` | `boolean` | Enable checkbox multi-select column |
 | `selectedKeys` | `Set<string \| number>` | Controlled multi-select keys |
 | `onSelectionChange` | `(keys) => void` | Multi-select change callback |
@@ -241,6 +243,10 @@ Keys are ignored while the focus is inside a cell, so an input, a `Dropdown` or
 
 **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.
 
+**`tabAcrossRows` makes `Tab` walk the whole grid**, for rows that are filled in rather than read: from the last field of a row it enters the next row's first field, `Shift+Tab` walks back the same way, and `Tab` out of the last row (or back out of the first) leaves the list as it always did. The list mounts the row it is moving into, so it works across the edge of the rendered window. A row with nothing focusable in it is stepped over, and when nothing past it has anything either, the focus goes back to the list so the next `Tab` leaves. `Tab` on the list's own stop steps into the active row instead of over the whole list, since otherwise nothing inside it would ever be reachable by tabbing.
+
+It is off by default on purpose: for a list that is read, one tab stop plus the arrow keys is what a screen-reader user expects, and a few thousand rows of tab stops is a trap with no way past it. Turn it on for a grid of inputs — invoice lines, a timesheet — where field-by-field entry is the whole interaction. It does not need `keyboardNavigation`: with that off the list takes no stop of its own and `tabAcrossRows` only carries `Tab` across the boundary between two rows.
+
 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.
@@ -280,7 +286,8 @@ listRef.current?.scrollToKey(user.id, { align: 'center' });
 | `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 |
+| `getScrollElement` | `() => HTMLElement \| null` | The element that scrolls: the list itself, or the `scrollParent` it was given. `null` for `scrollParent='window'`, where the page scrolls |
+| `remeasure` | `() => void` | Re-read where the list sits in its `scrollParent`. Only needed in that mode, and only when something **above** the list changed height without the list re-rendering — an element that merely moves fires no event of its own |
 | `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 |
 
@@ -355,7 +362,40 @@ interface TreeDropTarget {
 
 **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:
+**No scroll of its own (`scrollParent`):** the list renders at its full height as a plain block in the page flow and virtualizes against a scrollport it does not own. For a long list at the end of a scrolling page, where an inner scrollbar inside the page's own is the thing you are trying to avoid.
+
+```tsx
+// Whatever scrolls around it, found once on mount. The usual answer.
+<VirtualList items={positions} columns={columns} scrollParent='nearest' estimatedRowHeight={48} />
+
+// Or name it: the page, an element, or a getter for a ref that fills later.
+<VirtualList items={positions} columns={columns} scrollParent='window' estimatedRowHeight={48} />
+<VirtualList items={positions} columns={columns} scrollParent={() => shellRef.current} estimatedRowHeight={48} />
+```
+
+`'nearest'` walks up to the first ancestor whose `overflow-y` is `auto`, `scroll`
+or `overlay`, whether or not it currently scrolls, and falls back to the page. A
+wrapper carrying `overflow: auto` as a layout fix is therefore picked ahead of
+the real scrollport, and the list then renders its first window and stops; name
+the element outright where that happens. That is the same ancestor
+[Sticky](Sticky.md) pins to, which is what a sticky header above the list needs:
+the two have to answer to the same scrollport or they come apart on the first
+scroll. It is resolved once and re-read only if that element leaves the DOM,
+because walking the tree reads computed style.
+
+Everything else works as before — the same windowing, the same `scrollToIndex`, the same keyboard model. What changes:
+
+- **`height` no longer applies.** The list is as tall as its rows.
+- **Set `estimatedRowHeight` to the real height** where the rows have one. Row heights are corrected as rows are measured, and here that correction resizes the *page*, so a guess that is wrong by 10px across 2000 rows moves the page's scrollbar under the user's hand. Rows of one fixed height cost nothing: the first measurement is right and the page height never moves again.
+- **The header sticks to that scrollport**, which is the top of the viewport rather than the top of the list. Give the list `--vl-header-top` to clear a fixed app bar: `<VirtualList style={{ '--vl-header-top': '64px' }} … />`.
+- **A frozen column layout wider than the list overflows the page sideways** instead of scrolling inside the list. A container cannot scroll one axis and not the other, and getting the vertical scrollbar back would undo the whole mode. Only reachable with `resizableColumns`.
+- **Call `remeasure()`** when something above the list changes height without the list re-rendering. The list watches the scrollport's own content box, which covers most of it; an element that merely moves fires nothing.
+
+**The list says so when it isn't virtualizing.** A viewport as tall as its own content renders every row, which is what a percentage `height` amounts to inside a parent with no definite height: the scroll container grows to fit the rows instead of clipping them. Nothing looks broken, the page is just slow. Past a hundred rows the list writes a `console.warn` naming that, which is the one failure mode of this component that is otherwise invisible. Passing `height` alongside `scrollParent` warns too, since the list then has no viewport to size.
+
+Only the rendered rows are in the DOM, in this mode as in the other one, so the browser's own find-in-page and print reach the window on screen and not the rest of the list. That is the price of virtualization, and it is the reason to use it only where the row count earns it.
+
+**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. Whichever trigger fires, one row count is asked at most once, so the loop ends as soon as a call appends nothing, and a page scrolled well past the end of the list does not go on asking with every scroll event. 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} />

package/package.json

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

package/dist/cjs-types/common/loading/iconLoading/iconLoading.d.ts

@@ -1,5 +0,0 @@
-import { default as React } from 'react';
-declare function IconLoading({ className }: {
-    className?: string | undefined;
-}): React.JSX.Element;
-export default IconLoading;

package/dist/cjs-types/common/loading/iconLoading/index.d.ts

@@ -1,2 +0,0 @@
-import { default as IconLoading } from './iconLoading.js';
-export default IconLoading;

package/dist/esm/common/loading/iconLoading/iconLoading.mjs

@@ -1,2 +0,0 @@
-"use client";import e from"./iconLoading.module.mjs";import"react";import t from"classnames";import{jsx as n,jsxs as r}from"react/jsx-runtime";function i({className:i=``}){return n(`div`,{className:t(e.iconLoading,i),children:r(`svg`,{xmlns:`http://www.w3.org/2000/svg`,viewBox:`-8 -1 16 14`,children:[n(`path`,{className:e.iconLoadingFirst,d:`M 0 0 C 3 5 6 5 6 12`,strokeWidth:`1.7`,fill:`none`}),n(`path`,{className:e.iconLoadingFirst,d:`M 0 0 C -3 5 -6 5 -6 12`,strokeWidth:`1.7`,fill:`none`}),n(`path`,{className:e.iconLoadingFirst,d:`M 0 0 L 0 10`,strokeWidth:`1.7`,fill:`none`}),n(`path`,{className:e.iconLoadingSecond,d:`M 0.1 10 C -3 10 -4 10 -6 12`,strokeWidth:`1.7`,fill:`none`}),n(`path`,{className:e.iconLoadingSecond,d:`M -0.1 10 C 3 10 4 10 6 12`,strokeWidth:`1.7`,fill:`none`})]})})}export{i as default};
-//# sourceMappingURL=iconLoading.mjs.map

package/dist/esm/common/loading/iconLoading/iconLoading.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"iconLoading.mjs","names":[],"sources":["../../../../../package/common/loading/iconLoading/iconLoading.tsx"],"sourcesContent":["import React from 'react';\nimport cx from 'classnames';\n\nimport styles from './iconLoading.module.pcss';\n\nfunction IconLoading({ className = '' }) {\n  return (\n    <div className={cx(styles.iconLoading, className)}>\n      <svg xmlns='http://www.w3.org/2000/svg' viewBox='-8 -1 16 14'>\n        <path className={styles.iconLoadingFirst} d='M 0 0 C 3 5 6 5 6 12' strokeWidth='1.7' fill='none' />\n        <path className={styles.iconLoadingFirst} d='M 0 0 C -3 5 -6 5 -6 12' strokeWidth='1.7' fill='none' />\n        <path className={styles.iconLoadingFirst} d='M 0 0 L 0 10' strokeWidth='1.7' fill='none' />\n        <path className={styles.iconLoadingSecond} d='M 0.1 10 C -3 10 -4 10 -6 12' strokeWidth='1.7' fill='none' />\n        <path className={styles.iconLoadingSecond} d='M -0.1 10 C 3 10 4 10 6 12' strokeWidth='1.7' fill='none' />\n      </svg>\n    </div>\n  );\n}\n\nexport default IconLoading;\n"],"mappings":"+IAKA,SAAS,EAAY,CAAE,YAAY,IAAM,CACvC,OACE,EAAC,MAAD,CAAK,UAAW,EAAG,EAAO,YAAa,CAAS,EAC9C,SAAA,EAAC,MAAD,CAAK,MAAM,6BAA6B,QAAQ,cAAhD,SAAA,CACE,EAAC,OAAD,CAAM,UAAW,EAAO,iBAAkB,EAAE,uBAAuB,YAAY,MAAM,KAAK,MAAQ,CAAA,EAClG,EAAC,OAAD,CAAM,UAAW,EAAO,iBAAkB,EAAE,0BAA0B,YAAY,MAAM,KAAK,MAAQ,CAAA,EACrG,EAAC,OAAD,CAAM,UAAW,EAAO,iBAAkB,EAAE,eAAe,YAAY,MAAM,KAAK,MAAQ,CAAA,EAC1F,EAAC,OAAD,CAAM,UAAW,EAAO,kBAAmB,EAAE,+BAA+B,YAAY,MAAM,KAAK,MAAQ,CAAA,EAC3G,EAAC,OAAD,CAAM,UAAW,EAAO,kBAAmB,EAAE,6BAA6B,YAAY,MAAM,KAAK,MAAQ,CAAA,CACtG,GACF,CAAA,CAET"}

package/dist/esm/common/loading/iconLoading/iconLoading.module.mjs

@@ -1,2 +0,0 @@
-"use client";var e=`iconLoading_wovj4`,t=`spin-to-oblivion_0tZtm`,n=`iconLoading-first_SBwP3`,r=`draw-line_1NiWA`,i=`iconLoading-second_nHrW3`,a=`draw-line-two_HmaHl`,o={iconLoading:e,"spin-to-oblivion":`spin-to-oblivion_0tZtm`,spinToOblivion:t,"iconLoading-first":`iconLoading-first_SBwP3`,iconLoadingFirst:n,"draw-line":`draw-line_1NiWA`,drawLine:r,"iconLoading-second":`iconLoading-second_nHrW3`,iconLoadingSecond:i,"draw-line-two":`draw-line-two_HmaHl`,drawLineTwo:a};export{o as default,r as drawLine,a as drawLineTwo,e as iconLoading,n as iconLoadingFirst,i as iconLoadingSecond,t as spinToOblivion};
-//# sourceMappingURL=iconLoading.module.mjs.map

package/dist/esm/common/loading/iconLoading/iconLoading.module.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"iconLoading.module.mjs","names":[],"sources":["../../../../../package/common/loading/iconLoading/iconLoading.module.pcss"],"sourcesContent":[".iconLoading {\n  display: flex;\n  justify-content: center;\n  align-items: center;\n  height: 100%;\n  width: 100%;\n  position: absolute;\n  left: 0;\n  top: 0;\n  user-select: none;\n  pointer-events: none;\n\n  --draw-duration: 0.8s;\n  --delay: 0.4s;\n\n  svg {\n    stroke-dasharray: 14;\n    stroke-dashoffset: 14;\n    width: 200px;\n    aspect-ratio: 1;\n    animation: calc(var(--draw-duration) * 3) spin-to-oblivion var(--delay) infinite;\n    transform: rotate(0deg);\n    stroke: var(--primary-color);\n    stroke-linecap: round;\n  }\n\n  &-first {\n    animation: calc(var(--draw-duration) * 3) draw-line var(--delay) infinite;\n  }\n\n  &-second {\n    animation: calc(var(--draw-duration) * 3) draw-line-two var(--delay) infinite;\n  }\n\n  @keyframes draw-line {\n    33% {\n      stroke-dashoffset: 0;\n    }\n\n    95% {\n      stroke-dashoffset: 0;\n    }\n\n    96% {\n      stroke-dashoffset: 14;\n    }\n  }\n\n  @keyframes draw-line-two {\n    33% {\n      stroke-dashoffset: 14;\n    }\n\n    66% {\n      stroke-dashoffset: 0;\n    }\n\n    95% {\n      stroke-dashoffset: 0;\n    }\n\n    96% {\n      stroke-dashoffset: 14;\n    }\n  }\n\n  @keyframes spin-to-oblivion {\n    50% {\n      transform: rotate(180deg);\n    }\n\n    75% {\n      transform: rotate(180deg) scale(0);\n    }\n\n    100% {\n      transform: rotate(180deg) scale(0);\n    }\n  }\n}\n"],"mappings":""}

package/dist/esm/common/loading/iconLoading/index.mjs

@@ -1,2 +0,0 @@
-"use client";import e from"./iconLoading.mjs";var t=e;export{t as default};
-//# sourceMappingURL=index.mjs.map

package/dist/esm/common/loading/iconLoading/index.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../../../package/common/loading/iconLoading/index.ts"],"sourcesContent":["import IconLoading from './iconLoading.js';\n\nexport default IconLoading;\n"],"mappings":"8CAEA,IAAA,EAAe"}

package/dist/types/common/loading/iconLoading/iconLoading.d.ts

@@ -1,5 +0,0 @@
-import { default as React } from 'react';
-declare function IconLoading({ className }: {
-    className?: string | undefined;
-}): React.JSX.Element;
-export default IconLoading;

package/dist/types/common/loading/iconLoading/index.d.ts

@@ -1,2 +0,0 @@
-import { default as IconLoading } from './iconLoading.js';
-export default IconLoading;