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

package/es/components/TreeView/TreeNode.js

@@ -336,23 +336,81 @@ const TreeNode = React.forwardRef(({ children, className, disabled, id: nodeId,
 	}) });
 });
 TreeNode.propTypes = {
+	/**
+	* **Note:** this is controlled by the parent TreeView component, do not set manually.
+	* The ID of the active node in the tree
+	*/
 	active: deprecate(PropTypes.oneOfType([PropTypes.string, PropTypes.number]), "The `active` prop for `TreeNode` is no longer needed and has been deprecated. It will be removed in the next major release."),
+	/**
+	* Specify the children of the TreeNode
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the TreeNode
+	*/
 	className: PropTypes.string,
+	/**
+	* **[Experimental]** The default expansion state of the node.
+	* *This is only supported with the `enable-treeview-controllable` feature flag!*
+	*/
 	defaultIsExpanded: PropTypes.bool,
+	/**
+	* **Note:** this is controlled by the parent TreeView component, do not set manually.
+	* TreeNode depth to determine spacing
+	*/
 	depth: deprecate(PropTypes.number, "The `depth` prop for `TreeNode` is no longer needed and has been deprecated. It will be removed in the next major release."),
+	/**
+	* Specify if the TreeNode is disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Specify the TreeNode's ID. Must be unique in the DOM and is used for props.active, props.selected and aria-owns
+	*/
 	id: PropTypes.string,
+	/**
+	* Specify if the TreeNode is expanded (only applicable to parent nodes)
+	*/
 	isExpanded: PropTypes.bool,
+	/**
+	* Rendered label for the TreeNode
+	*/
 	label: PropTypes.node,
+	/**
+	* Callback function for when the node receives or loses focus
+	*/
 	onNodeFocusEvent: deprecate(PropTypes.func, "The `onNodeFocusEvent` prop for `TreeNode` is no longer needed and has been deprecated. It will be removed in the next major release."),
+	/**
+	* Callback function for when the node is selected
+	*/
 	onSelect: PropTypes.func,
+	/**
+	* Callback function for when a parent node is expanded or collapsed
+	*/
 	onToggle: PropTypes.func,
+	/**
+	* Callback function for when any node in the tree is selected
+	*/
 	onTreeSelect: deprecate(PropTypes.func, "The `onTreeSelect` prop for `TreeNode` is no longer needed and has been deprecated. It will be removed in the next major release."),
+	/**
+	* A component used to render an icon.
+	*/
 	renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
+	/**
+	* **Note:** this is controlled by the parent TreeView component, do not set manually.
+	* Array containing all selected node IDs in the tree
+	*/
 	selected: deprecate(PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.string, PropTypes.number])), "The `selected` prop for `TreeNode` is no longer needed and has been deprecated. It will be removed in the next major release."),
+	/**
+	* Specify the value of the TreeNode
+	*/
 	value: PropTypes.string,
+	/**
+	* Optional: The URL the TreeNode is linking to
+	*/
 	href: PropTypes.string,
+	/**
+	* Specify how the tooltip should align when text is truncated
+	*/
 	align: PropTypes.oneOf([
 		"top",
 		"bottom",
@@ -367,6 +425,12 @@ TreeNode.propTypes = {
 		"right-end",
 		"right-start"
 	]),
+	/**
+	* **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: PropTypes.bool
 };
 TreeNode.displayName = "TreeNode";

package/es/components/TreeView/TreeView.js

@@ -159,15 +159,47 @@ const TreeView = ({ active: prespecifiedActive, children, className, hideLabel =
 	})] });
 };
 TreeView.propTypes = {
+	/**
+	* Mark the active node in the tree, represented by its ID
+	*/
 	active: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+	/**
+	* Specify the children of the TreeView
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the TreeView
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether or not the label should be hidden
+	*/
 	hideLabel: PropTypes.bool,
+	/**
+	* Provide the label text that will be read by a screen reader
+	*/
 	label: PropTypes.string.isRequired,
+	/**
+	* **[Experimental]** Specify the selection mode of the tree.
+	* If `multiselect` is `false` then only one node can be selected at a time
+	*/
 	multiselect: PropTypes.bool,
+	/**
+	* **[Experimental]** Callback function that is called when any node is activated.
+	* *This is only supported with the `enable-treeview-controllable` feature flag!*
+	*/
 	onActivate: PropTypes.func,
+	/**
+	* Callback function that is called when any node is selected
+	*/
 	onSelect: PropTypes.func,
+	/**
+	* Array representing all selected node IDs in the tree
+	*/
 	selected: PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.string, PropTypes.number])),
