@canonical/react-components 1.6.0 → 1.7.0

package/dist/esm/components/ContextualMenu/ContextualMenu.d.ts

@@ -0,0 +1,110 @@
+import React from "react";
+import type { HTMLProps, ReactNode } from "react";
+import type { ButtonProps } from "../Button";
+import type { ContextualMenuDropdownProps } from "./ContextualMenuDropdown";
+import type { MenuLink, Position } from "./ContextualMenuDropdown";
+import { ClassName, ExclusiveProps, PropsWithSpread, SubComponentProps } from "../../types";
+export declare enum Label {
+    Toggle = "Toggle menu"
+}
+export type BaseProps<L> = PropsWithSpread<{
+    /**
+     * Whether the menu should adjust its horizontal position to fit on the screen.
+     */
+    autoAdjust?: boolean;
+    /**
+     * The menu content (if the links prop is not supplied).
+     */
+    children?: ContextualMenuDropdownProps["dropdownContent"];
+    /**
+     * An optional class to apply to the wrapping element.
+     */
+    className?: ClassName;
+    /**
+     * Whether the menu should close when the escape key is pressed.
+     */
+    closeOnEsc?: boolean;
+    /**
+     * Whether the menu should close when clicking outside the menu.
+     */
+    closeOnOutsideClick?: boolean;
+    /**
+     * Whether the menu's width should match the toggle's width.
+     */
+    constrainPanelWidth?: boolean;
+    /**
+     * An optional class to apply to the dropdown.
+     */
+    dropdownClassName?: string | null;
+    /**
+     * Additional props to pass to the dropdown.
+     */
+    dropdownProps?: SubComponentProps<ContextualMenuDropdownProps>;
+    /**
+     * A list of links to display in the menu (if the children prop is not supplied.)
+     */
+    links?: MenuLink<L>[] | null;
+    /**
+     * A function to call when the menu is toggled.
+     */
+    onToggleMenu?: (isOpen: boolean) => void | null;
+    /**
+     * The horizontal position of the menu.
+     */
+    position?: Position | null;
+    /**
+     * An element to make the menu relative to.
+     */
+    positionNode?: HTMLElement | null;
+    /**
+     * Whether the dropdown should scroll if it is too long to fit on the screen.
+     */
+    scrollOverflow?: boolean;
+    /**
+     * Whether the menu should be visible.
+     */
+    visible?: boolean;
+}, HTMLProps<HTMLSpanElement>>;
+/**
+ * The props for the ContextualMenu component.
+ * @template L - The type of the link props.
+ */
+export type Props<L> = BaseProps<L> & ExclusiveProps<{
+    /**
+     * Whether the toggle should display a chevron icon.
+     */
+    hasToggleIcon?: boolean;
+    /**
+     * The appearance of the toggle button.
+     */
+    toggleAppearance?: ButtonProps["appearance"] | null;
+    /**
+     * A class to apply to the toggle button.
+     */
+    toggleClassName?: string | null;
+    /**
+     * Whether the toggle button should be disabled.
+     */
+    toggleDisabled?: boolean;
+    /**
+     * The toggle button's label.
+     */
+    toggleLabel?: React.ReactNode | null;
+    /**
+     * Whether the toggle lable or icon should appear first.
+     */
+    toggleLabelFirst?: boolean;
+    /**
+     * Additional props to pass to the toggle button.
+     */
+    toggleProps?: SubComponentProps<ButtonProps>;
+}, {
+    toggle: ReactNode;
+}>;
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Contextual menu](https://docs.vanillaframework.io/patterns//contextual-menu/).
+ *
+ * A contextual menu can be used in conjunction with any page element to provide a contextual menu.
+ */
+declare const ContextualMenu: <L>({ autoAdjust, children, className, closeOnEsc, closeOnOutsideClick, constrainPanelWidth, dropdownClassName, dropdownProps, hasToggleIcon, links, onToggleMenu, position, positionNode, scrollOverflow, toggle, toggleAppearance, toggleClassName, toggleDisabled, toggleLabel, toggleLabelFirst, toggleProps, visible, ...wrapperProps }: Props<L>) => JSX.Element;
+export default ContextualMenu;

package/dist/esm/components/ContextualMenu/ContextualMenu.js

@@ -0,0 +1,215 @@
+var _excluded = ["autoAdjust", "children", "className", "closeOnEsc", "closeOnOutsideClick", "constrainPanelWidth", "dropdownClassName", "dropdownProps", "hasToggleIcon", "links", "onToggleMenu", "position", "positionNode", "scrollOverflow", "toggle", "toggleAppearance", "toggleClassName", "toggleDisabled", "toggleLabel", "toggleLabelFirst", "toggleProps", "visible"];
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+function _objectWithoutProperties(e, t) { if (null == e) return {}; var o, r, i = _objectWithoutPropertiesLoose(e, t); if (Object.getOwnPropertySymbols) { var n = Object.getOwnPropertySymbols(e); for (r = 0; r < n.length; r++) o = n[r], t.indexOf(o) >= 0 || {}.propertyIsEnumerable.call(e, o) && (i[o] = e[o]); } return i; }
+function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (e.indexOf(n) >= 0) continue; t[n] = r[n]; } return t; }
+import classNames from "classnames";
+import React, { useCallback, useEffect, useId, useRef, useState } from "react";
+import usePortal from "react-useportal";
+import { useListener, usePrevious } from "../../hooks";
+import Button from "../Button";
+import ContextualMenuDropdown from "./ContextualMenuDropdown";
+export var Label = /*#__PURE__*/function (Label) {
+  Label["Toggle"] = "Toggle menu";
+  return Label;
+}({});
+
+/**
+ * The props for the ContextualMenu component.
+ * @template L - The type of the link props.
+ */
+
+/**
+ * Get the node to use for positioning the menu.
+ * @param wrapper - The component's wrapping element.
+ * @param positionNode - A positioning node, if supplied.
+ * @return A node or null.
+ */
+var getPositionNode = (wrapper, positionNode) => {
+  if (positionNode) {
+    return positionNode;
+  } else if (wrapper) {
+    // We want to position the menu in relation to the toggle, if it exists.
+    var toggle = wrapper.querySelector(".p-contextual-menu__toggle");
+    return toggle || wrapper;
+  }
+  return null;
+};
+
+/**
+ * Whether the positioning node is visible.
+ * @param positionNode - The node that is used to position the menu.
+ * @return Whether the positioning node is visible.
+ */
+var getPositionNodeVisible = positionNode => {
+  return !positionNode || positionNode.offsetParent !== null;
+};
+
+/**
+ * This is a [React](https://reactjs.org/) component for the Vanilla [Contextual menu](https://docs.vanillaframework.io/patterns//contextual-menu/).
+ *
+ * A contextual menu can be used in conjunction with any page element to provide a contextual menu.
+ */
+var ContextualMenu = _ref => {
+  var {
+      autoAdjust = true,
+      children,
+      className,
+      closeOnEsc = true,
+      closeOnOutsideClick = true,
+      constrainPanelWidth,
+      dropdownClassName,
+      dropdownProps,
+      hasToggleIcon,
+      links,
+      onToggleMenu,
+      position = "right",
+      positionNode,
+      scrollOverflow,
+      toggle,
+      toggleAppearance,
+      toggleClassName,
+      toggleDisabled,
+      toggleLabel,
+      toggleLabelFirst = true,
+      toggleProps,
+      visible = false
+    } = _ref,
+    wrapperProps = _objectWithoutProperties(_ref, _excluded);
+  var id = useId();
+  var wrapper = useRef(null);
+  var [positionCoords, setPositionCoords] = useState();
+  var [adjustedPosition, setAdjustedPosition] = useState(position);
+  useEffect(() => {
+    setAdjustedPosition(position);
+  }, [position, autoAdjust]);
+
+  // Update the coordinates of the position node.
+  var updatePositionCoords = useCallback(() => {
+    var parent = getPositionNode(wrapper.current, positionNode);
+    if (!parent) {
+      return null;
+    }
+    setPositionCoords(parent.getBoundingClientRect());
+  }, [wrapper, positionNode]);
+  var {
+    openPortal,
+    closePortal,
+    isOpen,
+    Portal
+  } = usePortal({
+    closeOnEsc,
+    closeOnOutsideClick,
+    isOpen: visible,
+    onOpen: () => {
+      // Call the toggle callback, if supplied.
+      onToggleMenu === null || onToggleMenu === void 0 || onToggleMenu(true);
+      // When the menu opens then update the coordinates of the parent.
+      updatePositionCoords();
+    },
+    onClose: () => {
+      // Call the toggle callback, if supplied.
+      onToggleMenu === null || onToggleMenu === void 0 || onToggleMenu(false);
+    },
+    programmaticallyOpen: true
+  });
+  var previousVisible = usePrevious(visible);
+  var labelNode = toggleLabel && typeof toggleLabel === "string" ? /*#__PURE__*/React.createElement("span", null, toggleLabel) : /*#__PURE__*/React.isValidElement(toggleLabel) ? toggleLabel : null;
+  var contextualMenuClassName = classNames(className, "p-contextual-menu", {
+    ["p-contextual-menu--".concat(adjustedPosition)]: adjustedPosition !== "right"
+  });
+
+  // Update the coordinates of the wrapper once it mounts to the dom. This uses
+  // The callback ref pattern:
+  // https://reactjs.org/docs/hooks-faq.html#how-can-i-measure-a-dom-node
+  var wrapperRef = useCallback(node => {
+    wrapper.current = node;
+    if (node !== null) {
+      updatePositionCoords();
+    }
+  }, [updatePositionCoords]);
+
+  // Handle controlling updates to the menu visibility from outside
+  // the component.
+  useEffect(() => {
+    if (visible !== previousVisible) {
+      if (visible && !isOpen) {
+        openPortal();
+      } else if (!visible && isOpen) {
+        closePortal();
+      }
+    }
+  }, [closePortal, openPortal, visible, isOpen, previousVisible]);
+  var onResize = useCallback(evt => {
+    var parent = getPositionNode(wrapper.current, positionNode);
+    if (parent && !getPositionNodeVisible(parent)) {
+      // Hide the menu if the item has become hidden. This might happen in
+      // a responsive table when columns become hidden as the page
+      // becomes smaller.
+      closePortal(evt);
+    } else {
+      // Update the coordinates so that the menu stays relative to the
+      // toggle button.
+      updatePositionCoords();
+    }
+  }, [closePortal, positionNode, updatePositionCoords]);
+  var onScroll = useCallback(e => {
+    var parent = getPositionNode(wrapper.current, positionNode);
+    // update position if the scroll event is triggered by the parent of the menu
+    if (parent && e.target.contains(parent)) {
+      // Update the coordinates so that the menu stays relative to the
+      // toggle button.
+      updatePositionCoords();
+    }
+  }, [positionNode, updatePositionCoords]);
+  useListener(window, onResize, "resize", true, isOpen);
+  useListener(window, onScroll, "scroll", false, isOpen, true);
+  var toggleNode = null;
+  if (toggle) {
+    toggleNode = toggle;
+  } else if (hasToggleIcon || toggleLabel) {
+    toggleNode = /*#__PURE__*/React.createElement(Button, _extends({
+      appearance: toggleAppearance,
+      "aria-controls": id,
+      "aria-expanded": isOpen ? "true" : "false",
+      "aria-label": toggleLabel ? null : Label.Toggle,
+      "aria-pressed": isOpen ? "true" : "false",
+      "aria-haspopup": "true",
+      className: classNames("p-contextual-menu__toggle", toggleClassName),
+      disabled: toggleDisabled,
+      hasIcon: hasToggleIcon,
+      onClick: evt => {
+        if (!isOpen) {
+          openPortal(evt);
+        } else {
+          closePortal(evt);
+        }
+      },
+      type: "button"
+    }, toggleProps), toggleLabelFirst ? labelNode : null, hasToggleIcon ? /*#__PURE__*/React.createElement("i", {
+      className: classNames("p-icon--chevron-down p-contextual-menu__indicator", {
+        "is-light": ["negative", "positive"].includes(toggleAppearance)
+      })
+    }) : null, toggleLabelFirst ? null : labelNode);
+  }
+  return /*#__PURE__*/React.createElement("span", _extends({
+    className: contextualMenuClassName,
+    ref: wrapperRef
+  }, wrapperProps), toggleNode, isOpen && /*#__PURE__*/React.createElement(Portal, null, /*#__PURE__*/React.createElement(ContextualMenuDropdown, _extends({
+    adjustedPosition: adjustedPosition,
+    autoAdjust: autoAdjust,
+    handleClose: closePortal,
+    constrainPanelWidth: constrainPanelWidth,
+    dropdownClassName: dropdownClassName,
+    dropdownContent: children,
+    id: id,
+    isOpen: isOpen,
+    links: links,
+    position: position,
+    positionCoords: positionCoords,
+    contextualMenuClassName: contextualMenuClassName,
+    positionNode: getPositionNode(wrapper.current),
+    scrollOverflow: scrollOverflow,
+    setAdjustedPosition: setAdjustedPosition
+  }, dropdownProps))));
+};
+export default ContextualMenu;

