@carbon/react 1.78.2 → 1.79.0-rc.0

package/es/internal/OptimizedResize.js

@@ -8,44 +8,42 @@
 import window from 'window-or-global';
 
 // mdn resize function
-const OptimizedResize = function optimizedResize() {
+
+/**
+ * A callback function to be executed on `resize`.
+ */
+
+const OptimizedResize = (() => {
   const callbacks = [];
   let running = false;
-
-  // run the actual callbacks
-  function runCallbacks() {
+  const runCallbacks = () => {
     callbacks.forEach(callback => {
       callback();
     });
     running = false;
-  }
-
-  // fired on resize event
-  function resize() {
+  };
+  const handleResize = () => {
     if (!running) {
       running = true;
       window.requestAnimationFrame(runCallbacks);
     }
-  }
-
-  // adds callback to loop
-  function addCallback(callback) {
-    if (callback) {
-      const index = callbacks.indexOf(callback);
-      if (index < 0) {
-        callbacks.push(callback);
-      }
+  };
+  const addCallback = callback => {
+    const index = callbacks.indexOf(callback);
+    if (index < 0) {
+      callbacks.push(callback);
     }
-  }
+  };
   return {
-    // public method to add additional callback
+    /** Adds a callback function to be executed on window `resize`. */
     add: callback => {
       if (!callbacks.length) {
-        window.addEventListener('resize', resize);
+        window.addEventListener('resize', handleResize);
       }
       addCallback(callback);
       return {
-        release() {
+        /** Removes the callback. */
+        remove: () => {
           const index = callbacks.indexOf(callback);
           if (index >= 0) {
             callbacks.splice(index, 1);
@@ -54,7 +52,6 @@ const OptimizedResize = function optimizedResize() {
       };
     }
   };
-}();
-var OptimizedResize$1 = OptimizedResize;
+})();
 
-export { OptimizedResize$1 as default };
+export { OptimizedResize };

package/es/internal/createClassWrapper.d.ts

@@ -1,12 +1,12 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * 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.
  */
-import { ComponentClass, FunctionComponent } from 'react';
+import { type ComponentClass, type ForwardRefExoticComponent, type FunctionComponent, type PropsWithChildren } from 'react';
 /**
  * Wrap a class component with a functional component. This prevents an end-user
  * from being able to pass `ref` and access the underlying class instance.
  */
-export declare function createClassWrapper<Props>(Component: ComponentClass<Props>): FunctionComponent<Props>;
+export declare const createClassWrapper: <Props extends PropsWithChildren>(Component: ComponentClass<Props> | ForwardRefExoticComponent<Props>) => FunctionComponent<Props>;

package/es/internal/createClassWrapper.js

@@ -11,13 +11,13 @@ import React__default from 'react';
  * Wrap a class component with a functional component. This prevents an end-user
  * from being able to pass `ref` and access the underlying class instance.
  */
-function createClassWrapper(Component) {
-  function ClassWrapper(props) {
+const createClassWrapper = Component => {
+  const ClassWrapper = props => {
     return /*#__PURE__*/React__default.createElement(Component, props);
-  }
+  };
   const name = Component.displayName || Component.name;
   ClassWrapper.displayName = `ClassWrapper(${name})`;
   return ClassWrapper;
-}
+};
 
 export { createClassWrapper };

package/es/internal/keyboard/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export * as keys from './keys';
+export * from './match';
+export * from './navigation';

package/es/internal/keyboard/keys.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+import { KeyboardEvent } from 'react';
+export type Key = Pick<KeyboardEvent, 'which' | 'keyCode' | 'code'> & {
+    key?: string | string[];
+};
+export declare const Tab: Key;
+export declare const Enter: Key;
+export declare const Escape: Key;
+export declare const Space: Key;
+export declare const PageUp: Key;
+export declare const PageDown: Key;
+export declare const End: Key;
+export declare const Home: Key;
+export declare const ArrowLeft: Key;
+export declare const ArrowUp: Key;
+export declare const ArrowRight: Key;
+export declare const ArrowDown: Key;
+export declare const Delete: Key;

package/es/internal/keyboard/keys.js

@@ -69,8 +69,8 @@ const ArrowDown = {
 };
 const Delete = {
   key: 'Delete',
-  which: 8 ,
-  keyCode: 8 ,
+  which: 8,
+  keyCode: 8,
   code: 'ArrowDecimal'
 };
 

package/es/internal/keyboard/match.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+import type { KeyboardEvent as ReactKeyboardEvent } from 'react';
+import type { Key } from './keys';
+/**
+ * Check to see if at least one key code matches the key code of the
+ * given event.
+ *
+ * @param event - The event to test.
+ * @param keysToMatch - An array of key definitions to match against.
+ * @returns `true` if one of the keys matches.
+ */
+export declare const matches: (event: ReactKeyboardEvent | KeyboardEvent, keysToMatch: Key[]) => boolean;
+/**
+ * Check to see if the given key matches the corresponding keyboard event. Also
+ * supports passing in the value directly if you can't use the given event.
+ *
+ * @param eventOrCode - A `KeyboardEvent`, a number, or a string value.
+ * @param keyObj - An object with key properties to match against.
+ * @returns `true` if the event or code matches the key definition.
+ */
+export declare const match: (eventOrCode: ReactKeyboardEvent | KeyboardEvent | number | string, { key, which, keyCode, code }: Key) => boolean;

package/es/internal/keyboard/match.js

@@ -5,65 +5,38 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/**
- * @typedef Key
- * @property key {Array<string>|string}
- * @property which {number}
- * @property keyCode {number}
- */
-
 /**
  * Check to see if at least one key code matches the key code of the
  * given event.
  *
- * @example
- * import * as keys from '../keys';
- * import { matches } from '../match';
- *
- * function handleOnKeyDown(event) {
- *   if (matches(event, [keys.Enter, keys.Space]) {
- *     // ...
- *   }
- * }
- *
- * @param {Event|React.SyntheticEvent} event
- * @param {Array<Key>} keysToMatch
- * @returns {boolean}
+ * @param event - The event to test.
+ * @param keysToMatch - An array of key definitions to match against.
+ * @returns `true` if one of the keys matches.
  */
-function matches(event, keysToMatch) {
+const matches = (event, keysToMatch) => {
   for (let i = 0; i < keysToMatch.length; i++) {
     if (match(event, keysToMatch[i])) {
       return true;
     }
   }
   return false;
-}
+};
 
 /**
  * Check to see if the given key matches the corresponding keyboard event. Also
- * supports passing in the value directly if you can't used the given event.
- *
- * @example
- * import * as keys from '../keys';
- * import { matches } from '../match';
- *
- * function handleOnKeyDown(event) {
- *   if (match(event, keys.Enter) {
- *     // ...
- *   }
- * }
+ * supports passing in the value directly if you can't use the given event.
  *
- * @param {React.SyntheticEvent|Event|number|string} eventOrCode
- * @param {Key} key
- * @returns {boolean}
+ * @param eventOrCode - A `KeyboardEvent`, a number, or a string value.
+ * @param keyObj - An object with key properties to match against.
+ * @returns `true` if the event or code matches the key definition.
  */
-function match(eventOrCode) {
+const match = (eventOrCode, _ref) => {
   let {
     key,
     which,
     keyCode,
     code
-  } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  } = _ref;
   if (typeof eventOrCode === 'string') {
     return eventOrCode === key;
   }
@@ -71,9 +44,12 @@ function match(eventOrCode) {
     return eventOrCode === which || eventOrCode === keyCode;
   }
   if (eventOrCode.key && Array.isArray(key)) {
-    return key.indexOf(eventOrCode.key) !== -1;
+    return key.includes(eventOrCode.key);
   }
-  return eventOrCode.key === key || eventOrCode.which === which || eventOrCode.keyCode === keyCode || eventOrCode.code === code;
-}
+  return eventOrCode.key === key ||
+  // TODO: When can these checks for deprecated properties be deleted?
+  // Presumably, the `Key` type should also be pruned of these properties.
+  eventOrCode.which === which || eventOrCode.keyCode === keyCode || eventOrCode.code === code;
+};
 
 export { match, matches };

package/es/internal/keyboard/navigation.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+import { KeyboardEvent } from 'react';
+/**
+ * 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)
+ */
+export declare const getNextIndex: (key: KeyboardEvent | number | string, index: number, arrayLength: number) => number | undefined;
+/**
+ * A flag `node.compareDocumentPosition(target)` returns that indicates
+ * `target` is located earlier than `node` in the document or `target` contains `node`.
+ */
+export declare const DOCUMENT_POSITION_BROAD_PRECEDING: number;
+/**
+ * A flag `node.compareDocumentPosition(target)` returns that indicates
+ * `target` is located later than `node` in the document or `node` contains `target`.
+ */
+export declare const DOCUMENT_POSITION_BROAD_FOLLOWING: number;
+/**
+ * CSS selector that selects major nodes that are sequentially focusable.
+ */
+export declare const selectorTabbable = "\n  a[href], area[href], input:not([disabled]):not([tabindex='-1']),\n  button:not([disabled]):not([tabindex='-1']),select:not([disabled]):not([tabindex='-1']),\n  textarea:not([disabled]):not([tabindex='-1']),\n  iframe, object, embed, *[tabindex]:not([tabindex='-1']):not([disabled]), *[contenteditable=true]\n";
+/**
+ * CSS selector that selects major nodes that are click focusable.
+ */
+export declare const selectorFocusable = "\n  a[href], area[href], input:not([disabled]),\n  button:not([disabled]),select:not([disabled]),\n  textarea:not([disabled]),\n  iframe, object, embed, *[tabindex]:not([disabled]), *[contenteditable=true]\n";

package/es/internal/keyboard/navigation.js

@@ -9,21 +9,16 @@ import { ArrowRight, ArrowLeft } from './keys.js';
 import { match } from './match.js';
 
 /**
- * Various utilities to help with a11y work
- */
-
-/**
- * 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.
+ * 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 {string} key - the left or right arrow keys
- * @param {number} index - the current index in a given array
- * @param {number} arrayLength - the total length of the array
+ * @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)
+ *  getNextIndex(keyCodes.RIGHT, 0, 4)
  */
-
 const getNextIndex = (key, index, arrayLength) => {
   if (match(key, ArrowRight)) {
     return (index + 1) % arrayLength;
@@ -31,30 +26,23 @@ const getNextIndex = (key, index, arrayLength) => {
   if (match(key, ArrowLeft)) {
     return (index + arrayLength - 1) % arrayLength;
   }
+  return;
 };
 
 /**
- * A flag `node.compareDocumentPosition(target)` returns,
- * that indicates `target` is located earlier than `node` in the document or `target` contains `node`.
+ * A flag `node.compareDocumentPosition(target)` returns that indicates
+ * `target` is located earlier than `node` in the document or `target` contains `node`.
  */
-const DOCUMENT_POSITION_BROAD_PRECEDING =
-// Checks `typeof Node` for `react-docgen`
-typeof Node !== 'undefined' &&
-// eslint-disable-next-line ssr-friendly/no-dom-globals-in-module-scope
-Node.DOCUMENT_POSITION_PRECEDING | Node.DOCUMENT_POSITION_CONTAINS;
+const DOCUMENT_POSITION_BROAD_PRECEDING = typeof Node !== 'undefined' ? Node.DOCUMENT_POSITION_PRECEDING | Node.DOCUMENT_POSITION_CONTAINS : 0;
 
 /**
- * A flag `node.compareDocumentPosition(target)` returns,
- * that indicates `target` is located later than `node` in the document or `node` contains `target`.
+ * A flag `node.compareDocumentPosition(target)` returns that indicates
+ * `target` is located later than `node` in the document or `node` contains `target`.
  */
-const DOCUMENT_POSITION_BROAD_FOLLOWING =
-// Checks `typeof Node` for `react-docgen`
-typeof Node !== 'undefined' &&
-// eslint-disable-next-line ssr-friendly/no-dom-globals-in-module-scope
-Node.DOCUMENT_POSITION_FOLLOWING | Node.DOCUMENT_POSITION_CONTAINED_BY;
+const DOCUMENT_POSITION_BROAD_FOLLOWING = typeof Node !== 'undefined' ? Node.DOCUMENT_POSITION_FOLLOWING | Node.DOCUMENT_POSITION_CONTAINED_BY : 0;
 
 /**
- * CSS selector that selects major nodes that are sequential-focusable.
+ * CSS selector that selects major nodes that are sequentially focusable.
  */
 const selectorTabbable = `
   a[href], area[href], input:not([disabled]):not([tabindex='-1']),
@@ -64,7 +52,7 @@ const selectorTabbable = `
 `;
 
 /**
- * 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]),

package/es/internal/useMatchMedia.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+/** Listens to changes in a media query and returns whether it matches. */
+export declare const useMatchMedia: (mediaQuery: string) => boolean;

package/es/internal/useMatchMedia.js

@@ -8,37 +8,27 @@
 import { useState, useEffect } from 'react';
 import { canUseDOM } from './environment.js';
 
-function useMatchMedia(mediaQueryString) {
+/** Listens to changes in a media query and returns whether it matches. */
+const useMatchMedia = mediaQuery => {
   const [matches, setMatches] = useState(() => {
     if (canUseDOM) {
-      const mediaQueryList = window.matchMedia(mediaQueryString);
+      const mediaQueryList = window.matchMedia(mediaQuery);
       return mediaQueryList.matches;
     }
     return false;
   });
   useEffect(() => {
-    function listener(event) {
+    const listener = event => {
       setMatches(event.matches);
-    }
-    const mediaQueryList = window.matchMedia(mediaQueryString);
-    // Support fallback to `addListener` for broader browser support
-    if (mediaQueryList.addEventListener) {
-      mediaQueryList.addEventListener('change', listener);
-    } else {
-      mediaQueryList.addListener(listener);
-    }
-
-    // Make sure the media query list is in sync with the matches state
+    };
+    const mediaQueryList = window.matchMedia(mediaQuery);
+    mediaQueryList.addEventListener('change', listener);
     setMatches(mediaQueryList.matches);
     return () => {
-      if (mediaQueryList.addEventListener) {
-        mediaQueryList.removeEventListener('change', listener);
-      } else {
-        mediaQueryList.removeListener(listener);
-      }
+      mediaQueryList.removeEventListener('change', listener);
     };
-  }, [mediaQueryString]);
+  }, [mediaQuery]);
   return matches;
-}
+};
 
 export { useMatchMedia };

package/es/internal/useMergedRefs.js

@@ -7,6 +7,9 @@
 
 import { useCallback } from 'react';
 
+// TODO: Investigate updating this hook based on the following code from
+// https://github.com/carbon-design-system/carbon/pull/18611:
+// https://github.com/adamalston/carbon/blob/dd403b6b10de3d8a6ccd8d2e21174c908c1e890a/packages/react/src/components/ListBox/ListBoxMenuItem.tsx#L23-L46
 /**
  * Combine multiple refs into a single ref. This use useful when you have two
  * refs from both `React.forwardRef` and `useRef` that you would like to add to

package/es/internal/useNormalizedInputProps.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright IBM Corp. 2021, 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.
+ */
+import { type ComponentType, type ReactNode } from 'react';
+interface InputProps {
+    /** The ID for the input. */
+    id: string;
+    /** Whether the input is read-only. */
+    readOnly?: boolean;
+    /** Whether the input is disabled. */
+    disabled: boolean;
+    /** Whether the input is an invalid state. */
+    invalid: boolean;
+    /** The message displayed when the input is invalid. */
+    invalidText?: ReactNode;
+    /** Whether the input is in a warning state. */
+    warn: boolean;
+    /** The message displayed when the input is in a warning state. */
+    warnText?: ReactNode;
+}
+interface NormalizedInputProps {
+    /** Disabled state. */
+    disabled: boolean;
+    /** Invalid state. */
+    invalid: boolean;
+    /** The generated ID for the error message. */
+    invalidId: string;
+    /** The generated ID for the helper text. */
+    helperId: string;
+    /** Warning state. */
+    warn: boolean;
+    /** The generated ID for the warning message. */
+    warnId: string;
+    /** A React node containing the validation message. */
+    validation: ReactNode | null;
+    /** A React component representing the accompanying icon. */
+    icon: ComponentType | null;
+}
+/**
+ * Returns an object containing normalized properties for an input component.
+ *
+ * This hook ensures that only one of `invalid` or `warn` is active (with
+ * `invalid` taking precedence) and that `readOnly` overrides the `disabled`,
+ * `invalid`, and `warn` states. It generates unique IDs for error, warning, and
+ * helper messages, and conditionally provides the appropriate validation
+ * message and accompanying icon.
+ */
+export declare const useNormalizedInputProps: ({ id, readOnly, disabled, invalid, invalidText, warn, warnText, }: InputProps) => NormalizedInputProps;
+export {};

package/es/internal/useNormalizedInputProps.js

@@ -7,47 +7,20 @@
 
 import React__default from 'react';
 import { WarningFilled, WarningAltFilled } from '@carbon/icons-react';
-import { usePrefix } from './usePrefix.js';
 import '../components/Text/index.js';
+import { usePrefix } from './usePrefix.js';
 import { Text } from '../components/Text/Text.js';
 
 /**
- * @typedef {object} InputProps
- * @property {string} id - The input's id
- * @property {boolean | undefined} readOnly - Whether the input should be readonly
- * @property {boolean} disabled - Whether the input should be disabled
- * @property {boolean} invalid - Whether the input should be marked as invalid
- * @property {React.ReactNode | undefined} invalidText - The validation message displayed in case the input is considered invalid
- * @property {boolean} warn - Whether the input should be in warning state
- * @property {React.ReactNode | undefined} warnText - The validation message displayed in case the input is in warning state
- */
-
-/**
- * @typedef {object} NormalizedInputProps
- * @property {boolean} disabled - Whether the input is disabled
- * @property {boolean} invalid - Whether the input is invalid (takes precedence over warn)
- * @property {string} invalidId - The invalid message's id
- * @property {string} helperId - id used for helper text
- * @property {boolean} warn - Whether the input is in warning state
- * @property {string} warnId - The warning message's id
- * @property {React.ReactNode | null} validation – React node rendering the appropriate validation message (if any)
- * @property {React.ReactNode | null} icon – React node rendering the appropriate accompanying icon (if any)
- */
-
-/**
- * Returns an object containing non-colliding props and additional, generated ones.
- * This hook ensures that only either "invalid" or "warn" is true but never both at
- * the same time. Regardless whether "invalid" or "warn", the appropriate validation
- * message is passed as "validation". If the input should be accompanied by an icon
- * (to visually represent a readonly, invalid or warning state), the appropriate icon
- * is passed as "icon".
- * It also ensure that neither "invalid", nor "warn", nor "disabled" are enabled when
- * "readonly" is passed as "readonly" takes precedence over these variants.
+ * Returns an object containing normalized properties for an input component.
  *
- * @param {InputProps} props - The props passed to the component
- * @returns {NormalizedInputProps}
+ * This hook ensures that only one of `invalid` or `warn` is active (with
+ * `invalid` taking precedence) and that `readOnly` overrides the `disabled`,
+ * `invalid`, and `warn` states. It generates unique IDs for error, warning, and
+ * helper messages, and conditionally provides the appropriate validation
+ * message and accompanying icon.
  */
-function useNormalizedInputProps(_ref) {
+const useNormalizedInputProps = _ref => {
   let {
     id,
     readOnly,
@@ -84,6 +57,6 @@ function useNormalizedInputProps(_ref) {
     }, warnText);
   }
   return normalizedProps;
-}
+};
 
 export { useNormalizedInputProps };

package/lib/components/Accordion/AccordionItem.js

@@ -15,13 +15,13 @@ var cx = require('classnames');
 var PropTypes = require('prop-types');
 var React = require('react');
 require('../Text/index.js');
+var keys = require('../../internal/keyboard/keys.js');
+var match = require('../../internal/keyboard/match.js');
 var useId = require('../../internal/useId.js');
 var deprecate = require('../../prop-types/deprecate.js');
 var usePrefix = require('../../internal/usePrefix.js');
 var AccordionProvider = require('./AccordionProvider.js');
-var match = require('../../internal/keyboard/match.js');
 var Text = require('../Text/Text.js');
-var keys = require('../../internal/keyboard/keys.js');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 

package/lib/components/Button/Button.d.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * 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.
@@ -50,8 +50,7 @@ export interface ButtonBaseProps extends React.ButtonHTMLAttributes<HTMLButtonEl
      */
     rel?: React.AnchorHTMLAttributes<HTMLAnchorElement>['rel'];
     /**
-     * Optional prop to allow overriding the icon rendering.
-     * Can be a React component class
+     * A component used to render an icon.
      */
     renderIcon?: React.ElementType;
     /**