@carbon/react 1.78.0-rc.0 → 1.78.1

package/es/components/UIShell/SideNavLink.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.
@@ -37,7 +37,7 @@ export type SideNavLinkProps<E extends ElementType> = LinkProps<E> & {
      */
     large?: boolean;
     /**
-     * Provide an icon to render in the side navigation link. Should be a React class.
+     * A component used to render an icon.
      */
     renderIcon?: ComponentType;
     /**

package/es/components/UIShell/SideNavLink.js

@@ -69,7 +69,7 @@ SideNavLink.propTypes = {
    */
   large: PropTypes.bool,
   /**
-   * Provide an icon to render in the side navigation link. Should be a React class.
+   * A component used to render an icon.
    */
   // @ts-expect-error - PropTypes are unable to cover this case.
   renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),

package/es/components/UIShell/SideNavMenu.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.
@@ -27,7 +27,7 @@ export interface SideNavMenuProps {
      */
     large?: boolean;
     /**
-     * A custom icon to render next to the SideNavMenu title. This can be a function returning JSX or JSX itself.
+     * A component used to render an icon.
      */
     renderIcon?: React.ComponentType;
     /**

package/es/components/UIShell/SideNavMenu.js

@@ -10,10 +10,10 @@ import cx from 'classnames';
 import PropTypes from 'prop-types';
 import React__default, { useContext, useState } from 'react';
 import SideNavIcon from './SideNavIcon.js';
+import { Escape } from '../../internal/keyboard/keys.js';
+import { match } from '../../internal/keyboard/match.js';
 import { usePrefix } from '../../internal/usePrefix.js';
 import { SideNavContext } from './SideNav.js';
-import { match } from '../../internal/keyboard/match.js';
-import { Escape } from '../../internal/keyboard/keys.js';
 
 var _ChevronDown;
 const SideNavMenu = /*#__PURE__*/React__default.forwardRef(function SideNavMenu(_ref, ref) {
@@ -110,7 +110,7 @@ SideNavMenu.propTypes = {
    */
   large: PropTypes.bool,
   /**
-   * Pass in a custom icon to render next to the `SideNavMenu` title
+   * A component used to render an icon.
    */
   // @ts-expect-error - PropTypes are unable to cover this case.
   renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),

package/es/components/UIShell/SwitcherItem.js

@@ -11,9 +11,9 @@ import cx from 'classnames';
 import PropTypes from 'prop-types';
 import { Link } from './Link.js';
 import { usePrefix } from '../../internal/usePrefix.js';
-import { AriaLabelPropType } from '../../prop-types/AriaPropTypes.js';
-import { match } from '../../internal/keyboard/match.js';
 import { ArrowDown, ArrowUp } from '../../internal/keyboard/keys.js';
+import { match } from '../../internal/keyboard/match.js';
+import { AriaLabelPropType } from '../../prop-types/AriaPropTypes.js';
 
 const SwitcherItem = /*#__PURE__*/forwardRef(function SwitcherItem(props, forwardRef) {
   const {

package/es/internal/FloatingMenu.js

@@ -9,13 +9,13 @@ import React__default, { useContext, useState, useRef, useCallback, useEffect, c
 import * as FeatureFlags from '@carbon/feature-flags';
 import ReactDOM from 'react-dom';
 import window from 'window-or-global';
-import OptimizedResize from './OptimizedResize.js';
+import { Tab } from './keyboard/keys.js';
+import { match } from './keyboard/match.js';
 import { selectorTabbable, selectorFocusable } from './keyboard/navigation.js';
+import { OptimizedResize } from './OptimizedResize.js';
 import { PrefixContext } from './usePrefix.js';
 import { warning } from './warning.js';
 import wrapFocus, { wrapFocusWithoutSentinels } from './wrapFocus.js';
-import { match } from './keyboard/match.js';
-import { Tab } from './keyboard/keys.js';
 
 const DIRECTION_LEFT = 'left';
 const DIRECTION_TOP = 'top';
@@ -205,7 +205,7 @@ const FloatingMenu = _ref2 => {
       updateMenuPosition();
     });
     return () => {
-      resizeHandler.release();
+      resizeHandler.remove();
     };
   }, [triggerRef, menuOffset, menuDirection, flipped, target, updateOrientation]);
 

package/es/internal/OptimizedResize.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+/**
+ * A callback function to be executed on `resize`.
+ */
+type Callback = () => void;
+export declare const OptimizedResize: {
+    /** Adds a callback function to be executed on window `resize`. */
+    add: (callback: Callback) => {
+        /** Removes the callback. */
+        remove: () => void;
+    };
+};
+export {};

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/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/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/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;
     /**

package/lib/components/Button/Button.js

@@ -203,8 +203,7 @@ Button.propTypes = {
    */
   rel: PropTypes__default["default"].string,
   /**
-   * Optional prop to allow overriding the icon rendering.
-   * Can be a React component class
+   * A component used to render an icon.
    */
   renderIcon: PropTypes__default["default"].oneOfType([PropTypes__default["default"].func, PropTypes__default["default"].object]),
   /**

package/lib/components/Button/ButtonBase.js

@@ -58,7 +58,7 @@ const ButtonBase = /*#__PURE__*/React__default["default"].forwardRef(function Bu
     [`${prefix}--btn--${kind}`]: kind,
     [`${prefix}--btn--disabled`]: disabled,
     [`${prefix}--btn--expressive`]: isExpressive,
-    [`${prefix}--btn--icon-only`]: hasIconOnly && !className?.includes(`${prefix}--btn--icon-only`),
+    [`${prefix}--btn--icon-only`]: hasIconOnly,
     [`${prefix}--btn--selected`]: hasIconOnly && isSelected && kind === 'ghost'
   });
   const commonProps = {

package/lib/components/ChatButton/ChatButton.d.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright IBM Corp. 2024
+ * Copyright IBM Corp. 2024, 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.
@@ -33,8 +33,7 @@ export interface ChatButtonProps extends React.ButtonHTMLAttributes<HTMLButtonEl
      */
     kind?: ChatButtonKind;
     /**
-     * Optional prop to specify an icon to be rendered.
-     * Can be a React component class
+     * A component used to render an icon.
      */
     renderIcon?: ComponentType | FunctionComponent;
     /**

package/lib/components/ChatButton/ChatButton.js

@@ -85,8 +85,7 @@ ChatButton.propTypes = {
    */
   kind: PropTypes__default["default"].oneOf(['primary', 'secondary', 'danger', 'ghost', 'tertiary']),
   /**
-   * Optional prop to specify an icon to be rendered.
-   * Can be a React component class
+   * A component used to render an icon.
    */
   // @ts-expect-error: PropTypes are not expressive enough to cover this case
   renderIcon: PropTypes__default["default"].oneOfType([PropTypes__default["default"].func, PropTypes__default["default"].object]),