@enonic/ui 0.15.1 → 0.17.0

package/dist/types/components/menubar/menubar.d.ts

@@ -0,0 +1,346 @@
+import { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
+/**
+ * Root component that provides context for the Menubar.
+ *
+ * Implements the ARIA menubar pattern for horizontal navigation.
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/menubar/}
+ *
+ * @example
+ * ```tsx
+ * <Menubar.Root>
+ *   <Menubar.Content aria-label="Main navigation">
+ *     <Menubar.Button>New</Menubar.Button>
+ *     <Menubar.Button>Save</Menubar.Button>
+ *   </Menubar.Content>
+ * </Menubar.Root>
+ * ```
+ */
+export type MenubarRootProps = {
+    /** Default active item ID on initial render */
+    defaultActive?: string;
+    /** Callback when active item changes */
+    onActiveChange?: (active: string | undefined) => void;
+    /** Base ID for generating unique IDs */
+    id?: string;
+    children?: ReactNode;
+};
+/**
+ * Container component that renders the menubar element with keyboard navigation.
+ *
+ * Implements horizontal arrow key navigation (ArrowLeft/Right), Home/End keys,
+ * and Tab key to exit the menubar.
+ *
+ * This is exported as part of the Menubar API but used for the horizontal menubar container,
+ * not the dropdown menu content (which is also named MenubarContent but context-aware).
+ *
+ * @example
+ * ```tsx
+ * <MenubarNav aria-label="Main menu" loop>
+ *   <Menubar.Button>File</Menubar.Button>
+ *   <Menubar.Button>Edit</Menubar.Button>
+ * </MenubarNav>
+ * ```
+ */
+export type MenubarNavProps = {
+    /** Accessible label for the menubar (required for screen readers) */
+    'aria-label': string;
+    /** Whether navigation should loop from last to first item */
+    loop?: boolean;
+    className?: string;
+    children?: ReactNode;
+} & ComponentPropsWithoutRef<'div'>;
+/**
+ * A button item within the menubar.
+ *
+ * Implements ARIA menuitem role and integrates with menubar keyboard navigation.
+ * Supports active state animations via Tailwind transitions.
+ *
+ * @example
+ * ```tsx
+ * <Menubar.Button onSelect={() => console.log('clicked')}>
+ *   Save
+ * </Menubar.Button>
+ *
+ * <Menubar.Button disabled>Export</Menubar.Button>
+ *
+ * <Menubar.Button asChild>
+ *   <a href="/new">New</a>
+ * </Menubar.Button>
+ * ```
+ */
+export type MenubarButtonProps = {
+    /** Unique ID for this button (auto-generated if not provided) */
+    id?: string;
+    /** Whether the button is disabled */
+    disabled?: boolean;
+    /** Callback when the button is selected (clicked or activated via keyboard) */
+    onSelect?: (event: Event) => void;
+    /** Render as a child element using Radix UI Slot */
+    asChild?: boolean;
+    className?: string;
+    children: ReactNode;
+} & Omit<ComponentPropsWithoutRef<'button'>, 'id' | 'children'>;
+/**
+ * A visual separator component that adapts based on context.
+ *
+ * - Within Menubar.Content (menubar): Renders as vertical separator between buttons
+ * - Within Menubar.Menu Content (dropdown): Renders as horizontal separator between items
+ *
+ * Does not participate in keyboard navigation (purely decorative).
+ *
+ * @example
+ * ```tsx
+ * // Vertical separator between menubar buttons
+ * <Menubar.Content aria-label="Actions">
+ *   <Menubar.Button>File</Menubar.Button>
+ *   <Menubar.Separator />
+ *   <Menubar.Button>Edit</Menubar.Button>
+ * </Menubar.Content>
+ *
+ * // Horizontal separator between menu items
+ * <Menubar.Menu>
+ *   <Menubar.Trigger>File</Menubar.Trigger>
+ *   <Menubar.Portal>
+ *     <Menubar.Content>
+ *       <Menubar.Item>New</Menubar.Item>
+ *       <Menubar.Separator />
+ *       <Menubar.Item>Exit</Menubar.Item>
+ *     </Menubar.Content>
+ *   </Menubar.Portal>
+ * </Menubar.Menu>
+ * ```
+ */
+export type MenubarSeparatorProps = {
+    className?: string;
+} & ComponentPropsWithoutRef<'div'>;
+/**
+ * Wrapper component that integrates dropdown menus within a Menubar.
+ *
+ * Coordinates between the menubar's horizontal navigation and the menu's
+ * vertical navigation, implementing the ARIA menubar pattern with submenus.
+ *
+ * Features:
+ * - Registers menu trigger as a menubar item for keyboard navigation
+ * - ArrowDown opens the menu from the menubar
+ * - ArrowLeft/Right navigate between menus (closing current, opening adjacent)
+ * - Automatic conditional hover (hover opens menu when another menu is open)
+ * - Tab closes menu and exits menubar entirely
+ *
+ * @example
+ * ```tsx
+ * <Menubar.Menu>
+ *   <Menubar.Trigger>File</Menubar.Trigger>
+ *   <Menubar.Portal>
+ *     <Menubar.Content>
+ *       <Menubar.Item>New</Menubar.Item>
+ *       <Menubar.Item>Open</Menubar.Item>
+ *     </Menubar.Content>
+ *   </Menubar.Portal>
+ * </Menubar.Menu>
+ * ```
+ */
+export type MenubarMenuProps = {
+    /** Unique ID for this menu within the menubar */
+    id?: string;
+    /** Whether the menu is disabled (cannot be opened) */
+    disabled?: boolean;
+    children?: ReactNode;
+};
+/**
+ * Trigger button for a menubar dropdown menu.
+ *
+ * Opens the menu on click, Enter, Space, or ArrowDown.
+ * Implements conditional hover: when another menu is open, hovering this
+ * trigger automatically opens its menu and closes the other.
+ *
+ * Must be used within Menubar.Menu.
+ *
+ * @example
+ * ```tsx
+ * <Menubar.Menu>
+ *   <Menubar.Trigger>File</Menubar.Trigger>
+ *   <Menubar.Portal>
+ *     <Menubar.Content>...</Menubar.Content>
+ *   </Menubar.Portal>
+ * </Menubar.Menu>
+ *
+ * <Menubar.Menu>
+ *   <Menubar.Trigger asChild>
+ *     <Button variant="text">Edit</Button>
+ *   </Menubar.Trigger>
+ *   <Menubar.Portal>
+ *     <Menubar.Content>...</Menubar.Content>
+ *   </Menubar.Portal>
+ * </Menubar.Menu>
+ * ```
+ */
+export type MenubarTriggerProps = {
+    /** Render as a child element using Radix UI Slot */
+    asChild?: boolean;
+    className?: string;
+    children: ReactNode;
+} & Omit<ComponentPropsWithoutRef<'button'>, 'children'>;
+/**
+ * Portal component that renders menubar dropdown content to document.body.
+ *
+ * Prevents z-index stacking issues by rendering outside the DOM hierarchy.
+ * Only renders when the menu is open unless `forceMount` is true.
+ *
+ * Must be used within Menubar.Menu.
+ *
+ * @example
+ * ```tsx
+ * <Menubar.Menu>
+ *   <Menubar.Trigger>File</Menubar.Trigger>
+ *   <Menubar.Portal>
+ *     <Menubar.Content>
+ *       <Menubar.Item>New</Menubar.Item>
+ *     </Menubar.Content>
+ *   </Menubar.Portal>
+ * </Menubar.Menu>
+ * ```
+ */
+export type MenubarPortalProps = {
+    /** Custom container element (defaults to document.body) */
+    container?: HTMLElement | null;
+    /** Keep content mounted in DOM even when menu is closed */
+    forceMount?: boolean;
+    children?: ReactNode;
+};
+/**
+ * Dropdown content container for a menubar menu.
+ *
+ * Positioned below the trigger with automatic viewport collision detection.
+ * Implements vertical keyboard navigation (ArrowUp/Down) within the menu,
+ * plus special ArrowLeft/Right handling to navigate between menus.
+ *
+ * Must be used within Menubar.Portal and Menubar.Menu.
+ *
+ * @example
+ * ```tsx
+ * <Menubar.Menu>
+ *   <Menubar.Trigger>File</Menubar.Trigger>
+ *   <Menubar.Portal>
+ *     <Menubar.Content align="start" loop>
+ *       <Menubar.Item>New File</Menubar.Item>
+ *       <Menubar.Item>Open File</Menubar.Item>
+ *       <Menubar.Separator />
+ *       <Menubar.Item>Exit</Menubar.Item>
+ *     </Menubar.Content>
+ *   </Menubar.Portal>
+ * </Menubar.Menu>
+ * ```
+ */
+export type MenubarContentProps = {
+    /** Horizontal alignment relative to trigger */
+    align?: 'start' | 'end';
+    /** Whether navigation should loop from last to first item */
+    loop?: boolean;
+    /** Keep content mounted in DOM even when menu is closed */
+    forceMount?: boolean;
+    /** Callback when Escape key is pressed */
+    onEscapeKeyDown?: (event: React.KeyboardEvent<HTMLDivElement>) => void;
+    /** Callback when pointer clicks outside the menu */
+    onPointerDownOutside?: (event: PointerEvent) => void;
+    /** Callback when any outside interaction occurs */
+    onInteractOutside?: (event: Event) => void;
+    className?: string;
+    children?: ReactNode;
+} & ComponentPropsWithoutRef<'div'>;
+/**
+ * An interactive item within a menubar dropdown menu.
+ *
+ * Supports keyboard navigation, hover effects, and the onSelect callback.
+ * Automatically closes the menu when selected.
+ *
+ * Must be used within Menubar.Content.
+ *
+ * @example
+ * ```tsx
+ * <Menubar.Content>
+ *   <Menubar.Item onSelect={() => console.log('New file')}>
+ *     New File
+ *   </Menubar.Item>
+ *   <Menubar.Item disabled>
+ *     Save (disabled)
+ *   </Menubar.Item>
+ *   <Menubar.Item asChild>
+ *     <a href="/export">Export</a>
+ *   </Menubar.Item>
+ * </Menubar.Content>
+ * ```
+ */
+export type MenubarItemProps = {
+    /** Unique ID for this item (auto-generated if not provided) */
+    id?: string;
+    /** Whether the item is disabled */
+    disabled?: boolean;
+    /** Callback when the item is selected (clicked or activated via keyboard) */
+    onSelect?: (event: Event) => void;
+    /** Render as a child element using Radix UI Slot */
+    asChild?: boolean;
+    className?: string;
+    children: ReactNode;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'id' | 'children'>;
+/**
+ * A non-interactive label for grouping items within a menubar dropdown.
+ *
+ * Used to provide section headings or context within the menu.
+ * Does not participate in keyboard navigation.
+ *
+ * Must be used within Menubar.Content.
+ *
+ * @example
+ * ```tsx
+ * <Menubar.Content>
+ *   <Menubar.Label>File Operations</Menubar.Label>
+ *   <Menubar.Item>New</Menubar.Item>
+ *   <Menubar.Item>Open</Menubar.Item>
+ *   <Menubar.Separator />
+ *   <Menubar.Label>Recent Files</Menubar.Label>
+ *   <Menubar.Item>Document.txt</Menubar.Item>
+ * </Menubar.Content>
+ * ```
+ */
+export type MenubarLabelProps = {
+    className?: string;
+    children?: ReactNode;
+} & ComponentPropsWithoutRef<'div'>;
+export declare const Menubar: {
+    ({ defaultActive, onActiveChange, id, children }: MenubarRootProps): ReactElement;
+    displayName: string;
+} & {
+    Root: {
+        ({ defaultActive, onActiveChange, id, children }: MenubarRootProps): ReactElement;
+        displayName: string;
+    };
+    Nav: import('preact').FunctionalComponent<import('preact/compat').PropsWithoutRef<MenubarNavProps> & {
+        ref?: import('preact').Ref<HTMLDivElement> | undefined;
+    }>;
+    Content: import('preact').FunctionalComponent<import('preact/compat').PropsWithoutRef<MenubarContentProps> & {
+        ref?: import('preact').Ref<HTMLDivElement> | undefined;
+    }>;
+    Button: import('preact').FunctionalComponent<import('preact/compat').PropsWithoutRef<MenubarButtonProps> & {
+        ref?: import('preact').Ref<HTMLButtonElement> | undefined;
+    }>;
+    Separator: import('preact').FunctionalComponent<import('preact/compat').PropsWithoutRef<MenubarSeparatorProps> & {
+        ref?: import('preact').Ref<HTMLDivElement> | undefined;
+    }>;
+    Menu: {
+        ({ id: providedId, disabled, children }: MenubarMenuProps): ReactElement;
+        displayName: string;
+    };
+    Trigger: import('preact').FunctionalComponent<import('preact/compat').PropsWithoutRef<MenubarTriggerProps> & {
+        ref?: import('preact').Ref<HTMLButtonElement> | undefined;
+    }>;
+    Portal: {
+        ({ container, forceMount, children }: MenubarPortalProps): ReactElement | null;
+        displayName: string;
+    };
+    Item: import('preact').FunctionalComponent<import('preact/compat').PropsWithoutRef<MenubarItemProps> & {
+        ref?: import('preact').Ref<HTMLDivElement> | undefined;
+    }>;
+    Label: import('preact').FunctionalComponent<import('preact/compat').PropsWithoutRef<MenubarLabelProps> & {
+        ref?: import('preact').Ref<HTMLDivElement> | undefined;
+    }>;
+};

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

@@ -1,4 +1,10 @@
-export { useScrollLock } from './use-scroll-lock';
+export { useActiveItemFocus, type UseActiveItemFocusConfig } from './use-active-item-focus';
+export { useClickOutside, type UseClickOutsideConfig } from './use-click-outside';
 export { useControlledState } from './use-controlled-state';
+export { useControlledStateWithNull } from './use-controlled-state-with-null';
+export { useFloatingPosition, type FloatingPosition, type UseFloatingPositionConfig } from './use-floating-position';
 export { useItemRegistry, type ItemMetadata, type UseItemRegistryReturn } from './use-item-registry';
 export { useKeyboardNavigation, type KeyboardNavigationConfig, type UseKeyboardNavigationReturn, } from './use-keyboard-navigation';
+export { useRovingTabIndex, type UseRovingTabIndexConfig, type UseRovingTabIndexReturn } from './use-roving-tabindex';
+export { useScrollActiveIntoView, type UseScrollActiveIntoViewConfig } from './use-scroll-active-into-view';
+export { useScrollLock } from './use-scroll-lock';

package/dist/types/hooks/use-active-item-focus.d.ts

@@ -0,0 +1,83 @@
+import { RefObject } from 'react';
+export type UseActiveItemFocusConfig = {
+    /** Reference to the item element to focus */
+    ref: RefObject<HTMLElement> | null;
+    /** Whether this item is currently active */
+    isActive: boolean;
+    /** Whether this item is disabled */
+    disabled: boolean;
+    /**
+     * Focus mode - determines when to auto-focus:
+     * - 'roving-tabindex': Auto-focus when active (default)
+     * - 'activedescendant': Don't auto-focus (container manages focus)
+     */
+    focusMode?: 'roving-tabindex' | 'activedescendant';
+    /**
+     * When true, only focus if focus is already within the container.
+     * This prevents mouse hover from causing focus rings when navigating with keyboard.
+     *
+     * @example
+     * In Listbox, we only want to auto-focus during keyboard navigation,
+     * not when the user hovers with their mouse. We check if focus is
+     * already within the listbox to determine if keyboard nav is active.
+     */
+    checkFocusWithin?: {
+        /** Enable the focus-within check */
+        enabled: boolean;
+        /** ARIA role of the container to check (e.g., 'listbox', 'menu') */
+        containerRole: string;
+    };
+};
+/**
+ * Automatically focuses an element when it becomes active, typically used
+ * in keyboard navigation patterns like roving tabindex.
+ *
+ * This hook handles the common pattern where an item should receive DOM focus
+ * when it becomes the "active" item in a list, menu, or navigation structure.
+ * It includes safeguards to:
+ * - Only focus when not disabled
+ * - Only focus when not already focused (prevents infinite loops)
+ * - Optionally check if focus is within the container (prevents hover-induced focus)
+ * - Respect focus mode (roving-tabindex vs activedescendant)
+ *
+ * @param config - Configuration object for auto-focus behavior
+ *
+ * @example
+ * ```tsx
+ * // Basic usage (Menu item)
+ * function MenuItem() {
+ *   const itemRef = useRef<HTMLDivElement>(null);
+ *   const { active } = useMenu();
+ *   const isActive = active === id;
+ *
+ *   useActiveItemFocus({
+ *     ref: itemRef,
+ *     isActive,
+ *     disabled: false,
+ *   });
+ *
+ *   return <div ref={itemRef}>Item</div>;
+ * }
+ *
+ * // With focus-within check (Listbox item)
+ * function ListboxItem() {
+ *   const itemRef = useRef<HTMLDivElement>(null);
+ *   const { active, focusMode } = useListbox();
+ *   const isActive = active === id;
+ *
+ *   useActiveItemFocus({
+ *     ref: itemRef,
+ *     isActive,
+ *     disabled: false,
+ *     focusMode,
+ *     checkFocusWithin: {
+ *       enabled: true,
+ *       containerRole: 'listbox',
+ *     },
+ *   });
+ *
+ *   return <div ref={itemRef}>Item</div>;
+ * }
+ * ```
+ */
+export declare function useActiveItemFocus({ ref, isActive, disabled, focusMode, checkFocusWithin, }: UseActiveItemFocusConfig): void;

package/dist/types/hooks/use-click-outside.d.ts

@@ -0,0 +1,99 @@
+import { RefObject } from 'react';
+export type UseClickOutsideConfig = {
+    /** Whether the click outside listener is active */
+    enabled: boolean;
+    /** Reference to the content element (clicks inside are ignored) */
+    contentRef: RefObject<HTMLElement>;
+    /**
+     * Optional references to elements that should be excluded from "outside" detection.
+     * Typically used for trigger buttons that toggle the content visibility.
+     */
+    excludeRefs?: (RefObject<HTMLElement> | undefined)[];
+    /** Callback when pointer down occurs outside */
+    onPointerDownOutside?: (event: PointerEvent) => void;
+    /** Callback when any interaction occurs outside */
+    onInteractOutside?: (event: Event) => void;
+    /**
+     * Callback to close/hide the content.
+     * Only called if event.defaultPrevented is false.
+     */
+    onClose?: () => void;
+};
+/**
+ * Detects clicks/pointer events outside a content element and triggers callbacks.
+ *
+ * This hook is commonly used for dismissible UI elements like dropdowns, menus,
+ * dialogs, and popovers that should close when the user clicks outside.
+ *
+ * Features:
+ * - Ignores clicks inside the content element
+ * - Supports excluding additional elements (e.g., trigger buttons)
+ * - Respects event.defaultPrevented to allow custom handling
+ * - Only active when enabled
+ * - Properly cleans up event listeners
+ *
+ * @param config - Configuration object for click outside detection
+ *
+ * @example
+ * ```tsx
+ * // Basic usage (Dialog)
+ * function Dialog() {
+ *   const [open, setOpen] = useState(false);
+ *   const contentRef = useRef<HTMLDivElement>(null);
+ *
+ *   useClickOutside({
+ *     enabled: open,
+ *     contentRef,
+ *     onClose: () => setOpen(false),
+ *   });
+ *
+ *   if (!open) return null;
+ *   return <div ref={contentRef}>Dialog content</div>;
+ * }
+ *
+ * // With trigger exclusion (Menu)
+ * function Menu() {
+ *   const [open, setOpen] = useState(false);
+ *   const triggerRef = useRef<HTMLButtonElement>(null);
+ *   const contentRef = useRef<HTMLDivElement>(null);
+ *
+ *   useClickOutside({
+ *     enabled: open,
+ *     contentRef,
+ *     excludeRefs: [triggerRef],
+ *     onPointerDownOutside: (e) => console.log('Outside click', e),
+ *     onInteractOutside: (e) => console.log('Outside interaction', e),
+ *     onClose: () => setOpen(false),
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <button ref={triggerRef}>Open Menu</button>
+ *       {open && <div ref={contentRef}>Menu content</div>}
+ *     </>
+ *   );
+ * }
+ *
+ * // With custom close prevention
+ * function CustomDialog() {
+ *   const [open, setOpen] = useState(false);
+ *   const contentRef = useRef<HTMLDivElement>(null);
+ *
+ *   useClickOutside({
+ *     enabled: open,
+ *     contentRef,
+ *     onPointerDownOutside: (e) => {
+ *       const shouldClose = confirm('Close dialog?');
+ *       if (!shouldClose) {
+ *         e.preventDefault(); // Prevents onClose from being called
+ *       }
+ *     },
+ *     onClose: () => setOpen(false),
+ *   });
+ *
+ *   if (!open) return null;
+ *   return <div ref={contentRef}>Dialog content</div>;
+ * }
+ * ```
+ */
+export declare function useClickOutside({ enabled, contentRef, excludeRefs, onPointerDownOutside, onInteractOutside, onClose, }: UseClickOutsideConfig): void;

package/dist/types/hooks/use-controlled-state-with-null.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A variant of `useControlledState` that handles `null` as "no value" in controlled mode.
+ *
+ * This hook provides a clean external API where `null` represents "no value" while
+ * internally using `undefined` for consistency with React/Preact patterns.
+ *
+ * **External API (Component Props):**
+ * - `undefined` = uncontrolled mode (prop not provided)
+ * - `null` = controlled mode with no value
+ * - `value` = controlled mode with value
+ *
+ * **Internal State:**
+ * - `undefined` = no value (converted from external `null`)
+ * - `value` = has value
+ *
+ * @template T - The type of the state value (typically `string`)
+ *
+ * @param controlledValue - The controlled value from props (e.g., `active`)
+ * @param defaultValue - The default value for uncontrolled mode
+ * @param onChange - Callback invoked when the value changes (receives `null` for no value)
+ *
+ * @returns A tuple containing the current value and a setter function
+ *
+ * @example
+ * ```tsx
+ * // Component with controlled "no active" support
+ * function Listbox({ active, defaultActive, setActive }: {
+ *   active?: string | null;
+ *   defaultActive?: string;
+ *   setActive?: (active: string | null) => void;
+ * }) {
+ *   const [activeInternal, setActiveInternal] = useControlledStateWithNull(
+ *     active,
+ *     defaultActive,
+ *     setActive
+ *   );
+ *
+ *   // activeInternal is string | undefined internally
+ *   // But external API uses string | null
+ *
+ *   // active={null} → activeInternal = undefined
+ *   // active="item" → activeInternal = "item"
+ *   // active not provided → activeInternal from defaultActive
+ * }
+ * ```
+ */
+export declare function useControlledStateWithNull<T extends string>(controlledValue: T | null | undefined, defaultValue: T | undefined, onChange?: (value: T | null) => void): [T | undefined, (value: T | null | undefined) => void];

package/dist/types/hooks/use-controlled-state.d.ts

@@ -1,8 +1,8 @@
 /**
  * Manages state that can be either controlled or uncontrolled.
- * Follows the pattern for controlled/uncontrolled state management.
+ * Follows the React pattern for controlled/uncontrolled state management.
  *
- * @template T - The type of the state value
+ * @template T - The type of the state value (can include `null` for "no value" state)
  *
  * @param controlledValue - The controlled value from props (e.g., `value`, `open`, `checked`)
  * @param defaultValue - The default value for uncontrolled mode (e.g., `defaultValue`, `defaultOpen`)
@@ -10,6 +10,16 @@
  *
  * @returns A tuple containing the current value and a setter function
  *
+ * **Controlled vs Uncontrolled Detection:**
+ * - `undefined` = uncontrolled mode (prop not provided)
+ * - Any other value (including `null`) = controlled mode
+ *
+ * **Supporting "No Value" in Controlled Mode:**
+ * Use `null` to represent "no value" in controlled mode:
+ * - `active={null}` → controlled with no active item
+ * - `active="item-1"` → controlled with active item
+ * - `active` not provided → uncontrolled mode
+ *
  * @example
  * ```tsx
  * // Uncontrolled usage
@@ -23,6 +33,14 @@
  *   const [value, setValue] = useControlledState(open, false, onOpenChange);
  *   return <div>{value ? 'Open' : 'Closed'}</div>;
  * }
+ *
+ * // Controlled with null support (for "no value" state)
+ * function Component({ active, onActiveChange }: { active?: string | null }) {
+ *   const [value, setValue] = useControlledState(active, undefined, onActiveChange);
+ *   // active={null} → controlled, value = null
+ *   // active="item" → controlled, value = "item"
+ *   // active not provided → uncontrolled, value from defaultActive
+ * }
  * ```
  */
 export declare function useControlledState<T>(controlledValue: T | undefined, defaultValue: T, onChange?: (value: T) => void): [T, (value: T) => void];

package/dist/types/hooks/use-floating-position.d.ts

@@ -0,0 +1,58 @@
+import { RefObject } from 'react';
+export type FloatingPosition = {
+    top: number;
+    left?: number;
+    right?: number;
+};
+export type UseFloatingPositionConfig = {
+    /** Whether the floating element is open/visible */
+    enabled: boolean;
+    /** Reference to the trigger element */
+    triggerRef: RefObject<HTMLElement> | null;
+    /** Reference to the floating content element */
+    contentRef: RefObject<HTMLElement> | null;
+    /** Horizontal alignment relative to trigger */
+    align?: 'start' | 'end';
+};
+/**
+ * Calculates optimal position for floating elements (menus, dropdowns) relative to a trigger,
+ * with automatic viewport collision detection and flip behavior.
+ *
+ * This hook handles:
+ * - Positioning below trigger with configurable alignment
+ * - Vertical flipping when overflowing bottom edge
+ * - Horizontal adjustment to stay within viewport bounds
+ * - Automatic repositioning on window resize and scroll
+ *
+ * @param config - Configuration object for positioning behavior
+ * @returns Position object with top and left/right coordinates, or null if not yet calculated
+ *
+ * @example
+ * ```tsx
+ * function Menu() {
+ *   const triggerRef = useRef<HTMLButtonElement>(null);
+ *   const contentRef = useRef<HTMLDivElement>(null);
+ *   const position = useFloatingPosition({
+ *     enabled: open,
+ *     triggerRef,
+ *     contentRef,
+ *     align: 'start'
+ *   });
+ *
+ *   return (
+ *     <div
+ *       ref={contentRef}
+ *       style={{
+ *         position: 'fixed',
+ *         top: position ? `${position.top}px` : '0',
+ *         left: position?.left !== undefined ? `${position.left}px` : undefined,
+ *         right: position?.right !== undefined ? `${position.right}px` : undefined,
+ *       }}
+ *     >
+ *       Menu content
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useFloatingPosition({ enabled, triggerRef, contentRef, align, }: UseFloatingPositionConfig): FloatingPosition | null;