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

package/lib/components/InlineTip/InlineTip.js

@@ -0,0 +1,199 @@
+/**
+ * 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('@carbon/react');
+var icons = require('@carbon/react/icons');
+var React = require('react');
+var index = require('../../_virtual/index.js');
+var cx = require('classnames');
+var utils = require('./utils.js');
+var devtools = require('../../global/js/utils/devtools.js');
+var settings = require('../../settings.js');
+var uuidv4 = require('../../global/js/utils/uuidv4.js');
+
+var _Close, _Idea, _Crossroads;
+
+// The block part of our conventional BEM class names (blockClass__E--M).
+const blockClass = `${settings.pkg.prefix}--inline-tip`;
+const componentName = 'InlineTip';
+
+// NOTE: the component SCSS is not imported here: it is rolled up separately.
+
+// Default values for props
+const defaults = {
+  closeIconDescription: 'Close',
+  collapsible: false,
+  collapseButtonLabel: 'Read less',
+  expandButtonLabel: 'Read more',
+  narrow: false,
+  withLeftGutter: false,
+  title: 'Use case-specific heading'
+};
+/**
+ * Inline tips are messages embedded within other components that
+ * provide an ambient way to deliver learning content without
+ * distracting the user from their flow.
+ */
+const InlineTip = /*#__PURE__*/React.forwardRef((_ref, ref) => {
+  let {
+    action,
+    children,
+    className,
+    closeIconDescription = defaults.closeIconDescription,
+    collapsible = defaults.collapsible,
+    collapseButtonLabel = defaults.collapseButtonLabel,
+    expandButtonLabel = defaults.expandButtonLabel,
+    renderMedia,
+    narrow = defaults.narrow,
+    onClick,
+    onClose,
+    tertiaryButtonLabel,
+    title = defaults.title,
+    withLeftGutter = defaults.withLeftGutter,
+    ...rest
+  } = _ref;
+  const [isCollapsed, setIsCollapsed] = React.useState(collapsible);
+  const labelId = React.useRef(uuidv4.default()).current;
+  const previewText = React.useMemo(() => utils.getComponentText(React.Children.toArray(children)), [children]);
+  let childrenToRender = children;
+  if (!renderMedia && collapsible && isCollapsed) {
+    childrenToRender = /*#__PURE__*/React.createElement("p", {
+      className: `${blockClass}__preview-text`
+    }, previewText);
+  }
+
+  // If `collapsible` is changed after initial render...
+  React.useEffect(() => {
+    setIsCollapsed(collapsible);
+  }, [collapsible]);
+  return /*#__PURE__*/React.createElement(react.Section, _rollupPluginBabelHelpers.extends({}, rest, {
+    "aria-labelledby": labelId,
+    className: cx(blockClass, className, collapsible && `${blockClass}__collapsible`, isCollapsed && `${blockClass}__collapsible-collapsed`, renderMedia && `${blockClass}__has-media`, [narrow ? `${blockClass}__narrow` : `${blockClass}__wide`], withLeftGutter && !narrow && `${blockClass}__with-left-gutter`),
+    ref: ref,
+    role: "complementary"
+  }, devtools.getDevtoolsProps(componentName)), /*#__PURE__*/React.createElement("div", {
+    className: `${blockClass}__close-icon-wrapper`
+  }, /*#__PURE__*/React.createElement(react.IconButton, {
+    className: `${blockClass}__close-icon`,
+    kind: "ghost",
+    label: closeIconDescription,
+    onClick: onClose,
+    size: "lg"
+  }, _Close || (_Close = /*#__PURE__*/React.createElement(icons.Close, {
+    size: 16
+  })))), (!renderMedia && narrow || !narrow) && /*#__PURE__*/React.createElement("div", {
+    className: `${blockClass}__icon-idea`,
+    tabIndex: -1
+  }, _Idea || (_Idea = /*#__PURE__*/React.createElement(icons.Idea, {
+    size: 16
+  }))), /*#__PURE__*/React.createElement("div", {
+    className: `${blockClass}__content`
+  }, /*#__PURE__*/React.createElement(react.Heading, {
+    id: labelId,
+    className: `${blockClass}__title`
+  }, title), /*#__PURE__*/React.createElement("section", {
+    className: `${blockClass}__body`
+  }, childrenToRender, action && (!collapsible || collapsible && !isCollapsed) && /*#__PURE__*/React.createElement("div", {
+    className: `${blockClass}__secondary-btn`
+  }, action)), (collapsible || tertiaryButtonLabel) && /*#__PURE__*/React.createElement("footer", {
+    className: `${blockClass}__footer`
+  }, collapsible && !renderMedia && /*#__PURE__*/React.createElement(react.Button, {
+    className: `${blockClass}__toggle-btn`,
+    kind: "ghost",
+    size: "md",
+    onClick: () => {
+      setIsCollapsed(prevState => !prevState);
+    }
+  }, isCollapsed ? expandButtonLabel : collapseButtonLabel), tertiaryButtonLabel && /*#__PURE__*/React.createElement(react.Button, {
+    className: `${blockClass}__close-btn`,
+    size: "md",
+    onClick: onClick,
+    kind: "tertiary",
+    renderIcon: () => _Crossroads || (_Crossroads = /*#__PURE__*/React.createElement(icons.Crossroads, {
+      size: 16
+    }))
+  }, tertiaryButtonLabel))), renderMedia && /*#__PURE__*/React.createElement("div", {
+    className: `${blockClass}__media`
+  }, renderMedia()));
+});
+InlineTip.displayName = componentName;
+InlineTip.propTypes = {
+  /**
+   * Optional "call to action" ghost button or link that can appear
+   * directly below the content. This component comes with pre-styled
+   * elements available to use: `InlineTipLink` and `InlineTipButton`.
+   */
+  action: index.default.node,
+  /**
+   * Provide the contents of the InlineTip.
+   */
+  children: index.default.node.isRequired,
+  /**
+   * Provide an optional class to be applied to the containing node.
+   */
+  className: index.default.string,
+  /**
+   * Tooltip text and aria label for the Close button icon.
+   */
+  closeIconDescription: index.default.string,
+  /**
+   * The label for the collapse button.
+   * This button is not visible if `media` is specified.
+   */
+  collapseButtonLabel: index.default.string,
+  /**
+   * If set to `true`, it will truncate the body text to
+   * one line and expose an expand/collapse button toggle.
+   *
+   * This feature is disabled if `media` is specified.
+   */
+  collapsible: index.default.bool,
+  /**
+   * The label for the expand button.
+   * This button is not visible if `media` is specified.
+   */
+  expandButtonLabel: index.default.string,
+  /**
+   * Set to `true` to arrange the information in a format
+   * that is easier to read in a limited space.
+   */
+  narrow: index.default.bool,
+  /**
+   * Function to call when the tertiary button is clicked.
+   */
+  onClick: index.default.func,
+  /**
+   * Function to call when the InlineTip is closed via the "X" button.
+   */
+  onClose: index.default.func,
+  /**
+   * Optional prop to render any media like images or animated media.
+   */
+  renderMedia: index.default.func,
+  /**
+   * Defining the label will show a the tertiary button with the crossroads icon.
+   * You will still need to define the `onClose` method to trigger a callback.
+   */
+  tertiaryButtonLabel: index.default.string,
+  /**
+   * The title of the InlineTip.
+   */
+  title: index.default.string.isRequired,
+  /**
+   * If true, insert 1 rem of "space" on the left of the component.
+   * This will allow the component's content to line up with other
+   * content on the page under special circumstances.
+   *
+   * This will only be applied when `narrow` is false.
+   */
+  withLeftGutter: index.default.bool
+};
+
+exports.InlineTip = InlineTip;

