@ahrowe/ui 0.24.3 → 0.25.1

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

@@ -0,0 +1,8 @@
+import { Presentation } from '../floatingMenu/floatingMenu.types';
+/**
+ * The nearest `ConfigProvider`'s app-wide `presentation`, or `undefined` when none is set.
+ *
+ * Sits between a component-keyed global default and the component's own built-in default, so the
+ * full order is: explicit prop → `defaultProps.<Component>.presentation` → this → built-in.
+ */
+export declare function usePresentationDefault(): Presentation | undefined;

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

@@ -1,6 +1,7 @@
 import { ReactNode, Ref } from 'react';
 import { FormValidator } from '../../services/formValidation';
 import { HtmlProps } from '../types/slots.types';
+import { Presentation } from '../floatingMenu/floatingMenu.types';
 export interface DropdownItem {
     key: string | number;
     label: ReactNode;
@@ -29,6 +30,9 @@ export interface DropdownProps extends Omit<HtmlProps, 'onFocus' | 'onBlur' | 'o
     onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
     dropdownLabel?: string;
     isDropdownListWider?: boolean;
+    /** Where the list opens: anchored to the input (`Default`), pinned to the bottom of the
+     * screen, or the latter only on a small touch screen. */
+    presentation?: Presentation;
     inputClassName?: string;
     dropDownIconClassName?: string;
     dropDownClassName?: string;

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

@@ -1,3 +1,3 @@
 import { FloatingMenuProps } from './floatingMenu.types';
-declare function FloatingMenu({ align, children, content, isOpen, onOpenChange, dontCloseOnChildClick, className, style, classNames, styles: slotStyles, ...rest }: FloatingMenuProps): import("react/jsx-runtime").JSX.Element;
+declare function FloatingMenu(props: FloatingMenuProps): import("react/jsx-runtime").JSX.Element;
 export default FloatingMenu;

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

@@ -1,11 +1,20 @@
 import { CSSProperties, ReactNode } from 'react';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
+/** How a surface is presented on screen. */
+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"
+}
 export declare enum Align {
     Left = "left",
     Right = "right",
     Center = "center"
 }
