carbon-react 104.33.1 → 104.35.0

package/esm/components/action-popover/action-popover-menu/action-popover-menu.component.js

@@ -0,0 +1,154 @@
+function _extends() { _extends = Object.assign || function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
+
+import React, { useCallback, useMemo, useContext } from "react";
+import PropTypes from "prop-types";
+import { Menu } from "../action-popover.style";
+import Events from "../../../__internal__/utils/helpers/events";
+import ActionPopoverItem from "../action-popover-item/action-popover-item.component";
+import ActionPopoverDivider from "../action-popover-divider/action-popover-divider.component";
+import ActionPopoverContext from "../action-popover-context";
+const ActionPopoverMenu = /*#__PURE__*/React.forwardRef(({
+  parentID,
+  children,
+  focusIndex,
+  isOpen,
+  menuID,
+  onClick,
+  setOpen,
+  setFocusIndex,
+  placement = "bottom",
+  horizontalAlignment,
+  ...rest
+}, ref) => {
+  const {
+    focusButton
+  } = useContext(ActionPopoverContext);
+  const items = useMemo(() => React.Children.toArray(children).filter(child => child && child.type === ActionPopoverItem), [children]);
+  const onKeyDown = useCallback(e => {
+    if (Events.isTabKey(e)) {
+      e.preventDefault(); // TAB: close menu and allow focus to change to next focusable element
+
+      focusButton();
+      setOpen(false);
+    } else if (Events.isDownKey(e)) {
+      // DOWN: focus next item or first
+      e.preventDefault();
+      e.stopPropagation();
+      const indexValue = focusIndex < items.length - 1 ? focusIndex + 1 : 0;
+      setFocusIndex(indexValue);
+    } else if (Events.isUpKey(e)) {
+      // UP: focus previous item or last
+      e.preventDefault();
+      e.stopPropagation();
+      const indexValue = focusIndex > 0 ? focusIndex - 1 : items.length - 1;
+      setFocusIndex(indexValue);
+    } else if (Events.isHomeKey(e)) {
+      // HOME: focus first item
+      e.preventDefault();
+      e.stopPropagation();
+      setFocusIndex(0);
+    } else if (Events.isEndKey(e)) {
+      // END: focus last item
+      e.preventDefault();
+      e.stopPropagation();
+      setFocusIndex(items.length - 1);
+    } else if (Events.isAlphabetKey(e)) {
+      // A-Za-z: focus the next item on the list that starts with the pressed key
+      // selection should wrap to the start of the list
+      e.stopPropagation();
+      let firstMatch;
+      let nextMatch;
+      React.Children.forEach(items, ({
+        props: {
+          children: text
+        }
+      }, index) => {
+        if (text && text.toLowerCase().startsWith(e.key.toLowerCase())) {
+          if (firstMatch === undefined) {
+            firstMatch = index;
+          }
+
+          if (index > focusIndex && nextMatch === undefined) {
+            nextMatch = index;
+          }
+        }
+      });
+
+      if (nextMatch !== undefined) {
+        setFocusIndex(nextMatch);
+      } else if (firstMatch !== undefined) {
+        setFocusIndex(firstMatch);
+      }
+    }
+  }, [focusButton, setOpen, focusIndex, items, setFocusIndex]);
+  const clonedChildren = useMemo(() => {
+    let index = 0;
+    return React.Children.map(children, child => {
+      if (child && child.type === ActionPopoverItem) {
+        index += 1;
+        return /*#__PURE__*/React.cloneElement(child, {
+          focusItem: isOpen && focusIndex === index - 1,
+          placement: child.props.submenu ? placement : undefined,
+          horizontalAlignment
+        });
+      }
+
+      return child;
+    });
+  }, [children, focusIndex, isOpen, placement, horizontalAlignment]);
+  return /*#__PURE__*/React.createElement(Menu, _extends({
+    "data-component": "action-popover",
+    isOpen: isOpen,
+    onKeyDown: onKeyDown,
+    id: menuID,
+    "aria-labelledby": parentID,
+    role: "menu",
+    ref: ref
+  }, rest), clonedChildren);
+});
+ActionPopoverMenu.propTypes = {
+  /** Unique ID for the menu's parent */
+  parentID: PropTypes.string,
+
+  /** Children for the menu */
+  children(props, propName, componentName) {
+    let error;
+    const prop = props[propName];
+    React.Children.forEach(prop, child => {
+      if (child === null) {
+        return;
+      }
+
+      if (![ActionPopoverItem.displayName, ActionPopoverDivider.displayName].includes(child.type.displayName)) {
+        error = new Error(`\`${componentName}\` only accepts children of type \`${ActionPopoverItem.displayName}\`` + ` and \`${ActionPopoverDivider.displayName}\`.`);
+      }
+    });
+    return error;
+  },
+
+  /** Index to control which item is focused */
+  focusIndex: PropTypes.number,
+
+  /** A unique ID for the menu */
+  menuID: PropTypes.string,
+
+  /** Flag to indicate whether a menu should open */
+  isOpen: PropTypes.bool,
+
+  /** Callback to set the index of the focused item */
+  setFocusIndex: PropTypes.func,
+
+  /** Callback to set the isOpen flag */
+  setOpen: PropTypes.func,
+
+  /** Callback called on click event */
+  onClick: PropTypes.func,
+
+  /** @ignore @private */
+  placement: PropTypes.oneOf(["bottom", "top"]),
+
+  /** @ignore @private */
+  horizontalAlignment: PropTypes.oneOf(["left", "right"])
+};
+ActionPopoverMenu.displayName = "ActionPopoverMenu";
+export default ActionPopoverMenu;

package/esm/components/action-popover/action-popover-menu/action-popover-menu.d.ts

@@ -0,0 +1,33 @@
+import * as React from "react";
+import ActionPopoverDivider from "../action-popover-divider/action-popover-divider";
+import { ActionPopoverItemProps } from "../action-popover-item/action-popover-item";
+
+type ActionPopoverChild =
+  | React.ReactElement<ActionPopoverItemProps>
+  | typeof ActionPopoverDivider
+  | boolean
+  | null
+  | undefined;
+
+export interface ActionPopoverMenuProps {
+  /** Children for the menu */
+  children?: ActionPopoverChild | ActionPopoverChild[];
+  /** Index to control which item is focused */
+  focusIndex?: number;
+  /** Flag to indicate whether a menu should open */
+  isOpen?: boolean;
+  /** A unique ID for the menu */
+  menuID?: string;
+  /** Callback to set the index of the focused item */
+  setFocusIndex?: (args: number) => any;
+  /** Callback to set the isOpen flag */
+  setOpen?: (args: boolean) => any;
+  /** Unique ID for the menu's parent */
+  parentID?: string;
+}
+
+declare function ActionPopoverMenu(
+  props: ActionPopoverMenuProps & React.RefAttributes<HTMLDivElement>
+): JSX.Element;
+
+export default ActionPopoverMenu;

package/esm/components/action-popover/action-popover-menu-button/action-popover-menu-button.component.d.ts

@@ -0,0 +1,19 @@
+export default ActionPopoverMenuButton;
+declare function ActionPopoverMenuButton({ buttonType, iconType, iconPosition, size, children, ...props }: {
+    [x: string]: any;
+    buttonType: any;
+    iconType: any;
+    iconPosition: any;
+    size: any;
+    children: any;
+}): JSX.Element;
+declare namespace ActionPopoverMenuButton {
+    namespace propTypes {
+        const buttonType: PropTypes.Requireable<string>;
+        const iconType: PropTypes.Requireable<string>;
+        const iconPosition: PropTypes.Requireable<string>;
+        const size: PropTypes.Requireable<string>;
+        const children: PropTypes.Requireable<string>;
+    }
+}
+import PropTypes from "prop-types";

package/esm/components/action-popover/action-popover-menu-button/action-popover-menu-button.component.js

@@ -0,0 +1,29 @@
+function _extends() { _extends = Object.assign || function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
+
+import React from "react";
+import PropTypes from "prop-types";
+import { MenuButtonOverrideWrapper } from "../action-popover.style";
+import Button from "../../button";
+
+const ActionPopoverMenuButton = ({
+  buttonType,
+  iconType,
+  iconPosition,
+  size,
+  children,
+  ...props
+}) => /*#__PURE__*/React.createElement(MenuButtonOverrideWrapper, null, /*#__PURE__*/React.createElement(Button, _extends({
+  buttonType: buttonType,
+  iconType: iconType,
+  iconPosition: iconPosition,
+  size: size
+}, props), children));
+
+ActionPopoverMenuButton.propTypes = {
+  buttonType: PropTypes.string,
+  iconType: PropTypes.string,
+  iconPosition: PropTypes.string,
+  size: PropTypes.string,
+  children: PropTypes.string
+};
+export default ActionPopoverMenuButton;

package/esm/components/action-popover/action-popover-menu-button/action-popover-menu-button.d.ts

@@ -0,0 +1,13 @@
+export interface ActionPopoverMenuButtonProps {
+  children?: string;
+  buttonType?: string;
+  iconType?: string;
+  iconPosition?: string;
+  size?: string;
+}
+
+declare function ActionPopoverMenuButton(
+  props: ActionPopoverMenuButtonProps
+): JSX.Element;
+
+export default ActionPopoverMenuButton;

package/esm/components/action-popover/action-popover.component.d.ts

@@ -0,0 +1,38 @@
+export default ActionPopover;
+declare function ActionPopover({ children, id, onOpen, onClose, rightAlignMenu, renderButton, placement, horizontalAlignment, ...rest }: {
+    [x: string]: any;
+    children: any;
+    id: any;
+    onOpen: any;
+    onClose: any;
+    rightAlignMenu: any;
+    renderButton: any;
+    placement?: string | undefined;
+    horizontalAlignment: any;
+}): JSX.Element;
+declare namespace ActionPopover {
+    namespace propTypes {
+        const id: PropTypes.Requireable<string>;
+        const onOpen: PropTypes.Requireable<(...args: any[]) => any>;
+        const onClose: PropTypes.Requireable<(...args: any[]) => any>;
+        const rightAlignMenu: PropTypes.Requireable<boolean>;
+        /** Children for popover component */
+        function children(props: any, propName: any, componentName: any): undefined;
+        /** Children for popover component */
+        function children(props: any, propName: any, componentName: any): undefined;
+        const renderButton: PropTypes.Requireable<(...args: any[]) => any>;
+        const horizontalAlignment: PropTypes.Requireable<string>;
+        const placement: PropTypes.Requireable<string>;
+    }
+    namespace defaultProps {
+        const id_1: null;
+        export { id_1 as id };
+        export { onOpen };
+        export { onClose };
+        const horizontalAlignment_1: string;
+        export { horizontalAlignment_1 as horizontalAlignment };
+    }
+}
+import PropTypes from "prop-types";
+declare function onOpen_1(): void;
+declare function onClose_1(): void;

package/esm/components/action-popover/action-popover.component.js

@@ -0,0 +1,227 @@
+function _extends() { _extends = Object.assign || function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
+
+import React, { useState, useCallback, useMemo, useEffect, useRef } from "react";
+import PropTypes from "prop-types";
+import styledSystemPropTypes from "@styled-system/prop-types";
+import { MenuButton, ButtonIcon, StyledButtonIcon } from "./action-popover.style";
+import Events from "../../__internal__/utils/helpers/events";
+import { filterStyledSystemMarginProps } from "../../style/utils";
+import Popover from "../../__internal__/popover";
+import createGuid from "../../__internal__/utils/helpers/guid";
+import useLocale from "../../hooks/__internal__/useLocale";
+import ActionPopoverMenu from "./action-popover-menu/action-popover-menu.component";
+import ActionPopoverItem from "./action-popover-item/action-popover-item.component";
+import ActionPopoverDivider from "./action-popover-divider/action-popover-divider.component";
+import ActionPopoverContext from "./action-popover-context";
+const marginPropTypes = filterStyledSystemMarginProps(styledSystemPropTypes.space);
+
+const ActionPopover = ({
+  children,
+  id,
+  onOpen,
+  onClose,
+  rightAlignMenu,
+  renderButton,
+  placement = "bottom",
+  horizontalAlignment,
+  ...rest
+}) => {
+  const l = useLocale();
+  const [isOpen, setOpenState] = useState(false);
+  const [focusIndex, setFocusIndex] = useState(0);
+  const [guid] = useState(createGuid());
+  const buttonRef = useRef();
+  const menu = useRef();
+  const itemCount = useMemo(() => {
+    return React.Children.toArray(children).filter(child => child.type === ActionPopoverItem).length;
+  }, [children]);
+  const mappedPlacement = useMemo(() => {
+    if (placement === "top" && !rightAlignMenu) {
+      return "top-end";
+    }
+
+    if (placement === "top" && rightAlignMenu) {
+      return "top-start";
+    }
+
+    if (placement === "bottom" && rightAlignMenu) {
+      return "bottom-start";
+    }
+
+    return "bottom-end";
+  }, [placement, rightAlignMenu]);
+  const setOpen = useCallback(value => {
+    if (value && !isOpen) {
+      onOpen();
+    }
+
+    if (!value && isOpen) {
+      onClose();
+    }
+
+    setOpenState(value);
+  }, [isOpen, onOpen, onClose]);
+  const onButtonClick = useCallback(e => {
+    e.stopPropagation();
+    const isOpening = !isOpen;
+    setOpen(isOpening);
+
+    if (!isOpening) {
+      // Closing the menu should focus the MenuButton
+      buttonRef.current.querySelector("[data-component='action-popover-button']").focus();
+    }
+  }, [isOpen, setOpen]); // Keyboard commands implemented as recommended by WAI-ARIA best practices
+  // https://www.w3.org/TR/wai-aria-practices/examples/menu-button/menu-button-actions.html
+
+  const onButtonKeyDown = useCallback(e => {
+    if (Events.isSpaceKey(e) || Events.isDownKey(e) || Events.isEnterKey(e)) {
+      e.preventDefault();
+      e.stopPropagation();
+      setFocusIndex(0);
+      setOpen(true);
+    } else if (Events.isUpKey(e)) {
+      e.preventDefault();
+      e.stopPropagation();
+      setFocusIndex(itemCount - 1);
+      setOpen(true);
+    }
+  }, [itemCount, setOpen]);
+  const focusButton = useCallback(() => buttonRef.current.querySelector("[data-component='action-popover-button']").focus(), []);
+  useEffect(() => {
+    const handler = ({
+      target
+    }) => {
+      // If the event didn't came from part of this component, close the menu.
+      // There will be multiple document click listeners but we cant prevent propagation because it will interfere with
+      // other instances on the same page
+      if (!buttonRef.current.contains(target) && menu.current && !menu.current.contains(target)) {
+        setOpen(false);
+      }
+    };
+
+    const event = "click";
+    document.addEventListener(event, handler, {
+      capture: true
+    });
+    return function cleanup() {
+      document.removeEventListener(event, handler, {
+        capture: true
+      });
+    };
+  }, [setOpen]);
+
+  const menuButton = menuID => {
+    if (renderButton) {
+      return renderButton({
+        tabIndex: isOpen ? "-1" : "0",
+        "data-component": "action-popover-button",
+        ariaAttributes: {
+          "aria-haspopup": "true",
+          "aria-label": l.actionPopover.ariaLabel(),
+          "aria-controls": menuID,
+          "aria-expanded": isOpen
+        }
+      });
+    }
+
+    return /*#__PURE__*/React.createElement(StyledButtonIcon, {
+      role: "button",
+      "aria-haspopup": "true",
+      "aria-label": l.actionPopover.ariaLabel(),
+      "aria-controls": menuID,
+      "aria-expanded": isOpen,
+      tabIndex: isOpen ? "-1" : "0",
+      "data-component": "action-popover-button"
+    }, /*#__PURE__*/React.createElement(ButtonIcon, {
+      type: "ellipsis_vertical"
+    }));
+  };
+
+  const parentID = id || `ActionPopoverButton_${guid}`;
+  const menuID = `ActionPopoverMenu_${guid}`;
+  const menuProps = {
+    buttonRef,
+    parentID,
+    setFocusIndex,
+    focusIndex,
+    menuID,
+    isOpen,
+    setOpen,
+    rightAlignMenu,
+    placement,
+    horizontalAlignment
+  };
+  return /*#__PURE__*/React.createElement(MenuButton, _extends({
+    id: parentID,
+    "data-component": "action-popover-wrapper",
+    onKeyDown: onButtonKeyDown,
+    onClick: onButtonClick,
+    isOpen,
+    ref: buttonRef
+  }, rest), menuButton(menuID), /*#__PURE__*/React.createElement(ActionPopoverContext.Provider, {
+    value: {
+      setOpenPopover: setOpen,
+      focusButton,
+      isOpenPopover: isOpen
+    }
+  }, isOpen && /*#__PURE__*/React.createElement(Popover, {
+    placement: mappedPlacement,
+    reference: buttonRef
+  }, /*#__PURE__*/React.createElement(ActionPopoverMenu, _extends({
+    "data-component": "action-popover",
+    role: "menu",
+    ref: menu
+  }, menuProps), children))));
+};
+
+ActionPopover.propTypes = { ...marginPropTypes,
+
+  /** Unique ID */
+  id: PropTypes.string,
+
+  /** Callback to be called on menu open */
+  onOpen: PropTypes.func,
+
+  /** Callback to be called on menu close */
+  onClose: PropTypes.func,
+
+  /** Boolean to control whether menu should align to right */
+  rightAlignMenu: PropTypes.bool,
+
+  /** Children for popover component */
+  children(props, propName, componentName) {
+    let error;
+    const prop = props[propName];
+    React.Children.forEach(prop, child => {
+      if (child === null) {
+        return;
+      }
+
+      if (![ActionPopoverItem.displayName, ActionPopoverDivider.displayName].includes(child.type.displayName)) {
+        error = new Error(`\`${componentName}\` only accepts children of type \`${ActionPopoverItem.displayName}\`` + ` and \`${ActionPopoverDivider.displayName}\`.`);
+      }
+    });
+    return error;
+  },
+
+  /** Render a custom menu button to override default ellipsis icon */
+  renderButton: PropTypes.func,
+
+  /** Horizontal alignment of menu items content */
+  horizontalAlignment: PropTypes.oneOf(["left", "right"]),
+
+  /** Set whether the menu should open above or below the button */
+  placement: PropTypes.oneOf(["top", "bottom"])
+};
+
+const onOpen = () => {};
+
+const onClose = () => {};
+
+ActionPopover.defaultProps = {
+  id: null,
+  onOpen,
+  onClose,
+  horizontalAlignment: "left"
+};
+export default ActionPopover;

package/esm/components/action-popover/action-popover.d.ts

@@ -0,0 +1,39 @@
+import * as React from "react";
+import { MarginProps } from "styled-system";
+import ActionPopoverDivider from "./action-popover-divider/action-popover-divider";
+import { ActionPopoverItemProps } from "./action-popover-item/action-popover-item";
+
+export interface RenderButtonProps {
+  tabIndex: number;
+  "data-element": string;
+}
+
+type ActionPopoverChild =
+  | React.ReactElement<ActionPopoverItemProps>
+  | typeof ActionPopoverDivider
+  | boolean
+  | null
+  | undefined;
+
+export interface ActionPopoverProps extends MarginProps {
+  /** Children for popover component */
+  children?: ActionPopoverChild | ActionPopoverChild[];
+  /** Horizontal alignment of menu items content */
+  horizontalAlignment?: "left" | "right";
+  /** Unique ID */
+  id?: string;
+  /** Callback to be called on menu open */
+  onOpen?: () => void;
+  /** Callback to be called on menu close */
+  onClose?: () => void;
+  /** Set whether the menu should open above or below the button */
+  placement?: "bottom" | "top";
+  /** Render a custom menu button to override default ellipsis icon */
+  renderButton?: (buttonProps: RenderButtonProps) => React.ReactNode;
+  /** Boolean to control whether menu should align to right */
+  rightAlignMenu?: boolean;
+}
+
+declare function ActionPopover(props: ActionPopoverProps): JSX.Element;
+
+export default ActionPopover;

package/esm/components/action-popover/action-popover.style.d.ts

@@ -0,0 +1,13 @@
+export const Menu: import("styled-components").StyledComponent<"div", any, {}, never>;
+export function MenuItemFactory(button: any): import("styled-components").StyledComponent<any, any, object, string | number | symbol>;
+export const MenuButton: import("styled-components").StyledComponent<"div", any, {}, never>;
+export const ButtonIcon: import("styled-components").StyledComponent<typeof Icon, any, {}, never>;
+export const StyledButtonIcon: import("styled-components").StyledComponent<"div", any, {}, never>;
+export const MenuItemIcon: import("styled-components").StyledComponent<typeof Icon, any, {}, never>;
+export const MenuItemDivider: import("styled-components").StyledComponent<"div", any, {
+    "data-element": string;
+}, "data-element">;
+export const SubMenuItemIcon: import("styled-components").StyledComponent<typeof Icon, any, {}, never>;
+export const MenuButtonOverrideWrapper: import("styled-components").StyledComponent<"div", any, {}, never>;
+export const StyledMenuItem: import("styled-components").StyledComponent<"div", any, {}, never>;
+import Icon from "../icon";