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

package/lib/components/Tooltip/Tooltip.js

@@ -163,6 +163,9 @@ const Tooltip = react.default.forwardRef(({ as, align = "top", className: custom
 	});
 });
 Tooltip.propTypes = {
+	/**
+	* Specify how the trigger should align with the tooltip
+	*/
 	align: prop_types.default.oneOf([
 		"top",
 		"top-left",
@@ -185,15 +188,58 @@ Tooltip.propTypes = {
 		"right-end",
 		"right-start"
 	]),
+	/**
+	* Pass in the child to which the tooltip will be applied
+	*/
 	children: prop_types.default.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: prop_types.default.string,
+	/**
+	* Determines wether the tooltip should close when inner content is activated (click, Enter or Space)
+	*/
 	closeOnActivation: prop_types.default.bool,
+	/**
+	* Specify whether the tooltip should be open when it first renders
+	*/
 	defaultOpen: prop_types.default.bool,
+	/**
+	* Provide the description to be rendered inside of the Tooltip. The
+	* description will use `aria-describedby` and will describe the child node
+	* in addition to the text rendered inside of the child. This means that if you
+	* have text in the child node, that it will be announced alongside the
+	* description to the screen reader.
+	*
+	* Note: if label and description are both provided, label will be used and
+	* description will not be used
+	*/
 	description: prop_types.default.node,
+	/**
+	* Specify whether a drop shadow should be rendered
+	*/
 	dropShadow: prop_types.default.bool,
+	/**
+	* Specify the duration in milliseconds to delay before displaying the tooltip
+	*/
 	enterDelayMs: prop_types.default.number,
+	/**
+	* Render the component using the high-contrast theme
+	*/
 	highContrast: prop_types.default.bool,
+	/**
+	* Provide the label to be rendered inside of the Tooltip. The label will use
+	* `aria-labelledby` and will fully describe the child node that is provided.
+	* This means that if you have text in the child node, that it will not be
+	* announced to the screen reader.
+	*
+	* Note: if label and description are both provided, description will not be
+	* used
+	*/
 	label: prop_types.default.node,
+	/**
+	* Specify the duration in milliseconds to delay before hiding the tooltip
+	*/
 	leaveDelayMs: prop_types.default.number
 };
 //#endregion

package/lib/components/TreeView/TreeContext.js

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-require("../../_virtual/_rolldown/runtime.js");
 let react = require("react");
 //#region src/components/TreeView/TreeContext.ts
 /**

package/lib/components/TreeView/TreeNode.js

@@ -340,23 +340,81 @@ const TreeNode = react.default.forwardRef(({ children, className, disabled, id:
 	}) });
 });
 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: require_deprecate.deprecate(prop_types.default.oneOfType([prop_types.default.string, prop_types.default.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: prop_types.default.node,
+	/**
+	* Specify an optional className to be applied to the TreeNode
+	*/
 	className: prop_types.default.string,
+	/**
+	* **[Experimental]** The default expansion state of the node.
+	* *This is only supported with the `enable-treeview-controllable` feature flag!*
+	*/
 	defaultIsExpanded: prop_types.default.bool,
+	/**
+	* **Note:** this is controlled by the parent TreeView component, do not set manually.
+	* TreeNode depth to determine spacing
+	*/
 	depth: require_deprecate.deprecate(prop_types.default.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: prop_types.default.bool,
+	/**
+	* Specify the TreeNode's ID. Must be unique in the DOM and is used for props.active, props.selected and aria-owns
+	*/
 	id: prop_types.default.string,
+	/**
+	* Specify if the TreeNode is expanded (only applicable to parent nodes)
+	*/
 	isExpanded: prop_types.default.bool,
+	/**
+	* Rendered label for the TreeNode
+	*/
 	label: prop_types.default.node,
+	/**
+	* Callback function for when the node receives or loses focus
+	*/
 	onNodeFocusEvent: require_deprecate.deprecate(prop_types.default.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: prop_types.default.func,
+	/**
+	* Callback function for when a parent node is expanded or collapsed
+	*/
 	onToggle: prop_types.default.func,
+	/**
+	* Callback function for when any node in the tree is selected
+	*/
 	onTreeSelect: require_deprecate.deprecate(prop_types.default.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: prop_types.default.oneOfType([prop_types.default.func, prop_types.default.object]),
+	/**
+	* **Note:** this is controlled by the parent TreeView component, do not set manually.
+	* Array containing all selected node IDs in the tree
+	*/
 	selected: require_deprecate.deprecate(prop_types.default.arrayOf(prop_types.default.oneOfType([prop_types.default.string, prop_types.default.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: prop_types.default.string,
+	/**
+	* Optional: The URL the TreeNode is linking to
+	*/
 	href: prop_types.default.string,
+	/**
+	* Specify how the tooltip should align when text is truncated
+	*/
 	align: prop_types.default.oneOf([
 		"top",
 		"bottom",
@@ -371,6 +429,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: prop_types.default.bool
 };
 TreeNode.displayName = "TreeNode";

package/lib/components/TreeView/TreeView.js

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

package/lib/components/UIShell/Content.js

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

package/lib/components/UIShell/Header.js

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

package/lib/components/UIShell/HeaderContainer.js

@@ -36,7 +36,16 @@ function HeaderContainer({ render: Children, isSideNavExpanded = false, ...rest
 	});
 }
 HeaderContainer.propTypes = {
+	/**
+	* Optionally provide a custom class name that is applied to the underlying <header>
+	*/
 	isSideNavExpanded: prop_types.default.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: prop_types.default.elementType.isRequired
 };
 //#endregion

package/lib/components/UIShell/HeaderGlobalAction.js

@@ -61,17 +61,45 @@ const HeaderGlobalAction = react.default.forwardRef(({ "aria-label": ariaLabel,
 	});
 });
 HeaderGlobalAction.propTypes = {
+	/**
+	* Required props for the accessibility label of the button
+	*/
 	...require_AriaPropTypes.AriaLabelPropType,
+	/**
+	* Provide a custom icon for this global action
+	*/
 	children: prop_types.default.node.isRequired,
+	/**
+	* Optionally provide a custom class name that is applied to the underlying
+	* button
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify whether the action is currently active
+	*/
 	isActive: prop_types.default.bool,
+	/**
+	* Optionally provide an onClick handler that is called when the underlying
+	* button fires it's onclick event
+	*/
 	onClick: prop_types.default.func,
+	/**
+	* Specify the alignment of the tooltip to the icon-only button.
+	* Can be one of: start, center, or end.
+	*/
 	tooltipAlignment: prop_types.default.oneOf([
 		"start",
 		"center",
 		"end"
 	]),
+	/**
+	* Enable drop shadow for tooltips for icon-only buttons.
+	*/
 	tooltipDropShadow: prop_types.default.bool,
+	/**
+	* Render the tooltip using the high-contrast theme
+	* Default is true
+	*/
 	tooltipHighContrast: prop_types.default.bool
 };
 HeaderGlobalAction.displayName = "HeaderGlobalAction";

package/lib/components/UIShell/HeaderMenu.js

@@ -142,16 +142,53 @@ const HeaderMenu = frFn((props, ref) => {
 });
 HeaderMenu.displayName = "HeaderMenu";
 HeaderMenu.propTypes = {
+	/**
+	* Required props for the accessibility label of the menu
+	*/
 	...require_AriaPropTypes.AriaLabelPropType,
+	/**
+	* Optionally provide a custom class to apply to the underlying `<li>` node
+	*/
 	className: prop_types.default.string,
+	/**
+	* Provide a custom ref handler for the menu button
+	*/
 	focusRef: prop_types.default.func,
+	/**
+	* Applies selected styles to the item if a user sets this to true and `aria-current !== 'page'`.
+	*/
 	isActive: prop_types.default.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: require_deprecate.deprecate(prop_types.default.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: prop_types.default.string.isRequired,
+	/**
+	* Optionally provide an onBlur handler that is called when the underlying
+	* button fires it's onblur event
+	*/
 	onBlur: prop_types.default.func,
+	/**
+	* Optionally provide an onClick handler that is called when the underlying
+	* button fires it's onclick event
+	*/
 	onClick: prop_types.default.func,
+	/**
+	* Optionally provide an onKeyDown handler that is called when the underlying
+	* button fires it's onkeydown event
+	*/
 	onKeyDown: prop_types.default.func,
+	/**
+	* Optional component to render instead of string
+	*/
 	renderMenuContent: prop_types.default.func,
+	/**
+	* Optionally provide a tabIndex for the underlying menu button
+	*/
 	tabIndex: prop_types.default.number
 };
 //#endregion

package/lib/components/UIShell/HeaderMenuButton.js

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

package/lib/components/UIShell/HeaderMenuItem.js

@@ -50,12 +50,37 @@ const HeaderMenuItem = (0, react.forwardRef)(function HeaderMenuItem({ className
 });
 HeaderMenuItem.displayName = "HeaderMenuItem";
 HeaderMenuItem.propTypes = {
+	/**
+	* Pass in a valid `element` to replace the underlying `<a>` tag with a
+	* custom `Link` element
+	*/
 	...require_Link.LinkPropTypes,
+	/**
+	* Pass in children that are either a string or can be read as a string by
+	* screen readers
+	*/
 	children: prop_types.default.node.isRequired,
+	/**
+	* Optionally provide a custom class to apply to the underlying `<li>` node
+	*/
 	className: prop_types.default.string,
+	/**
+	* If `true` and `aria-current !== 'page'`, applies selected styles to the item and sets `aria-current="true"`.
+	*/
 	isActive: prop_types.default.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: require_deprecate.deprecate(prop_types.default.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: prop_types.default.string,
+	/**
+	* Specify the tab index of the Link
+	*/
 	tabIndex: prop_types.default.number
 };
 //#endregion

package/lib/components/UIShell/HeaderName.js

@@ -35,10 +35,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
+	*/
 	...require_Link.LinkPropTypes,
+	/**
+	* Pass in children that are either a string or can be read as a string by
+	* screen readers
+	*/
 	children: prop_types.default.node.isRequired,
+	/**
+	* Optionally provide a custom class to apply to the underlying `<li>` node
+	*/
 	className: prop_types.default.string,
+	/**
+	* Provide an href for the name to link to
+	*/
 	href: prop_types.default.string,
+	/**
+	* Optionally specify a prefix to your header name. Useful for companies, for
+	* example: IBM [Product Name] versus solely [Product Name]
+	*/
 	prefix: prop_types.default.string
 };
 //#endregion

package/lib/components/UIShell/HeaderNavigation.js

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

package/lib/components/UIShell/HeaderPanel.js

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

package/lib/components/UIShell/HeaderSideNavItems.js

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

package/lib/components/UIShell/Link.js

@@ -33,8 +33,22 @@ const Link = (0, react.forwardRef)((props, ref) => {
 * `@reach/router`
 */
 const LinkPropTypes = {
+	/**
+	* Provide a custom element or component to render the top-level node for the
+	* component.
+	*/
 	as: prop_types.default.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: require_deprecate.deprecate(prop_types.default.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: prop_types.default.bool
 };
 Link.displayName = "Link";

package/lib/components/UIShell/SideNav.js

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

package/lib/components/UIShell/SideNavDetails.js

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

package/lib/components/UIShell/SideNavDivider.js

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