@itwin/itwinui-react 3.15.4 → 3.16.0

package/cjs/utils/components/OverflowContainer.js

@@ -12,48 +12,191 @@ const _interop_require_default = require('@swc/helpers/_/_interop_require_defaul
 const _react = _interop_require_default._(require('react'));
 const _useMergedRefs = require('../hooks/useMergedRefs.js');
 const _Box = require('./Box.js');
-const _useOverflow = require('../hooks/useOverflow.js');
+const _useIsomorphicLayoutEffect = require('../hooks/useIsomorphicLayoutEffect.js');
 const _useSafeContext = require('../hooks/useSafeContext.js');
-const OverflowContainerComponent = _react.default.forwardRef((props, ref) => {
-  let { itemsCount, children, overflowOrientation, ...rest } = props;
-  let [containerRef, visibleCount] = (0, _useOverflow.useOverflow)(
-    itemsCount,
-    false,
-    overflowOrientation,
-  );
-  let overflowContainerContextValue = _react.default.useMemo(
-    () => ({
-      visibleCount,
+const _dev = require('../functions/dev.js');
+const _useResizeObserver = require('../hooks/useResizeObserver.js');
+const OverflowContainerMain = _react.default.forwardRef(
+  (props, forwardedRef) => {
+    let { itemsCount, children, overflowOrientation, ...rest } = props;
+    let [containerRef, visibleCount] = useOverflow(
       itemsCount,
-    }),
-    [itemsCount, visibleCount],
-  );
-  return _react.default.createElement(
-    OverflowContainerContext.Provider,
-    {
-      value: overflowContainerContextValue,
-    },
-    _react.default.createElement(
-      _Box.Box,
+      overflowOrientation,
+    );
+    let overflowContainerContextValue = _react.default.useMemo(
+      () => ({
+        visibleCount,
+        itemsCount,
+      }),
+      [itemsCount, visibleCount],
+    );
+    return _react.default.createElement(
+      OverflowContainerContext.Provider,
       {
-        ref: (0, _useMergedRefs.useMergedRefs)(ref, containerRef),
-        ...rest,
+        value: overflowContainerContextValue,
       },
-      children,
-    ),
-  );
-});
+      _react.default.createElement(
+        _Box.Box,
+        {
+          ref: (0, _useMergedRefs.useMergedRefs)(forwardedRef, containerRef),
+          ...rest,
+        },
+        children,
+      ),
+    );
+  },
+);
 const OverflowContainerOverflowNode = (props) => {
   let { children } = props;
   let { visibleCount, itemsCount } = useOverflowContainerContext();
   let isOverflowing = visibleCount < itemsCount;
   return isOverflowing ? children : null;
 };
+const OverflowContainerComponent = _react.default.forwardRef(
+  (props, forwardedRef) => {
+    let { itemsCount, overflowOrientation = 'horizontal', ...rest } = props;
+    let [size, setSize] = _react.default.useState(null);
+    let [resizeRef] = (0, _useResizeObserver.useResizeObserver)(setSize);
+    let ref = (0, _useMergedRefs.useMergedRefs)(resizeRef, forwardedRef);
+    let key = `${itemsCount}${
+      'vertical' === overflowOrientation ? size?.height : size?.width
+    }`;
+    return _react.default.createElement(OverflowContainerMain, {
+      ...rest,
+      key: key,
+      ref: ref,
+      itemsCount: itemsCount,
+      overflowOrientation: overflowOrientation,
+    });
+  },
+);
 const OverflowContainer = Object.assign(OverflowContainerComponent, {
   OverflowNode: OverflowContainerOverflowNode,
   useContext: useOverflowContainerContext,
 });
 const OverflowContainerContext = _react.default.createContext(void 0);
+const useOverflow = (itemsCount, orientation = 'horizontal') => {
+  let [guessState, dispatch] = _react.default.useReducer(
+    overflowGuessReducer,
+    {
+      itemsCount,
+    },
+    overflowGuessReducerInitialState,
+  );
+  let containerRef = _react.default.useRef(null);
+  let isGuessing = _react.default.useRef(false);
+  (0, _useIsomorphicLayoutEffect.useLayoutEffect)(() => {
+    let { minGuess, maxGuess, isStabilized, visibleCount } = guessState;
+    if (isStabilized) return;
+    guessVisibleCount();
+    function guessVisibleCount() {
+      if (isStabilized || isGuessing.current || _dev.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];
+};
+const STARTING_MAX_ITEMS_COUNT = 32;
+const overflowGuessReducerInitialState = ({ itemsCount }) => {
+  let initialVisibleCount = Math.min(itemsCount, STARTING_MAX_ITEMS_COUNT);
+  return _dev.isUnitTest
+    ? {
+        isStabilized: true,
+        minGuess: null,
+        maxGuess: null,
+        itemsCount,
+        visibleCount: itemsCount,
+      }
+    : {
+        isStabilized: false,
+        minGuess: 0,
+        maxGuess: initialVisibleCount,
+        itemsCount,
+        visibleCount: initialVisibleCount,
+      };
+};
+const 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 = (0, _useSafeContext.useSafeContext)(
     OverflowContainerContext,

package/cjs/utils/hooks/index.d.ts

@@ -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/cjs/utils/hooks/index.js

@@ -5,7 +5,6 @@ Object.defineProperty(exports, '__esModule', {
 const _export_star = require('@swc/helpers/_/_export_star');
 _export_star._(require('./useEventListener.js'), exports);
 _export_star._(require('./useMergedRefs.js'), exports);
-_export_star._(require('./useOverflow.js'), exports);
 _export_star._(require('./useResizeObserver.js'), exports);
 _export_star._(require('./useContainerWidth.js'), exports);
 _export_star._(require('./useGlobals.js'), exports);
@@ -19,4 +18,5 @@ _export_star._(require('./useId.js'), exports);
 _export_star._(require('./useControlledState.js'), exports);
 _export_star._(require('./useSyncExternalStore.js'), exports);
 _export_star._(require('./useVirtualScroll.js'), exports);
+_export_star._(require('./useInstance.js'), exports);
 _export_star._(require('./useWarningLogger.js'), exports);

package/cjs/utils/hooks/useInstance.d.ts

@@ -0,0 +1,22 @@
+declare class Instance {
+}
+export declare const useInstance: () => Instance;
+/**
+ * Synchronizes the instance with the provided properties.
+ *
+ * @param instance Instance created by `useInstance`.
+ * @param properties Memoized object containing properties to be synchronized.
+ *
+ * @example
+ * const instance = useInstance();
+ *
+ * const properties = React.useMemo(() => ({
+ *   show: () => console.log('show'),
+ * }), []);
+ *
+ * useSynchronizeInstance(instance, properties);
+ *
+ * instance.show(); // logs 'show'
+ */
+export declare const useSynchronizeInstance: <T>(instance: T, properties: T) => T;
+export {};

package/cjs/utils/hooks/useInstance.js

@@ -0,0 +1,38 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', {
+  value: true,
+});
+function _export(target, all) {
+  for (var name in all)
+    Object.defineProperty(target, name, {
+      enumerable: true,
+      get: all[name],
+    });
+}
+_export(exports, {
+  useInstance: function () {
+    return useInstance;
+  },
+  useSynchronizeInstance: function () {
+    return useSynchronizeInstance;
+  },
+});
+const _interop_require_wildcard = require('@swc/helpers/_/_interop_require_wildcard');
+const _react = _interop_require_wildcard._(require('react'));
+const _useSyncExternalStore = require('./useSyncExternalStore.js');
+class Instance {}
+const useInstance = () => _react.useMemo(() => new Instance(), []);
+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 (0, _useSyncExternalStore.useSyncExternalStore)(
+    synchronize,
+    () => instance,
+    () => instance,
+  );
+};

package/esm/core/Breadcrumbs/Breadcrumbs.js

@@ -8,7 +8,7 @@ import {
 } from '../../utils/index.js';
 import { Button } from '../Buttons/Button.js';
 import { Anchor } from '../Typography/Anchor.js';
-let BreadcrumbsComponent = React.forwardRef((props, ref) => {
+let BreadcrumbsComponent = React.forwardRef((props, forwardedRef) => {
   let {
     children: childrenProp,
     currentIndex = React.Children.count(childrenProp) - 1,
@@ -26,7 +26,7 @@ let BreadcrumbsComponent = React.forwardRef((props, ref) => {
     {
       as: 'nav',
       className: cx('iui-breadcrumbs', className),
-      ref: ref,
+      ref: forwardedRef,
       'aria-label': 'Breadcrumb',
       ...rest,
     },

package/esm/core/Checkbox/Checkbox.js

@@ -34,11 +34,11 @@ export 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,
@@ -57,15 +57,10 @@ export const Checkbox = React.forwardRef((props, ref) => {
         Box,
         {
           as: 'label',
-          className: cx(
-            'iui-checkbox-wrapper',
-            {
-              'iui-disabled': disabled,
-              [`iui-${status}`]: !!status,
-              'iui-loading': isLoading,
-            },
-            wrapperClassName,
-          ),
+          className: cx('iui-checkbox-wrapper', wrapperClassName),
+          'data-iui-disabled': disabled ? 'true' : void 0,
+          'data-iui-status': status,
+          'data-iui-loading': isLoading ? 'true' : void 0,
           ...restWrapperProps,
         },
         checkbox,

package/esm/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/esm/core/ComboBox/ComboBox.js

@@ -47,6 +47,7 @@ export 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);
@@ -200,7 +201,6 @@ export const ComboBox = React.forwardRef((props, forwardedRef) => {
         preventScroll: true,
       });
       if (optionsRef.current[__originalIndex]?.disabled) return;
-      setIsInputDirty(false);
       if (multiple) {
         let actionType = isMenuItemSelected(__originalIndex)
           ? 'removed'
@@ -218,7 +218,10 @@ export const ComboBox = React.forwardRef((props, forwardedRef) => {
             .filter(Boolean)
             .join(', '),
         );
-        setInputValue('');
+        if (clearFilterOnOptionToggle) {
+          setInputValue('');
+          setIsInputDirty(false);
+        }
       } else {
         setSelectedIndexes(__originalIndex);
         hide();
@@ -226,13 +229,14 @@ export const ComboBox = React.forwardRef((props, forwardedRef) => {
       }
     },
     [
-      selectedChangeHandler,
-      isMenuItemSelected,
+      optionsRef,
       multiple,
+      isMenuItemSelected,
+      selectedChangeHandler,
+      setSelectedIndexes,
       onChangeHandler,
-      optionsRef,
+      clearFilterOnOptionToggle,
       hide,
-      setSelectedIndexes,
     ],
   );
   let getMenuItem = React.useCallback(

package/esm/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/esm/core/DatePicker/DatePicker.js

@@ -8,6 +8,8 @@ import {
   isBefore,
   Box,
   useId,
+  useLayoutEffect,
+  useWarningLogger,
 } from '../../utils/index.js';
 import { IconButton } from '../Buttons/IconButton.js';
 import { TimePicker } from '../TimePicker/TimePicker.js';
@@ -135,6 +137,7 @@ export const DatePicker = React.forwardRef((props, forwardedRef) => {
     showDatesOutsideMonth = true,
     ...rest
   } = props;
+  let logWarning = useWarningLogger();
   let monthNames = localizedNames?.months ?? defaultMonths;
   let shortDays = localizedNames?.shortDays ?? defaultShortDays;
   let longDays = localizedNames?.days ?? defaultLongDays;
@@ -177,7 +180,7 @@ export const DatePicker = React.forwardRef((props, forwardedRef) => {
     );
   }, [date, setMonthAndYear, startDate, endDate, enableRangeSelect]);
   let popoverInitialFocusContext = React.useContext(PopoverInitialFocusContext);
-  React.useLayoutEffect(() => {
+  useLayoutEffect(() => {
     if (setFocus && popoverInitialFocusContext)
       popoverInitialFocusContext.setInitialFocus(-1);
   }, [popoverInitialFocusContext, setFocus]);

package/esm/core/Dialog/Dialog.js

@@ -11,7 +11,7 @@ import { Transition } from 'react-transition-group';
 let DialogComponent = React.forwardRef((props, ref) => {
   let {
     trapFocus = false,
-    setFocus = false,
+    setFocus = trapFocus,
     preventDocumentScroll = false,
     isOpen = false,
     isDismissible = true,

package/esm/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/esm/core/NonIdealState/NonIdealState.d.ts

@@ -2,7 +2,7 @@ import * as React from 'react';
 import type { PolymorphicForwardRefComponent } from '../../utils/index.js';
 type NonIdealStateProps = {
     /**
-     * An svg component, preferably from @itwin/itwinui-illustrations-react.
+     * An svg component, preferably from `@itwin/itwinui-illustrations-react`.
      *
      * @example
      * import { Svg404 } from '@itwin/itwinui-illustrations-react';
@@ -10,13 +10,17 @@ type NonIdealStateProps = {
      */
     svg: React.ReactNode;
     /**
-     * Primary heading for the error page
+     * Primary heading for the `NonIdealState`
      */
     heading?: React.ReactNode;
     /**
      * Secondary text to explain the error
      * Can include html in order to provide a hyperlink
-     * E.g. `Please visit <a href="https://www.bentley.com/help">our support page</a> for help.`
+     *
+     * @example
+     * <>
+     *   Please visit <Anchor href="https://www.bentley.com/help">our support page</Anchor> for help.
+     * </>
      */
     description?: React.ReactNode;
     /**
@@ -24,13 +28,13 @@ type NonIdealStateProps = {
      * Typically should be a primary and secondary button.
      *
      * @example
-     * <ErrorPage
-     *  actions={
-     *   <>
-     *    <Button styleType={'high-visibility'}>Retry</Button>
-     *    <Button>Contact us</Button>
-     *   </>
-     *  }
+     * <NonIdealState
+     *   actions={
+     *     <>
+     *       <Button styleType={'high-visibility'}>Retry</Button>
+     *       <Button>Contact us</Button>
+     *     </>
+     *   }
      * />
      */
     actions?: React.ReactNode;
@@ -53,7 +57,7 @@ type NonIdealStateProps = {
 };
 /**
  * A stylized display to communicate common http errors and other non-ideal states.
- * Works well with svgs from @itwin/itwinui-illustrations-react.
+ * Works well with svgs from `@itwin/itwinui-illustrations-react`.
  *
  * @example
  * <NonIdealState svg={<Svg404 />} heading='Not found' />