@carbon/react 1.110.0 → 1.111.0-rc.0

package/es/components/AILabel/index.js

@@ -10,8 +10,8 @@ import { useId } from "../../internal/useId.js";
 import { deprecate } from "../../prop-types/deprecate.js";
 import { IconButton } from "../IconButton/index.js";
 import Toggletip, { ToggletipActions, ToggletipButton, ToggletipContent } from "../Toggletip/index.js";
-import React from "react";
 import classNames from "classnames";
+import React from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { Undo } from "@carbon/icons-react";
@@ -34,7 +34,13 @@ const AILabelContent = ({ className, children }) => {
 };
 AILabelContent.displayName = "AILabelContent";
 AILabelContent.propTypes = {
+	/**
+	* Specify the content you want rendered inside the AILabel ToggleTip
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be added to the AILabel callout
+	*/
 	className: PropTypes.string
 };
 const AILabelActions = ({ className, children }) => {
@@ -45,7 +51,13 @@ const AILabelActions = ({ className, children }) => {
 };
 AILabelActions.displayName = "AILabelActions";
 AILabelActions.propTypes = {
+	/**
+	* Specify the content you want rendered inside the AILabel callout toolbar
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be added to the AILabel toolbar
+	*/
 	className: PropTypes.string
 };
 const AILabel = React.forwardRef(function AILabel({ aiText = "AI", aiTextLabel, textLabel, align, autoAlign = true, children, className, kind = "default", onRevertClick, revertActive, revertLabel = "Revert to AI input", slugLabel = "Show information", ["aria-label"]: ariaLabel = "Show information", size = "xs", ...rest }, ref) {
@@ -103,14 +115,42 @@ const AILabel = React.forwardRef(function AILabel({ aiText = "AI", aiTextLabel,
 AILabel.displayName = "AILabel";
 AILabel.propTypes = {
 	...Toggletip.propTypes,
+	/**
+	* Specify the content you want rendered inside the `AILabel` ToggleTip
+	*/
 	AILabelContent: PropTypes.node,
+	/**
+	* Specify the correct translation of the AI text
+	*/
 	aiText: PropTypes.string,
+	/**
+	* @deprecated
+	* Specify additional text to be rendered next to the AI label in the inline variant
+	*/
 	aiTextLabel: deprecate(PropTypes.string, "`aiTextLabel` on `AILabel` has been deprecated - Please use the `textLabel` prop instead"),
+	/**
+	* Specify the text that will be provided to the aria-label of the `AILabel` button
+	*/
 	"aria-label": PropTypes.string,
+	/**
+	* Specify the type of `AILabel`, from the following list of types:
+	*/
 	kind: PropTypes.oneOf(["default", "inline"]),
+	/**
+	* Callback function that fires when the revert button is clicked
+	*/
 	onRevertClick: PropTypes.func,
+	/**
+	* Specify whether the revert button should be visible
+	*/
 	revertActive: PropTypes.bool,
+	/**
+	* Specify the text that should be shown when the revert button is hovered
+	*/
 	revertLabel: PropTypes.string,
+	/**
+	* Specify the size of the button, from the following list of sizes:
+	*/
 	size: PropTypes.oneOf([
 		"mini",
 		"2xs",
@@ -120,7 +160,14 @@ AILabel.propTypes = {
 		"lg",
 		"xl"
 	]),
+	/**
+	* @deprecated
+	* Specify the text that will be provided to the aria-label of the `AILabel` button
+	*/
 	slugLabel: deprecate(PropTypes.string, "`slugLabel` on `AILabel` has been deprecated - Please use the `ariaLabel` prop instead"),
+	/**
+	* Specify additional text to be rendered next to the AI label in the inline variant
+	*/
 	textLabel: PropTypes.string
 };
 //#endregion

package/es/components/AISkeleton/AISkeletonIcon.js

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import SkeletonIcon from "../SkeletonIcon/SkeletonIcon.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/AISkeleton/AISkeletonIcon.tsx
@@ -25,7 +25,13 @@ const AISkeletonIcon = ({ className, ...rest }) => {
 	});
 };
 AISkeletonIcon.propTypes = {
+	/**
+	* Specify an optional className to add.
+	*/
 	className: PropTypes.string,
+	/**
+	* The CSS styles.
+	*/
 	style: PropTypes.object
 };
 //#endregion

package/es/components/AISkeleton/AISkeletonPlaceholder.js

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import SkeletonPlaceholder from "../SkeletonPlaceholder/SkeletonPlaceholder.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/AISkeleton/AISkeletonPlaceholder.tsx
@@ -18,6 +18,11 @@ const AISkeletonPlaceholder = ({ className, ...other }) => {
 		...other
 	});
 };
-AISkeletonPlaceholder.propTypes = { className: PropTypes.string };
+AISkeletonPlaceholder.propTypes = { 
+/**
+* Add a custom class to the component
+* to set the height and width
+*/
+className: PropTypes.string };
 //#endregion
 export { AISkeletonPlaceholder as default };

package/es/components/AISkeleton/AISkeletonText.js

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import SkeletonText from "../SkeletonText/SkeletonText.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/AISkeleton/AISkeletonText.tsx
@@ -25,10 +25,25 @@ const AISkeletonText = ({ className, ...rest }) => {
 	});
 };
 AISkeletonText.propTypes = {
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* generates skeleton text at a larger size
+	*/
 	heading: PropTypes.bool,
+	/**
+	* the number of lines shown if paragraph is true
+	*/
 	lineCount: PropTypes.number,
+	/**
+	* will generate multiple lines of text
+	*/
 	paragraph: PropTypes.bool,
+	/**
+	* width (in px or %) of single line of text or max-width of paragraph lines
+	*/
 	width: PropTypes.string
 };
 //#endregion

package/es/components/Accordion/Accordion.Skeleton.js

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import SkeletonText_default from "../SkeletonText/index.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { ChevronRight } from "@carbon/icons-react";
@@ -46,10 +46,25 @@ function AccordionSkeleton({ align = "end", className, count = 4, isFlush, open
 	});
 }
 AccordionSkeleton.propTypes = {
+	/**
+	* Specify the alignment of the accordion heading title and chevron.
+	*/
 	align: PropTypes.oneOf(["start", "end"]),
+	/**
+	* Specify an optional className to add.
+	*/
 	className: PropTypes.string,
+	/**
+	* Set number of items to render
+	*/
 	count: PropTypes.number,
+	/**
+	* Specify whether an individual AccordionItem should be flush, default is false
+	*/
 	isFlush: PropTypes.bool,
+	/**
+	* `false` to not display the first item opened
+	*/
 	open: PropTypes.bool
 };
 function AccordionSkeletonItem() {

package/es/components/Accordion/Accordion.js

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import { AccordionProvider } from "./AccordionProvider.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/Accordion/Accordion.tsx
@@ -36,12 +36,34 @@ function Accordion({ align = "end", children, className: customClassName, disabl
 	});
 }
 Accordion.propTypes = {
+	/**
+	* Specify the alignment of the accordion heading title and chevron.
+	*/
 	align: PropTypes.oneOf(["start", "end"]),
+	/**
+	* Pass in the children that will be rendered within the Accordion
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether an individual AccordionItem should be disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Specify whether Accordion text should be flush, default is false, does not work with align="start"
+	*/
 	isFlush: PropTypes.bool,
+	/**
+	* Specify if the Accordion should be an ordered list,
+	* default is `false`
+	*/
 	ordered: PropTypes.bool,
+	/**
+	* Specify the size of the Accordion. Currently supports the following:
+	*/
 	size: PropTypes.oneOf([
 		"sm",
 		"md",

package/es/components/Accordion/AccordionItem.js

@@ -12,8 +12,8 @@ import { Escape } from "../../internal/keyboard/keys.js";
 import { match } from "../../internal/keyboard/match.js";
 import { useId } from "../../internal/useId.js";
 import { deprecate } from "../../prop-types/deprecate.js";
-import React, { useContext, useEffect, useRef, useState } from "react";
 import classNames from "classnames";
+import React, { useContext, useEffect, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { ChevronRight } from "@carbon/icons-react";
@@ -96,15 +96,48 @@ function AccordionItem({ children, className: customClassName = "", open = false
 	});
 }
 AccordionItem.propTypes = {
+	/**
+	* Provide the contents of your AccordionItem
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* 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.
+	*/
 	onClick: PropTypes.func,
+	/**
+	* The handler of the massaged `click` event on the heading.
+	*/
 	onHeadingClick: PropTypes.func,
+	/**
+	* `true` to open the expand.
+	*/
 	open: PropTypes.bool,
+	/**
+	* The callback function to render the expand button.
+	* Can be a React component class.
+	*/
 	renderExpando: deprecate(PropTypes.func, "The `renderExpando` prop has been deprecated and will be removed in the next major release of Carbon. Use the `renderToggle` prop instead."),
+	/**
+	* The callback function to render the expand button.
+	* Can be a React component class.
+	*/
 	renderToggle: PropTypes.func,
+	/**
+	* The accordion title.
+	*/
 	title: PropTypes.node
 };
 //#endregion

package/es/components/AspectRatio/AspectRatio.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";
 //#region src/components/AspectRatio/AspectRatio.tsx
@@ -32,9 +32,28 @@ const AspectRatio = ({ as: BaseComponent = "div", className: containerClassName,
 	});
 };
 AspectRatio.propTypes = {
+	/**
+	* Provide a custom component or string to be rendered as the outermost node
+	* of the component. This is useful if you want to deviate from the default
+	* `div` tag, where you could specify `section` or `article` instead.
+	*
+	* ```jsx
+	* <AspectRatio as="article">My content</AspectRatio>
+	* ```
+	*/
 	as: PropTypes.elementType,
+	/**
+	* Specify the content that will be placed in the aspect ratio
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify a class name for the outermost node of the component
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify the ratio to be used by the aspect ratio container. This will
+	* determine what aspect ratio your content will be displayed in.
+	*/
 	ratio: PropTypes.oneOf([
 		"16x9",
 		"9x16",

package/es/components/BadgeIndicator/index.js

@@ -6,8 +6,8 @@
  */
 
 import { usePrefix } from "../../internal/usePrefix.js";
-import { forwardRef } from "react";
 import classNames from "classnames";
+import { forwardRef } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 const BadgeIndicator = forwardRef((props, ref) => {
@@ -23,8 +23,17 @@ const BadgeIndicator = forwardRef((props, ref) => {
 	});
 });
 BadgeIndicator.propTypes = {
+	/**
+	* Specify an optional className to add.
+	*/
 	className: PropTypes.string,
+	/**
+	* Count of badge indicator
+	*/
 	count: PropTypes.number,
+	/**
+	* Provide an `id` to uniquely identify the BadgeIndidcator
+	*/
 	id: PropTypes.string
 };
 //#endregion

package/es/components/Breadcrumb/Breadcrumb.Skeleton.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";
 //#region src/components/Breadcrumb/Breadcrumb.Skeleton.tsx
@@ -41,9 +41,21 @@ function BreadcrumbSkeleton({ className, items = 3, noTrailingSlash, size, ...re
 	});
 }
 BreadcrumbSkeleton.propTypes = {
+	/**
+	* Specify an optional className to add.
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify the number of items
+	*/
 	items: PropTypes.number,
+	/**
+	* Optional prop to omit the trailing slash for the breadcrumbs
+	*/
 	noTrailingSlash: PropTypes.bool,
+	/**
+	* Specify the size of the Breadcrumb. Currently supports the following: `sm` & `md` (default: 'md')
+	*/
 	size: PropTypes.oneOf(["sm", "md"])
 };
 //#endregion

package/es/components/Breadcrumb/Breadcrumb.js

@@ -6,8 +6,8 @@
  */
 
 import { usePrefix } from "../../internal/usePrefix.js";
-import { forwardRef } from "react";
 import classNames from "classnames";
+import { forwardRef } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/Breadcrumb/Breadcrumb.tsx
@@ -38,10 +38,26 @@ const Breadcrumb = forwardRef((props, ref) => {
 });
 Breadcrumb.displayName = "Breadcrumb";
 Breadcrumb.propTypes = {
+	/**
+	* Specify the label for the breadcrumb container
+	*/
 	"aria-label": PropTypes.string,
+	/**
+	* Pass in the BreadcrumbItem's for your Breadcrumb
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Optional prop to omit the trailing slash for the breadcrumbs
+	*/
 	noTrailingSlash: PropTypes.bool,
+	/**
+	* Specify the size of the Breadcrumb. Currently
+	* supports the following: `sm` & `md` (default: 'md')
+	*/
 	size: PropTypes.oneOf(["sm", "md"])
 };
 //#endregion

package/es/components/Breadcrumb/BreadcrumbItem.js

@@ -8,8 +8,8 @@
 import { usePrefix } from "../../internal/usePrefix.js";
 import { Text } from "../Text/Text.js";
 import Link_default from "../Link/index.js";
-import React, { cloneElement, forwardRef, isValidElement } from "react";
 import classNames from "classnames";
+import React, { cloneElement, forwardRef, isValidElement } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 import { OverflowMenuHorizontal } from "@carbon/icons-react";
@@ -80,9 +80,21 @@ BreadcrumbItem.propTypes = {
 		"date",
 		"time"
 	])]),
+	/**
+	* Pass in content that will be inside of the BreadcrumbItem
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Optional string representing the link location for the BreadcrumbItem
+	*/
 	href: PropTypes.string,
+	/**
+	* Provide if this breadcrumb item represents the current page
+	*/
 	isCurrentPage: PropTypes.bool
 };
 //#endregion

