@carbon/react 1.103.0 → 1.104.0-rc.0

package/es/internal/keyboard/navigation.js

@@ -1,47 +1,41 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * Copyright IBM Corp. 2016, 2026
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
-import { ArrowRight, ArrowLeft } from './keys.js';
-import { match } from './match.js';
+import { ArrowLeft, ArrowRight } from "./keys.js";
+import { match } from "./match.js";
 
+//#region src/internal/keyboard/navigation.ts
 /**
- * A "ring buffer" function that takes an array and, depending on an ArrowRight
- * or ArrowLeft key input, loops from last index to first or first index to last.
- *
- * @param key - the left or right arrow key (KeyboardEvent, number, or string)
- * @param index - the current index in the array
- * @param arrayLength - the total length of the array
- *
- * @example
- *  getNextIndex(keyCodes.RIGHT, 0, 4)
- */
+* A "ring buffer" function that takes an array and, depending on an ArrowRight
+* or ArrowLeft key input, loops from last index to first or first index to last.
+*
+* @param key - the left or right arrow key (KeyboardEvent, number, or string)
+* @param index - the current index in the array
+* @param arrayLength - the total length of the array
+*
+* @example
+*  getNextIndex(keyCodes.RIGHT, 0, 4)
+*/
 const getNextIndex = (key, index, arrayLength) => {
-  if (match(key, ArrowRight)) {
-    return (index + 1) % arrayLength;
-  }
-  if (match(key, ArrowLeft)) {
-    return (index + arrayLength - 1) % arrayLength;
-  }
-  return;
+	if (match(key, ArrowRight)) return (index + 1) % arrayLength;
+	if (match(key, ArrowLeft)) return (index + arrayLength - 1) % arrayLength;
 };
-
 /**
- * CSS selector that selects major nodes that are sequentially focusable.
- */
+* CSS selector that selects major nodes that are sequentially focusable.
+*/
 const selectorTabbable = `
   a[href], area[href], input:not([disabled]):not([tabindex='-1']),
   button:not([disabled]):not([tabindex='-1']),select:not([disabled]):not([tabindex='-1']),
   textarea:not([disabled]):not([tabindex='-1']),
   iframe, object, embed, *[tabindex]:not([tabindex='-1']):not([disabled]), *[contenteditable=true]
 `;