-export type FloatingMenuSlots = 'root' | 'trigger' | 'menu' | 'menuContainer';
+export type FloatingMenuSlots = 'root' | 'trigger' | 'menu' | 'menuContainer' | 'backdrop';
 export interface FloatingMenuProps extends Omit<HtmlProps, 'content'> {
     align?: Align;
     children?: ReactNode;
@@ -13,6 +22,9 @@ export interface FloatingMenuProps extends Omit<HtmlProps, 'content'> {
     isOpen?: boolean;
     onOpenChange?: (isOpen: boolean) => void;
     dontCloseOnChildClick?: boolean;
+    /** Where the menu opens: anchored to the trigger (`Default`), pinned to the bottom of the
+     * screen, or the latter only on a small touch screen. */
+    presentation?: Presentation;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<FloatingMenuSlots>;

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

@@ -1,10 +1,3 @@
-/**
- * `true` when the primary pointing device is coarse (touch), kept current so a device that
- * switches input modes re-renders.
- *
- * `useSyncExternalStore` rather than `useState` + `useEffect`: callers pick *markup* with this,
- * so hydration has to start from the server's answer. Reading `matchMedia` in a `useState`
- * initialiser makes the client's first render disagree with the server's HTML.
- */
+/** `true` when the primary pointing device is coarse (touch). */
 export declare function useCoarsePointer(): boolean;
 export default useCoarsePointer;

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

@@ -0,0 +1,9 @@
+/**
+ * `true` while `query` matches, kept current so a resize or an input-mode change re-renders.
+ *
+ * `useSyncExternalStore` rather than `useState` + `useEffect`: callers pick *markup* with this,
+ * so hydration has to start from the server's answer. Reading `matchMedia` in a `useState`
+ * initialiser makes the client's first render disagree with the server's HTML.
+ */
+export declare function useMediaQuery(query: string): boolean;
+export default useMediaQuery;

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

@@ -0,0 +1,26 @@
+import { RefObject } from 'react';
+export interface UseOverlayArgs {
+    /** Whether the overlay is currently visible. Everything below is set up while this is true. */
+    isActive: boolean;
+    /** The overlay panel. Focus is trapped inside it and Escape is scoped to it. */
+    containerRef: RefObject<HTMLElement | null>;
+    /** Called when Escape is pressed while this is the topmost overlay. Omit to not handle Escape. */
+    onEscape?: () => void;
+    /** Keep Tab inside the panel and restore focus to the previously focused element on close. */
+    trapFocus?: boolean;
+    /** Prevent the page behind the overlay from scrolling. */
+    lockScroll?: boolean;
+}
+/**
+ * The three behaviours every blocking overlay needs: Escape to dismiss, a focus trap, and a
+ * scroll lock on the page behind it.
+ *
+ * They share one module-level stack because they share one question: overlays nest (a
+ * ConfirmModal opened from inside a Modal), every instance listens on `document`, and only the
+ * innermost one may react. Without the stack, Escape would close every open layer at once and
+ * the outer trap would yank focus out of the inner panel on the next Tab.
+ *
+ * The scroll lock is reference-counted for the same reason: the page stays locked until the last
+ * overlay closes, and the body's original inline styles are restored rather than cleared.
+ */
+export declare function useOverlay({ isActive, containerRef, onEscape, trapFocus, lockScroll, }: UseOverlayArgs): void;

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

@@ -0,0 +1,16 @@
+import { CSSProperties } from 'react';
+import { Presentation } from '../floatingMenu/floatingMenu.types';
+export interface Sheet {
+    /** Whether the popup should render as a bottom sheet instead of anchored to its trigger. */
+    isSheet: boolean;
+    /** Inline style for the sheet root, keeping it above an open on-screen keyboard. */
+    sheetStyle: CSSProperties | undefined;
+}
+/**
+ * Resolves whether a popup presents as a bottom sheet.
+ *
+ * `Auto` asks for a coarse pointer *and* a small screen: pointer alone turns a touchscreen laptop
+ * into a phone, and width alone turns a narrow desktop window into one.
+ */
+export declare function useSheet(presentation?: Presentation): Sheet;
+export default useSheet;

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

@@ -1,3 +1,3 @@
 import { ModalProps } from './modal.types';
-declare function Modal({ children, title, isOpen, onClose, className, style, hideHeader, classNames, styles: slotStyles, }: ModalProps): import("react/jsx-runtime").JSX.Element | null;
+declare function Modal(props: ModalProps): import("react/jsx-runtime").JSX.Element | null;
 export default Modal;

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

@@ -1,7 +1,8 @@
 import { CSSProperties } from 'react';
-import { SlotClassNames, SlotStyles } from '../types/slots.types';
-export type ModalSlots = 'container' | 'backdrop' | 'modal' | 'header' | 'title' | 'closeButton';
-export interface ModalProps {
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
+import { Presentation } from '../floatingMenu/floatingMenu.types';
+export type ModalSlots = 'container' | 'backdrop' | 'modal' | 'header' | 'title' | 'closeButton' | 'body';
+export interface ModalProps extends HtmlProps<HTMLDivElement> {
     children?: React.ReactNode;
     title?: string;
     isOpen?: boolean;
@@ -10,6 +11,11 @@ export interface ModalProps {
     className?: string;
     style?: CSSProperties;
     hideHeader?: boolean;
+    /** Close on Escape while this is the topmost overlay. Default `true`. */
+    closeOnEscape?: boolean;
+    /** Present as a bottom sheet, always or only on a small touch screen. `Presentation.Default`
+     * (or omitting this) is the ordinary centred dialog. */
+    presentation?: Presentation;
     classNames?: SlotClassNames<ModalSlots>;
     styles?: SlotStyles<ModalSlots>;
 }

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

@@ -1,3 +1,3 @@
 import { PopoverProps } from './popover.types';
-declare function Popover({ children, content, placement, align, trigger, isOpen, defaultOpen, onOpenChange, offset, withArrow, closeOnOutsideClick, closeOnEscape, openDelay, closeDelay, disabled, className, style, classNames, styles: slotStyles, ...rest }: PopoverProps): import("react/jsx-runtime").JSX.Element;
+declare function Popover(props: PopoverProps): import("react/jsx-runtime").JSX.Element;
 export default Popover;

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

@@ -1,5 +1,6 @@
 import { CSSProperties, ReactNode } from 'react';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
+import { Presentation } from '../floatingMenu/floatingMenu.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",
@@ -19,7 +20,7 @@ export declare enum PopoverTrigger {
     Hover = "hover",
     Focus = "focus"
 }
-export type PopoverSlots = 'root' | 'trigger' | 'floating' | 'panel' | 'arrow';
+export type PopoverSlots = 'root' | 'trigger' | 'floating' | 'panel' | 'arrow' | 'backdrop';
 export interface PopoverProps extends Omit<HtmlProps, 'content'> {
     /** The trigger element. */
     children?: ReactNode;
@@ -51,6 +52,10 @@ export interface PopoverProps extends Omit<HtmlProps, 'content'> {
     closeDelay?: number;
     /** Prevent the popover from opening. */
     disabled?: 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. */
+    presentation?: Presentation;
     className?: string;
     style?: CSSProperties;
     classNames?: SlotClassNames<PopoverSlots>;

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

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

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

@@ -0,0 +1,16 @@
+import { SheetBackdropProps } from './sheetBackdrop.types';
+/**
+ * The dimmed layer behind a bottom sheet, and the thing that closes it when tapped.
+ *
+ * It closes on its own `click` rather than letting the sheet's usual outside-click handling see
+ * the press, because that handling fires on mousedown/mouseup — and the sheet, backdrop included,
+ * unmounts the moment it closes. The browser then dispatches the `click` that completes the tap
+ * at whatever is under the cursor by then, which is the page behind the sheet: tapping to dismiss
+ * would also press a button underneath it.
+ *
+ * The press is stopped with native listeners rather than React's `stopPropagation`, which would
+ * not be enough: React listens at its own root container, so a native handler on `document` or
+ * `window` still runs afterwards.
+ */
+declare function SheetBackdrop({ onClose, className, style }: SheetBackdropProps): import("react/jsx-runtime").JSX.Element;
+export default SheetBackdrop;

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

@@ -0,0 +1,7 @@
+import { CSSProperties } from 'react';
+export interface SheetBackdropProps {
+    /** Called when the backdrop itself is clicked or tapped. */
+    onClose: () => void;
+    className?: string;
+    style?: CSSProperties;
+}

package/docs/ConfigProvider.md

@@ -54,15 +54,46 @@ So a global default only fills in props a given instance left out — any instan
 | Prop | Type | Description |
 |------|------|-------------|
 | `defaultProps` | `ComponentDefaults` | Default props keyed by component name, e.g. `{ Input: { alwaysFloatLabel: true } }` |
+| `presentation` | `Presentation` | How every sheet-capable component presents by default — one switch for all of them (see below) |
 | `children` | `ReactNode` | Your app content |
 
+## 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:
+
+```tsx
+// Bottom sheets on small touch screens, everywhere, in one line
+<ConfigProvider presentation={Presentation.Auto}>
+  <App />
+</ConfigProvider>
+```
+
+It resolves *under* the component-keyed defaults, so the full order for a `presentation` prop is:
+
+1. The prop passed to the instance
+2. `defaultProps.<Component>.presentation`
+3. This app-wide `presentation`
+4. The component's built-in default, `Presentation.Default` — anchored to the trigger, or centred for `Modal`
+
+```tsx
+// Sheets app-wide, except Dropdown, except this one Dropdown
+<ConfigProvider
+  presentation={Presentation.Auto}
+  defaultProps={{ Dropdown: { presentation: Presentation.Default } }}
+>
+  <Dropdown label="Status" items={items} presentation={Presentation.Sheet} />
+</ConfigProvider>
+```
+
+A nested provider inherits it unless it sets its own, the same way `defaultProps` compose. Everything built on those four components follows along: `SplitButton`, `ColorPicker`, `Breadcrumb`, `VirtualList`, and `DatePicker`/`TimeInput`/`KlipyPicker` in either their menu or their `isModal` mode. `InputDropdown` and `Tooltip` are deliberately never sheets and ignore it.
+
 ## Supported components
 
 Each entry is a `Partial<...Props>`, so any of that component's props can be defaulted:
 
 - **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`
+- **Overlays:** `ConfirmModal` · `Modal` · `FloatingMenu` · `Popover`
 
 ```tsx
 <ConfigProvider

package/docs/Dropdown.md

@@ -2,7 +2,7 @@
 
 **When to use:** Single-value selection from a list — country pickers, status selectors, category filters, any select-style input.
 
-**Keywords:** combobox
+**Keywords:** combobox, bottom sheet, action sheet, mobile, touch
 
 **Import:** `import { Dropdown } from '@ahrowe/ui'`  
 **Types:** `import type { DropdownItem, DropdownProps } from '@ahrowe/ui'`
@@ -33,6 +33,9 @@ const statusValidator = new FormValidator('', [Validators.required()]);
 // Row layout (label left, input right)
 <Dropdown label="Status" items={items} value={status} onChange={onChange} isRow />
 
+// Bottom sheet on small touch screens, anchored to the input everywhere else
+<Dropdown label="Status" items={items} value={status} onChange={onChange} presentation={Presentation.Auto} />
+
 // Infinite scroll support
 <Dropdown
   items={items}
@@ -56,6 +59,9 @@ const statusValidator = new FormValidator('', [Validators.required()]);
 | `placeholder` | `string` | Placeholder when no selection |
 | `onScroll` | `() => Promise<void>` | Load more on list scroll |
 | `useMatLabelStyle` | `boolean` | Material-style floating label |
+| `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.
+
+**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. 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/FloatingMenu.md

@@ -2,7 +2,7 @@
 
 **When to use:** Contextual popover triggered by any element — action menus, dropdowns with custom content, "more options" menus, date pickers, colour swatches.
 
-**Keywords:** context menu, dropdown menu
+**Keywords:** context menu, dropdown menu, bottom sheet, action sheet, mobile, touch
 
 **Import:** `import { FloatingMenu } from '@ahrowe/ui'`
 
@@ -39,8 +39,20 @@ import { FloatingMenu, Align } from '@ahrowe/ui';
 </FloatingMenu>
 ```
 
+```tsx
+import { FloatingMenu, Presentation } from '@ahrowe/ui';
+
+// On a small touch screen the menu becomes a bottom sheet instead of a popover anchored to
+// the trigger; everywhere else it stays anchored.
+<FloatingMenu presentation={Presentation.Auto} content={<MenuContent />}>
+  <button>More ▾</button>
+</FloatingMenu>
+```
+
 **Align enum:** `Align.Left` | `Align.Right` | `Align.Center`
 
+**Presentation enum:** `Presentation.Default` (anchored to the trigger) | `Presentation.Sheet` | `Presentation.Auto`
+
 **Key props:**
 
 | Prop | Type | Description |
@@ -51,11 +63,28 @@ import { FloatingMenu, Align } from '@ahrowe/ui';
 | `isOpen` | `boolean` | Controlled open state |
 | `onOpenChange` | `(isOpen: boolean) => void` | Open state change callback |
 | `dontCloseOnChildClick` | `boolean` | Keep the menu open when its own content is clicked, and when the trigger itself is re-clicked while already open (default `false`) |
+| `presentation` | `Presentation` | Where the menu opens: anchored to the trigger (`Default`), always a bottom sheet, or a sheet only on a small touch screen |
+
+**Slots:** `root` `trigger` `menu` `menuContainer` `backdrop` (`backdrop` only exists while presenting as a sheet)
 
-**Slots:** `root` `trigger` `menu` `menuContainer`
+**Bottom sheet:** with `Presentation.Sheet` the menu leaves its trigger entirely: it pins to the bottom of the screen, spans the full width up to 560px, scrolls internally past 70% of the viewport height, and dims the page behind a backdrop. Scrolling on the page behind it is locked while it's open, Escape closes it even when focus never entered it, and it lifts itself above an open on-screen keyboard. Tapping the backdrop closes the sheet and nothing else: the tap is consumed by the backdrop rather than falling through to whatever sits behind it. `Presentation.Auto` applies that only when the pointer is coarse *and* the screen is under 768px wide: pointer alone would catch touchscreen laptops, width alone would catch a narrow desktop window. Set it once for a whole app via `ConfigProvider`:
+
+```tsx
+<ConfigProvider defaultProps={{ FloatingMenu: { presentation: Presentation.Auto } }}>
+```
+
+To set it for every sheet-capable component at once, use `ConfigProvider`'s own `presentation` prop instead of the four component-keyed entries — see [ConfigProvider.md](ConfigProvider.md).
+
+The default stays `Presentation.Default`, so nothing changes for an existing app until it opts in.
+
+**What that one setting covers.** Every component whose popup *is* a `FloatingMenu` inherits the default above, with no prop of its own: `SplitButton`'s action menu, `ColorPicker`'s picker, `Breadcrumb`'s collapsed-crumb menu, `VirtualList`'s column-visibility menu, and `DatePicker`/`TimeInput`/`KlipyPicker` when they're not already using their own `isModal`. To make one instance differ, wrap it in a nested `ConfigProvider`, which overrides only the keys it sets.
+
+`Dropdown`, `Popover` and `Modal` place their surfaces themselves rather than through `FloatingMenu`, so each takes its own `presentation` prop and its own `ConfigProvider` key (`Modal`'s covers `DatePicker`/`TimeInput`/`KlipyPicker` in their `isModal` mode). `InputDropdown` and `Tooltip` also position themselves and deliberately have no sheet mode: a typeahead's list belongs next to the text being typed, and a tooltip is a pointer hint, not a screen-owning panel.
 
 **Positioning:** the menu is portaled and tracks the trigger across scroll and resize, flipping above it when there's no room below. It re-measures whenever `content` changes size while open, so a menu holding a list that grows or shrinks (filtering, async loading) stays anchored to the trigger and re-evaluates whether it still needs to open upward. It's also shifted horizontally to stay within the viewport — a trigger near the left or right edge of the screen no longer lets the menu overflow off-screen, regardless of `align`.
 
 **Closing behaviour:** by default, clicking anywhere in `content` closes the menu — including inside a nested overlay that renders through its own portal (e.g. a `Dropdown` or another `FloatingMenu` used inside `content`), even though that overlay's DOM lives outside `content`'s own subtree. Re-clicking the trigger while open is a clean toggle: it closes the menu (unless `dontCloseOnChildClick` is set, in which case it's a no-op — the trigger owns its own open/close entirely, so it never fights with an outside-click check). Set `dontCloseOnChildClick` when `content` needs several interactions before the user is done (a multi-checkbox toggle, a color picker's slider, a calendar) — the consumer is then responsible for closing explicitly, e.g. calling `onOpenChange(false)` from the handler that reacts to a final selection.
 
-**Keyboard:** the menu is portaled to the end of the DOM, so Tab can't reach it in visual order on its own. When `content` has real focusable elements, Escape closes the menu and returns focus to the trigger; Tab past the last focusable element (or Shift+Tab past the first) closes the menu and continues focus as if it sat right after the trigger. This doesn't include auto-focusing the first element on open — content ranges from menus to live controls (e.g. `ColorPicker`'s hue slider), where grabbing focus on open would let a stray arrow-key press change a value the user never touched. A consumer that wants that (like `SplitButton` focusing its first enabled action) implements it itself.
+**Keyboard:** the menu is portaled to the end of the DOM, so Tab can't reach it in visual order on its own. Escape closes the menu and, when focus is inside it, returns focus to the trigger — it works wherever focus currently is, including on the trigger itself. When `content` has real focusable elements, Tab past the last focusable element (or Shift+Tab past the first) closes the menu and continues focus as if it sat right after the trigger. This doesn't include auto-focusing the first element on open — content ranges from menus to live controls (e.g. `ColorPicker`'s hue slider), where grabbing focus on open would let a stray arrow-key press change a value the user never touched. A consumer that wants that (like `SplitButton` focusing its first enabled action) implements it itself.
+
+**Nesting inside a Modal:** an open menu registers itself as the layer above whatever it was opened from, so a menu inside a `Modal` behaves the way it looks: Escape closes the menu and leaves the modal open (a second press closes the modal), and the modal's focus trap leaves focus alone while the menu has it. Both matter because the menu is portaled, so its DOM is a sibling of the modal's panel rather than a descendant, and neither DOM position nor mount order says which one is on top. The same applies to `Dropdown` and `Popover`.

package/docs/Modal.md

@@ -2,12 +2,16 @@
 
 **When to use:** Full overlay dialog — forms, detail views, confirmations, wizards that need to block the rest of the UI.
 
-**Keywords:** popup
+**Keywords:** popup, dialog, overlay, escape, focus trap, scroll lock, sticky header, bottom sheet, action sheet, mobile, touch
 
 **Import:** `import { Modal } from '@ahrowe/ui'`
 
 **Requires:** `<div id="bodyEnd"></div>` in your HTML (renders via portal).
 
+The panel itself never scrolls: the header is fixed and the children scroll inside the `body` slot, so the title and close button stay visible no matter how long the content is.
+
+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).
+
 ```tsx
 import { Modal, ActionButtons } from '@ahrowe/ui';
 
@@ -43,7 +47,27 @@ const [isOpen, setIsOpen] = useState(false);
 |------|------|-------------|
 | `isOpen` | `boolean` | Controls visibility |
 | `title` | `string` | Header title |
-| `onClose` | `() => void` | Called when backdrop clicked or close button pressed |
+| `onClose` | `() => void` | Called when the backdrop is clicked, the close button is pressed, or Escape is pressed |
 | `hideHeader` | `boolean` | Removes the header bar |
+| `closeOnEscape` | `boolean` | Close on Escape while this is the topmost modal. Default `true` |
+| `presentation` | `Presentation` | Present as a bottom sheet, always (`Sheet`) or only on a small touch screen (`Auto`). `Default`, or omitting it, is the centred dialog |
+
+**Bottom sheet:** `presentation={Presentation.Sheet}` pins the dialog to the bottom of the screen instead of centring it — full width up to 560px, rounded on its top corners only, sliding up rather than scaling in, and lifted above an open on-screen keyboard. Nothing else changes: the header stays fixed and the body scrolls, which is what a sheet needs anyway, and the backdrop, focus trap, scroll lock and Escape all behave exactly as they do centred. `Presentation.Auto` applies it only when the pointer is coarse *and* the screen is under 768px wide.
+
+`Presentation.Default` means "wherever the component normally puts it", which for a Modal is centred rather than anchored to anything — so an app-wide `<ConfigProvider presentation={Presentation.Default}>` switches sheets off everywhere, this included.
+
+```tsx
+import { Modal, Presentation } from '@ahrowe/ui';
+
+<Modal isOpen={isOpen} title="Filters" onClose={close} presentation={Presentation.Auto}>
+  <FilterForm />
+</Modal>
+```
+
+A sheet-presented Modal takes 90% of the screen height rather than the 70% a menu-sized sheet uses, since it carries forms and detail views. Override either with the `--sheet-max-height` and `--sheet-safe-padding` custom properties, per instance via `style` or theme-wide via `ThemeProvider`.
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ Modal: { presentation: Presentation.Auto } }}` — which also covers `DatePicker`, `TimeInput` and `KlipyPicker` when they open in a Modal via their own `isModal`. `presentation={Presentation.Auto}` on the provider itself sets every sheet-capable component at once. See [ConfigProvider.md](ConfigProvider.md).
+
+The panel also takes the full native `div` attribute set (`id`, `role`, `aria-*`, `data-*`, …). Pass `aria-label` when using `hideHeader`, since there is then no title to label the dialog with.
 
-**Slots:** `container` `backdrop` `modal` `header` `title` `closeButton`
+**Slots:** `container` `backdrop` `modal` `header` `title` `closeButton` `body`

package/docs/Popover.md

@@ -2,7 +2,7 @@
 
 **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.
 
-**Keywords:** hover card, info panel
+**Keywords:** hover card, info panel, bottom sheet, action sheet, mobile, touch
 
 **Import:** `import { Popover } from '@ahrowe/ui'`
 
@@ -36,6 +36,8 @@ import { Popover, PopoverPlacement, PopoverAlign, PopoverTrigger } from '@ahrowe
 
 **PopoverTrigger enum:** `PopoverTrigger.Click` | `Hover` | `Focus`.
 
+**Presentation enum:** `Presentation.Default` (anchored to the trigger) | `Presentation.Sheet` | `Presentation.Auto` — imported from the same package: `import { Presentation } from '@ahrowe/ui'`.
+
 **Key props:**
 
 | Prop | Type | Default | Description |
@@ -55,9 +57,16 @@ import { Popover, PopoverPlacement, PopoverAlign, PopoverTrigger } from '@ahrowe
 | `openDelay` | `number` | `100` | Hover open delay in ms |
 | `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 |
+
+**Slots:** `root` `trigger` `floating` `panel` `arrow` `backdrop` (`backdrop` only exists while presenting as a sheet)
+
+**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. 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`.
 
-**Slots:** `root` `trigger` `floating` `panel` `arrow`
+**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`.
 
-**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. 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, 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.24.3",
+  "version": "0.25.1",
   "publishConfig": {
     "access": "public"
   },