@enonic/ui 0.49.0 → 0.50.1

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

@@ -0,0 +1,6 @@
+/**
+ * Whether the browser supports CSS `field-sizing: content` for content-based form control sizing.
+ * Evaluated once at module load. `false` in non-browser environments.
+ * @see https://caniuse.com/mdn-css_properties_field-sizing
+ */
+export declare const SUPPORTS_FIELD_SIZING: boolean;

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.49.0",
+  "version": "0.50.1",
   "description": "Enonic UI Component Library",
   "author": "Enonic",
   "license": "MIT",