@carbon/ibm-products 2.81.0-rc.0 → 2.82.0-rc.0

package/lib/components/ActionBar/ActionBar.js

@@ -0,0 +1,173 @@
+/**
+ * Copyright IBM Corp. 2020, 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+var _rollupPluginBabelHelpers = require('../../_virtual/_rollupPluginBabelHelpers.js');
+var React = require('react');
+var index = require('../../_virtual/index.js');
+var cx = require('classnames');
+var settings = require('../../settings.js');
+var react = require('@carbon/react');
+var uuidv4 = require('../../global/js/utils/uuidv4.js');
+var propsHelper = require('../../global/js/utils/props-helper.js');
+var ActionBarItem = require('./ActionBarItem.js');
+var ActionBarOverflowItems = require('./ActionBarOverflowItems.js');
+var useOverflowItems = require('../../global/js/hooks/useOverflowItems/useOverflowItems.js');
+
+// The block part of our conventional BEM class names (blockClass__E--M).
+const blockClass = `${settings.pkg.prefix}--action-bar`;
+const componentName = 'ActionBar';
+
+// Default values for props
+const defaults = {
+  actions: Object.freeze([])
+};
+// NOTE: the component SCSS is not imported here: it is rolled up separately.
+
+/**
+ * The ActionBar is used internally by the PageHeader to wrap ActionBarItems.
+ */
+const ActionBar = /*#__PURE__*/React.forwardRef((_ref, ref) => {
+  let {
+    // The component props, in alphabetical order (for consistency).
+
+    actions = defaults.actions,
+    className,
+    maxVisible,
+    menuOptionsClass,
+    onWidthChange,
+    overflowAriaLabel,
+    overflowMenuRef,
+    rightAlign,
+    // Collect any other property values passed in.
+    ...rest
+  } = _ref;
+  const internalId = React.useRef(uuidv4.default());
+  const refDisplayedItems = React.useRef(null);
+  const backupRef = React.useRef(null);
+  const localRef = ref || backupRef;
+  const _offsetRef = React.useRef(null);
+  const offsetRef = overflowMenuRef || _offsetRef;
+  const _items = actions.map(action => ({
+    id: action?.key,
+    ...action
+  }));
+  const {
+    visibleItems,
+    hiddenItems,
+    itemRefHandler,
+    offsetRefHandler
+  } = useOverflowItems.useOverflowItems(_items, localRef, offsetRef, maxVisible, onWidthChange);
+  const overflowMenuItems = hiddenItems?.map(_ref2 => {
+    let {
+      id: key,
+      ...rest
+    } = _ref2;
+    return /*#__PURE__*/React.createElement(ActionBarItem.ActionBarItem, _rollupPluginBabelHelpers.extends({}, rest, {
+      key: key
+    }));
+  });
+  return /*#__PURE__*/React.createElement("div", _rollupPluginBabelHelpers.extends({}, rest, {
+    className: cx([blockClass, className]),
+    ref: localRef
+  }), /*#__PURE__*/React.createElement("div", {
+    ref: refDisplayedItems,
+    className: cx([`${blockClass}__displayed-items`, {
+      [`${blockClass}__displayed-items--right`]: rightAlign
+    }])
+  }, visibleItems.map(_ref3 => {
+    let {
+      key,
+      id,
+      ...rest
+    } = _ref3;
+    return /*#__PURE__*/React.createElement(ActionBarItem.ActionBarItem, _rollupPluginBabelHelpers.extends({
+      id
+    }, rest, {
+      key: key,
+      ref: node => {
+        itemRefHandler(id, node);
+      }
+    }));
+  }), overflowMenuItems?.length > 0 && /*#__PURE__*/React.createElement(ActionBarOverflowItems.ActionBarOverflowItems, {
+    menuOptionsClass: menuOptionsClass,
+    overflowAriaLabel: overflowAriaLabel,
+    overflowMenuRef: node => offsetRef.current = offsetRefHandler(node),
+    overflowItems: overflowMenuItems,
+    key: `overflow-menu-${internalId.current}`
+  })));
+});
+ActionBar.displayName = componentName;
+ActionBar.propTypes = {
+  /**
+   * Specifies the action bar items. Each item is specified as an object
+   * with required fields: key for array rendering, renderIcon, iconDescription and
+   * label to provide the icon to display,
+   * and optional 'onClick' to receive notifications when the button is clicked.
+   * Additional fields in the object will be passed to the
+   * Button component, and these can include 'disabled', 'ref', 'className',
+   * and any other Button props.
+   *
+   * Note that the Button props 'kind', 'size',
+   * 'tooltipPosition', 'tooltipAlignment' and 'type' are ignored, as these
+   * cannot be used for an action bar item.
+   *
+   * Carbon Button API https://react.carbondesignsystem.com/?path=/docs/components-button--default#component-api
+   */
+  /**@ts-ignore */
+  actions: index.default.arrayOf(index.default.shape({
+    /**@ts-ignore */
+    ...propsHelper.prepareProps(react.Button.propTypes, [
+    // props not desired from Button.propTypes
+    'kind', 'size', 'tooltipPosition', 'tooltipAlignment']),
+    id: index.default.string,
+    // Additional props
+    key: index.default.string.isRequired,
+    // Redefine as form different  to Button and a key prop used by ActionBarItems
+    iconDescription: index.default.string.isRequired,
+    label: index.default.string.isRequired,
+    /**@ts-ignore */
+    renderIcon: react.Button.propTypes.renderIcon.isRequired,
+    // We duplicate onClick here to improve DocGen in Storybook
+    onClick: index.default.func
+  })),
+  // expects action bar item as array or in fragment,
+  /**
+   * className
+   */
+  className: index.default.string,
+  /**
+   * maxVisible : Maximum action bar items visible before going into the overflow menu
+   */
+  maxVisible: index.default.number,
+  /**
+   * class name applied to the overflow options
+   */
+  menuOptionsClass: index.default.string,
+  /**
+   * onItemCountChange - event reporting maxWidth
+   */
+  onWidthChange: index.default.func,
+  /**
+   * overflowAriaLabel label for open close button overflow used for action bar items that do nto fit.
+   */
+  overflowAriaLabel: index.default.string.isRequired,
+  /**
+   * overflowMenuRef for the overflow menu width that is needed to calculate the width of the action bar with overflow
+   */
+  /**@ts-ignore */
+  overflowMenuRef: index.default.oneOfType([index.default.shape({
+    current: index.default.elementType
+  }), index.default.object]),
+  /**
+   * align tags to right of available space
+   */
+  rightAlign: index.default.bool
+};
+
+exports.ActionBar = ActionBar;

