@carbon/react 1.110.0 → 1.111.0-rc.0

package/es/components/ComboButton/index.js

@@ -16,8 +16,8 @@ import Button_default from "../Button/index.js";
 import { mergeRefs } from "../../tools/mergeRefs.js";
 import { Menu as Menu$1 } from "../Menu/Menu.js";
 import { useAttachedMenu } from "../../internal/useAttachedMenu.js";
-import React, { useRef } from "react";
 import classNames from "classnames";
+import React, { useRef } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { ChevronDown } from "@carbon/icons-react";
@@ -122,10 +122,25 @@ const ComboButton = React.forwardRef(function ComboButton({ children, className,
 	});
 });
 ComboButton.propTypes = {
+	/**
+	* A collection of MenuItems to be rendered as additional actions for this ComboButton.
+	*/
 	children: PropTypes.node.isRequired,
+	/**
+	* Additional CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the ComboButton should be disabled, or not.
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Provide the label to be rendered on the primary action button.
+	*/
 	label: PropTypes.string.isRequired,
+	/**
+	* Experimental property. Specify how the menu should align with the button element
+	*/
 	menuAlignment: PropTypes.oneOf([
 		"top",
 		"top-start",
@@ -134,13 +149,22 @@ ComboButton.propTypes = {
 		"bottom-start",
 		"bottom-end"
 	]),
+	/**
+	* Provide an optional function to be called when the primary action element is clicked.
+	*/
 	onClick: PropTypes.func,
+	/**
+	* Specify the size of the buttons and menu.
+	*/
 	size: PropTypes.oneOf([
 		"xs",
 		"sm",
 		"md",
 		"lg"
 	]),
+	/**
+	* Specify how the trigger tooltip should be aligned.
+	*/
 	tooltipAlignment: deprecateValuesWithin(PropTypes.oneOf([
 		"top",
 		"top-left",
@@ -176,6 +200,9 @@ ComboButton.propTypes = {
 		"right-start",
 		"right-end"
 	], mapPopoverAlign),
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: PropTypes.func
 };
 //#endregion

package/es/components/ComposedModal/ComposedModal.js

@@ -5,11 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { warning } from "../../internal/warning.js";
 import { usePrefix } from "../../internal/usePrefix.js";
 import { Escape, Tab } from "../../internal/keyboard/keys.js";
 import { match } from "../../internal/keyboard/match.js";
 import { useId } from "../../internal/useId.js";
+import { warning } from "../../internal/warning.js";
 import { deprecate } from "../../prop-types/deprecate.js";
 import { isComponentElement } from "../../internal/utils.js";
 import { useFeatureFlag } from "../FeatureFlags/index.js";
@@ -27,8 +27,8 @@ import { Dialog } from "../Dialog/Dialog.js";
 import { useComposedModalState } from "./useComposedModalState.js";
 import { ComposedModalPresence, ComposedModalPresenceContext, useExclusiveComposedModalPresenceContext } from "./ComposedModalPresence.js";
 import { isTopmostVisibleModal } from "../Modal/isTopmostVisibleModal.js";
-import React, { Children, cloneElement, useContext, useEffect, useRef, useState } from "react";
 import classNames from "classnames";
+import React, { Children, cloneElement, useContext, useEffect, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useMergeRefs } from "@floating-ui/react";
@@ -68,11 +68,30 @@ const ModalBody = React.forwardRef(function ModalBody({ ["aria-label"]: ariaLabe
 	});
 });
 ModalBody.propTypes = {
+	/**
+	* Specify the aria-label for the modal body when it is scrollable
+	*/
 	["aria-label"]: PropTypes.string,
+	/**
+	* Specify the aria-labelledby for the modal body when it is scrollable
+	*/
 	["aria-labelledby"]: PropTypes.string,
+	/**
+	* Specify the content to be placed in the ModalBody
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be added to the Modal Body node
+	*/
 	className: PropTypes.string,
+	/**
+	* Provide whether the modal content has a form element.
+	* If `true` is used here, non-form child content should have `cds--modal-content__regular-content` class.
+	*/
 	hasForm: PropTypes.bool,
+	/**
+	* Specify whether the modal contains scrolling content
+	*/
 	hasScrollingContent: PropTypes.bool
 };
 const ComposedModal = React.forwardRef(function ComposedModal({ open, ...props }, ref) {
@@ -317,21 +336,70 @@ const ComposedModalDialog = React.forwardRef(function ComposedModalDialog({ ["ar
 	});
 });
 ComposedModal.propTypes = {
+	/**
+	* Specify the aria-label for cds--modal-container
+	*/
 	["aria-label"]: PropTypes.string,
+	/**
+	* Specify the aria-labelledby for cds--modal-container
+	*/
 	["aria-labelledby"]: PropTypes.string,
+	/**
+	* Specify the content to be placed in the ComposedModal
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the modal root node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify an optional className to be applied to the modal node
+	*/
 	containerClassName: PropTypes.string,
+	/**
+	* Specify whether the primary button should be replaced with danger button.
+	* Note that this prop is not applied if you render primary/danger button by yourself
+	*/
 	danger: PropTypes.bool,
+	/**
+	* **Experimental**: Provide a `decorator` component to be rendered inside the `ComposedModal` component
+	*/
 	decorator: PropTypes.node,
+	/**
+	* Specify whether the Modal content should have any inner padding.
+	*/
 	isFullWidth: PropTypes.bool,
+	/**
+	* Provide a ref to return focus to once the modal is closed.
+	*/
 	launcherButtonRef: PropTypes.oneOfType([PropTypes.func, PropTypes.shape({ current: PropTypes.any })]),
+	/**
+	* Specify an optional handler for closing modal.
+	* Returning `false` here prevents closing modal.
+	*/
 	onClose: PropTypes.func,
+	/**
+	* Specify an optional handler for the `onKeyDown` event. Called for all
+	* `onKeyDown` events that do not close the modal
+	*/
 	onKeyDown: PropTypes.func,
+	/**
+	* Specify whether the Modal is currently open
+	*/
 	open: PropTypes.bool,
 	preventCloseOnClickOutside: PropTypes.bool,
+	/**
+	* Specify a CSS selector that matches the DOM element that should be
+	* focused when the Modal opens
+	*/
 	selectorPrimaryFocus: PropTypes.string,
+	/**
+	* Specify the CSS selectors that match the floating menus
+	*/
 	selectorsFloatingMenus: PropTypes.arrayOf(PropTypes.string.isRequired),
+	/**
+	* Specify the size variant.
+	*/
 	size: PropTypes.oneOf([
 		"xs",
 		"sm",

package/es/components/ComposedModal/ModalFooter.js

@@ -5,13 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { noopFn } from "../../internal/noopFn.js";
 import { usePrefix } from "../../internal/usePrefix.js";
+import { noopFn } from "../../internal/noopFn.js";
 import Button_default from "../Button/index.js";
 import ButtonSet_default from "../ButtonSet/index.js";
 import InlineLoading_default from "../InlineLoading/index.js";
-import React from "react";
 import classNames from "classnames";
+import React from "react";
 import PropTypes from "prop-types";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/ComposedModal/ModalFooter.tsx
@@ -101,27 +101,87 @@ const ModalFooter = React.forwardRef(function ModalFooter({ children, className:
 	});
 });
 ModalFooter.propTypes = {
+	/**
+	* Pass in content that will be rendered in the Modal Footer
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify a custom className to be applied to the Modal Footer container
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify an optional function that is called whenever the modal is closed
+	*/
 	closeModal: PropTypes.func,
+	/**
+	* Specify whether the primary button should be replaced with danger button.
+	* Note that this prop is not applied if you render primary/danger button by yourself
+	*/
 	danger: PropTypes.bool,
+	/**
+	* Specify the message read by screen readers for the danger primary button.
+	* Defaults to an empty string; provide localized text to opt in.
+	*/
 	dangerDescription: PropTypes.string,
+	/**
+	* The `ref` callback for the primary button.
+	*/
 	inputref: PropTypes.oneOfType([PropTypes.func, PropTypes.shape({ current: PropTypes.any })]),
+	/**
+	* Specify the description for the loading text
+	*/
 	loadingDescription: PropTypes.string,
+	/**
+	* Specify the description for the loading text
+	*/
 	loadingIconDescription: PropTypes.string,
+	/**
+	* loading status
+	*/
 	loadingStatus: PropTypes.oneOf([
 		"inactive",
 		"active",
 		"finished",
 		"error"
 	]),
+	/**
+	* Provide an optional handler to be invoked when loading is
+	* successful
+	*/
 	onLoadingSuccess: PropTypes.func,
+	/**
+	* Specify an optional function for when the modal is requesting to be
+	* closed
+	*/
 	onRequestClose: PropTypes.func,
+	/**
+	* Specify an optional function for when the modal is requesting to be
+	* submitted
+	*/
 	onRequestSubmit: PropTypes.func,
+	/**
+	* Specify whether the primary button should be disabled
+	*/
 	primaryButtonDisabled: PropTypes.bool,
+	/**
+	* Specify the text for the primary button
+	*/
 	primaryButtonText: PropTypes.string,
+	/**
+	* Specify a custom className to be applied to the primary button
+	*/
 	primaryClassName: PropTypes.string,
+	/**
+	* Specify the text for the secondary button
+	*/
 	secondaryButtonText: PropTypes.string,
+	/**
+	* Specify an array of config objects for secondary buttons
+	* (`Array<{
+	*   buttonText: string,
+	*   onClick: function,
+	* }>`).
+	*/
 	secondaryButtons: (props, propName, componentName) => {
 		if (props.secondaryButtons) {
 			if (!Array.isArray(props.secondaryButtons) || props.secondaryButtons.length !== 2) return /* @__PURE__ */ new Error(`${propName} needs to be an array of two button config objects`);
@@ -135,6 +195,9 @@ ModalFooter.propTypes = {
 		}
 		return null;
 	},
+	/**
+	* Specify a custom className to be applied to the secondary button
+	*/
 	secondaryClassName: PropTypes.string
 };
 //#endregion

package/es/components/ComposedModal/ModalHeader.js

@@ -9,8 +9,8 @@ import { usePrefix } from "../../internal/usePrefix.js";
 import { useId } from "../../internal/useId.js";
 import { IconButton } from "../IconButton/index.js";
 import { ComposedModalContext } from "./ComposedModalContext.js";
-import React, { useContext, useEffect } from "react";
 import classNames from "classnames";
+import React, { useContext, useEffect } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Close } from "@carbon/icons-react";
@@ -92,16 +92,51 @@ const ModalHeader = React.forwardRef(function ModalHeader({ buttonOnClick, child
 	});
 });
 ModalHeader.propTypes = {
+	/**
+	* Provide an optional function to be called when the close button is
+	* clicked
+	*/
 	buttonOnClick: PropTypes.func,
+	/**
+	* Specify the content to be placed in the ModalHeader
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the modal header
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify an optional className to be applied to the modal close node
+	*/
 	closeClassName: PropTypes.string,
+	/**
+	* Specify an optional className to be applied to the modal close icon node
+	*/
 	closeIconClassName: PropTypes.string,
+	/**
+	* Provide an optional function to be called when the modal is closed
+	*/
 	closeModal: PropTypes.func,
+	/**
+	* Specify a description for the close icon that can be read by screen
+	* readers
+	*/
 	iconDescription: PropTypes.string,
+	/**
+	* Specify an optional label to be displayed
+	*/
 	label: PropTypes.string,
+	/**
+	* Specify an optional className to be applied to the modal header label
+	*/
 	labelClassName: PropTypes.string,
+	/**
+	* Specify an optional title to be displayed
+	*/
 	title: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the modal heading
+	*/
 	titleClassName: PropTypes.string
 };
 //#endregion

package/es/components/ContainedList/ContainedList.js

@@ -12,8 +12,8 @@ import { LayoutConstraint } from "../Layout/index.js";
 import ContainedListItem_default from "./ContainedListItem/index.js";
 import Search from "../Search/Search.js";
 import ExpandableSearch_default from "../ExpandableSearch/index.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/ContainedList/ContainedList.tsx
@@ -69,12 +69,33 @@ const ContainedList = ({ action, children, className, isInset, kind = variants[0
 	});
 };
 ContainedList.propTypes = {
+	/**
+	* A slot for a possible interactive element to render.
+	*/
 	action: PropTypes.node,
+	/**
+	* A collection of ContainedListItems to be rendered in the ContainedList
+	*/
 	children: PropTypes.node,
+	/**
+	* Additional CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the dividing lines in between list items should be inset.
+	*/
 	isInset: PropTypes.bool,
+	/**
+	* The kind of ContainedList you want to display
+	*/
 	kind: PropTypes.oneOf(variants),
+	/**
+	* A label describing the contained list.
+	*/
 	label: PropTypes.oneOfType([PropTypes.string, PropTypes.node]),
+	/**
+	* Specify the size of the contained list.
+	*/
 	size: PropTypes.oneOf([
 		"sm",
 		"md",

package/es/components/ContainedList/ContainedListItem/ContainedListItem.js

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../../internal/usePrefix.js";
 import { LayoutConstraint } from "../../Layout/index.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/ContainedList/ContainedListItem/ContainedListItem.tsx
@@ -47,11 +47,29 @@ const ContainedListItem = ({ action, children, className, disabled = false, onCl
 	});
 };
 ContainedListItem.propTypes = {
+	/**
+	* A slot for a possible interactive element to render within the item.
+	*/
 	action: PropTypes.node,
+	/**
+	* The content of this item. Must not contain any interactive elements. Use props.action to include those.
+	*/
 	children: PropTypes.node,
+	/**
+	* Additional CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* Whether this item is disabled.
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Provide an optional function to be called when the item is clicked.
+	*/
 	onClick: PropTypes.func,
+	/**
+	* A component used to render an icon.
+	*/
 	renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object])
 };
 //#endregion

package/es/components/ContentSwitcher/ContentSwitcher.js

@@ -14,8 +14,8 @@ import { isComponentElement } from "../../internal/utils.js";
 import { LayoutConstraint } from "../Layout/index.js";
 import Switch from "../Switch/Switch.js";
 import IconSwitch from "../Switch/IconSwitch.js";
-import { Children, cloneElement, useContext, useEffect, useRef, useState } from "react";
 import classNames from "classnames";
+import { Children, cloneElement, useContext, useEffect, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/ContentSwitcher/ContentSwitcher.tsx
@@ -109,13 +109,38 @@ const ContentSwitcher = ({ children, className, light, lowContrast, selectedInde
 };
 ContentSwitcher.displayName = "ContentSwitcher";
 ContentSwitcher.propTypes = {
+	/**
+	* Pass in Switch components to be rendered in the ContentSwitcher
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be added to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* `true` to use the light variant.
+	*/
 	light: deprecate(PropTypes.bool, "The `light` prop for `ContentSwitcher` is no longer needed and has been deprecated. It will be removed in the next major release."),
+	/**
+	* `true` to use the low contrast version.
+	*/
 	lowContrast: PropTypes.bool,
+	/**
+	* Specify an `onChange` handler that is called whenever the ContentSwitcher
+	* changes which item is selected
+	*/
 	onChange: PropTypes.func.isRequired,
+	/**
+	* Specify a selected index for the initially selected content
+	*/
 	selectedIndex: PropTypes.number,
+	/**
+	* Choose whether or not to automatically change selection on focus when left/right arrow pressed. Defaults to 'automatic'
+	*/
 	selectionMode: PropTypes.oneOf(["automatic", "manual"]),
+	/**
+	* Specify the size of the Content Switcher. Currently supports either `sm`, `md` (default) or `lg` as an option.
+	*/
 	size: PropTypes.oneOf([
 		"sm",
 		"md",

package/es/components/Copy/Copy.js

@@ -5,14 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { noopFn } from "../../internal/noopFn.js";
 import { usePrefix } from "../../internal/usePrefix.js";
+import { noopFn } from "../../internal/noopFn.js";
 import { deprecateValuesWithin } from "../../prop-types/deprecateValuesWithin.js";
 import { mapPopoverAlign } from "../../tools/mapPopoverAlign.js";
 import { IconButton } from "../IconButton/index.js";
 import { composeEventHandlers } from "../../tools/events.js";
-import { useCallback, useEffect, useState } from "react";
 import classNames from "classnames";
+import { useCallback, useEffect, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 import { debounce } from "es-toolkit/compat";
@@ -59,6 +59,9 @@ function Copy({ align = "bottom", autoAlign = false, children, className, feedba
 	});
 }
 Copy.propTypes = {
+	/**
+	* Specify how the trigger should align with the tooltip
+	*/
 	align: deprecateValuesWithin(PropTypes.oneOf([
 		"top",
 		"top-left",
@@ -94,12 +97,38 @@ Copy.propTypes = {
 		"right-start",
 		"right-end"
 	], mapPopoverAlign),
+	/**
+	* **Experimental**: Will attempt to automatically align the tooltip. Requires
+	* React v17+
+	* @see https://github.com/carbon-design-system/carbon/issues/18714
+	*/
 	autoAlign: PropTypes.bool,
+	/**
+	* Pass in content to be rendered in the underlying `<button>`
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the underlying `<button>`
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify the string that is displayed when the button is clicked and the
+	* content is copied
+	*/
 	feedback: PropTypes.string,
+	/**
+	* Specify the time it takes for the feedback message to timeout
+	*/
 	feedbackTimeout: PropTypes.number,
+	/**
+	* Specify an optional `onAnimationEnd` handler that is called when the underlying
+	* animation ends
+	*/
 	onAnimationEnd: PropTypes.func,
+	/**
+	* Specify an optional `onClick` handler that is called when the underlying
+	* `<button>` is clicked
+	*/
 	onClick: PropTypes.func
 };
 //#endregion

package/es/components/CopyButton/CopyButton.js

@@ -5,14 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { noopFn } from "../../internal/noopFn.js";
 import { usePrefix } from "../../internal/usePrefix.js";
+import { noopFn } from "../../internal/noopFn.js";
 import { deprecateValuesWithin } from "../../prop-types/deprecateValuesWithin.js";
 import { mapPopoverAlign } from "../../tools/mapPopoverAlign.js";
 import Copy_default from "../Copy/index.js";
 import { LayoutConstraint } from "../Layout/index.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 import { Copy } from "@carbon/icons-react";
@@ -44,6 +44,9 @@ function CopyButton({ align = "bottom", autoAlign = false, feedback = "Copied!",
 	});
 }
 CopyButton.propTypes = {
+	/**
+	* Specify how the trigger should align with the tooltip
+	*/
 	align: deprecateValuesWithin(PropTypes.oneOf([
 		"top",
 		"top-left",
@@ -79,11 +82,34 @@ CopyButton.propTypes = {
 		"right-start",
 		"right-end"
 	], mapPopoverAlign),
+	/**
+	* **Experimental**: Will attempt to automatically align the tooltip. Requires
+	* React v17+
+	* @see https://github.com/carbon-design-system/carbon/issues/18714
+	*/
 	autoAlign: PropTypes.bool,
+	/**
+	* Specify an optional className to be applied to the underlying `<button>`
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify the string that is displayed when the button is clicked and the
+	* content is copied
+	*/
 	feedback: PropTypes.string,
+	/**
+	* Specify the time it takes for the feedback message to timeout
+	*/
 	feedbackTimeout: PropTypes.number,
+	/**
+	* Provide a description for the icon representing the copy action that can
+	* be read by screen readers
+	*/
 	iconDescription: PropTypes.string,
+	/**
+	* Specify an optional `onClick` handler that is called when the underlying
+	* `<button>` is clicked
+	*/
 	onClick: PropTypes.func
 };
 //#endregion