@enonic/ui 0.48.0 → 0.50.0

package/dist/types/hooks/use-active-on-open.d.ts

@@ -0,0 +1,63 @@
+import { RefObject } from 'react';
+export type UseActiveOnOpenConfig = {
+    /**
+     * Whether the dropdown is open. Pass `true` for always-open contexts
+     * like a standalone Listbox — the rising edge fires once on mount.
+     */
+    open: boolean;
+    /**
+     * Current selection set. The hook picks the first selected item in
+     * DOM order (according to `getItems()`) as the activation target.
+     */
+    selection: ReadonlySet<string>;
+    /** Setter for active item. */
+    setActive: (id: string | undefined) => void;
+    /** Returns DOM-ordered IDs from the item registry. */
+    getItems: () => readonly string[];
+    /** Returns whether an item is disabled. */
+    isItemDisabled: (id: string) => boolean;
+    /**
+     * Container element to scroll. The hook centers the activated selection
+     * inside this container by querying for the option element and calling
+     * `scrollIntoView({ block: 'center' })`. When omitted, only state is
+     * updated (useful for tests or virtualized consumers handling scroll
+     * through their own adapter).
+     */
+    containerRef?: RefObject<HTMLElement> | null;
+    /**
+     * Build the option element's DOM id from a registry id. Defaults to
+     * identity. Match the consumer's `buildElementId` used elsewhere.
+     */
+    buildElementId?: (id: string) => string;
+    /**
+     * When `false`, the hook does nothing. Used by Combobox when `active`
+     * is controlled externally — the consumer owns activation.
+     * @default true
+     */
+    enabled?: boolean;
+};
+/**
+ * Activates the selected item (or first enabled fallback) when a dropdown
+ * opens, and centers the activated selection in the viewport.
+ *
+ * Trigger: `open` rising edge. On rising edge, the hook unconditionally
+ * rewrites active even if a stale value persists from the previous open.
+ * If the item registry is empty at that moment (popup mounts items lazily,
+ * common with Portals), the hook re-runs on subsequent renders until items
+ * appear — `getItems` callback identity is coupled to the registry version,
+ * so listing it as a dep covers lazy-mount cases.
+ *
+ * Behavior:
+ * - Selection has any enabled item present in the registry → activate it
+ *   and call `scrollIntoView({ block: 'center' })` on the option element.
+ * - Otherwise → set active to first enabled item; no scroll (the default
+ *   `'nearest'` from `useScrollActiveIntoView` will apply on next nav).
+ * - No items registered yet → wait; the next `getItems` identity change
+ *   re-runs the effect (covers the lazy-mount case).
+ *
+ * The imperative scroll is owned by this hook so the open-transition center
+ * behavior is independent of whether `setActive` actually changed the value
+ * — if `active` already pointed at the target, `useScrollActiveIntoView`
+ * would not re-fire, and a coordination-via-ref scheme would silently fail.
+ */
+export declare function useActiveOnOpen({ open, selection, setActive, getItems, isItemDisabled, containerRef, buildElementId, enabled, }: UseActiveOnOpenConfig): void;

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

