@ahrowe/ui 0.33.0 → 0.34.0

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

@@ -1,6 +1,6 @@
 import { default as React } from 'react';
 import { ComponentDefaults, ConfigProviderProps } from './configProvider.types';
-import { Presentation } from '../floatingMenu/floatingMenu.types';
+import { Presentation } from '../configProvider/presentation.types';
 export declare const ConfigContext: React.Context<ComponentDefaults | null>;
 /**
  * One setting for every component that can present as a bottom sheet, kept separate from

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

@@ -39,9 +39,9 @@ import { PaginationProps } from '../pagination/pagination.types';
 import { TreeProps } from '../tree/tree.types';
 import { RoomDrawerProps } from '../roomDrawer/roomDrawer.types';
 import { RoomViewerProps } from '../roomViewer/roomViewer.types';
-import { FloatingMenuProps, Presentation } from '../floatingMenu/floatingMenu.types';
 import { PopoverProps } from '../popover/popover.types';
 import { ModalProps } from '../modal/modal.types';
+import { Presentation } from '../configProvider/presentation.types';
 /**
  * Global default props keyed by component name.
  *
@@ -112,7 +112,6 @@ export interface ComponentDefaults {
     Tree?: Partial<TreeProps>;
     RoomDrawer?: Partial<RoomDrawerProps>;
     RoomViewer?: Partial<RoomViewerProps>;
-    FloatingMenu?: Partial<FloatingMenuProps>;
     Popover?: Partial<PopoverProps>;
     Modal?: Partial<ModalProps>;
 }
@@ -122,7 +121,7 @@ export interface ConfigProviderProps {
     defaultProps?: ComponentDefaults;
     /**
      * How every sheet-capable component presents by default: anchored to its trigger, always a
-     * bottom sheet, or a sheet only on a small touch screen. One switch for `FloatingMenu`,
+     * bottom sheet, or a sheet only on a small touch screen. One switch for `Popover`,
      * `Dropdown`, `Popover` and `Modal` at once (and so for everything built on them). A
      * component-keyed entry in `defaultProps` overrides it, and an explicit prop overrides both.
      */

package/dist/types/common/configProvider/index.d.ts

@@ -3,3 +3,4 @@ export { useComponentDefaults } from './useComponentDefaults';
 export { useLabels } from './useLabels';
 export { usePresentationDefault } from './usePresentationDefault';
 export type { ComponentDefaults, ConfigProviderProps } from './configProvider.types';
+export { Presentation } from './presentation.types';

package/dist/types/common/configProvider/presentation.types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * How a surface is presented on screen. Lives here rather than with any one of
+ * the components that read it: `Modal`, `Popover`, `Dropdown` and `MultiSelect`
+ * all take it, and `ConfigProvider` owns the app-wide switch that sets it for
+ * every one of them at once.
+ */
+export declare enum Presentation {
+    /** Wherever the component normally puts it: anchored to its trigger, or centred for a Modal. */
+    Default = "default",
+    /** Pinned to the bottom of the screen, full width up to a maximum. */
+    Sheet = "sheet",
+    /** A sheet on touch devices with a small screen, anchored everywhere else. */
+    Auto = "auto"
+}

package/dist/types/common/configProvider/usePresentationDefault.d.ts

