@ahrowe/ui 0.36.0 → 0.37.0

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

@@ -0,0 +1,13 @@
+export { useHotkeys, formatHotkey } from './useHotkeys.js';
+export type { HotkeyHandler, HotkeyMap, UseHotkeysOptions } from './useHotkeys.js';
+export { useMediaQuery } from './useMediaQuery.js';
+export { useCoarsePointer } from './useCoarsePointer.js';
+export { useVisualViewportSize } from './useVisualViewportSize.js';
+export type { VisualViewportSize } from './useVisualViewportSize.js';
+export { useScrollEdges } from './useScrollEdges.js';
+export type { ScrollEdges, ScrollEdgesOptions } from './useScrollEdges.js';
+export { useSwipeDismiss } from './useSwipeDismiss.js';
+export type { UseSwipeDismissOptions, UseSwipeDismissResult } from './useSwipeDismiss.js';
+export { useOverlay } from './useOverlay.js';
+export type { UseOverlayArgs } from './useOverlay.js';
+export { tabbablesIn } from './useFocusBoundary.js';

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

@@ -0,0 +1,45 @@
+import { RefObject } from 'react';
+export type HotkeyHandler = (event: KeyboardEvent) => void;
+/** Combo → handler, e.g. `{ 'mod+k': open, Escape: close }`. */
+export type HotkeyMap = Record<string, HotkeyHandler>;
+export interface UseHotkeysOptions {
+    /** Attach the listener at all. Default `true`; pass `false` to suspend every combo at once. */
+    enabled?: boolean;
+    /** Scope the shortcuts to one element instead of the whole window. */
+    target?: RefObject<HTMLElement | null>;
+    /**
+     * Let plain-key combos fire while a text field or `contenteditable` has focus. Default `false`,
+     * so `'n'` does not fire for every `n` typed into an input. Combos carrying Ctrl, Cmd or Alt
+     * are never suppressed — they cannot be confused with typing.
+     */
+    enableInFields?: boolean;
+    /**
+     * Call `preventDefault()` on a match, so `mod+s` does not also open the browser's save dialog.
+     * Default `true`.
+     */
+    preventDefault?: boolean;
+}
+/**
+ * A combo written for the reader: `'mod+shift+k'` reads `⇧⌘K` on an Apple platform and
+ * `Ctrl+Shift+K` everywhere else.
+ *
+ * So a shortcut is written once, in one spelling, and the hint beside it cannot contradict what
+ * the binding actually listens for. Hand-written `'⌘K'` hints are wrong on every other platform,
+ * silently, because nothing compares the label to the binding.
+ *
+ * Resolved from the platform at call time, so a server-rendered page renders the non-Apple form.
+ */
+export declare function formatHotkey(combo: string): string;
+/**
+ * Keyboard shortcuts, for a whole app or for one element.
+ *
+ * ```tsx
+ * useHotkeys({ 'mod+k': () => setPaletteOpen(true), '?': () => setHelpOpen(true) });
+ * ```
+ *
+ * The map is read through a ref at event time, so an inline object literal is fine and no handler
+ * needs memoising. Shortcuts keep firing while a Modal or Drawer is open — pass `enabled` for the
+ * ones that should not.
+ */
+export declare function useHotkeys(hotkeys: HotkeyMap, options?: UseHotkeysOptions): void;
+export default useHotkeys;

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

@@ -19,8 +19,12 @@ export interface UseSwipeDismissOptions {
 }
 export interface UseSwipeDismissResult<T extends HTMLElement> {
     /** Attach to the element that should become draggable. The hook wires up its own pointer
-     * listeners on this node directly (no handlers to spread), so this is the only thing to attach. */
-    ref: React.RefObject<T | null>;
+     * listeners on this node directly (no handlers to spread), so this is the only thing to attach.
+     *
+     * A callback ref rather than an object one, because the hook has to know when the node changes:
+     * an element that is unmounted and rendered again is a *different* node, and a ref object cannot
+     * say so. To keep a ref of your own on the element, call both from one callback. */
+    ref: React.RefCallback<T>;
     /** True for the duration of an active drag — e.g. use it to pause an auto-dismiss timer. */
     isDragging: boolean;
 }

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

@@ -1,2 +1 @@
-export { default as IconLoading } from './iconLoading/index.js';
 export { default as SpinnerLoading } from './spinnerLoading/index.js';

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

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

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

