@carbon/react 1.110.0 → 1.111.0-rc.0

package/es/components/DataTable/DataTable.js

@@ -452,25 +452,68 @@ DataTable.TableToolbarContent = TableToolbarContent;
 DataTable.TableToolbarSearch = TableToolbarSearch;
 DataTable.TableToolbarMenu = TableToolbarMenu;
 DataTable.propTypes = {
+	/**
+	* Pass in the children that will be rendered within the Table
+	*/
 	children: PropTypes.func,
+	/**
+	* Experimental property. Allows table to align cell contents to the top if there is text wrapping in the content. Might have performance issues, intended for smaller tables
+	*/
 	experimentalAutoAlign: PropTypes.bool,
+	/**
+	* Optional hook to manually control filtering of the rows from the
+	* TableToolbarSearch component
+	*/
 	filterRows: PropTypes.func,
+	/**
+	* The `headers` prop represents the order in which the headers should
+	* appear in the table. We expect an array of objects to be passed in, where
+	* `key` is the name of the key in a row object, and `header` is the name of
+	* the header.
+	*/
 	headers: PropTypes.arrayOf(PropTypes.shape({
 		key: PropTypes.string.isRequired,
 		header: PropTypes.node.isRequired,
 		isSortable: PropTypes.bool
 	})).isRequired,
+	/**
+	* Specify whether the table should be able to be sorted by its headers
+	*/
 	isSortable: PropTypes.bool,
+	/**
+	* Provide a string for the current locale
+	*/
 	locale: PropTypes.string,
+	/**
+	* Specify whether the overflow menu (if it exists) should be shown always, or only on hover
+	*/
 	overflowMenuOnHover: PropTypes.bool,
+	/**
+	* Specify whether the control should be a radio button or inline checkbox
+	*/
 	radio: PropTypes.bool,
+	/**
+	* @deprecated Use `children` instead. This prop will be removed in
+	* the next major version.
+	*
+	* https://www.patterns.dev/react/render-props-pattern/#children-as-a-function
+	*/
 	render: deprecate(PropTypes.func),
+	/**
+	* The `rows` prop is where you provide us with a list of all the rows that
+	* you want to render in the table. The only hard requirement is that this
+	* is an array of objects, and that each object has a unique `id` field
+	* available on it.
+	*/
 	rows: PropTypes.arrayOf(PropTypes.shape({
 		id: PropTypes.string.isRequired,
 		disabled: PropTypes.bool,
 		isSelected: PropTypes.bool,
 		isExpanded: PropTypes.bool
 	})).isRequired,
+	/**
+	*  Change the row height of table. Currently supports `xs`, `sm`, `md`, `lg`, and `xl`.
+	*/
 	size: PropTypes.oneOf([
 		"xs",
 		"sm",
@@ -478,10 +521,26 @@ DataTable.propTypes = {
 		"lg",
 		"xl"
 	]),
+	/**
+	* Optional hook to manually control sorting of the rows.
+	*/
 	sortRow: PropTypes.func,
+	/**
+	* Specify whether the header should be sticky.
+	* Still experimental: may not work with every combination of table props
+	*/
 	stickyHeader: PropTypes.bool,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: PropTypes.func,
+	/**
+	* If `true`, sets the table width to `auto` instead of `100%`.
+	*/
 	useStaticWidth: PropTypes.bool,
+	/**
+	* `true` to add useZebraStyles striping.
+	*/
 	useZebraStyles: PropTypes.bool
 };
 //#endregion

package/es/components/DataTable/Table.js

@@ -9,8 +9,8 @@ import { usePrefix } from "../../internal/usePrefix.js";
 import useIsomorphicEffect from "../../internal/useIsomorphicEffect.js";
 import { useWindowEvent } from "../../internal/useEvent.js";
 import { TableContext } from "./TableContext.js";
-import { useCallback, useContext, useRef } from "react";
 import classNames from "classnames";
+import { useCallback, useContext, useRef } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 import { debounce } from "es-toolkit/compat";
@@ -101,11 +101,26 @@ const Table = ({ className, children, useZebraStyles, size = "lg", isSortable =
 	}) : table;
 };
 Table.propTypes = {
+	/**
+	* Pass in the children that will be rendered within the Table
+	*/
 	children: PropTypes.node,
 	className: PropTypes.string,
+	/**
+	* Experimental property. Allows table to align cell contents to the top if there is text wrapping in the content. Might have performance issues, intended for smaller tables
+	*/
 	experimentalAutoAlign: PropTypes.bool,
+	/**
+	* `false` If true, will apply sorting styles
+	*/
 	isSortable: PropTypes.bool,
+	/**
+	* Specify whether the overflow menu (if it exists) should be shown always, or only on hover
+	*/
 	overflowMenuOnHover: PropTypes.bool,
+	/**
+	*  Change the row height of table. Currently supports `xs`, `sm`, `md`, `lg`, and `xl`.
+	*/
 	size: PropTypes.oneOf([
 		"xs",
 		"sm",
@@ -113,9 +128,21 @@ Table.propTypes = {
 		"lg",
 		"xl"
 	]),
+	/**
+	* `false` If true, will keep the header sticky (only data rows will scroll)
+	*/
 	stickyHeader: PropTypes.bool,
+	/**
+	* If `true`, sets the table width to `auto` instead of `100%`.
+	*/
 	useStaticWidth: PropTypes.bool,
+	/**
+	* `true` to add useZebraStyles striping.
+	*/
 	useZebraStyles: PropTypes.bool,
+	/**
+	* Specify the table tabIndex
+	*/
 	tabIndex: PropTypes.number
 };
 //#endregion

package/es/components/DataTable/TableBatchAction.js

@@ -23,10 +23,20 @@ const TableBatchAction = ({ renderIcon = AddFilled, iconDescription = "Add", ...
 	...props
 });
 TableBatchAction.propTypes = {
+	/**
+	* Specify if the button is an icon-only button
+	*/
 	hasIconOnly: PropTypes.bool,
+	/**
+	* 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.");
 	},
+	/**
+	* A component used to render an icon.
+	*/
 	renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object])
 };
 //#endregion

