@lumx/react 4.3.2-alpha.21 → 4.3.2-alpha.23

package/package.json

@@ -6,8 +6,8 @@
         "url": "https://github.com/lumapps/design-system/issues"
     },
     "dependencies": {
-        "@lumx/core": "^4.3.2-alpha.21",
-        "@lumx/icons": "^4.3.2-alpha.21",
+        "@lumx/core": "^4.3.2-alpha.23",
+        "@lumx/icons": "^4.3.2-alpha.23",
         "@popperjs/core": "^2.5.4",
         "body-scroll-lock": "^3.1.5",
         "react-popper": "^2.2.4"
@@ -102,6 +102,6 @@
         "build:storybook": "storybook build"
     },
     "sideEffects": false,
-    "version": "4.3.2-alpha.21",
+    "version": "4.3.2-alpha.23",
     "stableVersion": "4.3.1"
 }

package/utils/index.d.ts

@@ -1,7 +1,10 @@
+import * as React$1 from 'react';
 import React__default, { RefObject, ReactNode, AriaAttributes } from 'react';
 import { Falsy, ObjectValues } from '@lumx/core/js/types';
+import { q as ComboboxAction, X as ComboboxState, y as OnComboboxSelect, T as TextFieldProps, r as ComboboxProps, Y as ComboboxSelectionType, Z as ComboboxTranslations, _ as BaseLoadingStatus, $ as RegisteredComboboxOption, a0 as ComboboxOptionSelectEventSource } from '../Tooltip-D7GkxJsY.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { DisabledStateContextValue } from '@lumx/core/js/utils/disabledState';
+import '@lumx/core/js/constants';
 
 interface ClickAwayParameters {
     /**
@@ -395,5 +398,186 @@ type Output = [
  */
 declare const useRovingTabIndex: (...args: BaseHookOptions) => Output;
 
-export { A11YLiveMessage, ClickAwayProvider, DisabledStateProvider, InfiniteScroll, MovingFocusContext, MovingFocusProvider, Portal, PortalProvider, useDisabledStateContext, useRovingTabIndex, useVirtualFocus, useVirtualFocusParent };
-export type { A11YLiveMessageProps, InfiniteScrollProps, PortalInit, PortalProps, PortalProviderProps };
+/** Dispatch for the combobox component */
+type ComboboxDispatch = React.Dispatch<ComboboxAction>;
+
+interface ComboboxContextActions {
+    onSelect?: OnComboboxSelect;
+    onInputChange?: TextFieldProps['onChange'];
+    onOpen?: (params: {
+        manual: boolean;
+        currentValue: string;
+    }) => void;
+}
+interface ComboboxContextProps extends ComboboxState, ComboboxContextActions {
+    openOnFocus?: ComboboxProps['openOnFocus'];
+    openOnClick?: ComboboxProps['openOnClick'];
+    optionsLength: number;
+    /** The dispatch function to manage the inner state */
+    dispatch: ComboboxDispatch;
+    /** The ids of the currently selected options */
+    selectedIds?: Array<string>;
+    /** the type of selection currently configured for the combobox */
+    selectionType?: ComboboxSelectionType;
+    /**
+     * Whether the error state should be displayed when the status is in error.
+     */
+    showErrorState?: boolean;
+    /**
+     * Whether the empty state should be displayed when there is no results.
+     */
+    showEmptyState?: boolean;
+    /** translations to be used across the combobox */
+    translations: ComboboxTranslations;
+}
+/** Context for the Combobox component */
+declare const ComboboxContext: React__default.Context<ComboboxContextProps>;
+/** Context for a combobox section to store its unique id */
+declare const SectionContext: React__default.Context<{
+    sectionId: string;
+    isLoading?: boolean;
+}>;
+
+interface ComboboxOptionContextValue {
+    optionId?: string;
+    isKeyboardHighlighted?: boolean;
+}
+declare const ComboboxOptionContext: React__default.Context<ComboboxOptionContextValue>;
+interface ComboboxOptionIdProviderProps extends Required<ComboboxOptionContextValue> {
+    /** Option to display */
+    children: ReactNode;
+}
+/** Context Provider to store the current combobox option id. */
+declare const ComboboxOptionContextProvider: ({ optionId, isKeyboardHighlighted, children, }: ComboboxOptionIdProviderProps) => react_jsx_runtime.JSX.Element;
+/**
+ * Retrieve the current combobox option id.
+ * Must be used within a ComboboxOptionIdProvider
+ */
+declare const useComboboxOptionContext: () => Required<ComboboxOptionContextValue>;
+
+interface ComboboxProviderProps {
+    children: ReactNode;
+    /** The data to pass the provider. Can be generated by the useCombobox hook */
+    value: ComboboxContextProps;
+}
+/** Context provider for the combobox. */
+declare const ComboboxProvider: ({ children, value }: ComboboxProviderProps) => react_jsx_runtime.JSX.Element;
+
+interface ComboboxRefsContext {
+    triggerRef: RefObject<HTMLElement>;
+    anchorRef: RefObject<HTMLElement>;
+}
+/** Context to store the refs of the combobox elements */
+declare const ComboboxRefsContext: React$1.Context<ComboboxRefsContext>;
+interface ComboboxRefsProviderProps extends ComboboxRefsContext {
+    children: ReactNode;
+}
+/** Provider to store the required refs for the Combobox */
+declare const ComboboxRefsProvider: ({ triggerRef, anchorRef, children }: ComboboxRefsProviderProps) => react_jsx_runtime.JSX.Element;
+/** Retrieves the combobox elements references from context */
+declare const useComboboxRefs: () => ComboboxRefsContext;
+
+/** Retrieve the current combobox state and actions */
+declare const useCombobox: () => {
+    openOnFocus?: ComboboxProps["openOnFocus"];
+    openOnClick?: ComboboxProps["openOnClick"];
+    optionsLength: number;
+    selectedIds?: Array<string>;
+    selectionType?: ComboboxSelectionType;
+    showErrorState?: boolean;
+    showEmptyState?: boolean;
+    translations: ComboboxTranslations;
+    comboboxId: string;
+    listboxId: string;
+    status: BaseLoadingStatus;
+    options: Record<string, RegisteredComboboxOption>;
+    isOpen: boolean;
+    showAll: boolean;
+    type: "listbox" | "grid";
+    defaultInputValue?: string;
+    handleClose: () => void;
+    handleOpen: (params?: {
+        manual?: boolean;
+    }) => Promise<RegisteredComboboxOption[] | undefined>;
+    handleInputChange: (value: string, name?: string, event?: React__default.SyntheticEvent) => void;
+    handleSelected: (option: RegisteredComboboxOption, source?: ComboboxOptionSelectEventSource) => void;
+    dispatch: ComboboxDispatch;
+    inputValue: string;
+};
+
+interface UseComboboxTriggerArgs {
+    context: ReturnType<typeof useCombobox>;
+    refs: ReturnType<typeof useComboboxRefs>;
+    onKeyDown?: React__default.KeyboardEventHandler;
+    onFocus?: React__default.FocusEventHandler;
+    onBlur?: React__default.FocusEventHandler;
+}
+/**
+ * Provide props for the semantic and behaviors the combobox trigger.
+ *
+ *
+ */
+declare function useComboboxTrigger({ context, refs, onBlur, onFocus, onKeyDown }: UseComboboxTriggerArgs): {
+    id: string;
+    role: string;
+    'aria-activedescendant': string;
+    'aria-controls': string;
+    'aria-owns': string;
+    'aria-expanded': boolean;
+    onFocus: (event: React__default.FocusEvent) => void;
+    onBlur: (event: React__default.FocusEvent<Element>) => void;
+    onClick: () => void;
+    onKeyDown: React__default.KeyboardEventHandler<Element>;
+};
+
+/**
+ * Provide props for the semantic and behaviors the combobox button trigger
+ *
+ * Overrides the useComboboxTrigger() props & behavior to add a jump to option
+ * on printable character key down.
+ */
+declare function useComboboxButton(args: UseComboboxTriggerArgs): {
+    id: string;
+    role: string;
+    'aria-activedescendant': string;
+    'aria-controls': string;
+    'aria-owns': string;
+    'aria-expanded': boolean;
+    onFocus: (event: React__default.FocusEvent) => void;
+    onBlur: (event: React__default.FocusEvent<Element>) => void;
+    onClick: () => void;
+    onKeyDown: React__default.KeyboardEventHandler<Element>;
+};
+
+/**
+ * Provide props for the semantic and behaviors the combobox input trigger
+ *
+ * Overrides the useComboboxTrigger() props & behavior to prevent open on click
+ * if `openOnFocus` is not enabled.
+ */
+declare function useComboboxInput({ onKeyDown: propsOnKeyDown, ...args }: UseComboboxTriggerArgs): {
+    onClick: () => void;
+    onKeyDown: React__default.KeyboardEventHandler<Element>;
+    id: string;
+    role: string;
+    'aria-activedescendant': string;
+    'aria-controls': string;
+    'aria-owns': string;
+    'aria-expanded': boolean;
+    onFocus: (event: React__default.FocusEvent) => void;
+    onBlur: (event: React__default.FocusEvent<Element>) => void;
+};
+
+/** Retrieve the current combobox section id */
+declare const useComboboxSectionId: () => {
+    sectionId: string;
+    isLoading?: boolean;
+};
+
+/**
+ * Register the given option to the context
+ */
+declare const useRegisterOption: (registerId: string, option: RegisteredComboboxOption, shouldRegister?: boolean) => void;
+
+export { A11YLiveMessage, ClickAwayProvider, ComboboxContext, ComboboxOptionContext, ComboboxOptionContextProvider, ComboboxProvider, ComboboxRefsProvider, DisabledStateProvider, InfiniteScroll, MovingFocusContext, MovingFocusProvider, Portal, PortalProvider, SectionContext, useCombobox, useComboboxButton, useComboboxInput, useComboboxOptionContext, useComboboxRefs, useComboboxSectionId, useComboboxTrigger, useDisabledStateContext, useRegisterOption, useRovingTabIndex, useVirtualFocus, useVirtualFocusParent };
+export type { A11YLiveMessageProps, ComboboxContextActions, ComboboxContextProps, ComboboxOptionContextValue, ComboboxProviderProps, InfiniteScrollProps, PortalInit, PortalProps, PortalProviderProps, UseComboboxTriggerArgs };

package/utils/index.js

@@ -1,7 +1,8 @@
-import { r as reducer, I as INITIAL_STATE, b as buildLoopAroundObject, M as MovingFocusContext, N as NAV_KEYS, g as getPointerTypeFromEvent } from '../_internal/CzTdCnO5.js';
-export { A as A11YLiveMessage, C as ClickAwayProvider, D as DisabledStateProvider, P as Portal, c as PortalProvider, u as useDisabledStateContext, a as useVirtualFocus } from '../_internal/CzTdCnO5.js';
-import React__default, { useEffect } from 'react';
+import { r as reducer, I as INITIAL_STATE, i as buildLoopAroundObject, M as MovingFocusContext, N as NAV_KEYS, j as getPointerTypeFromEvent, k as ComboboxContext, l as isComboboxValue } from '../_internal/BSETDrpT.js';
+export { A as A11YLiveMessage, h as ClickAwayProvider, m as ComboboxOptionContext, C as ComboboxOptionContextProvider, n as ComboboxRefsProvider, D as DisabledStateProvider, P as Portal, o as PortalProvider, S as SectionContext, b as useCombobox, e as useComboboxOptionContext, f as useComboboxRefs, a as useComboboxSectionId, u as useDisabledStateContext, c as useRegisterOption, d as useVirtualFocus } from '../_internal/BSETDrpT.js';
 import { jsx } from 'react/jsx-runtime';
+import React__default, { useEffect } from 'react';
+import debounce from 'lodash/debounce.js';
 import isNil from 'lodash/isNil.js';
 import uniqueId from 'lodash/uniqueId.js';
 
@@ -275,5 +276,364 @@ const useRovingTabIndex = (ref, disabled = false, rowKey = null, autofocus = fal
   return [tabIndex, focused, handleKeyDown, handleClick];
 };
 
-export { InfiniteScroll, MovingFocusContext, MovingFocusProvider, useRovingTabIndex, useVirtualFocusParent };
+/** Context provider for the combobox. */
+const ComboboxProvider = ({
+  children,
+  value
+}) => {
+  return /*#__PURE__*/jsx(ComboboxContext.Provider, {
+    value: value,
+    children: /*#__PURE__*/jsx(MovingFocusProvider, {
+      options: {
+        direction: value.type === 'grid' ? 'both' : 'vertical',
+        firstFocusDirection: value.type === 'grid' ? 'vertical' : undefined,
+        loopAround: {
+          row: 'next-loop',
+          col: 'inside'
+        },
+        gridJumpToShortcutDirection: 'vertical',
+        defaultSelectedId: value.selectedIds?.[0],
+        listKey: value.inputValue
+      },
+      children: children
+    })
+  });
+};
+
+/**
+ * Provide props for the semantic and behaviors the combobox trigger.
+ *
+ *
+ */
+function useComboboxTrigger({
+  context,
+  refs,
+  onBlur,
+  onFocus,
+  onKeyDown
+}) {
+  const {
+    comboboxId,
+    listboxId,
+    isOpen,
+    options,
+    optionsLength,
+    selectedIds,
+    openOnFocus,
+    handleClose,
+    handleOpen,
+    handleSelected,
+    showEmptyState = false,
+    showErrorState = false,
+    status
+  } = context;
+  const highlightedId = useVirtualFocusParent(refs.triggerRef);
+  const {
+    dispatch: movingFocusDispatch
+  } = React__default.useContext(MovingFocusContext);
+  const isErrorStateDisplayed = showErrorState && isOpen && status === 'error';
+  const isEmptyStateDisplayed = showEmptyState && isOpen && status === 'idle' && optionsLength === 0;
+  const showPopover = isOpen && optionsLength > 0 || isEmptyStateDisplayed || isErrorStateDisplayed;
+
+  /**
+   * A debounce close to use to leave time for the
+   * listbox to process things before closing.
+   * This can be useful when clicking an option to leave time for the
+   * event to be processed before closing the popover.
+   */
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const debouncedClose = React__default.useCallback(debounce(handleClose, 200), []);
+
+  /** Cleanup any ongoing cleanup */
+  React__default.useEffect(() => {
+    return () => {
+      if (debouncedClose?.cancel) {
+        debouncedClose.cancel();
+      }
+    };
+  }, [debouncedClose]);
+  const handleBlur = React__default.useCallback(event => {
+    debouncedClose();
+    if (onBlur) {
+      onBlur(event);
+    }
+  }, [debouncedClose, onBlur]);
+
+  /** Actions triggered when the input field is focused */
+  const handleFocus = event => {
+    // If the field is refocused in the process of closing, cancel close
+    if (debouncedClose?.cancel) {
+      debouncedClose.cancel();
+    }
+    if (onFocus) {
+      onFocus(event);
+    }
+    /**
+     * Only set the open on focus if the combobox isn't already opened.
+     * This avoids the popover re-opening when an option is selected and the
+     * field is refocused
+     */
+    if (openOnFocus && !showPopover) {
+      handleOpen({
+        manual: true
+      });
+    }
+  };
+  const handleClick = () => {
+    handleOpen({
+      manual: true
+    });
+  };
+
+  /**
+   * Keyboard shortcut management following the WAI APG pattern
+   * https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/#kbd_label
+   */
+  const handleKeyDown = React__default.useCallback(async event => {
+    const {
+      key,
+      altKey
+    } = event;
+
+    /**
+     * On Enter key
+     * * Select option that is currently highlighted, if any
+     * * Close suggestions, event if none is highlighted
+     */
+    if (event.key === 'Enter') {
+      if (!showPopover) {
+        return;
+      }
+      if (highlightedId) {
+        // prevent any potential form submission
+        event.preventDefault();
+        const option = options[highlightedId];
+        handleSelected(option, 'keyboard');
+      } else {
+        handleClose();
+      }
+      return;
+    }
+
+    /**
+     * On arrow up/down
+     * * If popover is already opened, do nothing
+     * * If alt key pressed, show the listbox without focusing an option
+     * * If arrow Up is pressed, select last option
+     * * If arrow Down is pressed, select first option
+     * */
+    if (key === 'ArrowDown' || key === 'ArrowUp') {
+      if (showPopover) {
+        return;
+      }
+
+      /** Open the listbox */
+      const listBoxOptions = await handleOpen({
+        manual: true
+      });
+      if (!listBoxOptions) {
+        return;
+      }
+
+      /**
+       * If alt key is pressed, only open without changing visual focus
+       * as per WAI Guidelines
+       */
+      if (!altKey) {
+        /** If a selected id is set, set it as current tabstop */
+        if (selectedIds?.length) {
+          movingFocusDispatch({
+            type: 'SELECT_TAB_STOP',
+            payload: {
+              id: selectedIds?.[0],
+              type: 'keyboard'
+            }
+          });
+        } else {
+          /** Focus either the first or last item depending on the keyboard arrow pressed */
+          movingFocusDispatch({
+            type: 'KEY_NAV',
+            payload: {
+              ctrlKey: false,
+              key: key === 'ArrowUp' ? 'End' : 'Home'
+            }
+          });
+        }
+      }
+      return;
+    }
+
+    // Forward event
+    onKeyDown?.(event);
+  }, [onKeyDown, showPopover, highlightedId, options, handleSelected, handleClose, handleOpen, selectedIds, movingFocusDispatch]);
+  return {
+    id: comboboxId,
+    role: 'combobox',
+    'aria-activedescendant': showPopover && highlightedId ? highlightedId : '',
+    'aria-controls': listboxId,
+    'aria-owns': listboxId,
+    'aria-expanded': showPopover,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
+    onClick: handleClick,
+    onKeyDown: handleKeyDown
+  };
+}
+
+/** Is printable character key press */
+const isTypeEvent = ({
+  key,
+  altKey,
+  ctrlKey,
+  metaKey
+}) => key.length === 1 && key !== ' ' && !altKey && !ctrlKey && !metaKey;
+
+/**
+ * Provide props for the semantic and behaviors the combobox button trigger
+ *
+ * Overrides the useComboboxTrigger() props & behavior to add a jump to option
+ * on printable character key down.
+ */
+function useComboboxButton(args) {
+  const {
+    context: {
+      handleOpen
+    },
+    onKeyDown: parentOnKeyDown
+  } = args;
+  const {
+    dispatch: movingFocusDispatch,
+    state: {
+      selectedId: highlightedId
+    }
+  } = React__default.useContext(MovingFocusContext);
+  const searchValueRef = React__default.useRef('');
+  const searchTimeoutRef = React__default.useRef();
+  const onKeyDown = React__default.useMemo(() => {
+    function clearSearchTimeout() {
+      const searchTimeout = searchTimeoutRef.current;
+      if (!searchTimeout) {
+        return;
+      }
+      clearTimeout(searchTimeout);
+      searchTimeoutRef.current = undefined;
+    }
+    function clearSearch() {
+      searchValueRef.current = '';
+      clearSearchTimeout();
+    }
+    return async event => {
+      if (!isTypeEvent(event)) {
+        // Forward key down event
+        parentOnKeyDown?.(event);
+        return undefined;
+      }
+      event.stopPropagation();
+
+      // Clear current search timeout
+      clearSearchTimeout();
+
+      // Open combobox and wait for options to mount
+      const options = await handleOpen({
+        manual: false
+      });
+      const optionArray = options && Object.values(options);
+      if (!optionArray?.length) {
+        return undefined;
+      }
+
+      // Append key to current search
+      searchValueRef.current += event.key.toLowerCase();
+      const searchValue = searchValueRef.current;
+
+      // Clear search after 500ms
+      searchTimeoutRef.current = setTimeout(clearSearch, 500);
+
+      // Search is containing all the same letters (ex: aaaa)
+      const allTheSameLetters = searchValue.split('').every(letter => letter === searchValue[0]);
+
+      // start from currently selected option
+      let startIndex = optionArray.findIndex(option => option.generatedId === highlightedId);
+      if (startIndex === -1) {
+        startIndex = 0;
+      }
+      let index = startIndex;
+      do {
+        // Increment index and loop around to 0 if we get over the array length
+        index = (index + 1) % optionArray.length;
+        const option = optionArray[index];
+        // Search by text value or fallback on id.
+        const optionText = isComboboxValue(option) ? option?.textValue || option?.id : null;
+        if (isComboboxValue(option) && optionText) {
+          const optionTextValue = optionText.toLowerCase();
+
+          // Search on first letter if search is all the same letters
+          const searchText = allTheSameLetters ? searchValue[0] : searchValue;
+
+          // Option text value starts with searched text
+          if (optionTextValue.startsWith(searchText)) {
+            movingFocusDispatch({
+              type: 'SELECT_TAB_STOP',
+              payload: {
+                id: option.generatedId,
+                type: 'keyboard'
+              }
+            });
+            break;
+          }
+        }
+      } while (index !== startIndex);
+      return clearSearchTimeout;
+    };
+  }, [handleOpen, parentOnKeyDown, highlightedId, movingFocusDispatch]);
+  return useComboboxTrigger({
+    ...args,
+    onKeyDown
+  });
+}
+
+/**
+ * Provide props for the semantic and behaviors the combobox input trigger
+ *
+ * Overrides the useComboboxTrigger() props & behavior to prevent open on click
+ * if `openOnFocus` is not enabled.
+ */
+function useComboboxInput({
+  onKeyDown: propsOnKeyDown,
+  ...args
+}) {
+  const triggerProps = useComboboxTrigger(args);
+  const {
+    onClick,
+    onKeyDown,
+    'aria-expanded': showPopover
+  } = triggerProps;
+  const handleClick = () => {
+    if (!args.context.openOnFocus && !args.context.openOnClick) {
+      // Skip if input should not opening on focus nor click
+      return;
+    }
+    onClick();
+  };
+  const handleKeyDown = evt => {
+    if (evt.key === 'Escape') {
+      // Reset field if closed
+      if (!showPopover) {
+        args.context.handleInputChange('');
+      }
+      return;
+    }
+    onKeyDown(evt);
+    if (propsOnKeyDown) {
+      propsOnKeyDown(evt);
+    }
+  };
+  return {
+    ...triggerProps,
+    onClick: handleClick,
+    onKeyDown: handleKeyDown
+  };
+}
+
+export { ComboboxContext, ComboboxProvider, InfiniteScroll, MovingFocusContext, MovingFocusProvider, useComboboxButton, useComboboxInput, useComboboxTrigger, useRovingTabIndex, useVirtualFocusParent };
 //# sourceMappingURL=index.js.map