@@ -10,10 +10,16 @@ export interface MenuAction {
     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.
+     * A keyboard shortcut for this action, in `useHotkeys` spelling: `'mod+k'`,
+     * `'shift+f2'`, `'delete'`. Shown on the trailing edge written for the
+     * platform: `⌘K` on an Apple one, `Ctrl+K` elsewhere.
+     *
+     * The menu draws it and nothing more. Binding is yours, because only the app
+     * knows what else is listening and whether the shortcut should work at all
+     * times or only while the menu is open. `menuHotkeys` turns these entries
+     * into a `useHotkeys` map, so the one spelling covers both ends.
      */
-    shortcut?: ReactNode;
+    shortcut?: string;
     disabled?: boolean;
     /** Renders in the destructive colour. For deleting, discarding, revoking. */
     danger?: boolean;

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

@@ -0,0 +1,20 @@
+import { HotkeyMap } from '../hooks/useHotkeys.js';
+import { MenuEntry } from './menu.types.js';
+/**
+ * The bindings for a menu's `shortcut` entries, to hand to `useHotkeys` yourself.
+ *
+ * The menu draws a shortcut but never listens for one, because only the app knows what else is
+ * listening: binding it here as well as in an app's own keymap would run the action twice, and
+ * whether a shortcut should work at all times or only while the menu is open is the app's
+ * question, not the menu's. Calling this keeps the answer in one spelling, so the hint the menu
+ * draws cannot drift from what actually fires.
+ *
+ * ```tsx
+ * useHotkeys(menuHotkeys(items, run));                      // whenever the page is up
+ * useHotkeys(menuHotkeys(items, run), { enabled: isOpen }); // only while the menu is open
+ * ```
+ *
+ * Runs each entry the way clicking it does: its own `onClick`, then `onAction`. A `disabled`
+ * entry, and an entry with no `shortcut`, is left out.
+ */
+export declare function menuHotkeys(items: MenuEntry[], onAction?: (id: string) => void): HotkeyMap;

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

@@ -1,5 +1,6 @@
 import { RefObject } from 'react';
 import { PopoverPlacement, PopoverAlign } from './popover.types.js';
+export declare function supportsAnchoring(): boolean;
 export interface UsePopoverPositionArgs {
     isOpen: boolean;
     placement: PopoverPlacement;

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

@@ -1,3 +1,3 @@
 import { default as React } from 'react';
 import { StickyProps } from './sticky.types.js';
-export default function Sticky({ children, offsetTop, offsetElement, stickToScrollParent, zIndex, disabled, onStuckChange, className, style, classNames, styles: slotStyles, ...rest }: StickyProps): React.JSX.Element;
+export default function Sticky({ children, offsetTop, offsetElement, stickToScrollParent, boundary, boundaryInset, zIndex, disabled, onStuckChange, className, style, classNames, styles: slotStyles, ...rest }: StickyProps): React.JSX.Element;

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

@@ -9,6 +9,21 @@ export interface StickyProps extends HtmlProps {
     offsetElement?: React.RefObject<HTMLElement | null>;
     /** Stick to the top of the nearest scrollable ancestor instead of the browser viewport. Falls back to the viewport if no scrollable ancestor is found. */
     stickToScrollParent?: boolean;
+    /**
+     * Element the content is confined to, normally the one it labels. Once that
+     * element's bottom edge reaches the pinned content, the content is pushed up
+     * with it and scrolls away, instead of staying pinned over whatever follows.
+     * Without it the content pins for as long as the page scrolls.
+     */
+    boundary?: React.RefObject<HTMLElement | null>;
+    /**
+     * How much of the boundary's lower end stays uncovered as the content leaves,
+     * in px. At 0 the content rests on the very bottom edge, which means the last
+     * stretch of the boundary, as tall as the pinned content, spends the whole
+     * exit hidden underneath it. Set it to how much you want to stay in sight:
+     * for a table header, a few rows. Default 0. Ignored without `boundary`.
+     */
+    boundaryInset?: number;
     /** z-index applied to the content while stuck. Default 20. */
     zIndex?: number;
     /** Disable sticking entirely — content stays in normal flow. */

package/dist/types/common/sticky/stickyStack.d.ts

@@ -15,6 +15,11 @@ export interface StickyStackMetrics {
      *  in unrelated scroll panels should never push each other down just because they happen to
      *  share horizontal DOM coordinates. */
     container: HTMLElement | null;
+    /** The element the entry is confined to, or null when nothing confines it.
+     *  Entries sharing one leave together. */
+    boundary: HTMLElement | null;
+    /** Bottom edge of that element (less its inset), in the same coordinate space as `top`. */
+    boundaryBottom: number | null;
 }
 export interface StickyStackEntry {
     node: HTMLElement;

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

@@ -1,2 +1,12 @@
 export declare function getScrollableAncestors(el: HTMLElement): HTMLElement[];
 export declare function isHiddenByAnyAncestor(rect: DOMRect, ancestors: HTMLElement[]): boolean;
+/**
+ * The ancestor whose scrollbar carries `el`, or null when that is the page.
+ * `Sticky` pins against it and `VirtualList` virtualizes against it, and the two
+ * have to agree or a sticky header and the rows under it come apart.
+ *
+ * Narrower than `getScrollableAncestors` above, which is about who *clips* and so
+ * counts `hidden` too: a `hidden` box never scrolls, so pinning to it would pin
+ * to something that never moves.
+ */
+export declare function getScrollParent(el: HTMLElement | null): HTMLElement | null;

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

@@ -0,0 +1,33 @@
+import { VirtualListScrollParent } from './virtualList.types.js';
+/**
+ * Whatever carries the list's scroll, and how the list is measured against it.
+ *
+ * Everything here works in *list space*: offset 0 is the top of the first row,
+ * which is the root's `scrollTop` when the list scrolls itself and its distance
+ * above the scrollport's top edge when it doesn't. One coordinate system, so the
+ * windowing, anchoring and jump math never branch.
+ */
+export type Scroller = HTMLElement | Window;
+export declare function isWindowScroller(scroller: Scroller): scroller is Window;
+/** `'nearest'` is resolved by the caller, which caches the ancestor walk. */
+export declare function resolveScroller(scrollParent: Exclude<VirtualListScrollParent, 'nearest'> | undefined): Scroller | null;
+/** In viewport coordinates, which is what the rects below are compared against. */
+export declare function scrollportBounds(scroller: Scroller): {
+    top: number;
+    height: number;
+};
+export interface Viewport {
+    /** List-space scroll position, unclamped: negative while the list starts below
+     *  the scrollport, which is what makes a target reachable from either side. */
+    rel: number;
+    /** The slice of the scrollport the list occupies now. */
+    visibleHeight: number;
+    /** The whole scrollport, which is what a scroll target is aimed within. */
+    viewportHeight: number;
+    /** From the list's last row to the end of the scrollport. The browser clamps
+     *  `scrollTop`, so a list that scrolls itself never reports this negative;
+     *  riding a scrollport, it does, for the whole rest of the page. */
+    distanceToEnd: number;
+    width: number;
+}
+export declare function measureViewport(root: HTMLElement, scroller: Scroller | null): Viewport;

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

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { TreeDropPosition, TreeDropTarget } from './virtualList.types.js';
+import { ListViewportRect } from './useVirtualWindow.js';
 interface UseRowDragArgs {
     reorderable: boolean;
     treeReorder: boolean;
@@ -15,6 +16,10 @@ interface UseRowDragArgs {
     rootRef: React.RefObject<HTMLDivElement | null>;
     /** Latest keys for async (touch / rAF) consumers — owned by useVirtualWindow. */
     keysRef: React.RefObject<(string | number)[]>;
+    /** Where the list is on screen, which is not its own box once it rides a
+     *  scrollport — owned by useVirtualWindow, as is `scrollBy`. */
+    getVisibleRect: () => ListViewportRect | null;
+    scrollBy: (dy: number) => void;
 }
 /** The drag-related props the parent spreads onto a given row. */
 export interface RowDragProps {
@@ -54,5 +59,5 @@ interface UseRowDragResult {
  * Touch uses a long-press → lifted-clone → pointer-move path with edge
  * auto-scroll. `dragHandle` restricts initiation to `[data-drag-handle]`.
  */
-export declare function useRowDrag({ reorderable, treeReorder, onReorder, onTreeDrop, longPressDelay, dragHandle, treeIndentPx, keys, depths, isGroupAt, rootRef, keysRef, }: UseRowDragArgs): UseRowDragResult;
+export declare function useRowDrag({ reorderable, treeReorder, onReorder, onTreeDrop, longPressDelay, dragHandle, treeIndentPx, keys, depths, isGroupAt, rootRef, keysRef, getVisibleRect, scrollBy, }: UseRowDragArgs): UseRowDragResult;
 export {};

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

@@ -1,12 +1,18 @@
 import { default as React } from 'react';
 import { VirtualListScrollOptions } from './virtualList.types.js';
+import { VisibleSlice } from './useVirtualWindow.js';
 interface UseRowNavigationArgs {
     enabled: boolean;
+    tabAcrossRows: boolean;
     rowCount: number;
     /** Row tops, from the windowing engine, used for paging and visibility. */
     offsets: number[];
     rootRef: React.RefObject<HTMLDivElement | null>;
     headerRef: React.RefObject<HTMLDivElement | null>;
+    /** Read live: a held arrow key moves the slice faster than the state commits. */
+    getVisibleSlice: () => VisibleSlice;
+    /** The whole scrollport, which is what one PageDown covers. */
+    viewportHeight: number;
     scrollToIndex: (index: number, options?: VirtualListScrollOptions) => void;
     /** Row index the active row starts on, normally the selected one. */
     initialIndex: number;
@@ -45,6 +51,10 @@ interface UseRowNavigationResult {
  * hold an input, a dropdown or a button, and every one of them wants the arrows,
  * Enter and Space for itself. `F2` steps into such a row and `Escape` steps back
  * out, which is the one pair of keys that does work from inside a cell.
+ *
+ * `tabAcrossRows` adds the second pair, Tab and Shift+Tab, which the browser
+ * cannot carry across a row boundary itself: the next row may not be in the DOM
+ * when it looks for the next stop.
  */
-export declare function useRowNavigation({ enabled, rowCount, offsets, rootRef, headerRef, scrollToIndex, initialIndex, multiSelect, onActivate, onToggleSelect, }: UseRowNavigationArgs): UseRowNavigationResult;
+export declare function useRowNavigation({ enabled, tabAcrossRows, rowCount, offsets, rootRef, headerRef, getVisibleSlice, viewportHeight, scrollToIndex, initialIndex, multiSelect, onActivate, onToggleSelect, }: UseRowNavigationArgs): UseRowNavigationResult;
 export {};

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

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { VirtualListHandle } from './virtualList.types.js';
+import { VirtualListHandle, VirtualListScrollParent } from './virtualList.types.js';
 interface UseVirtualWindowArgs<T> {
     items: T[];
     /** Stable key per row (already derived by the caller). */
@@ -12,6 +12,19 @@ interface UseVirtualWindowArgs<T> {
     loadMoreThreshold: number;
     /** Initial/filter load in progress — the body is replaced by a spinner. */
     isLoading: boolean;
+    scrollParent?: VirtualListScrollParent;
+}
+/** Where the list is on screen, which is not its own box once it rides a scrollport. */
+export interface ListViewportRect {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+/** The list-space slice currently on screen, read live for keyboard navigation. */
+export interface VisibleSlice {
+    top: number;
+    height: number;
 }
 interface UseVirtualWindowResult {
     rootRef: React.RefObject<HTMLDivElement | null>;
@@ -22,15 +35,21 @@ interface UseVirtualWindowResult {
     keysRef: React.RefObject<(string | number)[]>;
     offsets: number[];
     totalHeight: number;
+    /** The list's visible slice, which is what decides which rows are rendered. */
     containerHeight: number;
+    /** The whole scrollport, which is what a scroll target is aimed within. */
+    viewportHeight: number;
     containerWidth: number;
     startIndex: number;
     endIndex: number;
-    handleScroll: (e: React.UIEvent<HTMLDivElement>) => void;
     showLoadMoreSpinner: boolean;
+    isWindowed: boolean;
+    getVisibleSlice: () => VisibleSlice;
+    getVisibleRect: () => ListViewportRect | null;
+    scrollBy: (dy: number) => void;
     /** The scroll-related imperative methods, for the component to compose into
      *  the forwarded handle alongside column controls. */
     scrollApi: Omit<VirtualListHandle, 'recalculateColumns' | 'resetColumnWidths'>;
 }
-export declare function useVirtualWindow<T>({ items, keys, getItemKey, estimatedRowHeight, rowGap, overscan, onLoadMore, loadMoreThreshold, isLoading, }: UseVirtualWindowArgs<T>): UseVirtualWindowResult;
+export declare function useVirtualWindow<T>({ items, keys, getItemKey, estimatedRowHeight, rowGap, overscan, onLoadMore, loadMoreThreshold, isLoading, scrollParent, }: UseVirtualWindowArgs<T>): UseVirtualWindowResult;
 export {};

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

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
 import { VirtualListProps } from './virtualList.types.js';
 export { buildOffsets, findStartIndex, getVisibleRange, resolveReorderTarget, resolveTreeDropTarget, lastDescendantIndex, buildColumnTemplate, compareSortValues, isColumnSortable, isEmptySortValue, nextSort, sortItems, } from './virtualList.utils.js';
-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;
+declare function VirtualList<T>(props: VirtualListProps<T>): React.JSX.Element;
 export default VirtualList;

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

@@ -74,6 +74,13 @@ export interface VirtualListColumn<T> {
      */
     sortable?: boolean;
 }
+/**
+ * What scrolls, when the list is not to scroll itself. `'nearest'` is the first
+ * ancestor set to scroll, the same one `Sticky` pins to; `'window'` is the page;
+ * an element (or a getter for one, for a ref that fills after the first render)
+ * names it outright.
+ */
+export type VirtualListScrollParent = 'nearest' | 'window' | HTMLElement | (() => HTMLElement | null);
 export interface VirtualListScrollOptions {
     /** Where the target row lands in the viewport. Default: 'start'. */
     align?: 'start' | 'center' | 'end';
@@ -88,8 +95,18 @@ export interface VirtualListHandle {
     scrollToKey: (key: string | number, options?: VirtualListScrollOptions) => void;
     /** Scroll back to the top. */
     scrollToTop: (options?: Pick<VirtualListScrollOptions, 'behavior'>) => void;
-    /** The underlying scroll container element, for advanced use. */
-    getScrollElement: () => HTMLDivElement | null;
+    /**
+     * The element that scrolls: the list itself, or the `scrollParent` it was
+     * given. `null` for `scrollParent='window'`, where the page scrolls.
+     */
+    getScrollElement: () => HTMLElement | null;
+    /**
+     * Re-read where the list sits in its `scrollParent`. Only needed in that mode,
+     * and only when something *above* the list changed height without the list
+     * re-rendering: an element moving fires no event of its own, and the list
+     * would keep rendering the window it had before.
+     */
+    remeasure: () => void;
     /**
      * Re-measure `fit` columns on the next layout. Call this after an out-of-band
      * content change that doesn't flow through a new `items` array or `columns`
@@ -143,8 +160,22 @@ export interface VirtualListProps<T> extends HtmlProps {
         container: string;
         row: string;
     };
-    /** Height of the scroll viewport. Defaults to '100%' to fill the parent container. */
+    /** Height of the scroll viewport. Defaults to '100%' to fill the parent container. Ignored with `scrollParent`. */
     height?: number | string;
+    /**
+     * Drops the list's own scrollbar: it renders at its full height in the page
+     * flow and virtualizes against whatever is given here, so a long list at the
+     * end of a scrolling page doesn't put a second scrollbar inside the first.
+     * `height` no longer applies. `'nearest'` covers most cases: it walks up to
+     * the first ancestor whose `overflow-y` is set to scroll, whether or not it
+     * currently does, and falls back to the page.
+     *
+     * The header still sticks, now to the top of that scrollport; give the list
+     * `--vl-header-top` to clear a fixed app bar. Rows of uneven height move the
+     * page's own scrollbar as they are measured, so set `estimatedRowHeight` to
+     * the real height where the rows have one.
+     */
+    scrollParent?: VirtualListScrollParent;
     /** Estimated row height before measurement. Default: 40. */
     estimatedRowHeight?: number;
     /** Extra rows to render above/below the visible window. Default: 3. */
@@ -187,6 +218,15 @@ export interface VirtualListProps<T> extends HtmlProps {
      * `Tree` does.
      */
     keyboardNavigation?: boolean;
+    /**
+     * Lets Tab carry on into the next row instead of leaving the list at the end
+     * of the current one, for a grid of inputs a user fills in field by field.
+     * Shift+Tab walks back the same way, and Tab out of the last row (or back out
+     * of the first) leaves the list as it always did. Default: false, because for
+     * a list that is read rather than filled in, one tab stop and the arrow keys
+     * are the expected behaviour, and 5000 rows of tab stops are a trap.
+     */
+    tabAcrossRows?: boolean;
     /** Controlled visible column keys. When provided, internal state is ignored. */
     visibleColumnKeys?: string[];
     /** Called when the user toggles a column in the popover. */

package/dist/types/index.d.ts

@@ -148,6 +148,7 @@ export { default as VirtualList } from './common/virtualList/index.js';
 export * from './common/virtualList/index.js';
 export { default as Wizard } from './common/wizard/index.js';
 export * from './common/wizard/index.js';
+export * from './common/hooks/index.js';
 export { FormValidator, FormValidatorGroup, Validators, ValidatableComponent, useFormValidator, useFormValidatorGroup, } from './services/formValidation/index.js';
 export type { ValidationError, ValidatorFunction, ErrorParser, FormValidatorGroupOptions, InferGroupValues, MergedValues, } from './services/formValidation/index.js';
 export { mapLocale, setLocale, getLocale } from './services/localization.js';

package/docs/CLAUDE.md

@@ -73,6 +73,7 @@ enums and slot names. Do not infer props from a component's name.
 | FloorPlan.md | emptyFloorPlan, addWall, derivePlan | The shared data model behind `RoomDrawer` and `RoomViewer` |
 | FormValidator.md | FormValidator, Validators, useFormValidator | Track and validate a single form field's value, dirty/touched state, and errors |
 | FormValidatorGroup.md | useFormValidatorGroup, FormValidatorGroup, FormValidator, Validators | Manage a whole form — multiple fields, a single submit handler, validate-on-submit, dirty/touched tracking across the form, and mapping server-side errors back onto the right fields |
+| Hooks.md | useHotkeys, formatHotkey, useMediaQuery, useCoarsePointer, useVisualViewportSize, useScrollEdges, useSwipeDismiss, useOverlay, tabbablesIn | Standalone React hooks the library uses internally and publishes for the same jobs in your own code: keyboard shortcuts, media queries, the mobile keyboard's viewport, scroll-edge detection, swipe-to-dismiss, and the Escape / focus-trap / scroll-lock behaviour behind a custom overlay |
 | IconPicker.md | IconPicker | Pick one item from a visual icon/image grid — category selectors, emoji-style pickers, avatar selectors, anything where each option is best represented by an icon or image rather than text alone |
 | IdleManager.md | IdleManager | Show something only once the user has stopped interacting — a screen saver, a session-timeout warning, an "are you still there?" prompt, an idle dashboard view |
 | Input.md | Input, InputType | Text input with floating label, validation state, and type variants |
@@ -80,8 +81,8 @@ enums and slot names. Do not infer props from a component's name.
 | InteractableDiv.md | InteractableDiv | Accessible `<div>` that behaves like a button — click and keyboard (Enter/Space) events, with proper ARIA semantics |
 | KanbanBoard.md | KanbanBoard, KanbanColumn | Drag-and-drop board with columns — task management, workflow stages, status boards (e.g. Todo / In Progress / Done) |
 | KlipyPicker.md | KlipyPicker | GIF picker backed by the Klipy API — chat reactions, message composers, content authoring tools |
-| Loading.md | IconLoading, SpinnerLoading | Loading indicators for async operations — page loads, data fetching, button actions (when not using Button's built-in `isLoading`) |
-| Menu.md | Menu | A list of actions hanging off a trigger — a row's "more" button, a toolbar overflow, a context menu on a card |
+| Loading.md | SpinnerLoading | A loading indicator for async operations: page loads, data fetching, or covering a region while it refreshes |
+| Menu.md | Menu, menuHotkeys | A list of actions hanging off a trigger — a row's "more" button, a toolbar overflow, a context menu on a card |
 | Modal.md | Modal | Full overlay dialog — forms, detail views, confirmations, wizards that need to block the rest of the UI |
 | MultiSelect.md | MultiSelect | Pick several options from a list |
 | NumberInput.md | NumberInput | Numeric input with formatting — prices, quantities, percentages, phone numbers with separators |