package/lib/components/ActionBar/ActionBarItem.d.ts

@@ -0,0 +1,39 @@
+import React, { PropsWithChildren } from 'react';
+import { CarbonIconType } from '@carbon/icons-react/lib/CarbonIcon';
+interface ActionBarItemProps extends PropsWithChildren {
+    /**
+     * Specify an optional className to be added to your Button
+     *
+     * (inherited from Carbon Button)
+     */
+    className?: string;
+    /**
+     * If specifying the `renderIcon` prop, provide a description for that icon that can
+     * be read by screen readers
+     *
+     * (inherited from Carbon Button)
+     */
+    label?: string;
+    /**
+     * Optional click handler
+     *
+     * (inherited from Carbon Button)
+     */
+    onClick?: () => void;
+    /**
+     * Optional prop to allow overriding the icon rendering.
+     * Can be a React component class
+     *
+     * (inherited from Carbon Button)
+     */
+    renderIcon?: CarbonIconType;
+    /**
+     * Optional tab index
+     */
+    tabIndex?: number;
+}
+/**
+ * The ActionBarItem is used in the page header to populate the action bar
+ */
+export declare const ActionBarItem: React.ForwardRefExoticComponent<ActionBarItemProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/lib/components/ActionBar/ActionBarItem.js

@@ -0,0 +1,102 @@
+/**
+ * Copyright IBM Corp. 2020, 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+var _rollupPluginBabelHelpers = require('../../_virtual/_rollupPluginBabelHelpers.js');
+var React = require('react');
+var index = require('../../_virtual/index.js');
+var cx = require('classnames');
+var settings = require('../../settings.js');
+var react = require('@carbon/react');
+
+// The block part of our conventional BEM class names (blockClass__E--M).
+const componentName = 'ActionBarItem';
+const blockClass = `${settings.pkg.prefix}--action-bar-item`;
+// NOTE: the component SCSS is not imported here: it is rolled up separately.
+
+/**
+ * The ActionBarItem is used in the page header to populate the action bar
+ */
+const ActionBarItem = /*#__PURE__*/React.forwardRef((_ref, ref) => {
+  let {
+    label,
+    className,
+    renderIcon,
+    ...rest
+  } = _ref;
+  const Icon = renderIcon;
+  return /*#__PURE__*/React.createElement(react.IconButton, _rollupPluginBabelHelpers.extends({}, rest, {
+    ref,
+    className: cx(blockClass, className),
+    kind: 'ghost',
+    size: 'md',
+    align: 'bottom-end',
+    type: 'button',
+    label
+  }), Icon ? /*#__PURE__*/React.createElement(Icon, null) : null);
+});
+
+// Return a placeholder if not released and not enabled by feature flag
+
+// Props the user cannot change
+const reservedProps = ['kind', 'size', 'align', 'type'];
+// Base props on Carbon Button
+const propTypes = {
+  ...react.IconButton.propTypes
+};
+
+// Remove reserved props
+reservedProps.forEach(prop => {
+  delete propTypes[prop];
+});
+ActionBarItem.displayName = componentName;
+ActionBarItem.propTypes = {
+  /**
+   * The ...propTypes are copies of those from Button minus the props reserved for use by this component
+   */
+  ...propTypes,
+  /* ***************************************
+  /
+  /  The declarations below allow storybook & DocGen to produce documentation.
+  /  Some or all of them may be inherited from the underlying Carbon component.
+  /
+  / ****************************************/
+  /**
+   * Specify an optional className to be added to your Button
+   *
+   * (inherited from Carbon Button)
+   */
+  className: index.default.string,
+  /**
+   * If specifying the `renderIcon` prop, provide a description for that icon that can
+   * be read by screen readers
+   *
+   * (inherited from Carbon Button)
+   */
+  label: index.default.string,
+  /**
+   * Optional click handler
+   *
+   * (inherited from Carbon Button)
+   */
+  onClick: index.default.func,
+  /**
+   * Optional prop to allow overriding the icon rendering.
+   * Can be a React component class
+   *
+   * (inherited from Carbon Button)
+   */
+  /**@ts-ignore */
+  renderIcon: index.default.oneOfType([index.default.func, index.default.object]),
+  /**
+   * Optional tab index
+   */
+  tabIndex: index.default.number
+};
+
+exports.ActionBarItem = ActionBarItem;