package/es/components/DataTable/TableBatchActions.js

@@ -9,8 +9,8 @@ import { usePrefix } from "../../internal/usePrefix.js";
 import { Text } from "../Text/Text.js";
 import Button_default from "../Button/index.js";
 import TableActionList from "./TableActionList.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/DataTable/TableBatchActions.tsx
@@ -83,11 +83,35 @@ const TableBatchActions = ({ className, children, shouldShowBatchActions, totalS
 TableBatchActions.propTypes = {
 	children: PropTypes.node,
 	className: PropTypes.string,
+	/**
+	* Hook required to listen for when the user initiates a cancel request
+	* through this component
+	*/
 	onCancel: PropTypes.func.isRequired,
+	/**
+	* Hook to listen for when the user initiates a select all
+	* request through this component. This _only_ controls the rendering
+	* of the `Select All` button and does not include built in functionality
+	*/
 	onSelectAll: PropTypes.func,
+	/**
+	* Boolean specifier for whether or not the batch action bar should be
+	* displayed
+	*/
 	shouldShowBatchActions: PropTypes.bool,
+	/**
+	* Numeric representation of the total number of items in a table.
+	* This number is used in the select all button text
+	*/
 	totalCount: PropTypes.number,
+	/**
+	* Numeric representation of the total number of items selected in a table.
+	* This number is used to derive the selection message
+	*/
 	totalSelected: PropTypes.number.isRequired,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: PropTypes.func
 };
 //#endregion

package/es/components/DataTable/TableBody.js

@@ -22,6 +22,9 @@ const TableBody = ({ children, className, ...rest }) => /* @__PURE__ */ jsx("tbo
 	children
 });
 TableBody.propTypes = {
+	/**
+	* `polite` Adjust the notification behavior of screen readers
+	*/
 	"aria-live": PropTypes.oneOf([
 		"polite",
 		"assertive",

package/es/components/DataTable/TableCell.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/DataTable/TableCell.tsx
@@ -30,10 +30,25 @@ const TableCell = forwardRef((props, ref) => {
 });
 TableCell.displayName = "TableCell";
 TableCell.propTypes = {
+	/**
+	* Pass in children that will be embedded in the table header label
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* The width of the expanded row's internal cell
+	*/
 	colSpan: PropTypes.number,
+	/**
+	* Specify if the table cell is in an AI column
+	*/
 	hasAILabelHeader: PropTypes.bool,
+	/**
+	* The id of the matching th node in the table head. Addresses a11y concerns outlined here: https://www.ibm.com/able/guidelines/ci162/info_and_relationships.html and https://www.w3.org/TR/WCAG20-TECHS/H43
+	*/
 	headers: PropTypes.string
 };
 //#endregion

package/es/components/DataTable/TableContainer.js

@@ -9,8 +9,8 @@ import { usePrefix } from "../../internal/usePrefix.js";
 import { useId } from "../../internal/useId.js";
 import { TableContext } from "./TableContext.js";
 import { Heading, Section } from "../Heading/index.js";
-import { useMemo } from "react";
 import classNames from "classnames";
+import { useMemo } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/DataTable/TableContainer.tsx
@@ -71,13 +71,31 @@ const TableContainer = ({ aiEnabled, className, children, decorator, title, desc
 	});
 };
 TableContainer.propTypes = {
+	/**
+	* Specify if the entire table has AI generated contents
+	*/
 	aiEnabled: PropTypes.bool,
 	children: PropTypes.node,
 	className: PropTypes.string,
+	/**
+	* **Experimental**: Provide a `decorator` component to be rendered inside the `TableContainer` component
+	*/
 	decorator: PropTypes.node,
+	/**
+	* Optional description text for the Table
+	*/
 	description: PropTypes.node,
+	/**
+	* Specify whether the table should have a sticky header
+	*/
 	stickyHeader: PropTypes.bool,
+	/**
+	* Provide a title for the Table
+	*/
 	title: PropTypes.node,
+	/**
+	* If true, will use a width of 'fit-content' to match the inner table width
+	*/
 	useStaticWidth: PropTypes.bool
 };
 //#endregion

package/es/components/DataTable/TableDecoratorRow.js

@@ -8,8 +8,8 @@
 import { usePrefix } from "../../internal/usePrefix.js";
 import { isComponentElement } from "../../internal/utils.js";
 import { AILabel } from "../AILabel/index.js";
-import { cloneElement } from "react";
 import classNames from "classnames";
+import { cloneElement } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/DataTable/TableDecoratorRow.tsx
@@ -32,7 +32,13 @@ const TableDecoratorRow = ({ className, decorator }) => {
 };
 TableDecoratorRow.displayName = "TableDecoratorRow";
 TableDecoratorRow.propTypes = {
+	/**
+	* The CSS class names of the cell that wraps the underlying input control
+	*/
 	className: PropTypes.string,
+	/**
+	* **Experimental**: Provide a `decorator` component to be rendered inside the `TableDecoratorRow` component
+	*/
 	decorator: PropTypes.node
 };
 //#endregion

package/es/components/DataTable/TableExpandHeader.js

@@ -8,8 +8,8 @@
 import { usePrefix } from "../../internal/usePrefix.js";
 import { deprecate } from "../../prop-types/deprecate.js";
 import { requiredIfGivenPropIsTruthy } from "../../prop-types/requiredIfGivenPropIsTruthy.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";
@@ -44,16 +44,47 @@ const TableExpandHeader = ({ ["aria-controls"]: ariaControls, ["aria-label"]: ar
 	});
 };
 TableExpandHeader.propTypes = {
+	/**
+	* Space separated list of one or more ID values referencing the TableExpandedRow(s) being controlled by the TableExpandHeader
+	*/
 	["aria-controls"]: PropTypes.string,
+	/**
+	* Specify the string read by a voice reader when the expand trigger is
+	* focused
+	*/
 	["aria-label"]: PropTypes.string,
+	/**
+	* Deprecated, please use `aria-label` instead.
+	* Specify the string read by a voice reader when the expand trigger is
+	* focused
+	*/
 	ariaLabel: PropTypes.string,
 	children: PropTypes.node,
 	className: PropTypes.string,
+	/**
+	* The enableExpando prop is being replaced by TableExpandHeader
+	*/
 	enableExpando: deprecate(PropTypes.bool, "The `enableExpando` prop has been deprecated in favor of `enableToggle`. This prop will be removed in the next major release."),
+	/**
+	* Specify whether an expand all button should be displayed
+	*/
 	enableToggle: PropTypes.bool,
+	/**
+	* The description of the chevron right icon, to be put in its SVG `<title>` element.
+	*/
 	expandIconDescription: PropTypes.string,
+	/**
+	* Supply an id to the th element.
+	*/
 	id: PropTypes.string,
+	/**
+	* Specify whether this row is expanded or not. This helps coordinate data
+	* attributes so that `TableExpandRow` and `TableExpandedRow` work together
+	*/
 	isExpanded: requiredIfGivenPropIsTruthy("enableToggle", PropTypes.bool),
+	/**
+	* Hook for when a listener initiates a request to expand the given row
+	*/
 	onExpand: PropTypes.oneOfType([requiredIfGivenPropIsTruthy("enableExpando", PropTypes.func), requiredIfGivenPropIsTruthy("enableToggle", PropTypes.func)])
 };
 //#endregion

package/es/components/DataTable/TableExpandRow.js

@@ -11,8 +11,8 @@ import { AILabel } from "../AILabel/index.js";
 import TableCell from "./TableCell.js";
 import TableDecoratorRow from "./TableDecoratorRow.js";
 import TableSlugRow from "./TableSlugRow.js";
-import { Children, forwardRef } from "react";
 import classNames from "classnames";
+import { Children, forwardRef } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { ChevronRight } from "@carbon/icons-react";
@@ -75,15 +75,44 @@ const TableExpandRow = forwardRef(({ ["aria-controls"]: ariaControls, ["aria-lab
 	});
 });
 TableExpandRow.propTypes = {
+	/**
+	* Space separated list of one or more ID values referencing the TableExpandedRow(s) being controlled by the TableExpandRow
+	* TODO: make this required in v12
+	*/
 	"aria-controls": PropTypes.string,
+	/**
+	* Specify the string read by a voice reader when the expand trigger is
+	* focused
+	*/
 	"aria-label": PropTypes.string,
+	/**
+	* Deprecated, please use `aria-label` instead.
+	* Specify the string read by a voice reader when the expand trigger is
+	* focused
+	*/
 	ariaLabel: PropTypes.string,
 	children: PropTypes.node,
 	className: PropTypes.string,
+	/**
+	* The id of the matching th node in the table head. Addresses a11y concerns outlined here: https://www.ibm.com/able/guidelines/ci162/info_and_relationships.html and https://www.w3.org/TR/WCAG20-TECHS/H43
+	*/
 	expandHeader: PropTypes.string,
+	/**
+	* The description of the chevron right icon, to be put in its SVG `<title>` element.
+	*/
 	expandIconDescription: PropTypes.string,
+	/**
+	* Specify whether this row is expanded or not. This helps coordinate data
+	* attributes so that `TableExpandRow` and `TableExpandedRow` work together
+	*/
 	isExpanded: PropTypes.bool,
+	/**
+	* Specify if the row is selected
+	*/
 	isSelected: PropTypes.bool,
+	/**
+	* Hook for when a listener initiates a request to expand the given row
+	*/
 	onExpand: PropTypes.func.isRequired
 };
 TableExpandRow.displayName = "TableExpandRow";

package/es/components/DataTable/TableExpandedRow.js

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import TableCell from "./TableCell.js";
-import { useRef } from "react";
 import classNames from "classnames";
+import { useRef } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/DataTable/TableExpandedRow.tsx
@@ -46,8 +46,17 @@ const TableExpandedRow = ({ className: customClassName, children, colSpan, ...re
 	});
 };
 TableExpandedRow.propTypes = {
+	/**
+	* Pass in the contents for your TableExpandedRow
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* The width of the expanded row's internal cell
+	*/
 	colSpan: PropTypes.number.isRequired
 };
 //#endregion

package/es/components/DataTable/TableHeader.js

@@ -10,8 +10,8 @@ import { useId } from "../../internal/useId.js";
 import { isComponentElement } from "../../internal/utils.js";
 import { AILabel } from "../AILabel/index.js";
 import { sortStates } from "./state/sortStates.js";
-import { cloneElement, forwardRef, useRef } from "react";
 import classNames from "classnames";
+import { cloneElement, forwardRef, useRef } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { ArrowUp, ArrowsVertical } from "@carbon/icons-react";
@@ -135,15 +135,50 @@ const TableHeader = forwardRef((props, ref) => {
 	});
 });
 TableHeader.propTypes = {
+	/**
+	* Pass in children that will be embedded in the table header label
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify `colSpan` as a non-negative integer value to indicate how
+	* many columns the TableHeader cell extends in a table
+	*/
 	colSpan: PropTypes.number,
+	/**
+	* Supply an id to the th element.
+	*/
 	id: PropTypes.string,
+	/**
+	* Specify whether this header is the header by which a table is being sorted
+	* by
+	*/
 	isSortHeader: PropTypes.bool,
+	/**
+	* Specify whether this header is one through which a user can sort the table
+	*/
 	isSortable: PropTypes.bool,
+	/**
+	* Hook that is invoked when the header is clicked
+	*/
 	onClick: PropTypes.func,
+	/**
+	* Specify the scope of this table header. You can find more info about this
+	* attribute at the following URL:
+	* https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th#attr-scope
+	*/
 	scope: PropTypes.string,
+	/**
+	* Specify which direction we are currently sorting by, should be one of DESC,
+	* NONE, or ASC.
+	*/
 	sortDirection: PropTypes.oneOf(Object.values(sortStates)),
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: PropTypes.func
 };
 TableHeader.displayName = "TableHeader";

