@enonic/ui 0.47.12 → 0.49.0

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

@@ -1,10 +1,11 @@
 import { RefObject } from 'react';
+export type FloatingSide = 'top' | 'bottom' | 'left' | 'right';
 export type FloatingPosition = {
     top: number;
     left?: number;
     right?: number;
-    /** Which side the popup is positioned relative to the anchor */
-    side: 'top' | 'bottom';
+    /** Which side the popup is positioned relative to the anchor (post-flip) */
+    side: FloatingSide;
 };
 export type UseFloatingPositionConfig = {
     /** Whether the floating element is open/visible */
@@ -13,48 +14,29 @@ export type UseFloatingPositionConfig = {
     anchorRef: RefObject<HTMLElement> | null;
     /** Reference to the floating content element */
     contentRef: RefObject<HTMLElement> | null;
-    /** Horizontal alignment relative to anchor */
+    /**
+     * Preferred side relative to the anchor. Flips to the opposite side when
+     * the content would overflow the viewport.
+     * @default 'bottom'
+     */
+    side?: FloatingSide;
+    /**
+     * Alignment along the perpendicular axis:
+     * - For `side` top/bottom: horizontal alignment ('start' = left, 'end' = right)
+     * - For `side` left/right: vertical alignment ('start' = top, 'end' = bottom)
+     * @default 'start'
+     */
     align?: 'start' | 'end';
 };
 /**
- * Calculates optimal position for floating elements (menus, dropdowns) relative to an anchor,
- * with automatic viewport collision detection and flip behavior.
+ * Calculates optimal position for floating elements (menus, dropdowns, submenus) relative
+ * to an anchor, with automatic viewport collision detection and flip behavior.
  *
- * This hook handles:
- * - Positioning below anchor with configurable alignment
- * - Vertical flipping when overflowing bottom edge
- * - Horizontal adjustment to stay within viewport bounds
- * - Automatic repositioning on window resize and scroll
+ * Supports four preferred sides (top/bottom/left/right). When the content would overflow
+ * the viewport on the preferred side, it flips to the opposite side. Perpendicular-axis
+ * alignment is adjusted to keep the content within the viewport.
  *
  * @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 anchorRef = useRef<HTMLButtonElement>(null);
- *   const contentRef = useRef<HTMLDivElement>(null);
- *   const position = useFloatingPosition({
- *     enabled: open,
- *     anchorRef,
- *     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, anchorRef, contentRef, align, }: UseFloatingPositionConfig): FloatingPosition | null;
+export declare function useFloatingPosition({ enabled, anchorRef, contentRef, side: preferredSide, align, }: UseFloatingPositionConfig): FloatingPosition | null;

package/dist/types/hooks/use-submenu-safe-area.d.ts

@@ -0,0 +1,38 @@
+import { RefObject } from 'react';
+export type SafeAreaSide = 'left' | 'right';
+export type UseSubmenuSafeAreaConfig = {
+    /** Whether the submenu is open (tracking is active) */
+    enabled: boolean;
+    /** Reference to the submenu content element — used to compute its near edge */
+    submenuRef: RefObject<HTMLElement>;
+    /**
+     * Which side the submenu sits on relative to its trigger.
+     * - 'right': near edge is the submenu's LEFT edge; pointer travels right toward it
+     * - 'left':  near edge is the submenu's RIGHT edge; pointer travels left toward it
+     */
+    side: SafeAreaSide;
+    /**
+     * How long (ms) after the submenu opens the safe zone remains valid without
+     * a confirming pointer sample. Prevents a stale history from locking the zone.
+     * @default 300
+     */
+    graceMs?: number;
+};
+export type UseSubmenuSafeAreaReturn = {
+    /**
+     * Returns true if the pointer at (x, y) is currently traveling toward the submenu's
+     * near edge — i.e. inside the triangle formed by the previous pointer sample and
+     * the two corners of that edge. Callers should skip sibling hover handling while
+     * this is true.
+     */
+    isInSafeArea: (x: number, y: number) => boolean;
+};
+/**
+ * Tracks pointer history while a submenu is open and computes whether the pointer
+ * is inside the "safe triangle" — the region between the previous pointer position
+ * and the submenu's near edge. Callers use this to suppress sibling-item hover
+ * handling while the user is diagonally moving toward the submenu.
+ *
+ * Implements the classic Amazon.com menu heuristic popularized by Radix UI.
+ */
+export declare function useSubmenuSafeArea({ enabled, submenuRef, side, graceMs, }: UseSubmenuSafeAreaConfig): UseSubmenuSafeAreaReturn;

