@itwin/itwinui-react 3.11.2 → 3.12.0

package/esm/utils/components/index.js

@@ -1,7 +1,3 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
 export * from './Resizer.js';
 export * from './FocusTrap.js';
 export * from './InputContainer.js';

package/esm/utils/functions/colors.d.ts

@@ -12,7 +12,7 @@ export declare const SoftBackgrounds: {
     readonly oak: "var(--iui-color-background-oak)";
 };
 /** Returns true if a string value is one of the SoftBackgrounds keys */
-export declare const isSoftBackground: (value: string) => value is "skyblue" | "celery" | "froly" | "steelblue" | "sunglow" | "seabuckthorn" | "montecarlo" | "poloblue" | "bouquet" | "ash" | "oak";
+export declare const isSoftBackground: (value: string) => value is keyof typeof SoftBackgrounds;
 /**
  * Generate color from user name or email.
  * Recommended to use for `backgroundColor` in `Avatar` component.

package/esm/utils/functions/colors.js

@@ -1,35 +1,26 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
 export const SoftBackgrounds = {
-    skyblue: 'var(--iui-color-background-skyblue)',
-    celery: 'var(--iui-color-background-celery)',
-    froly: 'var(--iui-color-background-froly)',
-    steelblue: 'var(--iui-color-background-steelblue)',
-    sunglow: 'var(--iui-color-background-sunglow)',
-    seabuckthorn: 'var(--iui-color-background-seabuckthorn)',
-    montecarlo: 'var(--iui-color-background-montecarlo)',
-    poloblue: 'var(--iui-color-background-poloblue)',
-    bouquet: 'var(--iui-color-background-bouquet)',
-    ash: 'var(--iui-color-background-ash)',
-    oak: 'var(--iui-color-background-oak)',
+  skyblue: 'var(--iui-color-background-skyblue)',
+  celery: 'var(--iui-color-background-celery)',
+  froly: 'var(--iui-color-background-froly)',
+  steelblue: 'var(--iui-color-background-steelblue)',
+  sunglow: 'var(--iui-color-background-sunglow)',
+  seabuckthorn: 'var(--iui-color-background-seabuckthorn)',
+  montecarlo: 'var(--iui-color-background-montecarlo)',
+  poloblue: 'var(--iui-color-background-poloblue)',
+  bouquet: 'var(--iui-color-background-bouquet)',
+  ash: 'var(--iui-color-background-ash)',
+  oak: 'var(--iui-color-background-oak)',
 };
-/** Returns true if a string value is one of the SoftBackgrounds keys */
 export const isSoftBackground = (value) => {
-    return Object.keys(SoftBackgrounds).includes(value);
+  return Object.keys(SoftBackgrounds).includes(value);
 };
 const USER_COLORS = Object.values(SoftBackgrounds);
-/**
- * Generate color from user name or email.
- * Recommended to use for `backgroundColor` in `Avatar` component.
- */
 export const getUserColor = (emailOrName) => {
-    const normalizedString = emailOrName.trim().toLowerCase();
-    let hash = 0;
-    for (let i = 0; i < normalizedString.length; i++) {
-        const charCode = normalizedString.charCodeAt(i);
-        hash = (hash + charCode) % USER_COLORS.length;
-    }
-    return USER_COLORS[hash];
+  const normalizedString = emailOrName.trim().toLowerCase();
+  let hash = 0;
+  for (let i = 0; i < normalizedString.length; i++) {
+    const charCode = normalizedString.charCodeAt(i);
+    hash = (hash + charCode) % USER_COLORS.length;
+  }
+  return USER_COLORS[hash];
 };

package/esm/utils/functions/date.js

@@ -1,17 +1,10 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
-/**
- * Return true if the first date is earlier than the second date
- */
 export const isBefore = (beforeDate, afterDate) => {
-    if (!beforeDate || !afterDate) {
-        return false;
-    }
-    const firstDate = new Date(beforeDate);
-    const secondDate = new Date(afterDate);
-    firstDate && firstDate.setHours(0, 0, 0, 0);
-    secondDate && secondDate.setHours(0, 0, 0, 0);
-    return firstDate < secondDate;
+  if (!beforeDate || !afterDate) {
+    return false;
+  }
+  const firstDate = new Date(beforeDate);
+  const secondDate = new Date(afterDate);
+  firstDate && firstDate.setHours(0, 0, 0, 0);
+  secondDate && secondDate.setHours(0, 0, 0, 0);
+  return firstDate < secondDate;
 };