package/lib/components/ActionBar/ActionBarOverflowItems.d.ts

@@ -0,0 +1,65 @@
+import React, { PropsWithChildren, ReactElement, ForwardedRef } from 'react';
+import { CarbonIconType } from '@carbon/icons-react/lib/CarbonIcon';
+type OverflowItem = {
+    label: string;
+    onClick: () => void;
+    renderIcon: CarbonIconType;
+};
+interface ActionBarOverflowItemProps extends PropsWithChildren {
+    /**
+     * className
+     */
+    className?: string;
+    /**
+     * class name applied to the overflow options
+     */
+    menuOptionsClass?: string;
+    /**
+     * overflowAriaLabel label for open close button overflow used for action bar items that do not fit.
+     */
+    overflowAriaLabel?: string;
+    /**
+     * overflowMenuRef for the overflow menu width that is needed to calculate the width of the action bar with overflow
+     */
+    overflowMenuRef?: ForwardedRef<HTMLDivElement>;
+    /**
+     * overflowItems: items to bre shown in the ActionBar overflow menu
+     */
+    overflowItems?: ReactElement<OverflowItem>[];
+    /**
+     * Optional tab index
+     */
+    tabIndex?: number;
+}
+export declare const ActionBarOverflowItems: {
+    ({ className, menuOptionsClass, overflowItems, overflowAriaLabel, overflowMenuRef, }: ActionBarOverflowItemProps): React.JSX.Element;
+    displayName: string;
+    propTypes: {
+        /**
+         * className
+         */
+        className: any;
+        /**
+         * class name applied to the overflow options
+         */
+        menuOptionsClass: any;
+        /**
+         * overflowAriaLabel label for open close button overflow used for action bar items that do nto fit.
+         */
+        overflowAriaLabel: any;
+        /**
+         * overflowItems: items to bre shown in the ActionBar overflow menu
+         */
+        overflowItems: any;
+        /**
+         * overflowMenuRef for the overflow menu width that is needed to calculate the width of the action bar with overflow
+         */
+        /**@ts-ignore */
+        overflowMenuRef: any;
+        /**
+         * Optional tab index
+         */
+        tabIndex: any;
+    };
+};
+export {};

package/lib/components/ActionBar/ActionBarOverflowItems.js

