@carbon/react 1.110.0 → 1.111.0-rc.0

package/lib/components/MultiSelect/MultiSelect.js

@@ -6,12 +6,12 @@
  */
 
 const require_runtime = require("../../_virtual/_rolldown/runtime.js");
-const require_noopFn = require("../../internal/noopFn.js");
 const require_usePrefix = require("../../internal/usePrefix.js");
 const require_keys = require("../../internal/keyboard/keys.js");
 const require_match = require("../../internal/keyboard/match.js");
 const require_useIsomorphicEffect = require("../../internal/useIsomorphicEffect.js");
 const require_useId = require("../../internal/useId.js");
+const require_noopFn = require("../../internal/noopFn.js");
 const require_deprecate = require("../../prop-types/deprecate.js");
 const require_defaultItemToString = require("../../internal/defaultItemToString.js");
 const require_utils = require("../../internal/utils.js");
@@ -27,10 +27,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");
@@ -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

package/lib/components/Notification/Notification.js

@@ -6,24 +6,24 @@
  */
 
 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_useIsomorphicEffect = require("../../internal/useIsomorphicEffect.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_deprecateValuesWithin = require("../../prop-types/deprecateValuesWithin.js");
 const require_index = require("../FeatureFlags/index.js");
 const require_useNoInteractiveChildren = require("../../internal/useNoInteractiveChildren.js");
 const require_index$1 = require("../Button/index.js");
 const require_wrapFocus = require("../../internal/wrapFocus.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");
@@ -62,9 +62,21 @@ function NotificationActionButton({ children, className: customClassName, onClic
 	});
 }
 NotificationActionButton.propTypes = {
+	/**
+	* Specify the content of the notification action button.
+	*/
 	children: prop_types.default.node,
+	/**
+	* Specify an optional className to be applied to the notification action button
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify if the visual treatment of the button should be for an inline notification
+	*/
 	inline: prop_types.default.bool,
+	/**
+	* Optionally specify a click handler for the notification action button.
+	*/
 	onClick: prop_types.default.func
 };
 function NotificationButton({ "aria-label": ariaLabel = "close notification", ariaLabel: deprecatedAriaLabel, className, type = "button", renderIcon: IconTag = _carbon_icons_react.Close, name, notificationType = "toast", ...rest }) {
@@ -84,16 +96,39 @@ function NotificationButton({ "aria-label": ariaLabel = "close notification", ar
 	});
 }
 NotificationButton.propTypes = {
+	/**
+	* Specify a label to be read by screen readers on the container node
+	*/
 	["aria-label"]: prop_types.default.string,
+	/**
+	* 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, "This prop syntax has been deprecated. Please use the new `aria-label`."),
+	/**
+	* Specify an optional className to be applied to the notification button
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify an optional icon for the Button through a string,
+	* if something but regular "close" icon is desirable
+	*/
 	name: prop_types.default.string,
+	/**
+	* Specify the notification type
+	*/
 	notificationType: prop_types.default.oneOf([
 		"toast",
 		"inline",
 		"actionable"
 	]),
+	/**
+	* A component used to render an icon.
+	*/
 	renderIcon: prop_types.default.oneOfType([prop_types.default.func, prop_types.default.object]),
+	/**
+	* Optional prop to specify the type of the Button
+	*/
 	type: prop_types.default.string
 };
 /**
@@ -205,12 +240,34 @@ function ToastNotification({ ["aria-label"]: ariaLabel, ariaLabel: deprecatedAri
 	});
 }
 ToastNotification.propTypes = {
+	/**
+	* Provide a description for "close" icon button that can be read by screen readers
+	*/
 	["aria-label"]: prop_types.default.string,
+	/**
+	* Deprecated, please use `aria-label` instead.
+	* Provide a description for "close" icon button that can be read by screen readers
+	*/
 	ariaLabel: require_deprecate.deprecate(prop_types.default.string, "This prop syntax has been deprecated. Please use the new `aria-label`."),
+	/**
+	* Specify the caption
+	*/
 	caption: prop_types.default.string,
+	/**
+	* Specify the content
+	*/
 	children: prop_types.default.node,
+	/**
+	* Specify an optional className to be applied to the notification box
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify the close button should be disabled, or not
+	*/
 	hideCloseButton: prop_types.default.bool,
