@carbon/react 1.110.0 → 1.111.0-rc.0

package/es/components/TimePicker/TimePicker.js

@@ -8,8 +8,8 @@
 import { usePrefix } from "../../internal/usePrefix.js";
 import { deprecate } from "../../prop-types/deprecate.js";
 import { useNormalizedInputProps } from "../../internal/useNormalizedInputProps.js";
-import React, { forwardRef } from "react";
 import classNames from "classnames";
+import React, { forwardRef } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/TimePicker/TimePicker.tsx
@@ -130,30 +130,97 @@ const TimePicker = forwardRef((props, ref) => {
 	});
 });
 TimePicker.propTypes = {
+	/**
+	* Pass in the children that will be rendered next to the form control
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the `<input>` should be disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Specify whether you want the underlying label to be visually hidden
+	*/
 	hideLabel: PropTypes.bool,
+	/**
+	* Specify a custom `id` for the `<input>`
+	*/
 	id: PropTypes.string.isRequired,
+	/**
+	* Specify whether the control is currently invalid
+	*/
 	invalid: PropTypes.bool,
+	/**
+	* Provide the text that is displayed when the control is in an invalid state
+	*/
 	invalidText: PropTypes.node,
+	/**
+	* Provide the text that will be read by a screen reader when visiting this
+	* control
+	*/
 	labelText: PropTypes.node,
+	/**
+	* The `light` prop for `TimePicker` has been deprecated. It will be removed in v12. Use the `Layer` component instead.
+	*/
 	light: deprecate(PropTypes.bool, "The `light` prop for `TimePicker` is no longer needed and has been deprecated. It will be removed in the next major release. Use the `Layer` component instead."),
+	/**
+	* Specify the maximum length of the time string in `<input>`
+	*/
 	maxLength: PropTypes.number,
+	/**
+	* Optionally provide an `onBlur` handler that is called whenever the
+	* `<input>` loses focus
+	*/
 	onBlur: PropTypes.func,
+	/**
+	* Optionally provide an `onChange` handler that is called whenever `<input>`
+	* is updated
+	*/
 	onChange: PropTypes.func,
+	/**
+	* Optionally provide an `onClick` handler that is called whenever the
+	* `<input>` is clicked
+	*/
 	onClick: PropTypes.func,
+	/**
+	* Specify the regular expression working as the pattern of the time string in `<input>`
+	*/
 	pattern: PropTypes.string,
+	/**
+	* Specify the placeholder attribute for the `<input>`
+	*/
 	placeholder: PropTypes.string,
+	/**
+	* Specify whether the TimePicker should be read-only
+	*/
 	readOnly: PropTypes.bool,
+	/**
+	* Specify the size of the Time Picker.
+	*/
 	size: PropTypes.oneOf([
 		"sm",
 		"md",
 		"lg"
 	]),
+	/**
+	* Specify the type of the `<input>`
+	*/
 	type: PropTypes.string,
+	/**
+	* Specify the value of the `<input>`
+	*/
 	value: PropTypes.string,
+	/**
+	* Specify a warning message
+	*/
 	warning: PropTypes.bool,
+	/**
+	* Provide the text that is displayed when the control is in an warning state
+	*/
 	warningText: PropTypes.node
 };
 //#endregion

package/es/components/TimePickerSelect/TimePickerSelect.js

@@ -6,8 +6,8 @@
  */
 
 import { usePrefix } from "../../internal/usePrefix.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";
@@ -42,10 +42,25 @@ const TimePickerSelect = forwardRef((props, ref) => {
 	});
 });
 TimePickerSelect.propTypes = {
+	/**
+	* Provide the contents of your TimePickerSelect
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the node containing the label and the select box
+	*/
 	className: PropTypes.string,
+	/**
+	* Optionally provide the default value of the `<select>`
+	*/
 	defaultValue: PropTypes.any,
+	/**
+	* Specify whether the control is disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Specify a custom `id` for the `<select>`
+	*/
 	id: PropTypes.string.isRequired
 };
 //#endregion

