@carbon/ibm-products 2.71.1 → 2.72.0

package/lib/components/Coachmark/next/Coachmark/Coachmark.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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, { FC, ForwardRefExoticComponent, ReactNode, RefAttributes, RefObject } from 'react';
+import { CoachmarkContentProps } from './CoachmarkContent';
+import { NewPopoverAlignment } from '@carbon/react';
+export declare const blockClass: string;
+export interface CoachmarkProps {
+    /**
+     * Provide the contents of the Coachmark.
+     */
+    children: ReactNode;
+    /**
+     * Provide an optional class to be applied to the containing node.
+     */
+    className?: string;
+    /**
+     * The aria label applied to the Coachmark component
+     */
+    ariaLabel?: string;
+    /**
+     * Specifies whether the component is currently open.
+     */
+    open?: boolean;
+    /**
+     * Function to call when the close button is clicked.
+     */
+    onClose?: () => void;
+    /**
+     * Where to render the Coachmark relative to its target.
+     */
+    align?: NewPopoverAlignment;
+    /**
+     * Fine tune the position of the target in pixels.
+     */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Specifies whether the component is floating or not.
+     */
+    floating?: boolean;
+}
+export type CoachmarkComponent = ForwardRefExoticComponent<CoachmarkProps & RefAttributes<HTMLDivElement>> & {
+    Content: FC<CoachmarkContentProps>;
+};
+interface CoachmarkContextType {
+    onClose?: () => void;
+    open?: boolean;
+    setOpen: (value: boolean) => void;
+    align?: NewPopoverAlignment;
+    triggerRef: RefObject<HTMLElement | null>;
+    position: {
+        x: number;
+        y: number;
+    };
+    contentRef: HTMLElement | null;
+    setContentRef: (value: any) => void;
+    floating?: boolean;
+}
+export declare const CoachmarkContext: React.Context<CoachmarkContextType>;
+/**
+ * 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.
+ */
+export declare const Coachmark: CoachmarkComponent;
+export {};

package/lib/components/Coachmark/next/Coachmark/Coachmark.js

