@carbon/react 1.110.0 → 1.111.0-rc.0

package/es/components/StructuredList/StructuredList.js

@@ -10,8 +10,8 @@ import { Text } from "../Text/Text.js";
 import { useId } from "../../internal/useId.js";
 import { deprecate } from "../../prop-types/deprecate.js";
 import { useOutsideClick } from "../../internal/useOutsideClick.js";
-import React, { useRef, useState } from "react";
 import classNames from "classnames";
+import React, { useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { RadioButton, RadioButtonChecked } from "@carbon/icons-react";
@@ -48,13 +48,38 @@ function StructuredListWrapper(props) {
 	});
 }
 StructuredListWrapper.propTypes = {
+	/**
+	* Specify a label to be read by screen readers on the container node
+	*/
 	["aria-label"]: PropTypes.string,
+	/**
+	* Deprecated, please use `aria-label` instead.
+	* Specify a label to be read by screen readers on the container note.
+	*/
 	ariaLabel: deprecate(PropTypes.string, "This prop syntax has been deprecated. Please use the new `aria-label`."),
+	/**
+	* Provide the contents of your StructuredListWrapper
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify if structured list is condensed, default is false
+	*/
 	isCondensed: PropTypes.bool,
+	/**
+	* Specify if structured list is flush, not valid for selection variant, default is false
+	*/
 	isFlush: PropTypes.bool,
+	/**
+	* Specify whether your StructuredListWrapper should have selections
+	*/
 	selection: PropTypes.bool,
+	/**
+	* Specify which row will be selected initially
+	*/
 	selectedInitialRow: PropTypes.string
 };
 function StructuredListHead(props) {
@@ -67,7 +92,13 @@ function StructuredListHead(props) {
 	});
 }
 StructuredListHead.propTypes = {
+	/**
+	* Provide the contents of your StructuredListHead
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the node
+	*/
 	className: PropTypes.string
 };
 function StructuredListBody(props) {
@@ -80,9 +111,18 @@ function StructuredListBody(props) {
 	});
 }
 StructuredListBody.propTypes = {
+	/**
+	* Provide the contents of your StructuredListBody
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
 	head: PropTypes.bool,
+	/**
+	* Provide a handler that is invoked on the key down event for the control
+	*/
 	onKeyDown: PropTypes.func
 };
 const GridRowContext = React.createContext(null);
@@ -134,13 +174,37 @@ function StructuredListRow(props) {
 	});
 }
 StructuredListRow.propTypes = {
+	/**
+	* Provide the contents of your StructuredListRow
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether your StructuredListRow should be used as a header row
+	*/
 	head: PropTypes.bool,
+	/**
+	* Specify whether a `<label>` should be used
+	*/
 	label: deprecate(PropTypes.bool, `\nThe \`label\` prop is no longer needed and will be removed in the next major version of Carbon.`),
+	/**
+	* Provide a handler that is invoked on the click
+	*/
 	onClick: PropTypes.func,
+	/**
+	* Provide a handler that is invoked on the key down event for the control,
+	*/
 	onKeyDown: PropTypes.func,
+	/**
+	* Mark if this row should be selectable
+	*/
 	selection: PropTypes.bool,
+	/**
+	* Specify row id so that it can be used for initial selection
+	*/
 	id: PropTypes.string
 };
 function StructuredListInput(props) {
@@ -168,12 +232,33 @@ function StructuredListInput(props) {
 	});
 }
 StructuredListInput.propTypes = {
+	/**
+	* Specify an optional className to be applied to the input
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the underlying input should be checked by default
+	*/
 	defaultChecked: deprecate(PropTypes.bool, `\nThe prop \`defaultChecked\` is no longer needed and will be removed in the next major version of Carbon.`),
+	/**
+	* Specify a custom `id` for the input
+	*/
 	id: PropTypes.string,
+	/**
+	* Provide a `name` for the input
+	*/
 	name: PropTypes.string,
+	/**
+	* Provide an optional hook that is called each time the input is updated
+	*/
 	onChange: PropTypes.func,
+	/**
+	* Provide a `title` for the input
+	*/
 	title: PropTypes.string,
+	/**
+	* Specify the value of the input
+	*/
 	value: deprecate(PropTypes.oneOfType([PropTypes.string, PropTypes.number]).isRequired, `\nThe prop \`value\` will be removed in the next major version of Carbon.`)
 };
 function StructuredListCell(props) {
@@ -199,9 +284,21 @@ function StructuredListCell(props) {
 	});
 }
 StructuredListCell.propTypes = {
+	/**
+	* Provide the contents of your StructuredListCell
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether your StructuredListCell should be used as a header cell
+	*/
 	head: PropTypes.bool,
+	/**
+	* Specify whether your StructuredListCell should have text wrapping
+	*/
 	noWrap: PropTypes.bool
 };
 //#endregion