package/es/components/Toggle/Toggle.Skeleton.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/Toggle/Toggle.Skeleton.tsx

package/es/components/Toggle/Toggle.js

@@ -8,8 +8,8 @@
 import { usePrefix } from "../../internal/usePrefix.js";
 import { Text } from "../Text/Text.js";
 import { useControllableState } from "../../internal/useControllableState.js";
-import { useRef } from "react";
 import classNames from "classnames";
+import { useRef } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/Toggle/Toggle.tsx
@@ -92,19 +92,65 @@ function Toggle({ "aria-labelledby": ariaLabelledby, className, defaultToggled =
 	});
 }
 Toggle.propTypes = {
+	/**
+	* Specify another element's id to be used as the label for this toggle
+	*/
 	"aria-labelledby": PropTypes.string,
+	/**
+	* Specify a custom className to apply to the form-item node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the toggle should be on by default
+	*/
 	defaultToggled: PropTypes.bool,
+	/**
+	* Whether this control should be disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* If true, the side labels (props.labelA and props.labelB) will be replaced by
+	* props.labelText (if passed), so that the toggle doesn't render a top label.
+	*/
 	hideLabel: PropTypes.bool,
+	/**
+	* Provide an id that unique represents the underlying `<button>`
+	*/
 	id: PropTypes.string.isRequired,
+	/**
+	* Specify the label for the "off" position
+	*/
 	labelA: PropTypes.node,
+	/**
+	* Specify the label for the "on" position
+	*/
 	labelB: PropTypes.node,
+	/**
+	* Provide the text that will be read by a screen reader when visiting this
+	* control. This should be provided unless 'aria-labelledby' is set instead
+	* or you use an external <label> element with its "for" attribute set to the
+	* toggle's id.
+	*/
 	labelText: PropTypes.string,
+	/**
+	* Provide an event listener that is called when the control is clicked
+	*/
 	onClick: PropTypes.func,
+	/**
+	* Provide an event listener that is called when the control is toggled
+	*/
 	onToggle: PropTypes.func,
+	/**
+	* Whether the toggle should be read-only
+	*/
 	readOnly: PropTypes.bool,
+	/**
+	* Specify the size of the Toggle. Currently only supports 'sm' or 'md' (default)
+	*/
 	size: PropTypes.oneOf(["sm", "md"]),
+	/**
+	* Specify whether the control is toggled
+	*/
 	toggled: PropTypes.bool
 };
 //#endregion

package/es/components/ToggleSmall/ToggleSmall.Skeleton.js

@@ -6,8 +6,8 @@
  */
 
 import { PrefixContext } from "../../internal/usePrefix.js";
-import { useContext } from "react";
 import classNames from "classnames";
+import { useContext } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/ToggleSmall/ToggleSmall.Skeleton.tsx
@@ -47,8 +47,19 @@ const ToggleSmallSkeleton = ({ id, labelText, className, ...rest }) => {
 };
 ToggleSmallSkeleton.propTypes = {
 	["aria-label"]: PropTypes.string.isRequired,
+	/**
+	* Specify an optional className to add to the form item wrapper.
+	*/
 	className: PropTypes.string,
+	/**
+	* Provide an id that unique represents the underlying `<input>`
+	*/
 	id: PropTypes.string,
+	/**
+	* Provide the text that will be read by a screen reader when visiting this
+	* control. `aria-label` is always required but will be `null` if `labelText`
+	* is also provided.
+	*/
 	labelText: PropTypes.string
 };
 //#endregion

package/es/components/Toggletip/index.js

@@ -11,8 +11,8 @@ import { match } from "../../internal/keyboard/match.js";
 import { useId } from "../../internal/useId.js";
 import { useWindowEvent } from "../../internal/useEvent.js";
 import { Popover, PopoverContent } from "../Popover/index.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 } from "react/jsx-runtime";
 //#region src/components/Toggletip/index.tsx