@@ -0,0 +1,189 @@
+/**
+ * Copyright IBM Corp. 2020, 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.
+ */
+
+'use strict';
+
+var _rollupPluginBabelHelpers = require('../../../../_virtual/_rollupPluginBabelHelpers.js');
+var React = require('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 CoachmarkContent = require('./CoachmarkContent.js');
+var useIsomorphicEffect = require('../../../../global/js/hooks/useIsomorphicEffect.js');
+
+// The block part of our conventional BEM class names (blockClass__E--M).
+const blockClass = `${settings.pkg.prefix}--coachmark__next`;
+const componentName = 'Coachmark';
+
+// 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.
+
+// Define the type for Coachmark, extending it to include Trigger and Content
+
+const CoachmarkContext = /*#__PURE__*/React.createContext({
+  open: false,
+  setOpen: () => {},
+  align: 'bottom',
+  triggerRef: {
+    current: null
+  },
+  position: {
+    x: 0,
+    y: 0
+  },
+  contentRef: null,
+  setContentRef: value => {},
+  floating: false
+});
+/**
+ * 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.
+ */
+const Coachmark = /*#__PURE__*/React.forwardRef((props, ref) => {
+  const {
+    children,
+    className,
+    ariaLabel,
+    onClose,
+    align = 'bottom',
+    open,
+    position = {
+      x: 0,
+      y: 0
+    },
+    floating,
+    ...rest
+  } = props;
+  const triggerRef = React.useRef(null);
+  const internalRef = React.useRef(null);
+  const [contentRef, setContentRef] = React.useState(null);
+  const [openState, setOpenState] = React.useState(false);
+  const setOpen = value => {
+    if (!value) {
+      onClose?.();
+    }
+    if (open === undefined) {
+      setOpenState(value);
+    }
+  };
+  const currentOpen = open ?? openState;
+  React.useEffect(() => {
+    const container = internalRef.current;
+    if (!container) {
+      return;
+    }
+    const focusableElements = Array.from(container.querySelectorAll('*'));
+    const firstFocusable = focusableElements.find(el => el.tabIndex >= 0 && !el.hasAttribute('disabled'));
+    if (firstFocusable) {
+      triggerRef.current = firstFocusable;
+    }
+  }, [children]);
+  useIsomorphicEffect.useIsomorphicEffect(() => {
+    const {
+      x = 0,
+      y = 0
+    } = position ?? {};
+    const el = internalRef.current;
+    if (el && (x !== 0 || y !== 0)) {
+      el.style.transform = `translate(${x}px, ${y}px)`;
+    }
+  }, [position]);
+  const setRef = node => {
+    internalRef.current = node;
+    if (typeof ref === 'function') {
+      ref(node);
+    } else if (ref) {
+      ref.current = node;
+    }
+  };
+  return /*#__PURE__*/React.createElement(CoachmarkContext.Provider, {
+    value: {
+      onClose,
+      open: currentOpen,
+      setOpen,
+      align,
+      triggerRef,
+      position,
+      contentRef,
+      setContentRef,
+      floating
+    }
+  }, /*#__PURE__*/React.createElement("div", _rollupPluginBabelHelpers.extends({}, rest, {
+    className: cx(blockClass,
+    // Apply the block class to the main HTML element
+    className,
+    // Apply any supplied class names to the main HTML element.
+    {
+      [`${blockClass}--floating`]: floating
+    }),
+    "aria-label": ariaLabel,
+    ref: setRef
+  }, devtools.getDevtoolsProps(componentName)), /*#__PURE__*/React.createElement("div", {
+    className: `${blockClass}--container`
+  }, children)));
+});
+Coachmark.Content = CoachmarkContent.default;
+
+// The display name of the component, used by React. Note that displayName
+// is used in preference to relying on function.name.
+Coachmark.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.
+Coachmark.propTypes = {
+  /**
+   * Where to render the Coachmark relative to its target.
+   */
+  align: index.default.string,
+  /**
+   * The aria label applied to the Coachmark component
+   */
+  ariaLabel: index.default.string,
+  /**
+   * Provide the contents of the CoachmarkV2.
+   */
+  children: index.default.node.isRequired,
+  /**
+   * Provide an optional class to be applied to the containing node.
+   */
+  className: index.default.string,
+  /**
+   * Specifies whether the component is currently open.
+   */
+  defaultOpen: index.default.bool,
+  /**
+   * Specifies whether the component is floating or not.
+   */
+  floating: index.default.bool,
+  /**
+   * Function to call when the close button is clicked.
+   */
+  onClose: index.default.func,
+  /**
+   * Fine tune the position of the target in pixels. Applies only to Beacons.
+   */
+  // @ts-ignore
+  position: index.default.shape({
+    x: index.default.number,
+    y: index.default.number
+  })
+};
+
+exports.Coachmark = Coachmark;
+exports.CoachmarkContext = CoachmarkContext;
+exports.blockClass = blockClass;

package/lib/components/Coachmark/next/Coachmark/CoachmarkBeacon/CoachmarkBeacon.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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, { ElementType } from 'react';
+import { ButtonProps } from '@carbon/react';
+/**
+ * Reserved for future expansion, i.e. "RING".
+ */
+export declare enum BEACON_KIND {
+    DEFAULT = "default"
+}
+export interface CoachmarkButtonProps extends ButtonProps<ElementType> {
+    onClick?(): void;
+    onDoubleClick?(): void;
+    tabIndex?: number;
+    ['aria-expanded']?: boolean;
+}
+export interface CoachmarkBeaconProps {
+    /**
+     * Optional class name for this component.
+     */
+    className?: string;
+    /**
+     * What style of beacon.
+     * BEACON_KIND is an enum from the Coachmark and can be used for this value.
+     * @see {@link BEACON_KIND}
+     */
+    kind?: BEACON_KIND;
+    /**
+     * The aria label.
+     */
+    label: string;
+    /**
+     * button props
+     */
+    buttonProps?: CoachmarkButtonProps;
+}
+/**
+ * Use beacon for the target prop of a Coachmark component.
+ */
+export declare const CoachmarkBeacon: React.ForwardRefExoticComponent<CoachmarkBeaconProps & React.RefAttributes<HTMLDivElement>>;

package/lib/components/Coachmark/next/Coachmark/CoachmarkBeacon/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export { CoachmarkBeacon } from './CoachmarkBeacon';
+export type { CoachmarkBeaconProps } from './CoachmarkBeacon';

package/lib/components/Coachmark/next/Coachmark/CoachmarkBubble/CoachmarkBubble.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 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 { NewPopoverAlignment } from '@carbon/react';
+import React, { HTMLProps, RefObject } from 'react';
+interface BubbleProps extends Omit<HTMLProps<HTMLDivElement>, 'target'> {
+    /**
+     * 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-end' | 'left-start' | 'right-end' | 'right-start';
+     **/
+    align?: NewPopoverAlignment;
+    /**
+     * Values can range from an Element, a ref of an Element, a string which will use query selector to select an Element.
+     **/
+    target: Element | RefObject<Element> | string | null | undefined;
+    /**
+     * Specify whether the component should be rendered on high-contrast.
+     */
+    highContrast?: boolean;
+    /**
+     * Specify whether a drop shadow should be rendered on the popover.
+     */
+    dropShadow?: boolean;
+    /**
+     * Specifies whether the component is currently open.
+     */
+    open: boolean;
+    /**
+     * Specify whether a caret should be rendered.
+     */
+    caret?: boolean;
+}
+declare const CoachmarkBubble: React.ForwardRefExoticComponent<Omit<BubbleProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export { CoachmarkBubble };

package/lib/components/Coachmark/next/Coachmark/CoachmarkBubble/CoachmarkBubble.js

@@ -0,0 +1,127 @@
+/**
+ * Copyright IBM Corp. 2020, 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.
+ */
+
+'use strict';
+
+var _rollupPluginBabelHelpers = require('../../../../../_virtual/_rollupPluginBabelHelpers.js');
+var cx = require('classnames');
+var react = require('@carbon/react');
+var React = require('react');
+var settings = require('../../../../../settings.js');
+var floatingUi_reactDom = require('../../../../../node_modules/@floating-ui/react-dom/dist/floating-ui.react-dom.js');
+var floatingUi_dom = require('../../../../../node_modules/@floating-ui/dom/dist/floating-ui.dom.js');
+
+const CoachmarkBubble = /*#__PURE__*/React.forwardRef(props => {
+  const {
+    children,
+    align,
+    target,
+    className,
+    dropShadow = true,
+    highContrast = false,
+    caret = false,
+    open,
+    ...rest
+  } = props;
+  const {
+    theme
+  } = react.useTheme();
+  const carbonPrefix = react.usePrefix();
+  const tooltipRef = React.useRef(null);
+  const arrowRef = React.useRef(null);
+  const targetRef = React.useRef(null);
+  React.useLayoutEffect(() => {
+    if (target) {
+      if (typeof target === 'string') {
+        targetRef.current = document.querySelector(target);
+      } else if ('current' in target) {
+        targetRef.current = target.current;
+      } else {
+        targetRef.current = target;
+      }
+      if (targetRef.current && tooltipRef.current && arrowRef.current && open) {
+        targetRef.current.scrollIntoView({
+          behavior: 'smooth',
+          block: 'center',
+          inline: 'center'
+        });
+        const middlewares = [floatingUi_reactDom.offset(10), floatingUi_reactDom.flip(), floatingUi_reactDom.shift({
+          padding: 5
+        }), floatingUi_reactDom.arrow({
+          element: arrowRef.current
+        })];
+        const cleanup = floatingUi_dom.autoUpdate(targetRef.current, tooltipRef.current, () => {
+          if (targetRef.current && tooltipRef.current) {
+            floatingUi_dom.computePosition(targetRef.current, tooltipRef.current, {
+              placement: align,
+              strategy: 'fixed',
+              middleware: middlewares
+            }).then(_ref => {
+              let {
+                x,
+                y,
+                placement,
+                middlewareData
+              } = _ref;
+              if (tooltipRef.current) {
+                Object.assign(tooltipRef.current.style, {
+                  left: `${x}px`,
+                  top: `${y}px`
+                });
+              }
+              const arrowX = middlewareData.arrow?.x;
+              const arrowY = middlewareData.arrow?.y;
+              const staticSide = {
+                top: 'bottom',
+                right: 'left',
+                bottom: 'top',
+                left: 'right'
+              }[placement.split('-')[0]];
+              if (staticSide && arrowRef.current) {
+                Object.assign(arrowRef.current.style, {
+                  left: arrowX != null ? `${arrowX}px` : '',
+                  top: arrowY != null ? `${arrowY}px` : '',
+                  right: '',
+                  bottom: '',
+                  [staticSide]: '-4px'
+                });
+              }
+            });
+          }
+        }, {
+          animationFrame: true
+        });
+        return () => {
+          cleanup();
+        };
+      }
+    }
+  }, [target, open, align]);
+  if (!target) {
+    return null;
+  }
+  return /*#__PURE__*/React.createElement("div", _rollupPluginBabelHelpers.extends({}, rest, {
+    ref: tooltipRef,
+    className: cx({
+      [`${carbonPrefix}--g100`]: theme === 'white' && highContrast || theme === 'g100' && !highContrast,
+      [`${carbonPrefix}--g90`]: theme === 'g10' && highContrast || theme === 'g90' && !highContrast,
+      [`${carbonPrefix}--g10`]: theme === 'g90' && highContrast || theme === 'g10' && !highContrast,
+      [`${carbonPrefix}--white`]: theme === 'g100' && highContrast || theme === 'white' && !highContrast,
+      [`${settings.pkg.prefix}__bubble`]: true,
+      [`${settings.pkg.prefix}__bubble-open`]: open,
+      [`${settings.pkg.prefix}__bubble-drop-shadow`]: dropShadow,
+      [`${settings.pkg.prefix}__bubble-high-contrast`]: highContrast,
+      [`${settings.pkg.prefix}__bubble-hidden`]: !targetRef.current
+    }, className)
+  }), /*#__PURE__*/React.createElement("div", {
+    ref: arrowRef,
+    className: !caret ? `${settings.pkg.prefix}__bubble__arrow` : ''
+  }), children);
+});
+CoachmarkBubble.displayName = 'CoachmarkBubble';
+
+exports.CoachmarkBubble = CoachmarkBubble;

package/lib/components/Coachmark/next/Coachmark/CoachmarkBubble/CoachmarkBubbleHeader.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 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, { HTMLProps, ReactNode } from 'react';
+interface BubbleHeaderProps extends HTMLProps<HTMLElement> {
+    /**
+     * Provide the contents of the Bubble header
+     */
+    children: ReactNode;
+    /**
+     * Provide an optional class to be applied to the containing node.
+     */
+    className?: string;
+}
+declare const CoachmarkBubbleHeader: {
+    ({ children, className, ...rest }: BubbleHeaderProps): React.JSX.Element;
+    displayName: string;
+};
+export { CoachmarkBubbleHeader };

package/lib/components/Coachmark/next/Coachmark/CoachmarkBubble/CoachmarkBubbleHeader.js

@@ -0,0 +1,27 @@
+/**
+ * Copyright IBM Corp. 2020, 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.
+ */
+
+'use strict';
+
+var _rollupPluginBabelHelpers = require('../../../../../_virtual/_rollupPluginBabelHelpers.js');
+var React = require('react');
+var cx = require('classnames');
+var settings = require('../../../../../settings.js');
+
+const CoachmarkBubbleHeader = _ref => {
+  let {
+    children,
+    className,
+    ...rest
+  } = _ref;
+  return /*#__PURE__*/React.createElement("header", _rollupPluginBabelHelpers.extends({}, rest, {
+    className: cx(`${settings.pkg.prefix}__bubble__header`, className)
+  }), children);
+};
+CoachmarkBubbleHeader.displayName = 'CoachmarkBubbleHeader';
+
+exports.CoachmarkBubbleHeader = CoachmarkBubbleHeader;

package/lib/components/Coachmark/next/Coachmark/CoachmarkBubble/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 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.
+ */
+export { CoachmarkBubble } from './CoachmarkBubble';
+export { CoachmarkBubbleHeader } from './CoachmarkBubbleHeader';

package/lib/components/Coachmark/next/Coachmark/CoachmarkContent.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 { FC, ForwardRefExoticComponent, ReactElement, ReactNode, RefAttributes } from 'react';
+import { ContentHeaderProps } from './ContentHeader';
+import { ContentBodyProps } from './ContentBody';
+export interface CoachmarkContentProps {
+    /**
+     * Provide an optional class to be applied to the containing node.
+     */
+    className?: string;
+    /**
+     * This is a required callback that has to return the content to render in the body section.
+     * It can be a single child or an array of children depending on your need
+     */
+    children: ReactElement | ReactNode;
+    /**
+     * Specify whether the component should be rendered on high-contrast.
+     */
+    highContrast?: boolean;
+    /**
+     * Specify whether a drop shadow should be rendered on the popover.
+     */
+    dropShadow?: boolean;
+}
+export type CoachmarkContentComponent = ForwardRefExoticComponent<CoachmarkContentProps & RefAttributes<HTMLDivElement>> & {
+    Header: FC<ContentHeaderProps>;
+    Body: FC<ContentBodyProps>;
+};
+declare const CoachmarkContent: CoachmarkContentComponent;
+export default CoachmarkContent;