@carbon/react 1.110.0-rc.0 → 1.111.0-rc.0

package/lib/components/Modal/Modal.js

@@ -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/MultiSelect/FilterableMultiSelect.js

@@ -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

package/lib/components/MultiSelect/MultiSelect.js

@@ -146,6 +146,7 @@ const MultiSelect = react.default.forwardRef(({ autoAlign = false, className: co
 				if (require_match.match(e, require_keys.ArrowDown) && selectedItems.length === 0) setInputFocused(false);
 				if (require_match.match(e, require_keys.Escape) && isOpen) setInputFocused(true);
 				if (require_match.match(e, require_keys.Enter) && isOpen) setInputFocused(true);
+				if (require_match.match(e, require_keys.Tab) && isOpen) setIsOpenWrapper(false);
 			}
 		}
 	});
@@ -424,45 +425,192 @@ const MultiSelect = react.default.forwardRef(({ autoAlign = false, className: co
 MultiSelect.displayName = "MultiSelect";
 MultiSelect.propTypes = {
 	...require_MultiSelectPropTypes.sortingPropTypes,
+	/**
+	* **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,
+	/**
+	* Provide a custom class name to be added to the outermost node in the
+	* component
+	*/
 	className: prop_types.default.string,
+	/**
+	* 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,
+	/**
+	* Provide a compare function that is used to determine the ordering of
+	* options. See 'sortItems' for more control. Consider
+	* declaring function with `useCallback` to prevent unnecessary re-renders.
+	*/
 	compareItems: prop_types.default.func,
+	/**
+	* **Experimental**: Provide a decorator component to be rendered inside the `MultiSelect` component
+	*/
 	decorator: prop_types.default.node,
+	/**
+	* 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.object,
+	/**
+	* Provide helper text that is used alongside the control label for
+	* additional help
+	*/
 	helperText: prop_types.default.node,
+	/**
+	* 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,
+	/**
+	* Renders an item as a custom React node instead of a string.
+	*/
 	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. Consider
+	* declaring function with `useCallback` to prevent unnecessary re-renders.
+	*/
 	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,
+	/**
+	* Generic `label` that will be used as the textual representation of what
+	* this field is for
+	*/
 	label: prop_types.default.node.isRequired,
+	/**
+	* `true` to use the light version.
+	*/
 	light: require_deprecate.deprecate(prop_types.default.bool, "The `light` prop for `MultiSelect` 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,
+	/**
+	* `onMenuChange` is a utility for this controlled component to communicate to a
+	* consuming component that the menu was open(`true`)/closed(`false`).
+	*/
 	onMenuChange: prop_types.default.func,
+	/**
+	* Initialize the component with an open(`true`)/closed(`false`) menu.
+	*/
 	open: prop_types.default.bool,
+	/**
+	* Whether or not the Dropdown is readonly
+	*/
 	readOnly: prop_types.default.bool,
+	/**
+	* For full control of the selected items
+	*/
 	selectedItems: prop_types.default.array,
+	/**
+	* 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 `xs`, `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."),
+	/**
+	* Provide a method that sorts all options in the control. Overriding this
+	* prop means that you also have to handle the sort logic for selected versus
+	* un-selected items. If you just want to control ordering, consider the
+	* `compareItems` prop instead.
+	*
+	* The return value should be a number whose sign indicates the relative order
+	* of the two elements: negative if a is less than b, positive if a is greater
+	* than b, and zero if they are equal.
+	*
+	* sortItems :
+	*   (items: Array<Item>, {
+	*     selectedItems: Array<Item>,
+	*     itemToString: Item => string,
+	*     compareItems: (itemA: string, itemB: string, {
+	*       locale: string
+	*     }) => number,
+	*     locale: string,
+	*   }) => Array<Item>
+	*/
 	sortItems: prop_types.default.func,
+	/**
+	* Provide text to be used in a `<label>` element that is tied to the
+	* multiselect via ARIA attributes.
+	*/
 	titleText: prop_types.default.node,
+	/**
+	* Translates component strings using your i18n tool.
+	*/
 	translateWithId: prop_types.default.func,
+	/**
+	* Specify 'inline' to create an inline multi-select.
+	*/
 	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
 };
 //#endregion

package/lib/components/MultiSelect/MultiSelectPropTypes.js

@@ -16,7 +16,32 @@ prop_types = require_runtime.__toESM(prop_types);
 * LICENSE file in the root directory of this source tree.
 */
 const sortingPropTypes = {
+	/**
+	* Provide a compare function that is used to determine the ordering of
+	* options. `compareItems` has the following function signature:
+	*
+	* compareFunction :
+	*  (itemA: string, itemB: string, { locale: string }) => number
+	*/
 	compareItems: prop_types.default.func,
+	/**
+	* Provide a method that sorts all options in the control. Overriding this
+	* prop means that you also have to handle the sort logic for selected versus
+	* un-selected items. If you just want to control ordering, consider the
+	* `compareItems` prop instead.
+	*
+	* `sortItems` has the following signature:
+	*
+	* sortItems :
+	*   (items: Array<Item>, {
+	*     selectedItems: Array<Item>,
+	*     itemToString: Item => string,
+	*     compareItems: (itemA: string, itemB: string, {
+	*       locale: string
+	*     }) => number,
+	*     locale: string,
+	*   }) => Array<Item>
+	*/
 	sortItems: prop_types.default.func
 };
 //#endregion