@carbon/react 1.110.0 → 1.111.0-rc.0

package/es/components/UIShell/SideNavItems.js

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import { SideNavContext, SideNavContextProvider } from "./SideNavContext.js";
-import { useContext } from "react";
 import classNames from "classnames";
+import { useContext } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/UIShell/SideNavItems.tsx
@@ -32,8 +32,19 @@ const SideNavItems = ({ className: customClassName, children, isSideNavExpanded
 };
 SideNavItems.displayName = "SideNavItems";
 SideNavItems.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,
+	/**
+	* 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
 };
 //#endregion

package/es/components/UIShell/SideNavLink.js

@@ -11,8 +11,8 @@ import { SideNavContext } from "./SideNavContext.js";
 import SideNavIcon from "./SideNavIcon.js";
 import SideNavItem from "./SideNavItem.js";
 import SideNavLinkText from "./SideNavLinkText.js";
-import { forwardRef, useContext } from "react";
 import classNames from "classnames";
+import { forwardRef, useContext } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/UIShell/SideNavLink.tsx
@@ -49,12 +49,34 @@ const SideNavLink = forwardRef((props, ref) => {
 SideNavLink.displayName = "SideNavLink";
 SideNavLink.propTypes = {
 	...LinkPropTypes,
+	/**
+	* Specify the text content for the link
+	*/
 	children: PropTypes.node.isRequired,
+	/**
+	* Provide an optional class to be applied to the containing node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the link is the current page
+	*/
 	isActive: PropTypes.bool,
+	/**
+	* 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,
+	/**
+	* Specify if this is a large variation of the SideNavLink
+	*/
 	large: PropTypes.bool,
+	/**
+	* A component used to render an icon.
+	*/
 	renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
+	/**
+	* Optional prop to specify the tabIndex of the button. If undefined, it will be applied default validation
+	*/
 	tabIndex: PropTypes.number
 };
 //#endregion

package/es/components/UIShell/SideNavLinkText.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/SideNavLinkText.tsx
@@ -26,7 +26,13 @@ function SideNavLinkText({ className: customClassName, children, ...rest }) {
 	});
 }
 SideNavLinkText.propTypes = {
+	/**
+	* Provide the content for the link text
+	*/
 	children: PropTypes.node.isRequired,
+	/**
+	* Provide an optional class to be applied to the containing node
+	*/
 	className: PropTypes.string
 };
 //#endregion

package/es/components/UIShell/SideNavMenu.js

@@ -10,8 +10,8 @@ import { Escape } from "../../internal/keyboard/keys.js";
 import { match } from "../../internal/keyboard/match.js";
 import { SideNavContext } from "./SideNavContext.js";
 import SideNavIcon from "./SideNavIcon.js";
-import React, { forwardRef, useContext, useEffect, useRef, useState } from "react";
 import classNames from "classnames";
