@enonic/ui 0.16.0 → 0.18.0

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

package/dist/types/hooks/use-roving-tabindex.d.ts

@@ -0,0 +1,69 @@
+export type UseRovingTabIndexConfig = {
+    /** The ID of this item */
+    id: string;
+    /** Currently active item ID (undefined if no item is active) */
+    active: string | undefined;
+    /** Whether this item is disabled */
+    disabled: boolean;
+    /** Function to get all registered item IDs */
+    getItems: () => string[];
+    /** Function to check if a specific item is disabled */
+    isItemDisabled: (id: string) => boolean;
+    /**
+     * Focus mode for the component
+     * - 'roving-tabindex': Items are individually focusable (default)
+     * - 'activedescendant': Container manages focus via aria-activedescendant
+     */
+    focusMode?: 'roving-tabindex' | 'activedescendant';
+};
+export type UseRovingTabIndexReturn = {
+    /** Whether this item should be focusable (tabIndex=0) */
+    isFocusable: boolean;
+    /** The tabIndex value to apply to this item */
+    tabIndex: number;
+};
+/**
+ * Implements roving tabindex pattern for keyboard navigation.
+ *
+ * In roving tabindex, only one item in a list is focusable at a time (tabIndex=0),
+ * while all other items have tabIndex=-1. This allows users to:
+ * - Tab into the list (focuses the active or first available item)
+ * - Use arrow keys to navigate within the list
+ * - Tab out of the list
+ *
+ * The hook automatically determines which item should be focusable based on:
+ * 1. The currently active item (if set and not disabled)
+ * 2. The first non-disabled item (fallback)
+ * 3. The first item in the list (if all items are disabled)
+ * 4. This item itself (final fallback if no other items exist)
+ *
+ * @param config - Configuration object for roving tabindex behavior
+ * @returns Object containing isFocusable flag and tabIndex value
+ *
+ * @example
+ * ```tsx
+ * function MenuItem({ id, disabled }: MenuItemProps) {
+ *   const { active, getItems, isItemDisabled } = useMenu();
+ *   const { isFocusable, tabIndex } = useRovingTabIndex({
+ *     id,
+ *     active,
+ *     disabled,
+ *     getItems,
+ *     isItemDisabled,
+ *   });
+ *
+ *   return (
+ *     <div
+ *       role="menuitem"
+ *       tabIndex={tabIndex}
+ *       data-focusable={isFocusable || undefined}
+ *     >
+ *       {children}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex}
+ */
+export declare function useRovingTabIndex({ id, active, disabled, getItems, isItemDisabled, focusMode, }: UseRovingTabIndexConfig): UseRovingTabIndexReturn;

package/dist/types/hooks/use-scroll-active-into-view.d.ts

@@ -0,0 +1,83 @@
+import { RefObject } from 'react';
+export type UseScrollActiveIntoViewConfig = {
+    /** Reference to the container element */
+    containerRef: RefObject<HTMLElement> | null;
+    /** ID of the currently active item (undefined if no active item) */
+    activeId: string | undefined;
+    /**
+     * Scroll orientation:
+     * - 'vertical': Only scroll vertically (block: 'nearest')
+     * - 'horizontal': Scroll both horizontally and vertically (block + inline: 'nearest')
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /**
+     * Optional function to construct the element ID from the active ID.
+     * If not provided, uses activeId directly.
+     *
+     * @example
+     * // For Listbox, which prefixes IDs:
+     * buildElementId: (id) => `${baseId}-listbox-option-${id}`
+     */
+    buildElementId?: (activeId: string) => string;
+};
+/**
+ * Automatically scrolls the active item into view within a scrollable container.
+ *
+ * This hook is commonly used in keyboard-navigable lists, menus, and navigation
+ * components to ensure the currently active item is visible when it changes.
+ *
+ * Features:
+ * - Smooth scrolling behavior with 'nearest' algorithm (minimal scroll distance)
+ * - Supports both vertical and horizontal scrolling
+ * - Supports custom ID construction for prefixed/namespaced IDs
+ * - Only scrolls when activeId changes
+ *
+ * @param config - Configuration object for scroll behavior
+ *
+ * @example
+ * ```tsx
+ * // Vertical list (Menu)
+ * function MenuContent() {
+ *   const contentRef = useRef<HTMLDivElement>(null);
+ *   const { active } = useMenu();
+ *
+ *   useScrollActiveIntoView({
+ *     containerRef: contentRef,
+ *     activeId: active,
+ *     orientation: 'vertical',
+ *   });
+ *
+ *   return <div ref={contentRef}>...</div>;
+ * }
+ *
+ * // Horizontal navigation (Menubar)
+ * function Menubar() {
+ *   const menubarRef = useRef<HTMLDivElement>(null);
+ *   const { active } = useMenubar();
+ *
+ *   useScrollActiveIntoView({
+ *     containerRef: menubarRef,
+ *     activeId: active,
+ *     orientation: 'horizontal',
+ *   });
+ *
+ *   return <div ref={menubarRef}>...</div>;
+ * }
+ *
+ * // With ID prefix (Listbox)
+ * function ListboxContent({ baseId }: { baseId: string }) {
+ *   const contentRef = useRef<HTMLDivElement>(null);
+ *   const { active } = useListbox();
+ *
+ *   useScrollActiveIntoView({
+ *     containerRef: contentRef,
+ *     activeId: active,
+ *     orientation: 'vertical',
+ *     buildElementId: (id) => `${baseId}-listbox-option-${id}`,
+ *   });
+ *
+ *   return <div ref={contentRef}>...</div>;
+ * }
+ * ```
+ */
+export declare function useScrollActiveIntoView({ containerRef, activeId, orientation, buildElementId, }: UseScrollActiveIntoViewConfig): void;

