@carbon/ibm-products 2.23.0 → 2.25.0

package/lib/components/CoachmarkOverlayElements/CoachmarkOverlayElements.js

@@ -0,0 +1,216 @@
+/**
+ * Copyright IBM Corp. 2020, 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';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _rollupPluginBabelHelpers = require('../../_virtual/_rollupPluginBabelHelpers.js');
+var React = require('react');
+var index$1 = require('../../node_modules/prop-types/index.js');
+var index = require('../../node_modules/classnames/index.js');
+var devtools = require('../../global/js/utils/devtools.js');
+var settings = require('../../settings.js');
+var react = require('@carbon/react');
+var lodash = require('lodash');
+var pconsole = require('../../global/js/utils/pconsole.js');
+var context = require('../Coachmark/utils/context.js');
+var SteppedAnimatedMedia = require('../SteppedAnimatedMedia/SteppedAnimatedMedia.js');
+var Carousel = require('../Carousel/Carousel.js');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var React__default = /*#__PURE__*/_interopDefaultLegacy(React);
+
+var _excluded = ["className", "children", "isVisible", "media", "nextButtonText", "previousButtonLabel", "closeButtonLabel"];
+
+// The block part of our conventional BEM class names (blockClass__E--M).
+var blockClass = "".concat(settings.pkg.prefix, "--coachmark-overlay-elements");
+var componentName = 'CoachmarkOverlayElements';
+
+// NOTE: the component SCSS is not imported here: it is rolled up separately.
+
+// Default values can be included here and then assigned to the prop params,
+// e.g. prop = defaults.prop,
+// This gathers default values together neatly and ensures non-primitive
+// values are initialized early to avoid react making unnecessary re-renders.
+// Note that default values are not required for props that are 'required',
+// nor for props where the component can apply undefined values reasonably.
+// Default values should be provided when the component needs to make a choice
+// or assumption when a prop is not supplied.
+
+// Default values for props
+var defaults = {
+  isVisible: false,
+  nextButtonText: 'Next',
+  previousButtonLabel: 'Back',
+  closeButtonLabel: 'Got it'
+};
+/**
+ * Composable container to allow for the displaying of CoachmarkOverlayElement
+ * components in a carousel fashion.
+ */
+exports.CoachmarkOverlayElements = /*#__PURE__*/React__default["default"].forwardRef(function (_ref, ref) {
+  var className = _ref.className,
+    children = _ref.children,
+    _ref$isVisible = _ref.isVisible,
+    isVisible = _ref$isVisible === void 0 ? defaults.isVisible : _ref$isVisible,
+    media = _ref.media,
+    _ref$nextButtonText = _ref.nextButtonText,
+    nextButtonText = _ref$nextButtonText === void 0 ? defaults.nextButtonText : _ref$nextButtonText,
+    _ref$previousButtonLa = _ref.previousButtonLabel,
+    previousButtonLabel = _ref$previousButtonLa === void 0 ? defaults.previousButtonLabel : _ref$previousButtonLa,
+    _ref$closeButtonLabel = _ref.closeButtonLabel,
+    closeButtonLabel = _ref$closeButtonLabel === void 0 ? defaults.closeButtonLabel : _ref$closeButtonLabel,
+    rest = _rollupPluginBabelHelpers.objectWithoutProperties(_ref, _excluded);
+  var buttonFocusRef = React.useRef();
+  var scrollRef = React.useRef();
+  var _useState = React.useState(0),
+    _useState2 = _rollupPluginBabelHelpers.slicedToArray(_useState, 2),
+    scrollPosition = _useState2[0],
+    setScrollPosition = _useState2[1];
+  var _useState3 = React.useState(0),
+    _useState4 = _rollupPluginBabelHelpers.slicedToArray(_useState3, 2),
+    currentProgStep = _useState4[0],
+    _setCurrentProgStep = _useState4[1];
+  var coachmark = context.useCoachmark();
+  var setCurrentProgStep = function setCurrentProgStep(value) {
+    if (currentProgStep > 0 && value === 0 && buttonFocusRef.current) {
+      setTimeout(function () {
+        buttonFocusRef.current.focus();
+      }, 1000);
+    }
+    _setCurrentProgStep(value);
+  };
+  var numProgSteps = React.Children.count(children);
+  var progStepFloor = 0;
+  var progStepCeil = numProgSteps - 1;
+  React.useEffect(function () {
+    // On mount, one of the two primary buttons ("next" or "close")
+    // will be rendered and must have focus. (a11y)
+    if (buttonFocusRef.current) {
+      buttonFocusRef.current.focus();
+    }
+  }, []);
+  React.useEffect(function () {
+    setTimeout(function () {
+      if (buttonFocusRef.current && isVisible) {
+        buttonFocusRef.current.focus();
+      }
+    }, 100);
+  }, [isVisible]);
+  if (!coachmark) {
+    return pconsole["default"].warn("The ".concat(componentName, " is a composable container element which should be used only within the scope of a Coachmark or a CoachmarkFixed component."));
+  }
+  return /*#__PURE__*/React__default["default"].createElement("section", _rollupPluginBabelHelpers["extends"]({}, rest, {
+    className: index["default"](blockClass,
+    // Apply the block class to the main HTML element
+    className,
+    // Apply any supplied class names to the main HTML element.
+    // example: `${blockClass}__template-string-class-${kind}-n-${size}`,
+    {
+      // switched classes dependant on props or state
+      // example: [`${blockClass}__here-if-small`]: size === 'sm',
+    }),
+    ref: ref
+    // role="main"
+  }, devtools.getDevtoolsProps(componentName)), media && (media.render ? media.render() : /*#__PURE__*/React__default["default"].createElement(SteppedAnimatedMedia.SteppedAnimatedMedia, {
+    className: "".concat(blockClass, "__element-stepped-media"),
+    filePaths: media.filePaths,
+    playStep: currentProgStep
+  })), numProgSteps === 1 ? /*#__PURE__*/React__default["default"].createElement(React__default["default"].Fragment, null, children, closeButtonLabel && /*#__PURE__*/React__default["default"].createElement("div", {
+    className: index["default"]("".concat(blockClass, "__footer"), 'coachmark-carousel-controls')
+  }, /*#__PURE__*/React__default["default"].createElement(react.Button, _rollupPluginBabelHelpers["extends"]({
+    size: "sm"
+  }, coachmark.closeButtonProps, {
+    ref: buttonFocusRef
+  }), closeButtonLabel))) : /*#__PURE__*/React__default["default"].createElement(React__default["default"].Fragment, null, /*#__PURE__*/React__default["default"].createElement(Carousel.Carousel, {
+    disableArrowScroll: true,
+    ref: scrollRef,
+    onScroll: function onScroll(scrollPercent) {
+      setScrollPosition(scrollPercent);
+    }
+  }, children), /*#__PURE__*/React__default["default"].createElement("div", {
+    className: index["default"]("".concat(blockClass, "__footer"))
+  }, /*#__PURE__*/React__default["default"].createElement("div", {
+    className: "".concat(blockClass, "--controls-progress")
+  }, "".concat(currentProgStep + 1, " / ").concat(numProgSteps)), scrollPosition > 0 && /*#__PURE__*/React__default["default"].createElement(react.Button, {
+    size: "sm",
+    kind: "ghost",
+    title: previousButtonLabel,
+    disabled: scrollPosition === 0,
+    onClick: function onClick() {
+      var targetStep = lodash.clamp(currentProgStep - 1, progStepFloor, progStepCeil);
+      scrollRef.current.scrollToView(targetStep);
+      setCurrentProgStep(targetStep);
+    }
+  }, previousButtonLabel), currentProgStep < progStepCeil ? /*#__PURE__*/React__default["default"].createElement(react.Button, {
+    size: "sm",
+    ref: buttonFocusRef,
+    title: nextButtonText,
+    disabled: scrollPosition === 1,
+    onClick: function onClick() {
+      var targetStep = lodash.clamp(currentProgStep + 1, progStepFloor, progStepCeil);
+      scrollRef.current.scrollToView(targetStep);
+      setCurrentProgStep(targetStep);
+    }
+  }, nextButtonText) : closeButtonLabel && /*#__PURE__*/React__default["default"].createElement(react.Button, _rollupPluginBabelHelpers["extends"]({
+    size: "sm",
+    ref: buttonFocusRef
+  }, coachmark.closeButtonProps), closeButtonLabel))));
+});
+
+// Return a placeholder if not released and not enabled by feature flag
+exports.CoachmarkOverlayElements = settings.pkg.checkComponentEnabled(exports.CoachmarkOverlayElements, componentName);
+
+// The display name of the component, used by React. Note that displayName
+// is used in preference to relying on function.name.
+exports.CoachmarkOverlayElements.displayName = componentName;
+
+// The types and DocGen commentary for the component props,
+// in alphabetical order (for consistency).
+// See https://www.npmjs.com/package/prop-types#usage.
+exports.CoachmarkOverlayElements.propTypes = {
+  // TODO: UPDATE COMMENT HERE - UPDATE MDX TO HAVE DIRECTION TO USE ONLY OVERLAY ELEMENTS>...CoachmarkOverlayElements will accept only one or more CoachmarkOverlayElement as child components.
+
+  /**
+   * CoachmarkOverlayElements should be used with one or many CoachmarkOverlayElement components as children.
+   * @see CoachmarkOverlayElement
+   */
+  children: index$1["default"].node.isRequired,
+  /**
+   * Optional class name for this component.
+   */
+  className: index$1["default"].string,
+  /**
+   * The label for the Close button.
+   */
+  closeButtonLabel: index$1["default"].string,
+  /**
+   * The visibility of CoachmarkOverlayElements is
+   * managed in the parent component.
+   */
+  isVisible: index$1["default"].bool,
+  /**
+   * The object describing an image in one of two shapes.
+   * If a single media element is required, use `{render}`.
+   * If a stepped animation is required, use `{filePaths}`.
+   */
+  media: index$1["default"].oneOfType([index$1["default"].shape({
+    render: index$1["default"].func
+  }), index$1["default"].shape({
+    filePaths: index$1["default"].arrayOf(index$1["default"].string)
+  })]),
+  /**
+   * The label for the Next button.
+   */
+  nextButtonText: index$1["default"].string,
+  /**
+   * The label for the Previous button.
+   */
+  previousButtonLabel: index$1["default"].string
+};

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