@@ -13,6 +13,8 @@ export type UseClickOutsideConfig = {
     onPointerDownOutside?: (event: PointerEvent) => void;
     /** Callback when any interaction occurs outside */
     onInteractOutside?: (event: Event) => void;
+    /** Which event should trigger `onClose`. Outside callbacks still fire on pointerdown. Defaults to pointerdown. */
+    closeOn?: 'pointerdown' | 'click';
     /**
      * Callback to close/hide the content.
      * Only called if event.defaultPrevented is false.
@@ -29,6 +31,8 @@ export type UseClickOutsideConfig = {
  * - Ignores clicks inside the content element
  * - Supports excluding additional elements (e.g., trigger buttons)
  * - Ignores clicks inside elements with `data-click-outside-ignore` attribute
+ * - Can close immediately on outside pointerdown, or wait for the matching click
+ * - Waiting for click helps avoid mobile tap clicks reaching elements behind a closing overlay
  * - Respects event.defaultPrevented to allow custom handling
  * - Only active when enabled
  * - Properly cleans up event listeners
@@ -97,4 +101,4 @@ export type UseClickOutsideConfig = {
  * }
  * ```
  */
-export declare function useClickOutside({ enabled, contentRef, excludeRefs, onPointerDownOutside, onInteractOutside, onClose, }: UseClickOutsideConfig): void;
+export declare function useClickOutside({ enabled, contentRef, excludeRefs, onPointerDownOutside, onInteractOutside, closeOn, onClose, }: UseClickOutsideConfig): void;

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

@@ -21,66 +21,8 @@ export type UseScrollActiveIntoViewConfig = {
     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();
- *
- *   // Memoize to keep the effect dependency stable across re-renders
- *   const buildElementId = useCallback((id: string) => `${baseId}-listbox-option-${id}`, [baseId]);
- *
- *   useScrollActiveIntoView({
- *     containerRef: contentRef,
- *     activeId: active,
- *     orientation: 'vertical',
- *     buildElementId,
- *   });
- *
- *   return <div ref={contentRef}>...</div>;
- * }
- * ```
+ * Reactive scroll-into-view for keyboard navigation. Uses `block: 'nearest'`
+ * for minimal scroll travel. For the open-transition "center on selected"
+ * behavior, see `useActiveOnOpen` which performs an imperative center-scroll.
  */
 export declare function useScrollActiveIntoView({ containerRef, activeId, orientation, buildElementId, }: UseScrollActiveIntoViewConfig): void;

package/dist/types/hooks/use-scroll-selected-to-virtuoso.d.ts

@@ -0,0 +1,42 @@
+import { RefObject } from 'react';
+type VirtuosoLikeHandle = {
+    scrollToIndex: (location: number | {
+        index: number;
+        align?: 'start' | 'center' | 'end';
+        behavior?: 'auto' | 'smooth';
+    }) => void;
+};
+export type UseScrollSelectedToVirtuosoConfig<TItem extends {
+    id: string;
+}> = {
+    /** Whether the dropdown is open. The hook fires on the rising edge. */
+    open: boolean;
+    /** The single selected ID to center on open, or undefined to skip. */
+    selectedId: string | undefined;
+    /**
+     * Setter called with `selectedId` on the rising edge so navigation
+     * resumes from there. Pass the active setter from the wrapped list
+     * (e.g., `VirtualizedTreeList`'s `onActiveChange` consumer).
+     */
+    setActive: (id: string) => void;
+    /** Flat items in render order. Used to look up the index for `scrollToIndex`. */
+    items: readonly TItem[];
+    /** Ref to the Virtuoso instance for scroll operations. */
+    virtuosoRef: RefObject<VirtuosoLikeHandle | null> | undefined;
+};
+/**
+ * Centers the selected item in a Virtuoso-backed virtualized list when its
+ * containing dropdown opens, and sets the consumer's active state to match.
+ *
+ * Retries on `requestAnimationFrame` while the Virtuoso ref is still null
+ * (Virtuoso typically attaches within a frame of mount). Bails after a small
+ * cap to avoid infinite loops.
+ *
+ * Use inside a consumer that wraps `VirtualizedTreeList` in `Combobox.TreeContent`
+ * (or any other open/close container) when the same UX as `Combobox.ListContent`
+ * is desired: open with selection → centered, arrow keys → nearest.
+ */
+export declare function useScrollSelectedToVirtuoso<TItem extends {
+    id: string;
+}>({ open, selectedId, setActive, items, virtuosoRef, }: UseScrollSelectedToVirtuosoConfig<TItem>): void;
+export {};

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

@@ -29,6 +29,12 @@ export type ComboboxContextValue = {
     isItemDisabled: (id: string) => boolean;
     hasValue: boolean;
     setHasValue: (has: boolean) => void;
+    /**
+     * Whether the auto-active-on-open behavior should run inside Listbox-backed
+     * content. Set to `false` when active state is consumer-controlled. Tree
+     * content doesn't use this — see `useScrollSelectedToVirtuoso` instead.
+     */
+    autoActiveOnOpen: boolean;
 };
 export type ComboboxProviderProps = {
     value: ComboboxContextValue;

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

@@ -26,6 +26,11 @@ export type ListboxContextValue = {
     unregisterItem: (id: string) => void;
     getItems: () => string[];
     isItemDisabled: (id: string) => boolean;
+    /**
+     * When `false`, `useActiveOnOpen` in `Listbox.Content` is skipped. Set
+     * by hosts (e.g., Combobox) when the consumer controls active state.
+     */
+    autoActiveOnOpen: boolean;
 };
 export type ListboxProviderProps = {
     value: ListboxContextValue;

package/dist/types/providers/virtualized-tree-list-provider.d.ts

@@ -9,6 +9,7 @@ export type VirtualizedTreeListContextValue = {
     toggleSelection: (id: string, index: number) => void;
     selectionMode: 'single' | 'multiple' | 'none';
     isFocused: boolean;
+    keyboardActive: boolean;
     items: readonly FlatNodeBase[];
     getItemIndex: (id: string) => number;
     scrollToIndex: (index: number) => void;

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

@@ -2,4 +2,5 @@ export * from './aria';
 export * from './cn';
 export * from './mobile';
 export * from './ref';
+export * from './scroll';
 export * from './unwrap';

package/dist/types/utils/scroll.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Scrolls an element to the center of its nearest scrollable ancestor without
+ * disturbing outer scroll containers (page, dialog, etc.).
+ *
+ * - Chromium 134+ uses `scrollIntoView({ block: 'center', container: 'nearest' })`
+ *   and centers the element within the closest scroll container only.
+ * - Other browsers fall back to `scrollIntoView({ block: 'nearest' })` — the
+ *   element lands at the closest edge instead of the center, but ancestors
+ *   that already show it stay put.
+ *
+ * Useful for dropdowns: bring the selected option into view on open without
+ * scrolling the page underneath.
+ */
+export declare function scrollIntoCenter(element: HTMLElement): void;

package/package.json

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