package/dist/types/providers/listbox-provider.d.ts

@@ -9,7 +9,12 @@ export type ListboxContextValue = {
     selection: ReadonlySet<string>;
     selectionMode: 'single' | 'multiple';
     disabled?: boolean;
-    focusable?: boolean;
+    /**
+     * Focus management mode:
+     * - 'roving-tabindex': Items are individually focusable (default)
+     * - 'activedescendant': Container manages focus via aria-activedescendant
+     */
+    focusMode?: 'roving-tabindex' | 'activedescendant';
     /**
      * Set active item.
      * Accepts `null` for compatibility with controlled prop API, but converts it to `undefined` internally.

package/dist/types/providers/menubar-provider.d.ts

@@ -23,9 +23,7 @@ export type MenubarContextValue = {
     isItemDisabled: (id: string) => boolean;
     /**
      * ID of the currently open menu (if any).
-     * Used in Phase 2 to track which menu is expanded in the menubar.
-     *
-     * @phase2
+     * Tracks which menu is expanded in the menubar for conditional hover behavior.
      */
     openMenuId: string | undefined;
     setOpenMenuId: (id: string | undefined) => void;
@@ -67,9 +65,8 @@ export declare const useMenubar: () => MenubarContextValue;
  * Hook to optionally access menubar context.
  * Returns undefined if not within a MenubarProvider.
  *
- * Useful for components that can work both inside and outside a menubar (e.g., Menu.Trigger).
+ * Useful for components that can work both inside and outside a menubar.
  *
- * @phase2 Used by Menu components to detect if they're within a Menubar
  * @returns {MenubarContextValue | undefined} The menubar context or undefined
  */
 export declare const useMenubarOptional: () => MenubarContextValue | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enonic/ui",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Enonic UI Component Library",
   "author": "Enonic",
   "license": "MIT",
@@ -46,7 +46,7 @@
   "dependencies": {
     "class-variance-authority": "~0.7.1",
     "clsx": "~2.1.1",
-    "tailwind-merge": "~3.3.1"
+    "tailwind-merge": "~3.4.0"
   },
   "peerDependencies": {
     "@radix-ui/react-slot": "^1.2.0",
@@ -68,44 +68,44 @@
     }
   },
   "devDependencies": {
-    "@chromatic-com/storybook": "~4.1.1",
-    "@eslint/js": "~9.37.0",
+    "@chromatic-com/storybook": "~4.1.2",
+    "@eslint/js": "~9.39.1",
     "@preact/preset-vite": "~2.10.2",
     "@size-limit/file": "~11.2.0",
     "@size-limit/preset-small-lib": "~11.2.0",
-    "@storybook/addon-a11y": "~9.1.10",
-    "@storybook/addon-docs": "~9.1.10",
-    "@storybook/addon-links": "~9.1.10",
-    "@storybook/addon-themes": "~9.1.10",
-    "@storybook/preact-vite": "~9.1.10",
-    "@tailwindcss/vite": "~4.1.14",
-    "@trivago/prettier-plugin-sort-imports": "~5.2.2",
-    "@types/node": "~24.7.2",
-    "@types/react": "~19.2.2",
-    "@types/react-dom": "~19.2.1",
-    "@typescript-eslint/eslint-plugin": "~8.46.0",
-    "@typescript-eslint/parser": "~8.46.0",
-    "eslint": "~9.37.0",
+    "@storybook/addon-a11y": "~10.0.7",
+    "@storybook/addon-docs": "~10.0.7",
+    "@storybook/addon-links": "~10.0.7",
+    "@storybook/addon-themes": "~10.0.7",
+    "@storybook/preact-vite": "~10.0.7",
+    "@tailwindcss/vite": "~4.1.17",
+    "@trivago/prettier-plugin-sort-imports": "~6.0.0",
+    "@types/node": "~24.10.0",
+    "@types/react": "~19.2.3",
+    "@types/react-dom": "~19.2.2",
+    "@typescript-eslint/eslint-plugin": "~8.46.4",
+    "@typescript-eslint/parser": "~8.46.4",
+    "eslint": "~9.39.1",
     "eslint-import-resolver-typescript": "~4.4.4",
     "eslint-plugin-import": "~2.32.0",
     "eslint-plugin-jsx-a11y": "~6.10.2",
     "eslint-plugin-react": "~7.37.5",
-    "eslint-plugin-react-hooks": "~7.0.0",
+    "eslint-plugin-react-hooks": "~7.0.1",
     "husky": "~9.1.7",
-    "lint-staged": "~16.2.4",
-    "lucide-preact": "~0.545.0",
-    "lucide-react": "~0.545.0",
+    "lint-staged": "~16.2.6",
+    "lucide-preact": "~0.553.0",
+    "lucide-react": "~0.553.0",
     "postcss": "~8.5.6",
     "prettier": "~3.6.2",
-    "rollup-plugin-visualizer": "~6.0.4",
+    "rollup-plugin-visualizer": "~6.0.5",
     "size-limit": "~11.2.0",
-    "storybook": "~9.1.10",
-    "tailwindcss": "~4.1.14",
-    "terser": "~5.44.0",
+    "storybook": "~10.0.7",
+    "tailwindcss": "~4.1.17",
+    "terser": "~5.44.1",
     "tw-animate-css": "~1.4.0",
     "typescript": "~5.9.3",
-    "typescript-eslint": "~8.46.0",
-    "vite": "~7.1.9",
+    "typescript-eslint": "~8.46.4",
+    "vite": "~7.2.2",
     "vite-plugin-dts": "~4.5.4",
     "vite-plugin-environment": "~1.1.3"
   },