@@ -0,0 +1 @@
+export { CoachmarkOverlayElements } from "./CoachmarkOverlayElements";

package/lib/components/CoachmarkStack/CoachmarkStack.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Stacked coachmarks are used to call out specific functionality or concepts
+ * within the UI that may not be intuitive but are important for the
+ * user to gain understanding of the product's main value and discover new use cases.
+ * This variant allows the stacking of multiple coachmark overlays to be displayed by interacting with the tagline.
+ */
+export let CoachmarkStack: React.ForwardRefExoticComponent<React.RefAttributes<any>>;
+import React from 'react';

package/lib/components/CoachmarkStack/CoachmarkStack.js

@@ -0,0 +1,287 @@
+/**
+ * Copyright IBM Corp. 2020, 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';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var _rollupPluginBabelHelpers = require('../../_virtual/_rollupPluginBabelHelpers.js');
+var React = require('react');
+var reactDom = require('react-dom');
+var index$1 = require('../../node_modules/prop-types/index.js');
+var index = require('../../node_modules/classnames/index.js');
+var devtools = require('../../global/js/utils/devtools.js');
+var settings = require('../../settings.js');
+var CoachmarkOverlay = require('../Coachmark/CoachmarkOverlay.js');
+var CoachmarkStackHome = require('./CoachmarkStackHome.js');
+var CoachmarkTagline = require('../Coachmark/CoachmarkTagline.js');
+var context = require('../Coachmark/utils/context.js');
+var enums = require('../Coachmark/utils/enums.js');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var React__default = /*#__PURE__*/_interopDefaultLegacy(React);
+
+var _excluded = ["children", "className", "onClose", "description", "media", "navLinkLabels", "portalTarget", "closeButtonLabel", "tagline", "theme", "title"];
+
+// Carbon and package components we use.
+/* TODO: @import(s) of carbon components and other package components. */
+
+// The block part of our conventional BEM class names (blockClass__E--M).
+var blockClass = "".concat(settings.pkg.prefix, "--coachmark-stack");
+var componentName = 'CoachmarkStack';
+var elementBlockClass = "".concat(settings.pkg.prefix, "--coachmark-stack-element");
+var defaults = {
+  onClose: function onClose() {},
+  // Pass through to CoachmarkStackHome
+  theme: 'light'
+};
+
+// NOTE
+// The stack is limited to a depth of two Coachmarks:
+// - a single parent CoachmarkStackHome
+// - a single child Coachmark when stacked
+// The parent will include links to all the children.
+// No child Coachmark will include links to any other child Coachmarks.
+
+/**
+ * Stacked coachmarks are used to call out specific functionality or concepts
+ * within the UI that may not be intuitive but are important for the
+ * user to gain understanding of the product's main value and discover new use cases.
+ * This variant allows the stacking of multiple coachmark overlays to be displayed by interacting with the tagline.
+ */
+exports.CoachmarkStack = /*#__PURE__*/React__default["default"].forwardRef(function (_ref, ref) {
+  var _document$querySelect;
+  var children = _ref.children,
+    className = _ref.className,
+    _ref$onClose = _ref.onClose,
+    onClose = _ref$onClose === void 0 ? defaults.onClose : _ref$onClose,
+    description = _ref.description,
+    media = _ref.media,
+    navLinkLabels = _ref.navLinkLabels,
+    _ref$portalTarget = _ref.portalTarget,
+    portalTarget = _ref$portalTarget === void 0 ? defaults.portalTarget : _ref$portalTarget,
+    closeButtonLabel = _ref.closeButtonLabel,
+    tagline = _ref.tagline,
+    _ref$theme = _ref.theme,
+    theme = _ref$theme === void 0 ? defaults.theme : _ref$theme,
+    title = _ref.title,
+    rest = _rollupPluginBabelHelpers.objectWithoutProperties(_ref, _excluded);
+  var portalNode = portalTarget ? (_document$querySelect = document.querySelector(portalTarget)) !== null && _document$querySelect !== void 0 ? _document$querySelect : document.querySelector('body') : document.querySelector('body');
+  var stackHomeRef = React.useRef();
+  var stackedCoachmarkRefs = React.useRef([]);
+  var _useState = React.useState(false),
+    _useState2 = _rollupPluginBabelHelpers.slicedToArray(_useState, 2),
+    isOpen = _useState2[0],
+    setIsOpen = _useState2[1];
+  // selectedItemNumber -1 = parent close button was clicked, remove entire stack
+  // selectedItemNumber 0 = (default) the parent is visible, all children are hidden
+  // selectedItemNumber 1+ = a child is visible and stacked atop the parent
+  var _useState3 = React.useState(0),
+    _useState4 = _rollupPluginBabelHelpers.slicedToArray(_useState3, 2),
+    selectedItemNumber = _useState4[0],
+    setSelectedItemNumber = _useState4[1];
+  // // The parent height and width values to return to after unstacked
+  var _useState5 = React.useState(null),
+    _useState6 = _rollupPluginBabelHelpers.slicedToArray(_useState5, 2),
+    parentHeight = _useState6[0],
+    setParentHeight = _useState6[1];
+  // parent height = child height when stacked behind a child that is shorter
+  var childArray = React.Children.toArray(children);
+  var mountedRef = React.useRef();
+  // same value as CSS animation speed
+  var delayMs = 240;
+
+  // Unmount or unstack a child
+  var handleClickNavItem = function handleClickNavItem(itemNumber) {
+    setSelectedItemNumber(itemNumber);
+  };
+  var handleClose = React.useCallback(function (isParentCloseButton) {
+    if (isParentCloseButton) {
+      // Trigger slide-out animation
+      setSelectedItemNumber(-1);
+
+      // Unmount after animation is complete
+      var timer = setTimeout(function () {
+        setIsOpen(false);
+        onClose();
+      }, delayMs);
+      return function () {
+        return clearTimeout(timer);
+      };
+    } else {
+      // Unstack child
+      setSelectedItemNumber(0);
+    }
+  }, [onClose]);
+  var escFunction = React.useCallback(function (event) {
+    if (event.key === 'Escape') {
+      selectedItemNumber === 0 ? handleClose(true) : handleClose(false);
+    }
+  }, [handleClose, selectedItemNumber]);
+  React.useEffect(function () {
+    document.addEventListener('keydown', escFunction, false);
+    return function () {
+      document.removeEventListener('keydown', escFunction, false);
+    };
+  }, [escFunction]);
+  var contextValue = {
+    buttonProps: {
+      tabIndex: 0,
+      'aria-expanded': isOpen,
+      onClick: function onClick() {
+        setIsOpen(true);
+      },
+      // Compensate for accidental open/close on double-click.
+      // Only open on double-click.
+      onDoubleClick: function onDoubleClick() {
+        setIsOpen(true);
+      }
+    },
+    closeButtonProps: {
+      onClick: function onClick() {
+        return handleClose(false);
+      }
+    },
+    isOpen: isOpen
+  };
+  React.useEffect(function () {
+    mountedRef.current = true;
+    return function () {
+      mountedRef.current = false;
+    };
+  }, []);
+  React.useEffect(function () {
+    setTimeout(function () {
+      if (stackHomeRef.current) {
+        setParentHeight(stackHomeRef.current.clientHeight + 16);
+      }
+    }, 0);
+  }, [stackHomeRef]);
+  React.useEffect(function () {
+    var targetSelectedItem = selectedItemNumber - 1;
+    if (!parentHeight) {
+      return;
+    }
+    stackHomeRef.current.style.height = "".concat(parentHeight, "px");
+    if (!isOpen || targetSelectedItem < 0) {
+      stackHomeRef.current.focus();
+      return;
+    }
+    var targetHomeHeight = stackedCoachmarkRefs.current[targetSelectedItem].clientHeight;
+    stackHomeRef.current.style.height = "".concat(targetHomeHeight, "px");
+    stackedCoachmarkRefs.current[targetSelectedItem].focus();
+  }, [selectedItemNumber, isOpen, parentHeight]);
+  var wrappedChildren = React.Children.map(childArray, function (child, idx) {
+    var mountedClass = mountedRef.current ? "".concat(elementBlockClass, "--is-mounted") : '';
+    return /*#__PURE__*/React__default["default"].createElement(CoachmarkOverlay.CoachmarkOverlay, {
+      key: idx,
+      ref: function ref(_ref2) {
+        return stackedCoachmarkRefs.current[idx] = _ref2;
+      },
+      kind: enums.COACHMARK_OVERLAY_KIND.STACKED,
+      onClose: function onClose() {
+        return handleClose(false);
+      },
+      theme: theme,
+      fixedIsVisible: false,
+      className: index["default"](elementBlockClass, mountedClass, idx === selectedItemNumber - 1 && "".concat(elementBlockClass, "--is-visible"), mountedRef.current && "".concat(elementBlockClass, "--is-mounted"))
+    }, child);
+  });
+  return /*#__PURE__*/React__default["default"].createElement(context.CoachmarkContext.Provider, {
+    value: contextValue
+  }, /*#__PURE__*/React__default["default"].createElement("div", _rollupPluginBabelHelpers["extends"]({}, rest, {
+    className: index["default"](blockClass, "".concat(settings.pkg.prefix, "--coachmark-overlay--stack"), className),
+    ref: ref
+  }, devtools.getDevtoolsProps(componentName)), /*#__PURE__*/React__default["default"].createElement(CoachmarkTagline.CoachmarkTagline, {
+    title: tagline,
+    onClose: onClose
+  }), /*#__PURE__*/React__default["default"].createElement(CoachmarkStackHome.CoachmarkStackHome, {
+    ref: stackHomeRef,
+    className: index["default"]("".concat(settings.pkg.prefix, "--coachmark-overlay"), "".concat(settings.pkg.prefix, "--coachmark-overlay__").concat(theme), elementBlockClass, selectedItemNumber > 0 && "".concat(elementBlockClass, "--is-stacked"), selectedItemNumber > 0 && "".concat(elementBlockClass, "--is-stacked__").concat(theme), isOpen && "".concat(elementBlockClass, "--is-visible"), mountedRef.current && "".concat(elementBlockClass, "--is-mounted")),
+    isOpen: isOpen && selectedItemNumber < 1,
+    description: description,
+    media: media,
+    navLinkLabels: navLinkLabels,
+    onClickNavItem: handleClickNavItem,
+    onClose: function onClose() {
+      handleClose(true);
+    },
+    portalTarget: portalTarget,
+    closeButtonLabel: closeButtonLabel,
+    title: title
+  }), /*#__PURE__*/reactDom.createPortal(wrappedChildren, portalNode)));
+});
+
+// Return a placeholder if not released and not enabled by feature flag
+exports.CoachmarkStack = settings.pkg.checkComponentEnabled(exports.CoachmarkStack, componentName);
+
+// The display name of the component, used by React. Note that displayName
+// is used in preference to relying on function.name.
+exports.CoachmarkStack.displayName = componentName;
+
+// The types and DocGen commentary for the component props,
+// in alphabetical order (for consistency).
+// See https://www.npmjs.com/package/prop-types#usage.
+exports.CoachmarkStack.propTypes = {
+  /**
+   * CoachmarkStack should use a single CoachmarkOverlayElements component as a child.
+   */
+  children: index$1["default"].node.isRequired,
+  /**
+   * Provide an optional class to be applied to the containing node.
+   */
+  className: index$1["default"].string,
+  /**
+   * The label for the button that will close the Stack
+   */
+  closeButtonLabel: index$1["default"].string,
+  // Pass through to CoachmarkStackHome
+  /**
+   * The description of the Coachmark.
+   */
+  description: index$1["default"].node.isRequired,
+  /**
+   * The object describing an image in one of two shapes.
+   *
+   * If a single media element is required, use `{render}`.
+   *
+   * If a stepped animation is required, use `{filePaths}`.
+   *
+   * @see {@link MEDIA_PROP_TYPE}.
+   */
+  media: index$1["default"].oneOfType([index$1["default"].shape({
+    render: index$1["default"].func
+  }), index$1["default"].shape({
+    filePaths: index$1["default"].arrayOf(index$1["default"].string)
+  })]),
+  /**
+   * The labels used to link to the stackable Coachmarks.
+   */
+  navLinkLabels: index$1["default"].arrayOf(index$1["default"].string).isRequired,
+  /**
+   * Function to call when the CoachmarkStack closes.
+   */
+  onClose: index$1["default"].func,
+  /**
+   * Where in the DOM to render the stack.
+   * The default is `document.body`.
+   */
+  portalTarget: index$1["default"].string,
+  /**
+   * The tagline title which will be fixed to the bottom right of the window and will serve as the display trigger.
+   */
+  tagline: index$1["default"].string.isRequired,
+  /**
+   * Determines the theme of the component.
+   */
+  theme: index$1["default"].oneOf(['light', 'dark']),
+  /**
+   * The title of the Coachmark.
+   */
+  title: index$1["default"].string.isRequired
+};

package/lib/components/CoachmarkStack/CoachmarkStackHome.d.ts

@@ -0,0 +1,6 @@
+/**
+ * DO NOT USE. This component is for the exclusive use
+ * of other Novice to Pro components.
+ */
+export let CoachmarkStackHome: React.ForwardRefExoticComponent<React.RefAttributes<any>>;
+import React from 'react';