-
 /**
- * CSS selector that selects major nodes that are click focusable.
- */
+* CSS selector that selects major nodes that are click focusable.
+*/
 const selectorFocusable = `
   a[href], area[href], input:not([disabled]),
   button:not([disabled]),select:not([disabled]),
@@ -49,4 +43,5 @@ const selectorFocusable = `
   iframe, object, embed, *[tabindex]:not([disabled]), *[contenteditable=true]
 `;
 
-export { getNextIndex, selectorFocusable, selectorTabbable };
+//#endregion
+export { getNextIndex, selectorFocusable, selectorTabbable };

package/es/internal/noopFn.js

@@ -1,10 +1,18 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * Copyright IBM Corp. 2016, 2026
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
+//#region src/internal/noopFn.ts
+/**
+* Copyright IBM Corp. 2016, 2023
+*
+* This source code is licensed under the Apache-2.0 license found in the
+* LICENSE file in the root directory of this source tree.
+*/
 const noopFn = () => {};
 
-export { noopFn };
+//#endregion
+export { noopFn };

package/es/internal/useAttachedMenu.js

@@ -1,63 +1,55 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * Copyright IBM Corp. 2016, 2026
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
-import { useState } from 'react';
+import { useState } from "react";
 
+//#region src/internal/useAttachedMenu.ts
 /**
- * Array of two numbers either representing [left, right] or [top, bottom].
- */
-
+* Copyright IBM Corp. 2023
+*
+* This source code is licensed under the Apache-2.0 license found in the
+* LICENSE file in the root directory of this source tree.
+*/
 /**
- * This hook contains common code to be used when a menu should be visually attached to an anchor based on a click event.
- *
- * @param {Element|object} anchor The element or ref the menu should visually be attached to.
- * @returns {useAttachedMenuReturn}
- */
+* This hook contains common code to be used when a menu should be visually attached to an anchor based on a click event.
+*
+* @param {Element|object} anchor The element or ref the menu should visually be attached to.
+* @returns {useAttachedMenuReturn}
+*/
 function useAttachedMenu(anchor) {
-  const [open, setOpen] = useState(false);
-  const [position, setPosition] = useState([[-1, -1], [-1, -1]]);
-  function openMenu() {
-    const anchorEl = anchor?.current || anchor;
-    if (anchorEl) {
-      const {
-        left,
-        top,
-        right,
-        bottom
-      } = anchorEl.getBoundingClientRect();
-      setPosition([[left, right], [top, bottom]]);
-    }
-    setOpen(true);
-  }
-  function closeMenu() {
-    setOpen(false);
-  }
-  function handleClick() {
-    if (open) {
-      closeMenu();
-    } else {
-      openMenu();
-    }
-  }
-  function handleMousedown(e) {
-    // prevent default for mousedown on trigger element to avoid
-    // the "blur" event from firing on the menu as this would close
-    // it and immediately re-open since "click" event is fired after
-    // "blur" event.
-    e.preventDefault();
-  }
-  return {
-    open,
-    x: position[0],
-    y: position[1],
-    handleClick,
-    handleMousedown,
-    handleClose: closeMenu
-  };
+	const [open, setOpen] = useState(false);
+	const [position, setPosition] = useState([[-1, -1], [-1, -1]]);
+	function openMenu() {
+		const anchorEl = anchor?.current || anchor;
+		if (anchorEl) {
+			const { left, top, right, bottom } = anchorEl.getBoundingClientRect();
+			setPosition([[left, right], [top, bottom]]);
+		}
+		setOpen(true);
+	}
+	function closeMenu() {
+		setOpen(false);
+	}
+	function handleClick() {
+		if (open) closeMenu();
+		else openMenu();
+	}
+	function handleMousedown(e) {
+		e.preventDefault();
+	}
+	return {
+		open,
+		x: position[0],
+		y: position[1],
+		handleClick,
+		handleMousedown,
+		handleClose: closeMenu
+	};
 }
 
-export { useAttachedMenu };
+//#endregion
+export { useAttachedMenu };

package/es/internal/useControllableState.js

@@ -1,58 +1,53 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * Copyright IBM Corp. 2016, 2026
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
-import { useState, useRef, useEffect } from 'react';
-import { warning } from './warning.js';
+import { warning } from "./warning.js";
+import { useEffect, useRef, useState } from "react";
 
+//#region src/internal/useControllableState.ts
 /**
- * This hook simplifies the behavior of a component that has state which can be
- * both controlled and uncontrolled. It works like `useState`. You can use the
- * `onChange` callback to communicate state updates to parent components.
- *
- * Note: This hook will warn if the component switches between controlled and
- * uncontrolled states.
- */
-const useControllableState = ({
-  defaultValue,
-  name = 'custom',
-  onChange,
-  value
-}) => {
-  const [state, internalSetState] = useState(typeof value !== 'undefined' ? value : defaultValue);
-  const controlled = useRef(null);
-  if (controlled.current === null) {
-    controlled.current = typeof value !== 'undefined';
-  }
-  const setState = stateOrUpdater => {
-    const newValue = typeof stateOrUpdater === 'function' ? stateOrUpdater(state) : stateOrUpdater;
-    if (controlled.current === false) {
-      internalSetState(newValue);
-    }
-    if (onChange) {
-      onChange(newValue);
-    }
-  };
-  useEffect(() => {
-    const controlledValue = typeof value !== 'undefined';
-
-    // Uncontrolled -> Controlled
-    if (controlled.current === false && controlledValue) {
-      process.env.NODE_ENV !== "production" ? warning(false, `A component is changing an uncontrolled ${name} component to be controlled. ` + 'This is likely caused by the value changing to a defined value ' + 'from undefined. Decide between using a controlled or uncontrolled ' + 'value for the lifetime of the component. ' + 'More info: https://reactjs.org/link/controlled-components') : void 0;
-    }
-
-    // Controlled -> Uncontrolled
-    if (controlled.current === true && !controlledValue) {
-      process.env.NODE_ENV !== "production" ? warning(false, `A component is changing a controlled ${name} component to be uncontrolled. ` + 'This is likely caused by the value changing to an undefined value ' + 'from a defined one. Decide between using a controlled or ' + 'uncontrolled value for the lifetime of the component. ' + 'More info: https://reactjs.org/link/controlled-components') : void 0;
-    }
-  }, [name, value]);
-  if (controlled.current === true) {
-    return [value, setState, controlled.current];
-  }
-  return [state, setState, controlled.current];
+* Copyright IBM Corp. 2016, 2025
+*
+* This source code is licensed under the Apache-2.0 license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+/**
+* This hook simplifies the behavior of a component that has state which can be
+* both controlled and uncontrolled. It works like `useState`. You can use the
+* `onChange` callback to communicate state updates to parent components.
+*
+* Note: This hook will warn if the component switches between controlled and
+* uncontrolled states.
+*/
+const useControllableState = ({ defaultValue, name = "custom", onChange, value }) => {
+	const [state, internalSetState] = useState(typeof value !== "undefined" ? value : defaultValue);
+	const controlled = useRef(null);
+	if (controlled.current === null) controlled.current = typeof value !== "undefined";
+	const setState = (stateOrUpdater) => {
+		const newValue = typeof stateOrUpdater === "function" ? stateOrUpdater(state) : stateOrUpdater;
+		if (controlled.current === false) internalSetState(newValue);
+		if (onChange) onChange(newValue);
+	};
+	useEffect(() => {
+		const controlledValue = typeof value !== "undefined";
+		if (controlled.current === false && controlledValue) warning(false, `A component is changing an uncontrolled ${name} component to be controlled. This is likely caused by the value changing to a defined value from undefined. Decide between using a controlled or uncontrolled value for the lifetime of the component. More info: https://reactjs.org/link/controlled-components`);
+		if (controlled.current === true && !controlledValue) warning(false, `A component is changing a controlled ${name} component to be uncontrolled. This is likely caused by the value changing to an undefined value from a defined one. Decide between using a controlled or uncontrolled value for the lifetime of the component. More info: https://reactjs.org/link/controlled-components`);
+	}, [name, value]);
+	if (controlled.current === true) return [
+		value,
+		setState,
+		controlled.current
+	];
+	return [
+		state,
+		setState,
+		controlled.current
+	];
 };
 