package/es/components/Button/Button.Skeleton.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";
 //#region src/components/Button/Button.Skeleton.tsx
@@ -42,8 +42,19 @@ const ButtonSkeleton = ({ className, small = false, href, size = "lg", ...rest }
 	return href ? anchor : button;
 };
 ButtonSkeleton.propTypes = {
+	/**
+	* Specify an optional className to add.
+	*/
 	className: PropTypes.string,
+	/**
+	* Optionally specify an href for your Button to become an `<a>` element
+	*/
 	href: PropTypes.string,
+	/**
+	* Specify the size of the button, from a list of available sizes.
+	* For `default` buttons, this prop can remain unspecified or use `default`.
+	* In the next major release of Carbon, `default`, `field`, and `small` will be removed
+	*/
 	size: PropTypes.oneOf([
 		"xs",
 		"sm",
@@ -52,6 +63,12 @@ ButtonSkeleton.propTypes = {
 		"xl",
 		"2xl"
 	]),
+	/**
+	* @deprecated This property will be removed in the next major Carbon version,
+	* use size={sm} instead.
+	*
+	* Specify whether the Button should be a small variant
+	*/
 	small: PropTypes.bool
 };
 //#endregion

package/es/components/Button/Button.js

@@ -91,24 +91,64 @@ const Button = React.forwardRef((props, ref) => {
 });
 Button.displayName = "Button";
 Button.propTypes = {
+	/**
+	* Specify how the button itself should be rendered.
+	* Make sure to apply all props to the root node and render children appropriately
+	*/
 	as: PropTypes.oneOfType([
 		PropTypes.func,
 		PropTypes.string,
 		PropTypes.elementType
 	]),
+	/**
+	* **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 the content of your Button
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be added to your Button
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify the message read by screen readers for the danger button variants
+	*/
 	dangerDescription: PropTypes.string,
+	/**
+	* Specify whether the Button should be disabled, or not
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Specify if the button is an icon-only button
+	*/
 	hasIconOnly: PropTypes.bool,
+	/**
+	* Optionally specify an href for your Button to become an `<a>` element
+	*/
 	href: PropTypes.string,
+	/**
+	* If specifying the `renderIcon` prop, provide a description for that icon that can
+	* be read by screen readers
+	*/
 	iconDescription: (props) => {
 		if (props.renderIcon && !props.children && !props.iconDescription) return /* @__PURE__ */ new Error("renderIcon property specified without also providing an iconDescription property.");
 		return null;
 	},
+	/**
+	* Specify whether the Button is expressive, or not
+	*/
 	isExpressive: PropTypes.bool,
+	/**
+	* Specify whether the Button is currently selected. Only applies to the icon only Ghost variant.
+	*/
 	isSelected: PropTypes.bool,
+	/**
+	* Specify the kind of Button you want to create
+	*/
 	kind: (props, propName, componentName) => {
 		const { hasIconOnly } = props;
 		const validKinds = hasIconOnly ? IconButtonKinds : ButtonKinds;
@@ -116,14 +156,46 @@ Button.propTypes = {
 		if (!validKinds.includes(props[propName])) return /* @__PURE__ */ new Error(`Invalid prop \`${propName}\` supplied to \`${componentName}\`. Expected one of ${validKinds.join(", ")}.`);
 		return null;
 	},
+	/**
+	* Provide an optional function to be called when the button element
+	* loses focus
+	*/
 	onBlur: PropTypes.func,
+	/**
+	* Provide an optional function to be called when the button element
+	* is clicked
+	*/
 	onClick: PropTypes.func,
+	/**
+	* Provide an optional function to be called when the button element
+	* receives focus
+	*/
 	onFocus: PropTypes.func,
+	/**
+	* Provide an optional function to be called when the mouse
+	* enters the button element
+	*/
 	onMouseEnter: PropTypes.func,
+	/**
+	* Provide an optional function to be called when the mouse
+	* leaves the button element
+	*/
 	onMouseLeave: PropTypes.func,
+	/**
+	* Optionally specify a `rel` when using an `<a>` element.
+	*/
 	rel: PropTypes.string,
+	/**
+	* A component used to render an icon.
+	*/
 	renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
+	/**
+	* Optional prop to specify the role of the Button
+	*/
 	role: PropTypes.string,
+	/**
+	* Specify the size of the button, from the following list of sizes:
+	*/
 	size: PropTypes.oneOf([
 		"xs",
 		"sm",
@@ -132,21 +204,45 @@ Button.propTypes = {
 		"xl",
 		"2xl"
 	]),
+	/**
+	* Optional prop to specify the tabIndex of the Button
+	*/
 	tabIndex: PropTypes.number,
+	/**
+	* Optionally specify a `target` when using an `<a>` element.
+	*/
 	target: PropTypes.string,
+	/**
+	* Specify the alignment of the tooltip to the icon-only button.
+	* Can be one of: `start`, `center`, or `end`.
+	*/
 	tooltipAlignment: PropTypes.oneOf([
 		"start",
 		"center",
 		"end"
 	]),
+	/**
+	* Enable drop shadow for tooltips for icon-only buttons.
+	*/
 	tooltipDropShadow: PropTypes.bool,
+	/**
+	* Enable high-contrast theme for tooltips for icon-only buttons.
+	* Defaults to true.
+	*/
 	tooltipHighContrast: PropTypes.bool,
+	/**
+	* Specify the direction of the tooltip for icon-only buttons.
+	* Can be either `top`, `right`, `bottom`, or `left`.
+	*/
 	tooltipPosition: PropTypes.oneOf([
 		"top",
 		"right",
 		"bottom",
 		"left"
 	]),
+	/**
+	* Optional prop to specify the type of the Button
+	*/
 	type: PropTypes.oneOf([
 		"button",
 		"reset",