+	/**
+	* Specify the size of the tree from a list of available sizes.
+	*/
 	size: PropTypes.oneOf(["xs", "sm"])
 };
 TreeView.TreeNode = TreeNode;

package/es/components/UIShell/Content.js

@@ -24,8 +24,17 @@ const Content = ({ className: customClassName, children, tagName = "main", ...re
 	}, children);
 };
 Content.propTypes = {
+	/**
+	* Provide children nodes to be rendered in the content container
+	*/
 	children: PropTypes.node,
+	/**
+	* Optionally provide a custom class name that is applied to the container
+	*/
 	className: PropTypes.string,
+	/**
+	* Optionally specify the tag of the content node. Defaults to `main`
+	*/
 	tagName: PropTypes.string
 };
 //#endregion

package/es/components/UIShell/Header.js

@@ -26,8 +26,17 @@ const Header = ({ className: customClassName, children, ...rest }) => {
 	});
 };
 Header.propTypes = {
+	/**
+	* Optionally provide aria-label
+	*/
 	"aria-label": PropTypes.string,
+	/**
+	* Optionally provide aria-labelledby
+	*/
 	"aria-labelledby": PropTypes.string,
+	/**
+	* Optionally provide a custom class name that is applied to the underlying header
+	*/
 	className: PropTypes.string
 };
 //#endregion

package/es/components/UIShell/HeaderContainer.js

@@ -33,7 +33,16 @@ function HeaderContainer({ render: Children, isSideNavExpanded = false, ...rest
 	});
 }
 HeaderContainer.propTypes = {
+	/**
+	* Optionally provide a custom class name that is applied to the underlying <header>
+	*/
 	isSideNavExpanded: PropTypes.bool,
+	/**
+	* A function or a component that is invoked with `isSideNavExpanded` and `onClickSideNavExpand`.
+	* The function or component can then use those properties to within the components it
+	* returns, such as with the HeaderMenuButton and SideNav components. Additional props will also be passed
+	* into this component for convenience.
+	*/
 	render: PropTypes.elementType.isRequired
 };
 //#endregion

package/es/components/UIShell/HeaderGlobalAction.js

@@ -57,17 +57,45 @@ const HeaderGlobalAction = React.forwardRef(({ "aria-label": ariaLabel, "aria-la
 	});
 });
 HeaderGlobalAction.propTypes = {
+	/**
+	* Required props for the accessibility label of the button
+	*/
 	...AriaLabelPropType,
+	/**
+	* Provide a custom icon for this global action
+	*/
 	children: PropTypes.node.isRequired,
+	/**
+	* Optionally provide a custom class name that is applied to the underlying
+	* button
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the action is currently active
+	*/
 	isActive: PropTypes.bool,
+	/**
+	* Optionally provide an onClick handler that is called when the underlying
+	* button fires it's onclick event
+	*/
 	onClick: PropTypes.func,
+	/**
+	* 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,
+	/**
+	* Render the tooltip using the high-contrast theme
+	* Default is true
+	*/
 	tooltipHighContrast: PropTypes.bool
 };
 HeaderGlobalAction.displayName = "HeaderGlobalAction";

package/es/components/UIShell/HeaderMenu.js

@@ -130,16 +130,53 @@ const HeaderMenu = forwardRef((props, ref) => {
 });
 HeaderMenu.displayName = "HeaderMenu";
 HeaderMenu.propTypes = {
+	/**
+	* Required props for the accessibility label of the menu
+	*/
 	...AriaLabelPropType,
+	/**
+	* Optionally provide a custom class to apply to the underlying `<li>` node
+	*/
 	className: PropTypes.string,
+	/**
+	* Provide a custom ref handler for the menu button
+	*/
 	focusRef: PropTypes.func,
+	/**
+	* Applies selected styles to the item if a user sets this to true and `aria-current !== 'page'`.
+	*/
 	isActive: PropTypes.bool,
+	/**
+	* Applies selected styles to the item if a user sets this to true and `aria-current !== 'page'`.
+	* @deprecated Please use `isActive` instead. This will be removed in the next major release.
+	*/
 	isCurrentPage: deprecate(PropTypes.bool, "The `isCurrentPage` prop for `HeaderMenu` has been deprecated. Please use `isActive` instead. This will be removed in the next major release."),
+	/**
+	* Provide a label for the link text
+	*/
 	menuLinkName: PropTypes.string.isRequired,
+	/**
+	* Optionally provide an onBlur handler that is called when the underlying
+	* button fires it's onblur event
+	*/
 	onBlur: PropTypes.func,
+	/**
+	* Optionally provide an onClick handler that is called when the underlying
+	* button fires it's onclick event
+	*/
 	onClick: PropTypes.func,
+	/**
+	* Optionally provide an onKeyDown handler that is called when the underlying
+	* button fires it's onkeydown event
+	*/
 	onKeyDown: PropTypes.func,
+	/**
+	* Optional component to render instead of string
+	*/
 	renderMenuContent: PropTypes.func,
+	/**
+	* Optionally provide a tabIndex for the underlying menu button
+	*/
 	tabIndex: PropTypes.number
 };
 //#endregion