+	/**
+	* Specify what state the notification represents
+	*/
 	kind: prop_types.default.oneOf([
 		"error",
 		"info",
@@ -219,17 +276,42 @@ ToastNotification.propTypes = {
 		"warning",
 		"warning-alt"
 	]),
+	/**
+	* Specify whether you are using the low contrast variant of the ToastNotification.
+	*/
 	lowContrast: prop_types.default.bool,
+	/**
+	* Provide a function that is called when menu is closed
+	*/
 	onClose: prop_types.default.func,
+	/**
+	* Provide a function that is called when the close button is clicked
+	*/
 	onCloseButtonClick: prop_types.default.func,
+	/**
+	* By default, this value is "status". You can also provide an alternate
+	* role if it makes sense from the accessibility-side
+	*/
 	role: prop_types.default.oneOf([
 		"alert",
 		"log",
 		"status"
 	]),
+	/**
+	* Provide a description for "status" icon that can be read by screen readers
+	*/
 	statusIconDescription: prop_types.default.string,
+	/**
+	* Specify the subtitle
+	*/
 	subtitle: prop_types.default.string,
+	/**
+	* Specify an optional duration the notification should be closed in
+	*/
 	timeout: prop_types.default.number,
+	/**
+	* Specify the title
+	*/
 	title: prop_types.default.string
 };
 function InlineNotification({ ["aria-label"]: ariaLabel, children, title, subtitle, role = "status", onClose, onCloseButtonClick = require_noopFn.noopFn, statusIconDescription, className, kind = "error", lowContrast, hideCloseButton = false, ...rest }) {
@@ -288,10 +370,25 @@ function InlineNotification({ ["aria-label"]: ariaLabel, children, title, subtit
 	});
 }
 InlineNotification.propTypes = {
+	/**
+	* Provide a description for "close" icon button that can be read by screen readers
+	*/
 	["aria-label"]: prop_types.default.string,
+	/**
+	* Specify the content
+	*/
 	children: prop_types.default.node,
+	/**
+	* Specify an optional className to be applied to the notification box
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify the close button should be disabled, or not
+	*/
 	hideCloseButton: prop_types.default.bool,
+	/**
+	* Specify what state the notification represents
+	*/
 	kind: prop_types.default.oneOf([
 		"error",
 		"info",
@@ -300,16 +397,38 @@ InlineNotification.propTypes = {
 		"warning",
 		"warning-alt"
 	]),
+	/**
+	* Specify whether you are using the low contrast variant of the InlineNotification.
+	*/
 	lowContrast: prop_types.default.bool,
+	/**
+	* Provide a function that is called when menu is closed
+	*/
 	onClose: prop_types.default.func,
+	/**
+	* Provide a function that is called when the close button is clicked
+	*/
 	onCloseButtonClick: prop_types.default.func,
+	/**
+	* By default, this value is "status". You can also provide an alternate
+	* role if it makes sense from the accessibility-side.
+	*/
 	role: prop_types.default.oneOf([
 		"alert",
 		"log",
 		"status"
 	]),
+	/**
+	* Provide a description for "status" icon that can be read by screen readers
+	*/
 	statusIconDescription: prop_types.default.string,
+	/**
+	* Specify the subtitle
+	*/
 	subtitle: prop_types.default.string,
+	/**
+	* Specify the title
+	*/
 	title: prop_types.default.string
 };
 function ActionableNotification({ actionButtonLabel, ["aria-label"]: ariaLabel, ariaLabel: deprecatedAriaLabel, caption, children, role = "alertdialog", onActionButtonClick, onClose, onCloseButtonClick = require_noopFn.noopFn, statusIconDescription, className, inline = false, kind = "error", lowContrast, hideCloseButton = false, hasFocus = true, closeOnEscape = true, title, subtitle, ...rest }) {
@@ -439,16 +558,47 @@ function ActionableNotification({ actionButtonLabel, ["aria-label"]: ariaLabel,
 	});
 }
 ActionableNotification.propTypes = {
+	/**
+	* Pass in the action button label that will be rendered within the ActionableNotification.
+	*/
 	actionButtonLabel: prop_types.default.string,
+	/**
+	* Provide a description for "close" icon button that can be read by screen readers
+	*/
 	["aria-label"]: prop_types.default.string,
+	/**
+	* Deprecated, please use `aria-label` instead.
+	* Provide a description for "close" icon button that can be read by screen readers
+	*/
 	ariaLabel: require_deprecate.deprecate(prop_types.default.string, "This prop syntax has been deprecated. Please use the new `aria-label`."),
+	/**
+	* Specify the caption
+	*/
 	caption: prop_types.default.string,
+	/**
+	* Specify the content
+	*/
 	children: prop_types.default.node,
+	/**
+	* Specify an optional className to be applied to the notification box
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify if pressing the escape key should close notifications
+	*/
 	closeOnEscape: prop_types.default.bool,
+	/**
+	* Specify if focus should be moved to the component when the notification contains actions
+	*/
 	hasFocus: require_deprecate.deprecate(prop_types.default.bool, "hasFocus is deprecated. To conform to accessibility requirements hasFocus should always be `true` for ActionableNotification. If you were setting this prop to `false`, consider using the Callout component instead."),
+	/**
+	* Specify the close button should be disabled, or not
+	*/
 	hideCloseButton: prop_types.default.bool,
 	inline: prop_types.default.bool,
+	/**
+	* Specify what state the notification represents
+	*/
 	kind: prop_types.default.oneOf([
 		"error",
 		"info",
@@ -457,13 +607,40 @@ ActionableNotification.propTypes = {
 		"warning",
 		"warning-alt"
 	]),
+	/**
+	* Specify whether you are using the low contrast variant of the ActionableNotification.
+	*/
 	lowContrast: prop_types.default.bool,
+	/**
+	* Provide a function that is called when the action is clicked
+	*/
 	onActionButtonClick: prop_types.default.func,
+	/**
+	* Provide a function that is called when menu is closed
+	*/
 	onClose: prop_types.default.func,
+	/**
+	* Provide a function that is called when the close button is clicked
+	*/
 	onCloseButtonClick: prop_types.default.func,
+	/**
+	* Provide an accessible role to be used. Defaults to `alertdialog`. Any other
+	* value will disable the wrapping of focus. To remain accessible, additional
+	* work is required. See the storybook docs for more info:
+	* https://react.carbondesignsystem.com/?path=/docs/components-notifications-actionable--overview#using-the-role-prop
+	*/
 	role: prop_types.default.string,
+	/**
+	* Provide a description for "status" icon that can be read by screen readers
+	*/
 	statusIconDescription: prop_types.default.string,
+	/**
+	* Specify the subtitle
+	*/
 	subtitle: prop_types.default.node,
+	/**
+	* Specify the title
+	*/
 	title: prop_types.default.string
 };
 const mapping = {
@@ -522,9 +699,21 @@ function Callout({ actionButtonLabel, children, onActionButtonClick, title, titl
 	});
 }
 Callout.propTypes = {
+	/**
+	* Pass in the action button label that will be rendered within the ActionableNotification.
+	*/
 	actionButtonLabel: prop_types.default.string,
+	/**
+	* Specify the content
+	*/
 	children: prop_types.default.node,
+	/**
+	* Specify an optional className to be applied to the notification box
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify what state the notification represents
+	*/
 	kind: require_deprecateValuesWithin.deprecateValuesWithin(prop_types.default.oneOf([
 		"error",
 		"info",
@@ -533,11 +722,29 @@ Callout.propTypes = {
 		"warning",
 		"warning-alt"
 	]), ["warning", "info"], propMappingFunction),
+	/**
+	* Specify whether you are using the low contrast variant of the Callout.
+	*/
 	lowContrast: prop_types.default.bool,
+	/**
+	* Provide a function that is called when the action is clicked
+	*/
 	onActionButtonClick: prop_types.default.func,
+	/**
+	* Provide a description for "status" icon that can be read by screen readers
+	*/
 	statusIconDescription: prop_types.default.string,
+	/**
+	* Specify the subtitle
+	*/
 	subtitle: prop_types.default.node,
+	/**
+	* Specify the title
+	*/
 	title: prop_types.default.string,
+	/**
+	* Specify the id for the element containing the title
+	*/
 	titleId: prop_types.default.string
 };
 let didWarnAboutDeprecation = false;

package/lib/components/NumberInput/NumberInput.Skeleton.js

@@ -7,10 +7,10 @@
 
 const require_runtime = require("../../_virtual/_rolldown/runtime.js");
 const require_usePrefix = require("../../internal/usePrefix.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");
@@ -30,8 +30,17 @@ function NumberInputSkeleton({ hideLabel, className, size = "md", ...rest }) {
 	});
 }
 NumberInputSkeleton.propTypes = {
+	/**
+	* Specify an optional className to add to the form item wrapper.
+	*/
 	className: prop_types.default.string,
+	/**
+	* Specify whether the label should be hidden, or not
+	*/
 	hideLabel: prop_types.default.bool,
+	/**
+	* Specify the size of the Number Input.
+	*/
 	size: prop_types.default.oneOf([
 		"sm",
 		"md",