@carbon/react 1.91.0 → 1.92.0

package/es/index.js

@@ -26,6 +26,7 @@ export { default as CodeSnippetSkeleton } from './components/CodeSnippet/CodeSni
 export { default as ComboBox } from './components/ComboBox/ComboBox.js';
 export { ComboButton } from './components/ComboButton/index.js';
 export { default as ComposedModal, ModalBody } from './components/ComposedModal/ComposedModal.js';
+export { ComposedModalPresence } from './components/ComposedModal/ComposedModalPresence.js';
 export { ModalHeader } from './components/ComposedModal/ModalHeader.js';
 export { ModalFooter } from './components/ComposedModal/ModalFooter.js';
 import './components/ContainedList/index.js';
@@ -95,6 +96,7 @@ export { Menu } from './components/Menu/Menu.js';
 export { MenuItem, MenuItemDivider, MenuItemGroup, MenuItemRadioGroup, MenuItemSelectable } from './components/Menu/MenuItem.js';
 export { MenuButton } from './components/MenuButton/index.js';
 export { default as Modal } from './components/Modal/Modal.js';
+export { ModalPresence } from './components/Modal/ModalPresence.js';
 export { default as ModalWrapper } from './components/ModalWrapper/ModalWrapper.js';
 export { FilterableMultiSelect } from './components/MultiSelect/FilterableMultiSelect.js';
 export { MultiSelect } from './components/MultiSelect/MultiSelect.js';