-export { useControllableState };
+//#endregion
+export { useControllableState };

package/es/internal/useDelayedState.js

@@ -1,46 +1,41 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * Copyright IBM Corp. 2016, 2026
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
-import { useState, useRef, useCallback, useEffect } from 'react';
+import { useCallback, useEffect, useRef, useState } from "react";
 
+//#region src/internal/useDelayedState.ts
 /**
- * `useDelayedState` mirrors `useState` but also allows you to add a delay to
- * when your state updates. You can provide a second argument to `setState`,
- * `delayMs`, which will be the time in milliseconds after which the state is
- * updated.
- *
- * This hook will clean up pending timers in `useEffect` and will cancel any
- * pending timers when a `setState` is called before the state is updated from
- * a previous call
- */
-
+* Copyright IBM Corp. 2016, 2023
+*
+* This source code is licensed under the Apache-2.0 license found in the
+* LICENSE file in the root directory of this source tree.
+*/
 function useDelayedState(initialState) {
-  const [state, setState] = useState(initialState);
-  const timeoutId = useRef(null);
-  // We use `useCallback` to match the signature of React's `useState` which will
-  // always return the same reference for the `setState` updater
-  const setStateWithDelay = useCallback((stateToSet, delayMs = 0) => {
-    window.clearTimeout(timeoutId.current ?? undefined);
-    timeoutId.current = null;
-    if (delayMs === 0) {
-      setState(stateToSet);
-      return;
-    }
-    timeoutId.current = window.setTimeout(() => {
-      setState(stateToSet);
-      timeoutId.current = null;
-    }, delayMs);
-  }, []);
-  useEffect(() => {
-    return () => {
-      window.clearTimeout(timeoutId.current ?? undefined);
-    };
-  }, []);
-  return [state, setStateWithDelay];
+	const [state, setState] = useState(initialState);
+	const timeoutId = useRef(null);
+	const setStateWithDelay = useCallback((stateToSet, delayMs = 0) => {
+		window.clearTimeout(timeoutId.current ?? void 0);
+		timeoutId.current = null;
+		if (delayMs === 0) {
+			setState(stateToSet);
+			return;
+		}
+		timeoutId.current = window.setTimeout(() => {
+			setState(stateToSet);
+			timeoutId.current = null;
+		}, delayMs);
+	}, []);
+	useEffect(() => {
+		return () => {
+			window.clearTimeout(timeoutId.current ?? void 0);
+		};
+	}, []);
+	return [state, setStateWithDelay];
 }
 
