@ahrowe/ui 0.35.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/IdleManager.md

@@ -1,19 +1,49 @@
 # IdleManager
 
-**When to use:** Detects user inactivity — auto-logout, session timeout warnings, auto-save triggers, pausing background processes.
+**When to use:** Show something only once the user has stopped interacting — a screen saver, a session-timeout warning, an "are you still there?" prompt, an idle dashboard view. It renders its children after a period of inactivity and hides them again the moment the user does anything.
 
-**Keywords:** auto logout, inactivity timer
+**Keywords:** auto logout, inactivity timer, timeout, away, afk, screensaver, session expiry
 
 **Import:** `import { IdleManager } from '@ahrowe/ui'`
+**Types:** `import type { IdleManagerProps } from '@ahrowe/ui'`
 
 ```tsx
 import { IdleManager } from '@ahrowe/ui';
 
-// Warn after 14 minutes of inactivity, log out after 15
-<IdleManager
-  idleTimeout={14 * 60 * 1000}
-  onIdle={() => showSessionWarning()}
-/>
+// Nothing is rendered until the user has been idle for 14 minutes.
+<IdleManager idleAfterSeconds={14 * 60}>
+  <SessionWarning onStaySignedIn={keepAlive} />
+</IdleManager>
+
+// Only arm it where it makes sense — here, only while signed in.
+<IdleManager idleAfterSeconds={60} renderCondition={isSignedIn}>
+  <ScreenSaver />
+</IdleManager>
+```
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Rendered only while the user is idle |
+| `idleAfterSeconds` | `number` | Seconds of inactivity before the children appear. Default `600` |
+| `renderCondition` | `boolean` | Children appear only when this is `true` **and** the user is idle. Default `true` |
+
+**How idle is decided:** a `click`, `mousemove`, `keydown`, `scroll` or `touchstart` anywhere in the document counts as activity. Any of them restarts the countdown and hides the children again at once.
+
+There is no callback. The component tells you nothing and renders instead, so whatever should happen on idle goes in the children: put the side effect in their own `useEffect`, which runs when they mount.
+
+```tsx
+function AutoLogout() {
+  useEffect(() => {
+    signOut();
+  }, []);
+  return <p>Signed out for inactivity.</p>;
+}
+
+<IdleManager idleAfterSeconds={15 * 60}>
+  <AutoLogout />
+</IdleManager>
 ```
 
-**Note:** This is a legacy JSX component — check the source at [package/common/idleManager/idleManager.jsx](../common/idleManager/idleManager.jsx) for full prop details as no TypeScript types file exists yet.
+Changing `idleAfterSeconds` restarts the countdown without hiding what is already on screen; only real activity does that. The pending timer is cleared on unmount, so it never fires afterwards.

package/docs/InputDropdown.md

