@carbon-labs/react-ui-shell 0.25.0 → 0.26.0

package/lib/components/SideNavFlyoutMenu.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Copyright IBM Corp. 2016, 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.
+ */
+import PropTypes from 'prop-types';
+import React from 'react';
+import { PopoverAlignment } from '@carbon/react';
+import { type PolymorphicProps } from '../types/common';
+interface TooltipBaseProps {
+    /**
+     * Specify how the trigger should align with the tooltip
+     */
+    align?: PopoverAlignment;
+    /**
+     * Pass in the child to which the tooltip will be applied
+     */
+    children?: React.ReactElement;
+    /**
+     * Specify an optional className to be applied to the container node
+     */
+    className?: string;
+    /**
+     * Specify whether the tooltip should be open when it first renders
+     */
+    defaultOpen?: boolean;
+    /**
+     * Provide the description to be rendered inside of the Tooltip. The
+     * description will use `aria-describedby` and will describe the child node
+     * in addition to the text rendered inside of the child. This means that if you
+     * have text in the child node, that it will be announced alongside the
+     * description to the screen reader.
+     *
+     * Note: if label and description are both provided, label will be used and
+     * description will not be used
+     */
+    description?: React.ReactNode;
+    /**
+     * Specify whether a drop shadow should be rendered
+     */
+    dropShadow?: boolean;
+    /**
+     * Specify the duration in milliseconds to delay before displaying the tooltip
+     */
+    enterDelayMs?: number;
+    /**
+     * Provide the label to be rendered inside of the Tooltip. The label will use
+     * `aria-labelledby` and will fully describe the child node that is provided.
+     * This means that if you have text in the child node, that it will not be
+     * announced to the screen reader.
+     *
+     * Note: if label and description are both provided, description will not be
+     * used
+     */
+    label?: React.ReactNode;
+    /**
+     * Specify the duration in milliseconds to delay before hiding the tooltip
+     */
+    leaveDelayMs?: number;
+    /**
+     * The content to be rendered inside the popover menu.
+     */
+    menuContent?: React.ReactNode;
+    /**
+     *  The boolean to show the flyout menu has been selected.
+     */
+    selected?: boolean;
+    /**
+     *  The title for the overall menu name.
+     */
+    title?: string;
+}
+export type TooltipProps<T extends React.ElementType> = PolymorphicProps<T, TooltipBaseProps>;
+declare function SideNavFlyoutMenu<T extends React.ElementType>({ align, className: customClassName, children, label, description, enterDelayMs, leaveDelayMs, defaultOpen, dropShadow, highContrast, menuContent, selected, title, ...rest }: TooltipProps<T>): import("react/jsx-runtime").JSX.Element;
+declare namespace SideNavFlyoutMenu {
+    var propTypes: {
+        /**
+         * Specify how the trigger should align with the tooltip
+         */
+        align: PropTypes.Requireable<string>;
+        /**
+         * Pass in the child to which the tooltip will be applied
+         */
+        children: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        /**
+         * Specify an optional className to be applied to the container node
+         */
+        className: PropTypes.Requireable<string>;
+        /**
+         * Specify whether the tooltip should be open when it first renders
+         */
+        defaultOpen: PropTypes.Requireable<boolean>;
+        /**
+         * Provide the description to be rendered inside of the Tooltip. The
+         * description will use `aria-describedby` and will describe the child node
+         * in addition to the text rendered inside of the child. This means that if you
+         * have text in the child node, that it will be announced alongside the
+         * description to the screen reader.
+         *
+         * Note: if label and description are both provided, label will be used and
+         * description will not be used
+         */
+        description: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        /**
+         * Specify whether a drop shadow should be rendered
+         */
+        dropShadow: PropTypes.Requireable<boolean>;
+        /**
+         * Specify the duration in milliseconds to delay before displaying the tooltip
+         */
+        enterDelayMs: PropTypes.Requireable<number>;
+        /**
+         * Provide the label to be rendered inside of the Tooltip. The label will use
+         * `aria-labelledby` and will fully describe the child node that is provided.
+         * This means that if you have text in the child node, that it will not be
+         * announced to the screen reader.
+         *
+         * Note: if label and description are both provided, description will not be
+         * used
+         */
+        label: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        /**
+         * Specify the duration in milliseconds to delay before hiding the tooltip
+         */
+        leaveDelayMs: PropTypes.Requireable<number>;
+        /**
+         * The content to be rendered inside the popover menu.
+         */
+        menuContent: PropTypes.Requireable<PropTypes.ReactNodeLike>;
+        /**
+         *  The boolean to show the flyout menu has been selected.
+         */
+        selected: PropTypes.Requireable<boolean>;
+        /**
+         * The title for the overall menu name.
+         */
+        title: PropTypes.Requireable<string>;
+    };
+}
+export { SideNavFlyoutMenu };