package/es/components/UIShell/HeaderMenuButton.js

@@ -42,10 +42,27 @@ function HeaderMenuButton({ "aria-label": ariaLabel, "aria-labelledby": ariaLabe
 	});
 }
 HeaderMenuButton.propTypes = {
+	/**
+	* Required props for accessibility label on the underlying menu button
+	*/
 	...AriaLabelPropType,
+	/**
+	* Optionally provide a custom class name that is applied to the underlying
+	* button
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the menu button is "active".
+	*/
 	isActive: PropTypes.bool,
+	/**
+	* Specify whether the menu button is collapsible.
+	*/
 	isCollapsible: PropTypes.bool,
+	/**
+	* Optionally provide an onClick handler that is called when the underlying
+	* button fires it's onclick event
+	*/
 	onClick: PropTypes.func
 };
 //#endregion

package/es/components/UIShell/HeaderMenuItem.js

@@ -46,12 +46,37 @@ const HeaderMenuItem = forwardRef(function HeaderMenuItem({ className, isActive,
 });
 HeaderMenuItem.displayName = "HeaderMenuItem";
 HeaderMenuItem.propTypes = {
+	/**
+	* Pass in a valid `element` to replace the underlying `<a>` tag with a
+	* custom `Link` element
+	*/
 	...LinkPropTypes,
+	/**
+	* Pass in children that are either a string or can be read as a string by
+	* screen readers
+	*/
 	children: PropTypes.node.isRequired,
+	/**
+	* Optionally provide a custom class to apply to the underlying `<li>` node
+	*/
 	className: PropTypes.string,
+	/**
+	* If `true` and `aria-current !== 'page'`, applies selected styles to the item and sets `aria-current="true"`.
+	*/
 	isActive: PropTypes.bool,
+	/**
+	* Applies selected styles to the item if a user sets this to true and `aria-current !== 'page'`.
+	* @deprecated Please use `isActive` instead. This will be removed in the next major release.
+	*/
 	isCurrentPage: deprecate(PropTypes.bool, "The `isCurrentPage` prop for `HeaderMenuItem` has been deprecated. Please use `isActive` instead. This will be removed in the next major release."),
+	/**
+	* Optionally supply a role for the underlying `<li>` node. Useful for resetting
+	* `<ul>` semantics for menus.
+	*/
 	role: PropTypes.string,
+	/**
+	* Specify the tab index of the Link
+	*/
 	tabIndex: PropTypes.number
 };
 //#endregion

package/es/components/UIShell/HeaderName.js

@@ -31,10 +31,28 @@ function HeaderName({ children, className: customClassName, prefix = "IBM", ...r
 	});
 }
 HeaderName.propTypes = {
+	/**
+	* Pass in a valid `element` to replace the underlying `<a>` tag with a
+	* custom `Link` element
+	*/
 	...LinkPropTypes,
+	/**
+	* Pass in children that are either a string or can be read as a string by
+	* screen readers
+	*/
 	children: PropTypes.node.isRequired,
+	/**
+	* Optionally provide a custom class to apply to the underlying `<li>` node
+	*/
 	className: PropTypes.string,
+	/**
+	* Provide an href for the name to link to
+	*/
 	href: PropTypes.string,
+	/**
+	* Optionally specify a prefix to your header name. Useful for companies, for
+	* example: IBM [Product Name] versus solely [Product Name]
+	*/
 	prefix: PropTypes.string
 };
 //#endregion

package/es/components/UIShell/HeaderNavigation.js

@@ -33,8 +33,18 @@ function HeaderNavigation({ "aria-label": ariaLabel, "aria-labelledby": ariaLabe
 	});
 }
 HeaderNavigation.propTypes = {
+	/**
+	* Required props for accessibility label on the underlying menu
+	*/
 	...AriaLabelPropType,
+	/**
+	* Provide valid children of HeaderNavigation, for example `HeaderMenuItem`
+	* or `HeaderMenu`
+	*/
 	children: PropTypes.node,
+	/**
+	* Optionally provide a custom class to apply to the underlying <nav> node
+	*/
 	className: PropTypes.string
 };
 //#endregion