package/lib/components/InlineTip/InlineTipButton.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright IBM Corp. 2023, 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, { ReactNode } from 'react';
+import { ButtonProps } from '@carbon/react';
+export interface InlineTipButtonProps {
+    /**
+     * Provide an optional class to be applied to the containing node.
+     */
+    className?: string;
+    /**
+     * Provide the contents of the InlineTip.
+     */
+    children: ReactNode;
+}
+/**
+ * This is a standard Carbon button, styled specifically for use inside InlineTip.
+ */
+export declare const InlineTipButton: React.ForwardRefExoticComponent<InlineTipButtonProps & {
+    children?: ReactNode | undefined;
+} & React.RefAttributes<ButtonProps<React.ElementType<any, keyof React.JSX.IntrinsicElements>>>>;

package/lib/components/InlineTip/InlineTipButton.js

@@ -0,0 +1,55 @@
+/**
+ * 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 react = require('@carbon/react');
+var index = require('../../_virtual/index.js');
+var cx = require('classnames');
+var devtools = require('../../global/js/utils/devtools.js');
+var settings = require('../../settings.js');
+
+// The block part of our conventional BEM class names (blockClass__E--M).
+const blockClass = `${settings.pkg.prefix}--inline-tip__button`;
+const componentName = 'InlineTipButton';
+
+// NOTE: the component SCSS is not imported here: it is rolled up separately.
+
+/**
+ * This is a standard Carbon button, styled specifically for use inside InlineTip.
+ */
+const InlineTipButton = /*#__PURE__*/React.forwardRef((_ref, ref) => {
+  let {
+    children,
+    className,
+    ...rest
+  } = _ref;
+  return /*#__PURE__*/React.createElement(react.Button, _rollupPluginBabelHelpers.extends({}, rest, {
+    className: cx(blockClass, className),
+    ref: ref
+  }, devtools.getDevtoolsProps(componentName), {
+    size: "md",
+    kind: "ghost"
+  }), children);
+});
+InlineTipButton.displayName = componentName;
+InlineTipButton.propTypes = {
+  /**
+   * Provide the contents of the InlineTipButton.
+   */
+  children: index.default.node.isRequired,
+  /**
+   * Provide an optional class to be applied to the containing node.
+   */
+  className: index.default.string
+
+  /* TODO: add types and DocGen for all props. */
+};
+
+exports.InlineTipButton = InlineTipButton;

