@carbon/ibm-products
Version:
Carbon for IBM Products
260 lines (247 loc) • 10.4 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 React__default, { forwardRef, useRef, useContext, useState, useEffect, isValidElement } from 'react';
import PropTypes from '../../_virtual/index.js';
import cx from 'classnames';
import { Grid, Column, FormGroup } from '@carbon/react';
import { StepsContext, StepNumberContext } from './CreateTearsheet.js';
import { pkg } from '../../settings.js';
import pconsole from '../../global/js/utils/pconsole.js';
import { usePreviousValue } from '../../global/js/hooks/usePreviousValue.js';
import { useRetrieveStepData } from '../../global/js/hooks/useRetrieveStepData.js';
const componentName = 'CreateTearsheetStep';
const blockClass = `${pkg.prefix}--tearsheet-create__step`;
// Default values for props
const defaults = {
hasFieldset: true,
includeStep: true
};
/**
* Configuration options for customizing the behavior of the experimentalSecondary submit button.
*
* @property {string} [labelText] - Optional text to replace the default button text.
* @property {boolean} [disabled] - If true, the button will be disabled and not clickable.
* @property {boolean} [hideSecondarySubmit] - If true, the button will be hidden from view.
* @property {() => void} [onClick] - Optional click handler function to be executed when the button is clicked.
*/
let CreateTearsheetStep = /*#__PURE__*/forwardRef((_ref, ref) => {
let {
// The component props, in alphabetical order (for consistency).
children,
className,
description,
disableSubmit,
experimentalSecondarySubmit,
fieldsetLegendText,
hasFieldset = defaults.hasFieldset,
includeStep = defaults.includeStep,
introStep,
invalid,
onMount,
onNext,
onPrevious,
secondaryLabel,
subtitle,
title,
// Collect any other property values passed in.
...rest
} = _ref;
const localRef = useRef(null);
const stepRef = ref || localRef;
const stepRefValue = stepRef.current;
const stepsContext = useContext(StepsContext);
const stepNumber = useContext(StepNumberContext);
const [shouldIncludeStep, setShouldIncludeStep] = useState(includeStep);
const previousState = usePreviousValue({
currentStep: stepsContext?.currentStep
});
useRetrieveStepData({
stepsContext,
stepNumber,
introStep: !!introStep,
shouldIncludeStep,
secondaryLabel: secondaryLabel || '',
title,
invalid: !!invalid
});
// This useEffect reports back the onMount value so that they can be used
// in the appropriate custom hooks.
useEffect(() => {
if (stepNumber === stepsContext?.currentStep && previousState?.currentStep !== stepsContext?.currentStep) {
stepsContext?.setOnMount(onMount);
stepsContext?.setExperimentalSecondarySubmit(experimentalSecondarySubmit);
}
}, [onMount, experimentalSecondarySubmit, stepsContext, stepNumber, previousState?.currentStep]);
// Used to take the `includeStep` prop and use it as a local state value
useEffect(() => {
setShouldIncludeStep(includeStep);
}, [includeStep, stepsContext, title]);
const setFocusChildrenTabIndex = (childInputs, value) => {
if (childInputs?.length) {
childInputs.forEach(child => {
child.tabIndex = value;
});
}
};
// Whenever we are the current step, supply our disableSubmit and onNext values to the
// steps container context so that it can manage the 'Next' button appropriately.
useEffect(() => {
const focusElementQuery = `button, input, select, textarea, a`;
if (stepNumber !== stepsContext?.currentStep) {
// Specify tab-index -1 for focusable elements not contained
// in the current step so that the useFocus hook can exclude
// from the focus trap
const childInputs = stepRefValue?.querySelectorAll(focusElementQuery);
setFocusChildrenTabIndex(childInputs, -1);
}
if (stepNumber === stepsContext?.currentStep) {
// Specify tab-index 0 for current step focusable elements
// for the useFocus hook to know which elements to include
// in focus trap
const childInputs = stepRefValue?.querySelectorAll(focusElementQuery);
setFocusChildrenTabIndex(childInputs, 0);
stepsContext.setIsDisabled(!!disableSubmit);
stepsContext?.setOnNext(onNext); // needs to be updated here otherwise there could be stale state values from only initially setting onNext
stepsContext?.setOnPrevious(onPrevious);
//Handle props for experimentalSecondarySubmit button, depending on state change
stepsContext?.setExperimentalSecondarySubmit(experimentalSecondarySubmit);
}
}, [stepsContext, stepNumber, disableSubmit, onNext, onPrevious, stepRef, stepRefValue, experimentalSecondarySubmit]);
const renderDescription = () => {
if (description) {
if (typeof description === 'string') {
return /*#__PURE__*/React__default.createElement("p", {
className: `${blockClass}--description`
}, description);
}
if (/*#__PURE__*/isValidElement(description)) {
return /*#__PURE__*/React__default.createElement("div", {
className: `${blockClass}--description`
}, description);
}
}
return null;
};
return stepsContext ? /*#__PURE__*/React__default.createElement("div", {
ref: stepRef
}, /*#__PURE__*/React__default.createElement(Grid, _extends({}, rest, {
className: cx(blockClass, className, {
[`${blockClass}__step--hidden-step`]: stepNumber !== stepsContext?.currentStep,
[`${blockClass}__step--visible-step`]: stepNumber === stepsContext?.currentStep
})
}), /*#__PURE__*/React__default.createElement(Column, {
xlg: 12,
lg: 12,
md: 8,
sm: 4
}, /*#__PURE__*/React__default.createElement("h4", {
className: `${blockClass}--title`
}, title), subtitle && /*#__PURE__*/React__default.createElement("h6", {
className: `${blockClass}--subtitle`
}, subtitle), renderDescription()), /*#__PURE__*/React__default.createElement(Column, {
span: 100
}, hasFieldset ? /*#__PURE__*/React__default.createElement(FormGroup, {
legendText: fieldsetLegendText,
className: `${blockClass}--fieldset`
}, children) : children))) : pconsole.warn(`You have tried using a ${componentName} component outside of a CreateTearsheet. This is not allowed. ${componentName}s should always be children of the CreateTearsheet`);
});
// Return a placeholder if not released and not enabled by feature flag
CreateTearsheetStep = pkg.checkComponentEnabled(CreateTearsheetStep, componentName);
CreateTearsheetStep.propTypes = {
/**
* Content that shows in the tearsheet step
*/
children: PropTypes.node,
/**
* Sets an optional className to be added to the tearsheet step
*/
className: PropTypes.string,
/**
* Sets an optional description on the step component
*/
description: PropTypes.node,
/**
* This will conditionally disable the submit button in the multi step Tearsheet
*/
disableSubmit: PropTypes.bool,
/**
* Configuration options for customizing the behavior of the experimentalSecondary submit button.
*
* @property {string} [labelText] - Optional text to replace the default button text.
* @property {boolean} [disabled] - If true, the button will be disabled and not clickable.
* @property {boolean} [hideSecondarySubmit] - If true, the button will be hidden from view.
* @property {() => void} [onClick] - Optional click handler function to be executed when the button is clicked.
*/
/**@ts-ignore*/
experimentalSecondarySubmit: PropTypes.shape({
labelText: PropTypes.string,
disabled: PropTypes.bool,
hideSecondarySubmit: PropTypes.bool,
onClick: PropTypes.func
}),
/**
* This is the required legend text that appears above a fieldset html element for accessibility purposes.
* You can set the `hasFieldset` prop to false if you have multiple fieldset elements or want to control the children of your Full Page's step content.
* Otherwise, use CSS to hide/remove this label text.
*/
/**@ts-ignore*/
fieldsetLegendText: PropTypes.string.isRequired.if(_ref2 => {
let {
hasFieldset
} = _ref2;
return !!hasFieldset;
}),
/**
* This optional prop will render your form content inside of a fieldset html element
* and is defaulted to true.
* You can set this prop to `false` if you have multiple fieldset elements or want to control the children of your Full Page's step content.
*/
/**@ts-ignore*/
hasFieldset: PropTypes.bool,
/**
* This prop is used to help track dynamic steps. If this value is `false` then the step is not included in the visible steps or the ProgressIndicator
* steps. If this value is `true` then the step will be included in the list of visible steps, as well as being included in the ProgressIndicator step list
*/
includeStep: PropTypes.bool,
/**
* This prop can be used on the first step to mark it as an intro step, which will not render the progress indicator steps
*/
introStep: PropTypes.bool,
/**
* This optional prop will indicate an error icon on the progress indicator step item
*/
invalid: PropTypes.bool,
/**
* Optional function to be called on initial mount of a step.
* For example, this can be used to fetch data that is required on a particular step.
*/
onMount: PropTypes.func,
/**
* Optional function to be called when you move to the next step.
* For example, this can be used to validate input fields before proceeding to the next step.
* This function can _optionally_ return a promise that is either resolved or rejected and the CreateTearsheet will handle the submitting state of the next button.
*/
onNext: PropTypes.func,
/**
* Optional function to be called when you move to the previous step.
*/
onPrevious: PropTypes.func,
/**
* Sets the optional secondary label on the progress step component
*/
secondaryLabel: PropTypes.string,
/**
* Sets an optional subtitle on the step component
*/
subtitle: PropTypes.string,
/**
* Sets the title text for a tearsheet step
*/
title: PropTypes.node.isRequired
};
export { CreateTearsheetStep };