@carbon/react 1.110.0-rc.0 → 1.111.0-rc.0

package/lib/components/OverflowMenu/next/index.js

@@ -109,23 +109,50 @@ const OverflowMenu = react.default.forwardRef(({ autoAlign = false, children, cl
 	});
 });
 OverflowMenu.propTypes = {
+	/**
+	* **Experimental**: Will attempt to automatically align the floating element
+	* to avoid collisions with the viewport and being clipped by ancestor
+	* elements. Requires React v17+
+	* @see https://github.com/carbon-design-system/carbon/issues/18714
+	*/
 	autoAlign: prop_types.default.bool,
+	/**
+	* A collection of MenuItems to be rendered within this OverflowMenu.
+	*/
 	children: prop_types.default.node,
+	/**
+	* Additional CSS class names for the trigger button.
+	*/
 	className: prop_types.default.string,
+	/**
+	* A label describing the options available. Is used in the trigger tooltip and as the menu's accessible label.
+	*/
 	label: prop_types.default.string,
+	/**
+	* Experimental property. Specify how the menu should align with the button element
+	*/
 	menuAlignment: prop_types.default.oneOf([
 		"top-start",
 		"top-end",
 		"bottom-start",
 		"bottom-end"
 	]),
+	/**
+	* A component used to render an icon.
+	*/
 	renderIcon: prop_types.default.oneOfType([prop_types.default.func, prop_types.default.object]),
+	/**
+	* Specify the size of the menu, from a list of available sizes.
+	*/
 	size: prop_types.default.oneOf([
 		"xs",
 		"sm",
 		"md",
 		"lg"
 	]),
+	/**
+	* Specify how the trigger tooltip should be aligned.
+	*/
 	tooltipAlignment: require_deprecateValuesWithin.deprecateValuesWithin(prop_types.default.oneOf([
 		"top",
 		"top-left",
@@ -161,6 +188,9 @@ OverflowMenu.propTypes = {
 		"right-start",
 		"right-end"
 	], require_mapPopoverAlign.mapPopoverAlign),
+	/**
+	* Specify a DOM node where the Menu should be rendered in. Defaults to document.body.
+	*/
 	menuTarget: prop_types.default.instanceOf(typeof Element !== "undefined" ? Element : Object)
 };
 //#endregion

package/lib/components/OverflowMenuItem/OverflowMenuItem.js

@@ -87,16 +87,43 @@ const OverflowMenuItem = (0, react.forwardRef)((props, ref) => {
 	});
 });
 OverflowMenuItem.propTypes = {
+	/**
+	* The CSS class name to be placed on the button element
+	*/
 	className: prop_types.default.string,
+	/**
+	* A callback to tell the parent menu component that the menu should be closed.
+	*/
 	closeMenu: prop_types.default.func,
+	/**
+	* Specify the message read by screen readers for the danger overflow menu item variant
+	*/
 	dangerDescription: prop_types.default.string,
+	/**
+	* `true` to make this menu item disabled.
+	*/
 	disabled: prop_types.default.bool,
 	handleOverflowMenuItemFocus: prop_types.default.func,
+	/**
+	* `true` to make this menu item a divider.
+	*/
 	hasDivider: prop_types.default.bool,
+	/**
+	* If given, overflow item will render as a link with the given href
+	*/
 	href: prop_types.default.string,
 	index: prop_types.default.number,
+	/**
+	* `true` to make this menu item a "danger button".
+	*/
 	isDelete: prop_types.default.bool,
+	/**
+	* The text in the menu item.
+	*/
 	itemText: prop_types.default.node.isRequired,
+	/**
+	* event handlers
+	*/
 	onBlur: prop_types.default.func,
 	onClick: prop_types.default.func,
 	onFocus: prop_types.default.func,
@@ -106,8 +133,17 @@ OverflowMenuItem.propTypes = {
 	onMouseEnter: prop_types.default.func,
 	onMouseLeave: prop_types.default.func,
 	onMouseUp: prop_types.default.func,
+	/**
+	* `true` if this menu item has long text and requires a browser tooltip
+	*/
 	requireTitle: prop_types.default.bool,
+	/**
+	* Specify a title for the OverflowMenuItem
+	*/
 	title: prop_types.default.string,
+	/**
+	* The CSS class name to be placed on the wrapper list item element
+	*/
 	wrapperClassName: prop_types.default.string
 };
 //#endregion

package/lib/components/PageHeader/PageHeader.js

@@ -150,12 +150,33 @@ const PageHeaderContent = react.default.forwardRef(({ className, children, title
 });
 PageHeaderContent.displayName = "PageHeaderContent";
 PageHeaderContent.propTypes = {
+	/**
+	* Provide child elements to be rendered inside PageHeaderContent.
+	*/
 	children: prop_types.default.node,
+	/**
+	* Specify an optional className to be added to your PageHeaderContent
+	*/
 	className: prop_types.default.string,
+	/**
+	* Provide an optional icon to render in front of the PageHeaderContent's title.
+	*/
 	renderIcon: prop_types.default.oneOfType([prop_types.default.func, prop_types.default.object]),
+	/**
+	* The PageHeaderContent's title
+	*/
 	title: prop_types.default.string.isRequired,
+	/**
+	* The PageHeaderContent's subtitle
+	*/
 	subtitle: prop_types.default.string,
+	/**
+	* The PageHeaderContent's contextual actions
+	*/
 	contextualActions: prop_types.default.node,
+	/**
+	* The PageHeaderContent's page actions
+	*/
 	pageActions: prop_types.default.node
 };
 const PageHeaderContentPageActions = ({ className, children, menuButtonLabel = "Actions", actions, ...other }) => {
@@ -207,9 +228,21 @@ const PageHeaderContentPageActions = ({ className, children, menuButtonLabel = "
 };
 PageHeaderContentPageActions.displayName = "PageHeaderContentPageActions";
 PageHeaderContentPageActions.propTypes = {
+	/**
+	* Provide child elements to be rendered inside PageHeaderContentPageActions.
+	*/
 	children: prop_types.default.node,
+	/**
+	* Specify an optional className to be added to your PageHeaderContentPageActions
+	*/
 	className: prop_types.default.string,
+	/**
+	* The PageHeaderContent's collapsible Menu button label
+	*/
 	menuButtonLabel: prop_types.default.string,
+	/**
+	* The PageHeaderContent's page actions
+	*/
 	actions: prop_types.default.oneOfType([prop_types.default.node, prop_types.default.array])
 };
 const PageHeaderContentText = ({ className, children, subtitle, ...other }) => {
@@ -227,8 +260,17 @@ const PageHeaderContentText = ({ className, children, subtitle, ...other }) => {
 };
 PageHeaderContentText.displayName = "PageHeaderContentText";
 PageHeaderContentText.propTypes = {
+	/**
+	* Provide child elements to be rendered inside PageHeaderContentText.
+	*/
 	children: prop_types.default.node,
+	/**
+	* Specify an optional className to be added to your PageHeaderContentText
+	*/
 	className: prop_types.default.string,
+	/**
+	* The PageHeaderContent's subtitle
+	*/
 	subtitle: prop_types.default.string
 };
 const PageHeaderHeroImage = ({ className, children, ...other }) => {
@@ -244,7 +286,13 @@ const PageHeaderHeroImage = ({ className, children, ...other }) => {
 };
 PageHeaderHeroImage.displayName = "PageHeaderHeroImage";
 PageHeaderHeroImage.propTypes = {
+	/**
+	* Provide child elements to be rendered inside PageHeaderHeroImage.
+	*/
 	children: prop_types.default.node,
+	/**
+	* Specify an optional className to be added to your PageHeaderHeroImage
+	*/
 	className: prop_types.default.string
 };
 const PageHeaderTabBar = react.default.forwardRef(({ className, children, tags = [], ...other }, ref) => {

package/lib/components/Pagination/Pagination.Skeleton.js

@@ -40,6 +40,10 @@ function PaginationSkeleton({ className, ...rest }) {
 		})]
 	});
 }
-PaginationSkeleton.propTypes = { className: prop_types.default.string };
+PaginationSkeleton.propTypes = { 
+/**
+* Specify an optional className to add.
+*/
+className: prop_types.default.string };
 //#endregion
 exports.default = PaginationSkeleton;

package/lib/components/Pagination/Pagination.d.ts

@@ -15,6 +15,10 @@ export interface PaginationProps extends Omit<React.HTMLAttributes<HTMLDivElemen
      * The description for the backward icon.
      */
     backwardText?: string;
+    /**
+     * The tooltip position for the backward button.
+     */
+    backwardTextTooltipPosition?: 'top' | 'right' | 'bottom' | 'left';
     /**
      * The CSS class names.
      */
@@ -27,6 +31,10 @@ export interface PaginationProps extends Omit<React.HTMLAttributes<HTMLDivElemen
      * The description for the forward icon.
      */
     forwardText?: string;
+    /**
+     * The tooltip position for the forward button.
+     */
+    forwardTextTooltipPosition?: 'top' | 'right' | 'bottom' | 'left';
     /**
      * The unique ID of this component instance.
      */

package/lib/components/Pagination/Pagination.js

@@ -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

@@ -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

@@ -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

@@ -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