@carbon/react 1.110.0 → 1.111.0-rc.0

package/es/components/TextInput/PasswordInput.js

@@ -12,8 +12,8 @@ import { hasHelperText } from "../../internal/hasHelperText.js";
 import { useNormalizedInputProps } from "../../internal/useNormalizedInputProps.js";
 import { FormContext } from "../FluidForm/FormContext.js";
 import { getTextInputProps } from "./util.js";
-import { forwardRef, useContext, useEffect, useState } from "react";
 import classNames from "classnames";
+import { forwardRef, useContext, useEffect, useState } from "react";
 import PropTypes from "prop-types";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { View, ViewOff } from "@carbon/icons-react";
@@ -173,44 +173,127 @@ const PasswordInput = forwardRef(({ className, disabled = false, helperText, hid
 });
 PasswordInput.displayName = "PasswordInput";
 PasswordInput.propTypes = {
+	/**
+	* Provide a custom className that is applied directly to the underlying
+	* `<input>` node
+	*/
 	className: PropTypes.string,
+	/**
+	* Optionally provide the default value of the `<input>`
+	*/
 	defaultValue: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+	/**
+	* Specify whether the control is disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Provide text that is used alongside the control label for additional help
+	*/
 	helperText: PropTypes.node,
+	/**
+	* Specify whether or not the underlying label is visually hidden
+	*/
 	hideLabel: PropTypes.bool,
+	/**
+	* "Hide password" tooltip text on password visibility toggle
+	*/
 	hidePasswordLabel: PropTypes.string,
+	/**
+	* Provide a unique identifier for the input field
+	*/
 	id: PropTypes.string.isRequired,
+	/**
+	* `true` to use the inline version.
+	*/
 	inline: PropTypes.bool,
+	/**
+	* Specify whether the control is currently invalid
+	*/
 	invalid: PropTypes.bool,
+	/**
+	* Whether the PasswordInput should be read-only
+	*/
 	readOnly: 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.isRequired,
+	/**
+	* `true` to use the light version. For use on $ui-01 backgrounds only.
+	* Don't use this to make tile background color same as container background color.
+	*/
 	light: deprecate(PropTypes.bool, "The `light` prop for `PasswordInput` has been deprecated in favor of the new `Layer` component. It will be removed in the next major release."),
+	/**
+	* 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,
+	/**
+	* Callback function that is called whenever the toggle password visibility
+	* button is clicked
+	*/
 	onTogglePasswordVisibility: PropTypes.func,
+	/**
+	* Specify the placeholder attribute for the `<input>`
+	*/
 	placeholder: PropTypes.string,
+	/**
+	* "Show password" tooltip text on password visibility toggle
+	*/
 	showPasswordLabel: PropTypes.string,
+	/**
+	* Specify the size of the Text Input. Supports `xs`, `sm`, `md`, or `lg`.
+	*/
 	size: PropTypes.oneOf([
 		"xs",
 		"sm",
 		"md",
 		"lg"
 	]),
+	/**
+	* 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"
 	]),
+	/**
+	* Specify the direction of the tooltip for icon-only buttons.
+	* Can be either top, right, bottom, or left.
+	*/
 	tooltipPosition: PropTypes.oneOf([
 		"top",
 		"right",
 		"bottom",
 		"left"
 	]),
+	/**
+	* The input type, either password or text
+	*/
 	type: PropTypes.oneOf(["password", "text"]),
+	/**
+	* Provide the current value of the `<input>`
+	*/
 	value: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+	/**
+	* Specify whether the control is currently in warning state
+	*/
 	warn: PropTypes.bool,
+	/**
+	* Provide the text that is displayed when the control is in warning state
+	*/
 	warnText: PropTypes.node
 };
 //#endregion

package/es/components/TextInput/TextInput.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/TextInput/TextInput.Skeleton.tsx
@@ -26,8 +26,17 @@ const TextInputSkeleton = ({ hideLabel, className, size, ...rest }) => {
 	});
 };
 TextInputSkeleton.propTypes = {
+	/**
+	* Specify an optional className to add to the form item wrapper.
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the label should be hidden, or not
+	*/
 	hideLabel: PropTypes.bool,
+	/**
+	* Specify the size of the TextInputSkeleton
+	*/
 	size: PropTypes.oneOf([
 		"xs",
 		"sm",

package/es/components/TextInput/TextInput.js

@@ -16,8 +16,8 @@ import { AILabel } from "../AILabel/index.js";
 import { FormContext } from "../FluidForm/FormContext.js";
 import { getTextInputProps } from "./util.js";
 import { getAnnouncement } from "../../internal/getAnnouncement.js";
-import { cloneElement, forwardRef, useContext, useEffect, useRef, useState } from "react";
 import classNames from "classnames";
+import { cloneElement, forwardRef, useContext, useEffect, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/components/TextInput/TextInput.tsx
@@ -203,34 +203,110 @@ const TextInput = forwardRef(({ className, decorator, disabled = false, helperTe
 });
 TextInput.displayName = "TextInput";
 TextInput.propTypes = {
+	/**
+	* Specify an optional className to be applied to the `<input>` node
+	*/
 	className: PropTypes.string,
+	/**
+	* **Experimental**: Provide a `decorator` component to be rendered inside the `TextInput` component
+	*/
 	decorator: PropTypes.node,
+	/**
+	* Optionally provide the default value of the `<input>`
+	*/
 	defaultValue: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+	/**
+	* Specify whether the `<input>` should be disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Specify whether to display the character counter
+	*/
 	enableCounter: PropTypes.bool,
+	/**
+	* Provide text that is used alongside the control label for additional help
+	*/
 	helperText: PropTypes.node,
+	/**
+	* 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,
+	/**
+	* `true` to use the inline version.
+	*/
 	inline: PropTypes.bool,
+	/**
+	* 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.isRequired,
+	/**
+	* `true` to use the light version. For use on $ui-01 backgrounds only.
+	* Don't use this to make tile background color same as container background color.
+	*/
 	light: deprecate(PropTypes.bool, "The `light` prop for `TextInput` has been deprecated in favor of the new `Layer` component. It will be removed in the next major release."),
+	/**
+	* Max character count allowed for the input. This is needed in order for enableCounter to display
+	*/
 	maxCount: PropTypes.number,
+	/**
+	* 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 placeholder attribute for the `<input>`
+	*/
 	placeholder: PropTypes.string,
+	/**
+	* Whether the input should be read-only
+	*/
 	readOnly: PropTypes.bool,
+	/**
+	* Specify the size of the Text Input. Currently supports the following:
+	*/
 	size: PropTypes.oneOf([
 		"xs",
 		"sm",
 		"md",
 		"lg"
 	]),
+	/**
+	* **Experimental**: Provide a `Slug` component to be rendered inside the `TextInput` component
+	*/
 	slug: deprecate(PropTypes.node, "The `slug` prop for `TextInput` has been deprecated in favor of the new `decorator` prop. It will be removed in the next major release."),
+	/**
+	* Specify the type of the `<input>`
+	*/
 	type: PropTypes.string,
+	/**
+	* Specify the value of the `<input>`
+	*/
 	value: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+	/**
+	* Specify whether the control is currently in warning state
+	*/
 	warn: PropTypes.bool,
+	/**
+	* Provide the text that is displayed when the control is in warning state
+	*/
 	warnText: PropTypes.node
 };
 //#endregion

package/es/components/Theme/index.js

@@ -8,8 +8,8 @@
 import { usePrefix } from "../../internal/usePrefix.js";
 import { LayerContext } from "../Layer/LayerContext.js";
 import { useMatchMedia } from "../../internal/useMatchMedia.js";
-import React, { cloneElement, isValidElement, useMemo } from "react";
 import classNames from "classnames";
+import React, { cloneElement, isValidElement, useMemo } from "react";
 import PropTypes from "prop-types";
 import { jsx } from "react/jsx-runtime";
 //#region src/components/Theme/index.tsx
@@ -31,7 +31,14 @@ const GlobalTheme = React.forwardRef(({ children, theme }, ref) => {
 	});
 });
 GlobalTheme.propTypes = {
+	/**
+	* Provide child elements to be rendered inside of `GlobalTheme`, this is
+	* typically the root of your app
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify the global theme for your app
+	*/
 	theme: PropTypes.oneOf([
 		"white",
 		"g10",
@@ -70,13 +77,27 @@ function Theme({ as: BaseComponent = "div", className: customClassName, theme, .
 	});
 }
 Theme.propTypes = {
+	/**
+	* Specify a custom component or element to be rendered as the top-level
+	* element in the component
+	*/
 	as: PropTypes.oneOfType([
 		PropTypes.func,
 		PropTypes.string,
 		PropTypes.elementType
 	]),
+	/**
+	* Provide child elements to be rendered inside of `Theme`
+	*/
 	children: PropTypes.node,
+	/**
+	* Provide a custom class name to be used on the outermost element rendered by
+	* the component
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify the theme
+	*/
 	theme: PropTypes.oneOf([
 		"white",
 		"g10",

package/es/components/Tile/Tile.js

@@ -19,8 +19,8 @@ import { useFeatureFlag } from "../FeatureFlags/index.js";
 import { getInteractiveContent, getRoleContent } from "../../internal/useNoInteractiveChildren.js";
 import { AILabel } from "../AILabel/index.js";
 import { composeEventHandlers } from "../../tools/events.js";
-import React, { Children, cloneElement, forwardRef, useCallback, useEffect, useRef, useState } from "react";
 import classNames from "classnames";
+import React, { Children, cloneElement, forwardRef, useCallback, useEffect, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { AiLabel, ArrowRight, Checkbox, CheckboxCheckedFilled, ChevronDown, Error } from "@carbon/icons-react";
@@ -55,11 +55,33 @@ const Tile = React.forwardRef(({ children, className, decorator, light = false,
 });
 Tile.displayName = "Tile";
 Tile.propTypes = {
+	/**
+	* The child nodes.
+	*/
 	children: PropTypes.node,
+	/**
+	* The CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* **Experimental**: Provide a `decorator` component to be rendered inside the `Tile` component
+	*/
 	decorator: PropTypes.node,
+	/**
+	* **Experimental**: Specify if the `Tile` component should be rendered with rounded corners. Only valid
+	* when an AILabel is present
+	*/
 	hasRoundedCorners: PropTypes.bool,
+	/**
+	* `true` to use the light version. For use on $ui-01 backgrounds only.
+	* Don't use this to make tile background color same as container background color.
+	*
+	* @deprecated
+	*/
 	light: deprecate(PropTypes.bool, "The `light` prop for `Tile` is no longer needed and has been deprecated. It will be removed in the next major release. Use the Layer component instead."),
+	/**
+	* **Experimental**: Provide a `Slug` component to be rendered inside the `Tile` component
+	*/
 	slug: deprecate(PropTypes.node, "The `slug` prop for `Tile` has been deprecated in favor of the new `decorator` prop. It will be removed in the next major release.")
 };
 const ClickableTile = React.forwardRef(({ children, className, clicked = false, decorator, disabled, href, light, onClick = () => {}, onKeyDown = () => {}, renderIcon: Icon, hasRoundedCorners, slug, ...rest }, ref) => {
@@ -124,17 +146,55 @@ const ClickableTile = React.forwardRef(({ children, className, clicked = false,
 });
 ClickableTile.displayName = "ClickableTile";
 ClickableTile.propTypes = {
+	/**
+	* The child nodes.
+	*/
 	children: PropTypes.node,
+	/**
+	* The CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* Boolean for whether a tile has been clicked.
+	*/
 	clicked: PropTypes.bool,
+	/**
+	* **Experimental**: Provide a `decorator` component or set the boolean to True for an AILabel icon to be rendered inside the `ClickableTile` component
+	*/
 	decorator: PropTypes.oneOfType([PropTypes.bool, PropTypes.node]),
+	/**
+	* Specify whether the ClickableTile should be disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* **Experimental**: Specify if the `ClickableTile` component should be rendered with rounded corners.
+	* Only valid when `slug` prop is present
+	*/
 	hasRoundedCorners: PropTypes.bool,
+	/**
+	* The href for the link.
+	*/
 	href: PropTypes.string,
+	/**
+	* `true` to use the light version. For use on $ui-01 backgrounds only.
+	* Don't use this to make tile background color same as container background color.
+	*/
 	light: deprecate(PropTypes.bool, "The `light` prop for `ClickableTile` is no longer needed and has been deprecated. It will be removed in the next major release. Use the Layer component instead."),
+	/**
+	* Specify the function to run when the ClickableTile is clicked
+	*/
 	onClick: PropTypes.func,
+	/**
+	* Specify the function to run when the ClickableTile is interacted with via a keyboard
+	*/
 	onKeyDown: PropTypes.func,
+	/**
+	* The rel property for the link.
+	*/
 	rel: PropTypes.string,
+	/**
+	* A component used to render an icon.
+	*/
 	renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object])
 };
 const SelectableTile = React.forwardRef(({ children, className, decorator, disabled, id, light, onClick = () => {}, onChange = () => {}, onKeyDown = () => {}, selected = false, tabIndex = 0, title = "title", slug, hasRoundedCorners, ...rest }, ref) => {
@@ -211,19 +271,65 @@ const SelectableTile = React.forwardRef(({ children, className, decorator, disab
 SelectableTile.propTypes = {
 	children: PropTypes.node,
 	className: PropTypes.string,
+	/**
+	* **Experimental**: Provide a `decorator` component to be rendered inside the `SelectableTile` component
+	*/
 	decorator: PropTypes.node,
+	/**
+	* Specify whether the SelectableTile should be disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* **Experimental**: Specify if the `SelectableTile` component should be rendered with rounded corners.
+	* Only valid when `slug` prop is present
+	*/
 	hasRoundedCorners: PropTypes.bool,
+	/**
+	* The ID of the `<input>`.
+	*/
 	id: PropTypes.string,
+	/**
+	* `true` to use the light version. For use on $ui-01 backgrounds only.
+	* Don't use this to make tile background color same as container background color.
+	*/
 	light: deprecate(PropTypes.bool, "The `light` prop for `SelectableTile` is no longer needed and has been deprecated. It will be removed in the next major release. Use the Layer component instead."),
+	/**
+	* The `name` of the `<input>`.
+	* @deprecated
+	*/
 	name: deprecate(PropTypes.string, "The `name` property is no longer used.  It will be removed in the next major release."),
+	/**
+	* The empty handler of the `<input>`.
+	*/
 	onChange: PropTypes.func,
+	/**
+	* Specify the function to run when the SelectableTile is clicked
+	*/
 	onClick: PropTypes.func,
+	/**
+	* Specify the function to run when the SelectableTile is interacted with via a keyboard
+	*/
 	onKeyDown: PropTypes.func,
+	/**
+	* `true` to select this tile.
+	*/
 	selected: PropTypes.bool,
+	/**
+	* **Experimental**: Provide a `Slug` component to be rendered inside the `SelectableTile` component
+	*/
 	slug: deprecate(PropTypes.node, "The `slug` prop for `SelectableTile` has been deprecated in favor of the new `decorator` prop. It will be removed in the next major release."),
+	/**
+	* Specify the tab index of the wrapper element
+	*/
 	tabIndex: PropTypes.number,
+	/**
+	* The `title` of the `<input>`.
+	*/
 	title: PropTypes.string,
+	/**
+	* The value of the `<input>`.
+	* @deprecated
+	*/
 	value: deprecate(PropTypes.oneOfType([PropTypes.string, PropTypes.number]), "The `value` property is no longer used.  It will be removed in the next major release.`")
 };
 const ExpandableTile = forwardRef(({ tabIndex = 0, className, children, decorator, expanded = false, tileMaxHeight = 0, tilePadding = 0, onClick, onKeyUp, tileCollapsedIconText = "Interact to expand Tile", tileExpandedIconText = "Interact to collapse Tile", tileCollapsedLabel, tileExpandedLabel, light, slug, hasRoundedCorners, ...rest }, forwardRef) => {
@@ -374,18 +480,59 @@ const ExpandableTile = forwardRef(({ tabIndex = 0, className, children, decorato
 ExpandableTile.propTypes = {
 	children: PropTypes.node,
 	className: PropTypes.string,
+	/**
+	* **Experimental**: Provide a `decorator` component to be rendered inside the `ExpandableTile` component
+	*/
 	decorator: PropTypes.node,
+	/**
+	* `true` if the tile is expanded.
+	*/
 	expanded: PropTypes.bool,
+	/**
+	* Specify if the `ExpandableTile` component should be rendered with rounded corners.
+	* Only valid when `slug` prop is present
+	*/
 	hasRoundedCorners: PropTypes.bool,
+	/**
+	* An ID that can be provided to aria-labelledby
+	*/
 	id: PropTypes.string,
+	/**
+	* `true` to use the light version. For use on $ui-01 backgrounds only.
+	* Don't use this to make tile background color same as container background color.
+	*/
 	light: deprecate(PropTypes.bool, "The `light` prop for `ExpandableTile` is no longer needed and has been deprecated. It will be removed in the next major release. Use the Layer component instead."),
+	/**
+	* Specify the function to run when the ExpandableTile is clicked
+	*/
 	onClick: PropTypes.func,
+	/**
+	* optional handler to trigger a function when a key is pressed
+	*/
 	onKeyUp: PropTypes.func,
+	/**
+	* **Experimental**: Provide a `Slug` component to be rendered inside the `ExpandableTile` component
+	*/
 	slug: deprecate(PropTypes.node, "The `slug` prop for `ExpandableTile` has been deprecated in favor of the new `decorator` prop. It will be removed in the next major release."),
+	/**
+	* The `tabindex` attribute.
+	*/
 	tabIndex: PropTypes.number,
+	/**
+	* The description of the "collapsed" icon that can be read by screen readers.
+	*/
 	tileCollapsedIconText: PropTypes.string,
+	/**
+	* When "collapsed", a label to appear next to the chevron (e.g., "View more").
+	*/
 	tileCollapsedLabel: PropTypes.string,
+	/**
+	* The description of the "expanded" icon that can be read by screen readers.
+	*/
 	tileExpandedIconText: PropTypes.string,
+	/**
+	* When "expanded", a label to appear next to the chevron (e.g., "View less").
+	*/
 	tileExpandedLabel: PropTypes.string
 };
 ExpandableTile.displayName = "ExpandableTile";
@@ -396,7 +543,11 @@ const TileAboveTheFoldContent = React.forwardRef(({ children }, ref) => {
 		children
 	});
 });
-TileAboveTheFoldContent.propTypes = { children: PropTypes.node };
+TileAboveTheFoldContent.propTypes = { 
+/**
+* The child nodes.
+*/
+children: PropTypes.node };
 TileAboveTheFoldContent.displayName = "TileAboveTheFoldContent";
 const TileBelowTheFoldContent = React.forwardRef(({ children }, ref) => {
 	return /* @__PURE__ */ jsx("div", {
@@ -405,7 +556,11 @@ const TileBelowTheFoldContent = React.forwardRef(({ children }, ref) => {
 		children
 	});
 });
-TileBelowTheFoldContent.propTypes = { children: PropTypes.node };
+TileBelowTheFoldContent.propTypes = { 
+/**
+* The child nodes.
+*/
+children: PropTypes.node };
 TileBelowTheFoldContent.displayName = "TileBelowTheFoldContent";
 //#endregion
 export { ClickableTile, ExpandableTile, SelectableTile, Tile, TileAboveTheFoldContent, TileBelowTheFoldContent };

package/es/components/TileGroup/TileGroup.js

@@ -5,8 +5,8 @@
  * 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 { isComponentElement } from "../../internal/utils.js";
 import RadioTile_default from "../RadioTile/index.js";
 import { Children, cloneElement, createElement, isValidElement, useEffect, useState } from "react";
@@ -65,14 +65,42 @@ const TileGroup = ({ children, className, defaultSelected, disabled, legend, nam
 };
 TileGroup.displayName = "TileGroup";
 TileGroup.propTypes = {
+	/**
+	* Provide a collection of <RadioTile> components to render in the group
+	*/
 	children: PropTypes.node,
+	/**
+	* Provide an optional className to be applied to the container node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify the the value of <RadioTile> to be selected by default
+	*/
 	defaultSelected: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+	/**
+	* Specify whether the group is disabled
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Provide an optional legend for this group
+	*/
 	legend: PropTypes.string,
+	/**
+	* Specify the name of the underlying `<input>` nodes
+	*/
 	name: PropTypes.string.isRequired,
+	/**
+	* Provide an optional `onChange` hook that is called whenever the value of
+	* the group changes
+	*/
 	onChange: PropTypes.func,
+	/**
+	* `true` to specify if input selection in group is required.
+	*/
 	required: PropTypes.bool,
+	/**
+	* Specify the value that is currently selected in the group
+	*/
 	valueSelected: PropTypes.oneOfType([PropTypes.string, PropTypes.number])
 };
 //#endregion