@carbon/ibm-products
Version:
Carbon for IBM Products
223 lines (213 loc) • 8.68 kB
JavaScript
/**
* 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.
*/
import { extends as _extends } from '../../_virtual/_rollupPluginBabelHelpers.js';
import { Button } from '@carbon/react';
import React__default, { useRef, useState, Children, useMemo, useEffect } from 'react';
import { Carousel } from '../Carousel/Carousel.js';
import '../Carousel/CarouselItem.js';
import PropTypes from '../../_virtual/index.js';
import { clamp } from '../../global/js/utils/clamp.js';
import cx from 'classnames';
import { getDevtoolsProps } from '../../global/js/utils/devtools.js';
import pconsole from '../../global/js/utils/pconsole.js';
import { pkg } from '../../settings.js';
import '../Coachmark/Coachmark.js';
import { useCoachmark } from '../Coachmark/utils/context.js';
// The block part of our conventional BEM class names (blockClass__E--M).
const blockClass = `${pkg.prefix}--coachmark-overlay-elements`;
const 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
const defaults = {
isVisible: false,
nextButtonText: 'Next',
previousButtonLabel: 'Back',
closeButtonLabel: 'Got it',
onNext: undefined,
onBack: undefined,
currentStep: 0
};
/**
* Composable container to allow for the displaying of CoachmarkOverlayElement
* components in a carousel fashion.
*/
let CoachmarkOverlayElements = /*#__PURE__*/React__default.forwardRef((_ref, ref) => {
let {
className,
children,
isVisible = defaults.isVisible,
renderMedia,
currentStep = defaults.currentStep,
nextButtonText = defaults.nextButtonText,
previousButtonLabel = defaults.previousButtonLabel,
closeButtonLabel = defaults.closeButtonLabel,
onNext = defaults.onNext,
onBack = defaults.onBack,
// Collect any other property values passed in.
...rest
} = _ref;
const buttonFocusRef = useRef(undefined);
const scrollRef = useRef(undefined);
const [scrollPosition, setScrollPosition] = useState(0);
const [currentProgStep, _setCurrentProgStep] = useState(currentStep);
const coachmark = useCoachmark();
const setCurrentProgStep = value => {
if (currentProgStep > 0 && value === 0 && buttonFocusRef.current) {
setTimeout(() => {
buttonFocusRef.current?.focus();
}, 1000);
}
_setCurrentProgStep(value);
};
const numProgSteps = Children.count(children);
const progStepFloor = 0;
const progStepCeil = numProgSteps - 1;
const renderMediaContent = useMemo(() => renderMedia?.({
playStep: currentProgStep
}), [currentProgStep, renderMedia]);
useEffect(() => {
// When current step is set by props
// scroll to the appropriate view on the carrousel
const targetStep = clamp(currentStep, progStepFloor, progStepCeil);
scrollRef?.current?.scrollToView?.(targetStep);
// Avoid circular call to this hook
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [currentStep]);
useEffect(() => {
// 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();
}
}, []);
useEffect(() => {
setTimeout(() => {
if (buttonFocusRef.current && isVisible) {
buttonFocusRef.current.focus();
}
}, 100);
}, [isVisible]);
if (!coachmark) {
return pconsole.warn(`The ${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.createElement("section", _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.
// example: `${blockClass}__template-string-class-${kind}-n-${size}`,
{
// switched classes dependant on props or state
// example: [`${blockClass}__here-if-small`]: size === 'sm',
}),
ref: ref
}, getDevtoolsProps(componentName)), renderMedia && /*#__PURE__*/React__default.createElement("div", {
className: `${blockClass}__element-stepped-media`
}, renderMediaContent), numProgSteps === 1 ? /*#__PURE__*/React__default.createElement(React__default.Fragment, null, children, closeButtonLabel && /*#__PURE__*/React__default.createElement("div", {
className: cx(`${blockClass}__footer`, 'coachmark-carousel-controls')
}, /*#__PURE__*/React__default.createElement(Button, _extends({
size: "sm"
}, coachmark.closeButtonProps, {
ref: buttonFocusRef
}), closeButtonLabel))) : /*#__PURE__*/React__default.createElement(React__default.Fragment, null, /*#__PURE__*/React__default.createElement(Carousel, {
ref: scrollRef,
onScroll: scrollPercent => {
setScrollPosition(scrollPercent);
}
}, children), /*#__PURE__*/React__default.createElement("div", {
className: cx(`${blockClass}__footer`)
}, /*#__PURE__*/React__default.createElement("div", {
className: `${blockClass}--controls-progress`
}, `${currentProgStep + 1} / ${numProgSteps}`), scrollPosition > 0 && /*#__PURE__*/React__default.createElement(Button, {
size: "sm",
kind: "ghost",
title: previousButtonLabel,
disabled: scrollPosition === 0,
onClick: () => {
const targetStep = clamp(currentProgStep - 1, progStepFloor, progStepCeil);
scrollRef?.current?.scrollToView?.(targetStep);
setCurrentProgStep(targetStep);
onBack?.();
}
}, previousButtonLabel), currentProgStep < progStepCeil ? /*#__PURE__*/React__default.createElement(Button, {
size: "sm",
ref: buttonFocusRef,
title: nextButtonText,
disabled: scrollPosition === 1,
onClick: () => {
const targetStep = clamp(currentProgStep + 1, progStepFloor, progStepCeil);
scrollRef?.current?.scrollToView?.(targetStep);
setCurrentProgStep(targetStep);
onNext?.();
}
}, nextButtonText) : closeButtonLabel && /*#__PURE__*/React__default.createElement(Button, _extends({
size: "sm",
ref: buttonFocusRef
}, coachmark.closeButtonProps), closeButtonLabel))));
});
// Return a placeholder if not released and not enabled by feature flag
CoachmarkOverlayElements = pkg.checkComponentEnabled(CoachmarkOverlayElements, componentName);
// The display name of the component, used by React. Note that displayName
// is used in preference to relying on function.name.
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.
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: PropTypes.node.isRequired,
/**
* Optional class name for this component.
*/
className: PropTypes.string,
/**
* The label for the Close button.
*/
closeButtonLabel: PropTypes.string,
/**
* Current step of the coachmarks
*/
currentStep: PropTypes.number,
/**
* The visibility of CoachmarkOverlayElements is
* managed in the parent component.
*/
isVisible: PropTypes.bool,
/**
* The label for the Next button.
*/
nextButtonText: PropTypes.string,
/**
* Optional callback called when clicking on the Previous button.
*/
onBack: PropTypes.func,
/**
* Optional callback called when clicking on the Next button.
*/
onNext: PropTypes.func,
/**
* The label for the Previous button.
*/
previousButtonLabel: PropTypes.string,
/**
* Optional prop to render any media like images or animated media.
*/
renderMedia: PropTypes.func
};
export { CoachmarkOverlayElements };