@carbon/react 1.110.0 → 1.111.0-rc.0

package/es/components/ListBox/ListBox.js

@@ -9,8 +9,8 @@ import { usePrefix } from "../../internal/usePrefix.js";
 import { deprecate } from "../../prop-types/deprecate.js";
 import { ListBoxSizePropType, ListBoxTypePropType } from "./ListBoxPropTypes.js";
 import { FormContext } from "../FluidForm/FormContext.js";
-import { forwardRef, useContext } from "react";
 import classNames from "classnames";
+import { forwardRef, useContext } from "react";
 import PropTypes from "prop-types";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/ListBox/ListBox.tsx
@@ -73,18 +73,59 @@ const ListBox = forwardRef((props, ref) => {
 });
 ListBox.displayName = "ListBox";
 ListBox.propTypes = {
+	/**
+	* Provide the contents of your ListBox
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify a class name to be applied on the containing list box node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the ListBox is currently disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Specify whether the control is currently invalid
+	*/
 	invalid: PropTypes.bool,
+	/**
+	* Specify the text to be displayed when the control is invalid
+	*/
 	invalidText: PropTypes.node,
+	/**
+	* Specify the id to be applied to the element containing the invalid text
+	*/
 	invalidTextId: PropTypes.string,
+	/**
+	* Specify if the control should render open
+	*/
 	isOpen: PropTypes.bool,
+	/**
+	* `true` to use the light version. For use on $ui-01 backgrounds only.
+	* Don't use this to make tile background color same as container background color.
+	*/
 	light: deprecate(PropTypes.bool, "The `light` prop for `ListBox` has been deprecated in favor of the new `Layer` component. It will be removed in the next major release."),
+	/**
+	* Specify the size of the ListBox. Currently supports either `xs`, `sm`, `md` or `lg` as an option.
+	*/
 	size: ListBoxSizePropType,
+	/**
+	* Specify the "type" of the ListBox. Currently supports either `default` or
+	* `inline` as an option.
+	*/
 	type: ListBoxTypePropType,
+	/**
+	* Specify whether the control is currently in warning state
+	*/
 	warn: PropTypes.bool,
+	/**
+	* Provide the text that is displayed when the control is in warning state
+	*/
 	warnText: PropTypes.string,
+	/**
+	* Specify the id to be applied to the element containing the warn text
+	*/
 	warnTextId: PropTypes.string
 };
 //#endregion

package/es/components/ListBox/ListBoxField.js

@@ -24,10 +24,27 @@ function ListBoxField({ children, disabled, tabIndex, ...rest }) {
 	});
 }
 ListBoxField.propTypes = {
+	/**
+	* Typically set by `getToggleButtonProps`, this should specify whether the
+	* field has a popup.
+	*/
 	"aria-haspopup": PropTypes.oneOfType([PropTypes.string, PropTypes.bool]),
+	/**
+	* Provide the contents of your ListBoxField
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify if the parent <ListBox> is disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* The role for the component, should be set by `getToggleButtonProps` coming
+	* from Downshift
+	*/
 	role: PropTypes.string,
+	/**
+	* Optional prop to specify the tabIndex of the <ListBox> trigger button
+	*/
 	tabIndex: PropTypes.oneOfType([PropTypes.number, PropTypes.string])
 };
 //#endregion

package/es/components/ListBox/ListBoxMenu.js

@@ -34,12 +34,18 @@ const ListBoxMenu = forwardRef(({ children, id, ...rest }, ref) => {
 });
 ListBoxMenu.displayName = "ListBoxMenu";
 ListBoxMenu.propTypes = {
+	/**
+	* Provide the contents of your ListBoxMenu
+	*/
 	children: PropTypes.oneOfType([
 		PropTypes.node,
 		PropTypes.arrayOf(PropTypes.oneOf([ListBoxMenuItem])),
 		PropTypes.shape({ type: PropTypes.oneOf([ListBoxMenuItem]) }),
 		PropTypes.bool
 	]),
+	/**
+	* Specify a custom `id`
+	*/
 	id: PropTypes.string.isRequired
 };
 //#endregion

