@ahrowe/ui 0.34.0 → 0.36.0

package/docs/CLAUDE.md

@@ -1,193 +1,123 @@
-# ahrowe-ui — Claude Code Reference
-
-Package name: `@ahrowe/ui`  
-Install: `npm install @ahrowe/ui`  
-Import: `import { Button, Input, Card, ... } from '@ahrowe/ui'`  
-CSS: `import '@ahrowe/ui/style.css'` (add once in your app entry point)
-
-## Required: ThemeProvider
-
-Wrap your app (or the root layout) with `ThemeProvider`. Without it, CSS variables are undefined and components will be unstyled.
-
-```tsx
-import { ThemeProvider } from '@ahrowe/ui';
-
-// Minimal — uses built-in defaults
-<ThemeProvider>
-  <App />
-</ThemeProvider>
-
-// With a custom theme
-import type { Theme } from '@ahrowe/ui';
-const myTheme: Theme = {
-  id: 'brand',
-  variables: {
-    '--primary-color': '#6200ea',
-    '--primary-lighter': '#b388ff',
-    '--background': '#ffffff',
-    '--text-color': '#212121',
-  },
-};
-<ThemeProvider themes={[myTheme]} currentThemeId="brand">
-  <App />
-</ThemeProvider>
-```
-
-`useTheme()` hook returns `{ currentThemeId, setTheme }` for theme switching.
-
-## FormValidator (for form-connected components)
-
-Input, NumberInput, Dropdown, Checkbox, DatePicker, IconPicker, InputDropdown, and Textarea all accept a `formValidator` prop. Use it to connect validation state.
-
-```tsx
-import { FormValidator, Validators, Input } from '@ahrowe/ui';
-
-// Create with initial value and optional validators
-const nameValidator = new FormValidator('', [Validators.required(), Validators.minLength(2)]);
-
-// Pass to component — it tracks value, dirty, touched, errors internally
-<Input label="Name" formValidator={nameValidator} />
-```
-
-For multi-field forms with a single submit handler, use `useFormValidatorGroup`:
-
-```tsx
-import { useFormValidatorGroup, FormValidator, Validators } from '@ahrowe/ui';
-
-const form = useFormValidatorGroup(
-  {
-    name:  new FormValidator('', [Validators.required()]),
-    email: new FormValidator('', [Validators.required(), Validators.email()]),
-  },
-  { onSubmit: async (values) => save(values) }, // values is fully typed
-);
-
-<form.Form>
-  <Input label="Name"  formValidator={form.group.name} />
-  <Input label="Email" formValidator={form.group.email} />
-</form.Form>
-```
-
-Full reference: see **FormValidator.md** (single field, all built-in validators, custom validators) and **FormValidatorGroup.md** (whole-form submit, validate, reset, server-error mapping) below.
-
-## Slot customisation (classNames / styles)
-
-Most components expose `classNames` and `styles` props for styling inner elements without fighting CSS specificity.
-
-```tsx
-// className / style → root element
-// classNames.<slot> → named inner element
-// styles.<slot>     → inline style on inner element
-
-<Button
-  className="my-btn"
-  classNames={{ background: 'my-bg', label: 'my-label' }}
-  styles={{ background: { borderRadius: '99px' } }}
->
-  Save
-</Button>
-```
-
-Slot keys per component are documented in each component's doc file below.
-
-## Icon props (`IconDefinition | ReactElement`)
-
-Every `icon` prop (and every icon field inside an item/action object) accepts either a
-FontAwesome `IconDefinition` or an arbitrary React node — an inline `<svg>`, an `<img>`,
-or another icon library's component.
-
-```tsx
-import { faPen } from '@fortawesome/free-solid-svg-icons';
-
-<Button icon={faPen}>Edit</Button>                    // FontAwesome
-<Button icon={<MyIcon />}>Edit</Button>               // any React node
-<Button icon={<img src="/pen.svg" alt="" />}>Edit</Button>
-```
-
-A definition is rendered through `FontAwesomeIcon`; an element is rendered as-is, wrapped in a
-`<span>` carrying the component's icon class when that slot is styled. A custom element is not
-sized by FontAwesome's `1em` geometry, so give it its own width/height if the surrounding
-layout expects a square icon.
-
-`IconPicker` and the internal `AnimatedIcon` are the exceptions — their behaviour depends on
-FontAwesome internals, so they still take an `IconDefinition` only.
-
-## Component docs
-
-@Accordion.md
-@ActionButtons.md
-@ActionIcon.md
-@Alert.md
-@AnimatedLogo.md
-@AnimatedText.md
-@Avatar.md
-@Badge.md
-@BodyEnd.md
-@Breadcrumb.md
-@Button.md
-@ButtonGroup.md
-@Card.md
-@Carousel.md
-@Checkbox.md
-@Chip.md
-@ColorPicker.md
-@ConfigProvider.md
-@ConfirmModal.md
-@DatePicker.md
-@Divider.md
-@Drawer.md
-@Dropdown.md
-@DropZone.md
-@EmptyState.md
-@ErrorBoundary.md
-@Fab.md
-@Flip.md
-@FloorPlan.md
-@FormValidator.md
-@FormValidatorGroup.md
-@IconPicker.md
-@IdleManager.md
-@InfiniteBlock.md
-@Input.md
-@InputDropdown.md
-@InteractableDiv.md
-@KanbanBoard.md
-@KlipyPicker.md
-@Loading.md
-@Menu.md
-@Modal.md
-@MultiSelect.md
-@NumberInput.md
-@OptionPicker.md
-@OtpInput.md
-@Overscroll.md
-@Pagination.md
-@Popover.md
-@ProgressBar.md
-@RadioGroup.md
-@Rating.md
-@RevealLens.md
-@Ripple.md
-@RoomDrawer.md
-@RoomViewer.md
-@ScrollbarProvider.md
-@SearchInput.md
-@SectionHeader.md
-@Skeleton.md
-@Slider.md
-@SplitButton.md
-@Stepper.md
-@Sticky.md
-@Switch.md
-@TabHeader.md
-@Textarea.md
-@ThemeProvider.md
-@Tilt.md
-@TimeInput.md
-@Timeline.md
-@Timer.md
-@Toast.md
-@Tooltip.md
-@Tree.md
-@VirtualList.md
-@Wizard.md
+# @ahrowe/ui
+
+React 19 component library. `npm install @ahrowe/ui`, import everything from `@ahrowe/ui`, and
+import `@ahrowe/ui/style.css` once in the app entry.
+
+**Before using a component, read its doc: `node_modules/@ahrowe/ui/docs/<Doc>`**, where `<Doc>` is
+the first column of the table below. The doc has the import line, runnable examples, key props,
+enums and slot names. Do not infer props from a component's name.
+
+## Rules for every component
+
+- **`ThemeProvider` is required.** It injects the CSS variables every component paints with;
+  without it they render unstyled. Wrap the app once. Two themes ship, `defaultTheme` (dark) and
+  `lightTheme`; a custom theme is `{ id, variables: { '--primary-color': '#6200ea', … } }` passed
+  through `themes`, selected with `currentThemeId`. `useTheme()` switches at runtime. The variable
+  list is in ThemeProvider.md.
+- **Portals need a host.** Modal, Tooltip, Popover, Toast and Menu render into `<div id="bodyEnd" />`.
+  Put it inside `ThemeProvider`, once.
+- **Form components** (Input, NumberInput, Dropdown, MultiSelect, InputDropdown, Checkbox, Switch,
+  RadioGroup, DatePicker, TimeInput, OtpInput, IconPicker) take `formValidator`, which then owns
+  the value: `new FormValidator('', [Validators.required()])`. Whole forms use
+  `useFormValidatorGroup`. See FormValidator.md and FormValidatorGroup.md.
+- **Styling.** `className` and `style` hit the root element; `classNames.<slot>` and `styles.<slot>`
+  hit named inner elements. Slot names are on each doc's **Slots** line. Every native attribute of
+  the root element passes through (`id`, `aria-*`, `data-*`, `on*`).
+- **Text a component renders itself** (close buttons, empty messages, page labels) is set with its
+  `labels` prop. App-wide defaults for any prop go through `ConfigProvider` (ConfigProvider.md).
+- **Variants are enums**, not strings: `ButtonStyleType.Primary`, `ButtonSize.Small`. Each doc lists
+  them under **Enums**.
+- **`icon` props** take a FontAwesome `IconDefinition` or any React element.
+- **`ref`** is a plain prop, there is no `forwardRef`. It lands on the element you would reach for:
+  Input, Textarea, NumberInput and SearchInput hand out their inner `<input>`. Timer, Flip, Tilt,
+  Ripple, VirtualList, RoomDrawer and RoomViewer expose an imperative handle instead; its type is
+  exported next to the props.
+- Every module is `'use client'`; nothing renders on the server. No right-to-left support.
+  `prefers-reduced-motion` is honoured. Built for Chrome and Edge 111, Firefox 114, Safari 16.4
+  and newer, with no polyfills. The package is 0.x: a minor can break, a patch cannot.
+
+## Components
+
+<!-- components:start -->
+
+| Doc | Exports | When to use |
+|-----|---------|-------------|
+| Accordion.md | Accordion | Collapsible sections for progressive disclosure — FAQs, settings panels, long-form content that users expand on demand |
+| ActionButtons.md | ActionButtons | Standardised Submit / Cancel button pair for forms, dialogs, and drawer footers |
+| ActionIcon.md | ActionIcon | Clickable icon button without a label — toolbar actions, table row actions, icon-only controls |
+| Alert.md | Alert, AlertStyleType | A persistent inline status message, used for form-level errors, page/section banners, empty-config warnings, and "here's what changed" notices |
+| AnimatedLogo.md | AnimatedLogo | A self-drawing SVG mark for splash/loading screens, empty states, or anywhere a brand or icon mark should feel alive rather than static |
+| AnimatedText.md | AnimatedText, AnimatedTextVariant, AnimatedTextUnit | Decorative text entrance or emphasis effect, for hero headlines, empty-state messages, "premium"/"new" callouts, loading/decoding states |
+| Avatar.md | Avatar, AvatarGroup | User or entity image — profile pictures, comment authors, member lists |
+| Badge.md | Badge, BadgeStyleType, BadgePosition | Small count or status indicator — unread counts, notification dots, "new" markers |
+| BodyEnd.md | BodyEnd | Renders children via a React portal into a `#bodyEnd` DOM node |
+| Breadcrumb.md | Breadcrumb | A trail showing the current page's position within a hierarchy, with links back to each ancestor, such as a file browser path, a category/subcategory drill-down, or a multi-level settings page |
+| Button.md | Button, ButtonStyleType, ButtonSize, ButtonType | Primary interactive action trigger |
+| ButtonGroup.md | ButtonGroup, ButtonGroupOrientation | Joins a row (or column) of buttons into a single seamless control, merging their borders and rounding only the outer corners |
+| Card.md | Card, CardStyleType, CardHeader, CardMedia, CardContent, CardActions | Surface container for grouping related content — list items, profile cards, dashboard tiles, product listings |
+| Carousel.md | Carousel | A slide track for stepping through a set of items one at a time, with arrows, dots, and drag/swipe support, plus optional autoplay |
+| Checkbox.md | Checkbox | Boolean toggle input — settings, multi-select lists, accept terms, feature flags |
+| Chip.md | Chip, ChipContainer, ChipStyleType | Compact tag, label, or filter token — selected items, applied filters, category badges, user avatars with remove |
+| ColorPicker.md | ColorPicker | Hex colour selection — theme editors, annotation tools, customisation panels |
+| ConfigProvider.md | ConfigProvider | Set global **default props** for library components once, near the root of your app, instead of repeating the same prop on every instance |
+| ConfirmModal.md | ConfirmModal | Confirmation dialog before destructive or irreversible actions — delete, archive, send, overwrite |
+| DatePicker.md | DatePicker | Date selection input — booking forms, birth date fields, date range pickers, deadline selectors |
+| Divider.md | Divider, DividerTextPosition, DividerOrientation | A rule that separates sections of content — horizontal by default, filling the width of its parent |
+| Drawer.md | Drawer | Inline horizontal panel that collapses and expands by animating its width — side panels, navigation rails, detail/filter panes that slide open beside the main content |
+| DropZone.md | DropZone, DropZoneReturnType, DropZoneStatus | Drag-and-drop file upload area, optionally click-to-open the native picker |
+| Dropdown.md | Dropdown | Single-value selection from a list — country pickers, status selectors, category filters, any select-style input |
+| EmptyState.md | EmptyState | Placeholder shown when a list, table, or search result has no items — empty inboxes, no search matches, freshly-created sections |
+| ErrorBoundary.md | ErrorBoundary | Wrap any subtree whose render errors shouldn't take down the rest of the app — a widget, a route, a third-party embed, a list row |
+| Fab.md | Fab | Floating action button — primary screen action (create, add, compose), optionally with a speed-dial sub-menu |
+| Flip.md | Flip | Flip a front/back pair of content 180°, like a physical playing card |
+| FloorPlan.md | emptyFloorPlan, addWall, derivePlan | The shared data model behind `RoomDrawer` and `RoomViewer` |
+| FormValidator.md | FormValidator, Validators, useFormValidator | Track and validate a single form field's value, dirty/touched state, and errors |
+| FormValidatorGroup.md | useFormValidatorGroup, FormValidatorGroup, FormValidator, Validators | Manage a whole form — multiple fields, a single submit handler, validate-on-submit, dirty/touched tracking across the form, and mapping server-side errors back onto the right fields |
+| IconPicker.md | IconPicker | Pick one item from a visual icon/image grid — category selectors, emoji-style pickers, avatar selectors, anything where each option is best represented by an icon or image rather than text alone |
+| IdleManager.md | IdleManager | 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 |
+| Input.md | Input, InputType | Text input with floating label, validation state, and type variants |
+| InputDropdown.md | InputDropdown | Combobox-style input — the user can type to filter and also pick from a dropdown list |
+| InteractableDiv.md | InteractableDiv | Accessible `<div>` that behaves like a button — click and keyboard (Enter/Space) events, with proper ARIA semantics |
+| KanbanBoard.md | KanbanBoard, KanbanColumn | Drag-and-drop board with columns — task management, workflow stages, status boards (e.g. Todo / In Progress / Done) |
+| KlipyPicker.md | KlipyPicker | GIF picker backed by the Klipy API — chat reactions, message composers, content authoring tools |
+| Loading.md | IconLoading, SpinnerLoading | Loading indicators for async operations — page loads, data fetching, button actions (when not using Button's built-in `isLoading`) |
+| Menu.md | Menu | A list of actions hanging off a trigger — a row's "more" button, a toolbar overflow, a context menu on a card |
+| Modal.md | Modal | Full overlay dialog — forms, detail views, confirmations, wizards that need to block the rest of the UI |
+| MultiSelect.md | MultiSelect | Pick several options from a list |
+| NumberInput.md | NumberInput | Numeric input with formatting — prices, quantities, percentages, phone numbers with separators |
+| OptionPicker.md | OptionPicker | Segmented control for picking exactly one option from a small set — view modes, sort directions, simple tab-like switches |
+| OtpInput.md | OtpInput, OtpInputCharset | A one-time-passcode / verification-code input, rendered as one box per character |
+| Overscroll.md | Overscroll | Mobile-style collapsing header that shrinks as the user scrolls — profile pages, detail screens, anywhere a large hero area should yield space to content on scroll |
+| Pagination.md | Pagination | Move through server-paged results a page at a time — a results list, an admin table, a report |
+| Popover.md | Popover | Any panel anchored to a trigger: profile cards, quick forms, action menus, pickers, filter dropdowns |
+| ProgressBar.md | ProgressBar | Visual progress indicator — file uploads, multi-step completion, storage usage, stacked stats (e.g. budget breakdown) |
+| RadioGroup.md | RadioGroup, RadioGroupOrientation | Single-choice selection from a small, always-visible set of options — plan pickers, shipping methods, yes/no/maybe, settings with 2–5 mutually exclusive choices |
+| Rating.md | Rating | A star rating input or display, for review scores, feedback prompts, and quality indicators |
+| RevealLens.md | RevealLens | A two-layer reveal/magnifier effect — an `overlay` covers a `background` by default, and moving the pointer over the component uncovers the `background` in an area around the cursor |
+| Ripple.md | Ripple | Material-style ink ripple effect on any interactive element — buttons, list items, cards, tiles |
+| RoomDrawer.md | RoomDrawer | An interactive floor plan editor |
+| RoomViewer.md | RoomViewer | Shows a floor plan someone can look at and click, without letting them change it — a building directory, a booking screen, a dashboard beside a room list |
+| ScrollFade.md | ScrollFade, ScrollFadeAxis | A scrollable box whose content dissolves at the edge it is scrolling past, instead of being cut off mid-line against it |
+| ScrollbarProvider.md | ScrollbarProvider | Applies custom scrollbar styling to a scrollable region — use to keep scrollbar appearance consistent with the theme |
+| SearchInput.md | SearchInput | Search field with built-in debouncing and an optional result count line — list filters, search-as-you-type pages |
+| SectionHeader.md | SectionHeader, SectionHeaderSize | A reusable heading block for the top of a page, panel, card, or any section — a title with an optional subtitle, a leading icon or thumbnail, and a trailing actions area |
+| Skeleton.md | Skeleton, SkeletonVariant, SkeletonAnimation | Content-shaped loading placeholder, shown while real content is being fetched — more polished than a spinner for content-heavy pages (lists, cards, profile headers) |
+| Slider.md | Slider | Let the user pick a number from a continuous or stepped range by dragging a thumb: volume, brightness, price ranges, zoom, quality presets |
+| SplitButton.md | SplitButton | A primary action button with a small attached dropdown for closely related secondary actions, e.g. "Save ▾" opening "Save as draft" / "Save and close" |
+| Stepper.md | Stepper | Step progress indicator for multi-step forms, onboarding flows, and checkout wizards |
+| Sticky.md | Sticky | Pin a piece of content to the top of the viewport once the page scrolls past it — section headers, toolbars, filter bars, table headers |
+| Switch.md | Switch | Sliding boolean toggle — settings panels, feature flags, preference lists |
+| TabHeader.md | TabHeader | A horizontal row of tabs to switch between sibling views or sections — settings panels, dashboards, detail pages |
+| Textarea.md | Textarea | Multiline text input — comments, descriptions, notes, code snippets, long-form content |
+| ThemeProvider.md | ThemeProvider | Required wrapper for the entire component library |
+| Tilt.md | Tilt, TiltGroup | Wrap content that should tilt toward the cursor in 3D |
+| TimeInput.md | TimeInput | Time-of-day selection — appointment times, opening hours, shift starts, reminders |
+| Timeline.md | Timeline, TimelineAlignment, TimelineItemStatus | A vertical list of dated events, connected by a line, for audit logs, activity feeds, order status history, and deploy logs |
+| Timer.md | Timer | A countdown timer with a depleting ring, add/remove-time and pause/cancel controls, and an imperative ref API |
+| Toast.md | ToastProvider, showToast | Non-blocking notifications — save confirmations, error alerts, info messages, warnings |
+| Tooltip.md | Tooltip | Contextual help, info icons, field explanations, error pointers |
+| Tree.md | Tree, flattenTree | A hierarchical list the user can expand, collapse and pick from: categories, nested locations, folder structures, org charts |
+| VirtualList.md | VirtualList | Efficiently render large lists or tables — thousands of rows rendered with a virtualised scroll window so only visible rows are in the DOM |
+| Wizard.md | Wizard | Animated step container for multi-step forms and flows |
+
+<!-- components:end -->

package/docs/Card.md

@@ -56,11 +56,12 @@ All sub-components are optional — use only what you need. Stacked sub-componen
 | Prop | Type | Description |
 |------|------|-------------|
 | `styleType` | `CardStyleType` | Surface variant — `Elevated` (fill + shadow), `Outlined` (transparent + border), `Filled` (flat fill) |
-| `onClick` | `() => void` | Makes card clickable |
+| `onClick` | `() => void` | Makes the card clickable, by pointer and by Enter/Space. A click or key on a control inside the card (a field, a link, a button, anything with an interactive `role`) is that control's, and neither fires this nor ripples |
 | `hoverEffect` | `boolean` | Adds hover elevation |
 | `tabIndex` | `number \| null` | For keyboard navigation |
 | `autoGap` | `boolean` | Space stacked sub-components apart with a shared gap (default `true`); set `false` to space them yourself |
 | `clip` | `boolean` | Clip content to the rounded corners (`overflow: hidden`, default `false`). Set `true` for full-bleed `CardMedia` or a clipped hover/ripple effect. Safe to enable even when the card holds a `Dropdown`/`Popover`/`Tooltip` — those popovers are portaled and always escape the card regardless of this setting |
+| `ref` | `Ref<HTMLDivElement>` | Ref to the root element |
 
 **CardHeaderProps:**
 

package/docs/Checkbox.md

@@ -36,6 +36,7 @@ const agreedValidator = new FormValidator(false, [Validators.required()]);
 | `isLoading` | `boolean` | Shows skeleton state |
 | `children` | `ReactNode` | Custom label content |
 | `cursorDefault` | `boolean` | Use default cursor instead of pointer |
+| `ref` | `Ref<HTMLDivElement>` | Ref to the root element |
 
 **Slots:** `icon` `checkmark` `label`
 

package/docs/ColorPicker.md

@@ -51,8 +51,18 @@ The inline swatch tracks the theme's text size, since it sits beside a label: `-
 
 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`.
+**Labels:** `pickFromScreen`, `saturationAndBrightness`, `saturationAndBrightnessValue(saturation, brightness)` — 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`.
 
-**Keyboard:** the swatch is a button, so `Enter` or `Space` opens the panel and puts the focus on the hue slider, the arrow keys move it, `Tab` walks the rest of the panel, and `Escape` closes and hands the focus back. The saturation and value square is a pointer control with no keyboard equivalent; the hex field covers the same ground for anyone not using a mouse.
+**Keyboard:** the swatch is a button, so `Enter` or `Space` opens the panel and puts the focus on the saturation and brightness square. A click leaves the focus on the swatch, since a pointer open is not a request to be taken somewhere. `Tab` walks the rest of the panel, and `Escape` closes and hands the focus back to the swatch.
+
+| Key | Does |
+|-----|------|
+| `←` `→` | Saturation, a percent at a time |
+| `↑` `↓` | Brightness, a percent at a time |
+| `Shift` with any arrow | Ten at a time |
+| `Home` `End` | Saturation to either end |
+| `PageUp` `PageDown` | Brightness to either end |
+
+The square is a two-axis control, which ARIA has no role for. It reports itself as a slider whose value is the horizontal axis, with `aria-valuetext` carrying both numbers, so a screen reader reads out "62% saturation, 40% brightness" after every move.
 
 **Slots:** `root` `swatch` `panel` `gradient` `hueSlider` `alphaSlider` `hexInput` `eyeDropper`

package/docs/Divider.md

@@ -2,6 +2,8 @@
 
 **When to use:** A rule that separates sections of content — horizontal by default, filling the width of its parent. Optionally label it with text (e.g. "OR", a date, a section name); the line splits around the text, leaving a gap for it. Set `orientation` to `Vertical` for a vertical line filling the height of its parent instead, e.g. as a separator between two buttons in a `ButtonGroup`.
 
+**Keywords:** separator, hr, spacer
+
 **Import:** `import { Divider, DividerTextPosition, DividerOrientation } from '@ahrowe/ui'`
 
 **Text position:** `DividerTextPosition.Left` | `DividerTextPosition.Center` (default) | `DividerTextPosition.Right`

package/docs/Dropdown.md

@@ -66,4 +66,24 @@ The list is rendered through a portal and tracks the trigger across scroll, so i
 
 **Bottom sheet:** `presentation={Presentation.Sheet}` drops the anchoring entirely and pins the list to the bottom of the screen instead, full width up to 560px, behind a backdrop, scrolling internally past 70% of the viewport height and lifting itself above an open on-screen keyboard, shrinking to fit the space that leaves rather than running off the top of the screen. Tapping the backdrop closes the list without also pressing whatever sits behind it. It is the same list with the same keyboard handling, so selection, highlighting and infinite scroll are unchanged. `Presentation.Auto` does that only when the pointer is coarse *and* the screen is under 768px wide. The default is `Presentation.Default`. A whole app can opt in with `<ConfigProvider defaultProps={{ Dropdown: { presentation: Presentation.Auto } }}>`, or for every sheet-capable component at once with `<ConfigProvider presentation={Presentation.Auto}>` — see [ConfigProvider.md](ConfigProvider.md).
 
+**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`.
+
+**Keyboard:** `ArrowDown` / `ArrowUp` open the list and move the highlight, wrapping at the ends and
+skipping disabled items. `Home` / `End` jump to the first and last. `Enter` and `Space` open the list,
+then pick the highlighted item. `Escape` and `Tab` close it without selecting. Typing a letter jumps to
+the next item whose label starts with it, as a native `<select>` does; typing while the list is closed
+selects that item outright. Keystrokes within half a second of each other match as one prefix.
+
+**Screen readers:** the trigger is a `combobox` named by the field's `label`, with the selected item as
+its value, `aria-expanded`, and `aria-activedescendant` pointing at the highlighted option while the
+list is open. The list is a `listbox` of `option`s carrying `aria-selected` and `aria-disabled`. The
+chevron is `aria-hidden`, because it only repeats what the trigger already offers. The focus stays on
+the trigger the whole time the list is open.
+
+Nothing highlights on open unless `scrollToSelected` is set, which starts on the current value.
+
+**Width:** the control fills its container, the way `Input` and `MultiSelect` do. Constrain it from the
+outside (a wrapper, a grid column, `style={{ maxWidth: 240 }}`) rather than expecting it to size itself
+to the label: everything inside is absolutely positioned, so it has no width of its own to fall back on.
+
 **Slots:** `root` `label` `field` `control` `icon` `placeholder` `list` `option`

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/Input.md

@@ -122,6 +122,7 @@ The stored value is the formatted one, spaces included, so strip them before a l
 | `parse` | `(value: string) => string` | Transform the value on every change, before `onChange`/`formValidator` — also what gets rendered (see above) |
 | `isUppercase` | `boolean` | Uppercases the field's rendering (CSS only — the stored value is unchanged; use `parse` to uppercase the value itself) |
 | `customInput` | `ReactElement` | Element rendered in place of the internal `<input>`, cloned with all of Input's props. The escape hatch for a mask library; note `autoFocus` and `autoResize` stop working, since Input cannot attach its ref |
+| `ref` | `Ref<HTMLInputElement \| HTMLTextAreaElement>` | Ref to the inner field, not the wrapper. Not forwarded to a `customInput` |
 
 **Slots:** `label` `container` `input` `suffix` `upperRightLabel` `fieldset`
 

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

@@ -6,7 +6,7 @@
 
 **Import:** `import { KlipyPicker } from '@ahrowe/ui'`
 
-**Requires:** `<div id="bodyEnd"></div>` in your HTML when `isModal` is used (Modal renders via portal). A Klipy API token — the component ships with a default key, but supply your own `token` prop for production use.
+**Requires:** `<div id="bodyEnd"></div>` in your HTML when `isModal` is used (Modal renders via portal). A Klipy API token, passed as the `token` prop. There is no built-in key: without one the picker renders but every request fails.
 
 ```tsx
 import { KlipyPicker } from '@ahrowe/ui';
@@ -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

@@ -2,6 +2,8 @@
 
 **When to use:** Loading indicators for async operations — page loads, data fetching, button actions (when not using Button's built-in `isLoading`).
 
+**Keywords:** busy, waiting, activity indicator, throbber
+
 **Import:** `import { IconLoading, SpinnerLoading } from '@ahrowe/ui'`
 
 ```tsx
@@ -22,4 +24,4 @@ import { IconLoading, SpinnerLoading } from '@ahrowe/ui';
 - `SpinnerLoading` — circular progress ring, good for full-area loading states
 - Both components accept `className` for sizing/positioning
 
-Check [package/common/loading/](../common/loading/) for full prop details.
+Check [package/common/loading/](https://github.com/AndreasWeinzierl/ahrowe-ui/tree/master/package/common/loading) for full prop details.

package/docs/Menu.md

@@ -104,4 +104,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`.