@@ -33,8 +33,19 @@ function ToggletipLabel({ as: BaseComponent = "span", children, className: custo
 	});
 }
 ToggletipLabel.propTypes = {
+	/**
+	* Provide a custom element or component to render the top-level node for the
+	* component.
+	*/
 	as: PropTypes.elementType,
+	/**
+	* Custom children to be rendered as the content of the label
+	*/
 	children: PropTypes.node,
+	/**
+	* Provide a custom class name to be added to the outermost node in the
+	* component
+	*/
 	className: PropTypes.string
 };
 const ToggletipContext = React.createContext(void 0);
@@ -126,6 +137,9 @@ function Toggletip({ align, as, autoAlign, className: customClassName, children,
 const { open, ...popoverNonOpenPropTypes } = Popover.propTypes ?? {};
 Toggletip.propTypes = {
 	...popoverNonOpenPropTypes,
+	/**
+	* Specify if the toggletip should be open by default
+	*/
 	defaultOpen: PropTypes.bool
 };
 /**
@@ -153,8 +167,18 @@ const ToggletipButton = forwardRef(function ToggletipButton({ children, classNam
 	});
 });
 ToggletipButton.propTypes = {
+	/**
+	* Custom children to be rendered as the content of the label
+	*/
 	children: PropTypes.node,
+	/**
+	* Provide a custom class name to be added to the outermost node in the
+	* component
+	*/
 	className: PropTypes.string,
+	/**
+	* Provide an accessible label for this button
+	*/
 	label: PropTypes.string
 };
 ToggletipButton.displayName = "ToggletipButton";
@@ -178,7 +202,14 @@ const ToggletipContent = forwardRef((props, ref) => {
 	});
 });
 ToggletipContent.propTypes = {
+	/**
+	* Custom children to be rendered as the content of the label
+	*/
 	children: PropTypes.node,
+	/**
+	* Provide a custom class name to be added to the outermost node in the
+	* component
+	*/
 	className: PropTypes.string
 };
 ToggletipContent.displayName = "ToggletipContent";
@@ -193,7 +224,14 @@ function ToggletipActions({ children, className: customClassName }) {
 	});
 }
 ToggletipActions.propTypes = {
+	/**
+	* Custom children to be rendered as the content of the label
+	*/
 	children: PropTypes.node,
+	/**
+	* Provide a custom class name to be added to the outermost node in the
+	* component
+	*/
 	className: PropTypes.string
 };
 //#endregion

package/es/components/Tooltip/DefinitionTooltip.js

@@ -11,8 +11,8 @@ import { match } from "../../internal/keyboard/match.js";
 import { useFallbackId } from "../../internal/useId.js";
 import { deprecate } from "../../prop-types/deprecate.js";
 import { Popover, PopoverContent } from "../Popover/index.js";
-import { useState } from "react";
 import classNames from "classnames";
