@carbon/react 1.110.0 → 1.111.0-rc.0

package/lib/components/Pagination/Pagination.js

@@ -12,10 +12,10 @@ const require_index = require("../IconButton/index.js");
 const require_usePreviousValue = require("../../internal/usePreviousValue.js");
 const require_index$1 = require("../Select/index.js");
 const require_index$2 = require("../SelectItem/index.js");
-let react = require("react");
-react = require_runtime.__toESM(react);
 let classnames = require("classnames");
 classnames = require_runtime.__toESM(classnames);
+let react = require("react");
+react = require_runtime.__toESM(react);
 let prop_types = require("prop-types");
 prop_types = require_runtime.__toESM(prop_types);
 let react_jsx_runtime = require("react/jsx-runtime");
@@ -57,7 +57,7 @@ const getPageSize = (pageSizes, pageSize) => {
 	}
 	return pageSizes[0].value;
 };
-const Pagination = react.default.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.default.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 = require_usePrefix.usePrefix();
 	const inputId = require_useId.useFallbackId(id?.toString());
 	const backBtnRef = (0, react.useRef)(null);
@@ -244,7 +244,7 @@ const Pagination = react.default.forwardRef(({ backwardText = "Previous page", c
 			})] }), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: `${prefix}--pagination__control-buttons`,
 				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_index.IconButton, {
-					align: "top",
+					align: backwardTextTooltipPosition,
 					disabled: backButtonDisabled,
 					kind: "ghost",
 					className: backButtonClasses,
@@ -254,7 +254,7 @@ const Pagination = react.default.forwardRef(({ backwardText = "Previous page", c
 					ref: backBtnRef,
 					children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_carbon_icons_react.CaretLeft, {})
 				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_index.IconButton, {
-					align: "top",
+					align: forwardTextTooltipPosition,
 					disabled: forwardButtonDisabled || isLastPage,
 					kind: "ghost",
 					className: forwardButtonClasses,
@@ -269,35 +269,117 @@ const Pagination = react.default.forwardRef(({ backwardText = "Previous page", c
 	});
 });
 Pagination.propTypes = {
+	/**
+	* The description for the backward icon.
+	*/
 	backwardText: prop_types.default.string,
+	/**
+	* The tooltip position for the backward button.
+	*/
+	backwardTextTooltipPosition: prop_types.default.oneOf([
+		"top",
+		"right",
+		"bottom",
+		"left"
+	]),
+	/**
+	* The CSS class names.
+	*/
 	className: prop_types.default.string,
+	/**
+	* `true` if the backward/forward buttons, as well as the page select elements,  should be disabled.
+	*/
 	disabled: prop_types.default.bool,
+	/**
+	* The description for the forward icon.
+	*/
 	forwardText: prop_types.default.string,
+	/**
+	* The tooltip position for the forward button.
+	*/
+	forwardTextTooltipPosition: prop_types.default.oneOf([
+		"top",
+		"right",
+		"bottom",
+		"left"
+	]),
+	/**
+	* The unique ID of this component instance.
+	*/
 	id: prop_types.default.oneOfType([prop_types.default.string, prop_types.default.number]),
+	/**
+	* `true` if the current page should be the last page.
+	*/
 	isLastPage: prop_types.default.bool,
+	/**
+	* The function returning a translatable text showing where the current page is,
+	* in a manner of the range of items.
+	*/
 	itemRangeText: prop_types.default.func,
+	/**
+	* A variant of `itemRangeText`, used if the total number of items is unknown.
+	*/
 	itemText: prop_types.default.func,
+	/**
+	* The translatable text indicating the number of items per page.
+	*/
 	itemsPerPageText: prop_types.default.string,
+	/**
+	* The callback function called when the current page changes.
+	*/
 	onChange: prop_types.default.func,
+	/**
+	* The current page.
+	*/
 	page: prop_types.default.number,
+	/**
+	* `true` if the select box to change the page should be disabled.
+	*/
 	pageInputDisabled: prop_types.default.bool,
 	pageNumberText: prop_types.default.string,
+	/**
+	* A function returning PII showing where the current page is.
+	*/
 	pageRangeText: prop_types.default.func,
+	/**
+	* A function returning the label for the page select.
+	*/
 	pageSelectLabelText: prop_types.default.func,
+	/**
+	* The number dictating how many items a page contains.
+	*/
 	pageSize: prop_types.default.number,
+	/**
+	* `true` if the select box to change the items per page should be disabled.
+	*/
 	pageSizeInputDisabled: prop_types.default.bool,
+	/**
+	* The choices for `pageSize`.
+	*/
 	pageSizes: prop_types.default.oneOfType([prop_types.default.arrayOf(prop_types.default.number.isRequired), prop_types.default.arrayOf(prop_types.default.shape({
 		text: prop_types.default.string.isRequired,
 		value: prop_types.default.number.isRequired
 	}).isRequired)]).isRequired,
+	/**
+	* The translatable text showing the current page.
+	*/
 	pageText: prop_types.default.func,
+	/**
+	* `true` if the total number of items is unknown.
+	*/
 	pagesUnknown: prop_types.default.bool,
+	/**
+	* Specify the size of the Pagination.
+	*/
 	size: prop_types.default.oneOf([
 		"xs",
 		"sm",
 		"md",
 		"lg"
 	]),
+	/**
+	* The total number of items.
+	*/
 	totalItems: prop_types.default.number
 };
 //#endregion

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

@@ -10,10 +10,10 @@ const require_usePrefix = require("../../../internal/usePrefix.js");
 const require_useId = require("../../../internal/useId.js");
 const require_index = require("../../Select/index.js");
 const require_index$1 = require("../../SelectItem/index.js");
-let react = require("react");
-react = require_runtime.__toESM(react);
 let classnames = require("classnames");
 classnames = require_runtime.__toESM(classnames);
+let react = require("react");
+react = require_runtime.__toESM(react);
 let prop_types = require("prop-types");
 prop_types = require_runtime.__toESM(prop_types);
 let react_jsx_runtime = require("react/jsx-runtime");
@@ -47,10 +47,18 @@ function PageSelector({ className = null, currentPage, id = 1, labelText = "Curr
 	});
 }
 PageSelector.propTypes = {
+	/** Extra class names to add. */
 	className: prop_types.default.string,
+	/** The current page. */
 	currentPage: prop_types.default.number.isRequired,
+	/** The unique ID of this component instance. */
 	id: prop_types.default.oneOfType([prop_types.default.string, prop_types.default.number]),
+	/** Translatable string to label the page selector element. */
 	labelText: prop_types.default.string,
+	/**
+	* Total number of pages.
+	* This value is calculated using a valid `totalItems` prop passed to the parent `Unstable_Pagination`.
+	*/
 	totalPages: prop_types.default.number.isRequired
 };
 //#endregion

package/lib/components/Pagination/experimental/Pagination.js

@@ -10,10 +10,10 @@ const require_usePrefix = require("../../../internal/usePrefix.js");
 const require_index = require("../../IconButton/index.js");
 const require_index$1 = require("../../Select/index.js");
 const require_index$2 = require("../../SelectItem/index.js");
-let react = require("react");
-react = require_runtime.__toESM(react);
 let classnames = require("classnames");
 classnames = require_runtime.__toESM(classnames);
+let react = require("react");
+react = require_runtime.__toESM(react);
 let prop_types = require("prop-types");
 prop_types = require_runtime.__toESM(prop_types);
 let react_jsx_runtime = require("react/jsx-runtime");
@@ -135,22 +135,76 @@ function Pagination({ backwardText = "Previous page", children = void 0, classNa
 	});
 }
 Pagination.propTypes = {
+	/**
+	* The description for the backward icon.
+	*/
 	backwardText: prop_types.default.string,
+	/**
+	* The children of the pagination component.
+	*/
 	children: prop_types.default.oneOfType([prop_types.default.node, prop_types.default.func]),
+	/**
+	* Extra classes to add.
+	*/
 	className: prop_types.default.string,
+	/**
+	* `true` if the backward/forward buttons should be disabled.
+	*/
 	disabled: prop_types.default.bool,
+	/**
+	* The description for the forward icon.
+	*/
 	forwardText: prop_types.default.string,
+	/** The unique ID of this component instance. */
 	id: prop_types.default.oneOfType([prop_types.default.string, prop_types.default.number]),
+	/**
+	* The initial active page when the component is first mounted.
+	*/
 	initialPage: prop_types.default.number,
+	/**
+	* The function returning a translatable text showing where the current page is,
+	* in a manner of the range of items.
+	*/
 	itemRangeText: prop_types.default.func,
+	/**
+	* A variant of `itemRangeText`, used if the total number of items is unknown.
+	*/
 	itemText: prop_types.default.func,
+	/**
+	* The translatable text indicating the number of items per page.
+	*/
 	itemsPerPageText: prop_types.default.string,
+	/**
+	* The callback function called when the current page changes.
+	*/
 	onChange: prop_types.default.func,
+	/**
+	* The function returning a translatable text showing where the current page is,
+	* in a manner of the total number of pages.
+	*/
 	pageRangeText: prop_types.default.func,
+	/**
+	* The number dictating how many items a page contains.
+	*/
 	pageSize: prop_types.default.number,
+	/**
+	* The choices for `pageSize`.
+	*/
 	pageSizes: prop_types.default.arrayOf(prop_types.default.number),
+	/**
+	* The translatable text showing the current page.
+	*/
 	pageText: prop_types.default.func,
+	/**
+	* `true` if total number of pages is unknown.
+	*/
 	pagesUnknown: prop_types.default.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: prop_types.default.number
 };
 //#endregion

package/lib/components/PaginationNav/PaginationNav.js

@@ -10,10 +10,10 @@ const require_usePrefix = require("../../internal/usePrefix.js");
 const require_index = require("../IconButton/index.js");
 const require_clamp = require("../../internal/clamp.js");
 const require_useMatchMedia = require("../../internal/useMatchMedia.js");
-let react = require("react");
-react = require_runtime.__toESM(react);
 let classnames = require("classnames");
 classnames = require_runtime.__toESM(classnames);
+let react = require("react");
+react = require_runtime.__toESM(react);
 let prop_types = require("prop-types");
 prop_types = require_runtime.__toESM(prop_types);
 let react_jsx_runtime = require("react/jsx-runtime");
@@ -292,15 +292,35 @@ const PaginationNav = react.default.forwardRef(({ className, onChange = () => {}
 	});
 });
 DirectionButton.propTypes = {
+	/**
+	* The direction this button represents ("forward" or "backward").
+	*/
 	direction: prop_types.default.oneOf(["forward", "backward"]),
+	/**
+	* Whether or not the button should be disabled.
+	*/
 	disabled: prop_types.default.bool,
+	/**
+	* The label shown in the button's tooltip.
+	*/
 	label: prop_types.default.string,
+	/**
+	* The callback function called when the button is clicked.
+	*/
 	onClick: prop_types.default.func,
+	/**
+	* Specify how the tooltip should align with the navigation button.
+	* Can be one of: start, center, or end.
+	*/
 	tooltipAlignment: prop_types.default.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: prop_types.default.oneOf([
 		"top",
 		"right",
@@ -309,42 +329,102 @@ DirectionButton.propTypes = {
 	])
 };
 PaginationItem.propTypes = {
+	/**
+	* Whether or not this is the currently active page.
+	*/
 	isActive: prop_types.default.bool,
+	/**
+	* The callback function called when the item is clicked.
+	*/
 	onClick: prop_types.default.func,
+	/**
+	* The page number this item represents.
+	*/
 	page: prop_types.default.number,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: prop_types.default.func
 };
 PaginationOverflow.propTypes = {
+	/**
+	* How many items to display in this overflow.
+	*/
 	count: prop_types.default.number,
+	/**
+	* From which index on this overflow should start displaying pages.
+	*/
 	fromIndex: prop_types.default.number,
+	/**
+	* The callback function called when the user selects a page from the overflow.
+	*/
 	onSelect: prop_types.default.func,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: prop_types.default.func
 };
 PaginationNav.displayName = "PaginationNav";
 PaginationNav.propTypes = {
+	/**
+	* Additional CSS class names.
+	*/
 	className: prop_types.default.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: prop_types.default.bool,
+	/**
+	* The number of items to be shown (minimum of 4 unless props.items < 4).
+	*/
 	itemsShown: prop_types.default.number,
+	/**
+	* Whether user should be able to loop through the items when reaching first / last.
+	*/
 	loop: prop_types.default.bool,
+	/**
+	* The callback function called when the current page changes.
+	*/
 	onChange: prop_types.default.func,
+	/**
+	* The index of current page.
+	*/
 	page: prop_types.default.number,
+	/**
+	* Specify the size of the PaginationNav.
+	*/
 	size: prop_types.default.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: prop_types.default.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: prop_types.default.oneOf([
 		"top",
 		"right",
 		"bottom",
 		"left"
 	]),
+	/**
+	* The total number of items.
+	*/
 	totalItems: prop_types.default.number,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: prop_types.default.func
 };
 //#endregion

package/lib/components/Popover/index.js

@@ -14,10 +14,10 @@ const require_useMergedRefs = require("../../internal/useMergedRefs.js");
 const require_useEvent = require("../../internal/useEvent.js");
 const require_mapPopoverAlign = require("../../tools/mapPopoverAlign.js");
 const require_index = require("../FeatureFlags/index.js");
-let react = require("react");
-react = require_runtime.__toESM(react);
 let classnames = require("classnames");
 classnames = require_runtime.__toESM(classnames);
+let react = require("react");
+react = require_runtime.__toESM(react);
 let prop_types = require("prop-types");
 prop_types = require_runtime.__toESM(prop_types);
 let react_jsx_runtime = require("react/jsx-runtime");
@@ -258,6 +258,9 @@ const Popover = react.default.forwardRef(function PopoverRenderFunction({ isTabT
 });
 if (process.env.NODE_ENV !== "production") Popover.displayName = "Popover";
 Popover.propTypes = {
+	/**
+	* Specify how the popover should align with the trigger element
+	*/
 	align: require_deprecateValuesWithin.deprecateValuesWithin(prop_types.default.oneOf([
 		"top",
 		"top-left",
@@ -293,10 +296,29 @@ Popover.propTypes = {
 		"right-start",
 		"right-end"
 	], require_mapPopoverAlign.mapPopoverAlign),
+	/**
+	* **Experimental:** Provide an offset value for alignment axis. Only takes effect when `autoalign` is enabled.
+	*/
 	alignmentAxisOffset: prop_types.default.number,
+	/**
+	* Provide a custom element or component to render the top-level node for the
+	* component.
+	*/
 	as: prop_types.default.oneOfType([prop_types.default.string, prop_types.default.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: prop_types.default.bool,
+	/**
+	* Specify the background token to use. Default is 'layer'.
+	*/
 	backgroundToken: prop_types.default.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: prop_types.default.oneOfType([
 		prop_types.default.oneOf(["clippingAncestors"]),
 		prop_types.default.elementType,
@@ -308,14 +330,43 @@ Popover.propTypes = {
 			height: prop_types.default.number.isRequired
 		})
 	]),
+	/**
+	* Specify whether a caret should be rendered
+	*/
 	caret: prop_types.default.bool,
+	/**
+	* Specify whether a border should be rendered on the popover
+	*/
 	border: prop_types.default.bool,
+	/**
+	* Provide elements to be rendered inside of the component
+	*/
 	children: prop_types.default.node,
+	/**
+	* Provide a custom class name to be added to the outermost node in the
+	* component
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify whether a drop shadow should be rendered on the popover
+	*/
 	dropShadow: prop_types.default.bool,
+	/**
+	* Render the component using the high-contrast variant
+	*/
 	highContrast: prop_types.default.bool,
+	/**
+	* Render the component using the tab tip variant
+	*/
 	isTabTip: prop_types.default.bool,
+	/**
+	* Specify a handler for closing popover.
+	* The handler should take care of closing the popover, e.g. changing the `open` prop.
+	*/
 	onRequestClose: prop_types.default.func,
+	/**
+	* Specify whether the component is currently open or closed
+	*/
 	open: prop_types.default.bool.isRequired
 };
 const frFn = react.forwardRef;
@@ -346,7 +397,14 @@ const PopoverContent = frFn((props, forwardRef) => {
 });
 PopoverContent.displayName = "PopoverContent";
 PopoverContent.propTypes = {
+	/**
+	* Provide elements to be rendered inside of the component
+	*/
 	children: prop_types.default.node,
+	/**
+	* Provide a custom class name to be added to the outermost node in the
+	* component
+	*/
 	className: prop_types.default.string
 };
 //#endregion

package/lib/components/ProgressBar/ProgressBar.js

@@ -9,10 +9,10 @@ const require_runtime = require("../../_virtual/_rolldown/runtime.js");
 const require_usePrefix = require("../../internal/usePrefix.js");
 const require_useIsomorphicEffect = require("../../internal/useIsomorphicEffect.js");
 const require_useId = require("../../internal/useId.js");
-let react = require("react");
-react = require_runtime.__toESM(react);
 let classnames = require("classnames");
 classnames = require_runtime.__toESM(classnames);
+let react = require("react");
+react = require_runtime.__toESM(react);
 let prop_types = require("prop-types");
 prop_types = require_runtime.__toESM(prop_types);
 let react_jsx_runtime = require("react/jsx-runtime");
@@ -108,22 +108,49 @@ function ProgressBar({ className, helperText, hideLabel, label, max = 100, size
 	});
 }
 ProgressBar.propTypes = {
+	/**
+	* Additional CSS class names.
+	*/
 	className: prop_types.default.string,
+	/**
+	* The current progress as a textual representation.
+	*/
 	helperText: prop_types.default.string,
+	/**
+	* Whether the label should be visually hidden.
+	*/
 	hideLabel: prop_types.default.bool,
+	/**
+	* A label describing the progress bar.
+	*/
 	label: prop_types.default.string.isRequired,
+	/**
+	* The maximum value.
+	*/
 	max: prop_types.default.number,
+	/**
+	* Specify the size of the ProgressBar.
+	*/
 	size: prop_types.default.oneOf(["small", "big"]),
+	/**
+	* Specify the status.
+	*/
 	status: prop_types.default.oneOf([
 		"active",
 		"finished",
 		"error"
 	]),
+	/**
+	* Defines the alignment variant of the progress bar.
+	*/
 	type: prop_types.default.oneOf([
 		"default",
 		"inline",
 		"indented"
 	]),
+	/**
+	* The current value.
+	*/
 	value: prop_types.default.number
 };
 //#endregion

package/lib/components/ProgressIndicator/ProgressIndicator.Skeleton.js

@@ -7,10 +7,10 @@
 
 const require_runtime = require("../../_virtual/_rolldown/runtime.js");
 const require_usePrefix = require("../../internal/usePrefix.js");
-let react = require("react");
-react = require_runtime.__toESM(react);
 let classnames = require("classnames");
 classnames = require_runtime.__toESM(classnames);
+let react = require("react");
+react = require_runtime.__toESM(react);
 let prop_types = require("prop-types");
 prop_types = require_runtime.__toESM(prop_types);
 let react_jsx_runtime = require("react/jsx-runtime");
@@ -50,7 +50,13 @@ function ProgressIndicatorSkeleton({ className, vertical, ...rest }) {
 	});
 }
 ProgressIndicatorSkeleton.propTypes = {
+	/**
+	* Specify an optional className to add.
+	*/
 	className: prop_types.default.string,
+	/**
+	* Determines whether or not the ProgressIndicator should be rendered vertically.
+	*/
 	vertical: prop_types.default.bool
 };
 //#endregion