@@ -67,6 +67,17 @@ interface InputDropdownItem {
 | `error` | `string` | Manual error message (used when no `formValidator` is given) |
 | `isRequired` | `boolean` | Shows the required mark (`*`) next to the label. Also inferred automatically when `formValidator` has a `required` validator. Default `false` |
 
+**Keyboard:** `↑`/`↓` move the highlight through the suggestions, and the text you typed is part of
+the cycle rather than a dead end: arrowing off either end returns to it, and one more press carries
+on to the far end of the list. So `↓` on the last suggestion shows your text again, then the first
+suggestion. This is how a browser's own address bar behaves, and it is why the list does not wrap
+straight around the way `Dropdown` and `MultiSelect` do — neither of those has typed text to pass
+through. `Enter` picks the highlighted suggestion, and the list scrolls to keep it in view.
+
+Inside a `<form>`, `Enter` on a highlighted suggestion picks it without submitting the form; `Enter`
+with nothing highlighted submits as any text field would. So cycling to your own text and pressing
+`Enter` twice is the way to submit exactly what you typed. `Home` and `End` are left to the text field, so they move the caret.
+
 **Slots:** `root` `dropdown` `item`
 
 Long lists are handled by capping how many matches are rendered (`maxItems`, default `100`) rather than by virtualizing: only about six rows fit in the scroll box, so anything past the cap is DOM the user never sees. Raise `maxItems` (or set it to `0`) if a list is genuinely meant to be scrolled end to end. For lists too large to pass as `items` at all, fetch on the server, keep the results in your own state and feed them in as `items`.

package/docs/InteractableDiv.md

@@ -4,6 +4,12 @@
 
 Enter and Space dispatch a real click, the way a native button does, so `onClick` always receives a `MouseEvent` and a handler on an element above this one sees the activation too.
 
+A click or a key on a control **inside** it belongs to that control: a field, a link, a button or
+anything carrying an interactive `role` swallows the activation, so a clickable container can hold
+a form without every click into it counting as a press. The event itself is never stopped, so a
+handler on an element above this one, or one attached to the node with a `ref`, still sees every
+click, including the ones this one declines.
+
 **Keywords:** custom button div
 
 **Import:** `import { InteractableDiv } from '@ahrowe/ui'`
@@ -17,4 +23,4 @@ import { InteractableDiv } from '@ahrowe/ui';
 </InteractableDiv>
 ```
 
-**Note:** Check [package/common/interactableDiv/](../common/interactableDiv/) for full prop details.
+**Note:** Check [package/common/interactableDiv/](https://github.com/AndreasWeinzierl/ahrowe-ui/tree/master/package/common/interactableDiv) for full prop details.

package/docs/KlipyPicker.md

@@ -36,7 +36,7 @@ import { KlipyPicker } from '@ahrowe/ui';
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `token` | `string` | Klipy API key (defaults to a built-in demo key — replace in production) |
+| `token` | `string` | Klipy API key. No default: without one the picker renders but every request fails |
 | `isModal` | `boolean` | Render the picker inside a `Modal` instead of inline |
 | `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 |

package/docs/Loading.md

@@ -1,25 +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).
 
-**Import:** `import { IconLoading, SpinnerLoading } from '@ahrowe/ui'`
+**Keywords:** busy, waiting, activity indicator, throbber, progress, async, fetching, overlay
 
-```tsx
-import { IconLoading, SpinnerLoading } from '@ahrowe/ui';
+**Import:** `import { SpinnerLoading } from '@ahrowe/ui'`
 
-// Animated icon loader (uses FontAwesome spinner style)
-{isLoading && <IconLoading />}
+```tsx
+import { SpinnerLoading } from '@ahrowe/ui';
 
-// 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/](../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` |
@@ -104,4 +126,6 @@ Separators and headings are never focused. The trigger is given `aria-haspopup`,
 
 `root` and `trigger` generate no box, so your trigger keeps the place it would have had without a Menu around it. A `className` or `style` on those two cannot paint; style the trigger you pass in instead.
 
+**Sheet dimensions:** as a sheet it spans the full width up to `--sheet-max-width` (560px) and centres beyond it, caps its height at `--sheet-max-height` (70dvh) of the space actually visible, and clears a phone's home indicator with `--sheet-safe-padding` (8px, or the device's own safe-area inset where that is larger). Set any of them per instance via `style` or theme-wide via `ThemeProvider`.
+
 **No submenus yet.** An entry is a single action. Nesting brings its own interaction model — hover intent, a second layer of focus management, and a different shape again as a sheet on touch — so it is a separate piece of work rather than a field on `MenuAction`.

package/docs/Modal.md

@@ -2,13 +2,13 @@
 
 **When to use:** Full overlay dialog — forms, detail views, confirmations, wizards that need to block the rest of the UI.
 
-**Keywords:** popup, dialog, overlay, escape, focus trap, scroll lock, sticky header, bottom sheet, action sheet, mobile, touch
+**Keywords:** popup, dialog, overlay, escape, focus trap, scroll lock, sticky header, sticky footer, actions, buttons, bottom sheet, action sheet, mobile, touch
 
 **Import:** `import { Modal } from '@ahrowe/ui'`
 
 **Requires:** `<div id="bodyEnd"></div>` in your HTML (renders via portal).
 
