@itwin/itwinui-react 3.15.5 → 3.16.0

package/DEV-esm/utils/components/OverflowContainer.js

@@ -1,13 +1,14 @@
 import React from 'react';
 import { useMergedRefs } from '../hooks/useMergedRefs.js';
 import { Box } from './Box.js';
-import { useOverflow } from '../hooks/useOverflow.js';
+import { useLayoutEffect } from '../hooks/useIsomorphicLayoutEffect.js';
 import { useSafeContext } from '../hooks/useSafeContext.js';
-let OverflowContainerComponent = React.forwardRef((props, ref) => {
+import { isUnitTest } from '../functions/dev.js';
+import { useResizeObserver } from '../hooks/useResizeObserver.js';
+let OverflowContainerMain = React.forwardRef((props, forwardedRef) => {
   let { itemsCount, children, overflowOrientation, ...rest } = props;
   let [containerRef, visibleCount] = useOverflow(
     itemsCount,
-    false,
     overflowOrientation,
   );
   let overflowContainerContextValue = React.useMemo(
@@ -25,7 +26,7 @@ let OverflowContainerComponent = React.forwardRef((props, ref) => {
     React.createElement(
       Box,
       {
-        ref: useMergedRefs(ref, containerRef),
+        ref: useMergedRefs(forwardedRef, containerRef),
         ...rest,
       },
       children,
@@ -38,12 +39,150 @@ let OverflowContainerOverflowNode = (props) => {
   let isOverflowing = visibleCount < itemsCount;
   return isOverflowing ? children : null;
 };
+let OverflowContainerComponent = React.forwardRef((props, forwardedRef) => {
+  let { itemsCount, overflowOrientation = 'horizontal', ...rest } = props;
+  let [size, setSize] = React.useState(null);
+  let [resizeRef] = useResizeObserver(setSize);
+  let ref = useMergedRefs(resizeRef, forwardedRef);
+  let key = `${itemsCount}${
+    'vertical' === overflowOrientation ? size?.height : size?.width
+  }`;
+  return React.createElement(OverflowContainerMain, {
+    ...rest,
+    key: key,
+    ref: ref,
+    itemsCount: itemsCount,
+    overflowOrientation: overflowOrientation,
+  });
+});
 export const OverflowContainer = Object.assign(OverflowContainerComponent, {
   OverflowNode: OverflowContainerOverflowNode,
   useContext: useOverflowContainerContext,
 });
 let OverflowContainerContext = React.createContext(void 0);
 OverflowContainerContext.displayName = 'OverflowContainerContext';
+let useOverflow = (itemsCount, orientation = 'horizontal') => {
+  let [guessState, dispatch] = React.useReducer(
+    overflowGuessReducer,
+    {
+      itemsCount,
+    },
+    overflowGuessReducerInitialState,
+  );
+  let containerRef = React.useRef(null);
+  let isGuessing = React.useRef(false);
+  useLayoutEffect(() => {
+    let { minGuess, maxGuess, isStabilized, visibleCount } = guessState;
+    if (isStabilized) return;
+    guessVisibleCount();
+    function guessVisibleCount() {
+      if (isStabilized || isGuessing.current || isUnitTest) return;
+      try {
+        isGuessing.current = true;
+        if (null == containerRef.current) return;
+        let dimension = 'horizontal' === orientation ? 'Width' : 'Height';
+        let availableSize = containerRef.current[`offset${dimension}`];
+        let requiredSize = containerRef.current[`scroll${dimension}`];
+        let isOverflowing = availableSize < requiredSize;
+        if (
+          0 === itemsCount ||
+          (1 === visibleCount && isOverflowing) ||
+          (visibleCount === itemsCount && !isOverflowing) ||
+          (maxGuess - minGuess === 1 && visibleCount === minGuess)
+        ) {
+          dispatch({
+            type: 'stabilize',
+          });
+          return;
+        }
+        if (maxGuess === visibleCount && !isOverflowing) {
+          dispatch({
+            type: 'shiftGuessRangeForward',
+          });
+          return;
+        }
+        isOverflowing
+          ? dispatch({
+              type: 'decreaseMaxGuess',
+              currentState: guessState,
+            })
+          : dispatch({
+              type: 'increaseMinGuess',
+              currentState: guessState,
+            });
+      } finally {
+        isGuessing.current = false;
+      }
+    }
+  }, [guessState, itemsCount, orientation]);
+  return [containerRef, guessState.visibleCount];
+};
+let STARTING_MAX_ITEMS_COUNT = 32;
+let overflowGuessReducerInitialState = ({ itemsCount }) => {
+  let initialVisibleCount = Math.min(itemsCount, STARTING_MAX_ITEMS_COUNT);
+  return isUnitTest
+    ? {
+        isStabilized: true,
+        minGuess: null,
+        maxGuess: null,
+        itemsCount,
+        visibleCount: itemsCount,
+      }
+    : {
+        isStabilized: false,
+        minGuess: 0,
+        maxGuess: initialVisibleCount,
+        itemsCount,
+        visibleCount: initialVisibleCount,
+      };
+};
+let overflowGuessReducer = (state, action) => {
+  let getSafeVisibleCount = ({ visibleCount, itemsCount }) =>
+    Math.min(itemsCount, visibleCount);
+  switch (action.type) {
+    case 'decreaseMaxGuess':
+    case 'increaseMinGuess':
+      if (state.isStabilized) return state;
+      let newMinGuess = state.minGuess;
+      let newMaxGuess = state.maxGuess;
+      if ('decreaseMaxGuess' === action.type)
+        newMaxGuess = action.currentState.visibleCount;
+      else newMinGuess = action.currentState.visibleCount;
+      let newVisibleCount = Math.floor((newMinGuess + newMaxGuess) / 2);
+      return {
+        ...state,
+        isStabilized: false,
+        minGuess: newMinGuess,
+        maxGuess: newMaxGuess,
+        visibleCount: getSafeVisibleCount({
+          visibleCount: newVisibleCount,
+          itemsCount: state.itemsCount,
+        }),
+      };
+    case 'shiftGuessRangeForward':
+      if (state.isStabilized) return state;
+      let doubleOfMaxGuess = 2 * state.maxGuess;
+      return {
+        ...state,
+        isStabilized: false,
+        minGuess: state.maxGuess,
+        maxGuess: doubleOfMaxGuess,
+        visibleCount: getSafeVisibleCount({
+          visibleCount: doubleOfMaxGuess,
+          itemsCount: state.itemsCount,
+        }),
+      };
+    case 'stabilize':
+      return {
+        ...state,
+        isStabilized: true,
+        minGuess: null,
+        maxGuess: null,
+      };
+    default:
+      return state;
+  }
+};
 function useOverflowContainerContext() {
   let overflowContainerContext = useSafeContext(OverflowContainerContext);
   return overflowContainerContext;

package/DEV-esm/utils/hooks/index.js

@@ -1,6 +1,5 @@
 export * from './useEventListener.js';
 export * from './useMergedRefs.js';
-export * from './useOverflow.js';
 export * from './useResizeObserver.js';
 export * from './useContainerWidth.js';
 export * from './useGlobals.js';
@@ -14,4 +13,5 @@ export * from './useId.js';
 export * from './useControlledState.js';
 export * from './useSyncExternalStore.js';
 export * from './useVirtualScroll.js';
+export * from './useInstance.js';
 export * from './useWarningLogger.js';

package/DEV-esm/utils/hooks/useInstance.js

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import { useSyncExternalStore } from './useSyncExternalStore.js';
+class Instance {}
+export const useInstance = () => React.useMemo(() => new Instance(), []);
+export const useSynchronizeInstance = (instance, properties) => {
+  let synchronize = React.useCallback(() => {
+    if (!(instance instanceof Instance)) return () => {};
+    Object.assign(instance, properties);
+    return () => {
+      for (let key in properties) delete instance[key];
+    };
+  }, [instance, properties]);
+  return useSyncExternalStore(
+    synchronize,
+    () => instance,
+    () => instance,
+  );
+};

package/cjs/core/Breadcrumbs/Breadcrumbs.js

@@ -15,7 +15,7 @@ const _classnames = _interop_require_default._(require('classnames'));
 const _index = require('../../utils/index.js');
 const _Button = require('../Buttons/Button.js');
 const _Anchor = require('../Typography/Anchor.js');
-const BreadcrumbsComponent = _react.forwardRef((props, ref) => {
+const BreadcrumbsComponent = _react.forwardRef((props, forwardedRef) => {
   let {
     children: childrenProp,
     currentIndex = _react.Children.count(childrenProp) - 1,
@@ -33,7 +33,7 @@ const BreadcrumbsComponent = _react.forwardRef((props, ref) => {
     {
       as: 'nav',
       className: (0, _classnames.default)('iui-breadcrumbs', className),
-      ref: ref,
+      ref: forwardedRef,
       'aria-label': 'Breadcrumb',
       ...rest,
     },

package/cjs/core/Checkbox/Checkbox.js

@@ -46,11 +46,11 @@ const Checkbox = _react.forwardRef((props, ref) => {
         'iui-checkbox',
         {
           'iui-checkbox-visibility': 'eyeball' === variant,
-          'iui-loading': isLoading,
         },
         className,
       ),
       style: style,
+      'data-iui-loading': isLoading ? 'true' : void 0,
       disabled: disabled || isLoading,
       type: 'checkbox',
       ref: refs,
@@ -71,13 +71,11 @@ const Checkbox = _react.forwardRef((props, ref) => {
           as: 'label',
           className: (0, _classnames.default)(
             'iui-checkbox-wrapper',
-            {
-              'iui-disabled': disabled,
-              [`iui-${status}`]: !!status,
-              'iui-loading': isLoading,
-            },
             wrapperClassName,
           ),
+          'data-iui-disabled': disabled ? 'true' : void 0,
+          'data-iui-status': status,
+          'data-iui-loading': isLoading ? 'true' : void 0,
           ...restWrapperProps,
         },
         checkbox,

package/cjs/core/ComboBox/ComboBox.d.ts

@@ -33,11 +33,24 @@ export type ComboboxMultipleTypeProps<T> = {
      * Callback fired when selected value changes.
      */
     onChange?: (value: T) => void;
+    /**
+     * Only applicable when `multiple` is enabled.
+     *
+     * If `true`, toggling an option will clear the filter.
+     * Useful when users would likely want to re-filter after toggling an option.
+     *
+     * If `false`, the filter will remain as-is after toggling an option.
+     * Useful when users would likely want to toggle multiple options from the _same_ filtered results.
+     *
+     * @default true
+     */
+    clearFilterOnOptionToggle?: never;
 } | {
     multiple: true;
     value?: T[] | null | undefined;
     defaultValue?: T[] | null;
     onChange?: (value: T[], event: MultipleOnChangeProps<T>) => void;
+    clearFilterOnOptionToggle?: boolean;
 };
 export type ComboBoxProps<T> = {
     /**

package/cjs/core/ComboBox/ComboBox.js

@@ -51,6 +51,7 @@ const ComboBox = _react.forwardRef((props, forwardedRef) => {
     onHide: onHideProp,
     id = inputProps?.id ? `iui-${inputProps.id}-cb` : idPrefix,
     defaultValue,
+    clearFilterOnOptionToggle = true,
     ...rest
   } = props;
   let inputRef = _react.useRef(null);
@@ -204,7 +205,6 @@ const ComboBox = _react.forwardRef((props, forwardedRef) => {
         preventScroll: true,
       });
       if (optionsRef.current[__originalIndex]?.disabled) return;
-      setIsInputDirty(false);
       if (multiple) {
         let actionType = isMenuItemSelected(__originalIndex)
           ? 'removed'
@@ -222,7 +222,10 @@ const ComboBox = _react.forwardRef((props, forwardedRef) => {
             .filter(Boolean)
             .join(', '),
         );
-        setInputValue('');
+        if (clearFilterOnOptionToggle) {
+          setInputValue('');
+          setIsInputDirty(false);
+        }
       } else {
         setSelectedIndexes(__originalIndex);
         hide();
@@ -230,13 +233,14 @@ const ComboBox = _react.forwardRef((props, forwardedRef) => {
       }
     },
     [
-      selectedChangeHandler,
-      isMenuItemSelected,
+      optionsRef,
       multiple,
+      isMenuItemSelected,
+      selectedChangeHandler,
+      setSelectedIndexes,
       onChangeHandler,
-      optionsRef,
+      clearFilterOnOptionToggle,
       hide,
-      setSelectedIndexes,
     ],
   );
   let getMenuItem = _react.useCallback(

package/cjs/core/DatePicker/DatePicker.d.ts

@@ -29,8 +29,8 @@ export type DateRangePickerProps = {
     onChange?: (date: Date) => void;
 } | {
     enableRangeSelect: true;
-    startDate: Date;
-    endDate: Date;
+    startDate?: Date;
+    endDate?: Date;
     onChange?: (startDate: Date, endDate: Date) => void;
 };
 type DatePickerProps = {

package/cjs/core/DatePicker/DatePicker.js

@@ -148,6 +148,7 @@ const DatePicker = _react.forwardRef((props, forwardedRef) => {
     showDatesOutsideMonth = true,
     ...rest
   } = props;
+  let logWarning = (0, _index.useWarningLogger)();
   let monthNames = localizedNames?.months ?? defaultMonths;
   let shortDays = localizedNames?.shortDays ?? defaultShortDays;
   let longDays = localizedNames?.days ?? defaultLongDays;
@@ -192,7 +193,7 @@ const DatePicker = _react.forwardRef((props, forwardedRef) => {
   let popoverInitialFocusContext = _react.useContext(
     _Popover.PopoverInitialFocusContext,
   );
-  _react.useLayoutEffect(() => {
+  (0, _index.useLayoutEffect)(() => {
     if (setFocus && popoverInitialFocusContext)
       popoverInitialFocusContext.setInitialFocus(-1);
   }, [popoverInitialFocusContext, setFocus]);

package/cjs/core/Dialog/Dialog.js

@@ -23,7 +23,7 @@ const _reacttransitiongroup = require('react-transition-group');
 const DialogComponent = _react.forwardRef((props, ref) => {
   let {
     trapFocus = false,
-    setFocus = false,
+    setFocus = trapFocus,
     preventDocumentScroll = false,
     isOpen = false,
     isDismissible = true,

package/cjs/core/Dialog/DialogContext.d.ts

@@ -30,13 +30,17 @@ export type DialogContextProps = {
      */
     closeOnEsc?: boolean;
     /**
-     * Traps the focus inside the dialog. This is useful when the dialog is modal.
+     * Prevents focus from leaving the dialog. This is useful when the dialog is modal.
+     *
+     * Setting this prop to `true` will also set `setFocus` to `true`.
+     *
      * @default false
      */
     trapFocus?: boolean;
     /**
      * If true, focuses the dialog.
-     * @default false
+     *
+     * Defaults to `true` if `trapFocus` is set to `true`, otherwise defaults to `false`.
      */
     setFocus?: boolean;
     /**

package/cjs/core/Panels/Panels.d.ts

@@ -0,0 +1,174 @@
+import * as React from 'react';
+import type { PolymorphicForwardRefComponent } from '../../utils/index.js';
+import { Text } from '../Typography/Text.js';
+import type { FocusEntry, PanelsInstance, TriggerMapEntry } from './helpers.js';
+type PanelsWrapperProps = {
+    /**
+     * Function that gets called when the active panel is changed.
+     */
+    onActiveIdChange?: (newActiveId: string) => void;
+    children: React.ReactNode;
+    /**
+     * Pass an instance created by `useInstance` to control the panels imperatively.
+     *
+     * @example
+     * const panels = Panels.useInstance();
+     * <Panels instance={panels} />
+     */
+    instance?: PanelsInstance;
+};
+export declare const PanelsWrapper: PolymorphicForwardRefComponent<"div", PanelsWrapperProps>;
+export declare const PanelsWrapperContext: React.Context<{
+    activePanelId: string | undefined;
+    setActivePanelId: React.Dispatch<React.SetStateAction<string>>;
+    /**
+     * Simpler alternative to a full history stack.
+     *
+     * ```
+     * Record<
+     *   string, // Id of a panel
+     *   {
+     *     triggerId: string, // Id of the trigger element that points to this panel
+     *     panelId: string, // Id of the panel element in which the trigger is present
+     *   }
+     * >
+     * ```
+     */
+    triggers: Record<string, TriggerMapEntry>;
+    setTriggers: React.Dispatch<React.SetStateAction<Record<string, TriggerMapEntry>>>;
+    changeActivePanel: (newActiveId: string) => void;
+    shouldFocus: FocusEntry;
+    setShouldFocus: React.Dispatch<React.SetStateAction<FocusEntry>>;
+    panels: React.MutableRefObject<Set<string>>;
+} | undefined>;
+type PanelProps = {
+    id: string;
+};
+type PanelTriggerProps = {
+    for: string;
+    children: React.ReactElement;
+};
+type PanelHeaderProps = {
+    titleProps?: React.ComponentProps<typeof Text>;
+};
+export declare const Panels: {
+    /**
+     * Component that manages the logic for layered panels.
+     * It can be used anywhere to create layers. E.g. `Menu`, `InformationPanel`, `Popover`, etc.
+     *
+     * Requirements:
+     * - The initial displayed Panel should be the first `Panel` in the `Panels.Wrapper`.
+     * - A panel can have only one trigger pointing to it. i.e. out of all the triggers across all panels,
+     *   only one can point to a particular panel.
+     * - The `Panels.Panel`s within the wrapper should be in the order of the navigation. E.g.:
+     *   ```jsx
+     *   <Panels.Wrapper>
+     *     <Panels.Panel id={root} /> // Must come before moreDetails since it contains the trigger to moreDetails
+     *     <Panels.Panel id={moreDetails}> // Must come after root since it is navigated to from root
+     *   </Panels.Wrapper>
+     *   ```
+     *
+     * @example
+     * <Panels.Wrapper as={Surface}>
+     *   <Panels.Panel
+     *     id={panelIdRoot}
+     *     as={Surface}
+     *     border={false}
+     *     elevation={0}
+     *   >
+     *     <Surface.Header as={Panels.Header}>Root</Surface.Header>
+     *     <Surface.Body as={List}>
+     *       <ListItem>
+     *         <Panels.Trigger for={panelIdMoreInfo}>
+     *           <ListItem.Action>More details</ListItem.Action>
+     *         </Panels.Trigger>
+     *       </ListItem>
+     *     </Surface.Body>
+     *   </Panels.Panel>
+     *
+     *   <Panels.Panel
+     *     id={panelIdMoreInfo}
+     *     as={Surface}
+     *     border={false}
+     *     elevation={0}
+     *   >
+     *     <Surface.Header as={Panels.Header}>More details</Surface.Header>
+     *     <Surface.Body isPadded>
+     *       <Text>Content</Text>
+     *     </Surface.Body>
+     *   </Panels.Panel>
+     * </Panels.Wrapper>
+     */
+    Wrapper: PolymorphicForwardRefComponent<"div", PanelsWrapperProps>;
+    /**
+     * Takes an `id` and the panel content.
+     * Match this `id` with a `Panels.Triggers`'s `for` prop to create a link between them.
+     *
+     * @example
+     * <Panels.Panel id={panelIdRoot} as={Surface} border={false} elevation={0}>
+     *   <Surface.Header as={Panels.Header}>Root</Surface.Header>
+     *   <Surface.Body as={List}>
+     *     <ListItem>
+     *       <Panels.Trigger for={panelIdMoreInfo}>
+     *         <ListItem.Action>More details</ListItem.Action>
+     *       </Panels.Trigger>
+     *     </ListItem>
+     *   </Surface.Body>
+     * </Panels.Panel>
+     */
+    Panel: PolymorphicForwardRefComponent<"div", PanelProps>;
+    /**
+     * Wraps the clickable element and appends an `onClick` to change the active panel to the one specified in the `for`
+     * prop. Also appends some attributes for accessibility.
+     *
+     * @example
+     * <Panels.Trigger for={nextPanelId}>
+     *   <Button>go to next panel</Button>
+     * </Panels.Trigger>
+     *
+     * @example
+     * <ListItem>
+     *   <Panels.Trigger for={panelIdMoreInfo}>
+     *     <ListItem.Action>More details</ListItem.Action>
+     *   </Panels.Trigger>
+     * </ListItem>
+     */
+    Trigger: {
+        (props: PanelTriggerProps): string | number | true | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null;
+        displayName: string;
+    };
+    /**
+     * Required component to add an accessible name and also a back button (if previous panel exists) to the panel.
+     *
+     * @example
+     * <Panels.Panel id={panelIdRoot}>
+     *   <Panels.Header>Root</Panels.Header>
+     *   …
+     * </Panels.Panel>
+     *
+     * @example
+     * <Panels.Panel
+     *   id={panelIdMoreInfo}
+     *   as={Surface}
+     *   border={false}
+     *   elevation={0}
+     * >
+     *   <Surface.Header as={Panels.Header}>More details</Surface.Header>
+     *   <Surface.Body isPadded>
+     *     <Text>Content</Text>
+     *   </Surface.Body>
+     * </Panels.Panel>
+     */
+    Header: PolymorphicForwardRefComponent<"div", PanelHeaderProps>;
+    /**
+     * You can use methods from `Panels.useInstance()` to control the state programmatically.
+     *
+     * @example
+     * const panels = Panels.useInstance();
+     *
+     * <Button onClick={() => panels.goBack()}>Go back</Button>
+     * <Panels.Wrapper instance={panels}>{…}</Panels.Wrapper>;
+     */
+    useInstance: () => PanelsInstance;
+};
+export {};