package/es/components/DataTable/TableRow.js

@@ -10,8 +10,8 @@ import { isComponentElement } from "../../internal/utils.js";
 import { AILabel } from "../AILabel/index.js";
 import TableDecoratorRow from "./TableDecoratorRow.js";
 import TableSlugRow from "./TableSlugRow.js";
-import { Children, forwardRef } from "react";
 import classNames from "classnames";
+import { Children, forwardRef } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/DataTable/TableRow.tsx
@@ -39,12 +39,33 @@ const TableRow = forwardRef((props, ref) => {
 	});
 });
 TableRow.propTypes = {
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify if the row is selected
+	*/
 	isSelected: PropTypes.bool,
+	/**
+	* Non-standard alias for `aria-label`.
+	*/
 	ariaLabel: PropTypes.string,
+	/**
+	* Accessible label for the row element.
+	*/
 	"aria-label": PropTypes.string,
+	/**
+	* Associates this row with the id of the corresponding expanded row content.
+	*/
 	"aria-controls": PropTypes.string,
+	/**
+	* Handler called when the row’s expand toggle is clicked.
+	*/
 	onExpand: PropTypes.func,
+	/**
+	* Flag indicating whether the row is currently expanded.
+	*/
 	isExpanded: PropTypes.bool
 };
 //#endregion