package/lib/components/InlineTip/InlineTipLink.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright IBM Corp. 2023, 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 React, { PropsWithChildren, ReactNode } from 'react';
+export interface InlineTipLinkProps extends PropsWithChildren {
+    /**
+     * Provide the contents of the InlineTipLink.
+     */
+    children: ReactNode;
+    /**
+     * Provide an optional class to be applied to the containing node.
+     */
+    className?: string;
+}
+/**
+ * This is a standard Carbon link, styled specifically for use inside InlineTip.
+ */
+export declare const InlineTipLink: React.ForwardRefExoticComponent<InlineTipLinkProps & React.RefAttributes<HTMLDivElement>>;

package/lib/components/InlineTip/InlineTipLink.js

@@ -0,0 +1,59 @@
+/**
+ * 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 icons = require('@carbon/react/icons');
+var react = require('@carbon/react');
+var index = require('../../_virtual/index.js');
+var cx = require('classnames');
+var devtools = require('../../global/js/utils/devtools.js');
+var settings = require('../../settings.js');
+
+var _Launch;
+
+// The block part of our conventional BEM class names (blockClass__E--M).
+const blockClass = `${settings.pkg.prefix}--inline-tip__link`;
+const componentName = 'InlineTipLink';
+
+// NOTE: the component SCSS is not imported here: it is rolled up separately.
+
+/**
+ * This is a standard Carbon link, styled specifically for use inside InlineTip.
+ */
+const InlineTipLink = /*#__PURE__*/React.forwardRef((_ref, ref) => {
+  let {
+    children,
+    className,
+    ...rest
+  } = _ref;
+  return /*#__PURE__*/React.createElement(react.Link, _rollupPluginBabelHelpers.extends({}, rest, {
+    className: cx(blockClass, className),
+    ref: ref
+  }, devtools.getDevtoolsProps(componentName), {
+    renderIcon: () => _Launch || (_Launch = /*#__PURE__*/React.createElement(icons.Launch, {
+      size: 16
+    }))
+  }), children);
+});
+InlineTipLink.displayName = componentName;
+InlineTipLink.propTypes = {
+  /**
+   * Provide the contents of the InlineTipLink.
+   */
+  children: index.default.node.isRequired,
+  /**
+   * Provide an optional class to be applied to the containing node.
+   */
+  className: index.default.string
+
+  /* TODO: add types and DocGen for all props. */
+};
+
+exports.InlineTipLink = InlineTipLink;

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

@@ -0,0 +1,12 @@
+/**
+ * Copyright IBM Corp. 2023, 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.
+ */
+export { InlineTip } from './InlineTip';
+export { InlineTipButton } from './InlineTipButton';
+export { InlineTipLink } from './InlineTipLink';
+export type { InlineTipProps } from './InlineTip';
+export type { InlineTipButtonProps } from './InlineTipButton';
+export type { InlineTipLinkProps } from './InlineTipLink';

package/lib/components/InlineTip/utils.d.ts

@@ -0,0 +1 @@
+export function getComponentText(reactNode: any): any;

package/lib/components/InlineTip/utils.js