package/esm/utils/functions/dev.js

@@ -1,36 +1,23 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
-// @ts-expect-error -- jest is not used in iTwinUI but may be used in consuming apps
 const isJest = typeof jest !== 'undefined';
-const isMocha = typeof globalThis.beforeEach !== 'undefined' &&
-    `${globalThis.beforeEach}`.replace(/\s/g, '') ===
-        'function(name,fn){suites[0].beforeEach(name,fn);}';
+const isMocha =
+  typeof globalThis.beforeEach !== 'undefined' &&
+  `${globalThis.beforeEach}`.replace(/\s/g, '') ===
+    'function(name,fn){suites[0].beforeEach(name,fn);}';
 const isVitest = typeof globalThis.__vitest_index__ !== 'undefined';
 const isUnitTest = isJest || isVitest || isMocha;
 let isDev = false;
-// wrapping in try-catch because process might be undefined
 try {
-    isDev = process.env.NODE_ENV !== 'production' && !isUnitTest;
-}
-catch { }
-/**
- * Logs message one time only in dev environments.
- *
- * @example
- * const logWarningInDev = createWarningLogger();
- * logWarningInDev("please don't use this")
- */
+  isDev = process.env.NODE_ENV !== 'production' && !isUnitTest;
+} catch {}
 const createWarningLogger = !isDev
