@enonic/ui 0.15.1 → 0.17.0

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/index.d.ts

@@ -4,4 +4,6 @@ export * from './dialog-provider';
 export * from './id-provider';
 export * from './listbox-provider';
 export * from './menu-provider';
+export * from './menubar-menu-provider';
+export * from './menubar-provider';
 export * from './search-field-provider';

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

@@ -1,12 +1,25 @@
 import { ReactElement, ReactNode } from 'react';
 export type ListboxContextValue = {
     baseId: string;
+    /**
+     * Active item ID (`undefined` when no item is active).
+     * Note: Never `null` - the hook converts `null` to `undefined` internally.
+     */
     active?: string;
     selection: ReadonlySet<string>;
     selectionMode: 'single' | 'multiple';
     disabled?: boolean;
-    focusable?: boolean;
-    setActive: (id?: string) => void;
+    /**
+     * 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.
+     */
+    setActive: (id?: string | null) => void;
     toggleValue: (value: string) => void;
     keyHandler?: (e: React.KeyboardEvent<HTMLElement>) => void;
     registerItem: (id: string, disabled?: boolean) => void;

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

@@ -0,0 +1,36 @@
+import { RefObject } from 'react';
+import { MenubarContextValue } from './menubar-provider';
+/**
+ * Context value for individual menu within a menubar.
+ *
+ * Coordinates between the menu's state and the parent menubar's state.
+ */
+export type MenubarMenuContextValue = {
+    /** Unique ID for this menu */
+    menuId: string;
+    /** ID for the menu content element */
+    contentId: string;
+    /** Whether this menu is currently open */
+    open: boolean;
+    /** Open/close this menu */
+    setOpen: (open: boolean) => void;
+    /** Reference to the parent menubar context */
+    menubarContext: MenubarContextValue;
+    /** Reference to the trigger element */
+    triggerRef: RefObject<HTMLButtonElement> | null;
+};
+export declare const MenubarMenuContext: import('preact').Context<MenubarMenuContextValue | undefined>;
+export declare const MenubarMenuProvider: import('preact').Provider<MenubarMenuContextValue | undefined>;
+/**
+ * Access the menubar menu context.
+ *
+ * @throws Error if used outside MenubarMenuProvider
+ */
+export declare function useMenubarMenu(): MenubarMenuContextValue;
+/**
+ * Optionally access the menubar menu context.
+ *
+ * Returns undefined if used outside MenubarMenuProvider.
+ * Useful for components that can work both inside and outside a menubar.
+ */
+export declare function useMenubarMenuOptional(): MenubarMenuContextValue | undefined;

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

@@ -0,0 +1,72 @@
+import { ReactElement, ReactNode, RefObject } from 'react';
+/**
+ * Context value for Menubar component.
+ * Manages horizontal navigation between menubar items (buttons and menu triggers).
+ *
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/menubar/} - ARIA Menubar Pattern
+ */
+export type MenubarContextValue = {
+    /**
+     * Currently active menubar item ID (keyboard navigation focus).
+     * This tracks which button or menu trigger is currently highlighted.
+     * `undefined` when no item is active.
+     */
+    active: string | undefined;
+    setActive: (id: string | undefined) => void;
+    /**
+     * Registry for menubar items to enable keyboard navigation.
+     * Items are tracked in insertion order for left/right arrow navigation.
+     */
+    registerItem: (id: string, disabled?: boolean) => void;
+    unregisterItem: (id: string) => void;
+    getItems: () => string[];
+    isItemDisabled: (id: string) => boolean;
+    /**
+     * ID of the currently open menu (if any).
+     * Tracks which menu is expanded in the menubar for conditional hover behavior.
+     */
+    openMenuId: string | undefined;
+    setOpenMenuId: (id: string | undefined) => void;
+    /**
+     * Base ID for the menubar container.
+     */
+    menubarId: string;
+    /**
+     * Ref to the menubar container element for focus management.
+     */
+    menubarRef: RefObject<HTMLDivElement> | null;
+};
+export type MenubarProviderProps = {
+    value: MenubarContextValue;
+    children?: ReactNode;
+};
+/**
+ * Provider component that supplies menubar context to child components.
+ * Should wrap all Menubar.* components.
+ */
+export declare const MenubarProvider: {
+    ({ value, children }: MenubarProviderProps): ReactElement;
+    displayName: string;
+};
+/**
+ * Hook to access menubar context.
+ * Must be used within a MenubarProvider.
+ *
+ * @throws {Error} If used outside of MenubarProvider
+ * @returns {MenubarContextValue} The menubar context
+ *
+ * @example
+ * ```tsx
+ * const { active, setActive, registerItem } = useMenubar();
+ * ```
+ */
+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.
+ *
+ * @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.15.1",
+  "version": "0.17.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"
   },