@@ -1,4 +1,4 @@
-import { Presentation } from '../floatingMenu/floatingMenu.types';
+import { Presentation } from '../configProvider/presentation.types';
 /**
  * The nearest `ConfigProvider`'s app-wide `presentation`, or `undefined` when none is set.
  *

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

@@ -1,7 +1,7 @@
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 import { ReactNode, Ref } from 'react';
 import { FormValidator } from '../../services/formValidation';
-import { Presentation } from '../floatingMenu/floatingMenu.types';
+import { Presentation } from '../configProvider/presentation.types';
 export interface DropdownItem {
     key: string | number;
     label: ReactNode;

package/dist/types/common/hooks/useAnchorTracking.d.ts

@@ -31,7 +31,7 @@ export interface UseAnchorTrackingArgs {
  * positioning on every scroll, viewport resize and tracked size change until it closes.
  *
  * Callers supply only the geometry (`update`) and the inline styles to clear again (`teardown`);
- * `useFloatingPosition` and `usePopoverPosition` are both built on this.
+ * `usePopoverPosition` is built on this.
  *
  * Position is deliberately written straight to the DOM by the caller rather than through React
  * state: going through setState -> re-render -> commit adds a round-trip that lags behind the

package/dist/types/common/hooks/useFocusBoundary.d.ts

@@ -9,9 +9,9 @@ export interface UseFocusBoundaryArgs {
 }
 /**
  * Focus helpers for content portaled to the end of the DOM (e.g. via BodyEnd), where Tab can't
- * reach it in visual document order on its own. Shared by FloatingMenu and Popover, which both
- * need to hand focus back to the trigger on Escape / Shift+Tab out of the top, and continue
- * focus naturally past the trigger when Tab exits the bottom.
+ * reach it in visual document order on its own. Used by Popover and by Menu, which both need to
+ * hand focus back to the trigger on Escape / Shift+Tab out of the top, and continue focus
+ * naturally past the trigger when Tab exits the bottom.
  */
 export declare function useFocusBoundary({ triggerRef, contentRef }: UseFocusBoundaryArgs): {
     firstTriggerFocusable: () => HTMLElement | null;

package/dist/types/common/hooks/useSheet.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties } from 'react';
-import { Presentation } from '../floatingMenu/floatingMenu.types';
+import { Presentation } from '../configProvider/presentation.types';
 export interface Sheet {
     /** Whether the popup should render as a bottom sheet instead of anchored to its trigger. */
     isSheet: boolean;

package/dist/types/common/menu/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './menu';
+export * from './menu.types';

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

@@ -0,0 +1,14 @@
+import { ReactElement } from 'react';
+import { MenuProps } from './menu.types';
+/**
+ * A menu of actions on a trigger of your choosing.
+ *
+ * `Popover` does the anchoring, portalling and outside-click work but takes
+ * arbitrary `content`, which leaves every consumer to write their own `ul`/`li`
+ * and, in practice, to leave out the roles and the arrow keys. This is that list,
+ * done once: `role="menu"`, a roving focus that skips disabled entries, Escape
+ * back to the trigger, and separators and headings that stay out of the keyboard
+ * order.
+ */
+declare function Menu({ items, children, onAction, isOpen: controlledOpen, onOpenChange, placement, align, presentation, className, style, classNames, styles: slotStyles, ...rest }: MenuProps): ReactElement;
+export default Menu;

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

@@ -0,0 +1,55 @@
+import { CSSProperties, ReactNode } from 'react';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
+import { IconContent } from '../types/icon.types';
+import { PopoverAlign, PopoverPlacement } from '../popover/popover.types';
+import { Presentation } from '../configProvider/presentation.types';
+/** One thing the menu can do. */
+export interface MenuAction {
+    /** Stable id, also what `onAction` reports. */
+    id: string;
+    label: ReactNode;
+    icon?: IconContent;
+    /**
+     * Keyboard hint on the trailing edge, e.g. `⌘K`. Display only: binding the
+     * shortcut is yours, since only you know what else is listening.
+     */
+    shortcut?: ReactNode;
+    disabled?: boolean;
+    /** Renders in the destructive colour. For deleting, discarding, revoking. */
+    danger?: boolean;
+    onClick?: () => void;
+}
+/** A line between groups of actions. */
+export interface MenuSeparator {
+    separator: true;
+}
+/** A label over the actions that follow it. */
+export interface MenuHeading {
+    heading: ReactNode;
+}
+export type MenuEntry = MenuAction | MenuSeparator | MenuHeading;
+export declare function isMenuSeparator(entry: MenuEntry): entry is MenuSeparator;
+export declare function isMenuHeading(entry: MenuEntry): entry is MenuHeading;
+export declare function isMenuAction(entry: MenuEntry): entry is MenuAction;
+export type MenuSlots = 'root' | 'trigger' | 'menu' | 'item' | 'itemIcon' | 'itemLabel' | 'itemShortcut' | 'separator' | 'heading';
+export interface MenuProps extends Omit<HtmlProps, 'onSelect'> {
+    /** What the menu offers, in the order it is read. */
+    items: MenuEntry[];
+    /** The element that opens the menu. */
+    children?: ReactNode;
+    /** Called with the id of the action that was picked, after its own `onClick`. */
+    onAction?: (id: string) => void;
+    /** Controlled open state. Leave it out to let the menu manage its own. */
+    isOpen?: boolean;
+    onOpenChange?: (isOpen: boolean) => void;
+    /** Which side of the trigger the menu opens on (default `Bottom`). */
+    placement?: PopoverPlacement;
+    /** Which edge it lines up with on the cross axis (default `Start`). */
+    align?: PopoverAlign;
+    /** Anchored to the trigger, pinned to the bottom of the screen, or the latter only on touch. */
+    presentation?: Presentation;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<MenuSlots>;
+    styles?: SlotStyles<MenuSlots>;
+}

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

@@ -1,6 +1,6 @@
 import { CSSProperties } from 'react';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
-import { Presentation } from '../floatingMenu/floatingMenu.types';
+import { Presentation } from '../configProvider/presentation.types';
 export type ModalSlots = 'container' | 'backdrop' | 'modal' | 'header' | 'title' | 'closeButton' | 'body';
 /** Text Modal renders of its own, for translating it. */
 export interface ModalLabels {

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

@@ -1,7 +1,7 @@
 import { CSSProperties } from 'react';
 import { FormValidator } from '../../services/formValidation';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
-import { Presentation } from '../floatingMenu/floatingMenu.types';
+import { Presentation } from '../configProvider/presentation.types';
 export type MultiSelectValue = string | number;
 export interface MultiSelectItem {
     key: MultiSelectValue;

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

@@ -1,6 +1,6 @@
 import { CSSProperties, ReactNode } from 'react';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
-import { Presentation } from '../floatingMenu/floatingMenu.types';
+import { Presentation } from '../configProvider/presentation.types';
 /** Preferred side of the trigger the panel opens on. Flips to the opposite side when there's no room. */
 export declare enum PopoverPlacement {
     Top = "top",
@@ -36,8 +36,14 @@ export interface PopoverProps extends Omit<HtmlProps, 'content'> {
     isOpen?: boolean;
     /** Initial open state when uncontrolled (default `false`). */
     defaultOpen?: boolean;
-    /** Fires whenever the popover wants to open or close. */
-    onOpenChange?: (isOpen: boolean) => void;
+    /**
+     * Fires whenever the popover wants to open or close. `fromKeyboard` says
+     * whether a key caused it, which is what a menu needs in order to put the
+     * focus on an entry only when the pointer was not what opened it.
+     */
+    onOpenChange?: (isOpen: boolean, meta: {
+        fromKeyboard: boolean;
+    }) => void;
     /** Gap in px between trigger and panel (default `10`). */
     offset?: number;
     /** Render the arrow pointing at the trigger (default `true`). */
@@ -52,6 +58,31 @@ export interface PopoverProps extends Omit<HtmlProps, 'content'> {
     closeDelay?: number;
     /** Prevent the popover from opening. */
     disabled?: boolean;
+    /**
+     * Move focus into the panel when it opens, and claim `role="dialog"` with it.
+     * `'keyboard'` (the default) does it only when the open came from the
+     * keyboard: the panel is portaled to the end of the document, so Tab never
+     * reaches it on its own, while a click leaves the focus where the pointer
+     * already put it. `true` always, `false` never.
+     */
+    focusOnOpen?: boolean | 'keyboard';
+    /**
+     * Whether clicking the trigger while the panel is open closes it (default
+     * `true`). A menu button should toggle; a text field that opens a picker
+     * should not, or clicking into it to place the caret would close the panel.
+     */
+    closeOnTriggerClick?: boolean;
+    /**
+     * `'trigger'` gives the panel at least the trigger's width, for a list that
+     * should line up with the field it belongs to. `'auto'` (the default) lets it
+     * size to its own content.
+     */
+    width?: 'auto' | 'trigger';
+    /**
+     * Cap the panel at a readable measure (default `true`). Off for a panel with
+     * its own width, a calendar or a media grid.
+     */
+    constrainWidth?: boolean;
     /** Where the panel opens: anchored to the trigger (`Default`), pinned to the bottom of the
      * screen, or the latter only on a small touch screen. Only a `Click` trigger presents as a
      * sheet. */

package/dist/types/common/popover/usePopoverPosition.d.ts

@@ -12,6 +12,25 @@ export interface UsePopoverPositionArgs {
     panelRef: RefObject<HTMLElement | null>;
     /** Arrow element; gets `--arrow-x` / `--arrow-y` written to it. Pass a null ref when `withArrow` is false. */
     arrowRef: RefObject<HTMLElement | null>;
+    /**
+     * Give the panel at least the trigger's width, for a list that lines up with
+     * the field it belongs to. A minimum rather than a fixed width: a menu on a
+     * narrow icon button still sizes to its own content.
+     */
+    matchTriggerWidth?: boolean;
+    /**
+     * When the panel does not fit on the side its alignment puts it, narrow it
+     * rather than sliding it away from the trigger. Sliding keeps the panel
+     * on-screen but detaches it: an end-aligned bubble stops ending where its
+     * trigger ends, and its arrow stops pointing at anything. Off by default, since
+     * a panel whose width is its content, a menu or a list, would rather overhang
+     * its trigger than wrap.
+     *
+     * Only down to `MIN_SHRINK_WIDTH`. Past that the panel is narrower than it is
+     * readable, and a trigger that close to the screen edge is better served by a
+     * panel that overhangs it.
+     */
+    shrinkToFit?: boolean;
 }
 /**
  * Positions a portaled, `position: fixed` popover on any of the four sides of its trigger with
@@ -22,4 +41,4 @@ export interface UsePopoverPositionArgs {
  * `useAnchorTracking` supplies the lifecycle around this: mount wait, ancestor resolution, and
  * re-running on scroll, viewport resize and panel size changes.
  */
-export declare function usePopoverPosition({ isOpen, placement, align, offset, triggerRef, floatingRef, panelRef, arrowRef, }: UsePopoverPositionArgs): void;
+export declare function usePopoverPosition({ isOpen, placement, align, offset, triggerRef, floatingRef, panelRef, arrowRef, matchTriggerWidth, shrinkToFit, }: UsePopoverPositionArgs): void;

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

@@ -1,7 +1,7 @@
+import { PopoverAlign } from '../popover/popover.types';
 import { CSSProperties, ReactNode } from 'react';
 import { IconContent } from '../types/icon.types';
 import { ButtonStyleType, ButtonSize } from '../button/button.types';
-import { Align } from '../floatingMenu/floatingMenu.types';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
 export interface SplitButtonAction {
     id: string;
@@ -24,8 +24,8 @@ export interface SplitButtonProps extends HtmlProps {
     size?: ButtonSize;
     disabled?: boolean;
     isLoading?: boolean;
-    /** Alignment of the actions menu relative to the trigger button (default `Align.Right`) */
-    align?: Align;
+    /** Alignment of the actions menu relative to the trigger button (default `PopoverAlign.End`) */
+    align?: PopoverAlign;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<SplitButtonSlots>;

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/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

@@ -142,7 +142,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 +154,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,7 @@ 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 |
 
 **CardHeaderProps:**
 

package/docs/ColorPicker.md

@@ -53,4 +53,6 @@ The picker panel deliberately does not. It is a floating control surface 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`.
 
+**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.
+
 **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/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/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/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.