@@ -208,7 +210,7 @@ export { default as FluidSearchSkeleton, default as preview__FluidSearchSkeleton
 export { default as FluidTextArea, default as preview__FluidTextArea, default as unstable__FluidTextArea } from './components/FluidTextArea/FluidTextArea.js';
 export { default as FluidTextAreaSkeleton, default as preview__FluidTextAreaSkeleton, default as unstable__FluidTextAreaSkeleton } from './components/FluidTextArea/FluidTextArea.Skeleton.js';
 export { default as FluidTextInput, default as preview__FluidTextInput, default as unstable__FluidTextInput } from './components/FluidTextInput/FluidTextInput.js';
-import './components/FluidTextInput/FluidPasswordInput.js';
+export { default as FluidPasswordInput } from './components/FluidTextInput/FluidPasswordInput.js';
 export { default as FluidTextInputSkeleton, default as preview__FluidTextInputSkeleton, default as unstable__FluidTextInputSkeleton } from './components/FluidTextInput/FluidTextInput.Skeleton.js';
 export { default as FluidNumberInput, default as preview__FluidNumberInput, default as unstable__FluidNumberInput } from './components/FluidNumberInput/FluidNumberInput.js';
 export { default as FluidNumberInputSkeleton, default as preview__FluidNumberInputSkeleton, default as unstable__FluidNumberInputSkeleton } from './components/FluidNumberInput/FluidNumberInput.Skeleton.js';
@@ -234,7 +236,9 @@ export { default as AISkeletonIcon, default as preview__AiSkeletonIcon, default
 export { default as AISkeletonText, default as preview__AiSkeletonText, default as unstable__AiSkeletonText } from './components/AISkeleton/AISkeletonText.js';
 export { DefinitionTooltip } from './components/Tooltip/DefinitionTooltip.js';
 export { Tooltip } from './components/Tooltip/Tooltip.js';
-import './components/Text/index.js';
+export { Text as preview_Text, Text as unstable_Text } from './components/Text/Text.js';
+export { TextDirection as preview_TextDirection, TextDirection as unstable_TextDirection } from './components/Text/TextDirection.js';
+import 'react';
 export { GlobalTheme, Theme, ThemeContext, usePrefersDarkScheme, useTheme } from './components/Theme/index.js';
 export { PrefixContext, usePrefix } from './internal/usePrefix.js';
 export { useIdPrefix } from './internal/useIdPrefix.js';
@@ -242,5 +246,3 @@ export { default as preview_PageSelector, default as unstable_PageSelector } fro
 export { default as preview_Pagination, default as unstable_Pagination } from './components/Pagination/experimental/Pagination.js';
 export { default as ContainedListItem } from './components/ContainedList/ContainedListItem/ContainedListItem.js';
 export { default as ContainedList } from './components/ContainedList/ContainedList.js';
-export { Text as preview_Text, Text as unstable_Text } from './components/Text/Text.js';
-export { TextDirection as preview_TextDirection, TextDirection as unstable_TextDirection } from './components/Text/TextDirection.js';

package/es/internal/useNormalizedInputProps.js

@@ -7,9 +7,9 @@
 
 import React from 'react';
 import { WarningFilled, WarningAltFilled } from '@carbon/icons-react';
-import '../components/Text/index.js';
-import { usePrefix } from './usePrefix.js';
 import { Text } from '../components/Text/Text.js';
+import '../components/Text/TextDirection.js';
+import { usePrefix } from './usePrefix.js';
 
 /**
  * Returns an object containing normalized properties for an input component.

package/es/internal/usePresence.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright IBM Corp. 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 RefObject } from 'react';
+export declare const usePresence: (ref: RefObject<HTMLElement | null>, isOpen: boolean) => {
+    /**
+     * Indicates whether the ref object is supposed to be mounted
+     */
+    isPresent: boolean;
+    /**
+     * Indicates whether the ref object is currently exiting
+     */
+    isExiting: boolean;
+};

package/es/internal/usePresence.js

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+
+import { useState, useCallback, useLayoutEffect } from 'react';
+import { usePrefix } from './usePrefix.js';
+
+const usePresence = (ref, isOpen) => {
+  const prefix = usePrefix();
+  const [exitState, setExitState] = useState(isOpen ? 'idle' : 'finished');
+  const isExiting = exitState === 'active';
+
+  // element is exiting
+  if (!isOpen && exitState === 'idle') {
+    setExitState('active');
+  }
+
+  // element exit was interrupted
+  if (isOpen && exitState !== 'idle') {
+    setExitState('idle');
+  }
+  const handleAnimationEnd = useCallback(() => {
+    setExitState('finished');
+  }, []);
+  useLayoutEffect(() => {
+    if (!ref.current || !isExiting) return;
+
+    // resolve for JSDOM
+    if (!('getAnimations' in ref.current)) {
+      handleAnimationEnd();
+      return;
+    }
+
+    // cover all animations that start with the presence prefix
+    const animations = ref.current.getAnimations({
+      subtree: true
+    }).filter(animation => animation instanceof CSSAnimation && animation.animationName.startsWith(`${prefix}--presence`));
+    if (!animations.length) {
+      handleAnimationEnd();
+      return;
+    }
+    let cancelled = false;
+    Promise.all(animations.map(animation => animation.finished)).finally(() => {
+      if (cancelled) return;
+      handleAnimationEnd();
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [ref, isExiting, prefix, handleAnimationEnd]);
+  return {
+    /**
+     * Indicates whether the ref object is supposed to be mounted
+     */
+    isPresent: isOpen || exitState !== 'finished',
+    /**
+     * Indicates whether the ref object is currently exiting
+     */
+    isExiting
+  };
+};
+
+export { usePresence };

package/es/internal/usePresenceContext.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright IBM Corp. 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 RefObject } from 'react';
+export interface PresenceContext {
+    /**
+     * The ref object the presence mode is mounted with
+     */
+    presenceRef: RefObject<HTMLDivElement | null>;
+    /**
+     * Indicates whether the ref object is currently exiting
+     */
+    isExiting: boolean;
+    /**
+     * Returns if the caller is exclusive to this presence context
+     */
+    isPresenceExclusive: (id: string) => boolean;
+}
+/**
+ * Returns if the presence node is present and the context value to be used by a presence context, e.g. ModalPresence.
+ */
+export declare const usePresenceContext: (open: boolean, initialPresenceId?: string) => readonly [boolean, PresenceContext];

package/es/internal/usePresenceContext.js

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+
+import { useRef, useCallback, useMemo } from 'react';
+import { usePresence } from './usePresence.js';
+
+/**
+ * Returns if the presence node is present and the context value to be used by a presence context, e.g. ModalPresence.
+ */
+const usePresenceContext = (open, initialPresenceId) => {
+  const presenceIdRef = useRef(initialPresenceId);
+  const presenceRef = useRef(null);
+  const prevPresenceRef = useRef(null);
+
+  // clean up the presence id, if not predefined and if the presence node was unmounted
+  if (!initialPresenceId && prevPresenceRef.current && !presenceRef.current) {
+    presenceIdRef.current = null;
+  }
+  prevPresenceRef.current = presenceRef.current;
+  const {
+    isPresent,
+    isExiting
+  } = usePresence(presenceRef, open);
+  const isPresenceExclusive = useCallback(id => {
+    if (!id) return false;
+
+    // return false if the presence context is occupied
+    if (presenceIdRef.current && presenceIdRef.current !== id) return false;
+
+    // otherwise occupy presence context and return true
+    presenceIdRef.current = id;
+    return true;
+  }, []);
+  const contextValue = useMemo(() => ({
+    presenceRef,
+    isPresenceExclusive,
+    isExiting
+  }), [presenceRef, isPresenceExclusive, isExiting]);
+  return [isPresent, contextValue];
+};
+
+export { usePresenceContext };

package/es/tools/mergeRefs.d.ts

@@ -1,12 +1,12 @@
-export default mergeRefs;
 /**
- * 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 type { Ref, RefCallback } from 'react';
 /**
- * @param {...Ref<Element>} refs List of React refs to merge.
- * @returns {Ref<Element>} Merged React ref.
+ * @param refs Refs to merge.
+ * @returns Merged ref.
  */
-declare function mergeRefs(...refs: Ref<Element>[]): Ref<Element>;
+export declare const mergeRefs: <T>(...refs: (Ref<T> | null | undefined)[]) => RefCallback<T>;

package/es/tools/mergeRefs.js

@@ -6,18 +6,22 @@
  */
 
 /**
- * @param {...Ref<Element>} refs List of React refs to merge.
- * @returns {Ref<Element>} Merged React ref.
+ * @param refs Refs to merge.
+ * @returns Merged ref.
  */
-const mergeRefs = (...refs) => el => {
-  refs.forEach(ref => {
-    // https://github.com/facebook/react/issues/13029#issuecomment-410002316
-    if (typeof ref === 'function') {
-      ref(el);
-    } else if (Object(ref) === ref) {
-      ref.current = el;
-    }
-  });
+const mergeRefs = (...refs) => {
+  return value => {
+    refs.forEach(ref => {
+      if (!ref) return;
+
+      // https://github.com/facebook/react/issues/13029#issuecomment-410002316
+      if (typeof ref === 'function') {
+        ref(value);
+      } else if (typeof ref === 'object' && 'current' in ref) {
+        ref.current = value;
+      }
+    });
+  };
 };
 
-export { mergeRefs as default };
+export { mergeRefs };

package/lib/components/Accordion/AccordionItem.d.ts

@@ -12,6 +12,11 @@ export interface AccordionItemProps {
      * this value will be managed by the parent Accordion.
      */
     disabled?: boolean;
+    /**
+     * Specify a custom label for the accordion button.
+     * This is important for accessibility when the accordion has no visible title.
+     */
+    'aria-label'?: AriaAttributes['aria-label'];
     /**
      * The handler of the massaged `click` event.
      */
@@ -52,6 +57,7 @@ export interface AccordionItemProps {
 export interface AccordionToggleProps {
     'aria-controls'?: AriaAttributes['aria-controls'];
     'aria-expanded'?: AriaAttributes['aria-expanded'];
+    'aria-label'?: AriaAttributes['aria-label'];
     className?: string;
     disabled?: boolean;
     onClick?: MouseEventHandler<HTMLButtonElement>;
@@ -59,7 +65,7 @@ export interface AccordionToggleProps {
     type?: 'button';
 }
 declare function AccordionItem({ children, className: customClassName, open, onHeadingClick, renderExpando, // remove renderExpando in next major release
-renderToggle, title, disabled: controlledDisabled, handleAnimationEnd, ...rest }: PropsWithChildren<AccordionItemProps>): import("react/jsx-runtime").JSX.Element;
+renderToggle, title, disabled: controlledDisabled, handleAnimationEnd, 'aria-label': ariaLabel, ...rest }: PropsWithChildren<AccordionItemProps>): import("react/jsx-runtime").JSX.Element;
 declare namespace AccordionItem {
     var propTypes: {
         /**
@@ -74,6 +80,11 @@ declare namespace AccordionItem {
          * Specify whether an individual AccordionItem should be disabled
          */
         disabled: PropTypes.Requireable<boolean>;
+        /**
+         * Specify a custom label for the accordion button.
+         * This is important for accessibility when the accordion has no visible title.
+         */
+        'aria-label': PropTypes.Requireable<string>;
         /**
          * The handler of the massaged `click` event.
          */

package/lib/components/Accordion/AccordionItem.js

@@ -14,14 +14,14 @@ var iconsReact = require('@carbon/icons-react');
 var cx = require('classnames');
 var PropTypes = require('prop-types');
 var React = require('react');
-require('../Text/index.js');
+var Text = require('../Text/Text.js');
+require('../Text/TextDirection.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 Text = require('../Text/Text.js');
 
 const defaultRenderToggle = props => /*#__PURE__*/React.createElement("button", _rollupPluginBabelHelpers.extends({
   type: "button"
@@ -37,6 +37,7 @@ function AccordionItem({
   title = 'title',
   disabled: controlledDisabled,
   handleAnimationEnd,
+  'aria-label': ariaLabel,
   ...rest
 }) {
   const [isOpen, setIsOpen] = React.useState(open);
@@ -100,6 +101,7 @@ function AccordionItem({
     disabled: disabled,
     "aria-controls": id,
     "aria-expanded": isOpen,
+    "aria-label": ariaLabel,
     className: `${prefix}--accordion__heading`,
     onClick: onClick,
     onKeyDown: onKeyDown,
@@ -131,6 +133,11 @@ AccordionItem.propTypes = {
    * Specify whether an individual AccordionItem should be disabled
    */
   disabled: PropTypes.bool,
+  /**
+   * Specify a custom label for the accordion button.
+   * This is important for accessibility when the accordion has no visible title.
+   */
+  'aria-label': PropTypes.string,
   /**
    * The handler of the massaged `click` event.
    */

package/lib/components/Breadcrumb/BreadcrumbItem.js

@@ -16,8 +16,8 @@ var cx = require('classnames');
 var Link = require('../Link/Link.js');
 var iconsReact = require('@carbon/icons-react');
 var usePrefix = require('../../internal/usePrefix.js');
-require('../Text/index.js');
 var Text = require('../Text/Text.js');
+require('../Text/TextDirection.js');
 
 const frFn = React.forwardRef;
 const BreadcrumbItem = frFn((props, ref) => {

package/lib/components/Checkbox/Checkbox.js

@@ -13,7 +13,8 @@ var _rollupPluginBabelHelpers = require('../../_virtual/_rollupPluginBabelHelper
 var PropTypes = require('prop-types');
 var React = require('react');
 var cx = require('classnames');
-require('../Text/index.js');
+var Text = require('../Text/Text.js');
+require('../Text/TextDirection.js');
 var deprecate = require('../../prop-types/deprecate.js');
 var usePrefix = require('../../internal/usePrefix.js');
 var iconsReact = require('@carbon/icons-react');
@@ -21,7 +22,6 @@ var useId = require('../../internal/useId.js');
 var noopFn = require('../../internal/noopFn.js');
 var index = require('../AILabel/index.js');
 var utils = require('../../internal/utils.js');
-var Text = require('../Text/Text.js');
 
 const Checkbox = /*#__PURE__*/React.forwardRef(({
   className,

package/lib/components/ComboBox/ComboBox.js

@@ -14,7 +14,8 @@ var cx = require('classnames');
 var Downshift = require('downshift');
 var PropTypes = require('prop-types');
 var React = require('react');
-require('../Text/index.js');
+var Text = require('../Text/Text.js');
+require('../Text/TextDirection.js');
 var iconsReact = require('@carbon/icons-react');
 var isEqual = require('react-fast-compare');
 var index$2 = require('../ListBox/index.js');
@@ -34,7 +35,6 @@ var index$1 = require('../AILabel/index.js');
 var defaultItemToString = require('../../internal/defaultItemToString.js');
 var utils = require('../../internal/utils.js');
 var ListBoxPropTypes = require('../ListBox/ListBoxPropTypes.js');
-var Text = require('../Text/Text.js');
 
 const {
   InputBlur,
@@ -285,9 +285,13 @@ const ComboBox = /*#__PURE__*/React.forwardRef((props, ref) => {
     switch (type) {
       case InputBlur:
         {
-          if (allowCustomValue && highlightedIndex == '-1') {
-            const customValue = inputValue;
-            changes.selectedItem = customValue;
+          // If custom values are allowed, treat whatever the user typed as
+          // the value.
+          if (allowCustomValue && highlightedIndex === -1) {
+            const {
+              inputValue
+            } = state;
+            changes.selectedItem = inputValue;
             if (onChange) {
               onChange({
                 selectedItem: inputValue,
@@ -296,17 +300,28 @@ const ComboBox = /*#__PURE__*/React.forwardRef((props, ref) => {
             }
             return changes;
           }
-          if (state.inputValue && highlightedIndex == '-1' && changes.selectedItem) {
+
+          // If a new item was selected, keep its label in the input.
+          if (state.inputValue && highlightedIndex === -1 && changes.selectedItem) {
             return {
               ...changes,
               inputValue: itemToString(changes.selectedItem)
             };
           }
-          if (state.inputValue && highlightedIndex == '-1' && !allowCustomValue && !changes.selectedItem) {
-            return {
-              ...changes,
-              inputValue: ''
-            };
+
+          // If custom values are not allowed, normalize any non-matching
+          // text. If the input isn’t an exact item label, restore the
+          // selected label if there is one, or clear it.
+          if (!allowCustomValue) {
+            const currentInput = state.inputValue ?? '';
+            const hasExactMatch = !!currentInput && items.some(item => itemToString(item) === currentInput);
+            if (!hasExactMatch) {
+              const restoredInput = state.selectedItem !== null ? itemToString(state.selectedItem) : '';
+              return {
+                ...changes,
+                inputValue: restoredInput
+              };
+            }
           }
           return changes;
         }
@@ -359,16 +374,17 @@ const ComboBox = /*#__PURE__*/React.forwardRef((props, ref) => {
         };
       case FunctionToggleMenu:
       case ToggleButtonClick:
-        if (!changes.isOpen && state.inputValue && highlightedIndex === -1 && !allowCustomValue) {
-          return {
-            ...changes,
-            inputValue: '' // Clear the input
-          };
-        }
-        if (changes.isOpen && !changes.selectedItem) {
-          return {
-            ...changes
-          };
+        // When closing the menu, apply the same normalization as blur.
+        if (state.isOpen && !changes.isOpen && !allowCustomValue) {
+          const currentInput = state.inputValue ?? '';
+          const hasExactMatch = !!currentInput && items.some(item => itemToString(item) === currentInput);
+          if (!hasExactMatch) {
+            const restoredInput = state.selectedItem !== null ? itemToString(state.selectedItem) : '';
+            return {
+              ...changes,
+              inputValue: restoredInput
+            };
+          }
         }
         return changes;
       case MenuMouseLeave:
@@ -395,7 +411,7 @@ const ComboBox = /*#__PURE__*/React.forwardRef((props, ref) => {
     }
   },
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  [allowCustomValue, inputValue, onChange]);
+  [allowCustomValue, inputValue, itemToString, items, onChange]);
   const handleToggleClick = isOpen => event => {
     if (onToggleClick) {
       onToggleClick(event);
@@ -639,7 +655,7 @@ const ComboBox = /*#__PURE__*/React.forwardRef((props, ref) => {
       setInputValue(newValue);
       downshiftSetInputValue(newValue);
     },
-    ref: mergeRefs.default(textInput, ref, inputRef),
+    ref: mergeRefs.mergeRefs(textInput, ref, inputRef),
     onKeyDown: event => {
       if (match.match(event, keys.Space)) {
         event.stopPropagation();

package/lib/components/ComboButton/index.js

@@ -91,7 +91,7 @@ const ComboButton = /*#__PURE__*/React.forwardRef(function ComboButton({
     middleware: middlewares,
     whileElementsMounted: react.autoUpdate
   });
-  const ref = mergeRefs.default(forwardRef, containerRef, refs.setReference);
+  const ref = mergeRefs.mergeRefs(forwardRef, containerRef, refs.setReference);
   const {
     open,
     handleClick: hookOnClick,