@@ -0,0 +1,38 @@
+/**
+ * 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';
+
+const getComponentText = reactNode => {
+  const tmpChildren = reactNode?.props?.children || undefined;
+  if (Array.isArray(reactNode)) {
+    let joinedNodes = [];
+    reactNode.forEach(node => {
+      if (typeof node === 'object') {
+        joinedNodes.push(getComponentText(node));
+      } else if (typeof node === 'string') {
+        joinedNodes.push(node);
+      }
+    });
+    return joinedNodes.join(' ');
+  }
+  if (tmpChildren === undefined) {
+    if (typeof reactNode === 'string') {
+      return reactNode;
+    } else {
+      return ' ';
+    }
+  }
+  if (typeof tmpChildren === 'object') {
+    return getComponentText(reactNode.props.children);
+  }
+  if (typeof tmpChildren === 'string') {
+    return reactNode.props.children;
+  }
+};
+
+exports.getComponentText = getComponentText;

package/lib/components/InterstitialScreen/InterstitialScreen.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Copyright IBM Corp. 2024, 2025
+ *
+ * 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, { ReactNode, RefObject } from 'react';
+import { InterstitialScreenHeaderProps } from './InterstitialScreenHeader';
+import { InterstitialScreenBodyProps } from './InterstitialScreenBody';
+import { InterstitialScreenFooterProps } from './InterstitialScreenFooter';
+import { ActionType } from './context';
+export interface InterstitialScreenProps {
+    /**
+     * Provide the contents of the InterstitialScreen.
+     */
+    children: ReactNode;
+    /**
+     * Provide an optional class to be applied to the containing node.
+     */
+    className?: string;
+    /**
+     * The aria label applied to the Interstitial Screen component
+     */
+    ariaLabel?: string;
+    /**
+     * Specifies whether the component is shown as a full-screen
+     * experience, else it is shown as a modal by default.
+     */
+    isFullScreen?: boolean;
+    /**
+     * Specifies whether the component is currently open.
+     */
+    open?: boolean;
+    /**
+     * Function to call when the close button is clicked.
+     */
+    onClose?: (value: ActionType) => void;
+    /**
+     * Provide a ref to return focus to once the interstitial is closed.
+     */
+    launcherButtonRef?: RefObject<HTMLElement>;
+}
+export type InterstitialScreenComponent = React.ForwardRefExoticComponent<InterstitialScreenProps & React.RefAttributes<HTMLDivElement>> & {
+    Header: React.FC<InterstitialScreenHeaderProps>;
+    Body: React.FC<InterstitialScreenBodyProps>;
+    Footer: React.FC<InterstitialScreenFooterProps>;
+};
+/**
+ * InterstitialScreen can be a full page or an overlay, and are
+ * shown on the first time a user accesses a new experience
+ * (e.g. upon first login or first time opening a page where a
+ * newly purchased capability is presented).
+ */
+export declare const InterstitialScreen: InterstitialScreenComponent;

package/lib/components/InterstitialScreen/InterstitialScreen.js

