@enonic/ui 0.23.1 → 0.24.0

package/dist/types/components/tree-list/tree-list.d.ts

@@ -1,14 +1,29 @@
 import { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
 import { IconButtonProps } from '../icon-button';
 import { LucideIcon } from '../../types';
-export type TreeListProps<T extends TreeNode = TreeNode> = {
+export declare const LOADING_SUFFIX = "__loading__";
+export declare const ROOT_PARENT_ID = "__root__";
+export type TreeData = {
+    id: string;
+    hasChildren: boolean;
+};
+export type TreeItems<TreeData> = {
+    nodes: Record<string, TreeData | undefined>;
+    children: Record<string, string[] | undefined>;
+    hasMore: Record<string, boolean | undefined>;
+};
+export type FlatTreeNode<TData extends TreeData> = {
+    id: string;
+    data: TData;
+    level: number;
+    parentId: string | null;
+    nodeType: 'node' | 'loading' | 'error';
+};
+export type TreeListProps<TData extends TreeData = TreeData> = {
     className?: string;
-    items?: T[];
-    setItems?: (items: T[]) => void;
-    isItemSelectable?: (item: T) => boolean;
-    fetchChildren: (parentNode: T | undefined, offset: number) => Promise<{
-        items: T[];
-        total: number;
+    fetchChildren: (parentId: string | undefined, offset: number) => Promise<{
+        items: TData[];
+        hasMore: boolean;
     }>;
     expanded?: ReadonlySet<string>;
     onExpandedChange?: (expanded: ReadonlySet<string>) => void;
@@ -18,75 +33,85 @@ export type TreeListProps<T extends TreeNode = TreeNode> = {
     active?: string | null;
     defaultActive?: string;
     setActive?: (active: string | null | undefined) => void;
+    isItemSelectable?: (item: TData) => boolean;
+    items?: TreeItems<TData>;
+    onItemsChange?: (items: TreeItems<TData>) => void;
     children?: ReactNode;
 } & ComponentPropsWithoutRef<'div'>;
-export type TreeListContentProps = {
+export type TreeListContainerProps = {
     children?: ReactNode;
-    load?: boolean;
+    className?: string;
+} & ComponentPropsWithoutRef<'div'>;
+export type DefaultTreeListLoadingRowViewProps<TData extends TreeData> = {
+    item: FlatTreeNode<TData>;
 } & ComponentPropsWithoutRef<'div'>;
-type TreeListContainerProps = {
+export type TreeListLoadingRowProps<TData extends TreeData> = {
+    item: FlatTreeNode<TData>;
+    renderLoading?: (item: FlatTreeNode<TData>) => ReactNode;
     children?: ReactNode;
+    intersectionProps?: IntersectionObserverInit;
+} & ComponentPropsWithoutRef<'div'>;
+export type TreeListErrorRowProps<TData extends TreeData> = {
+    item: FlatTreeNode<TData>;
+    renderError?: (item: FlatTreeNode<TData>) => ReactNode;
     className?: string;
+    onRetry?: () => void;
 } & ComponentPropsWithoutRef<'div'>;
-type TreeListRowLeftProps = {
+export type TreeListContentProps<TData extends TreeData> = {
+    renderNode: (item: FlatTreeNode<TData>) => ReactNode;
+    renderLoading?: (item: FlatTreeNode<TData>) => ReactNode;
+    renderError?: (item: FlatTreeNode<TData>) => ReactNode;
+};
+export type TreeListRowLeftProps = {
     children?: ReactNode;
     className?: string;
 } & ComponentPropsWithoutRef<'div'>;
-type TreeListRowRightProps = {
+export type TreeListRowRightProps = {
     children?: ReactNode;
     className?: string;
 } & ComponentPropsWithoutRef<'div'>;
-type TreeListRowLevelSpacerProps = {
+export type TreeListRowLevelSpacerProps = {
     level?: number;
     className?: string;
 } & ComponentPropsWithoutRef<'div'>;
-type TreeListRowExpandControlProps = {
-    data: TreeNode;
+export type TreeListRowExpandControlProps<TData extends TreeData> = {
+    data: FlatTreeNode<TData>;
     icon?: LucideIcon;
 } & Omit<IconButtonProps, 'icon'>;
-type TreeListRowContentProps = {
+export type TreeListRowContentProps = {
     children?: ReactNode;
     className?: string;
 } & ComponentPropsWithoutRef<'div'>;
-type TreeListRowSelectionControlProps = {
-    data: TreeNode;
+export type TreeListRowSelectionControlProps<TData extends TreeData> = {
+    data: FlatTreeNode<TData>;
     className?: string;
 } & ComponentPropsWithoutRef<'div'>;
-type TreeListRowProps<T extends TreeNode> = {
-    item: T;
+export type TreeListRowProps<TData extends TreeData> = {
+    item: FlatTreeNode<TData>;
     children: ReactNode;
     className?: string;
 } & ComponentPropsWithoutRef<'div'>;
-export type TreeListLoadingRowProps = {
-    item: TreeNode;
-    children?: ReactNode;
-    intersectionProps?: IntersectionObserverInit;
-} & ComponentPropsWithoutRef<'div'>;
-export declare const TreeListRoot: <T extends TreeNode = TreeNode>({ className, items: controlledItems, setItems: setItemsControlled, fetchChildren, selection: controlledSelection, expanded: controlledExpanded, onSelectionChange, onExpandedChange, active: controlledActive, defaultActive, setActive, selectionMode, isItemSelectable, children, ...props }: TreeListProps<T>) => ReactElement;
-export type TreeNode = {
-    id: string;
-    hasChildren?: boolean;
-    children?: TreeNode[];
-    hasMoreChildren?: boolean;
-    path: string[];
-};
-export declare function isLoadingPlaceholder(node: TreeNode): boolean;
-export declare const TreeList: (<T extends TreeNode = TreeNode>({ className, items: controlledItems, setItems: setItemsControlled, fetchChildren, selection: controlledSelection, expanded: controlledExpanded, onSelectionChange, onExpandedChange, active: controlledActive, defaultActive, setActive, selectionMode, isItemSelectable, children, ...props }: TreeListProps<T>) => ReactElement) & {
-    Root: <T extends TreeNode = TreeNode>({ className, items: controlledItems, setItems: setItemsControlled, fetchChildren, selection: controlledSelection, expanded: controlledExpanded, onSelectionChange, onExpandedChange, active: controlledActive, defaultActive, setActive, selectionMode, isItemSelectable, children, ...props }: TreeListProps<T>) => ReactElement;
+export declare const TreeList: (<TData extends TreeData = TreeData>({ className, fetchChildren, selection: controlledSelection, expanded: controlledExpanded, onSelectionChange, onExpandedChange, active: controlledActive, defaultActive, setActive, selectionMode, isItemSelectable, items: controlledItems, onItemsChange, children, ...props }: TreeListProps<TData>) => ReactElement) & {
+    Root: <TData extends TreeData = TreeData>({ className, fetchChildren, selection: controlledSelection, expanded: controlledExpanded, onSelectionChange, onExpandedChange, active: controlledActive, defaultActive, setActive, selectionMode, isItemSelectable, items: controlledItems, onItemsChange, children, ...props }: TreeListProps<TData>) => ReactElement;
     Container: {
         ({ children, className, ...props }: TreeListContainerProps): ReactElement<TreeListContainerProps>;
         displayName: string;
     };
     Content: {
-        ({ children, load }: TreeListContentProps): ReactElement;
+        <TData extends TreeData>({ renderNode, renderLoading, renderError, }: TreeListContentProps<TData>): ReactElement;
         displayName: string;
     };
     Row: {
-        <T extends TreeNode>({ item, children, className, ...props }: TreeListRowProps<T>): ReactElement;
+        <TData extends TreeData>({ item, children, className, ...props }: TreeListRowProps<TData>): ReactElement;
         displayName: string;
     };
     LoadingRow: {
-        ({ item, children, intersectionProps, ...props }: TreeListLoadingRowProps): ReactElement;
+        <TData extends TreeData>({ item, renderLoading, className, children, intersectionProps, ...props }: TreeListLoadingRowProps<TData>): ReactElement;
+        displayName: string;
+    };
+    DefaultLoadingRowView: <TData extends TreeData>({ item, className, children, ...props }: DefaultTreeListLoadingRowViewProps<TData>) => ReactElement;
+    ErrorRow: {
+        <TData extends TreeData>({ item, onRetry, renderError, className, ...props }: TreeListErrorRowProps<TData>): ReactElement;
         displayName: string;
     };
     RowLeft: {
@@ -94,15 +119,15 @@ export declare const TreeList: (<T extends TreeNode = TreeNode>({ className, ite
         displayName: string;
     };
     RowRight: {
-        ({ children, className, ...props }: TreeListRowRightProps): ReactElement<TreeListRowLeftProps>;
+        ({ children, className, ...props }: TreeListRowRightProps): ReactElement<TreeListRowRightProps>;
         displayName: string;
     };
     RowLevelSpacer: {
-        ({ level, className, ...props }: TreeListRowLevelSpacerProps): ReactElement<TreeListRowLeftProps> | undefined;
+        ({ level, className, ...props }: TreeListRowLevelSpacerProps): ReactElement<TreeListRowLevelSpacerProps> | null;
         displayName: string;
     };
     RowExpandControl: {
-        ({ data, icon, className, ...props }: TreeListRowExpandControlProps): ReactElement<TreeListRowExpandControlProps>;
+        <TData extends TreeData>({ data, icon, className, ...props }: TreeListRowExpandControlProps<TData>): ReactElement<TreeListRowExpandControlProps<TData>>;
         displayName: string;
     };
     RowContent: {
@@ -110,8 +135,7 @@ export declare const TreeList: (<T extends TreeNode = TreeNode>({ className, ite
         displayName: string;
     };
     RowSelectionControl: {
-        ({ data, className, ...props }: TreeListRowSelectionControlProps): ReactElement;
+        <TData extends TreeData>({ data, className, ...props }: TreeListRowSelectionControlProps<TData>): ReactElement;
         displayName: string;
     };
 };
-export {};

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

@@ -4,8 +4,11 @@ export { useControlledState } from './use-controlled-state';
 export { useControlledStateWithNull } from './use-controlled-state-with-null';
 export { type FloatingPosition, type UseFloatingPositionConfig, useFloatingPosition } from './use-floating-position';
 export { type ItemMetadata, type UseItemRegistryReturn, useItemRegistry } from './use-item-registry';
+export { type UseItemTextRegistryReturn, useItemTextRegistry } from './use-item-text-registry';
 export { type KeyboardNavigationConfig, type UseKeyboardNavigationReturn, useKeyboardNavigation, } from './use-keyboard-navigation';
 export { type UseRovingTabIndexConfig, type UseRovingTabIndexReturn, useRovingTabIndex } from './use-roving-tabindex';
 export { type UseScrollActiveIntoViewConfig, useScrollActiveIntoView } from './use-scroll-active-into-view';
 export { useScrollLock } from './use-scroll-lock';
+export { type UseSelectorKeyboardConfig, type UseSelectorKeyboardReturn, useSelectorKeyboard, } from './use-selector-keyboard';
 export { useSyncValue } from './use-sync-value';
+export { type UseTypeAheadConfig, type UseTypeAheadReturn, useTypeAhead } from './use-type-ahead';

package/dist/types/hooks/use-item-text-registry.d.ts

@@ -0,0 +1,29 @@
+export type UseItemTextRegistryReturn = {
+    /**
+     * Register text content for an item (for type-ahead matching)
+     */
+    registerItemText: (id: string, text: string) => void;
+    /**
+     * Unregister text content for an item
+     */
+    unregisterItemText: (id: string) => void;
+    /**
+     * Get the text content for an item
+     */
+    getItemText: (id: string) => string | undefined;
+};
+/**
+ * Hook for managing item text content registry.
+ * Used for type-ahead search functionality.
+ *
+ * @example
+ * ```tsx
+ * const { registerItemText, getItemText } = useItemTextRegistry();
+ *
+ * // In item component:
+ * useEffect(() => {
+ *   registerItemText(id, textContent);
+ * }, [id, textContent]);
+ * ```
+ */
+export declare function useItemTextRegistry(): UseItemTextRegistryReturn;

package/dist/types/hooks/use-selector-keyboard.d.ts

@@ -0,0 +1,68 @@
+export type UseSelectorKeyboardConfig = {
+    /**
+     * Get all item IDs in order
+     */
+    getItems: () => string[];
+    /**
+     * Check if an item is disabled
+     */
+    isItemDisabled: (id: string) => boolean;
+    /**
+     * Get the text content for an item (for type-ahead matching)
+     */
+    getItemText: (id: string) => string | undefined;
+    /**
+     * Currently active item ID
+     */
+    active: string | undefined;
+    /**
+     * Set the active item ID
+     */
+    setActive: (id: string | undefined) => void;
+    /**
+     * Currently selected value
+     */
+    value: string | undefined;
+    /**
+     * Whether the dropdown is open
+     */
+    open: boolean;
+    /**
+     * Set open state (internal, doesn't return focus)
+     */
+    setOpenInternal: (open: boolean) => void;
+    /**
+     * Set open state (with focus return handling)
+     */
+    setOpen: (open: boolean) => void;
+    /**
+     * Whether the selector is disabled
+     */
+    disabled: boolean;
+    /**
+     * Called when an item is selected
+     */
+    onSelect: (id: string) => void;
+};
+export type UseSelectorKeyboardReturn = {
+    /**
+     * Combined keyboard event handler
+     */
+    keyHandler: (e: React.KeyboardEvent<HTMLElement>) => void;
+};
+/**
+ * Hook for Selector keyboard handling.
+ *
+ * Combines keyboard navigation, type-ahead, and selector-specific behaviors:
+ * - Arrow keys, Home/End for navigation
+ * - Enter/Space for selection
+ * - Escape to close
+ * - Tab to select and close
+ * - PageUp/PageDown for large jumps
+ * - Type-ahead search (single char cycling, multi-char search)
+ * - Opens dropdown on navigation keys when closed
+ *
+ * @param config - Configuration object
+ * @returns Object with keyHandler
+ */
+export declare function useSelectorKeyboard(config: UseSelectorKeyboardConfig): UseSelectorKeyboardReturn;

package/dist/types/hooks/use-type-ahead.d.ts

@@ -0,0 +1,76 @@
+export type UseTypeAheadConfig = {
+    /**
+     * Get all item IDs in order
+     */
+    getItems: () => string[];
+    /**
+     * Check if an item is disabled
+     */
+    isItemDisabled: (id: string) => boolean;
+    /**
+     * Get the text content for an item (for matching)
+     */
+    getItemText: (id: string) => string | undefined;
+    /**
+     * Currently active item ID
+     */
+    active: string | undefined;
+    /**
+     * Set the active item ID
+     */
+    setActive: (id: string | undefined) => void;
+    /**
+     * Called when a match is found
+     */
+    onMatch?: (id: string) => void;
+    /**
+     * Timeout in ms before search string resets
+     * @default 500
+     */
+    timeout?: number;
+};
+export type UseTypeAheadReturn = {
+    /**
+     * Handle a typed character for type-ahead search
+     */
+    handleTypeAhead: (char: string) => void;
+    /**
+     * Reset the search string manually
+     */
+    resetSearch: () => void;
+};
+/**
+ * Hook for type-ahead search in a list of items.
+ *
+ * Behavior:
+ * - Single character: cycles through items starting with that character
+ * - Multiple characters typed quickly: finds first match for full string
+ * - Case-insensitive matching
+ * - Skips disabled items
+ * - Resets after timeout (default 500ms)
+ *
+ * **Important**: The `getItemText` function must return the searchable text for each item.
+ * When using complex children (e.g., `<ItemText>{label}</ItemText>`), you must either:
+ * 1. Provide a `textValue` prop to register searchable text explicitly
+ * 2. Extract text from DOM after mount using `element.textContent`
+ *
+ * Plain string children work automatically, but wrapped content requires explicit registration.
+ *
+ * @example
+ * ```tsx
+ * const { handleTypeAhead } = useTypeAhead({
+ *   getItems,
+ *   isItemDisabled,
+ *   getItemText,
+ *   active,
+ *   setActive,
+ *   onMatch: (id) => console.log('Found:', id),
+ * });
+ *
+ * // In keyboard handler:
+ * if (e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+ *   handleTypeAhead(e.key);
+ * }
+ * ```
+ */
+export declare function useTypeAhead(config: UseTypeAheadConfig): UseTypeAheadReturn;

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

@@ -7,6 +7,7 @@ export * from './menu-provider';
 export * from './menubar-menu-provider';
 export * from './menubar-provider';
 export * from './search-field-provider';
+export * from './selector-provider';
 export * from './toast-provider';
 export * from './toggle-group-provider';
 export * from './tree-list-provider';

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

@@ -1,5 +1,6 @@
 import { ReactElement, ReactNode, RefObject } from 'react';
 export type MenuContextValue = {
+    baseId: string;
     open: boolean;
     setOpen: (open: boolean) => void;
     active: string | undefined;
@@ -8,8 +9,6 @@ export type MenuContextValue = {
     unregisterItem: (id: string) => void;
     getItems: () => string[];
     isItemDisabled: (id: string) => boolean;
-    triggerId: string;
-    menuId: string;
     triggerRef: RefObject<HTMLButtonElement> | null;
 };
 export type MenuProviderProps = {

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

@@ -0,0 +1,33 @@
+import { ReactElement, ReactNode, RefObject } from 'react';
+export type SelectorContextValue = {
+    baseId: string;
+    value: string | undefined;
+    setValue: (value: string) => void;
+    open: boolean;
+    setOpen: (next: boolean) => void;
+    active: string | undefined;
+    setActive: (id: string | undefined) => void;
+    disabled: boolean;
+    error: boolean;
+    required: boolean;
+    name?: string;
+    form?: string;
+    registerItem: (id: string, disabled?: boolean) => void;
+    unregisterItem: (id: string) => void;
+    getItems: () => string[];
+    isItemDisabled: (id: string) => boolean;
+    registerItemText: (id: string, text: string) => void;
+    unregisterItemText: (id: string) => void;
+    getItemText: (id: string) => string | undefined;
+    keyHandler: (e: React.KeyboardEvent<HTMLElement>) => void;
+    triggerRef: RefObject<HTMLButtonElement>;
+};
+export type SelectorProviderProps = {
+    value: SelectorContextValue;
+    children?: ReactNode;
+};
+export declare const SelectorProvider: {
+    ({ value, children }: SelectorProviderProps): ReactElement;
+    displayName: string;
+};
+export declare const useSelector: () => SelectorContextValue;

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

@@ -1,21 +1,23 @@
-import { ReactElement, ReactNode } from 'react';
-import { TreeNode } from '../components/tree-list/tree-list';
-export type TreeListContextValue<T extends TreeNode = TreeNode> = {
+import { ReactElement, ReactNode, RefObject } from 'react';
+import { FlatTreeNode, TreeData } from '../components/tree-list/tree-list';
+export type TreeListContextValue<T extends TreeData = TreeData> = {
     baseId: string;
-    items: readonly T[];
-    loadMore: (parent?: string) => void;
+    items: readonly FlatTreeNode<T>[];
+    loadMore: (parent?: string) => Promise<void>;
     isItemSelectable: (item: T) => boolean;
     active?: string;
     selection?: ReadonlySet<string>;
     expanded?: ReadonlySet<string>;
-    toggleSelection?: (id: string) => void;
+    toggleSelection: (id: string) => void;
     toggleExpanded: (id: string) => void;
+    updateActive: (id: string | undefined) => void;
     selectionMode: 'single' | 'multiple';
     isFocused: boolean;
+    scrollRootRef?: RefObject<HTMLDivElement>;
 };
-export type TreeListProviderProps<T extends TreeNode = TreeNode> = {
+export type TreeListProviderProps<T extends TreeData = TreeData> = {
     value: TreeListContextValue<T>;
     children?: ReactNode;
 };
-export declare const TreeListProvider: <T extends TreeNode = TreeNode>({ value, children, }: TreeListProviderProps<T>) => ReactElement;
-export declare const useTreeList: <T extends TreeNode = TreeNode>() => TreeListContextValue<T>;
+export declare const TreeListProvider: <T extends TreeData = TreeData>({ value, children, }: TreeListProviderProps<T>) => ReactElement;
+export declare const useTreeList: <T extends TreeData = TreeData>() => TreeListContextValue<T>;

package/package.json

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