+import React, { forwardRef, useContext, useEffect, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { ChevronDown } from "@carbon/icons-react";
@@ -83,14 +83,45 @@ const SideNavMenu = forwardRef(({ className: customClassName, children, defaultE
 });
 SideNavMenu.displayName = "SideNavMenu";
 SideNavMenu.propTypes = {
+	/**
+	* Provide <SideNavMenuItem>'s inside of the `SideNavMenu`
+	*/
 	children: PropTypes.node,
+	/**
+	* Provide an optional class to be applied to the containing node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the menu should default to expanded. By default, it will
+	* be closed.
+	*/
 	defaultExpanded: PropTypes.bool,
+	/**
+	* Specify whether the `SideNavMenu` is "active". `SideNavMenu` should be
+	* considered active if one of its menu items are a link for the current
+	* page.
+	*/
 	isActive: PropTypes.bool,
+	/**
+	* 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,
+	/**
+	* Specify if this is a large variation of the SideNavMenu
+	*/
 	large: PropTypes.bool,
+	/**
+	* A component used to render an icon.
+	*/
 	renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
+	/**
+	* Optional prop to specify the tabIndex of the button. If undefined, it will be applied default validation
+	*/
 	tabIndex: PropTypes.number,
+	/**
+	* Provide the text for the overall menu name
+	*/
 	title: PropTypes.string.isRequired
 };
 /**

package/es/components/UIShell/SideNavMenuItem.js

@@ -8,8 +8,8 @@
 import { usePrefix } from "../../internal/usePrefix.js";
 import Link from "./Link.js";
 import SideNavLinkText from "./SideNavLinkText.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/SideNavMenuItem.tsx
@@ -39,10 +39,27 @@ const SideNavMenuItem = forwardRef((props, ref) => {
 });
 SideNavMenuItem.displayName = "SideNavMenuItem";
 SideNavMenuItem.propTypes = {
+	/**
+	* Optional component to render instead of default Link
+	*/
 	as: PropTypes.elementType,
+	/**
+	* Specify the children to be rendered inside of the `SideNavMenuItem`
+	*/
 	children: PropTypes.node,
+	/**
+	* Provide an optional class to be applied to the containing node
+	*/
 	className: PropTypes.string,
+	/**
+	* Optionally provide an href for the underlying li`
+	*/
 	href: PropTypes.string,
+	/**
+	* Optionally specify whether the link is "active". An active link is one that
+	* has an href that is the same as the current page. Can also pass in
+	* `aria-current="page"`, as well.
+	*/
 	isActive: PropTypes.bool
 };
 //#endregion

package/es/components/UIShell/SideNavSwitcher.js

@@ -7,8 +7,8 @@
 
 import { usePrefix } from "../../internal/usePrefix.js";
 import { useId } from "../../internal/useId.js";
-import { forwardRef } from "react";
 import classNames from "classnames";
+import { forwardRef } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { ChevronDown } from "@carbon/icons-react";
@@ -59,9 +59,25 @@ const SideNavSwitcher = forwardRef((props, ref) => {
 });
 SideNavSwitcher.displayName = "SideNavSwitcher";
 SideNavSwitcher.propTypes = {
+	/**
+	* Provide an optional class to be applied to the containing node
+	*/
 	className: PropTypes.string,
+	/**
+	* Provide the label for the switcher. This will be the first visible option
+	* when someone views this control
+	*/
 	labelText: PropTypes.string.isRequired,
+	/**
+	* Provide a callback function that is called whenever the switcher value is
+	* updated
+	*/
 	onChange: PropTypes.func,
+	/**
+	* Provide an array of options to be rendered in the switcher as an
+	* `<option>`. The text value will be what is displayed to the user and is set
+	* as the `value` prop for each `<option>`.
+	*/
 	options: PropTypes.arrayOf(PropTypes.string).isRequired
 };
 //#endregion

package/es/components/UIShell/SkipToContent.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/SkipToContent.tsx
@@ -28,9 +28,20 @@ function SkipToContent({ children = "Skip to main content", className: customCla
 	});
 }
 SkipToContent.propTypes = {
+	/**
+	* A ReactNode to display in the SkipToContent `a` tag.
+	* `'Skip to main content'` by default.
+	*/
 	children: PropTypes.string,
 	className: PropTypes.string,
+	/**
+	* Provide the `href` to the id of the element on your package that is the
+	* main content. `#main-content` by default.
+	*/
 	href: PropTypes.string,
+	/**
+	* Optionally override the default tabindex of 0
+	*/
 	tabIndex: PropTypes.string
 };
 //#endregion

package/es/components/UIShell/Switcher.js

@@ -11,8 +11,8 @@ import { useMergedRefs } from "../../internal/useMergedRefs.js";
 import { AriaLabelPropType } from "../../prop-types/AriaPropTypes.js";
 import SwitcherItem from "./SwitcherItem.js";
 import SwitcherDivider from "./SwitcherDivider.js";
-import { Children, cloneElement, forwardRef, useRef } from "react";
 import classNames from "classnames";