package/es/components/ListBox/ListBoxMenuIcon.js

@@ -6,8 +6,8 @@
  */
 
 import { usePrefix } from "../../internal/usePrefix.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 import { ChevronDown } from "@carbon/icons-react";
@@ -47,7 +47,14 @@ const ListBoxMenuIcon = ({ isOpen, translateWithId: t = defaultTranslateWithId }
 	});
 };
 ListBoxMenuIcon.propTypes = {
+	/**
+	* Specify whether the menu is currently open, which will influence the
+	* direction of the menu icon
+	*/
 	isOpen: PropTypes.bool.isRequired,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: PropTypes.func
 };
 //#endregion

package/es/components/ListBox/ListBoxMenuItem.js

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import { useMergedRefs } from "../../internal/useMergedRefs.js";
-import { forwardRef, useEffect, useRef, useState } from "react";
 import classNames from "classnames";
+import { forwardRef, useEffect, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/ListBox/ListBoxMenuItem.tsx
@@ -69,10 +69,26 @@ const ListBoxMenuItem = forwardRef(({ children, isActive = false, isHighlighted
 });
 ListBoxMenuItem.displayName = "ListBoxMenuItem";
 ListBoxMenuItem.propTypes = {
+	/**
+	* Specify any children nodes that should be rendered inside of the ListBox
+	* Menu Item
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify if the item should be disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Specify whether the current menu item is "active".
+	*/
 	isActive: PropTypes.bool,
+	/**
+	* Specify whether the current menu item is "highlighted".
+	*/
 	isHighlighted: PropTypes.bool,
+	/**
+	* Provide an optional tooltip for the ListBoxMenuItem
+	*/
 	title: PropTypes.string
 };
 //#endregion

package/es/components/ListBox/ListBoxSelection.d.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright IBM Corp. 2016, 2025
+ * 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.

package/es/components/ListBox/ListBoxSelection.js

@@ -6,14 +6,14 @@
  */
 
 import { usePrefix } from "../../internal/usePrefix.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Close } from "@carbon/icons-react";
 //#region src/components/ListBox/ListBoxSelection.tsx
 /**
-* Copyright IBM Corp. 2016, 2025
+* 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.
@@ -23,7 +23,7 @@ const translationIds = {
 	"clear.selection": "clear.selection"
 };
 const defaultTranslations = {
-	[translationIds["clear.all"]]: "Clear all selected items",
+	[translationIds["clear.all"]]: "Clear selected items",
 	[translationIds["clear.selection"]]: "Clear selected item"
 };
 const defaultTranslateWithId = (messageId) => {
@@ -36,9 +36,11 @@ const defaultTranslateWithId = (messageId) => {
 */
 const ListBoxSelection = ({ clearSelection, selectionCount, translateWithId: t = defaultTranslateWithId, disabled, onClearSelection, readOnly }) => {
 	const prefix = usePrefix();
+	const hasSelectionCount = (selectionCount ?? 0) > 0;
+	const hasMultipleSelections = (selectionCount ?? 0) > 1;
 	const className = classNames(`${prefix}--list-box__selection`, {
-		[`${prefix}--tag--filter`]: selectionCount,
-		[`${prefix}--list-box__selection--multi`]: selectionCount
+		[`${prefix}--tag--filter`]: hasSelectionCount,
+		[`${prefix}--list-box__selection--multi`]: hasSelectionCount
 	});
 	const handleOnClick = (event) => {
 		event.stopPropagation();
@@ -46,9 +48,9 @@ const ListBoxSelection = ({ clearSelection, selectionCount, translateWithId: t =
 		clearSelection(event);
 		if (onClearSelection) onClearSelection(event);
 	};
-	const description = selectionCount ? t("clear.all") : t("clear.selection");
+	const description = hasMultipleSelections ? t("clear.all") : t("clear.selection");
 	const tagClasses = classNames(`${prefix}--tag`, `${prefix}--tag--filter`, `${prefix}--tag--high-contrast`, { [`${prefix}--tag--disabled`]: disabled });
-	return selectionCount ? /* @__PURE__ */ jsxs("div", {
+	return hasSelectionCount ? /* @__PURE__ */ jsxs("div", {
 		className: tagClasses,
 		children: [/* @__PURE__ */ jsx("span", {
 			className: `${prefix}--tag__label`,
@@ -59,27 +61,48 @@ const ListBoxSelection = ({ clearSelection, selectionCount, translateWithId: t =
 			tabIndex: -1,
 			className: `${prefix}--tag__close-icon`,
 			onClick: handleOnClick,
-			"aria-label": t("clear.all"),
+			"aria-label": description,
 			title: description,
 			"aria-disabled": readOnly ? true : void 0,
 			children: /* @__PURE__ */ jsx(Close, {})
 		})]
-	}) : /* @__PURE__ */ jsxs("div", {
+	}) : /* @__PURE__ */ jsx("div", {
 		role: "button",
 		className,
 		tabIndex: -1,
 		onClick: handleOnClick,
 		"aria-label": description,
 		title: description,
-		children: [selectionCount, /* @__PURE__ */ jsx(Close, {})]
+		children: /* @__PURE__ */ jsx(Close, {})
 	});
 };
 ListBoxSelection.propTypes = {
+	/**
+	* Specify a function to be invoked when a user interacts with the clear
+	* selection element.
+	*/
 	clearSelection: PropTypes.func.isRequired,
+	/**
+	* Specify whether or not the clear selection element should be disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Specify an optional `onClearSelection` handler that is called when the underlying
+	* element is cleared
+	*/
 	onClearSelection: PropTypes.func,
+	/**
+	* Whether or not the Dropdown is readonly
+	*/
 	readOnly: PropTypes.bool,
+	/**
+	* Specify an optional `selectionCount` value that will be used to determine
+	* whether the selection should display a badge or a single clear icon.
+	*/
 	selectionCount: PropTypes.number,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: PropTypes.func
 };
 //#endregion

package/es/components/ListBox/next/ListBoxSelection.d.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright IBM Corp. 2016, 2025
+ * 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.

package/es/components/ListBox/next/ListBoxSelection.js

@@ -6,14 +6,14 @@
  */
 
 import { usePrefix } from "../../../internal/usePrefix.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Close } from "@carbon/icons-react";
 //#region src/components/ListBox/next/ListBoxSelection.tsx
 /**
-* Copyright IBM Corp. 2016, 2025
+* 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.
@@ -28,7 +28,7 @@ const translationIds = {
 	"clear.selection": "clear.selection"
 };
 const defaultTranslations = {
-	[translationIds["clear.all"]]: "Clear all selected items",
+	[translationIds["clear.all"]]: "Clear selected items",
 	[translationIds["clear.selection"]]: "Clear selected item"
 };
 const defaultTranslateWithId = (messageId) => {
@@ -36,11 +36,13 @@ const defaultTranslateWithId = (messageId) => {
 };
 function ListBoxSelection({ clearSelection, selectionCount, translateWithId: t = defaultTranslateWithId, disabled, readOnly, onClearSelection, ...rest }) {
 	const prefix = usePrefix();
+	const hasSelectionCount = (selectionCount ?? 0) > 0;
+	const hasMultipleSelections = (selectionCount ?? 0) > 1;
 	const className = classNames(`${prefix}--list-box__selection`, {
-		[`${prefix}--tag--filter`]: selectionCount,
-		[`${prefix}--list-box__selection--multi`]: selectionCount
+		[`${prefix}--tag--filter`]: hasSelectionCount,
+		[`${prefix}--list-box__selection--multi`]: hasSelectionCount
 	});
-	const description = selectionCount ? t("clear.all") : t("clear.selection");
+	const description = hasMultipleSelections ? t("clear.all") : t("clear.selection");
 	const tagClasses = classNames(`${prefix}--tag`, `${prefix}--tag--filter`, `${prefix}--tag--high-contrast`, { [`${prefix}--tag--disabled`]: disabled });
 	function onClick(event) {
 		event.stopPropagation();
@@ -48,7 +50,7 @@ function ListBoxSelection({ clearSelection, selectionCount, translateWithId: t =
 		clearSelection(event);
 		if (onClearSelection) onClearSelection(event);
 	}
-	if (selectionCount) return /* @__PURE__ */ jsxs("div", {
+	if (hasSelectionCount) return /* @__PURE__ */ jsxs("div", {
 		className: tagClasses,
 		children: [/* @__PURE__ */ jsx("span", {
 			className: `${prefix}--tag__label`,
@@ -80,14 +82,47 @@ function ListBoxSelection({ clearSelection, selectionCount, translateWithId: t =
 	});
 }
 ListBoxSelection.propTypes = {
+	/**
+	* Specify a function to be invoked when a user interacts with the clear
+	* selection element.
+	*/
 	clearSelection: PropTypes.func.isRequired,
+	/**
+	* Specify whether or not the clear selection element should be disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Whether or not the listbox is readonly
+	*/
 	readOnly: PropTypes.bool,
+	/**
+	* Specify an optional `onClearSelection` handler that is called when the underlying
+	* element is cleared
+	*/
 	onClearSelection: PropTypes.func,
+	/**
+	* Specify an optional `onClick` handler that is called when the underlying
+	* clear selection element is clicked
+	*/
 	onClick: PropTypes.func,
+	/**
+	* Specify an optional `onClick` handler that is called when the underlying
+	* clear selection element is clicked
+	*/
 	onMouseUp: PropTypes.func,
+	/**
+	* Specify an optional `onKeyDown` handler that is called when the underlying
+	* clear selection element fires a keydown event
+	*/
 	onKeyDown: PropTypes.func,
+	/**
+	* Specify an optional `selectionCount` value that will be used to determine
+	* whether the selection should display a badge or a single clear icon.
+	*/
 	selectionCount: PropTypes.number,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: PropTypes.func
 };
 //#endregion

package/es/components/ListBox/next/ListBoxTrigger.js

@@ -6,8 +6,8 @@
  */
 
 import { usePrefix } from "../../../internal/usePrefix.js";
-import React from "react";
 import classNames from "classnames";
+import React from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 import { ChevronDown } from "@carbon/icons-react";
@@ -52,7 +52,14 @@ const ListBoxTrigger = React.forwardRef(({ isOpen, translateWithId: t = defaultT
 	});
 });
 ListBoxTrigger.propTypes = {
+	/**
+	* Specify whether the menu is currently open, which will influence the
+	* direction of the menu icon
+	*/
 	isOpen: PropTypes.bool.isRequired,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: PropTypes.func
 };
 //#endregion

package/es/components/ListItem/ListItem.js

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import { Text } from "../Text/Text.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/ListItem/ListItem.tsx
@@ -27,7 +27,13 @@ function ListItem({ className, children, ...other }) {
 	});
 }
 ListItem.propTypes = {
+	/**
+	* Specify the content for the ListItem
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to apply to the underlying `<li>` node
+	*/
 	className: PropTypes.string
 };
 //#endregion

package/es/components/Loading/Loading.js

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import { deprecate } from "../../prop-types/deprecate.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/Loading/Loading.tsx
@@ -62,11 +62,29 @@ function Loading({ active = true, className: customClassName, withOverlay = true
 	}) : loading;
 }
 Loading.propTypes = {
+	/**
+	* Specify whether you want the loading indicator to be spinning or not
+	*/
 	active: PropTypes.bool,
+	/**
+	* Provide an optional className to be applied to the containing node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify a description that would be used to best describe the loading state
+	*/
 	description: PropTypes.string,
+	/**
+	* Provide an `id` to uniquely identify the label
+	*/
 	id: deprecate(PropTypes.string, `\nThe prop \`id\` is no longer needed.`),
+	/**
+	* Specify whether you would like the small variant of <Loading>
+	*/
 	small: PropTypes.bool,
+	/**
+	* Specify whether you want the loader to be applied with an overlay
+	*/
 	withOverlay: PropTypes.bool
 };
 //#endregion

package/es/components/Menu/Menu.js

@@ -13,8 +13,8 @@ import { useMergedRefs } from "../../internal/useMergedRefs.js";
 import { MenuContext, menuReducer } from "./MenuContext.js";
 import { useLayoutDirection } from "../LayoutDirection/useLayoutDirection.js";
 import { canUseDOM } from "../../internal/environment.js";
-import { forwardRef, useContext, useEffect, useMemo, useReducer, useRef, useState } from "react";
 import classNames from "classnames";
+import { forwardRef, useContext, useEffect, useMemo, useReducer, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 import { createPortal } from "react-dom";
@@ -212,25 +212,77 @@ const Menu = forwardRef(function Menu({ backgroundToken = "layer", border = fals
 	return isRoot ? open && createPortal(rendered, target) || null : rendered;
 });
 Menu.propTypes = {
+	/**
+	* Specify the background token to use. Default is 'layer'.
+	*/
 	backgroundToken: PropTypes.oneOf(["layer", "background"]),
+	/**
+	* Specify whether a border should be rendered on the menu
+	*/
 	border: PropTypes.bool,
+	/**
+	* A collection of MenuItems to be rendered within this Menu.
+	*/
 	children: PropTypes.node,
+	/**
+	* Additional CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* A label describing the Menu.
+	*/
 	label: PropTypes.string,
+	/**
+	* Specify how the menu should align with the button element
+	*/
 	menuAlignment: PropTypes.string,
+	/**
+	* **Deprecated**: Menus now always support both icons as well as selectable items and nesting.
+	* The mode of this menu. Defaults to full.
+	* `full` supports nesting and selectable menu items, but no icons.
+	* `basic` supports icons but no nesting or selectable menu items.
+	*
+	* **This prop is not intended for use and will be set by the respective implementation (like useContextMenu, MenuButton, and ComboButton).**
+	*/
 	mode: deprecate(PropTypes.oneOf(["full", "basic"]), "Menus now always support both icons as well as selectable items and nesting."),
+	/**
+	* Provide an optional function to be called when the Menu should be closed,
+	* including if the Menu is blurred, the user presses escape, or the Menu is
+	* a submenu and the user presses ArrowLeft.
+	*/
 	onClose: PropTypes.func,
+	/**
+	* Provide an optional function to be called when the Menu is opened.
+	*/
 	onOpen: PropTypes.func,
+	/**
+	* Whether the Menu is open or not.
+	*/
 	open: PropTypes.bool,
+	/**
+	* Specify the size of the Menu.
+	*/
 	size: PropTypes.oneOf([
 		"xs",
 		"sm",
 		"md",
 		"lg"
 	]),
+	/**
+	* Specify a DOM node where the Menu should be rendered in. Defaults to document.body.
+	*/
 	target: PropTypes.object,
+	/**
+	* Specify the x position of the Menu. Either pass a single number or an array with two numbers describing your activator's boundaries ([x1, x2])
+	*/
 	x: PropTypes.oneOfType([PropTypes.number, PropTypes.arrayOf(PropTypes.number)]),
+	/**
+	* Specify the y position of the Menu. Either pass a single number or an array with two numbers describing your activator's boundaries ([y1, y2])
+	*/
 	y: PropTypes.oneOfType([PropTypes.number, PropTypes.arrayOf(PropTypes.number)]),
+	/**
+	* @deprecated Internal compatibility flag. Use `false` to enable auto-alignment behavior.
+	*/
 	legacyAutoalign: PropTypes.bool
 };
 //#endregion