package/es/components/UIShell/HeaderPanel.js

@@ -71,11 +71,30 @@ const HeaderPanel = React.forwardRef(({ children, className: customClassName, ex
 	});
 });
 HeaderPanel.propTypes = {
+	/**
+	* Specify whether focus and blur listeners are added. They are by default.
+	*/
 	addFocusListeners: PropTypes.bool,
+	/**
+	* The content that will render inside of the `HeaderPanel`
+	*/
 	children: PropTypes.node,
+	/**
+	* Optionally provide a custom class to apply to the underlying `<li>` node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the panel is expanded
+	*/
 	expanded: PropTypes.bool,
+	/**
+	* Provide the `href` to the id of the element on your package that could
+	* be target.
+	*/
 	href: PropTypes.string,
+	/**
+	* An optional listener that is called a callback to collapse the HeaderPanel
+	*/
 	onHeaderPanelFocus: PropTypes.func
 };
 HeaderPanel.displayName = "HeaderPanel";

package/es/components/UIShell/HeaderSideNavItems.js

@@ -28,8 +28,19 @@ function HeaderSideNavItems({ className: customClassName, children, hasDivider =
 	});
 }
 HeaderSideNavItems.propTypes = {
+	/**
+	* The child nodes to be rendered
+	*/
 	children: PropTypes.node,
+	/**
+	* Optionally provide a custom class name that is applied to the underlying
+	* button
+	*/
 	className: PropTypes.string,
+	/**
+	* Optionally specify if container will have a bottom divider to differentiate
+	* between original sidenav items and header menu items. False by default.
+	*/
 	hasDivider: PropTypes.bool
 };
 //#endregion

package/es/components/UIShell/Link.js

@@ -30,8 +30,22 @@ const Link = forwardRef((props, ref) => {
 * `@reach/router`
 */
 const LinkPropTypes = {
+	/**
+	* Provide a custom element or component to render the top-level node for the
+	* component.
+	*/
 	as: PropTypes.elementType,
+	/**
+	* The base element to use to build the link. Defaults to `a`, can also accept
+	* alternative tag names or custom components like `Link` from `react-router`.
+	* @deprecated Use `as` instead
+	*
+	*/
 	element: deprecate(PropTypes.elementType, "The `element` prop for `Link` has been deprecated. Please use `as` instead. This will be removed in the next major release."),
+	/**
+	* Property to indicate if the side nav container is open (or not). Use to
+	* keep local state and styling in step with the SideNav expansion state.
+	*/
 	isSideNavExpanded: PropTypes.bool
 };
 Link.displayName = "Link";

package/es/components/UIShell/SideNav.js

@@ -121,20 +121,73 @@ const SideNav = forwardRef((props, ref) => {
 });
 SideNav.displayName = "SideNav";
 SideNav.propTypes = {
+	/**
+	* Required props for accessibility label on the underlying menu
+	*/
 	...AriaLabelPropType,
+	/**
+	* Specify whether focus and blur listeners are added. They are by default.
+	*/
 	addFocusListeners: PropTypes.bool,
+	/**
+	* Specify whether mouse entry/exit listeners are added. They are by default.
+	*/
 	addMouseListeners: PropTypes.bool,
+	/**
+	* Optionally provide a custom class to apply to the underlying `<li>` node
+	*/
 	className: PropTypes.string,
+	/**
+	* If `true`, the SideNav will be open on initial render.
+	*/
 	defaultExpanded: PropTypes.bool,
+	/**
+	* Specify the duration in milliseconds to delay before displaying the side navigation
+	*/
 	enterDelayMs: PropTypes.number,
+	/**
+	* If `true`, the SideNav will be expanded, otherwise it will be collapsed.
+	* Using this prop causes SideNav to become a controlled component.
+	*/
 	expanded: PropTypes.bool,
+	/**
+	* Provide the `href` to the id of the element on your package that is the
+	* main content.
+	*/
 	href: PropTypes.string,
+	/**
+	* Optionally provide a custom class to apply to the underlying `<li>` node
+	*/
 	isChildOfHeader: PropTypes.bool,
+	/**
+	* Specify if sideNav is standalone
+	*/
 	isFixedNav: PropTypes.bool,
+	/**
+	* Specify if the sideNav will be persistent above the lg breakpoint
+	*/
 	isPersistent: PropTypes.bool,
+	/**
+	* Optional prop to display the side nav rail.
+	*/
 	isRail: PropTypes.bool,
+	/**
+	* An optional listener that is called when the SideNav overlay is clicked
+	*
+	* @param {object} event
+	*/
 	onOverlayClick: PropTypes.func,
+	/**
+	* An optional listener that is called a callback to collapse the SideNav
+	*/
 	onSideNavBlur: PropTypes.func,
+	/**
+	* An optional listener that is called when an event that would cause
+	* toggling the SideNav occurs.
+	*
+	* @param {object} event
+	* @param {boolean} value
+	*/
 	onToggle: PropTypes.func
 };
 //#endregion

package/es/components/UIShell/SideNavDetails.js

@@ -30,8 +30,18 @@ const SideNavDetails = ({ children, className: customClassName, title, ...rest }
 	});
 };
 SideNavDetails.propTypes = {
+	/**
+	* Provide optional children to render in `SideNavDetails`. Useful for
+	* rendering the `SideNavSwitcher` component.
+	*/
 	children: PropTypes.node,
+	/**
+	* Optionally provide a custom class to apply to the underlying `<li>` node
+	*/
 	className: PropTypes.string,
+	/**
+	* Provide the text that will be rendered as the title in the component
+	*/
 	title: PropTypes.string.isRequired
 };
 //#endregion