+import { Children, cloneElement, forwardRef, useRef } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/UIShell/Switcher.tsx
@@ -69,9 +69,21 @@ const Switcher = forwardRef((props, forwardRef) => {
 });
 Switcher.displayName = "Switcher";
 Switcher.propTypes = {
+	/**
+	* Required props for accessibility label on the underlying menu
+	*/
 	...AriaLabelPropType,
+	/**
+	* expects to receive <SwitcherItem />
+	*/
 	children: PropTypes.node.isRequired,
+	/**
+	* Optionally provide a custom class to apply to the underlying `<ul>` node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the panel is expanded
+	*/
 	expanded: PropTypes.bool
 };
 //#endregion

package/es/components/UIShell/SwitcherDivider.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/SwitcherDivider.tsx
@@ -18,6 +18,10 @@ const SwitcherDivider = ({ className: customClassName, ...other }) => {
 		className: classNames$1
 	}) });
 };
-SwitcherDivider.propTypes = { className: PropTypes.string };
+SwitcherDivider.propTypes = { 
+/**
+* Optionally provide a custom class to apply to the underlying `<hr>` node
+*/
+className: PropTypes.string };
 //#endregion
 export { SwitcherDivider as default };

package/es/components/UIShell/SwitcherItem.js

@@ -10,8 +10,8 @@ import { ArrowDown, ArrowUp } from "../../internal/keyboard/keys.js";
 import { match } from "../../internal/keyboard/match.js";
 import { AriaLabelPropType } from "../../prop-types/AriaPropTypes.js";
 import Link 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/SwitcherItem.tsx