package/es/components/Switch/IconSwitch.js

@@ -5,11 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { noopFn } from "../../internal/noopFn.js";
 import { usePrefix } from "../../internal/usePrefix.js";
+import { noopFn } from "../../internal/noopFn.js";
 import { IconButton } from "../IconButton/index.js";
-import { forwardRef, useState } from "react";
 import classNames from "classnames";
+import { forwardRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/Switch/IconSwitch.tsx
@@ -77,6 +77,9 @@ const IconSwitch = forwardRef((props, ref) => {
 });
 IconSwitch.displayName = "IconSwitch";
 IconSwitch.propTypes = {
+	/**
+	* Specify how the trigger should align with the tooltip
+	*/
 	align: PropTypes.oneOf([
 		"top",
 		"top-left",
@@ -87,21 +90,65 @@ IconSwitch.propTypes = {
 		"left",
 		"right"
 	]),
+	/**
+	* Children to be rendered inside of the `IconSwitch`.
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be added to your `IconSwitch`.
+	*/
 	className: PropTypes.string,
+	/**
+	* Whether the `IconSwitch` should be disabled.
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Specify the duration in milliseconds to delay before displaying the tooltip
+	*/
 	enterDelayMs: PropTypes.number,
+	/**
+	* The index of the `IconSwitch`.
+	*
+	* Reserved for usage in `ContentSwitcher`.
+	*/
 	index: PropTypes.number,
+	/**
+	* Specify the duration in milliseconds to delay before hiding the tooltip
+	*/
 	leaveDelayMs: PropTypes.number,
+	/**
+	* The name of the `IconSwitch`.
+	*/
 	name: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+	/**
+	* A handler that is invoked when a user clicks on the control.
+	*
+	* Reserved for usage in `ContentSwitcher`.
+	*/
 	onClick: PropTypes.func,
+	/**
+	* A handler that is invoked on the key down event for the control.
+	*
+	* Reserved for usage in `ContentSwitcher`.
+	*/
 	onKeyDown: PropTypes.func,
+	/**
+	* Whether the `IconSwitch` is selected.
+	*
+	* Reserved for usage in `ContentSwitcher`.
+	*/
 	selected: PropTypes.bool,
+	/**
+	* Specify the size of the underlying icon-only button.
+	*/
 	size: PropTypes.oneOf([
 		"sm",
 		"md",
 		"lg"
 	]),
+	/**
+	* `Tooltip` text.
+	*/
 	text: PropTypes.string
 };
 //#endregion

package/es/components/Switch/Switch.js

@@ -5,10 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { noopFn } from "../../internal/noopFn.js";
 import { usePrefix } from "../../internal/usePrefix.js";
-import React from "react";
+import { noopFn } from "../../internal/noopFn.js";
 import classNames from "classnames";
+import React from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/Switch/Switch.tsx
@@ -61,14 +61,44 @@ const Switch = React.forwardRef((props, tabRef) => {
 });
 Switch.displayName = "Switch";
 Switch.propTypes = {
+	/**
+	* Provide child elements to be rendered inside of the Switch
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be added to your Switch
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether or not the Switch should be disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* The index of your Switch in your ContentSwitcher that is used for event handlers.
+	* Reserved for usage in ContentSwitcher
+	*/
 	index: PropTypes.number,
+	/**
+	* Provide the name of your Switch that is used for event handlers
+	*/
 	name: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+	/**
+	* A handler that is invoked when a user clicks on the control.
+	* Reserved for usage in ContentSwitcher
+	*/
 	onClick: PropTypes.func,
+	/**
+	* A handler that is invoked on the key down event for the control.
+	* Reserved for usage in ContentSwitcher
+	*/
 	onKeyDown: PropTypes.func,
+	/**
+	* Whether your Switch is selected. Reserved for usage in ContentSwitcher
+	*/
 	selected: PropTypes.bool,
+	/**
+	* Provide the contents of your Switch
+	*/
 	text: PropTypes.string
 };
 //#endregion

package/es/components/TabContent/TabContent.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/TabContent/TabContent.tsx
@@ -30,8 +30,17 @@ function TabContent(props) {
 	});
 }
 TabContent.propTypes = {
+	/**
+	* Pass in content to render inside the TabContent
+	*/
 	children: PropTypes.node,
+	/**
+	* Provide a className for the tab content container
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the TabContent is selected
+	*/
 	selected: PropTypes.bool
 };
 //#endregion

