@carbon/react 1.110.0 → 1.111.0-rc.0

package/lib/components/Menu/MenuItem.js

@@ -17,10 +17,10 @@ const require_MenuContext = require("./MenuContext.js");
 const require_useLayoutDirection = require("../LayoutDirection/useLayoutDirection.js");
 const require_Menu = require("./Menu.js");
 const require_useControllableState = require("../../internal/useControllableState.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");
@@ -202,14 +202,41 @@ const MenuItem = (0, react.forwardRef)(function MenuItem({ children, className,
 	});
 });
 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: prop_types.default.node,
+	/**
+	* Additional CSS class names.
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify the message read by screen readers for the danger menu item variant
+	*/
 	dangerDescription: prop_types.default.string,
+	/**
+	* Specify whether the MenuItem is disabled or not.
+	*/
 	disabled: prop_types.default.bool,
+	/**
+	* Specify the kind of the MenuItem.
+	*/
 	kind: prop_types.default.oneOf(["default", "danger"]),
+	/**
+	* A required label titling the MenuItem. Will be rendered as its text content.
+	*/
 	label: prop_types.default.string.isRequired,
+	/**
+	* Provide an optional function to be called when the MenuItem is clicked.
+	*/
 	onClick: prop_types.default.func,
+	/**
+	* A component used to render an icon.
+	*/
 	renderIcon: prop_types.default.oneOfType([prop_types.default.func, prop_types.default.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: prop_types.default.string
 };
 const MenuItemSelectable = (0, react.forwardRef)(function MenuItemSelectable({ className, defaultSelected, label, onChange, selected, ...rest }, forwardRef) {
@@ -238,10 +265,25 @@ const MenuItemSelectable = (0, react.forwardRef)(function MenuItemSelectable({ c
 	});
 });
 MenuItemSelectable.propTypes = {
+	/**
+	* Additional CSS class names.
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify whether the option should be selected by default.
+	*/
 	defaultSelected: prop_types.default.bool,
+	/**
+	* A required label titling this option.
+	*/
 	label: prop_types.default.string.isRequired,
+	/**
+	* Provide an optional function to be called when the selection state changes.
+	*/
 	onChange: prop_types.default.func,
+	/**
+	* Pass a bool to props.selected to control the state of this option.
+	*/
 	selected: prop_types.default.bool
 };
 const MenuItemGroup = (0, react.forwardRef)(function MenuItemGroup({ children, className, label, ...rest }, forwardRef) {
@@ -258,8 +300,17 @@ const MenuItemGroup = (0, react.forwardRef)(function MenuItemGroup({ children, c
 	});
 });
 MenuItemGroup.propTypes = {
+	/**
+	* A collection of MenuItems to be rendered within this group.
+	*/
 	children: prop_types.default.node,
+	/**
+	* Additional CSS class names.
+	*/
 	className: prop_types.default.string,
+	/**
+	* A required label titling this group.
+	*/
 	label: prop_types.default.string.isRequired
 };
 const MenuItemRadioGroup = (0, react.forwardRef)(function MenuItemRadioGroup({ className, defaultSelectedItem, items, itemToString = require_defaultItemToString.defaultItemToString, label, onChange, selectedItem, ...rest }, forwardRef) {
@@ -296,12 +347,33 @@ const MenuItemRadioGroup = (0, react.forwardRef)(function MenuItemRadioGroup({ c
 	});
 });
 MenuItemRadioGroup.propTypes = {
+	/**
+	* Additional CSS class names.
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify the default selected item. Must match the type of props.items.
+	*/
 	defaultSelectedItem: prop_types.default.any,
+	/**
+	* Converts an item into a string for display.
+	*/
 	itemToString: prop_types.default.func,
+	/**
+	* Provide the options for this radio group. Can be of any type, as long as you provide an appropriate props.itemToString function.
+	*/
 	items: prop_types.default.array,
+	/**
+	* A required label titling this radio group.
+	*/
 	label: prop_types.default.string.isRequired,
+	/**
+	* Provide an optional function to be called when the selection changes.
+	*/
 	onChange: prop_types.default.func,
+	/**
+	* Provide props.selectedItem to control the state of this radio group. Must match the type of props.items.
+	*/
 	selectedItem: prop_types.default.any
 };
 const MenuItemDivider = (0, react.forwardRef)(function MenuItemDivider({ className, ...rest }, forwardRef) {
@@ -313,7 +385,11 @@ const MenuItemDivider = (0, react.forwardRef)(function MenuItemDivider({ classNa
 		ref: forwardRef
 	});
 });
-MenuItemDivider.propTypes = { className: prop_types.default.string };
+MenuItemDivider.propTypes = { 
+/**
+* Additional CSS class names.
+*/
+className: prop_types.default.string };
 //#endregion
 exports.MenuItem = MenuItem;
 exports.MenuItemDivider = MenuItemDivider;

package/lib/components/MenuButton/index.js

@@ -14,10 +14,10 @@ const require_index$1 = require("../Button/index.js");
 const require_mergeRefs = require("../../tools/mergeRefs.js");
 const require_Menu = require("../Menu/Menu.js");
 const require_useAttachedMenu = require("../../internal/useAttachedMenu.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");
@@ -119,11 +119,29 @@ const MenuButton = (0, react.forwardRef)(({ children, className, disabled, kind
 	});
 });
 MenuButton.propTypes = {
+	/**
+	* A collection of MenuItems to be rendered as actions for this MenuButton.
+	*/
 	children: prop_types.default.node.isRequired,
+	/**
+	* Additional CSS class names.
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify whether the MenuButton should be disabled, or not.
+	*/
 	disabled: prop_types.default.bool,
+	/**
+	* Specify the type of button to be used as the base for the trigger button.
+	*/
 	kind: prop_types.default.oneOf(validButtonKinds),
+	/**
+	* Provide the label to be rendered on the trigger button.
+	*/
 	label: prop_types.default.string.isRequired,
+	/**
+	* Experimental property. Specify how the menu should align with the button element
+	*/
 	menuAlignment: prop_types.default.oneOf([
 		"top",
 		"top-start",
@@ -132,15 +150,30 @@ MenuButton.propTypes = {
 		"bottom-start",
 		"bottom-end"
 	]),
+	/**
+	* Specify the size of the button and menu.
+	*/
 	size: prop_types.default.oneOf([
 		"xs",
 		"sm",
 		"md",
 		"lg"
 	]),
+	/**
+	* Specify the tabIndex of the button.
+	*/
 	tabIndex: prop_types.default.number,
+	/**
+	* Specify the background token to use for the menu. Default is 'layer'.
+	*/
 	menuBackgroundToken: prop_types.default.oneOf(["layer", "background"]),
+	/**
+	* Specify whether a border should be rendered on the menu
+	*/
 	menuBorder: prop_types.default.bool,
+	/**
+	* Specify a DOM node where the Menu should be rendered in. Defaults to document.body.
+	*/
 	menuTarget: prop_types.default.instanceOf(typeof Element !== "undefined" ? Element : Object)
 };
 //#endregion

package/lib/components/Modal/Modal.js

@@ -6,14 +6,14 @@
  */
 
 const require_runtime = require("../../_virtual/_rolldown/runtime.js");
-const require_noopFn = require("../../internal/noopFn.js");
-const require_warning = require("../../internal/warning.js");
 const require_usePrefix = require("../../internal/usePrefix.js");
 const require_Text = require("../Text/Text.js");
 const require_keys = require("../../internal/keyboard/keys.js");
 const require_match = require("../../internal/keyboard/match.js");
 const require_navigation = require("../../internal/keyboard/navigation.js");
 const require_useId = require("../../internal/useId.js");
+const require_noopFn = require("../../internal/noopFn.js");
+const require_warning = require("../../internal/warning.js");
 const require_deprecate = require("../../prop-types/deprecate.js");
 const require_utils = require("../../internal/utils.js");
 const require_useMergedRefs = require("../../internal/useMergedRefs.js");
@@ -33,10 +33,10 @@ const require_isTopmostVisibleModal = require("./isTopmostVisibleModal.js");
 const require_requiredIfGivenPropIsTruthy = require("../../prop-types/requiredIfGivenPropIsTruthy.js");
 const require_usePreviousValue = require("../../internal/usePreviousValue.js");
 const require_ModalPresence = require("./ModalPresence.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");
@@ -487,43 +487,143 @@ const ModalDialog = react.default.forwardRef(function ModalDialog({ "aria-label"
 	});
 });
 Modal.propTypes = {
+	/**
+	* Specify whether the Modal is displaying an alert, error or warning
+	* Should go hand in hand with the danger prop.
+	*/
 	alert: prop_types.default.bool,
+	/**
+	* Required props for the accessibility label of the header
+	*/
 	["aria-label"]: require_requiredIfGivenPropIsTruthy.requiredIfGivenPropIsTruthy("hasScrollingContent", prop_types.default.string),
+	/**
+	* Provide the contents of your Modal
+	*/
 	children: prop_types.default.node,
+	/**
+	* Specify an optional className to be applied to the modal root node
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify label for the close button of the modal; defaults to close
+	*/
 	closeButtonLabel: prop_types.default.string,
+	/**
+	* Specify whether the Modal is for dangerous actions
+	*/
 	danger: prop_types.default.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: prop_types.default.string,
+	/**
+	* **Experimental**: Provide a decorator component to be rendered inside the `Modal` component
+	*/
 	decorator: prop_types.default.node,
+	/**
+	* Specify whether the modal contains scrolling content
+	*/
 	hasScrollingContent: prop_types.default.bool,
+	/**
+	* Specify the DOM element ID of the top-level node.
+	*/
 	id: prop_types.default.string,
+	/**
+	* Specify whether or not the Modal content should have any inner padding.
+	*/
 	isFullWidth: prop_types.default.bool,
+	/**
+	* Provide a ref to return focus to once the modal is closed.
+	*/
 	launcherButtonRef: prop_types.default.oneOfType([prop_types.default.func, prop_types.default.shape({ current: prop_types.default.oneOfType([typeof HTMLElement !== "undefined" ? prop_types.default.instanceOf(HTMLElement) : prop_types.default.any, prop_types.default.oneOf([null])]).isRequired })]),
+	/**
+	* Specify the description for the loading text
+	*/
 	loadingDescription: prop_types.default.string,
+	/**
+	* Specify the description for the loading text
+	*/
 	loadingIconDescription: prop_types.default.string,
+	/**
+	* loading status
+	*/
 	loadingStatus: prop_types.default.oneOf([
 		"inactive",
 		"active",
 		"finished",
 		"error"
 	]),
+	/**
+	* Specify a label to be read by screen readers on the modal root node
+	*/
 	modalAriaLabel: prop_types.default.string,
+	/**
+	* Specify the content of the modal header title.
+	*/
 	modalHeading: prop_types.default.node,
+	/**
+	* Specify the content of the modal header label.
+	*/
 	modalLabel: prop_types.default.node,
+	/**
+	* Specify a handler for keypresses.
+	*/
 	onKeyDown: prop_types.default.func,
+	/**
+	* Provide an optional handler to be invoked when loading is
+	* successful
+	*/
 	onLoadingSuccess: prop_types.default.func,
+	/**
+	* Specify a handler for closing modal.
+	* The handler should care of closing modal, e.g. changing `open` prop.
+	*/
 	onRequestClose: prop_types.default.func,
+	/**
+	* Specify a handler for "submitting" modal.
+	* The handler should care of closing modal, e.g. changing `open` prop, if necessary.
+	*/
 	onRequestSubmit: prop_types.default.func,
+	/**
+	* Specify a handler for the secondary button.
+	* Useful if separate handler from `onRequestClose` is desirable
+	*/
 	onSecondarySubmit: prop_types.default.func,
+	/**
+	* Specify whether the Modal is currently open
+	*/
 	open: prop_types.default.bool,
+	/**
+	* Specify whether the modal should be button-less
+	*/
 	passiveModal: prop_types.default.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: prop_types.default.bool,
+	/**
+	* Specify the text for the primary button
+	*/
 	primaryButtonText: prop_types.default.node,
+	/**
+	* Specify the text for the secondary button
+	*/
 	secondaryButtonText: prop_types.default.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`);
@@ -537,9 +637,23 @@ Modal.propTypes = {
 		}
 		return null;
 	},
+	/**
+	* Specify a CSS selector that matches the DOM element that should
+	* be focused when the Modal opens
+	*/
 	selectorPrimaryFocus: prop_types.default.string,
+	/**
+	* Specify CSS selectors that match DOM elements working as floating menus.
+	* Focusing on those elements won't trigger "focus-wrap" behavior
+	*/
 	selectorsFloatingMenus: prop_types.default.arrayOf(prop_types.default.string.isRequired),
+	/**
+	* Specify if Enter key should be used as "submit" action
+	*/
 	shouldSubmitOnEnter: prop_types.default.bool,
+	/**
+	* Specify the size variant.
+	*/
 	size: prop_types.default.oneOf(ModalSizes),
 	slug: require_deprecate.deprecate(prop_types.default.node, "The `slug` prop has been deprecated and will be removed in the next major version. Use the decorator prop instead.")
 };

package/lib/components/ModalWrapper/ModalWrapper.js

@@ -6,10 +6,10 @@
  */
 
 const require_runtime = require("../../_virtual/_rolldown/runtime.js");
-const require_noopFn = require("../../internal/noopFn.js");
-const require_warning = require("../../internal/warning.js");
 const require_keys = require("../../internal/keyboard/keys.js");
 const require_match = require("../../internal/keyboard/match.js");
+const require_noopFn = require("../../internal/noopFn.js");
+const require_warning = require("../../internal/warning.js");
 const require_Button = require("../Button/Button.js");
 const require_index = require("../Button/index.js");
 const require_index$1 = require("../Modal/index.js");

package/lib/components/MultiSelect/FilterableMultiSelect.js

@@ -29,10 +29,10 @@ const require_MultiSelectPropTypes = require("./MultiSelectPropTypes.js");
 const require_isSelectAllItem = require("./tools/isSelectAllItem.js");
 const require_sorting = require("./tools/sorting.js");
 const require_Selection = require("../../internal/Selection.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");
@@ -577,45 +577,173 @@ const FilterableMultiSelect = (0, react.forwardRef)(function FilterableMultiSele
 });
 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"]: require_deprecate.deprecate(prop_types.default.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: require_deprecate.deprecate(prop_types.default.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: prop_types.default.bool,
+	/**
+	* Specify the text that should be read for screen readers that describes total items selected
+	*/
 	clearSelectionDescription: prop_types.default.string,
+	/**
+	* Specify the text that should be read for screen readers to clear selection.
+	*/
 	clearSelectionText: prop_types.default.string,
+	/**
+	* **Experimental**: Provide a decorator component to be rendered inside the `FilterableMultiSelect` component
+	*/
 	decorator: prop_types.default.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: prop_types.default.func,
+	/**
+	* Specify the direction of the multiselect dropdown. Can be either top or bottom.
+	*/
 	direction: prop_types.default.oneOf(["top", "bottom"]),
+	/**
+	* Disable the control
+	*/
 	disabled: prop_types.default.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: prop_types.default.shape(downshift.default.propTypes),
+	/**
+	* Specify whether the title text should be hidden or not
+	*/
 	hideLabel: prop_types.default.bool,
+	/**
+	* Specify a custom `id`
+	*/
 	id: prop_types.default.string.isRequired,
+	/**
+	* Allow users to pass in arbitrary items from their collection that are
+	* pre-selected
+	*/
 	initialSelectedItems: prop_types.default.array,
+	/**
+	* Is the current selection invalid?
+	*/
 	invalid: prop_types.default.bool,
+	/**
+	* If invalid, what is the error?
+	*/
 	invalidText: prop_types.default.node,
+	/**
+	* Function to render items as custom components instead of strings.
+	* Defaults to null and is overridden by a getter
+	*/
 	itemToElement: prop_types.default.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: prop_types.default.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: prop_types.default.array.isRequired,
+	/**
+	* `true` to use the light version.
+	*/
 	light: require_deprecate.deprecate(prop_types.default.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: prop_types.default.string,
+	/**
+	* `onChange` is a utility for this controlled component to communicate to a
+	* consuming component what kind of internal state changes are occurring.
+	*/
 	onChange: prop_types.default.func,
+	/**
+	* `onInputValueChange` is a utility for this controlled component to communicate to
+	* the currently typed input.
+	*/
 	onInputValueChange: prop_types.default.func,
+	/**
+	* `onMenuChange` is a utility for this controlled component to communicate to a
+	* consuming component that the menu was opened(`true`)/closed(`false`).
+	*/
 	onMenuChange: prop_types.default.func,
+	/**
+	* Initialize the component with an open(`true`)/closed(`false`) menu.
+	*/
 	open: prop_types.default.bool,
+	/**
+	* Generic `placeholder` that will be used as the textual representation of
+	* what this field is for
+	*/
 	placeholder: prop_types.default.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: prop_types.default.oneOf([
 		"top",
 		"fixed",
 		"top-after-reopen"
 	]),
+	/**
+	* Specify the size of the ListBox. Currently supports either `sm`, `md` or `lg` as an option.
+	*/
 	size: require_ListBoxPropTypes.ListBoxSizePropType,
 	slug: require_deprecate.deprecate(prop_types.default.node, "The `slug` prop has been deprecated and will be removed in the next major version. Use the decorator prop instead."),
 	...require_MultiSelectPropTypes.sortingPropTypes,
+	/**
+	* Provide text to be used in a `<label>` element that is tied to the
+	* combobox via ARIA attributes.
+	*/
 	titleText: prop_types.default.node,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: prop_types.default.func,
 	type: require_ListBoxPropTypes.ListBoxTypePropType,
+	/**
+	* Specify title to show title on hover
+	*/
 	useTitleInItem: prop_types.default.bool,
+	/**
+	* Specify whether the control is currently in warning state
+	*/
 	warn: prop_types.default.bool,
+	/**
+	* Provide the text that is displayed when the control is in warning state
+	*/
 	warnText: prop_types.default.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: prop_types.default.object
 };
 //#endregion