package/dist/esm/components/ContextualMenu/ContextualMenu.stories.d.ts

@@ -0,0 +1,13 @@
+import { Meta, StoryObj } from "@storybook/react";
+import ContextualMenu from "./ContextualMenu";
+declare const meta: Meta<typeof ContextualMenu>;
+export default meta;
+type Story = StoryObj<typeof ContextualMenu>;
+/**
+ * The contextual menu will provide a visual wrapper to any provided children. Visibility can be toggled via the `visible` prop.
+ */
+export declare const Default: Story;
+export declare const Toggle: Story;
+export declare const OverflowingContainer: Story;
+export declare const ChildFunction: Story;
+export declare const ChildElement: Story;

package/dist/esm/components/ContextualMenu/ContextualMenu.stories.js

@@ -0,0 +1,100 @@
+import React from "react";
+import Button from "../Button";
+import ContextualMenu from "./ContextualMenu";
+var ScrollTemplate = args => /*#__PURE__*/React.createElement("div", {
+  style: {
+    maxWidth: "30rem",
+    maxHeight: "10rem",
+    overflow: "auto",
+    padding: "1rem"
+  }
+}, /*#__PURE__*/React.createElement(ContextualMenu, args), Array(3).fill( /*#__PURE__*/React.createElement("p", null, "Lorem ipsum dolor sit amet, consectetur adipisicing elit. Consequuntur cum dicta beatae nostrum eligendi similique earum, dolorem fuga quis, sequi voluptates architecto ipsa dolorum eaque rem expedita inventore voluptas odit aspernatur alias molestias facere.")), /*#__PURE__*/React.createElement(ContextualMenu, args));
+var Template = args => /*#__PURE__*/React.createElement("div", {
+  className: "u-align--center"
+}, /*#__PURE__*/React.createElement(ContextualMenu, args));
+var meta = {
+  component: ContextualMenu,
+  render: Template,
+  tags: ["autodocs"],
+  argTypes: {
+    children: {
+      control: {
+        disable: true
+      }
+    },
+    links: {
+      control: {
+        disable: true
+      }
+    }
+  }
+};
+export default meta;
+/**
+ * The contextual menu will provide a visual wrapper to any provided children. Visibility can be toggled via the `visible` prop.
+ */
+export var Default = {
+  name: "Default",
+  args: {
+    children: /*#__PURE__*/React.createElement("span", {
+      style: {
+        padding: "1rem"
+      }
+    }, "This is a menu."),
+    closeOnOutsideClick: false,
+    constrainPanelWidth: false,
+    position: "left",
+    visible: true
+  }
+};
+export var Toggle = {
+  name: "Toggle",
+  args: {
+    links: [{
+      children: "Link 1",
+      onClick: () => {}
+    }, {
+      children: "Link 2",
+      onClick: () => {}
+    }],
+    hasToggleIcon: true,
+    position: "right",
+    toggleLabel: "Click me!"
+  }
+};
+export var OverflowingContainer = {
+  render: ScrollTemplate.bind({}),
+  name: "Overflowing container",
+  args: {
+    links: [{
+      children: "Link 1",
+      onClick: () => {}
+    }, {
+      children: "Long Link 2",
+      onClick: () => {}
+    }],
+    hasToggleIcon: true,
+    position: "right",
+    toggleLabel: "Click me!"
+  }
+};
+export var ChildFunction = {
+  name: "Child function",
+  args: {
+    children: close => /*#__PURE__*/React.createElement(Button, {
+      onClick: close
+    }, "child function"),
+    hasToggleIcon: true,
+    position: "right",
+    toggleLabel: "Click me!"
+  }
+};
+export var ChildElement = {
+  name: "Child element",
+  args: {
+    children: /*#__PURE__*/React.createElement(Button, null, "child element"),
+    hasToggleIcon: true,
+    position: "right",
+    toggleLabel: "Click me!"
+  }
+};

