@carbon/react 1.110.0 → 1.111.0-rc.0

package/es/components/UIShell/Header.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 } from "react/jsx-runtime";
 //#region src/components/UIShell/Header.tsx
@@ -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

@@ -8,8 +8,8 @@
 import { usePrefix } from "../../internal/usePrefix.js";
 import Button_default from "../Button/index.js";
 import { AriaLabelPropType } from "../../prop-types/AriaPropTypes.js";
-import React from "react";
 import classNames from "classnames";
+import React from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/UIShell/HeaderGlobalAction.tsx
@@ -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

@@ -14,8 +14,8 @@ import { useMergedRefs } from "../../internal/useMergedRefs.js";
 import { composeEventHandlers } from "../../tools/events.js";
 import { AriaLabelPropType } from "../../prop-types/AriaPropTypes.js";
 import HeaderMenuItem from "./HeaderMenuItem.js";
-import { Children, cloneElement, forwardRef, useContext, useRef, useState } from "react";
 import classNames from "classnames";
+import { Children, cloneElement, forwardRef, useContext, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { ChevronDown } from "@carbon/icons-react";
@@ -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

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import { AriaLabelPropType } from "../../prop-types/AriaPropTypes.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 import { Close, Menu } from "@carbon/icons-react";
@@ -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

@@ -8,8 +8,8 @@
 import { usePrefix } from "../../internal/usePrefix.js";
 import { deprecate } from "../../prop-types/deprecate.js";
 import Link, { LinkPropTypes } from "./Link.js";
-import { forwardRef } from "react";
 import classNames from "classnames";
+import { forwardRef } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/UIShell/HeaderMenuItem.tsx
@@ -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

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import Link, { LinkPropTypes } from "./Link.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/UIShell/HeaderName.tsx
@@ -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

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import { AriaLabelPropType } from "../../prop-types/AriaPropTypes.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/UIShell/HeaderNavigation.tsx
@@ -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

@@ -5,16 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { noopFn } from "../../internal/noopFn.js";
 import { usePrefix } from "../../internal/usePrefix.js";
 import { Escape } from "../../internal/keyboard/keys.js";
 import { match } from "../../internal/keyboard/match.js";
+import { noopFn } from "../../internal/noopFn.js";
 import { isComponentElement } from "../../internal/utils.js";
 import { useMergedRefs } from "../../internal/useMergedRefs.js";
 import { useWindowEvent } from "../../internal/useEvent.js";
 import Switcher from "./Switcher.js";
-import React, { useRef, useState } from "react";
 import classNames from "classnames";
+import React, { useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/UIShell/HeaderPanel.tsx
@@ -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

@@ -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 } from "react/jsx-runtime";
 //#region src/components/UIShell/HeaderSideNavItems.tsx
@@ -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

@@ -14,8 +14,8 @@ import { useDelayedState } from "../../internal/useDelayedState.js";
 import { useMatchMedia } from "../../internal/useMatchMedia.js";
 import { AriaLabelPropType } from "../../prop-types/AriaPropTypes.js";
 import { SideNavContextProvider } from "./SideNavContext.js";
-import { forwardRef, useEffect, useRef } from "react";
 import classNames from "classnames";
+import { forwardRef, useEffect, useRef } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { breakpoints } from "@carbon/layout";
@@ -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

@@ -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";
 //#region src/components/UIShell/SideNavDetails.tsx
@@ -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

@@ -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 } from "react/jsx-runtime";
 //#region src/components/UIShell/SideNavDivider.tsx
@@ -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

@@ -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 { ChevronRight, Close } from "@carbon/icons-react";
@@ -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

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import SideNavIcon from "./SideNavIcon.js";
-import "react";
 import classNames from "classnames";
+import "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/UIShell/SideNavHeader.tsx
@@ -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

@@ -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 } from "react/jsx-runtime";
 //#region src/components/UIShell/SideNavIcon.tsx
@@ -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

@@ -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 } from "react/jsx-runtime";
 //#region src/components/UIShell/SideNavItem.tsx
@@ -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