-export { useDelayedState };
+//#endregion
+export { useDelayedState };

package/es/internal/useEvent.js

@@ -1,47 +1,51 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * Copyright IBM Corp. 2016, 2026
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
-import { useRef, useEffect } from 'react';
+import { useEffect, useRef } from "react";
 
+//#region src/internal/useEvent.ts
+/**
+* Copyright IBM Corp. 2016, 2025
+*
+* This source code is licensed under the Apache-2.0 license found in the
+* LICENSE file in the root directory of this source tree.
+*/
 const useEvent = (elementOrRef, eventName, callback) => {
-  const savedCallback = useRef(null);
-  useEffect(() => {
-    savedCallback.current = callback;
-  }, [callback]);
-  useEffect(() => {
-    const element = 'current' in elementOrRef ? elementOrRef.current : elementOrRef;
-    if (!element) return;
-    const handler = event => {
-      if (savedCallback.current) {
-        savedCallback.current(event);
-      }
-    };
-    element.addEventListener(eventName, handler);
-    return () => {
-      element.removeEventListener(eventName, handler);
-    };
-  }, [elementOrRef, eventName]);
+	const savedCallback = useRef(null);
+	useEffect(() => {
+		savedCallback.current = callback;
+	}, [callback]);
+	useEffect(() => {
+		const element = "current" in elementOrRef ? elementOrRef.current : elementOrRef;
+		if (!element) return;
+		const handler = (event) => {
+			if (savedCallback.current) savedCallback.current(event);
+		};
+		element.addEventListener(eventName, handler);
+		return () => {
+			element.removeEventListener(eventName, handler);
+		};
+	}, [elementOrRef, eventName]);
 };
 const useWindowEvent = (eventName, callback) => {
-  const savedCallback = useRef(null);
-  useEffect(() => {
-    savedCallback.current = callback;
-  }, [callback]);
-  useEffect(() => {
-    const handler = event => {
-      if (savedCallback.current) {
-        savedCallback.current(event);
-      }
-    };
-    window.addEventListener(eventName, handler);
-    return () => {
-      window.removeEventListener(eventName, handler);
-    };
-  }, [eventName]);
+	const savedCallback = useRef(null);
+	useEffect(() => {
+		savedCallback.current = callback;
+	}, [callback]);
+	useEffect(() => {
+		const handler = (event) => {
+			if (savedCallback.current) savedCallback.current(event);
+		};
+		window.addEventListener(eventName, handler);
+		return () => {
+			window.removeEventListener(eventName, handler);
+		};
+	}, [eventName]);
 };
 
-export { useEvent, useWindowEvent };
+//#endregion
+export { useEvent, useWindowEvent };

package/es/internal/useId.js

@@ -1,108 +1,72 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * Copyright IBM Corp. 2016, 2026
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, { useState, useEffect } from 'react';
-import { setupGetInstanceId } from '../tools/setupGetInstanceId.js';
-import useIsomorphicEffect from './useIsomorphicEffect.js';
-import { useIdPrefix } from './useIdPrefix.js';
+import { setupGetInstanceId } from "../tools/setupGetInstanceId.js";
+import useIsomorphicEffect from "./useIsomorphicEffect.js";
+import { useIdPrefix } from "./useIdPrefix.js";
+import React, { useEffect, useState } from "react";
 
-// This file was heavily inspired by:
-//
-// 1. Reach UI and their work on their auto-id package:
-//    https://github.com/reach/reach-ui/blob/86a046f54d53b6420e392b3fa56dd991d9d4e458/packages/auto-id/src/index.ts
-//
-// 2. Floating UI and their work on react >=18 compatibility
-//    https://github.com/floating-ui/floating-ui/blob/%40floating-ui/utils%400.2.5/packages/react/src/hooks/useId.ts
-//
-// The problem that this solves is an id mismatch when auto-generating
-// ids on both the server and the client. When using server-side rendering,
-// there can be the chance of a mismatch between what the server renders and
-// what the client renders when the id value is auto-generated.
-//
-// To get around this, we set the initial value of the `id` to `null` and then
-// conditionally use `useLayoutEffect` on the client and `useEffect` on the
-// server. On the client, `useLayoutEffect` will patch up the id to the correct
-// value. On the server, `useEffect` will not run.
-//
-// This ensures that we won't encounter a mismatch in ids between server and
-// client, at the cost of runtime patching of the id value in
-// `useLayoutEffect`
-//
-// React 18 introduced a new hook called `useId` that takes care of hydration
-// mismatches. If the user is running React 18 or higher, the native hook is
-// used via the `useReactId` function. If the user is running React 17 or
-// lower, `useCompatibleId` is used.
-
-
-// This tricks bundlers so they can't statically analyze this and produce
-// compilation warnings/errors.
-// https://github.com/webpack/webpack/issues/14814
-// https://github.com/mui/material-ui/issues/41190
-const _React = {
-  ...React
-};
+//#region src/internal/useId.js
+/**
+* Copyright IBM Corp. 2016, 2026
+*
+* This source code is licensed under the Apache-2.0 license found in the
+* LICENSE file in the root directory of this source tree.
+*/
+const _React = { ...React };
 const instanceId = setupGetInstanceId();
 let serverHandoffCompleted = false;