-    ? () => () => { }
-    : () => {
-        let logged = false;
-        return (message) => {
-            if (!logged) {
-                console.warn(message);
-                logged = true;
-            }
-        };
+  ? () => () => {}
+  : () => {
+      let logged = false;
+      return (message) => {
+        if (!logged) {
+          console.warn(message);
+          logged = true;
+        }
+      };
     };
 export { isUnitTest, isDev, createWarningLogger };

package/esm/utils/functions/dom.d.ts

@@ -12,7 +12,7 @@ export declare const getWindow: () => (Window & typeof globalThis) | undefined;
  * Merges multiple event handlers into one, while making sure that
  * `defaultPrevented` is respected for each callback.
  */
-export declare const mergeEventHandlers: <E extends import("react").SyntheticEvent<Element, Event>>(...callbacks: (((event: E) => void) | undefined)[]) => (event: E) => void;
+export declare const mergeEventHandlers: <E extends React.SyntheticEvent>(...callbacks: Array<((event: E) => void) | undefined>) => (event: E) => void;
 /**
  * Returns translate values as an array of a given element.
  * @param element HTML element you want to get translate value of

package/esm/utils/functions/dom.js

@@ -1,46 +1,28 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
-/**
- * Get document if it is defined.
- * Used to support SSR/SSG applications.
- */
 export const getDocument = () => {
-    return typeof document === 'undefined' ? undefined : document;
+  return typeof document === 'undefined' ? undefined : document;
 };
-/**
- * Get window if it is defined.
- * Used to support SSR/SSG applications.
- */
 export const getWindow = () => {
-    return typeof window === 'undefined' ? undefined : window;
+  return typeof window === 'undefined' ? undefined : window;
 };
-/**
- * Merges multiple event handlers into one, while making sure that
- * `defaultPrevented` is respected for each callback.
- */
-export const mergeEventHandlers = (...callbacks) => (event) => {
+export const mergeEventHandlers =
+  (...callbacks) =>
+  (event) => {
     for (const cb of callbacks) {
-        cb?.(event);
-        if (event?.defaultPrevented) {
-            return;
-        }
+      cb?.(event);
+      if (event?.defaultPrevented) {
+        return;
+      }
     }
-};
-/**
- * Returns translate values as an array of a given element.
- * @param element HTML element you want to get translate value of
- * @returns Translate values in pixels in an array `[translateX, translateY]`
- */
+  };
 export const getTranslateValuesFromElement = (element) => {
-    if (!element) {
-        return [];
-    }
-    const transformValue = getComputedStyle(element).getPropertyValue('transform');
-    return getTranslateValues(transformValue);
+  if (!element) {
+    return [];
+  }
+  const transformValue =
+    getComputedStyle(element).getPropertyValue('transform');
+  return getTranslateValues(transformValue);
 };
 export const getTranslateValues = (transformValue) => {
-    const matrix = new DOMMatrix(transformValue);
-    return [matrix.m41, matrix.m42];
+  const matrix = new DOMMatrix(transformValue);
+  return [matrix.m41, matrix.m42];
 };

package/esm/utils/functions/focusable.d.ts

@@ -1,3 +1,4 @@
+import * as React from 'react';
 /**
  * Return array of tabbable elements in the container.
  */
@@ -6,3 +7,25 @@ export declare const getTabbableElements: (container: HTMLElement | undefined |
  * Return array of focusable elements in the container.
  */
 export declare const getFocusableElements: (container: HTMLElement | undefined | null) => Element[];
+/**
+ * Returns the latest focusable elements in the `root` element.
+ * This is returned as a ref and a state. Choose which one to use according to the use case. E.g.:
+ * - ref: since FloatingUI needs a ref ([`listRef`](https://floating-ui.com/docs/useListNavigation#listref)).
+ * - state: when reading this value in a render.
+ *
+ * Pass `extraOptions.filter` to filter the elements.
+ *
+ * @example
+ * const {focusableElementsRef, focusableElements} = useFocusableElements(root, {
+ *   // Filter out focusable elements that are inside other focusable elements.
+ *   filter: (allElements) => allElements.filter(
+ *     (i) => !allElements?.some((p) => p.contains(i.parentElement)),
+ *   ),
+ * });
+ */
+export declare function useFocusableElements(root: HTMLElement | null, extraOptions?: {
+    filter?: (elements: HTMLElement[]) => HTMLElement[];
+}): {
+    focusableElementsRef: React.MutableRefObject<HTMLElement[]>;
+    focusableElements: HTMLElement[];
+};

package/esm/utils/functions/focusable.js

@@ -1,29 +1,72 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
-const tabbableElementsSelector = 'a[href], button, input, textarea, select, details, audio[controls], video[controls], [contenteditable]:not([contenteditable="false"]), [tabindex]:not([tabindex="-1"])';
-/**
- * Return array of tabbable elements in the container.
- */
+import * as React from 'react';
+import { useSyncExternalStore, useLatestRef } from '../hooks/index.js';
+const tabbableElementsSelector =
+  'a[href], button, input, textarea, select, details, audio[controls], video[controls], [contenteditable]:not([contenteditable="false"]), [tabindex]:not([tabindex="-1"])';
 export const getTabbableElements = (container) => {
-    if (!container) {
-        return [];
-    }
-    const elements = container.querySelectorAll(tabbableElementsSelector);
-    return Array.from(elements).filter((el) => !el.hasAttribute('disabled') &&
-        !el.classList.contains('iui-disabled') &&
-        el.getAttribute('aria-disabled') !== 'true');
+  if (!container) {
+    return [];
+  }
+  const elements = container.querySelectorAll(tabbableElementsSelector);
+  return Array.from(elements).filter(
+    (el) =>
+      !el.hasAttribute('disabled') &&
+      !el.classList.contains('iui-disabled') &&
+      el.getAttribute('aria-disabled') !== 'true',
+  );
 };
-/**
- * Return array of focusable elements in the container.
- */
 export const getFocusableElements = (container) => {
-    if (!container) {
-        return [];
-    }
-    const elements = container.querySelectorAll(`${tabbableElementsSelector}, [tabindex="-1"]`);
-    return Array.from(elements).filter((el) => !el.hasAttribute('disabled') &&
-        !el.classList.contains('iui-disabled') &&
-        el.getAttribute('aria-disabled') !== 'true');
+  if (!container) {
+    return [];
+  }
+  const elements = container.querySelectorAll(
+    `${tabbableElementsSelector}, [tabindex="-1"]`,
+  );
+  return Array.from(elements).filter(
+    (el) =>
+      !el.hasAttribute('disabled') &&
+      !el.classList.contains('iui-disabled') &&
+      el.getAttribute('aria-disabled') !== 'true',
+  );
 };
+export function useFocusableElements(root, extraOptions) {
+  const focusableElementsRef = React.useRef([]);
+  const [focusableElements, setFocusableElements] = React.useState(
+    focusableElementsRef.current,
+  );
+  const setFocusableElementsRefAndState = (newFocusableElements) => {
+    focusableElementsRef.current = newFocusableElements;
+    setFocusableElements(newFocusableElements);
+  };
+  const { filter: filterProp } = extraOptions ?? {};
+  const filter = useLatestRef(filterProp);
+  const returnValue = React.useMemo(() => {
+    return {
+      focusableElementsRef,
+      focusableElements,
+    };
+  }, [focusableElementsRef, focusableElements]);
+  return useSyncExternalStore(
+    React.useCallback(() => {
+      if (!root) {
+        setFocusableElementsRefAndState([]);
+        return () => {};
+      }
+      updateFocusableElements();
+      const observer = new MutationObserver(() => updateFocusableElements());
+      observer.observe(root, {
+        childList: true,
+        subtree: true,
+      });
+      return () => observer.disconnect();
+      function updateFocusableElements() {
+        let newFocusableElements = getFocusableElements(root);
+        if (filter.current) {
+          newFocusableElements = filter.current?.(newFocusableElements);
+        }
+        setFocusableElementsRefAndState(newFocusableElements);
+      }
+    }, [root, filter]),
+    () => returnValue,
+    () => returnValue,
+  );
+}

package/esm/utils/functions/import.js

@@ -1,32 +1,23 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
-/**
- * Wrapper around native CSS module scripts (import attributes) for dynamic imports.
- * In unsupported browsers, it gracefully degrades to import assertions, and then `fetch`.
- *
- * Returns a constructable CSSStyleSheet object that can be adopted.
- *
- * @see https://web.dev/articles/css-module-scripts
- * @see https://github.com/tc39/proposal-import-attributes
- */
 export const importCss = async (url) => {
+  try {
+    return await new Function(
+      `return import("${url}", { with: { type: "css" } })`,
+    )();
+  } catch {
     try {
-        return await new Function(`return import("${url}", { with: { type: "css" } })`)();
-    }
-    catch {
-        try {
-            return await new Function(`return import("${url}", { assert: { type: "css" } })`)();
-        }
-        catch {
-            return await fetch(url)
-                .then((res) => res.text())
-                .then((cssText) => {
-                const stylesheet = new CSSStyleSheet();
-                stylesheet.replaceSync(cssText);
-                return { default: stylesheet };
-            });
-        }
+      return await new Function(
+        `return import("${url}", { assert: { type: "css" } })`,
+      )();
+    } catch {
+      return await fetch(url)
+        .then((res) => res.text())
+        .then((cssText) => {
+          const stylesheet = new CSSStyleSheet();
+          stylesheet.replaceSync(cssText);
+          return {
+            default: stylesheet,
+          };
+        });
     }
+  }
 };

package/esm/utils/functions/index.js

@@ -1,7 +1,3 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
 export * from './date.js';
 export * from './dom.js';
 export * from './colors.js';

package/esm/utils/functions/numbers.js

@@ -1,31 +1,15 @@
-/*---------------------------------------------------------------------------------------------
- * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
- * See LICENSE.md in the project root for license terms and full copyright notice.
- *--------------------------------------------------------------------------------------------*/
-/**
- * Return input value bounded by specified range.
- */
 export const getBoundedValue = (val, min, max) => {
-    return Math.min(max, Math.max(min, val));
+  return Math.min(max, Math.max(min, val));
 };
-/**
- * Returns a random value of a given length containing `A-Za-z0-9_-` symbols.
- */
 export const getRandomValue = (length = 21) => {
-    const alphabet = `_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ`;
-    let id = '';
-    for (let i = 0; i < length; i++) {
-        id += alphabet[(Math.random() * 64) | 0];
-    }
-    return id;
+  const alphabet = `_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ`;
+  let id = '';
+  for (let i = 0; i < length; i++) {
+    id += alphabet[(Math.random() * 64) | 0];
+  }
+  return id;
 };
-/**
- * Rounds a pixel value based on the device's pixel ratio. This ensures that values can be
- * placed evenly on the device’s pixel grid, avoiding any blurring.
- *
- * @see https://floating-ui.com/docs/misc#subpixel-and-accelerated-positioning
- */
 export const roundByDPR = (value) => {
-    const dpr = window.devicePixelRatio || 1;
-    return Math.round(value * dpr) / dpr;
+  const dpr = window.devicePixelRatio || 1;
+  return Math.round(value * dpr) / dpr;
 };