@carbon/react 1.110.0 → 1.111.0-rc.0

package/es/components/Menu/MenuItem.js

@@ -16,8 +16,8 @@ import { MenuContext } from "./MenuContext.js";
 import { useLayoutDirection } from "../LayoutDirection/useLayoutDirection.js";
 import { Menu as Menu$1 } from "./Menu.js";
 import { useControllableState } from "../../internal/useControllableState.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 { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { CaretLeft, CaretRight, Checkmark } from "@carbon/icons-react";
@@ -198,14 +198,41 @@ const MenuItem = forwardRef(function MenuItem({ children, className, dangerDescr
 	});
 });
 MenuItem.propTypes = {
+	/**
+	* Optionally provide another Menu to create a submenu. props.children can't be used to specify the content of the MenuItem itself. Use props.label instead.
+	*/
 	children: PropTypes.node,
+	/**
+	* Additional CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify the message read by screen readers for the danger menu item variant
+	*/
 	dangerDescription: PropTypes.string,
+	/**
+	* Specify whether the MenuItem is disabled or not.
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Specify the kind of the MenuItem.
+	*/
 	kind: PropTypes.oneOf(["default", "danger"]),
+	/**
+	* A required label titling the MenuItem. Will be rendered as its text content.
+	*/
 	label: PropTypes.string.isRequired,
+	/**
+	* Provide an optional function to be called when the MenuItem is clicked.
+	*/
 	onClick: PropTypes.func,
+	/**
+	* A component used to render an icon.
+	*/
 	renderIcon: PropTypes.oneOfType([PropTypes.func, PropTypes.object]),
+	/**
+	* Provide a shortcut for the action of this MenuItem. Note that the component will only render it as a hint but not actually register the shortcut.
+	*/
 	shortcut: PropTypes.string
 };
 const MenuItemSelectable = forwardRef(function MenuItemSelectable({ className, defaultSelected, label, onChange, selected, ...rest }, forwardRef) {
@@ -234,10 +261,25 @@ const MenuItemSelectable = forwardRef(function MenuItemSelectable({ className, d
 	});
 });
 MenuItemSelectable.propTypes = {
+	/**
+	* Additional CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the option should be selected by default.
+	*/
 	defaultSelected: PropTypes.bool,
+	/**
+	* A required label titling this option.
+	*/
 	label: PropTypes.string.isRequired,
+	/**
+	* Provide an optional function to be called when the selection state changes.
+	*/
 	onChange: PropTypes.func,
+	/**
+	* Pass a bool to props.selected to control the state of this option.
+	*/
 	selected: PropTypes.bool
 };
 const MenuItemGroup = forwardRef(function MenuItemGroup({ children, className, label, ...rest }, forwardRef) {
@@ -254,8 +296,17 @@ const MenuItemGroup = forwardRef(function MenuItemGroup({ children, className, l
 	});
 });
 MenuItemGroup.propTypes = {
+	/**
+	* A collection of MenuItems to be rendered within this group.
+	*/
 	children: PropTypes.node,
+	/**
+	* Additional CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* A required label titling this group.
+	*/
 	label: PropTypes.string.isRequired
 };
 const MenuItemRadioGroup = forwardRef(function MenuItemRadioGroup({ className, defaultSelectedItem, items, itemToString = defaultItemToString, label, onChange, selectedItem, ...rest }, forwardRef) {
@@ -292,12 +343,33 @@ const MenuItemRadioGroup = forwardRef(function MenuItemRadioGroup({ className, d
 	});
 });
 MenuItemRadioGroup.propTypes = {
+	/**
+	* Additional CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify the default selected item. Must match the type of props.items.
+	*/
 	defaultSelectedItem: PropTypes.any,
+	/**
+	* Converts an item into a string for display.
+	*/
 	itemToString: PropTypes.func,
+	/**
+	* Provide the options for this radio group. Can be of any type, as long as you provide an appropriate props.itemToString function.
+	*/
 	items: PropTypes.array,
+	/**
+	* A required label titling this radio group.
+	*/
 	label: PropTypes.string.isRequired,
+	/**
+	* Provide an optional function to be called when the selection changes.
+	*/
 	onChange: PropTypes.func,
+	/**
+	* Provide props.selectedItem to control the state of this radio group. Must match the type of props.items.
+	*/
 	selectedItem: PropTypes.any
 };
 const MenuItemDivider = forwardRef(function MenuItemDivider({ className, ...rest }, forwardRef) {
@@ -309,6 +381,10 @@ const MenuItemDivider = forwardRef(function MenuItemDivider({ className, ...rest
 		ref: forwardRef
 	});
 });
-MenuItemDivider.propTypes = { className: PropTypes.string };
+MenuItemDivider.propTypes = { 
+/**
+* Additional CSS class names.
+*/
+className: PropTypes.string };
 //#endregion
 export { MenuItem, MenuItemDivider, MenuItemGroup, MenuItemRadioGroup, MenuItemSelectable };

package/es/components/MenuButton/index.js

@@ -13,8 +13,8 @@ import Button_default from "../Button/index.js";
 import { mergeRefs } from "../../tools/mergeRefs.js";
 import { Menu as Menu$1 } from "../Menu/Menu.js";
 import { useAttachedMenu } from "../../internal/useAttachedMenu.js";
-import { forwardRef, useRef } from "react";
 import classNames from "classnames";
+import { forwardRef, useRef } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { ChevronDown } from "@carbon/icons-react";
@@ -115,11 +115,29 @@ const MenuButton = forwardRef(({ children, className, disabled, kind = defaultBu
 	});
 });
 MenuButton.propTypes = {
+	/**
+	* A collection of MenuItems to be rendered as actions for this MenuButton.
+	*/
 	children: PropTypes.node.isRequired,
+	/**
+	* Additional CSS class names.
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify whether the MenuButton should be disabled, or not.
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Specify the type of button to be used as the base for the trigger button.
+	*/
 	kind: PropTypes.oneOf(validButtonKinds),
+	/**
+	* Provide the label to be rendered on the trigger button.
+	*/
 	label: PropTypes.string.isRequired,
+	/**
+	* Experimental property. Specify how the menu should align with the button element
+	*/
 	menuAlignment: PropTypes.oneOf([
 		"top",
 		"top-start",
@@ -128,15 +146,30 @@ MenuButton.propTypes = {
 		"bottom-start",
 		"bottom-end"
 	]),
+	/**
+	* Specify the size of the button and menu.
+	*/
 	size: PropTypes.oneOf([
 		"xs",
 		"sm",
 		"md",
 		"lg"
 	]),
+	/**
+	* Specify the tabIndex of the button.
+	*/
 	tabIndex: PropTypes.number,
+	/**
+	* Specify the background token to use for the menu. Default is 'layer'.
+	*/
 	menuBackgroundToken: PropTypes.oneOf(["layer", "background"]),
+	/**
+	* Specify whether a border should be rendered on the menu
+	*/
 	menuBorder: PropTypes.bool,
+	/**
+	* Specify a DOM node where the Menu should be rendered in. Defaults to document.body.
+	*/
 	menuTarget: PropTypes.instanceOf(typeof Element !== "undefined" ? Element : Object)
 };
 //#endregion

package/es/components/Modal/Modal.js

@@ -5,14 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { noopFn } from "../../internal/noopFn.js";
-import { warning } from "../../internal/warning.js";
 import { usePrefix } from "../../internal/usePrefix.js";
 import { Text } from "../Text/Text.js";
 import { Enter, Escape, Tab } from "../../internal/keyboard/keys.js";
 import { match } from "../../internal/keyboard/match.js";
 import { selectorTabbable } from "../../internal/keyboard/navigation.js";
 import { useId } from "../../internal/useId.js";
+import { noopFn } from "../../internal/noopFn.js";
+import { warning } from "../../internal/warning.js";
 import { deprecate } from "../../prop-types/deprecate.js";
 import { isComponentElement } from "../../internal/utils.js";
 import { useMergedRefs } from "../../internal/useMergedRefs.js";
@@ -32,8 +32,8 @@ import { isTopmostVisibleModal } from "./isTopmostVisibleModal.js";
 import { requiredIfGivenPropIsTruthy } from "../../prop-types/requiredIfGivenPropIsTruthy.js";
 import { usePreviousValue } from "../../internal/usePreviousValue.js";
 import { ModalPresence, ModalPresenceContext, useExclusiveModalPresenceContext } from "./ModalPresence.js";
-import React, { cloneElement, useCallback, useContext, useEffect, useRef, useState } from "react";
 import classNames from "classnames";
+import React, { cloneElement, useCallback, useContext, useEffect, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { Close } from "@carbon/icons-react";
@@ -483,43 +483,143 @@ const ModalDialog = React.forwardRef(function ModalDialog({ "aria-label": ariaLa
 	});
 });
 Modal.propTypes = {
+	/**
+	* Specify whether the Modal is displaying an alert, error or warning
+	* Should go hand in hand with the danger prop.
+	*/
 	alert: PropTypes.bool,
+	/**
+	* Required props for the accessibility label of the header
+	*/
 	["aria-label"]: requiredIfGivenPropIsTruthy("hasScrollingContent", PropTypes.string),
+	/**
+	* Provide the contents of your Modal
+	*/
 	children: PropTypes.node,
+	/**
+	* Specify an optional className to be applied to the modal root node
+	*/
 	className: PropTypes.string,
+	/**
+	* Specify label for the close button of the modal; defaults to close
+	*/
 	closeButtonLabel: PropTypes.string,
+	/**
+	* Specify whether the Modal is for dangerous actions
+	*/
 	danger: PropTypes.bool,
+	/**
+	* Specify the message read by screen readers for the danger primary button.
+	* Defaults to an empty string; provide localized text to opt in.
+	*/
 	dangerDescription: PropTypes.string,
+	/**
+	* **Experimental**: Provide a decorator component to be rendered inside the `Modal` component
+	*/
 	decorator: PropTypes.node,
+	/**
+	* Specify whether the modal contains scrolling content
+	*/
 	hasScrollingContent: PropTypes.bool,
+	/**
+	* Specify the DOM element ID of the top-level node.
+	*/
 	id: PropTypes.string,
+	/**
+	* Specify whether or not the Modal content should have any inner padding.
+	*/
 	isFullWidth: PropTypes.bool,
+	/**
+	* Provide a ref to return focus to once the modal is closed.
+	*/
 	launcherButtonRef: PropTypes.oneOfType([PropTypes.func, PropTypes.shape({ current: PropTypes.oneOfType([typeof HTMLElement !== "undefined" ? PropTypes.instanceOf(HTMLElement) : PropTypes.any, PropTypes.oneOf([null])]).isRequired })]),
+	/**
+	* Specify the description for the loading text
+	*/
 	loadingDescription: PropTypes.string,
+	/**
+	* Specify the description for the loading text
+	*/
 	loadingIconDescription: PropTypes.string,
+	/**
+	* loading status
+	*/
 	loadingStatus: PropTypes.oneOf([
 		"inactive",
 		"active",
 		"finished",
 		"error"
 	]),
+	/**
+	* Specify a label to be read by screen readers on the modal root node
+	*/
 	modalAriaLabel: PropTypes.string,
+	/**
+	* Specify the content of the modal header title.
+	*/
 	modalHeading: PropTypes.node,
+	/**
+	* Specify the content of the modal header label.
+	*/
 	modalLabel: PropTypes.node,
+	/**
+	* Specify a handler for keypresses.
+	*/
 	onKeyDown: PropTypes.func,
+	/**
+	* Provide an optional handler to be invoked when loading is
+	* successful
+	*/
 	onLoadingSuccess: PropTypes.func,
+	/**
+	* Specify a handler for closing modal.
+	* The handler should care of closing modal, e.g. changing `open` prop.
+	*/
 	onRequestClose: PropTypes.func,
+	/**
+	* Specify a handler for "submitting" modal.
+	* The handler should care of closing modal, e.g. changing `open` prop, if necessary.
+	*/
 	onRequestSubmit: PropTypes.func,
+	/**
+	* Specify a handler for the secondary button.
+	* Useful if separate handler from `onRequestClose` is desirable
+	*/
 	onSecondarySubmit: PropTypes.func,
+	/**
+	* Specify whether the Modal is currently open
+	*/
 	open: PropTypes.bool,
+	/**
+	* Specify whether the modal should be button-less
+	*/
 	passiveModal: PropTypes.bool,
+	/**
+	* Prevent closing on click outside of modal
+	*/
 	preventCloseOnClickOutside: (props, propName) => {
-		if (!props.passiveModal && props[propName] === false) return new Error(invalidOutsideClickMessage);
+		if (!props.passiveModal && props[propName] === false) return /* @__PURE__ */ new Error(invalidOutsideClickMessage);
 		return null;
 	},
+	/**
+	* Specify whether the Button should be disabled, or not
+	*/
 	primaryButtonDisabled: PropTypes.bool,
+	/**
+	* Specify the text for the primary button
+	*/
 	primaryButtonText: PropTypes.node,
+	/**
+	* Specify the text for the secondary button
+	*/
 	secondaryButtonText: PropTypes.node,
+	/**
+	* Specify an array of config objects for secondary buttons
+	* (`Array<{
+	*   buttonText: string,
+	*   onClick: function,
+	* }>`).
+	*/
 	secondaryButtons: (props, propName, componentName) => {
 		if (props.secondaryButtons) {
 			if (!Array.isArray(props.secondaryButtons) || props.secondaryButtons.length !== 2) return /* @__PURE__ */ new Error(`${propName} needs to be an array of two button config objects`);
@@ -533,9 +633,23 @@ Modal.propTypes = {
 		}
 		return null;
 	},
+	/**
+	* Specify a CSS selector that matches the DOM element that should
+	* be focused when the Modal opens
+	*/
 	selectorPrimaryFocus: PropTypes.string,
+	/**
+	* Specify CSS selectors that match DOM elements working as floating menus.
+	* Focusing on those elements won't trigger "focus-wrap" behavior
+	*/
 	selectorsFloatingMenus: PropTypes.arrayOf(PropTypes.string.isRequired),
+	/**
+	* Specify if Enter key should be used as "submit" action
+	*/
 	shouldSubmitOnEnter: PropTypes.bool,
+	/**
+	* Specify the size variant.
+	*/
 	size: PropTypes.oneOf(ModalSizes),
 	slug: deprecate(PropTypes.node, "The `slug` prop has been deprecated and will be removed in the next major version. Use the decorator prop instead.")
 };

package/es/components/ModalWrapper/ModalWrapper.js

@@ -5,10 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import { noopFn } from "../../internal/noopFn.js";
-import { warning } from "../../internal/warning.js";
 import { Escape } from "../../internal/keyboard/keys.js";
 import { match } from "../../internal/keyboard/match.js";
+import { noopFn } from "../../internal/noopFn.js";
+import { warning } from "../../internal/warning.js";
 import { ButtonKinds } from "../Button/Button.js";
 import Button_default from "../Button/index.js";
 import Modal_default from "../Modal/index.js";

package/es/components/MultiSelect/FilterableMultiSelect.js

@@ -28,8 +28,8 @@ import { sortingPropTypes } from "./MultiSelectPropTypes.js";
 import { isSelectAllItem } from "./tools/isSelectAllItem.js";
 import { defaultCompareItems, defaultSortItems } from "./tools/sorting.js";
 import { useSelection } from "../../internal/Selection.js";
-import { cloneElement, forwardRef, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import classNames from "classnames";
+import { cloneElement, forwardRef, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import PropTypes from "prop-types";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { WarningAltFilled, WarningFilled } from "@carbon/icons-react";
@@ -571,45 +571,173 @@ const FilterableMultiSelect = forwardRef(function FilterableMultiSelect({ autoAl
 });
 FilterableMultiSelect.displayName = "FilterableMultiSelect";
 FilterableMultiSelect.propTypes = {
+	/**
+	* Deprecated, aria-label is no longer needed
+	* Specify a label to be read by screen readers on the container node
+	*/
 	["aria-label"]: deprecate(PropTypes.string, "ariaLabel / aria-label props are no longer required for FilterableMultiSelect"),
+	/**
+	* Deprecated, please use `aria-label` instead.
+	* Specify a label to be read by screen readers on the container note.
+	*/
 	ariaLabel: deprecate(PropTypes.string, "ariaLabel / aria-label props are no longer required for FilterableMultiSelect"),
+	/**
+	* **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,
+	/**
+	* Specify the text that should be read for screen readers that describes total items selected
+	*/
 	clearSelectionDescription: PropTypes.string,
+	/**
+	* Specify the text that should be read for screen readers to clear selection.
+	*/
 	clearSelectionText: PropTypes.string,
+	/**
+	* **Experimental**: Provide a decorator component to be rendered inside the `FilterableMultiSelect` component
+	*/
 	decorator: PropTypes.node,
+	/**
+	* Provide a method that filters the dropdown options based on the current input. Overriding this
+	* prop means that you have to handle the filtering logic when the user types in the text input.
+	* Otherwise, a default built-in filtering function will be used.
+	*/
 	filterItems: PropTypes.func,
+	/**
+	* Specify the direction of the multiselect dropdown. Can be either top or bottom.
+	*/
 	direction: PropTypes.oneOf(["top", "bottom"]),
+	/**
+	* Disable the control
+	*/
 	disabled: PropTypes.bool,
+	/**
+	* Additional props passed to Downshift.
+	*
+	* **Use with caution:** anything you define here overrides the components'
+	* internal handling of that prop. Downshift APIs and internals are subject to
+	* change, and in some cases they can not be shimmed by Carbon to shield you
+	* from potentially breaking changes.
+	*/
 	downshiftProps: PropTypes.shape(Downshift.propTypes),
+	/**
+	* Specify whether the title text should be hidden or not
+	*/
 	hideLabel: PropTypes.bool,
+	/**
+	* Specify a custom `id`
+	*/
 	id: PropTypes.string.isRequired,
+	/**
+	* Allow users to pass in arbitrary items from their collection that are
+	* pre-selected
+	*/
 	initialSelectedItems: PropTypes.array,
+	/**
+	* Is the current selection invalid?
+	*/
 	invalid: PropTypes.bool,
+	/**
+	* If invalid, what is the error?
+	*/
 	invalidText: PropTypes.node,
+	/**
+	* Function to render items as custom components instead of strings.
+	* Defaults to null and is overridden by a getter
+	*/
 	itemToElement: PropTypes.func,
+	/**
+	* Helper function passed to downshift that allows the library to render a
+	* given item to a string label. By default, it extracts the `label` field
+	* from a given item to serve as the item label in the list.
+	*/
 	itemToString: PropTypes.func,
+	/**
+	* We try to stay as generic as possible here to allow individuals to pass
+	* in a collection of whatever kind of data structure they prefer
+	*/
 	items: PropTypes.array.isRequired,
+	/**
+	* `true` to use the light version.
+	*/
 	light: deprecate(PropTypes.bool, "The `light` prop for `FilterableMultiSelect` has been deprecated in favor of the new `Layer` component. It will be removed in the next major release."),
+	/**
+	* Specify the locale of the control. Used for the default `compareItems`
+	* used for sorting the list of items in the control.
+	*/
 	locale: PropTypes.string,
+	/**
+	* `onChange` is a utility for this controlled component to communicate to a
+	* consuming component what kind of internal state changes are occurring.
+	*/
 	onChange: PropTypes.func,
+	/**
+	* `onInputValueChange` is a utility for this controlled component to communicate to
+	* the currently typed input.
+	*/
 	onInputValueChange: PropTypes.func,
+	/**
+	* `onMenuChange` is a utility for this controlled component to communicate to a
+	* consuming component that the menu was opened(`true`)/closed(`false`).
+	*/
 	onMenuChange: PropTypes.func,
+	/**
+	* Initialize the component with an open(`true`)/closed(`false`) menu.
+	*/
 	open: PropTypes.bool,
+	/**
+	* Generic `placeholder` that will be used as the textual representation of
+	* what this field is for
+	*/
 	placeholder: PropTypes.string,
+	/**
+	* Specify feedback (mode) of the selection.
+	* `top`: selected item jumps to top
+	* `fixed`: selected item stays at it's position
+	* `top-after-reopen`: selected item jump to top after reopen dropdown
+	*/
 	selectionFeedback: PropTypes.oneOf([
 		"top",
 		"fixed",
 		"top-after-reopen"
 	]),
+	/**
+	* Specify the size of the ListBox. Currently supports either `sm`, `md` or `lg` as an option.
+	*/
 	size: ListBoxSizePropType,
 	slug: deprecate(PropTypes.node, "The `slug` prop has been deprecated and will be removed in the next major version. Use the decorator prop instead."),
 	...sortingPropTypes,
+	/**
+	* Provide text to be used in a `<label>` element that is tied to the
+	* combobox via ARIA attributes.
+	*/
 	titleText: PropTypes.node,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: PropTypes.func,
 	type: ListBoxTypePropType,
+	/**
+	* Specify title to show title on hover
+	*/
 	useTitleInItem: PropTypes.bool,
+	/**
+	* 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,
+	/**
+	* Specify native input attributes to place on the `<input>`, like maxLength.
+	* These are passed to downshift's getInputProps() and will override the
+	* internal input props.
+	* https://github.com/downshift-js/downshift?tab=readme-ov-file#getinputprops
+	*/
 	inputProps: PropTypes.object
 };
 //#endregion