-const defaultId = 'id';
-
+const defaultId = "id";
 /**
- * Generate a unique ID for React <=17 with an optional prefix prepended to it.
- * This is an internal utility, not intended for public usage.
- * @param {string} [prefix]
- * @returns {string}
- */
+* Generate a unique ID for React <=17 with an optional prefix prepended to it.
+* This is an internal utility, not intended for public usage.
+* @param {string} [prefix]
+* @returns {string}
+*/
 function useCompatibleId(prefix = defaultId) {
-  const contextPrefix = useIdPrefix();
-  const [id, setId] = useState(() => {
-    if (serverHandoffCompleted) {
-      return `${contextPrefix ? `${contextPrefix}-` : ``}${prefix}-${instanceId()}`;
-    }
-    return null;
-  });
-  useIsomorphicEffect(() => {
-    if (id === null) {
-      setId(`${contextPrefix ? `${contextPrefix}-` : ``}${prefix}-${instanceId()}`);
-    }
-  }, [instanceId]);
-  useEffect(() => {
-    if (serverHandoffCompleted === false) {
-      serverHandoffCompleted = true;
-    }
-  }, []);
-  return id;
+	const contextPrefix = useIdPrefix();
+	const [id, setId] = useState(() => {
+		if (serverHandoffCompleted) return `${contextPrefix ? `${contextPrefix}-` : ``}${prefix}-${instanceId()}`;
+		return null;
+	});
+	useIsomorphicEffect(() => {
+		if (id === null) setId(`${contextPrefix ? `${contextPrefix}-` : ``}${prefix}-${instanceId()}`);
+	}, [instanceId]);
+	useEffect(() => {
+		if (serverHandoffCompleted === false) serverHandoffCompleted = true;
+	}, []);
+	return id;
 }
-
 /**
- * Generate a unique ID for React >=18 with an optional prefix prepended to it.
- * This is an internal utility, not intended for public usage.
- * @param {string} [prefix]
- * @returns {string}
- */
+* Generate a unique ID for React >=18 with an optional prefix prepended to it.
+* This is an internal utility, not intended for public usage.
+* @param {string} [prefix]
+* @returns {string}
+*/
 function useReactId(prefix = defaultId) {
-  const contextPrefix = useIdPrefix();
-  return `${contextPrefix ? `${contextPrefix}-` : ``}${prefix}-${_React.useId()}`;
+	const contextPrefix = useIdPrefix();
+	return `${contextPrefix ? `${contextPrefix}-` : ``}${prefix}-${_React.useId()}`;
 }
-
 /**
- * Uses React 18's built-in `useId()` when available, or falls back to a
- * slightly less performant (requiring a double render) implementation for
- * earlier React versions.
- */
+* Uses React 18's built-in `useId()` when available, or falls back to a
+* slightly less performant (requiring a double render) implementation for
+* earlier React versions.
+*/
 const useId = _React.useId ? useReactId : useCompatibleId;
-
 /**
- * Generate a unique id if a given `id` is not provided
- * This is an internal utility, not intended for public usage.
- * @param {string|undefined} id
- * @returns {string}
- */
+* Generate a unique id if a given `id` is not provided
+* This is an internal utility, not intended for public usage.
+* @param {string|undefined} id
+* @returns {string}
+*/
 function useFallbackId(id) {
-  const fallback = useId();
-  return id ?? fallback;
+	const fallback = useId();
+	return id ?? fallback;
 }
 
-export { useCompatibleId, useFallbackId, useId };
+//#endregion
+export { useFallbackId, useId };