@enonic/ui 0.15.0 → 0.16.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,5 @@
 export { useScrollLock } from './use-scroll-lock';
 export { useControlledState } from './use-controlled-state';
+export { useControlledStateWithNull } from './use-controlled-state-with-null';
 export { useItemRegistry, type ItemMetadata, type UseItemRegistryReturn } from './use-item-registry';
 export { useKeyboardNavigation, type KeyboardNavigationConfig, type UseKeyboardNavigationReturn, } from './use-keyboard-navigation';

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/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,20 @@
 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;
+    /**
+     * 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,75 @@
+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).
+     * Used in Phase 2 to track which menu is expanded in the menubar.
+     *
+     * @phase2
+     */
+    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 (e.g., Menu.Trigger).
+ *
+ * @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.15.0",
+  "version": "0.16.0",
   "description": "Enonic UI Component Library",
   "author": "Enonic",
   "license": "MIT",