package/dist/types/providers/context-menu-content-provider.d.ts

@@ -0,0 +1,29 @@
+import { MutableRefObject, ReactElement, ReactNode } from 'react';
+/**
+ * Navigation-related state scoped to a single `ContextMenu.Content` (or `SubContent`).
+ *
+ * Each menu level owns its own item registry and active-item state so nested submenus
+ * don't share navigation state with their parent. Selection-related state like `setOpen`
+ * (which closes the entire menu) still lives on the root `ContextMenuContextValue`.
+ */
+export type ContextMenuContentContextValue = {
+    active: string | undefined;
+    setActive: (id: string | undefined) => void;
+    registerItem: (id: string, disabled?: boolean, element?: HTMLElement | null) => void;
+    unregisterItem: (id: string) => void;
+    getItems: () => string[];
+    isItemDisabled: (id: string) => boolean;
+    /**
+     * Safe-triangle check registered by a currently-open child `Sub`. When non-null,
+     * the Content's pointer-move capture handler consults it to decide whether to
+     * suppress sibling hover activation while the user is traveling toward the submenu.
+     * Null when no submenu is open at this level.
+     */
+    safeAreaCheckRef: MutableRefObject<((x: number, y: number) => boolean) | null>;
+};
+export type ContextMenuContentProviderProps = {
+    value: ContextMenuContentContextValue;
+    children?: ReactNode;
+};
+export declare const ContextMenuContentProvider: ({ value, children }: ContextMenuContentProviderProps) => ReactElement;
+export declare const useContextMenuContent: () => ContextMenuContentContextValue;

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

@@ -1,14 +1,16 @@
 import { ReactElement, ReactNode } from 'react';
+/**
+ * Root-level context for ContextMenu. Holds menu-wide state that every level
+ * (top content, submenus) needs access to.
+ *
+ * Navigation state (active item, item registry) lives in a per-level
+ * `ContextMenuContentContextValue` — each Content and SubContent owns its own.
+ */
 export type ContextMenuContextValue = {
     baseId: string;
     open: boolean;
     setOpen: (open: boolean) => void;
-    active: string | undefined;
-    setActive: (id: string | undefined) => void;
-    registerItem: (id: string, disabled?: boolean, element?: HTMLElement | null) => void;
-    unregisterItem: (id: string) => void;
-    getItems: () => string[];
-    isItemDisabled: (id: string) => boolean;
+    /** Pointer coordinates where the menu was opened (set by Trigger onContextMenu) */
     position: {
         x: number;
         y: number;

package/dist/types/providers/context-menu-sub-provider.d.ts

@@ -0,0 +1,28 @@
+import { RefObject } from 'react';
+import { ContextMenuContentContextValue } from './context-menu-content-provider';
+/**
+ * Context value for a single `ContextMenu.Sub` wrapper.
+ *
+ * Coordinates between the submenu's local open state and the parent content's
+ * navigation state (so ArrowLeft from a submenu can restore active on its trigger).
+ */
+export type ContextMenuSubContextValue = {
+    /** Unique ID used by the SubTrigger (also the registry key in the parent content) */
+    subId: string;
+    /** ID of the submenu content element (for aria-controls) */
+    contentId: string;
+    /** Whether the submenu is currently open */
+    open: boolean;
+    /** Open/close the submenu */
+    setOpen: (open: boolean) => void;
+    /** Ref to the SubTrigger DOM node (for ArrowLeft refocus and collision anchoring) */
+    triggerRef: RefObject<HTMLDivElement> | null;
+    /**
+     * Snapshot of the parent content context captured at mount time.
+     * Used by SubContent's ArrowLeft handler to set parent `active` back to the trigger.
+     */
+    parentContent: ContextMenuContentContextValue;
+};
+export declare const ContextMenuSubProvider: import('preact').Provider<ContextMenuSubContextValue | undefined>;
+export declare const useContextMenuSub: () => ContextMenuSubContextValue;
+export declare const useContextMenuSubOptional: () => ContextMenuSubContextValue | undefined;

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

@@ -1,6 +1,8 @@
 export * from './avatar-provider';
 export * from './combobox-provider';
+export * from './context-menu-content-provider';
 export * from './context-menu-provider';
+export * from './context-menu-sub-provider';
 export * from './date-picker-provider';
 export * from './dialog-provider';
 export * from './focus-container-provider';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enonic/ui",
-  "version": "0.47.12",
+  "version": "0.49.0",
   "description": "Enonic UI Component Library",
   "author": "Enonic",
   "license": "MIT",