+import { useState } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/Tooltip/DefinitionTooltip.tsx
@@ -71,6 +71,9 @@ const DefinitionTooltip = ({ align = "bottom", autoAlign, className, children, d
 	});
 };
 DefinitionTooltip.propTypes = {
+	/**
+	* Specify how the trigger should align with the tooltip
+	*/
 	align: PropTypes.oneOf([
 		"top",
 		"top-left",
@@ -93,14 +96,47 @@ DefinitionTooltip.propTypes = {
 		"right-end",
 		"right-start"
 	]),
+	/**
+	* Will auto-align the popover. This prop is currently experimental and is
+	* subject to future changes. Requires React v17+
+	* @see https://github.com/carbon-design-system/carbon/issues/18714
+	*/
 	autoAlign: PropTypes.bool,
+	/**
+	* The `children` prop will be used as the value that is being defined
+	*/
 	children: PropTypes.node.isRequired,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the tooltip should be open when it first renders
+	*/
 	defaultOpen: PropTypes.bool,
+	/**
+	* The `definition` prop is used as the content inside of the tooltip that
+	* appears when a user interacts with the element rendered by the `children`
+	* prop
+	*/
 	definition: PropTypes.node.isRequired,
+	/**
+	* Provide a value that will be assigned as the id of the tooltip
+	*/
 	id: PropTypes.string,
+	/**
+	* Specifies whether or not the `DefinitionTooltip` should open on hover or not
+	*/
 	openOnHover: PropTypes.bool,
+	/**
+	* [Deprecated in v11] Please use the `definition` prop instead.
+	*
+	* Provide the text that will be displayed in the tooltip when it is rendered.
+	*/
 	tooltipText: deprecate(PropTypes.node, "The tooltipText prop has been deprecated. Please use the `definition` prop instead."),
+	/**
+	* The CSS class name of the trigger element
+	*/
 	triggerClassName: PropTypes.string
 };
 //#endregion

package/es/components/Tooltip/Tooltip.js

@@ -13,8 +13,8 @@ import { useId } from "../../internal/useId.js";
 import { Popover, PopoverContent } from "../Popover/index.js";
 import { useDelayedState } from "../../internal/useDelayedState.js";
 import { useNoInteractiveChildren } from "../../internal/useNoInteractiveChildren.js";
-import React, { useCallback, useEffect, useRef, useState } from "react";
 import classNames from "classnames";
+import React, { useCallback, useEffect, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/Tooltip/Tooltip.tsx
@@ -159,6 +159,9 @@ const Tooltip = React.forwardRef(({ as, align = "top", className: customClassNam
 	});
 });
 Tooltip.propTypes = {
+	/**
+	* Specify how the trigger should align with the tooltip
+	*/
 	align: PropTypes.oneOf([
 		"top",
 		"top-left",
@@ -181,15 +184,58 @@ Tooltip.propTypes = {
 		"right-end",
 		"right-start"
 	]),
+	/**
+	* Pass in the child to which the tooltip will be applied
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Determines wether the tooltip should close when inner content is activated (click, Enter or Space)
+	*/
 	closeOnActivation: PropTypes.bool,
+	/**
+	* Specify whether the tooltip should be open when it first renders
+	*/
 	defaultOpen: PropTypes.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: PropTypes.node,
+	/**
+	* Specify whether a drop shadow should be rendered
+	*/
 	dropShadow: PropTypes.bool,
+	/**
+	* Specify the duration in milliseconds to delay before displaying the tooltip
+	*/
 	enterDelayMs: PropTypes.number,
+	/**
+	* Render the component using the high-contrast theme
+	*/
 	highContrast: PropTypes.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: PropTypes.node,
+	/**
+	* Specify the duration in milliseconds to delay before hiding the tooltip
+	*/
 	leaveDelayMs: PropTypes.number
 };
 //#endregion

package/es/components/TreeView/TreeNode.js

@@ -14,8 +14,8 @@ import { useFeatureFlag } from "../FeatureFlags/index.js";
 import { IconButton } from "../IconButton/index.js";
 import { useControllableState } from "../../internal/useControllableState.js";
 import { DepthContext, TreeContext } from "./TreeContext.js";
-import React, { isValidElement, useCallback, useContext, useEffect, useRef, useState } from "react";
 import classNames from "classnames";
+import React, { isValidElement, useCallback, useContext, useEffect, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { CaretDown } from "@carbon/icons-react";
@@ -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

@@ -13,8 +13,8 @@ import { useFeatureFlag } from "../FeatureFlags/index.js";
 import { useControllableState } from "../../internal/useControllableState.js";
 import { DepthContext, TreeContext } from "./TreeContext.js";
 import TreeNode from "./TreeNode.js";
-import { useEffect, useMemo, useRef, useState } from "react";
 import classNames from "classnames";
+import { useEffect, useMemo, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/TreeView/TreeView.tsx
@@ -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

@@ -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/components/UIShell/Content.ts
 /**
@@ -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