package/dist/esm/components/ContextualMenu/ContextualMenu.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/components/ContextualMenu/ContextualMenuDropdown/ContextualMenuDropdown.d.ts

@@ -0,0 +1,43 @@
+import { ReactElement } from "react";
+import type { HTMLProps, ReactNode } from "react";
+import type { ButtonProps } from "../../Button";
+import type { WindowFitment } from "../../../hooks";
+export declare enum Label {
+    Dropdown = "submenu"
+}
+/**
+ * The type of the menu links.
+ * @template L - The type of the link props.
+ */
+export type MenuLink<L = null> = string | ButtonProps<L> | ButtonProps<L>[];
+export type Position = "left" | "center" | "right";
+/**
+ * The props for the ContextualMenuDropdown component.
+ * @template L - The type of the link props.
+ */
+export type Props<L = null> = {
+    adjustedPosition?: Position;
+    autoAdjust?: boolean;
+    handleClose?: (evt?: MouseEvent) => void;
+    constrainPanelWidth?: boolean;
+    dropdownClassName?: string;
+    dropdownContent?: ReactNode | ((close: () => void) => ReactElement);
+    id?: string;
+    isOpen?: boolean;
+    links?: MenuLink<L>[];
+    position?: Position;
+    positionCoords?: DOMRect;
+    positionNode?: HTMLElement;
+    scrollOverflow?: boolean;
+    setAdjustedPosition?: (position: Position) => void;
+    contextualMenuClassName?: string;
+} & HTMLProps<HTMLSpanElement>;
+/**
+ * Calculate the adjusted position in relation to the window.
+ * @param position - The requested position.
+ * @param fitsWindow - The window fitment info.
+ * @return The new position.
+ */
+export declare const adjustForWindow: (position: Position, fitsWindow: WindowFitment) => Position;
+declare const ContextualMenuDropdown: <L>({ adjustedPosition, autoAdjust, handleClose, constrainPanelWidth, dropdownClassName, dropdownContent, id, isOpen, links, position, positionCoords, positionNode, scrollOverflow, setAdjustedPosition, contextualMenuClassName, ...props }: Props<L>) => JSX.Element;
+export default ContextualMenuDropdown;