@carbon/react 1.110.0 → 1.111.0-rc.0

package/es/components/Pagination/Pagination.js

@@ -11,8 +11,8 @@ import { IconButton } from "../IconButton/index.js";
 import { usePreviousValue } from "../../internal/usePreviousValue.js";
 import Select_default from "../Select/index.js";
 import SelectItem_default from "../SelectItem/index.js";
-import React, { useEffect, useMemo, useRef, useState } from "react";
 import classNames from "classnames";
+import React, { useEffect, useMemo, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { CaretLeft, CaretRight } from "@carbon/icons-react";
@@ -52,7 +52,7 @@ const getPageSize = (pageSizes, pageSize) => {
 	}
 	return pageSizes[0].value;
 };
-const Pagination = React.forwardRef(({ backwardText = "Previous page", className: customClassName = "", disabled = false, forwardText = "Next page", id, isLastPage = false, itemText = (min, max) => `${min}–${max} items`, itemRangeText = (min, max, total) => `${min}–${max} of ${total} items`, itemsPerPageText = "Items per page:", onChange, pageNumberText: _pageNumberText, pageRangeText = (_current, total) => `of ${total} ${total === 1 ? "page" : "pages"}`, pageSelectLabelText = (total) => `Page of ${total} ${total === 1 ? "page" : "pages"}`, page: controlledPage = 1, pageInputDisabled, pageSize: controlledPageSize, pageSizeInputDisabled, pageSizes: controlledPageSizes, pageText = (page) => `page ${page}`, pagesUnknown = false, size = "md", totalItems, ...rest }, ref) => {
+const Pagination = React.forwardRef(({ backwardText = "Previous page", backwardTextTooltipPosition = "top", className: customClassName = "", disabled = false, forwardText = "Next page", forwardTextTooltipPosition = "top", id, isLastPage = false, itemText = (min, max) => `${min}–${max} items`, itemRangeText = (min, max, total) => `${min}–${max} of ${total} items`, itemsPerPageText = "Items per page:", onChange, pageNumberText: _pageNumberText, pageRangeText = (_current, total) => `of ${total} ${total === 1 ? "page" : "pages"}`, pageSelectLabelText = (total) => `Page of ${total} ${total === 1 ? "page" : "pages"}`, page: controlledPage = 1, pageInputDisabled, pageSize: controlledPageSize, pageSizeInputDisabled, pageSizes: controlledPageSizes, pageText = (page) => `page ${page}`, pagesUnknown = false, size = "md", totalItems, ...rest }, ref) => {
 	const prefix = usePrefix();
 	const inputId = useFallbackId(id?.toString());
 	const backBtnRef = useRef(null);
@@ -239,7 +239,7 @@ const Pagination = React.forwardRef(({ backwardText = "Previous page", className
 			})] }), /* @__PURE__ */ jsxs("div", {
 				className: `${prefix}--pagination__control-buttons`,
 				children: [/* @__PURE__ */ jsx(IconButton, {
-					align: "top",
+					align: backwardTextTooltipPosition,
 					disabled: backButtonDisabled,
 					kind: "ghost",
 					className: backButtonClasses,
@@ -249,7 +249,7 @@ const Pagination = React.forwardRef(({ backwardText = "Previous page", className
 					ref: backBtnRef,
 					children: /* @__PURE__ */ jsx(CaretLeft, {})
 				}), /* @__PURE__ */ jsx(IconButton, {
-					align: "top",
+					align: forwardTextTooltipPosition,
 					disabled: forwardButtonDisabled || isLastPage,
 					kind: "ghost",
 					className: forwardButtonClasses,
@@ -264,35 +264,117 @@ const Pagination = React.forwardRef(({ backwardText = "Previous page", className
 	});
 });
 Pagination.propTypes = {
+	/**
+	* The description for the backward icon.
+	*/
 	backwardText: PropTypes.string,
+	/**
+	* The tooltip position for the backward button.
+	*/
+	backwardTextTooltipPosition: PropTypes.oneOf([
+		"top",
+		"right",
+		"bottom",
+		"left"
+	]),
+	/**
+	* The CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* `true` if the backward/forward buttons, as well as the page select elements,  should be disabled.
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* The description for the forward icon.
+	*/
 	forwardText: PropTypes.string,
+	/**
+	* The tooltip position for the forward button.
+	*/
+	forwardTextTooltipPosition: PropTypes.oneOf([
+		"top",
+		"right",
+		"bottom",
+		"left"
+	]),
+	/**
+	* The unique ID of this component instance.
+	*/
 	id: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+	/**
+	* `true` if the current page should be the last page.
+	*/
 	isLastPage: PropTypes.bool,
+	/**
+	* The function returning a translatable text showing where the current page is,
+	* in a manner of the range of items.
+	*/
 	itemRangeText: PropTypes.func,
+	/**
+	* A variant of `itemRangeText`, used if the total number of items is unknown.
+	*/
 	itemText: PropTypes.func,
+	/**
+	* The translatable text indicating the number of items per page.
+	*/
 	itemsPerPageText: PropTypes.string,
+	/**
+	* The callback function called when the current page changes.
+	*/
 	onChange: PropTypes.func,
+	/**
+	* The current page.
+	*/
 	page: PropTypes.number,
+	/**
+	* `true` if the select box to change the page should be disabled.
+	*/
 	pageInputDisabled: PropTypes.bool,
 	pageNumberText: PropTypes.string,
+	/**
+	* A function returning PII showing where the current page is.
+	*/
 	pageRangeText: PropTypes.func,
+	/**
+	* A function returning the label for the page select.
+	*/
 	pageSelectLabelText: PropTypes.func,
+	/**
+	* The number dictating how many items a page contains.
+	*/
 	pageSize: PropTypes.number,
+	/**
+	* `true` if the select box to change the items per page should be disabled.
+	*/
 	pageSizeInputDisabled: PropTypes.bool,
+	/**
+	* The choices for `pageSize`.
+	*/
 	pageSizes: PropTypes.oneOfType([PropTypes.arrayOf(PropTypes.number.isRequired), PropTypes.arrayOf(PropTypes.shape({
 		text: PropTypes.string.isRequired,
 		value: PropTypes.number.isRequired
 	}).isRequired)]).isRequired,
+	/**
+	* The translatable text showing the current page.
+	*/
 	pageText: PropTypes.func,
+	/**
+	* `true` if the total number of items is unknown.
+	*/
 	pagesUnknown: PropTypes.bool,
+	/**
+	* Specify the size of the Pagination.
+	*/
 	size: PropTypes.oneOf([
 		"xs",
 		"sm",
 		"md",
 		"lg"
 	]),
+	/**
+	* The total number of items.
+	*/
 	totalItems: PropTypes.number
 };
 //#endregion

package/es/components/Pagination/experimental/PageSelector.js

@@ -9,8 +9,8 @@ import { usePrefix } from "../../../internal/usePrefix.js";
 import { useId } from "../../../internal/useId.js";
 import Select_default from "../../Select/index.js";
 import SelectItem_default from "../../SelectItem/index.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/Pagination/experimental/PageSelector.js
@@ -37,10 +37,18 @@ function PageSelector({ className = null, currentPage, id = 1, labelText = "Curr
 	});
 }
 PageSelector.propTypes = {
+	/** Extra class names to add. */
 	className: PropTypes.string,
+	/** The current page. */
 	currentPage: PropTypes.number.isRequired,
+	/** The unique ID of this component instance. */
 	id: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+	/** Translatable string to label the page selector element. */
 	labelText: PropTypes.string,
+	/**
+	* Total number of pages.
+	* This value is calculated using a valid `totalItems` prop passed to the parent `Unstable_Pagination`.
+	*/
 	totalPages: PropTypes.number.isRequired
 };
 //#endregion

package/es/components/Pagination/experimental/Pagination.js

@@ -9,8 +9,8 @@ import { usePrefix } from "../../../internal/usePrefix.js";
 import { IconButton } from "../../IconButton/index.js";
 import Select_default from "../../Select/index.js";
 import SelectItem_default from "../../SelectItem/index.js";
-import { useState } from "react";
 import classNames from "classnames";
+import { useState } from "react";
 import PropTypes from "prop-types";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { CaretLeft, CaretRight } from "@carbon/icons-react";
@@ -131,22 +131,76 @@ function Pagination({ backwardText = "Previous page", children = void 0, classNa
 	});
 }
 Pagination.propTypes = {
+	/**
+	* The description for the backward icon.
+	*/
 	backwardText: PropTypes.string,
+	/**
+	* The children of the pagination component.
+	*/
 	children: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+	/**
+	* Extra classes to add.
+	*/
 	className: PropTypes.string,
+	/**
+	* `true` if the backward/forward buttons should be disabled.
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* The description for the forward icon.
+	*/
 	forwardText: PropTypes.string,
+	/** The unique ID of this component instance. */
 	id: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+	/**
+	* The initial active page when the component is first mounted.
+	*/
 	initialPage: PropTypes.number,
+	/**
+	* The function returning a translatable text showing where the current page is,
+	* in a manner of the range of items.
+	*/
 	itemRangeText: PropTypes.func,
+	/**
+	* A variant of `itemRangeText`, used if the total number of items is unknown.
+	*/
 	itemText: PropTypes.func,
+	/**
+	* The translatable text indicating the number of items per page.
+	*/
 	itemsPerPageText: PropTypes.string,
+	/**
+	* The callback function called when the current page changes.
+	*/
 	onChange: PropTypes.func,
+	/**
+	* The function returning a translatable text showing where the current page is,
+	* in a manner of the total number of pages.
+	*/
 	pageRangeText: PropTypes.func,
+	/**
+	* The number dictating how many items a page contains.
+	*/
 	pageSize: PropTypes.number,
+	/**
+	* The choices for `pageSize`.
+	*/
 	pageSizes: PropTypes.arrayOf(PropTypes.number),
+	/**
+	* The translatable text showing the current page.
+	*/
 	pageText: PropTypes.func,
+	/**
+	* `true` if total number of pages is unknown.
+	*/
 	pagesUnknown: PropTypes.bool,
+	/**
+	* The total number of items.
+	* You need to provide total items to calculate total page,
+	* which is required by a child like the `PageSelector`
+	* to know how many pages to display.
+	*/
 	totalItems: PropTypes.number
 };
 //#endregion

package/es/components/PaginationNav/PaginationNav.js

@@ -9,8 +9,8 @@ import { usePrefix } from "../../internal/usePrefix.js";
 import { IconButton } from "../IconButton/index.js";
 import { clamp } from "../../internal/clamp.js";
 import { useMatchMedia } from "../../internal/useMatchMedia.js";
-import React, { useEffect, useRef, useState } from "react";
 import classNames from "classnames";
+import React, { useEffect, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { CaretLeft, CaretRight, OverflowMenuHorizontal } from "@carbon/icons-react";
@@ -288,15 +288,35 @@ const PaginationNav = React.forwardRef(({ className, onChange = () => {}, totalI
 	});
 });
 DirectionButton.propTypes = {
+	/**
+	* The direction this button represents ("forward" or "backward").
+	*/
 	direction: PropTypes.oneOf(["forward", "backward"]),
+	/**
+	* Whether or not the button should be disabled.
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* The label shown in the button's tooltip.
+	*/
 	label: PropTypes.string,
+	/**
+	* The callback function called when the button is clicked.
+	*/
 	onClick: PropTypes.func,
+	/**
+	* Specify how the tooltip should align with the navigation button.
+	* Can be one of: start, center, or end.
+	*/
 	tooltipAlignment: PropTypes.oneOf([
 		"start",
 		"center",
 		"end"
 	]),
+	/**
+	* Specify the position of the tooltip relative to the navigation button.
+	* Can be one of: top, right, bottom, or left.
+	*/
 	tooltipPosition: PropTypes.oneOf([
 		"top",
 		"right",
@@ -305,42 +325,102 @@ DirectionButton.propTypes = {
 	])
 };
 PaginationItem.propTypes = {
+	/**
+	* Whether or not this is the currently active page.
+	*/
 	isActive: PropTypes.bool,
+	/**
+	* The callback function called when the item is clicked.
+	*/
 	onClick: PropTypes.func,
+	/**
+	* The page number this item represents.
+	*/
 	page: PropTypes.number,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: PropTypes.func
 };
 PaginationOverflow.propTypes = {
+	/**
+	* How many items to display in this overflow.
+	*/
 	count: PropTypes.number,
+	/**
+	* From which index on this overflow should start displaying pages.
+	*/
 	fromIndex: PropTypes.number,
+	/**
+	* The callback function called when the user selects a page from the overflow.
+	*/
 	onSelect: PropTypes.func,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: PropTypes.func
 };
 PaginationNav.displayName = "PaginationNav";
 PaginationNav.propTypes = {
+	/**
+	* Additional CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* If true, the '...' pagination overflow will not render page links between the first and last rendered buttons.
+	* Set this to true if you are having performance problems with large data sets.
+	*/
 	disableOverflow: PropTypes.bool,
+	/**
+	* The number of items to be shown (minimum of 4 unless props.items < 4).
+	*/
 	itemsShown: PropTypes.number,
+	/**
+	* Whether user should be able to loop through the items when reaching first / last.
+	*/
 	loop: PropTypes.bool,
+	/**
+	* The callback function called when the current page changes.
+	*/
 	onChange: PropTypes.func,
+	/**
+	* The index of current page.
+	*/
 	page: PropTypes.number,
+	/**
+	* Specify the size of the PaginationNav.
+	*/
 	size: PropTypes.oneOf([
 		"sm",
 		"md",
 		"lg"
 	]),
+	/**
+	* Specify the alignment of the tooltip for the icon-only prev/next buttons.
+	* Can be one of: start, center, or end.
+	*/
 	tooltipAlignment: PropTypes.oneOf([
 		"start",
 		"center",
 		"end"
 	]),
+	/**
+	* Specify the position of the tooltip for the icon-only prev/next buttons.
+	* Can be one of: top, right, bottom, or left.
+	*/
 	tooltipPosition: PropTypes.oneOf([
 		"top",
 		"right",
 		"bottom",
 		"left"
 	]),
+	/**
+	* The total number of items.
+	*/
 	totalItems: PropTypes.number,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: PropTypes.func
 };
 //#endregion

package/es/components/Popover/index.js

@@ -13,8 +13,8 @@ import { useMergedRefs } from "../../internal/useMergedRefs.js";
 import { useEvent, useWindowEvent } from "../../internal/useEvent.js";
 import { mapPopoverAlign } from "../../tools/mapPopoverAlign.js";
 import { useFeatureFlag } from "../FeatureFlags/index.js";
-import React, { forwardRef, useEffect, useMemo, useRef } from "react";
 import classNames from "classnames";
+import React, { forwardRef, useEffect, useMemo, useRef } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { arrow, autoUpdate, flip, hide, offset, useFloating } from "@floating-ui/react";
@@ -254,6 +254,9 @@ const Popover = React.forwardRef(function PopoverRenderFunction({ isTabTip, alig
 });
 Popover.displayName = "Popover";
 Popover.propTypes = {
+	/**
+	* Specify how the popover should align with the trigger element
+	*/
 	align: deprecateValuesWithin(PropTypes.oneOf([
 		"top",
 		"top-left",
@@ -289,10 +292,29 @@ Popover.propTypes = {
 		"right-start",
 		"right-end"
 	], mapPopoverAlign),
+	/**
+	* **Experimental:** Provide an offset value for alignment axis. Only takes effect when `autoalign` is enabled.
+	*/
 	alignmentAxisOffset: PropTypes.number,
+	/**
+	* Provide a custom element or component to render the top-level node for the
+	* component.
+	*/
 	as: PropTypes.oneOfType([PropTypes.string, PropTypes.elementType]),
+	/**
+	* Will auto-align the popover on first render if it is not visible. This prop
+	* is currently experimental and is subject to future changes. Requires
+	* React v17+
+	* @see https://github.com/carbon-design-system/carbon/issues/18714
+	*/
 	autoAlign: PropTypes.bool,
+	/**
+	* Specify the background token to use. Default is 'layer'.
+	*/
 	backgroundToken: PropTypes.oneOf(["layer", "background"]),
+	/**
+	* Specify a bounding element to be used for autoAlign calculations. The viewport is used by default. This prop is currently experimental and is subject to future changes.
+	*/
 	autoAlignBoundary: PropTypes.oneOfType([
 		PropTypes.oneOf(["clippingAncestors"]),
 		PropTypes.elementType,
@@ -304,14 +326,43 @@ Popover.propTypes = {
 			height: PropTypes.number.isRequired
 		})
 	]),
+	/**
+	* Specify whether a caret should be rendered
+	*/
 	caret: PropTypes.bool,
+	/**
+	* Specify whether a border should be rendered on the popover
+	*/
 	border: PropTypes.bool,
+	/**
+	* Provide elements to be rendered inside of the component
+	*/
 	children: PropTypes.node,
+	/**
+	* Provide a custom class name to be added to the outermost node in the
+	* component
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether a drop shadow should be rendered on the popover
+	*/
 	dropShadow: PropTypes.bool,
+	/**
+	* Render the component using the high-contrast variant
+	*/
 	highContrast: PropTypes.bool,
+	/**
+	* Render the component using the tab tip variant
+	*/
 	isTabTip: PropTypes.bool,
+	/**
+	* Specify a handler for closing popover.
+	* The handler should take care of closing the popover, e.g. changing the `open` prop.
+	*/
 	onRequestClose: PropTypes.func,
+	/**
+	* Specify whether the component is currently open or closed
+	*/
 	open: PropTypes.bool.isRequired
 };
 const PopoverContent = forwardRef((props, forwardRef) => {
@@ -341,7 +392,14 @@ const PopoverContent = forwardRef((props, forwardRef) => {
 });
 PopoverContent.displayName = "PopoverContent";
 PopoverContent.propTypes = {
+	/**
+	* Provide elements to be rendered inside of the component
+	*/
 	children: PropTypes.node,
+	/**
+	* Provide a custom class name to be added to the outermost node in the
+	* component
+	*/
 	className: PropTypes.string
 };
 //#endregion

package/es/components/ProgressBar/ProgressBar.js

@@ -8,8 +8,8 @@
 import { usePrefix } from "../../internal/usePrefix.js";
 import useIsomorphicEffect from "../../internal/useIsomorphicEffect.js";
 import { useId } from "../../internal/useId.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 { CheckmarkFilled, ErrorFilled } from "@carbon/icons-react";
@@ -104,22 +104,49 @@ function ProgressBar({ className, helperText, hideLabel, label, max = 100, size
 	});
 }
 ProgressBar.propTypes = {
+	/**
+	* Additional CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* The current progress as a textual representation.
+	*/
 	helperText: PropTypes.string,
+	/**
+	* Whether the label should be visually hidden.
+	*/
 	hideLabel: PropTypes.bool,
+	/**
+	* A label describing the progress bar.
+	*/
 	label: PropTypes.string.isRequired,
+	/**
+	* The maximum value.
+	*/
 	max: PropTypes.number,
+	/**
+	* Specify the size of the ProgressBar.
+	*/
 	size: PropTypes.oneOf(["small", "big"]),
+	/**
+	* Specify the status.
+	*/
 	status: PropTypes.oneOf([
 		"active",
 		"finished",
 		"error"
 	]),
+	/**
+	* Defines the alignment variant of the progress bar.
+	*/
 	type: PropTypes.oneOf([
 		"default",
 		"inline",
 		"indented"
 	]),
+	/**
+	* The current value.
+	*/
 	value: PropTypes.number
 };
 //#endregion

package/es/components/ProgressIndicator/ProgressIndicator.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, jsxs } from "react/jsx-runtime";
 import { CircleDash } from "@carbon/icons-react";
@@ -46,7 +46,13 @@ function ProgressIndicatorSkeleton({ className, vertical, ...rest }) {
 	});
 }
 ProgressIndicatorSkeleton.propTypes = {
+	/**
+	* Specify an optional className to add.
+	*/
 	className: PropTypes.string,
+	/**
+	* Determines whether or not the ProgressIndicator should be rendered vertically.
+	*/
 	vertical: PropTypes.bool
 };
 //#endregion