package/lib/components/SideNavFlyoutMenu.js

@@ -0,0 +1,367 @@
+/**
+ * Copyright IBM Corp. 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.
+ */
+
+'use strict';
+
+var _rollupPluginBabelHelpers = require('../_virtual/_rollupPluginBabelHelpers.js');
+var index = require('../_virtual/index.js');
+var PropTypes = require('prop-types');
+var React = require('react');
+var react = require('@carbon/react');
+var keys = require('../internal/keyboard/keys.js');
+var match = require('../internal/keyboard/match.js');
+var useDelayedState = require('../internal/useDelayedState.js');
+var useId = require('../internal/useId.js');
+var usePrefix = require('../internal/usePrefix.js');
+
+/**
+ * Event types that trigger a "drag" to stop.
+ */
+const DRAG_STOP_EVENT_TYPES = new Set(['mouseup', 'touchend', 'touchcancel']);
+function SideNavFlyoutMenu(_ref) {
+  let {
+    align = 'right-start',
+    className: customClassName,
+    children,
+    label,
+    description,
+    enterDelayMs = 100,
+    leaveDelayMs = 300,
+    defaultOpen = false,
+    dropShadow = true,
+    highContrast = false,
+    menuContent,
+    selected = false,
+    title,
+    ...rest
+  } = _ref;
+  const popoverRef = React.useRef(null);
+  const [open, setOpen] = useDelayedState.useDelayedState(defaultOpen);
+  const [isDragging, setIsDragging] = React.useState(false);
+  const [focusByMouse, setFocusByMouse] = React.useState(false);
+  const [isPointerIntersecting, setIsPointerIntersecting] = React.useState(false);
+  const id = useId.useId('tooltip');
+  const prefix = usePrefix.usePrefix();
+  const child = React.Children.only(children);
+  const menuButton = React.useRef();
+  const [clickMode, setClickMode] = React.useState(false);
+  const isFocusedInsideRef = React.useRef(false);
+  const popoverMenuLinks = React.useRef(null);
+  const [isButtonFocused, setIsButtonFocused] = React.useState(false);
+  const flyoutMenuItems = React.Children.map(menuContent, child => {
+    if (/*#__PURE__*/React.isValidElement(child)) {
+      return /*#__PURE__*/React.cloneElement(child, {
+        ...{
+          isFlyoutMenuItem: true
+        }
+      });
+    }
+    return child;
+  });
+  const triggerProps = {
+    onFocus: () => {
+      if (!focusByMouse) {
+        setOpen(true);
+        setIsButtonFocused(true);
+        setClickMode(false);
+        isFocusedInsideRef.current = false;
+      }
+    },
+    onBlur: () => {
+      if (!isFocusedInsideRef.current && !focusByMouse) {
+        closeMenu();
+      }
+    },
+    onClick: () => {
+      setIsButtonFocused(false);
+      setClickMode(!clickMode);
+      setOpen(!clickMode);
+    },
+    // This should be placed on the trigger in case the element is disabled
+    onMouseEnter,
+    onMouseLeave,
+    onMouseDown,
+    onMouseMove: onMouseMove,
+    onTouchStart: onDragStart
+  };
+  function getChildEventHandlers(childProps) {
+    const eventHandlerFunctions = Object.keys(triggerProps).filter(prop => prop.startsWith('on'));
+    const eventHandlers = {};
+    eventHandlerFunctions.forEach(functionName => {
+      eventHandlers[functionName] = evt => {
+        triggerProps[functionName](evt);
+        if (childProps?.[functionName]) {
+          childProps?.[functionName](evt);
+        }
+      };
+    });
+    return eventHandlers;
+  }
+  if (label) {
+    triggerProps['aria-labelledby'] = id;
+  } else {
+    triggerProps['aria-describedby'] = id;
+  }
+  function onKeyDown(event) {
+    if (open && match.match(event, keys.Escape)) {
+      event.stopPropagation();
+      if (!isButtonFocused) {
+        closeMenu({
+          revertFocus: true
+        });
+      }
+      setOpen(!isButtonFocused);
+      setIsButtonFocused(!isButtonFocused);
+    }
+    if (match.match(event, keys.Enter) || match.match(event, keys.Space)) {
+      setIsButtonFocused(false);
+      setOpen(true);
+      setFocusByMouse(false);
+
+      // focus on the first link
+      if (popoverMenuLinks?.current && !isFocusedInsideRef.current) {
+        const firstLink = popoverMenuLinks?.current?.[0];
+        setContentTabIndex('0');
+        if (firstLink) {
+          isFocusedInsideRef.current = true;
+          // avoid race condition
+          setTimeout(() => firstLink.focus(), 0);
+        }
+      }
+    }
+  }
+  function onMouseEnter() {
+    if (!clickMode) {
+      if (!rest?.onMouseEnter) {
+        setIsPointerIntersecting(true);
+        setOpen(true, enterDelayMs);
+      }
+    }
+  }
+  function onMouseDown() {
+    setFocusByMouse(true);
+    onDragStart();
+  }
+  function onMouseLeave() {
+    if (!clickMode && !isFocusedInsideRef.current) {
+      setIsPointerIntersecting(false);
+      if (isDragging) {
+        return;
+      }
+      setIsButtonFocused(false);
+      setOpen(false, leaveDelayMs);
+    }
+  }
+  function onMouseMove(evt) {
+    if (evt.buttons === 1) {
+      setIsDragging(true);
+    } else {
+      setIsDragging(false);
+    }
+  }
+  function onDragStart() {
+    setIsDragging(true);
+  }
+  const onDragStop = React.useCallback(() => {
+    setIsDragging(false);
+    // Close the tooltip, unless the mouse pointer is within the bounds of the
+    // trigger.
+    if (!isPointerIntersecting) {
+      setIsButtonFocused(false);
+      setOpen(false, leaveDelayMs);
+    }
+  }, [isPointerIntersecting, leaveDelayMs, setOpen]);
+  React.useEffect(() => {
+    if (isDragging) {
+      // Register drag stop handlers.
+      DRAG_STOP_EVENT_TYPES.forEach(eventType => {
+        document.addEventListener(eventType, onDragStop);
+      });
+    }
+    return () => {
+      DRAG_STOP_EVENT_TYPES.forEach(eventType => {
+        document.removeEventListener(eventType, onDragStop);
+      });
+    };
+  }, [isDragging, onDragStop]);
+  const setContentTabIndex = value => {
+    if (popoverMenuLinks.current) {
+      popoverMenuLinks.current.forEach(e => e.setAttribute('tabindex', value));
+    }
+  };
+  function handleBlur(event) {
+    const isFocusOutside = !popoverRef.current?.contains(event.relatedTarget);
+
+    // tab outside the menu
+    if (open && isFocusedInsideRef.current && !focusByMouse && isFocusOutside) {
+      closeMenu();
+    }
+
+    // if button has been clicked, and new click is outside the menu
+    if (clickMode && isFocusOutside) {
+      closeMenu();
+    }
+  }
+  function closeMenu() {
+    let {
+      revertFocus = false
+    } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    if (revertFocus) {
+      menuButton.current?.focus();
+      setOpen(true);
+      setIsButtonFocused(true);
+    } else {
+      setOpen(false);
+      setIsButtonFocused(false);
+    }
+    isFocusedInsideRef.current = false;
+    setFocusByMouse(false);
+    setIsPointerIntersecting(!clickMode);
+    setClickMode(false);
+    setContentTabIndex('-1');
+  }
+
+  // initiate menu content to be untabbable
+  React.useEffect(() => {
+    if (popoverRef.current) {
+      popoverMenuLinks.current = popoverRef.current.querySelectorAll(`.${prefix}--side-nav-menu--popover-content a`);
+      setContentTabIndex('-1');
+      menuButton.current = popoverRef.current.querySelector(`.${prefix}--side-nav__submenu`);
+    }
+  }, []);
+
+  // set menu content to be untabbable
+  React.useEffect(() => {
+    if (popoverRef.current && !popoverMenuLinks.current) {
+      popoverMenuLinks.current = popoverRef.current.querySelectorAll(`.${prefix}--side-nav-menu--popover-content a`);
+      setContentTabIndex('-1');
+    }
+  }, [open]);
+  return (
+    /*#__PURE__*/
+    // @ts-ignore-error Popover throws a TS error everytime is imported
+    React.createElement(react.Popover, _rollupPluginBabelHelpers.extends({
+      ref: popoverRef
+    }, rest, {
+      align: isButtonFocused ? 'right' : align,
+      className: index.default(customClassName, {
+        [`${prefix}--flyout-menu`]: true,
+        [`${prefix}--flyout-menu-clicked`]: clickMode,
+        [`${prefix}--flyout-menu-selected`]: selected,
+        [`${prefix}--flyout-menu-focused`]: isButtonFocused || open
+      }),
+      dropShadow: dropShadow,
+      highContrast: false,
+      onBlur: handleBlur,
+      onKeyDown: onKeyDown,
+      onMouseLeave: onMouseLeave,
+      open: open
+    }), child !== undefined ? /*#__PURE__*/React.cloneElement(child, {
+      ...triggerProps,
+      ...getChildEventHandlers(child.props)
+    }) : null, /*#__PURE__*/React.createElement(react.PopoverContent, {
+      "aria-hidden": open ? 'false' : 'true',
+      className: index.default({
+        [`${prefix}--side-nav-menu--popover-content`]: !isButtonFocused,
+        [`${prefix}--flyout-tooltip-content ${prefix}--tooltip-content`]: isButtonFocused
+      }),
+      id: id,
+      onMouseEnter: onMouseEnter,
+      role: "tooltip"
+    }, !isButtonFocused ? /*#__PURE__*/React.createElement(react.FormLabel, null, title) : title, /*#__PURE__*/React.createElement("div", {
+      style: {
+        display: isButtonFocused ? 'none' : 'block'
+      }
+    }, flyoutMenuItems)))
+  );
+}
+SideNavFlyoutMenu.propTypes = {
+  /**
+   * Specify how the trigger should align with the tooltip
+   */
+  align: PropTypes.oneOf(['top', 'top-left',
+  // deprecated use top-start instead
+  'top-right',
+  // deprecated use top-end instead
+
+  'bottom', 'bottom-left',
+  // deprecated use bottom-start instead
+  'bottom-right',
+  // deprecated use bottom-end instead
+
+  'left', 'left-bottom',
+  // deprecated use left-end instead
+  'left-top',
+  // deprecated use left-start instead
+
+  'right', 'right-bottom',
+  // deprecated use right-end instead
+  'right-top',
+  // deprecated use right-start instead
+
+  // new values to match floating-ui
+  'top-start', 'top-end', 'bottom-start', 'bottom-end', 'left-end', 'left-start', 'right-end', 'right-start']),
+  /**
+   * Pass in the child to which the tooltip will be applied
+   */
+  children: PropTypes.node,
+  /**
+   * Specify an optional className to be applied to the container node
+   */
+  className: PropTypes.string,
+  /**
+   * Specify whether the tooltip should be open when it first renders
+   */
+  defaultOpen: PropTypes.bool,
+  /**
+   * Provide the description to be rendered inside of the Tooltip. The
+   * description will use `aria-describedby` and will describe the child node
+   * in addition to the text rendered inside of the child. This means that if you
+   * have text in the child node, that it will be announced alongside the
+   * description to the screen reader.
+   *
+   * Note: if label and description are both provided, label will be used and
+   * description will not be used
+   */
+  description: PropTypes.node,
+  /**
+   * Specify whether a drop shadow should be rendered
+   */
+  dropShadow: PropTypes.bool,
+  /**
+   * Specify the duration in milliseconds to delay before displaying the tooltip
+   */
+  enterDelayMs: PropTypes.number,
+  /**
+   * Provide the label to be rendered inside of the Tooltip. The label will use
+   * `aria-labelledby` and will fully describe the child node that is provided.
+   * This means that if you have text in the child node, that it will not be
+   * announced to the screen reader.
+   *
+   * Note: if label and description are both provided, description will not be
+   * used
+   */
+  label: PropTypes.node,
+  /**
+   * Specify the duration in milliseconds to delay before hiding the tooltip
+   */
+  leaveDelayMs: PropTypes.number,
+  /**
+   * The content to be rendered inside the popover menu.
+   */
+  menuContent: PropTypes.node,
+  /**
+   *  The boolean to show the flyout menu has been selected.
+   */
+  selected: PropTypes.bool,
+  /**
+   * The title for the overall menu name.
+   */
+  title: PropTypes.string
+};
+
+exports.SideNavFlyoutMenu = SideNavFlyoutMenu;

package/lib/components/SideNavMenu.d.ts

@@ -39,6 +39,10 @@ export interface SideNavMenuProps {
      * Indicates if the side navigation container is expanded or collapsed.
      */
     isSideNavExpanded?: boolean;
+    /**
+     *  The boolean to show the flyout menu has been selected.
+     */
+    selected?: boolean;
     /**
      * The tabIndex for the button element.
      * If not specified, the default validation will be applied.