@@ -0,0 +1,94 @@
+/**
+ * Copyright IBM Corp. 2020, 2026
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+var React = require('react');
+var index = require('../../_virtual/index.js');
+var cx = require('classnames');
+var react = require('@carbon/react');
+var uuidv4 = require('../../global/js/utils/uuidv4.js');
+var settings = require('../../settings.js');
+
+// Copyright IBM Corp. 2020, 2023
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+const blockClass = `${settings.pkg.prefix}--action-bar-overflow-items`;
+const componentName = 'ActionBar';
+const ActionBarOverflowItems = _ref => {
+  let {
+    className,
+    menuOptionsClass,
+    overflowItems,
+    overflowAriaLabel,
+    overflowMenuRef
+  } = _ref;
+  const internalId = React.useRef(uuidv4.default());
+  return /*#__PURE__*/React.createElement("div", {
+    ref: overflowMenuRef
+  }, /*#__PURE__*/React.createElement(react.OverflowMenu, {
+    "aria-label": overflowAriaLabel,
+    className: cx(blockClass, className),
+    direction: "bottom",
+    flipped: true,
+    iconDescription: overflowAriaLabel // also needs setting to avoid a11y "Accessible name does not match or contain the visible label text"
+    ,
+    menuOptionsClass: cx(`${blockClass}__options`, menuOptionsClass)
+  }, React.Children.map(overflowItems, (item, index) => {
+    // This uses a copy of a menu item option
+    // NOTE: Cannot use a real Tooltip icon below as it uses a <button /> the
+    // div equivalent below is based on Carbon 10.25.0
+    const ItemIcon = item?.props.renderIcon;
+    return /*#__PURE__*/React.createElement(react.OverflowMenuItem, {
+      className: `${blockClass}__item`,
+      onClick: item?.props.onClick,
+      itemText: /*#__PURE__*/React.createElement("div", {
+        className: `${blockClass}__item-content`,
+        "aria-describedby": `${internalId.current}-${index}--item-label`
+      }, /*#__PURE__*/React.createElement("span", {
+        className: `${blockClass}__item-label`,
+        id: `${internalId.current}-${index}--item-label`
+      }, item?.props.label), typeof item?.props.renderIcon === 'function' ? /*#__PURE__*/React.createElement(ItemIcon, null) : item?.props.renderIcon)
+    });
+  })));
+};
+ActionBarOverflowItems.displayName = componentName;
+ActionBarOverflowItems.propTypes = {
+  // expects action bar item as array or in fragment,
+  /**
+   * className
+   */
+  className: index.default.string,
+  /**
+   * class name applied to the overflow options
+   */
+  menuOptionsClass: index.default.string,
+  /**
+   * overflowAriaLabel label for open close button overflow used for action bar items that do nto fit.
+   */
+  overflowAriaLabel: index.default.string,
+  /**
+   * overflowItems: items to bre shown in the ActionBar overflow menu
+   */
+  overflowItems: index.default.arrayOf(index.default.element),
+  /**
+   * overflowMenuRef for the overflow menu width that is needed to calculate the width of the action bar with overflow
+   */
+  /**@ts-ignore */
+  overflowMenuRef: index.default.oneOfType([index.default.shape({
+    current: index.default.elementType
+  }), index.default.object, index.default.func]),
+  /**
+   * Optional tab index
+   */
+  tabIndex: index.default.number
+};
+
+exports.ActionBarOverflowItems = ActionBarOverflowItems;

package/lib/components/ActionBar/index.d.ts

@@ -0,0 +1,2 @@
+export { ActionBar } from "./ActionBar";
+export { ActionBarItem } from "./ActionBarItem";

package/lib/components/ActionSet/ActionSet.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright IBM Corp. 2021, 2024
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import { ButtonProps } from '@carbon/react';
+export declare const ButtonSizes: readonly ["sm", "md", "lg", "xl", "2xl"];
+export type ButtonSize = (typeof ButtonSizes)[number];
+export interface ActionSetProps {
+    /**
+     * The action buttons to show. Each action is specified as an object
+     * representation of a Carbon button.
+     *
+     * See https://react.carbondesignsystem.com/?path=/docs/components-button--default#component-api
+     */
+    actions: ButtonProps<React.ElementType>[];
+    /**
+     * The size of buttons to use for the actions. The allowed values are
+     * those for the size prop of carbon Button. If this prop is specified, all
+     * the buttons will be set to this size, overriding any 'size' values (if any)
+     * supplied in the actions array (if any).
+     */
+    buttonSize?: ButtonSize;
+    /**
+     * An optional class or classes to be added to the outermost element.
+     */
+    className?: string;
+    /**
+     * The size of the action set. Different button arrangements are used at
+     * different sizes, to make best use of the available space.
+     */
+    size?: ButtonSize;
+}
+export declare const validateActionSetProps: ({ actions, size }: {
+    actions: any;
+    size: any;
+}) => any;
+/**
+ * An ActionSet presents a set of action buttons, constructed from bundles
+ * of prop values and applying some layout rules. When the size is 'sm'
+ * the buttons are stacked, and should only include primary and secondary
+ * kinds. When the size is 'md' the buttons are stacked if there are three or
+ * more. When the size is 'md' or 'lg', two buttons share the horizontal space.
+ * When the size is 'lg', three or more buttons use a quarter of the available
+ * horizontal space, and if the size is 'xlg' or 'max' the buttons always use
+ * a quarter of the available horizontal space. If there is a ghost button,
+ * it appears at the left side. If there is a primary button it appears at the
+ * right.
+ */
+export declare const ActionSet: React.ForwardRefExoticComponent<ActionSetProps & React.RefAttributes<HTMLDivElement>>;