package/es/components/DataTable/TableSelectAll.js

@@ -8,8 +8,8 @@
 import { usePrefix } from "../../internal/usePrefix.js";
 import { deprecate } from "../../prop-types/deprecate.js";
 import InlineCheckbox_default from "../InlineCheckbox/index.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/DataTable/TableSelectAll.tsx
@@ -36,14 +36,42 @@ const TableSelectAll = ({ ariaLabel: deprecatedAriaLabel = "Select all rows in t
 	});
 };
 TableSelectAll.propTypes = {
+	/**
+	* Specify the aria label for the underlying input control
+	*/
 	["aria-label"]: PropTypes.string,
+	/**
+	* Deprecated, please use `aria-label` instead.
+	* Specify the aria label for the underlying input control
+	*/
 	ariaLabel: deprecate(PropTypes.string, "This prop syntax has been deprecated. Please use the new `aria-label`."),
+	/**
+	* Specify whether all items are selected, or not
+	*/
 	checked: PropTypes.bool,
+	/**
+	* The CSS class names of the cell that wraps the underlying input control
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the checkbox input should be disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Provide an `id` for the underlying input control
+	*/
 	id: PropTypes.string.isRequired,
+	/**
+	* Specify whether the selection only has a subset of all items
+	*/
 	indeterminate: PropTypes.bool,
+	/**
+	* Provide a `name` for the underlying input control
+	*/
 	name: PropTypes.string.isRequired,
+	/**
+	* Provide a handler to listen to when a user initiates a selection request
+	*/
 	onSelect: PropTypes.func.isRequired
 };
 //#endregion