@carbon/ibm-products
Version:
Carbon for IBM Products
274 lines (261 loc) • 10.3 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.
*/
;
var _rollupPluginBabelHelpers = require('../../_virtual/_rollupPluginBabelHelpers.js');
var react = require('@carbon/react');
var Checklist_types = require('./Checklist.types.js');
var React = require('react');
var ChecklistChart = require('./ChecklistChart.js');
var ChecklistIcon = require('./ChecklistIcon.js');
var icons = require('@carbon/react/icons');
var index = require('../../_virtual/index.js');
var cx = require('classnames');
var devtools = require('../../global/js/utils/devtools.js');
var settings = require('../../settings.js');
var uuidv4 = require('../../global/js/utils/uuidv4.js');
// The block part of our conventional BEM class names (blockClass__E--M).
const blockClass = `${settings.pkg.prefix}--checklist`;
const componentName = 'Checklist';
// 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 = {
checklistAriaLabel: 'Checklist',
checklistToggleAriaLabel: 'Checklist toggle',
onClickViewAll: () => {},
onToggle: () => {},
open: true,
enableToggle: true,
taskLists: [],
theme: Checklist_types.Themes.light,
toggleLabel: 'Toggle'
};
/**
* The Checklist tracks a user's progress much like Your Learning or
* WalkMe. Each item in the list can be clickable, and each item has
* an icon that defines the item's state as "not started", "in progress",
* and "complete".
*/
exports.Checklist = /*#__PURE__*/React.forwardRef((_ref, ref) => {
let {
chartValue,
chartLabel,
checklistAriaLabel = defaults.checklistAriaLabel,
checklistToggleAriaLabel = defaults.checklistToggleAriaLabel,
className,
onClickViewAll = defaults.onClickViewAll,
onToggle = defaults.onToggle,
open = defaults.open,
enableToggle = defaults.enableToggle,
taskLists = defaults.taskLists,
theme = defaults.theme,
title,
toggleLabel = defaults.toggleLabel,
toggleLabelAlign = 'top',
viewAllLabel,
...rest
} = _ref;
const [isOpen, setIsOpen] = React.useState(open);
const listContainerId = React.useRef(uuidv4.default()).current;
const chartLabelId = React.useRef(uuidv4.default()).current;
// Don't use this test: {chartValue && chartLabel && (render...)}.
// If `chartValue` is 0 (zero) - a valid value - then it will render 0 and skip the remaining statement.
// Use this test instead: {chartLabelAndValue && (render...)}.
// The ChecklistChart component will validate `chartValue`.
const chartLabelAndValue = typeof chartValue === 'number' && chartLabel;
const handleClickToggle = () => {
setIsOpen(prevOpen => !prevOpen);
};
const handleClickViewAll = () => {
onClickViewAll();
};
// If state changes, then trigger callback.
React.useEffect(() => {
onToggle(isOpen);
}, [isOpen, onToggle]);
// If the "open" prop is changed after initialization,
// then update internal state.
React.useEffect(() => {
setIsOpen(open);
}, [open]);
return /*#__PURE__*/React.createElement(react.Section, _rollupPluginBabelHelpers.extends({}, rest, {
"aria-label": checklistAriaLabel,
as: "aside",
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}`,
{
[`${blockClass}__closed`]: !isOpen
}),
ref: ref
}, devtools.getDevtoolsProps(componentName)), (title || chartLabelAndValue) && /*#__PURE__*/React.createElement("header", {
className: `${blockClass}__header`
}, chartLabelAndValue && /*#__PURE__*/React.createElement(ChecklistChart.ChecklistChart, {
"aria-labelledby": chartLabelId,
theme: theme,
value: chartValue
}), /*#__PURE__*/React.createElement("div", {
className: `${blockClass}__titles`
}, title && /*#__PURE__*/React.createElement(react.Heading, {
className: `${blockClass}__title`
}, title), chartLabelAndValue && /*#__PURE__*/React.createElement("p", {
id: chartLabelId,
className: `${blockClass}__chart-label`
}, chartLabel)), enableToggle && /*#__PURE__*/React.createElement(react.IconButton, {
align: toggleLabelAlign,
"aria-controls": listContainerId,
"aria-expanded": isOpen,
"aria-label": checklistToggleAriaLabel,
className: `${blockClass}__toggle`,
kind: "ghost",
label: toggleLabel,
onClick: handleClickToggle,
size: "sm"
}, /*#__PURE__*/React.createElement(icons.ChevronUp, {
size: 16,
className: cx(`${blockClass}__chevron`)
}))), /*#__PURE__*/React.createElement("div", {
id: listContainerId,
className: `${blockClass}__content-outer`
}, /*#__PURE__*/React.createElement("div", {
className: `${blockClass}__content-inner`
}, /*#__PURE__*/React.createElement("div", {
className: cx(`${blockClass}__body`)
}, taskLists.map((list, index) => {
return /*#__PURE__*/React.createElement(react.Section, {
className: `${blockClass}__list-group`,
key: `${list.title}-${index}`
}, list.title && /*#__PURE__*/React.createElement(react.Heading, {
title: list.title,
className: `${blockClass}__list-title`
}, list.title), /*#__PURE__*/React.createElement("ol", {
className: `${blockClass}__list`
}, list.tasks.map((item, index) => {
return /*#__PURE__*/React.createElement("li", {
className: `${blockClass}__list-item`,
key: `${item.label}-${index}`
}, /*#__PURE__*/React.createElement(ChecklistIcon.ChecklistIcon, {
kind: item.kind,
theme: theme
}), typeof item.onClick === 'function' ? /*#__PURE__*/React.createElement(react.Button, {
className: cx(`${blockClass}__button`, {
[`${blockClass}__button--error`]: item.kind === 'error'
}),
onClick: () => {
item.onClick?.(item);
},
size: "sm",
title: item.label
}, /*#__PURE__*/React.createElement("div", null, item.label)) : /*#__PURE__*/React.createElement("div", {
className: cx(`${blockClass}__label`, `${blockClass}__label--${item.kind}`),
title: item.label
}, item.label));
})));
})), viewAllLabel && /*#__PURE__*/React.createElement("footer", {
className: `${blockClass}__footer`
}, /*#__PURE__*/React.createElement(react.Button, {
className: cx(`${blockClass}__button`, `${blockClass}__view-all`),
onClick: handleClickViewAll,
size: "sm"
}, /*#__PURE__*/React.createElement("div", null, viewAllLabel))))));
});
// Return a placeholder if not released and not enabled by feature flag
exports.Checklist = settings.pkg.checkComponentEnabled(exports.Checklist, componentName);
exports.Checklist.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.Checklist.propTypes = {
/**
* Define both `chartLabel` and `chartValue` to show the chart and its label together.
*/
chartLabel: index.default.string,
/**
* A number between 0 and 1.
*
* Define both `chartLabel` and `chartValue` to show the chart and its label together.
*/
chartValue: index.default.number,
/**
* Aria-label for the Checklist component.
*/
checklistAriaLabel: index.default.string,
/**
* Aria-label for the Checklist's toggle component.
*/
checklistToggleAriaLabel: index.default.string,
/**
* Provide an optional class to be applied to the containing node.
*/
className: index.default.string,
/**
* Whether or not to show the open/close toggle.
*/
enableToggle: index.default.bool,
/**
* Callback for the "View all" button. See also `viewAllLabel`.
*/
onClickViewAll: index.default.func,
/**
* Optional callback for when the list is opened/closed.
*/
onToggle: index.default.func,
/**
* Specifies whether the component is opened or closed.
* This can be set during initialization, or changed after being rendered.
*/
open: index.default.bool,
/**
* The task list can be broken down into sub-lists.
*
* Each sub-list can include an optional `title`.
*
* Each task must specify the appropriate icon (`kind`) and `label`.
*
* If any task has an `onClick` callback function defined,
* then the `label` will be rendered as a button,
* else the `label` will be rendered as plain text.
*/
/**@ts-ignore */
taskLists: index.default.arrayOf(index.default.shape({
title: index.default.string,
tasks: index.default.arrayOf(index.default.shape({
kind: index.default.oneOf([Checklist_types.Kinds.unchecked, Checklist_types.Kinds.indeterminate, Checklist_types.Kinds.checked, Checklist_types.Kinds.disabled, Checklist_types.Kinds.error]).isRequired,
label: index.default.string.isRequired,
onClick: index.default.func
})).isRequired
})).isRequired,
/**
* Determines the theme of the component.
*/
theme: index.default.oneOf([Checklist_types.Themes.light, Checklist_types.Themes.dark]),
/**
* The title of the component.
*/
title: index.default.node,
/**
* The label for the toggle's tooltip.
*/
toggleLabel: index.default.string,
/**
* The alignment of the toggle's tooltip.
*/
toggleLabelAlign: index.default.oneOf(['top', 'top-left', 'top-right', 'bottom', 'bottom-left', 'bottom-right', 'left', 'right']),
/**
* If defined, will show and enable the "View all (#)" button at the bottom of the list.
*/
viewAllLabel: index.default.string
};