-The panel itself never scrolls: the header is fixed and the children scroll inside the `body` slot, so the title and close button stay visible no matter how long the content is.
+The panel itself never scrolls: the header is fixed and the children scroll inside the `body` slot, so the title and close button stay visible no matter how long the content is. Pass `footer` for anything that should stay put below the content, typically the action buttons.
 
 While open, the modal traps focus (focus moves into the panel and returns to whatever was focused before on close), locks scrolling on the page behind it, and closes on Escape. Modals nest correctly: Escape closes only the topmost one, and the page stays locked until the last one closes. The same applies to anything opened from inside a modal — a `Menu`, `Dropdown` or `Popover` counts as the layer above it, so Escape closes that first, and the modal's focus trap leaves focus alone while it's open (all three render through the same portal, so their DOM sits beside the modal's panel rather than inside it).
 
@@ -23,16 +23,18 @@ const [isOpen, setIsOpen] = useState(false);
   isOpen={isOpen}
   title="Edit Profile"
   onClose={() => setIsOpen(false)}
+  footer={
+    <ActionButtons
+      onSubmit={handleSubmit}
+      onClose={() => setIsOpen(false)}
+      isSubmitButtonLoading={isSaving}
+    />
+  }
 >
   <form onSubmit={handleSubmit}>
     <Input label="Name" formValidator={nameValidator} />
     <Input label="Email" type={InputType.Email} formValidator={emailValidator} />
   </form>
-  <ActionButtons
-    onSubmit={handleSubmit}
-    onClose={() => setIsOpen(false)}
-    isSubmitButtonLoading={isSaving}
-  />
 </Modal>
 
 // Modal without header
@@ -48,11 +50,12 @@ const [isOpen, setIsOpen] = useState(false);
 | `isOpen` | `boolean` | Controls visibility |
 | `title` | `string` | Header title |
 | `onClose` | `() => void` | Called when the backdrop is clicked, the close button is pressed, or Escape is pressed |
+| `footer` | `ReactNode` | Pinned below the scrolling body, e.g. action buttons. Nothing renders when omitted |
 | `hideHeader` | `boolean` | Removes the header bar |
 | `closeOnEscape` | `boolean` | Close on Escape while this is the topmost modal. Default `true` |
 | `presentation` | `Presentation` | Present as a bottom sheet, always (`Sheet`) or only on a small touch screen (`Auto`). `Default`, or omitting it, is the centred dialog |
 
-**Bottom sheet:** `presentation={Presentation.Sheet}` pins the dialog to the bottom of the screen instead of centring it — full width up to 560px, rounded on its top corners only, sliding up rather than scaling in, and lifted above an open on-screen keyboard, shrinking to fit the space that leaves rather than running off the top of the screen. Nothing else changes: the header stays fixed and the body scrolls, which is what a sheet needs anyway, and the backdrop, focus trap, scroll lock and Escape all behave exactly as they do centred. `Presentation.Auto` applies it only when the pointer is coarse *and* the screen is under 768px wide.
+**Bottom sheet:** `presentation={Presentation.Sheet}` pins the dialog to the bottom of the screen instead of centring it — full width up to 560px, rounded on its top corners only, sliding up rather than scaling in, and lifted above an open on-screen keyboard, shrinking to fit the space that leaves rather than running off the top of the screen. Nothing else changes: the header and footer stay fixed and the body scrolls, which is what a sheet needs anyway, and the backdrop, focus trap, scroll lock and Escape all behave exactly as they do centred. `Presentation.Auto` applies it only when the pointer is coarse *and* the screen is under 768px wide.
 
 `Presentation.Default` means "wherever the component normally puts it", which for a Modal is centred rather than anchored to anything — so an app-wide `<ConfigProvider presentation={Presentation.Default}>` switches sheets off everywhere, this included.
 
@@ -64,12 +67,33 @@ import { Modal, Presentation } from '@ahrowe/ui';
 </Modal>
 ```
 
-A sheet-presented Modal takes 90% of the screen height rather than the 70% a menu-sized sheet uses, since it carries forms and detail views. Override either with the `--sheet-max-height` and `--sheet-safe-padding` custom properties, per instance via `style` or theme-wide via `ThemeProvider`. `--sheet-max-height` is a ceiling, not a height: whatever it's set to, a sheet never grows past the area actually visible, which is measured live and so accounts for an open keyboard that no viewport unit can see.
+A sheet-presented Modal takes 90% of the screen height rather than the 70% a menu-sized sheet uses, since it carries forms and detail views, and it takes its bottom safe-area padding from `--modal-padding`, so the panel's own spacing carries down to the screen edge. It sets both on the panel itself, so a `ThemeProvider` value for `--sheet-max-height` or `--sheet-safe-padding` never reaches a Modal sheet: override those two per instance via `style`. `--sheet-max-width` it leaves alone, so that one works theme-wide as well. A sheet spans the full width up to it (560px) and centres beyond, full-bleed on a phone and a centred panel on anything wider. `--sheet-max-height` is a ceiling, not a height: whatever it's set to, a sheet never grows past the area actually visible, which is measured live and so accounts for an open keyboard that no viewport unit can see.
+
+**Theming:** override these CSS variables theme-wide via `ThemeProvider` or per instance via `style`; each falls back to a built-in default:
+
+| Variable | Falls back to |
+|----------|---------------|
+| `--modal-padding` | `var(--spacing-l)` |
+| `--modal-gap` | `var(--spacing-l)` — the gap between header, body and footer |
+| `--modal-max-width` | `calc(100% - 2 * var(--modal-padding))` |
+| `--modal-max-height` | `calc(100% - 2 * var(--modal-padding))` |
+| `--modal-body-bleed` | `calc(var(--modal-gap) / 2)` |
+| `--modal-scroll-fade` | `calc(var(--modal-gap) + var(--modal-body-bleed))` — `0px` switches the fade off |
+
+The panel has no width of its own, so it grows to whatever its content asks for up to `--modal-max-width`. Give a text-heavy dialog an explicit `width` (or set `--modal-max-width` app-wide) rather than letting a long paragraph decide how wide the dialog is.
+
+The cap is the same at every screen size: the panel never comes closer to the edge than its own padding. There is no breakpoint, so a phone and a desktop leave the same gap and the backdrop stays visible around the panel on both.
+
+`--modal-body-bleed` is how far the body reaches past its own edge, as a negative margin cancelled by an equal padding, so a focus ring or a floating label on the first element inside isn't clipped by the scroll container. Adjust it through this variable rather than setting `padding` on the `body` slot, which drops the negative half and brings the clipping back. Because the two cancel, content always rests exactly `--modal-gap` from the header and footer whatever the bleed is; what the bleed sets is where scrolling content is *clipped*, at `gap - bleed` from each. It defaults to half the gap, putting that edge midway between the chrome and where the content rests.
+
+**Scrolling.** Content dissolves into the edge it is scrolling past rather than being cut off against it: a `mask-image` fades the top of the body while content is hidden above, and the bottom while content continues below. Each end is independent, and both are fully opaque on a dialog that doesn't scroll, so a short modal renders exactly as before. A line sliced clean in half is what a rule or a shadow at that boundary would leave in place, which is why neither is used. Set `styles={{ body: { overflow: 'hidden' } }}` — for content that scrolls itself, say a `VirtualList` — and the fade goes quiet with it, rather than dimming content nobody can scroll to.
+
+To switch it off and go back to a hard edge, set `--modal-scroll-fade: 0px`, per instance via `style` or across an app via `ThemeProvider`. It is also off automatically under `prefers-contrast: more`, since fading text costs contrast at exactly the edge someone may be reading.
 
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Modal: { presentation: Presentation.Auto } }}` — which also covers `DatePicker`, `TimeInput` and `KlipyPicker` when they open in a Modal via their own `isModal`. `presentation={Presentation.Auto}` on the provider itself sets every sheet-capable component at once. See [ConfigProvider.md](ConfigProvider.md).
 
 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`
+**Slots:** `container` `backdrop` `modal` `header` `title` `closeButton` `body` `footer`
 
 **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

@@ -31,7 +31,7 @@ const [value, setValue] = useState<MultiSelectValue[]>([]);
 <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 labels={{ create: (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} />
@@ -84,7 +84,7 @@ import { Presentation } from '@ahrowe/ui';
 | `errorMessage` | `string` | Manual error, shown in a tooltip when there's no validator |
 | `isValid` | `boolean` | Manual valid state (default `true`) |
 
-**Keyboard:** `↓` or `Enter` opens the panel. `↑`/`↓` move the highlight and wrap around, `Home`/`End` jump to the ends, `Enter` toggles the highlighted option, `Escape` closes. `Backspace` removes the last selection when the search box is empty. With `searchable`, focus moves into the search box on open and the same keys work from there.
+**Keyboard:** `↓` or `Enter` opens the panel. `↑`/`↓` move the highlight and wrap around, skipping options that cannot be picked — a disabled one, or any unselected one once `maxSelected` is reached. `Home`/`End` jump to the ends, `Enter` toggles the highlighted option, `Escape` closes. The panel scrolls to keep the highlighted option in view. `Backspace` removes the last selection when the search box is empty. With `searchable`, focus moves into the search box on open and the same keys work from there.
 
 **Accessibility:** the control is a `role="combobox"` with `aria-expanded`, `aria-haspopup="listbox"` and `aria-controls`; the panel is a `role="listbox"` with `aria-multiselectable="true"`, and each option carries `aria-selected`. The highlighted option is reported through `aria-activedescendant`, so focus stays on the control (or the search box) rather than moving between options. Each chip's remove button is labelled `Remove <label>`.
 

package/docs/Pagination.md

@@ -1,6 +1,6 @@
 # Pagination
 
-**When to use:** Move through server-paged results a page at a time — a results list, an admin table, a report. For endless scrolling instead, use `InfiniteBlock`; for a long list that's all in memory, use `VirtualList`.
+**When to use:** Move through server-paged results a page at a time — a results list, an admin table, a report. For endless scrolling instead, or for a long list that's all in memory, use `VirtualList`.
 
 **Keywords:** pager, paging, page numbers, next page, previous page, page navigation, offset, results
 

package/docs/Popover.md

@@ -69,10 +69,14 @@ import { Popover, PopoverPlacement, PopoverAlign, PopoverTrigger } from '@ahrowe
 
 **Bottom sheet:** `presentation={Presentation.Sheet}` drops the anchoring and the arrow, and pins the panel to the bottom of the screen instead — full width up to 560px, behind a backdrop, scrolling internally past 70% of the viewport height, lifted above an open on-screen keyboard, and shrunk to fit the space that leaves rather than running off the top of the screen. Scrolling on the page behind it is locked while it's open, and tapping the backdrop closes it without pressing whatever sits behind it (`closeOnOutsideClick={false}` leaves the backdrop inert but still blocking). `Presentation.Auto` applies that only when the pointer is coarse *and* the screen is under 768px wide.
 
+**Sheet dimensions:** as a sheet it spans the full width up to `--sheet-max-width` (560px) and centres beyond it, caps its height at `--sheet-max-height` (70dvh) of the space actually visible, and clears a phone's home indicator with `--sheet-safe-padding` (8px, or the device's own safe-area inset where that is larger). Set any of them per instance via `style` or theme-wide via `ThemeProvider`.
+
 Only a `Click` trigger presents as a sheet. `Hover` and `Focus` open something small next to whatever caused them, which is the opposite of a screen-owning sheet, so they stay anchored regardless of `presentation`.
 
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Popover: { presentation: Presentation.Auto } }}`, or `presentation={Presentation.Auto}` on the provider itself to set every sheet-capable component at once. See [ConfigProvider.md](ConfigProvider.md).
 
 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/RadioGroup.md

@@ -66,7 +66,7 @@ interface RadioOption {
 | `onChange` | `(value, event?) => void` | Fires with the newly selected value |
 | `orientation` | `RadioGroupOrientation` | Layout direction (default `Vertical`) |
 | `disabled` | `boolean` | Disable the whole group |
-| `size` | `string` | Diameter of the radio circle (default `'18px'`) |
+| `size` | `string` | Diameter of the radio circle. Defaults to `1.125em` of `--default-font-size`, i.e. 18px at a 16px base |
 | `formValidator` | `FormValidator` | Connects to form validation |
 | `errorMessage` | `string` | Manual error message (when not using a `formValidator`) |
 | `isValid` | `boolean` | Manual valid state (default `true`) |