package/es/components/Tabs/Tabs.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/Tabs/Tabs.Skeleton.tsx
@@ -45,7 +45,13 @@ function TabsSkeleton({ className, contained, ...rest }) {
 	});
 }
 TabsSkeleton.propTypes = {
+	/**
+	* Specify an optional className to add.
+	*/
 	className: PropTypes.string,
+	/**
+	* Provide the type of Tab
+	*/
 	contained: PropTypes.bool
 };
 //#endregion

package/es/components/Tabs/Tabs.js

@@ -21,8 +21,8 @@ import { useControllableState } from "../../internal/useControllableState.js";
 import { GridAsGridComponent } from "../Grid/Grid.js";
 import { useMatchMedia } from "../../internal/useMatchMedia.js";
 import { usePressable } from "./usePressable.js";
-import React, { Children, cloneElement, createContext, forwardRef, isValidElement, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import classNames from "classnames";
+import React, { Children, cloneElement, createContext, forwardRef, isValidElement, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { ChevronLeft, ChevronRight, Close } from "@carbon/icons-react";
@@ -79,13 +79,36 @@ function Tabs({ children, defaultSelectedIndex = 0, onChange, selectedIndex: con
 	});
 }
 Tabs.propTypes = {
+	/**
+	* Provide child elements to be rendered inside the `Tabs`.
+	* These elements should render either `TabsList` or `TabsPanels`
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify which content tab should be initially selected when the component
+	* is first rendered
+	*/
 	defaultSelectedIndex: PropTypes.number,
+	/**
+	* Whether the render Tab children should be dismissable.
+	*/
 	dismissable: PropTypes.bool,
+	/**
+	* Provide an optional function which is called whenever the state of the
+	* `Tabs` changes
+	*/
 	onChange: PropTypes.func,
+	/**
+	* If specifying the `onTabCloseRequest` prop, provide a callback function
+	* responsible for removing the tab when close button is pressed on one of the Tab elements
+	*/
 	onTabCloseRequest: (props) => {
 		if (props.dismissable && !props.onTabCloseRequest) return /* @__PURE__ */ new Error("dismissable property specified without also providing an onTabCloseRequest property.");
 	},
+	/**
+	* Control which content panel is currently selected. This puts the component
+	* in a controlled mode and should be used along with `onChange`
+	*/
 	selectedIndex: PropTypes.number
 };
 function TabsVertical({ children, height, defaultSelectedIndex = 0, onChange, selectedIndex: controlledSelectedIndex, ...rest }) {
@@ -112,10 +135,29 @@ function TabsVertical({ children, height, defaultSelectedIndex = 0, onChange, se
 	});
 }
 TabsVertical.propTypes = {
+	/**
+	* Provide child elements to be rendered inside the `TabsVertical`.
+	* These elements should render either `TabsListVertical` or `TabsPanels`
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify which content tab should be initially selected when the component
+	* is first rendered
+	*/
 	defaultSelectedIndex: PropTypes.number,
+	/**
+	* Option to set a height style only if using vertical variation
+	*/
 	height: PropTypes.string,
+	/**
+	* Provide an optional function which is called whenever the state of the
+	* `Tabs` changes
+	*/
 	onChange: PropTypes.func,
+	/**
+	* Control which content panel is currently selected. This puts the component
+	* in a controlled mode and should be used along with `onChange`
+	*/
 	selectedIndex: PropTypes.number
 };
 /**
@@ -331,18 +373,66 @@ function TabList({ activation = "automatic", "aria-label": label, children, clas
 	});
 }
 TabList.propTypes = {
+	/**
+	* Specify whether the content tab should be activated automatically or
+	* manually
+	*/
 	activation: PropTypes.oneOf(["automatic", "manual"]),
+	/**
+	* Provide an accessible label to be read when a user interacts with this
+	* component
+	*/
 	"aria-label": PropTypes.string,
+	/**
+	* Provide child elements to be rendered inside `ContentTabs`.
+	* These elements should render a `ContentTab`
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be added to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether component is contained type
+	*/
 	contained: PropTypes.bool,
+	/**
+	* Used for tabs within a grid, this makes it so tabs span the full container width and have the same width. Only available on contained tabs with <9 children
+	*/
 	fullWidth: PropTypes.bool,
+	/**
+	* If using `IconTab`, specify the size of the icon being used.
+	*/
 	iconSize: PropTypes.oneOf(["default", "lg"]),
+	/**
+	* Provide the props that describe the left overflow button
+	*/
 	leftOverflowButtonProps: PropTypes.object,
+	/**
+	* Specify whether to use the light component variant
+	*/
 	light: deprecate(PropTypes.bool, "The `light` prop for `TabList` has been deprecated in favor of the new `Layer` component. It will be removed in the next major release."),
+	/**
+	* Provide the props that describe the right overflow button
+	*/
 	rightOverflowButtonProps: PropTypes.object,
+	/**
+	* Optionally provide a delay (in milliseconds) passed to the lodash
+	* debounce of the onScroll handler. This will impact the responsiveness
+	* of scroll arrow buttons rendering when scrolling to the first or last tab.
+	*/
 	scrollDebounceWait: PropTypes.number,
+	/**
+	* Choose whether to automatically scroll
+	* to newly selected tabs on component rerender
+	*/
 	scrollIntoView: PropTypes.bool,
+	/**
+	* Specify the size of the tabs.
+	*
+	* Supports `sm` and `md` for line tabs.
+	* Supports `sm`, `md`, and `lg` for contained tabs.
+	*/
 	size: PropTypes.oneOf([
 		"sm",
 		"md",
@@ -461,10 +551,28 @@ function TabListVertical({ activation = "automatic", "aria-label": label, childr
 	});
 }
 TabListVertical.propTypes = {
+	/**
+	* Specify whether the content tab should be activated automatically or
+	* manually
+	*/
 	activation: PropTypes.oneOf(["automatic", "manual"]),
+	/**
+	* Provide an accessible label to be read when a user interacts with this
+	* component
+	*/
 	"aria-label": PropTypes.string,
+	/**
+	* Provide child elements to be rendered inside `ContentTabs`.
+	* These elements should render a `ContentTab`
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be added to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify the size of the tabs.
+	*/
 	size: PropTypes.oneOf([
 		"sm",
 		"md",
@@ -684,14 +792,44 @@ const Tab = forwardRef(({ as = "button", children, className: customClassName, d
 	}), DismissIcon] });
 });
 Tab.propTypes = {
+	/**
+	* Provide a custom element to render instead of the default button
+	*/
 	as: PropTypes.oneOfType([PropTypes.string, PropTypes.elementType]),
+	/**
+	* Provide child elements to be rendered inside `Tab`.
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be added to your Tab
+	*/
 	className: PropTypes.string,
+	/**
+	* Whether your Tab is disabled.
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Provide a handler that is invoked when a user clicks on the control
+	*/
 	onClick: PropTypes.func,
+	/**
+	* Provide a handler that is invoked on the key down event for the control
+	*/
 	onKeyDown: PropTypes.func,
+	/**
+	* An optional parameter to allow overriding the anchor rendering.
+	* Useful for using Tab along with react-router or other client
+	* side router libraries.
+	*/
 	renderButton: PropTypes.func,
+	/**
+	* A component used to render an icon.
+	*/
 	renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
+	/**
+	* An optional label to render under the primary tab label.
+	* Only useful for contained tabs.
+	*/
 	secondaryLabel: PropTypes.string
 };
 /**
@@ -722,12 +860,37 @@ const IconTab = React.forwardRef(({ badgeIndicator, children, className: customC
 	});
 });
 IconTab.propTypes = {
+	/**
+	* **Experimental**: Display an empty dot badge on the Tab.
+	*/
 	badgeIndicator: PropTypes.bool,
+	/**
+	* Provide an icon to be rendered inside `IconTab` as the visual label for Tab.
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be added to your Tab
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the tooltip for the icon should be open when it first renders
+	*/
 	defaultOpen: PropTypes.bool,
+	/**
+	* Specify the duration in milliseconds to delay before displaying the tooltip for the icon.
+	*/
 	enterDelayMs: PropTypes.number,
+	/**
+	* Provide the label to be rendered inside 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 it will not be
+	* announced to the screen reader. If using the badgeIndicator then provide a
+	* label with describing that there is a new notification.
+	*/
 	label: PropTypes.node.isRequired,
+	/**
+	* Specify the duration in milliseconds to delay before hiding the tooltip
+	*/
 	leaveDelayMs: PropTypes.number
 };
 const TabPanel = React.forwardRef(({ children, className: customClassName, ...rest }, forwardRef) => {
@@ -749,7 +912,13 @@ const TabPanel = React.forwardRef(({ children, className: customClassName, ...re
 	});
 });
 TabPanel.propTypes = {
+	/**
+	* Provide child elements to be rendered inside `TabPanel`.
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be added to TabPanel.
+	*/
 	className: PropTypes.string
 };
 function TabPanels({ children }) {
@@ -782,6 +951,10 @@ function TabPanels({ children }) {
 		});
 	}) });
 }
-TabPanels.propTypes = { children: PropTypes.node };
+TabPanels.propTypes = { 
+/**
+* Provide child elements to be rendered inside `TabPanels`.
+*/
+children: PropTypes.node };
 //#endregion
 export { IconTab, Tab, TabList, TabListVertical, TabPanel, TabPanels, Tabs, TabsVertical };