@ahrowe/ui 0.33.0 → 0.35.0

package/dist/types/common/tilt/tilt.d.ts

@@ -1,3 +1,3 @@
-import { TiltHandle, TiltProps } from './tilt.types';
-declare const Tilt: import('react').ForwardRefExoticComponent<TiltProps & import('react').RefAttributes<TiltHandle>>;
+import { TiltProps } from './tilt.types';
+declare function Tilt(props: TiltProps): import("react").JSX.Element;
 export default Tilt;

package/dist/types/common/tilt/tilt.types.d.ts

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactNode } from 'react';
+import { CSSProperties, ReactNode, Ref } from 'react';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 import { TiltAxisLock } from './tiltMath';
 export type TiltTrackingMode = 'self' | 'group';
@@ -31,6 +31,8 @@ export interface TiltProps extends HtmlProps {
     disabled?: boolean;
     /** Fires on every applied tilt update. */
     onTiltChange?: (rotateX: number, rotateY: number) => void;
+    /** Imperative handle for driving the tilt directly. */
+    ref?: Ref<TiltHandle>;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<TiltSlots>;

package/dist/types/common/timer/timer.d.ts

@@ -1,3 +1,3 @@
-import { TimerHandle, TimerProps } from './timer.types';
-declare const Timer: import('react').ForwardRefExoticComponent<TimerProps & import('react').RefAttributes<TimerHandle>>;
+import { TimerProps } from './timer.types';
+declare function Timer(props: TimerProps): import("react").JSX.Element;
 export default Timer;

package/dist/types/common/timer/timer.types.d.ts

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactNode } from 'react';
+import { CSSProperties, ReactNode, Ref } from 'react';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export type TimerSlots = 'root' | 'ringWrapper' | 'ringSvg' | 'ringTrack' | 'ringProgress' | 'ripples' | 'ripple' | 'display' | 'time' | 'label' | 'controls' | 'addButton' | 'removeButton' | 'pauseButton' | 'cancelButton';
 export type TimerStatus = 'idle' | 'running' | 'paused' | 'completed' | 'cancelled';