package/es/components/UIShell/SideNavDivider.js

@@ -23,6 +23,10 @@ const SideNavDivider = ({ className }) => {
 		children: /* @__PURE__ */ jsx("hr", {})
 	});
 };
-SideNavDivider.propTypes = { className: PropTypes.string };
+SideNavDivider.propTypes = { 
+/**
+* Provide an optional class to be applied to the containing node
+*/
+className: PropTypes.string };
 //#endregion
 export { SideNavDivider as default };

package/es/components/UIShell/SideNavFooter.js

@@ -44,9 +44,20 @@ function SideNavFooter({ assistiveText = "Toggle opening or closing the side nav
 }
 SideNavFooter.displayName = "SideNavFooter";
 SideNavFooter.propTypes = {
+	/**
+	* Provide text to be read to screen readers and shown as a tooltip when
+	* interacting with the toggle button in the footer
+	*/
 	assistiveText: PropTypes.string,
 	className: PropTypes.string,
+	/**
+	* Specify whether the side navigation is expanded or collapsed
+	*/
 	expanded: PropTypes.bool.isRequired,
+	/**
+	* Provide a function that is called when the toggle button is interacted
+	* with. Useful for controlling the expansion state of the side navigation.
+	*/
 	onToggle: PropTypes.func.isRequired
 };
 //#endregion

package/es/components/UIShell/SideNavHeader.js

@@ -26,9 +26,22 @@ const SideNavHeader = ({ children, className: customClassName, renderIcon: IconE
 };
 SideNavHeader.displayName = "SideNavHeader";
 SideNavHeader.propTypes = {
+	/**
+	* The child nodes to be rendered
+	*/
 	children: PropTypes.node,
+	/**
+	* Provide an optional class to be applied to the containing node
+	*/
 	className: PropTypes.string,
+	/**
+	* Property to indicate if the side nav container is open (or not). Use to
+	* keep local state and styling in step with the SideNav expansion state.
+	*/
 	isSideNavExpanded: PropTypes.bool,
+	/**
+	* A component used to render an icon.
+	*/
 	renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object]).isRequired
 };
 //#endregion

package/es/components/UIShell/SideNavIcon.js

@@ -29,8 +29,18 @@ const SideNavIcon = ({ children, className: customClassName, small = false }) =>
 	});
 };
 SideNavIcon.propTypes = {
+	/**
+	* Provide a single icon as the child to `SideNavIcon` to render in the
+	* container
+	*/
 	children: PropTypes.node.isRequired,
+	/**
+	* Provide an optional class to be applied to the containing node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the icon should be placed in a smaller bounding box
+	*/
 	small: PropTypes.bool
 };
 //#endregion

package/es/components/UIShell/SideNavItem.js

@@ -29,8 +29,18 @@ const SideNavItem = ({ className: customClassName, children, large = false }) =>
 	});
 };
 SideNavItem.propTypes = {
+	/**
+	* Provide a single icon as the child to `SideNavItem` to render in the
+	* container
+	*/
 	children: PropTypes.node.isRequired,
+	/**
+	* Provide an optional class to be applied to the containing node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify if this is a large variation of the SideNavItem
+	*/
 	large: PropTypes.bool
 };
 //#endregion