@@ -0,0 +1,199 @@
+/**
+ * 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('@carbon/react');
+var React = require('react');
+var index = require('../../_virtual/index.js');
+var cx = require('classnames');
+var devtools = require('../../global/js/utils/devtools.js');
+var InterstitialScreenHeader = require('./InterstitialScreenHeader.js');
+var InterstitialScreenBody = require('./InterstitialScreenBody.js');
+var InterstitialScreenFooter = require('./InterstitialScreenFooter.js');
+var context = require('./context.js');
+
+const componentName = 'InterstitialScreen';
+
+// Define the type for InterstitialScreen, extending it to include Header
+
+/**
+ * InterstitialScreen can be a full page or an overlay, and are
+ * shown on the first time a user accesses a new experience
+ * (e.g. upon first login or first time opening a page where a
+ * newly purchased capability is presented).
+ */
+const InterstitialScreen = /*#__PURE__*/React.forwardRef((props, ref) => {
+  const {
+    children,
+    className,
+    ariaLabel = 'Interstitial screen',
+    isFullScreen = false,
+    open = false,
+    launcherButtonRef,
+    onClose,
+    ...rest
+  } = props;
+  const backupRef = React.useRef(null);
+  const _forwardedRef = ref || backupRef;
+  const scrollRef = React.useRef(undefined);
+  const startButtonRef = React.useRef(undefined);
+  const nextButtonRef = React.useRef(undefined);
+  const [isVisibleClass, setIsVisibleClass] = React.useState(null);
+  const [progStep, setProgStep] = React.useState(0);
+  const bodyScrollRef = React.useRef(null);
+  const [stepCount, setStepCount] = React.useState(0);
+  const [disableButtonConfig, setDisableButtonConfig] = React.useState({
+    skip: false,
+    back: false,
+    next: false,
+    start: false
+  });
+  const variantClass = isFullScreen ? `${context.blockClass}--full-screen` : `${context.blockClass}--modal`;
+  const [bodyChildrenData, setBodyChildrenData] = React.useState(null);
+  const handleClose = React.useCallback(actionName => {
+    setProgStep(0);
+    onClose?.(actionName ?? 'close');
+  }, [onClose]);
+  React.useEffect(() => {
+    if (!open) {
+      setProgStep(0);
+    }
+    startButtonRef.current?.focus();
+  }, [open, progStep, onClose]);
+  React.useEffect(() => {
+    // for modal only, "is-visible" triggers animation
+    setIsVisibleClass(!isFullScreen && open ? 'is-visible' : null);
+    nextButtonRef?.current?.focus();
+    if (!open && launcherButtonRef) {
+      setTimeout(() => {
+        launcherButtonRef.current.focus();
+      }, 0);
+    }
+  }, [launcherButtonRef, isFullScreen, open]);
+
+  // hitting escape key also closes this component
+  React.useEffect(() => {
+    const close = e => {
+      const {
+        key
+      } = e;
+      if (key === 'Escape') {
+        handleClose('close');
+      }
+    };
+    window.addEventListener('keydown', close);
+    return () => window.removeEventListener('keydown', close);
+  }, [handleClose]);
+  if (!open) {
+    return null;
+  }
+  const renderModal = () => {
+    return /*#__PURE__*/React.createElement(react.unstable_FeatureFlags, {
+      enableExperimentalFocusWrapWithoutSentinels: true
+    }, /*#__PURE__*/React.createElement(react.ComposedModal, _rollupPluginBabelHelpers.extends({}, rest, {
+      preventCloseOnClickOutside: true,
+      className: cx(context.blockClass,
+      // Apply the block class to the main HTML element
+      className // Apply any supplied class names to the main HTML element.
+      ),
+      size: "lg",
+      onClose: handleClose,
+      open: open,
+      ref: _forwardedRef,
+      "aria-label": ariaLabel
+    }, devtools.getDevtoolsProps(componentName)), children));
+  };
+  const renderFullScreen = () => {
+    return /*#__PURE__*/React.createElement("div", _rollupPluginBabelHelpers.extends({}, rest, {
+      className: cx(context.blockClass,
+      // Apply the block class to the main HTML element
+      className,
+      // Apply any supplied class names to the main HTML element.
+      variantClass, isVisibleClass),
+      role: "main",
+      "aria-label": ariaLabel,
+      ref: ref
+    }, devtools.getDevtoolsProps(componentName)), /*#__PURE__*/React.createElement("div", {
+      className: `${context.blockClass}--container`
+    }, children));
+  };
+  const handleGotoStep = targetStep => {
+    setProgStep(targetStep);
+    scrollRef.current.scrollToView(targetStep);
+    scrollBodyToTop();
+  };
+  const scrollBodyToTop = () => {
+    bodyScrollRef.current?.scroll?.({
+      top: 0,
+      behavior: 'smooth'
+    });
+  };
+  return /*#__PURE__*/React.createElement(context.InterstitialScreenContext.Provider, {
+    value: {
+      bodyChildrenData,
+      setBodyChildrenData,
+      isFullScreen,
+      handleClose,
+      progStep,
+      setProgStep,
+      bodyScrollRef,
+      scrollRef,
+      handleGotoStep,
+      stepCount,
+      setStepCount,
+      disableButtonConfig,
+      setDisableButtonConfig
+    }
+  }, isFullScreen ? renderFullScreen() : renderModal());
+});
+InterstitialScreen.Header = InterstitialScreenHeader.default;
+InterstitialScreen.Body = InterstitialScreenBody.default;
+InterstitialScreen.Footer = InterstitialScreenFooter.default;
+
+// The display name of the component, used by React. Note that displayName
+// is used in preference to relying on function.name.
+InterstitialScreen.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.
+InterstitialScreen.propTypes = {
+  /**
+   * The aria label applied to the Interstitial Screen component
+   */
+  ariaLabel: index.default.string,
+  children: index.default.node,
+  /**
+   * Provide an optional class to be applied to the containing node.
+   */
+  className: index.default.string,
+  /**
+   * Tooltip text and aria label for the Close button icon.
+   */
+  closeIconDescription: index.default.string,
+  /**
+   * Specifies whether the component is shown as a full-screen
+   * experience, else it is shown as a modal by default.
+   */
+  isFullScreen: index.default.bool,
+  /**
+   * Provide a ref to return focus to once the interstitial is closed.
+   */
+  launcherButtonRef: index.default.any,
+  /**
+   * Function to call when the close button is clicked.
+   */
+  onClose: index.default.func,
+  /**
+   * Specifies whether the component is currently open.
+   */
+  open: index.default.bool
+};
+
+exports.InterstitialScreen = InterstitialScreen;