@@ -99,6 +99,8 @@ export interface TimerProps extends HtmlProps {
     notificationTitle?: string;
     /** Notification body when `notifyOnComplete` is set. Falls back to `label` when it's a string. */
     notificationBody?: string;
+    /** Imperative handle for starting, pausing and resetting the timer. */
+    ref?: Ref<TimerHandle>;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<TimerSlots>;

package/dist/types/common/tooltip/tooltip.d.ts

@@ -1,3 +1,3 @@
 import { default as React } from 'react';
 import { TooltipProps } from './tooltip.types';
-export default function Tooltip({ variant, message, isVisible, tooltipPosition, onClick }: TooltipProps): React.JSX.Element | null;
+export default function Tooltip({ variant, message, isVisible, tooltipPosition, onClick, labels, }: TooltipProps): React.JSX.Element | null;

package/dist/types/common/tooltip/tooltip.types.d.ts

@@ -1,5 +1,10 @@
 import { default as React } from 'react';
 export type TooltipVariant = 'info' | 'details' | 'error';
+/** Text Tooltip renders of its own, for translating it. */
+export interface TooltipLabels {
+    /** Accessible name of the `?` icon the `details` variant renders (default `More information`). */
+    details?: string;
+}
 export interface TooltipProps {
     variant: TooltipVariant;
     message?: React.ReactNode;
@@ -7,4 +12,6 @@ export interface TooltipProps {
     iconPosition?: string;
     tooltipPosition?: string;
     onClick?: () => void;
+    /** Overrides the text Tooltip renders of its own. Merged per key. */
+    labels?: TooltipLabels;
 }

package/dist/types/common/types/baseProps.types.d.ts

@@ -15,6 +15,12 @@ type DataAttributes = {
  * matching React type instead and add `DataProps` for the `data-*` half — `Button` does this
  * with `React.ButtonHTMLAttributes<HTMLButtonElement>`.
  *
+ * `ref` is deliberately *not* here. `Ref<E>` is invariant, so a shared `Ref<HTMLElement>` is not
+ * assignable to the `<div>` it would be spread onto, and narrowing the default to `HTMLDivElement`
+ * re-types every event handler with it — which breaks `Dropdown` and `SplitButton`, whose `onClick`
+ * is typed for the `<button>` they hand it to. A component that accepts a ref declares it itself,
+ * next to its other props, typed for the element it actually lands on.
+ *
  * A component prop that collides with a native one of the same name must `Omit` the native one.
  */
 export type HtmlProps<E extends HTMLElement = HTMLElement> = React.HTMLAttributes<E> & DataAttributes;

package/dist/types/common/utils/mergeRefs.d.ts

@@ -0,0 +1,12 @@
+import { Ref } from 'react';
+/**
+ * Fans one element out to several refs, for a component that needs the node itself *and*
+ * hands it to the consumer through a `ref` prop.
+ *
+ * The returned callback is a new function on every render, so React detaches and reattaches
+ * it each time (null, then the node). Every ref here is therefore written twice per render,
+ * which is fine for storing a node and wrong for anything with a side effect. Call it inline
+ * rather than memoising: a memo would have to list the refs it closes over, and a consumer
+ * passing an inline callback ref changes that identity every render anyway.
+ */
+export declare function mergeRefs<T>(...refs: (Ref<T> | undefined)[]): (node: T | null) => void;

package/dist/types/common/virtualList/virtualList.d.ts

@@ -1,7 +1,5 @@
 import { default as React } from 'react';
-import { VirtualListProps, VirtualListHandle } from './virtualList.types';
+import { VirtualListProps } from './virtualList.types';
 export { buildOffsets, findStartIndex, getVisibleRange, resolveReorderTarget, resolveTreeDropTarget, lastDescendantIndex, buildColumnTemplate, compareSortValues, isColumnSortable, isEmptySortValue, nextSort, sortItems, } from './virtualList.utils';
-declare const VirtualList: <T>(props: VirtualListProps<T> & {
-    ref?: React.Ref<VirtualListHandle>;
-}) => React.ReactElement | null;
+declare function VirtualList<T>({ ref, items, renderRow, ariaRoles, columns, height, estimatedRowHeight, overscan, rowGap, rowPadding, selectedKey, getItemKey, onRowClick, keyboardNavigation, visibleColumnKeys, onVisibleColumnsChange, persistColumnsKey, resizableColumns, columnWidths, onColumnWidthsChange, labels, sort, defaultSort, onSortChange, showColumnToggle, onLoadMore, loadMoreThreshold, isLoading, multiSelect, selectedKeys, onSelectionChange, reorderable, onReorder, longPressDelay, treeReorder, getItemDepth, isGroup, onTreeDrop, treeIndentPx, dragHandle, showDivider, rowHover, className, style, classNames, styles: slotStyles, ...rest }: VirtualListProps<T>): React.JSX.Element;
 export default VirtualList;

package/dist/types/common/virtualList/virtualList.types.d.ts

@@ -1,4 +1,4 @@
-import { CSSProperties, ReactNode } from 'react';
+import { CSSProperties, ReactNode, Ref } from 'react';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export type ColumnWidthFixed = {
     type: 'fixed';
@@ -308,6 +308,8 @@ export interface VirtualListProps<T> extends HtmlProps {
      * and touch. Render a handle in your row, e.g. `<span data-drag-handle>⠿</span>`.
      */
     dragHandle?: boolean;
+    /** Imperative handle for scrolling and for recalculating column layout. */
+    ref?: Ref<VirtualListHandle>;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<VirtualListSlots>;

package/dist/types/index.d.ts

@@ -53,8 +53,6 @@ export { default as Fab } from './common/fab';
 export * from './common/fab';
 export { default as Flip } from './common/flip';
 export * from './common/flip';
-export { default as FloatingMenu } from './common/floatingMenu';
-export * from './common/floatingMenu';
 export * from './common/floorPlan';
 export { default as IconPicker } from './common/iconPicker';
 export * from './common/iconPicker';
@@ -73,6 +71,8 @@ export * from './common/kanbanBoard';
 export { default as KlipyPicker } from './common/klipyPicker';
 export * from './common/klipyPicker';
 export * from './common/loading';
+export { default as Menu } from './common/menu';
+export * from './common/menu';
 export { default as Modal } from './common/modal';
 export * from './common/modal';
 export { default as MultiSelect } from './common/multiSelect';

package/docs/Accordion.md

@@ -40,6 +40,15 @@ import { Accordion, AccordionStyleType } from '@ahrowe/ui';
 | `hideHeader` | `boolean` | Hide the clickable header |
 | `id` | `string` | Passed back in `onHeaderClicked` |
 
+## Accessibility
+
+The header is a button: it takes focus, toggles on Enter and Space, and reports the section's
+state through `aria-expanded`. It names the body it controls with `aria-controls`, and the body is
+a `role="region"` labelled by the header, so a screen reader can move between the two.
+
+An activation key pressed inside the body does not reach the header, so a Space typed into a
+field in an open section types a space instead of collapsing the section.
+
 **Slots:** `root` `header` `title` `icon` `body` `bodyInner`
 
 ## Sizing

package/docs/ActionIcon.md

@@ -27,3 +27,4 @@ import { faTrash } from '@fortawesome/free-solid-svg-icons';
 | `title` | `string` | Tooltip / accessible label |
 | `onClick` | `(event: MouseEvent) => void` | Click handler |
 | `className` | `string` | Root element class |
+| `ref` | `Ref<HTMLDivElement>` | Ref to the root element |

package/docs/Breadcrumb.md

@@ -68,7 +68,7 @@ function Example() {
 // Long trails: collapse the middle behind a clickable ellipsis once items.length
 // exceeds maxItems. The ellipsis counts as one of the visible slots, so maxItems={3}
 // on a 4-item trail shows: Home / ... / Settings. Clicking the ellipsis opens a menu
-// (via FloatingMenu) listing the hidden items.
+// (via Popover) listing the hidden items.
 <Breadcrumb
   items={[
     { label: 'Home', href: '/' },
@@ -80,7 +80,7 @@ function Example() {
 />
 ```
 
-**Requires:** `<div id="bodyEnd"></div>` in your HTML when `maxItems` is used and the trail actually collapses (the hidden-items menu is a `FloatingMenu`, which renders via portal).
+**Requires:** `<div id="bodyEnd"></div>` in your HTML when `maxItems` is used and the trail actually collapses (the hidden-items menu is a `Popover`, which renders via portal).
 
 **BreadcrumbItem:**
 

package/docs/ButtonGroup.md

@@ -81,6 +81,6 @@ Flattening reaches a child's visible border even when that border doesn't live o
 
 **Separators:** any child with `role="separator"` (what `Divider` sets) is excluded from that border-collapsing margin, on both sides — it stays fully visible between its neighbors instead of being partially hidden under one of them. Use a vertical `Divider` (see [Divider.md](Divider.md)) between two buttons when their style has no visible border of its own to merge (`Primary`, `Delete`), so there's still a clear seam between them.
 
-**Note:** the corner-flattening rules key off DOM position (`:first-child`/`:last-child`), so they work for direct `Button`/`Input`/`Dropdown`-family children out of the box. A child that renders as a wrapper around its own button (e.g. a component that portals its real content elsewhere) won't get the flattening automatically. `SplitButton` is exactly that case (its second child is a `FloatingMenu`-wrapped button), which is why it sets its own corner overrides directly rather than relying on `ButtonGroup`'s automatic ones. See [SplitButton.md](SplitButton.md). A fully custom component whose CSS doesn't reference the `--group-radius-*` variables can still be flattened manually the same way, via its own `classNames`/`styles` slots if it exposes the right one.
+**Note:** the corner-flattening rules key off DOM position (`:first-child`/`:last-child`), so they work for direct `Button`/`Input`/`Dropdown`-family children out of the box. A child that renders as a wrapper around its own button (e.g. a component that portals its real content elsewhere) won't get the flattening automatically. `SplitButton` is exactly that case (its second child is a `Popover`-wrapped button), which is why it sets its own corner overrides directly rather than relying on `ButtonGroup`'s automatic ones. See [SplitButton.md](SplitButton.md). A fully custom component whose CSS doesn't reference the `--group-radius-*` variables can still be flattened manually the same way, via its own `classNames`/`styles` slots if it exposes the right one.
 
 **Slots:** none — `ButtonGroup` has no named inner elements, only `className`/`style` on the root.

package/docs/CLAUDE.md

@@ -90,6 +90,43 @@ Most components expose `classNames` and `styles` props for styling inner element
 
 Slot keys per component are documented in each component's doc file below.
 
+## Refs
+
+The library targets **React 19 or newer**. Every component that takes a ref takes it as a plain
+prop, not through `forwardRef`, so there is nothing to unwrap and a generic component keeps its
+type parameter.
+
+```tsx
+const input = useRef<HTMLInputElement>(null);
+<Input label="Name" ref={input} />;
+input.current?.focus();
+```
+
+A ref lands on the element you would actually reach for, which is not always the root: `Input`,
+`Textarea`, `NumberInput` and `SearchInput` give you the `<input>` or `<textarea>` inside, not
+their wrapper. Components that do more than hold a node expose an imperative handle instead of an
+element: `Timer` (`start`/`pause`/`reset`), `Flip` (`flip`/`setFlipped`/`reset`), `Tilt`
+(`setTilt`/`reset`), `Ripple` (`addRipple`), `VirtualList` (scrolling and column layout),
+`RoomDrawer` and `RoomViewer`. Each handle's type is exported next to the component's props.
+
+## Server components
+
+Every module in the package is marked `'use client'`. All the components are interactive, so none
+of them renders on a server, but they can be imported straight into a React Server Components app
+(Next.js App Router and the like) with no wrapper component in between.
+
+## Right to left
+
+Not supported. The stylesheets use physical CSS properties (`margin-left`, `left`), so the library
+does not mirror for right-to-left languages.
+
+## Reduced motion
+
+Components honour `prefers-reduced-motion: reduce`: entrances, slides, chevron rotations and the
+ink ripple stop, while fades and colour changes stay. Two things deliberately keep moving, because
+freezing them would state something untrue: the loading spinners, and the Toast progress bar that
+shows how long a toast has left.
+
 ## Icon props (`IconDefinition | ReactElement`)
 
 Every `icon` prop (and every icon field inside an item/action object) accepts either a
@@ -142,7 +179,6 @@ FontAwesome internals, so they still take an `IconDefinition` only.
 @ErrorBoundary.md
 @Fab.md
 @Flip.md
-@FloatingMenu.md
 @FloorPlan.md
 @FormValidator.md
 @FormValidatorGroup.md
@@ -155,6 +191,7 @@ FontAwesome internals, so they still take an `IconDefinition` only.
 @KanbanBoard.md
 @KlipyPicker.md
 @Loading.md
+@Menu.md
 @Modal.md
 @MultiSelect.md
 @NumberInput.md

package/docs/Card.md

@@ -60,7 +60,8 @@ All sub-components are optional — use only what you need. Stacked sub-componen
 | `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`/`FloatingMenu`/`Tooltip` — those popovers are portaled and always escape the card regardless of this setting |
+| `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,6 +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 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/ConfigProvider.md

@@ -59,7 +59,7 @@ So a global default only fills in props a given instance left out — any instan
 
 ## App-wide `presentation`
 
-`FloatingMenu`, `Dropdown`, `Popover` and `Modal` can each present as a bottom sheet instead of anchored to their trigger (centred, for `Modal`). They're unrelated components, so setting that through `defaultProps` would mean four entries, and missing one would leave sheets in half an app. `presentation` is the single switch:
+`Popover`, `Menu`, `Dropdown`, `MultiSelect` and `Modal` can each present as a bottom sheet instead of anchored to their trigger (centred, for `Modal`). They're unrelated components, so setting that through `defaultProps` would mean five entries, and missing one would leave sheets in half an app. `presentation` is the single switch:
 
 ```tsx
 // Bottom sheets on small touch screens, everywhere, in one line
@@ -93,7 +93,7 @@ Each entry is a `Partial<...Props>`, so any of that component's props can be def
 
 - **Form inputs:** `Input` · `Textarea` · `NumberInput` · `Dropdown` · `InputDropdown` · `Checkbox` · `Switch` · `RadioGroup` · `DatePicker` · `OptionPicker` · `OtpInput`
 - **Display:** `Button` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Accordion` · `Divider` · `Timer`
-- **Overlays:** `ConfirmModal` · `Modal` · `FloatingMenu` · `Popover`
+- **Overlays:** `ConfirmModal` · `Modal` · `Popover` · `Popover`
 - **Editors:** `RoomDrawer`, `RoomViewer`
 
 ```tsx

package/docs/Dropdown.md

@@ -62,7 +62,7 @@ const statusValidator = new FormValidator('', [Validators.required()]);
 | `presentation` | `Presentation` | Where the list opens: anchored to the input (`Default`), always a bottom sheet, or a sheet only on a small touch screen. Imported from the same package: `import { Presentation } from '@ahrowe/ui'` |
 | `alwaysFloatLabel` | `boolean` | Keep the material label floated in the border notch even when nothing is selected, so an empty dropdown reads as blank instead of showing the label as if it were the selected value. Only applies with `useMatLabelStyle` (default) |
 
-The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). It flips to open upward automatically when there's no room below, and shifts horizontally to stay within the viewport when the trigger sits near the left or right edge of the screen. It hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view. It also re-measures when its own content changes size while open, so a list that shrinks (e.g. filtered down to fewer entries) stays anchored to the trigger instead of hanging above it.
+The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). The panel itself is a [Popover](Popover.md), so it flips, clamps and presents as a bottom sheet the same way every other anchored surface in the library does. It flips to open upward automatically when there's no room below, and shifts horizontally to stay within the viewport when the trigger sits near the left or right edge of the screen. It hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view. It also re-measures when its own content changes size while open, so a list that shrinks (e.g. filtered down to fewer entries) stays anchored to the trigger instead of hanging above it.
 
 **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).
 

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

@@ -71,4 +71,4 @@ interface InputDropdownItem {
 
 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`.
 
-The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). It flips to open upward automatically when there's no room below, and shifts horizontally to stay within the viewport when the trigger sits near the left or right edge of the screen. It hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view. It also re-measures when its own content changes size while open, so a list that shrinks (e.g. filtered down to fewer entries) stays anchored to the trigger instead of hanging above it.
+The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). The panel itself is a [Popover](Popover.md), so it flips, clamps and presents as a bottom sheet the same way every other anchored surface in the library does. It flips to open upward automatically when there's no room below, and shifts horizontally to stay within the viewport when the trigger sits near the left or right edge of the screen. It hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view. It also re-measures when its own content changes size while open, so a list that shrinks (e.g. filtered down to fewer entries) stays anchored to the trigger instead of hanging above it.

package/docs/InteractableDiv.md

@@ -2,6 +2,8 @@
 
 **When to use:** Accessible `<div>` that behaves like a button — click and keyboard (Enter/Space) events, with proper ARIA semantics. Use when you need a custom-styled clickable container that isn't a `<button>`.
 
+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.
+
 **Keywords:** custom button div
 
 **Import:** `import { InteractableDiv } from '@ahrowe/ui'`

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';

package/docs/Menu.md

@@ -0,0 +1,107 @@
+# Menu
+
+**When to use:** A list of actions hanging off a trigger — a row's "more" button, a toolbar overflow, a context menu on a card. Use [Popover](Popover.md) directly when the panel holds something other than a list of actions, and [Dropdown](Dropdown.md) when the user is picking a value rather than doing something.
+
+**Keywords:** context menu, action menu, overflow menu, kebab menu, three dots, popup menu, right click, anchored list
+
+**Import:** `import { Menu } 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.
+
+```tsx
+import { Menu } from '@ahrowe/ui';
+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: 'duplicate', label: 'Duplicate', icon: faCopy },
+  { separator: true },
+  { id: 'delete', label: 'Delete', icon: faTrash, danger: true },
+];
+
+<Menu items={items} onAction={(id) => run(id)}>
+  <Button>Actions</Button>
+</Menu>;
+```
+
+**Entries** are one of three shapes, and the list is read in the order you give it:
+
+```ts
+{ id: 'edit', label: 'Edit', icon, shortcut, disabled, danger, onClick }  // an action
+{ separator: true }                                                       // a line
+{ heading: 'This document' }                                              // a label over what follows
+```
+
+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
+// Grouped, with a heading over each group
+<Menu
+  items={[
+    { heading: 'This document' },
+    { id: 'rename', label: 'Rename' },
+    { separator: true },
+    { heading: 'Elsewhere' },
+    { id: 'open', label: 'Open in a new tab' },
+  ]}
+>
+  <ActionIcon icon={faEllipsisVertical} aria-label='More actions' />
+</Menu>
+
+// A sheet on a small touch screen, anchored everywhere else
+<Menu items={items} presentation={Presentation.Auto}>
+  <Button>Open</Button>
+</Menu>
+```
+
+**Keyboard:** the menu takes one tab stop, and follows the menu-button pattern.
+
+| Key | Does |
+|-----|------|
+| `↓` on the closed trigger | Open, focus the first entry |
+| `↑` on the closed trigger | Open, focus the last entry |
+| `↓` `↑` on the trigger of a menu opened by mouse | Move into the list, at the first or last entry |
+| `↑` `↓` | Move between entries, wrapping, skipping disabled ones |
+| `Home` `End` | First or last entry |
+| a letter | Jump to the next entry that starts with it; keep typing to narrow, or repeat one letter to walk the matches |
+| `Enter` `Space` | Run the focused entry |
+| `Escape` | Close and hand focus back to the trigger |
+| `Tab` | Close, and carry on to whatever follows the trigger, from any entry |
+| `Shift+Tab` | Close, and hand focus back to the trigger |
+
+A click opens the menu without moving the focus, so no entry is marked until you point at one or press an arrow key: a highlight that does not follow the mouse reads as a selection. Opening with the keyboard, including `Enter` and `Space`, puts the focus on an entry straight away.
+
+Separators and headings are never focused. The trigger is given `aria-haspopup`, `aria-expanded` and `aria-controls` unless it sets them itself, so a screen reader announces it as a menu button.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `MenuEntry[]` | What the menu offers (required) |
+| `children` | `ReactNode` | The trigger |
+| `onAction` | `(id: string) => void` | Called with the id of the entry that was picked |
+| `isOpen` | `boolean` | Controlled open state; leave it out to let the menu manage its own |
+| `onOpenChange` | `(isOpen: boolean) => void` | Called when the menu wants to open or close |
+| `placement` | `PopoverPlacement` | Which side of the trigger it opens on (default `Bottom`) |
+| `align` | `PopoverAlign` | Which edge it lines up with (default `Start`) |
+| `presentation` | `Presentation` | Anchored, a bottom sheet, or a sheet only on touch |
+
+**Entry fields (`MenuAction`):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `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 |
+| `disabled` | `boolean` | Not clickable, and skipped by the arrow keys |
+| `danger` | `boolean` | Renders in the destructive colour |
+| `onClick` | `() => void` | Runs before `onAction` |
+
+**Slots:** `root` `trigger` `menu` `item` `itemIcon` `itemLabel` `itemShortcut` `separator` `heading`
+
+`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.
+
+**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

@@ -10,7 +10,7 @@
 
 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.
 
-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 `FloatingMenu`, `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).
+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).
 
 ```tsx
 import { Modal, ActionButtons } from '@ahrowe/ui';

package/docs/NumberInput.md

@@ -76,6 +76,7 @@ const priceValidator = new FormValidator<number | undefined>(undefined, [Validat
 | `arrowsLayout` | `'auto' \| 'stacked' \| 'split'` | Stepper layout. Default: `'auto'` |
 | `labels.increase` | `string` | Accessible name for the increase button. Default: `'Increase'` |
 | `labels.decrease` | `string` | Accessible name for the decrease button. Default: `'Decrease'` |
+| `ref` | `Ref<HTMLInputElement>` | Ref to the inner `<input>` |
 
 **Steppers (`showArrows`):** two layouts, picked by `arrowsLayout`:
 

package/docs/OtpInput.md

@@ -88,6 +88,7 @@ const codeValidator = new FormValidator('', [Validators.required(), Validators.m
 | `clearErrorDelay` | `number` | Delay in ms before `clearOnError` clears the boxes (default `900`) |
 | `disabled` | `boolean` | |
 | `autoFocus` | `boolean` | Focuses the first empty box (or the first box) on mount |
+| `ref` | `Ref<HTMLDivElement>` | Ref to the root element |
 
 **Slots:** `root` `label` `inputs` `input` `separator`
 

package/docs/Popover.md

@@ -1,8 +1,8 @@
 # Popover
 
-**When to use:** A floating panel anchored to a trigger — profile cards, quick forms, action menus, help panels, filter dropdowns. Reach for `Tooltip` for plain text hints, `FloatingMenu` for a menu that mirrors the trigger width; use `Popover` when you need free content on any side with an arrow.
+**When to use:** Any panel anchored to a trigger: profile cards, quick forms, action menus, pickers, filter dropdowns. It is the one anchored surface in the library, and it absorbed `FloatingMenu`, which used to be the other one. Reach for `Tooltip` instead when all you need is a plain text hint on hover.
 
-**Keywords:** hover card, info panel, bottom sheet, action sheet, mobile, touch
+**Keywords:** hover card, info panel, bottom sheet, action sheet, mobile, touch, anchored panel, dropdown surface
 
 **Import:** `import { Popover } from '@ahrowe/ui'`
 
@@ -49,7 +49,7 @@ import { Popover, PopoverPlacement, PopoverAlign, PopoverTrigger } from '@ahrowe
 | `trigger` | `PopoverTrigger` | `Click` | What opens the popover |
 | `isOpen` | `boolean` | — | Controlled open state (omit for uncontrolled) |
 | `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled |
-| `onOpenChange` | `(isOpen: boolean) => void` | — | Open-state change callback |
+| `onOpenChange` | `(isOpen, { fromKeyboard }) => void` | — | Open-state change callback. `fromKeyboard` says whether a key caused it, which is what a menu uses to decide between putting the focus on an entry and leaving it on the trigger |
 | `offset` | `number` | `10` | Gap in px between trigger and panel |
 | `withArrow` | `boolean` | `true` | Render the arrow pointing at the trigger |
 | `closeOnOutsideClick` | `boolean` | `true` | Close on click outside (ignored for hover trigger) |
@@ -58,15 +58,21 @@ import { Popover, PopoverPlacement, PopoverAlign, PopoverTrigger } from '@ahrowe
 | `closeDelay` | `number` | `120` | Hover close delay in ms |
 | `disabled` | `boolean` | `false` | Prevent opening |
 | `presentation` | `Presentation` | `Default` | Where the panel opens: anchored to the trigger, always a bottom sheet, or a sheet only on a small touch screen |
+| `focusOnOpen` | `boolean \| 'keyboard'` | `'keyboard'` | Move focus into the panel on open, and claim `role="dialog"` with it. `'keyboard'` does it only when the open came from the keyboard, which is the only way into a panel portaled to the end of the document, while a click leaves the focus where the pointer already put it. `true` always, `false` never |
+| `closeOnTriggerClick` | `boolean` | `true` | Whether clicking the trigger while open closes it. Off for a field that opens a picker, where a click to place the caret must not take the panel away |
+| `width` | `'auto' \| 'trigger'` | `'auto'` | `'trigger'` gives the panel at least the trigger's width, for a list that lines up with its field |
+| `constrainWidth` | `boolean` | `true` | Cap the panel at a readable measure. Off for a panel with its own width, a calendar or a media grid |
 
 **Slots:** `root` `trigger` `floating` `panel` `arrow` `backdrop` (`backdrop` only exists while presenting as a sheet)
 
+`root` and `trigger` generate no box of their own, so your trigger sits in your layout exactly as it would without Popover around it: it is the flex item, the grid item, the block-level child, and a row that stretches its children reaches it. The trade is that a `className` or `style` on those two cannot paint a background, padding or a border. Style the trigger you pass in instead.
+
 **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.
 
 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 `FloatingMenu`.
+Requires a `<div id="bodyEnd"></div>` at the app root — the panel is portaled there, same as `Tooltip` and `Menu`.
 
-**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, opening it (click trigger only) moves focus to the first focusable element and the panel gets `role="dialog"`. 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.
+**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/SearchInput.md

@@ -40,6 +40,7 @@ import { SearchInput } from '@ahrowe/ui';
 | Variable | Falls back to |
 |----------|---------------|
 | `--search-input-color` | *(none — unset by default)* |
+| `ref` | `Ref<HTMLInputElement>` | Ref to the inner `<input>`, for focusing the field |
 
 **Key props:**
 

package/docs/SplitButton.md

@@ -1,13 +1,14 @@
 # SplitButton
 
-**When to use:** A primary action button with a small attached dropdown for closely related secondary actions, e.g. "Save ▾" opening "Save as draft" / "Save and close". Built from `Button`, `ButtonGroup`, and `FloatingMenu` internally, rather than a mechanism of its own.
+**When to use:** A primary action button with a small attached dropdown for closely related secondary actions, e.g. "Save ▾" opening "Save as draft" / "Save and close". Built from `Button`, `ButtonGroup` and [Menu](Menu.md) internally, rather than a mechanism of its own. Reach for `Menu` on its own when there is no primary action to weld the list to.
 
 **Keywords:** dropdown button, button with menu
 
 **Import:** `import { SplitButton } from '@ahrowe/ui'`
-**Types:** `import type { SplitButtonAction, SplitButtonProps } from '@ahrowe/ui'`
+**Types:** `import type { SplitButtonAction, SplitButtonProps } from '@ahrowe/ui'`  
+**Enums:** `import { PopoverAlign } from '@ahrowe/ui'` for `align`.
 
-**Requires:** `<div id="bodyEnd"></div>` in your HTML (the actions menu renders via `FloatingMenu`, which portals).
+**Requires:** `<div id="bodyEnd"></div>` in your HTML (the actions menu is a `Menu`, which portals).
 
 ```tsx
 import { SplitButton } from '@ahrowe/ui';
@@ -73,11 +74,14 @@ import { ButtonStyleType } from '@ahrowe/ui';
 | `size` | `ButtonSize` | Size variant, shared by both buttons |
 | `disabled` | `boolean` | Disables both the primary and trigger button |
 | `isLoading` | `boolean` | Shows a spinner on the primary button (same as `Button`'s own `isLoading`) |
+| `align` | `PopoverAlign` | Which edge of the group the menu lines up with (default `End`, the chevron's side). The menu is a [Menu](Menu.md), hence `Popover`'s enum |
 
 **`isLoading` vs. `disabled`:** `isLoading` only affects the primary button — the trigger and its menu stay usable while the primary action is in flight, e.g. to cancel via a menu action. To lock the whole control during the async action instead, pass both: `isLoading={isSaving} disabled={isSaving}`. Setting `disabled` also closes the menu if it happened to be open already, and blocks any in-flight click on a menu action.
 
 **Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ SplitButton: { styleType: ButtonStyleType.Default } }}`. See [ConfigProvider.md](ConfigProvider.md).
 
-**Slots:** `root` `primaryButton` `triggerButton` `menu` `menuItem`
+**Keyboard:** the list is a [Menu](Menu.md), so it behaves like one: `↓` `↑` move between actions and skip disabled ones, `Home` and `End` jump to either end, typing a letter jumps to the action that starts with it, `Enter` and `Space` run the focused action, and `Escape` closes and hands the focus back. A click opens the menu without taking the focus, so nothing is marked until you point at an action or press an arrow key; opening with the keyboard focuses the first action straight away. The trigger announces itself as a menu button.
+
+**Slots:** `root` `primaryButton` `triggerButton` `menu` `menuItem` (`menu` is Menu's list, `menuItem` one of its rows)
 
 **Labels:** `moreActions` — the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `SplitButtonLabels`.