@enonic/ui 0.13.0 → 0.13.1

package/dist/types/components/combobox/combobox.d.ts

@@ -2,13 +2,19 @@ import { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
 export type ComboboxRootProps = {
     children?: ReactNode;
     open?: boolean;
+    defaultOpen?: boolean;
     onOpenChange?: (open: boolean) => void;
     closeOnBlur?: boolean;
     value?: string;
+    defaultValue?: string;
     onChange?: (value: string | undefined) => void;
     selectionMode?: 'single' | 'multiple';
     selection?: readonly string[];
+    defaultSelection?: readonly string[];
     onSelectionChange?: (selection: readonly string[]) => void;
+    active?: string;
+    defaultActive?: string;
+    setActive?: (active: string | undefined) => void;
     disabled?: boolean;
     error?: boolean;
 };
@@ -32,11 +38,11 @@ export type ComboboxPopupProps = {
     className?: string;
 };
 export declare const Combobox: {
-    ({ children, open: controlledOpen, onOpenChange, closeOnBlur, value, onChange, disabled, error, selectionMode, selection: controlledSelection, onSelectionChange, }: ComboboxRootProps): ReactElement;
+    ({ children, open: controlledOpen, defaultOpen, onOpenChange, closeOnBlur, value, defaultValue, onChange, disabled, error, selectionMode, selection: controlledSelection, defaultSelection, onSelectionChange, active: controlledActive, defaultActive, setActive, }: ComboboxRootProps): ReactElement;
     displayName: string;
 } & {
     Root: {
-        ({ children, open: controlledOpen, onOpenChange, closeOnBlur, value, onChange, disabled, error, selectionMode, selection: controlledSelection, onSelectionChange, }: ComboboxRootProps): ReactElement;
+        ({ children, open: controlledOpen, defaultOpen, onOpenChange, closeOnBlur, value, defaultValue, onChange, disabled, error, selectionMode, selection: controlledSelection, defaultSelection, onSelectionChange, active: controlledActive, defaultActive, setActive, }: ComboboxRootProps): ReactElement;
         displayName: string;
     };
     Content: import('preact').FunctionalComponent<import('preact/compat').PropsWithoutRef<ComboboxContentProps> & {

package/dist/types/components/listbox/listbox.d.ts

@@ -1,3 +1,4 @@
+import { UseItemRegistryReturn } from '../../hooks';
 import { ComponentPropsWithoutRef, ReactElement, ReactNode } from 'react';
 export type ListboxRootProps = {
     baseId?: string;
@@ -12,6 +13,10 @@ export type ListboxRootProps = {
     focusable?: boolean;
     children?: ReactNode;
     keyHandler?: (e: React.KeyboardEvent<HTMLElement>) => void;
+    registerItem?: UseItemRegistryReturn['registerItem'];
+    unregisterItem?: UseItemRegistryReturn['unregisterItem'];
+    getItems?: UseItemRegistryReturn['getItems'];
+    isItemDisabled?: UseItemRegistryReturn['isItemDisabled'];
 };
 export type ListboxContentProps = {
     className?: string;
@@ -20,22 +25,23 @@ export type ListboxContentProps = {
 } & ComponentPropsWithoutRef<'div'>;
 export type ListboxItemProps = {
     value: string;
+    disabled?: boolean;
     children: ReactNode;
     className?: string;
 } & ComponentPropsWithoutRef<'div'>;
 export declare const Listbox: {
-    ({ baseId, selection: controlledSelection, defaultSelection, onSelectionChange, active: controlledActive, defaultActive, setActive, selectionMode, focusable, disabled, children, keyHandler, }: ListboxRootProps): ReactElement;
+    ({ baseId, selection: controlledSelection, defaultSelection, onSelectionChange, active: controlledActive, defaultActive, setActive, selectionMode, focusable, disabled, children, keyHandler, registerItem: externalRegisterItem, unregisterItem: externalUnregisterItem, getItems: externalGetItems, isItemDisabled: externalIsItemDisabled, }: ListboxRootProps): ReactElement;
     displayName: string;
 } & {
     Root: {
-        ({ baseId, selection: controlledSelection, defaultSelection, onSelectionChange, active: controlledActive, defaultActive, setActive, selectionMode, focusable, disabled, children, keyHandler, }: ListboxRootProps): ReactElement;
+        ({ baseId, selection: controlledSelection, defaultSelection, onSelectionChange, active: controlledActive, defaultActive, setActive, selectionMode, focusable, disabled, children, keyHandler, registerItem: externalRegisterItem, unregisterItem: externalUnregisterItem, getItems: externalGetItems, isItemDisabled: externalIsItemDisabled, }: ListboxRootProps): ReactElement;
         displayName: string;
     };
     Content: import('preact').FunctionalComponent<import('preact/compat').PropsWithoutRef<ListboxContentProps> & {
         ref?: import('preact').Ref<HTMLDivElement> | undefined;
     }>;
     Item: {
-        ({ value, children, className, ...props }: ListboxItemProps): ReactElement;
+        ({ value, disabled, children, className, ...props }: ListboxItemProps): ReactElement;
         displayName: string;
     };
 };

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

@@ -1 +1,4 @@
 export { useScrollLock } from './use-scroll-lock';
+export { useControlledState } from './use-controlled-state';
+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.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Manages state that can be either controlled or uncontrolled.
+ * Follows the pattern for controlled/uncontrolled state management.
+ *
+ * @template T - The type of the state value
+ *
+ * @param controlledValue - The controlled value from props (e.g., `value`, `open`, `checked`)
+ * @param defaultValue - The default value for uncontrolled mode (e.g., `defaultValue`, `defaultOpen`)
+ * @param onChange - Callback invoked when the value changes
+ *
+ * @returns A tuple containing the current value and a setter function
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled usage
+ * function Component({ defaultOpen = false, onOpenChange }) {
+ *   const [open, setOpen] = useControlledState(undefined, defaultOpen, onOpenChange);
+ *   return <div>{open ? 'Open' : 'Closed'}</div>;
+ * }
+ *
+ * // Controlled usage
+ * function Component({ open, onOpenChange }) {
+ *   const [value, setValue] = useControlledState(open, false, onOpenChange);
+ *   return <div>{value ? 'Open' : 'Closed'}</div>;
+ * }
+ * ```
+ */
+export declare function useControlledState<T>(controlledValue: T | undefined, defaultValue: T, onChange?: (value: T) => void): [T, (value: T) => void];

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

@@ -0,0 +1,57 @@
+export type ItemMetadata = {
+    disabled: boolean;
+};
+export type UseItemRegistryReturn = {
+    /**
+     * Registers an item with the registry.
+     * @param id - Unique identifier for the item
+     * @param disabled - Whether the item is disabled
+     */
+    registerItem: (id: string, disabled?: boolean) => void;
+    /**
+     * Unregisters an item from the registry.
+     * @param id - Unique identifier for the item to remove
+     */
+    unregisterItem: (id: string) => void;
+    /**
+     * Gets all registered item IDs in insertion order.
+     * @returns Array of item IDs
+     */
+    getItems: () => string[];
+    /**
+     * Checks if an item is disabled.
+     * @param id - Item ID to check
+     * @returns True if the item is disabled
+     */
+    isItemDisabled: (id: string) => boolean;
+};
+/**
+ * Hook for managing a registry of items (menu items, listbox options, etc.).
+ * Provides a more reliable alternative to DOM queries for item discovery.
+ *
+ * This pattern is superior to `querySelectorAll` because:
+ * - No stale queries from DOM changes
+ * - Type-safe item metadata
+ * - Better performance (no DOM traversal)
+ * - Consistent insertion order
+ *
+ * @returns Object with registry methods
+ *
+ * @example
+ * ```tsx
+ * function MyList() {
+ *   const { registerItem, unregisterItem, getItems, isItemDisabled } = useItemRegistry();
+ *
+ *   // In child components:
+ *   useEffect(() => {
+ *     registerItem(id, disabled);
+ *     return () => unregisterItem(id);
+ *   }, [id, disabled]);
+ *
+ *   // Navigate through items
+ *   const items = getItems();
+ *   const enabledItems = items.filter(id => !isItemDisabled(id));
+ * }
+ * ```
+ */
+export declare function useItemRegistry(): UseItemRegistryReturn;

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

@@ -0,0 +1,82 @@
+export type KeyboardNavigationConfig = {
+    /**
+     * Get all item IDs in order
+     */
+    getItems: () => string[];
+    /**
+     * Check if an item is disabled
+     */
+    isItemDisabled: (id: string) => boolean;
+    /**
+     * Currently active item ID
+     */
+    active: string | undefined;
+    /**
+     * Set the active item ID
+     */
+    setActive: (id: string | undefined) => void;
+    /**
+     * Whether to loop navigation (wrap around at start/end)
+     * @default false
+     */
+    loop?: boolean;
+    /**
+     * Orientation of navigation
+     * @default 'vertical'
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /**
+     * Called when user requests selection (Enter/Space)
+     * Receives the active item ID
+     */
+    onSelect?: (id: string) => void;
+    /**
+     * Called when user presses Escape
+     */
+    onEscape?: () => void;
+};
+export type UseKeyboardNavigationReturn = {
+    /**
+     * Move active item by delta (1 for next, -1 for previous)
+     */
+    moveActive: (delta: number) => void;
+    /**
+     * Keyboard event handler to attach to the container
+     */
+    handleKeyDown: (e: React.KeyboardEvent<HTMLElement>) => void;
+};
+/**
+ * Hook for keyboard navigation through a list of items.
+ * Handles arrow keys, Home/End, Enter/Space, and Escape.
+ *
+ * Supports:
+ * - ArrowUp/ArrowDown (or ArrowLeft/ArrowRight for horizontal)
+ * - Home/End keys
+ * - Loop navigation (optional)
+ * - Disabled item skipping
+ * - Enter/Space for selection
+ * - Escape key handling
+ *
+ * @param config - Configuration object
+ * @returns Object with navigation methods
+ *
+ * @example
+ * ```tsx
+ * function MyList() {
+ *   const { getItems, isItemDisabled } = useItemRegistry();
+ *   const [active, setActive] = useState<string>();
+ *
+ *   const { handleKeyDown } = useKeyboardNavigation({
+ *     getItems,
+ *     isItemDisabled,
+ *     active,
+ *     setActive,
+ *     loop: true,
+ *     onSelect: (id) => console.log('Selected:', id),
+ *   });
+ *
+ *   return <div onKeyDown={handleKeyDown}>...</div>;
+ * }
+ * ```
+ */
+export declare function useKeyboardNavigation(config: KeyboardNavigationConfig): UseKeyboardNavigationReturn;

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

@@ -6,7 +6,7 @@ export type ComboboxContextValue = {
     closeOnBlur: boolean;
     inputValue: string;
     setInputValue: (value: string) => void;
-    selection: readonly string[];
+    selection: ReadonlySet<string>;
     active?: string;
     keyHandler: (e: React.KeyboardEvent<HTMLElement>) => void;
     disabled?: boolean;

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

@@ -9,6 +9,10 @@ export type ListboxContextValue = {
     setActive: (id?: string) => void;
     toggleValue: (value: string) => void;
     keyHandler?: (e: React.KeyboardEvent<HTMLElement>) => void;
+    registerItem: (id: string, disabled?: boolean) => void;
+    unregisterItem: (id: string) => void;
+    getItems: () => string[];
+    isItemDisabled: (id: string) => boolean;
 };
 export type ListboxProviderProps = {
     value: ListboxContextValue;

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

@@ -0,0 +1,69 @@
+/**
+ * Generates ARIA-compliant IDs for component parts.
+ * Helps maintain consistent ID patterns across components.
+ *
+ * @param baseId - The base ID for the component
+ * @param suffix - The suffix to append (e.g., 'trigger', 'content', 'option')
+ * @returns The generated ID
+ *
+ * @example
+ * ```tsx
+ * const baseId = 'menu-1';
+ * const triggerId = generateAriaId(baseId, 'trigger'); // 'menu-1-trigger'
+ * const contentId = generateAriaId(baseId, 'content'); // 'menu-1-content'
+ * ```
+ */
+export declare function generateAriaId(baseId: string, suffix: string): string;
+/**
+ * Generates multiple ARIA IDs at once from a base ID.
+ * Useful for components with multiple parts.
+ *
+ * @param baseId - The base ID for the component
+ * @param parts - Array of part names
+ * @returns Object mapping part names to generated IDs
+ *
+ * @example
+ * ```tsx
+ * const ids = generateAriaIds('menu-1', ['trigger', 'content', 'item']);
+ * // { trigger: 'menu-1-trigger', content: 'menu-1-content', item: 'menu-1-item' }
+ *
+ * <button id={ids.trigger} aria-controls={ids.content}>Menu</button>
+ * <div id={ids.content} role="menu">...</div>
+ * ```
+ */
+export declare function generateAriaIds<T extends readonly string[]>(baseId: string, parts: T): Record<T[number], string>;
+/**
+ * Generates an ARIA ID for an item within a list (menu, listbox, etc.).
+ *
+ * @param baseId - The base ID for the component
+ * @param componentType - The type of component ('menu', 'listbox', etc.)
+ * @param itemValue - The value/ID of the specific item
+ * @returns The generated item ID
+ *
+ * @example
+ * ```tsx
+ * const itemId = generateItemId('menu-1', 'menu', 'file-open');
+ * // 'menu-1-menu-item-file-open'
+ *
+ * <div id={itemId} role="menuitem">Open File</div>
+ * ```
+ */
+export declare function generateItemId(baseId: string, componentType: string, itemValue: string): string;
+/**
+ * Generates aria-activedescendant ID based on component configuration.
+ * Returns undefined if no active item.
+ *
+ * @param baseId - The base ID for the component
+ * @param componentType - The type of component ('menu', 'listbox', etc.)
+ * @param activeValue - The currently active item value (undefined if none)
+ * @returns The active descendant ID or undefined
+ *
+ * @example
+ * ```tsx
+ * const activeId = getActiveDescendantId('listbox-1', 'listbox', 'option-2');
+ * // 'listbox-1-listbox-item-option-2'
+ *
+ * <div role="listbox" aria-activedescendant={activeId}>...</div>
+ * ```
+ */
+export declare function getActiveDescendantId(baseId: string, componentType: string, activeValue: string | undefined): string | undefined;

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

@@ -1,3 +1,4 @@
+export * from './aria';
 export * from './cn';
 export * from './ref';
 export * from './unwrap';

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

@@ -1,3 +1,3 @@
 import { ForwardedRef, Ref } from 'react';
-export declare function setRef<T>(ref: Ref<T> | undefined, value: T | null): void;
+export declare function setRef<T>(ref: Ref<T> | undefined | null, value: T | null): void;
 export declare function useComposedRefs<T>(...refs: (Ref<T> | undefined | null)[]): ForwardedRef<T>;

package/package.json

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