@@ -68,15 +68,45 @@ const SwitcherItem = forwardRef((props, forwardRef) => {
 SwitcherItem.displayName = "SwitcherItem";
 SwitcherItem.propTypes = {
 	...AriaLabelPropType,
+	/**
+	* Specify the text content for the link
+	*/
 	children: PropTypes.node.isRequired,
+	/**
+	* Optionally provide a custom class to apply to the underlying `<li>` node
+	*/
 	className: PropTypes.string,
+	/**
+	* event handlers
+	*/
 	handleSwitcherItemFocus: PropTypes.func,
+	/**
+	* Optionally provide an href for the underlying li`
+	*/
 	href: PropTypes.string,
+	/**
+	* Specify the index of the SwitcherItem
+	*/
 	index: PropTypes.number,
+	/**
+	* event handlers
+	*/
 	onClick: PropTypes.func,
+	/**
+	* event handlers
+	*/
 	onKeyDown: PropTypes.func,
+	/**
+	* Specify the tab index of the Link
+	*/
 	tabIndex: PropTypes.number,
+	/**
+	* Specify where to open the link.
+	*/
 	target: PropTypes.string,
+	/**
+	* The rel property for the link.
+	*/
 	rel: PropTypes.string
 };
 //#endregion

package/es/components/UnorderedList/UnorderedList.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/UnorderedList/UnorderedList.tsx
@@ -28,9 +28,21 @@ function UnorderedList({ className, nested = false, isExpressive = false, ...oth
 	});
 }
 UnorderedList.propTypes = {
+	/**
+	* Specify a collection of ListItem's to be rendered in the UnorderedList
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the underlying `<ul>` node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether this ordered list expressive or not
+	*/
 	isExpressive: PropTypes.bool,
+	/**
+	* Specify whether the list is nested, or not
+	*/
 	nested: PropTypes.bool
 };
 //#endregion

package/es/internal/FloatingMenu.js

@@ -5,11 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { warning } from "./warning.js";
 import { PrefixContext } from "./usePrefix.js";
 import { Tab } from "./keyboard/keys.js";
 import { match } from "./keyboard/match.js";
 import { selectorFocusable, selectorTabbable } from "./keyboard/navigation.js";
+import { warning } from "./warning.js";
 import { wrapFocus, wrapFocusWithoutSentinels } from "./wrapFocus.js";
 import { OptimizedResize } from "./OptimizedResize.js";
 import { enabled } from "@carbon/feature-flags";

package/es/internal/OptimizedResize.js

@@ -31,10 +31,14 @@ const OptimizedResize = (() => {
 	const addCallback = (callback) => {
 		if (callbacks.indexOf(callback) < 0) callbacks.push(callback);
 	};
-	return { add: (callback) => {
+	return { 
+	/** Adds a callback function to be executed on window `resize`. */
+add: (callback) => {
 		if (!callbacks.length) win.addEventListener("resize", handleResize);
 		addCallback(callback);
-		return { remove: () => {
+		return { 
+		/** Removes the callback. */
+remove: () => {
 			const index = callbacks.indexOf(callback);
 			if (index >= 0) callbacks.splice(index, 1);
 		} };

package/es/internal/usePresence.js

@@ -51,7 +51,13 @@ const usePresence = (ref, isOpen) => {
 		prefix
 	]);
 	return {
+		/**
+		* Indicates whether the ref object is supposed to be mounted
+		*/
 		isPresent: isOpen || exitState !== "finished",
+		/**
+		* Indicates whether the ref object is currently exiting
+		*/
 		isExiting
 	};
 };

package/es/tools/wrapComponent.js

@@ -6,8 +6,8 @@
  */
 
 import { usePrefix } from "../internal/usePrefix.js";
-import React from "react";
 import classNames from "classnames";
+import React from "react";
 import PropTypes from "prop-types";
 //#region src/tools/wrapComponent.ts
 /**

package/lib/components/AILabel/index.js

@@ -11,10 +11,10 @@ const require_useId = require("../../internal/useId.js");
 const require_deprecate = require("../../prop-types/deprecate.js");
 const require_index = require("../IconButton/index.js");
 const require_index$1 = require("../Toggletip/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");
@@ -38,7 +38,13 @@ const AILabelContent = ({ className, children }) => {
 };
 AILabelContent.displayName = "AILabelContent";
 AILabelContent.propTypes = {
+	/**
+	* Specify the content you want rendered inside the AILabel ToggleTip
+	*/
 	children: prop_types.default.node,
+	/**
+	* Specify an optional className to be added to the AILabel callout
+	*/
 	className: prop_types.default.string
 };
 const AILabelActions = ({ className, children }) => {
@@ -49,7 +55,13 @@ const AILabelActions = ({ className, children }) => {
 };
 AILabelActions.displayName = "AILabelActions";
 AILabelActions.propTypes = {
+	/**
+	* Specify the content you want rendered inside the AILabel callout toolbar
+	*/
 	children: prop_types.default.node,
+	/**
+	* Specify an optional className to be added to the AILabel toolbar
+	*/
 	className: prop_types.default.string
 };
 const AILabel = react.default.forwardRef(function AILabel({ aiText = "AI", aiTextLabel, textLabel, align, autoAlign = true, children, className, kind = "default", onRevertClick, revertActive, revertLabel = "Revert to AI input", slugLabel = "Show information", ["aria-label"]: ariaLabel = "Show information", size = "xs", ...rest }, ref) {
@@ -107,14 +119,42 @@ const AILabel = react.default.forwardRef(function AILabel({ aiText = "AI", aiTex
 AILabel.displayName = "AILabel";
 AILabel.propTypes = {
 	...require_index$1.default.propTypes,
+	/**
+	* Specify the content you want rendered inside the `AILabel` ToggleTip
+	*/
 	AILabelContent: prop_types.default.node,
+	/**
+	* Specify the correct translation of the AI text
+	*/
 	aiText: prop_types.default.string,
+	/**
+	* @deprecated
+	* Specify additional text to be rendered next to the AI label in the inline variant
+	*/
 	aiTextLabel: require_deprecate.deprecate(prop_types.default.string, "`aiTextLabel` on `AILabel` has been deprecated - Please use the `textLabel` prop instead"),
+	/**
+	* Specify the text that will be provided to the aria-label of the `AILabel` button
+	*/
 	"aria-label": prop_types.default.string,
+	/**
+	* Specify the type of `AILabel`, from the following list of types:
+	*/
 	kind: prop_types.default.oneOf(["default", "inline"]),
+	/**
+	* Callback function that fires when the revert button is clicked
+	*/
 	onRevertClick: prop_types.default.func,
+	/**
+	* Specify whether the revert button should be visible
+	*/
 	revertActive: prop_types.default.bool,
+	/**
+	* Specify the text that should be shown when the revert button is hovered
+	*/
 	revertLabel: prop_types.default.string,
+	/**
+	* Specify the size of the button, from the following list of sizes:
+	*/
 	size: prop_types.default.oneOf([
 		"mini",
 		"2xs",
@@ -124,7 +164,14 @@ AILabel.propTypes = {
 		"lg",
 		"xl"
 	]),
+	/**
+	* @deprecated
+	* Specify the text that will be provided to the aria-label of the `AILabel` button
+	*/
 	slugLabel: require_deprecate.deprecate(prop_types.default.string, "`slugLabel` on `AILabel` has been deprecated - Please use the `ariaLabel` prop instead"),
+	/**
+	* Specify additional text to be rendered next to the AI label in the inline variant
+	*/
 	textLabel: prop_types.default.string
 };
 //#endregion

package/lib/components/AISkeleton/AISkeletonIcon.js

@@ -8,10 +8,10 @@
 const require_runtime = require("../../_virtual/_rolldown/runtime.js");
 const require_usePrefix = require("../../internal/usePrefix.js");
 const require_SkeletonIcon = require("../SkeletonIcon/SkeletonIcon.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");
@@ -29,7 +29,13 @@ const AISkeletonIcon = ({ className, ...rest }) => {
 	});
 };
 AISkeletonIcon.propTypes = {
+	/**
+	* Specify an optional className to add.
+	*/
 	className: prop_types.default.string,
+	/**
+	* The CSS styles.
+	*/
 	style: prop_types.default.object
 };
 //#endregion

package/lib/components/AISkeleton/AISkeletonPlaceholder.js

@@ -8,10 +8,10 @@
 const require_runtime = require("../../_virtual/_rolldown/runtime.js");
 const require_usePrefix = require("../../internal/usePrefix.js");
 const require_SkeletonPlaceholder = require("../SkeletonPlaceholder/SkeletonPlaceholder.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");
@@ -28,6 +28,11 @@ const AISkeletonPlaceholder = ({ className, ...other }) => {
 		...other
 	});
 };
-AISkeletonPlaceholder.propTypes = { className: prop_types.default.string };
+AISkeletonPlaceholder.propTypes = { 
+/**
+* Add a custom class to the component
+* to set the height and width
+*/
+className: prop_types.default.string };
 //#endregion
 exports.default = AISkeletonPlaceholder;

package/lib/components/AISkeleton/AISkeletonText.js

@@ -8,10 +8,10 @@
 const require_runtime = require("../../_virtual/_rolldown/runtime.js");
 const require_usePrefix = require("../../internal/usePrefix.js");
 const require_SkeletonText = require("../SkeletonText/SkeletonText.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");
@@ -29,10 +29,25 @@ const AISkeletonText = ({ className, ...rest }) => {
 	});
 };
 AISkeletonText.propTypes = {
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: prop_types.default.string,
+	/**
+	* generates skeleton text at a larger size
+	*/
 	heading: prop_types.default.bool,
+	/**
+	* the number of lines shown if paragraph is true
+	*/
 	lineCount: prop_types.default.number,
+	/**
+	* will generate multiple lines of text
+	*/
 	paragraph: prop_types.default.bool,
+	/**
+	* width (in px or %) of single line of text or max-width of paragraph lines
+	*/
 	width: prop_types.default.string
 };
 //#endregion