@aurora-ds/components 1.5.0 → 1.6.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ComponentType, SVGProps, ButtonHTMLAttributes, Ref, FC, AnchorHTMLAttributes, ReactNode, HTMLAttributes, CSSProperties, TdHTMLAttributes, ThHTMLAttributes, AriaAttributes, ErrorInfo, Component, FormEvent, InputHTMLAttributes, MouseEvent, AriaRole } from 'react';
+import { ComponentType, SVGProps, ButtonHTMLAttributes, Ref, FC, AnchorHTMLAttributes, ReactNode, HTMLAttributes, CSSProperties, TdHTMLAttributes, ThHTMLAttributes, AriaAttributes, ErrorInfo, Component, FormEvent, InputHTMLAttributes, MouseEvent, AriaRole, RefObject, RefCallback } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 declare const lightPalette: {
@@ -2739,6 +2739,29 @@ declare const Dialog: DialogComponent;
 
 /** Where the menu opens relative to its anchor. */
 type MenuPlacement = 'bottom' | 'right';
+type UseMenuPositionOptions = {
+    /** Anchor element the menu is positioned relative to. */
+    anchorEl?: HTMLElement | null;
+    /** Whether the menu is currently open. */
+    open: boolean;
+    /** Ref to the menu panel element — used to measure actual dimensions. */
+    menuRef: RefObject<HTMLElement | null>;
+    /** Minimum width override. Defaults to the anchor element's width. */
+    minWidth?: number | string;
+    /** Gap in px between anchor and menu. @default 4 */
+    gap?: number;
+    /**
+     * Where the menu opens relative to the anchor.
+     * - `'bottom'` — opens below the anchor (default dropdown).
+     * - `'right'` — opens beside the anchor (submenu), flipping to the left when there is no room.
+     * @default 'bottom'
+     */
+    placement?: MenuPlacement;
+};
+type UseMenuPositionResult = {
+    /** Computed inline style to apply on the menu panel (top, left, minWidth). */
+    style: CSSProperties;
+};
 
 type MenuProps = {
     /** Whether the menu is visible. */
@@ -2867,9 +2890,211 @@ declare const Menu: MenuComponent;
  */
 declare const Tooltip: FC<TooltipProps>;
 
+/**
+ * Locks scrolling on `document.body` while `active` is true.
+ *
+ * Preserves the current scroll position and keeps the scrollbar gutter
+ * (`overflow-y: scroll`) to avoid horizontal layout shift when the scrollbar
+ * disappears. The original styles and scroll position are restored on cleanup.
+ *
+ * @example useBodyScrollLock(isDialogOpen)
+ */
+declare const useBodyScrollLock: (active: boolean) => void;
+
+type UseControllableStateOptions<T> = {
+    /** Controlled value. When defined, the hook operates in controlled mode. */
+    value?: T;
+    /** Initial value used in uncontrolled mode. */
+    defaultValue: T;
+    /** Called with the next value whenever `setValue` runs. */
+    onChange?: (value: T) => void;
+};
+type UseControllableStateResult<T> = [T, (next: T) => void];
+
+/**
+ * Unifies controlled and uncontrolled value handling.
+ *
+ * - When `value` is provided the hook is controlled: the returned value mirrors
+ *   it and internal state is never used to render.
+ * - Otherwise it is uncontrolled: state starts at `defaultValue` and updates
+ *   internally.
+ *
+ * In both modes `setValue` calls `onChange` with the next value, so consumers
+ * have a single code path regardless of mode.
+ *
+ * @example
+ * const [value, setValue] = useControllableState({ value, defaultValue: '', onChange })
+ */
+declare const useControllableState: <T>({ value, defaultValue, onChange, }: UseControllableStateOptions<T>) => UseControllableStateResult<T>;
+
+/**
+ * Traps Tab / Shift+Tab focus within the element referenced by `containerRef`
+ * while `active` is true. Focusable elements are recomputed on each Tab press
+ * so dynamic content is handled correctly. Required for accessible modals.
+ *
+ * @example useFocusTrap(panelRef, open)
+ */
+declare const useFocusTrap: (containerRef: RefObject<HTMLElement | null>, active: boolean) => void;
+
+type KeyPressHandler = (event: KeyboardEvent) => void;
+/** Map of key name → handler, for handling multiple keys in a single hook call. */
+type KeyPressMap = Partial<Record<KeyboardEvent['key'], KeyPressHandler>>;
+type UseKeyPressOptions = {
+    /** Only trigger when this element is the target (defaults to the whole document) */
+    target?: EventTarget | null;
+    /** Whether the listener is active */
+    enabled?: boolean;
+};
+
+/**
+ * Listens to keyboard events and dispatches to the matching handler in `keyMap`.
+ * A single hook call can handle multiple keys.
+ *
+ * @example
+ * `	s
+ * useKeyPress(
+ *   { ArrowDown: onDown, ArrowUp: onUp, Enter: onEnter, Escape: onClose },
+ *   { enabled: isOpen }
+ * )
+ * `
+ */
+declare const useKeyPress: (keyMap: KeyPressMap, { target, enabled }?: UseKeyPressOptions) => void;
+
+/**
+ * Merges several refs (callback or object) into a single stable callback ref.
+ *
+ * Useful when a component needs an internal ref while still forwarding the
+ * consumer's `ref`. The returned callback keeps a stable identity across
+ * renders to avoid detach/attach churn, always assigning to the latest refs.
+ *
+ * @example
+ * const inputRef = useRef<HTMLInputElement | null>(null)
+ * const mergedRef = useMergedRefs(ref, inputRef)
+ */
+declare const useMergedRefs: <T>(...refs: Array<Ref<T> | undefined>) => RefCallback<T>;
+
+type UseTransitionRenderReturnType = {
+    /** Whether the element should be mounted in the DOM. */
+    isVisible: boolean;
+    /** Whether the fade-in CSS class should be applied. */
+    isFadingIn: boolean;
+};
+
+/**
+ * Manages mount/unmount transitions with a two-phase approach (visible → fading-in).
+ *
+ * Opening sequence:
+ *   1. `useLayoutEffect` sets `isVisible=true` synchronously before the browser paints
+ *      → element is in the DOM at its initial hidden state on the very first frame.
+ *   2. Double `requestAnimationFrame` in `useEffect` waits for two rendered frames
+ *      before setting `isFadingIn=true`, guaranteeing the CSS transition always starts
+ *      from the painted hidden state (prevents flickering).
+ *
+ * Closing sequence:
+ *   `isFadingIn=false` → CSS transition plays → after `duration` ms → `isVisible=false`.
+ *
+ * @param isOpen - Whether the element should be shown.
+ * @param duration - Transition duration in milliseconds (defaults to `DEFAULT_TRANSITION_DURATION_MS`).
+ */
+declare const useTransitionRender: (isOpen: boolean, duration?: number) => UseTransitionRenderReturnType;
+
+type UseListKeyNavOptions = {
+    /** Total number of navigable items. */
+    itemCount: number;
+    /** Whether keyboard navigation is active (menu is open). */
+    enabled: boolean;
+    /** Called with the flat index of the item confirmed via Enter. */
+    onSelect: (index: number) => void;
+    /** Returns true if the item at a given index should be skipped during navigation. */
+    isDisabled?: (index: number) => boolean;
+    /** Whether navigation wraps around at boundaries. @default true */
+    loop?: boolean;
+    /** Index to focus when navigation becomes active. @default 0 */
+    initialIndex?: number;
+};
+type UseListKeyNavResult = {
+    /** Currently keyboard-focused item index, or -1 when navigation is inactive. */
+    focusedIndex: number;
+    /** Manually override the focused index. */
+    setFocusedIndex: (index: number) => void;
+};
+
+/**
+ * Manages keyboard navigation for a listbox-style menu.
+ *
+ * Binds ArrowDown, ArrowUp, Home, End, and Enter using `useKeyPress`.
+ * Automatically skips disabled items and optionally wraps around (loop).
+ * Resets focus when `enabled` toggles.
+ */
+declare const useListKeyNav: ({ itemCount, enabled, onSelect, isDisabled, loop, initialIndex, }: UseListKeyNavOptions) => UseListKeyNavResult;
+
+/**
+ * Computes and continuously updates the `position: fixed` style for a menu panel.
+ *
+ * Positioning strategy:
+ * - `placement="bottom"` (default): the menu opens below the anchor. If it would
+ *   overflow the bottom of the viewport, `top` is shifted up so the menu bottom
+ *   lands at `viewportHeight - margin` (never going off the top of the screen).
+ * - `placement="right"` (submenu): the menu opens to the right of the anchor and
+ *   flips to the left when there is no horizontal room. Its `top` aligns with the
+ *   anchor top and is clamped to the viewport.
+ *
+ * Scroll handling: the page scroll is locked while the menu is open (see
+ * `MenuPanel`), so the anchor cannot move out from under the menu. As a safety
+ * net for nested scroll containers, the menu re-positions on scroll/resize so it
+ * always stays attached to its anchor.
+ *
+ * Uses a two-pass strategy: first render with `menuHeight = 0`, then a rAF
+ * recompute with the actual rendered size to apply any overflow offset.
+ */
+declare const useMenuPosition: ({ anchorEl, open, menuRef, minWidth, gap, placement, }: UseMenuPositionOptions) => UseMenuPositionResult;
+
+type UseTooltipPositionOptions = {
+    /** Preferred placement of the tooltip relative to its trigger. */
+    placement: TooltipPlacement;
+};
+type TooltipPosition = {
+    top: number;
+    left: number;
+};
+type UseTooltipPositionResult = {
+    /** Ref to attach to the wrapper element (trigger container). */
+    wrapperRef: RefObject<HTMLDivElement | null>;
+    /** Ref to attach to the tooltip bubble element. */
+    bubbleRef: RefObject<HTMLDivElement | null>;
+    /** Whether the tooltip bubble should be mounted in the DOM. */
+    isVisible: boolean;
+    /** Whether the tooltip has faded in (drives opacity/scale transition). */
+    isFadingIn: boolean;
+    /** Computed fixed position for the tooltip bubble. */
+    position: TooltipPosition;
+    handleMouseEnter: () => void;
+    handleMouseLeave: () => void;
+    handleFocus: () => void;
+    handleBlur: () => void;
+    /** Hides the tooltip immediately (used when hideOnClick=true). */
+    handleClick: () => void;
+};
+
+/**
+ * Computes and continuously updates the `position: fixed` coordinates for a
+ * tooltip bubble, clamping it to the viewport on all four sides.
+ *
+ * Positioning strategy (two-pass):
+ * - First pass: mount the bubble at the preferred position.
+ * - Second pass (rAF): read the actual rendered size and clamp all sides.
+ *
+ * Handles:
+ * - All four placements: top, bottom, left, right.
+ * - Screen-edge clamping so the tooltip never overflows any side.
+ * - Fade-in animation (sets `isFadingIn` on next tick to trigger CSS transition).
+ * - Mouse/focus event handlers for show/hide.
+ */
+declare const useTooltipPosition: ({ placement, }: UseTooltipPositionOptions) => UseTooltipPositionResult;
+
 declare const lightTheme: Theme;
 
 declare const darkTheme: Theme;
 
-export { Accordion, Alert, Article, Aside, Avatar, AvatarGroup, Backdrop, Badge, Box, Breadcrumb, Button, Card, Checkbox, DatePicker, DefaultErrorFallback, Dialog, Drawer, ErrorBoundary, Fab, Footer, Form, Grid, Header, Icon, IconButton, Image, InfoBubble, Link, LoaderScreen, Main, Menu, Nav, Pagination, RadioButton, RadioGroup, Section, Select, Separator, Skeleton, Stack, SvgImage, Switch, Table, Tabs, Text, TextField, ToggleButton, ToggleGroup, ToggleIconButton, Tooltip, darkTheme, lightTheme, useDrawerContext };
-export type { AccordionBodyProps, AccordionProps, AccordionTitleProps, AlertBodyProps, AlertProps, AlertTitleProps, AlertVariant, ArticleProps, AsideProps, AvatarColor, AvatarGroupOverlap, AvatarGroupProps, AvatarProps, AvatarShape, AvatarSize, BackdropProps, BadgeColor, BadgeIcon, BadgeProps, BadgeSize, BadgeVariant, BoxProps, BreadcrumbItemProps, BreadcrumbProps, BreadcrumbSeparator, ButtonColor, ButtonIcon, ButtonProps, ButtonSize, ButtonVariant, CardBodyProps, CardHeaderProps, CardProps, CardVariant, CheckboxProps, DatePickerProps, DatePickerSize, DatePickerStatus, DefaultErrorFallbackProps, DialogBodyProps, DialogHeaderProps, DialogProps, DrawerBodyProps, DrawerFooterProps, DrawerHeaderProps, DrawerItemIcon, DrawerItemProps, DrawerProps, DrawerVariant, ErrorBoundaryFallbackRenderProps, ErrorBoundaryProps, FabColor, FabIcon, FabPlacement, FabProps, FabSize, FooterProps, FormProps, GridProps, GridStyleProps, HeaderProps, IconButtonProps, IconProps, IconStyleParams, ImageProps, InfoBubbleProps, LinkColor, LinkIcon, LinkProps, LinkUnderline, LoaderScreenProps, MainProps, MenuGroupProps, MenuItemProps, MenuItemRole, MenuPlacement, MenuProps, NavProps, PaginationProps, PaginationShape, PaginationSize, Palette, RadioButtonProps, RadioGroupProps, SectionProps, SelectOption, SelectProps, SeparatorOrientation, SeparatorProps, SeparatorStyleParams, SeparatorThickness, SkeletonAnimation, SkeletonProps, SkeletonVariant, StackProps, SvgImageProps, SwitchColor, SwitchProps, SwitchSize, TabItemProps, TableAlign, TableBodyProps, TableCellProps, TableColumn, TableFootProps, TableHeadProps, TableHeaderCellProps, TableLayout, TableProps, TableRowProps, TabsListProps, TabsPanelProps, TabsProps, TextFieldProps, TextFieldSize, TextFieldStatus, TextProps, TextStyleParams, TextVariantStyle, TextVariants, Theme, ToggleButtonProps, ToggleButtonVariant, ToggleGroupProps, ToggleIconButtonProps, TooltipPlacement, TooltipProps, WeekStart };
+export { Accordion, Alert, Article, Aside, Avatar, AvatarGroup, Backdrop, Badge, Box, Breadcrumb, Button, Card, Checkbox, DatePicker, DefaultErrorFallback, Dialog, Drawer, ErrorBoundary, Fab, Footer, Form, Grid, Header, Icon, IconButton, Image, InfoBubble, Link, LoaderScreen, Main, Menu, Nav, Pagination, RadioButton, RadioGroup, Section, Select, Separator, Skeleton, Stack, SvgImage, Switch, Table, Tabs, Text, TextField, ToggleButton, ToggleGroup, ToggleIconButton, Tooltip, darkTheme, lightTheme, useBodyScrollLock, useControllableState, useDrawerContext, useFocusTrap, useKeyPress, useListKeyNav, useMenuPosition, useMergedRefs, useTooltipPosition, useTransitionRender };
+export type { AccordionBodyProps, AccordionProps, AccordionTitleProps, AlertBodyProps, AlertProps, AlertTitleProps, AlertVariant, ArticleProps, AsideProps, AvatarColor, AvatarGroupOverlap, AvatarGroupProps, AvatarProps, AvatarShape, AvatarSize, BackdropProps, BadgeColor, BadgeIcon, BadgeProps, BadgeSize, BadgeVariant, BoxProps, BreadcrumbItemProps, BreadcrumbProps, BreadcrumbSeparator, ButtonColor, ButtonIcon, ButtonProps, ButtonSize, ButtonVariant, CardBodyProps, CardHeaderProps, CardProps, CardVariant, CheckboxProps, DatePickerProps, DatePickerSize, DatePickerStatus, DefaultErrorFallbackProps, DialogBodyProps, DialogHeaderProps, DialogProps, DrawerBodyProps, DrawerFooterProps, DrawerHeaderProps, DrawerItemIcon, DrawerItemProps, DrawerProps, DrawerVariant, ErrorBoundaryFallbackRenderProps, ErrorBoundaryProps, FabColor, FabIcon, FabPlacement, FabProps, FabSize, FooterProps, FormProps, GridProps, GridStyleProps, HeaderProps, IconButtonProps, IconProps, IconStyleParams, ImageProps, InfoBubbleProps, KeyPressHandler, KeyPressMap, LinkColor, LinkIcon, LinkProps, LinkUnderline, LoaderScreenProps, MainProps, MenuGroupProps, MenuItemProps, MenuItemRole, MenuPlacement, MenuProps, NavProps, PaginationProps, PaginationShape, PaginationSize, Palette, RadioButtonProps, RadioGroupProps, SectionProps, SelectOption, SelectProps, SeparatorOrientation, SeparatorProps, SeparatorStyleParams, SeparatorThickness, SkeletonAnimation, SkeletonProps, SkeletonVariant, StackProps, SvgImageProps, SwitchColor, SwitchProps, SwitchSize, TabItemProps, TableAlign, TableBodyProps, TableCellProps, TableColumn, TableFootProps, TableHeadProps, TableHeaderCellProps, TableLayout, TableProps, TableRowProps, TabsListProps, TabsPanelProps, TabsProps, TextFieldProps, TextFieldSize, TextFieldStatus, TextProps, TextStyleParams, TextVariantStyle, TextVariants, Theme, ToggleButtonProps, ToggleButtonVariant, ToggleGroupProps, ToggleIconButtonProps, TooltipPlacement, TooltipPosition, TooltipProps, UseControllableStateOptions, UseControllableStateResult, UseKeyPressOptions, UseListKeyNavOptions, UseListKeyNavResult, UseMenuPositionOptions, UseMenuPositionResult, UseTooltipPositionOptions, UseTooltipPositionResult, UseTransitionRenderReturnType, WeekStart };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurora-ds/components",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "type": "module",
   "description": "Aurora DS - React Components Library",
   "main": "dist/cjs/index.js",