` attributes and properties
+
+${children}
+ `;
+};
+
+singleLine.storyName = 'Single line';
+
+singleLine.parameters = {
+ knobs: defaultKnobs,
+};
+
+export const multiLine = (args) => {
+ const {
+ codeAssistiveText,
+ copyButtonAssistiveText,
+ copyButtonFeedbackText,
+ copyButtonFeedbackTimeout,
+ collapseButtonText,
+ expandButtonText,
+ colorScheme,
+ onClick,
+ } = args?.['bx-code-snippet'] ?? {};
+ const children = `
+@mixin grid-container {
+ width: 100%;
+ padding-right: padding(mobile);
+ padding-left: padding(mobile);
+
+ @include breakpoint(bp--xs--major) {
+ padding-right: padding(xs);
+ padding-left: padding(xs);
+ }
+}
+
+$z-indexes: (
+ modal : 9000,
+ overlay : 8000,
+ dropdown : 7000,
+ header : 6000,
+ footer : 5000,
+ hidden : - 1,
+ overflowHidden: - 1,
+ floating: 10000
+);
+`.trim();
+ // prettier-ignore
+ return html`
+ ${children}
+`;
+};
+
+multiLine.storyName = 'Multi line';
+
+multiLine.parameters = {
+ knobs: {
+ 'bx-code-snippet': () => ({
+ ...defaultKnobs['bx-code-snippet'](),
+ collapseButtonText: textNullable(
+ 'The text for the collapse button (collapse-button-text)',
+ ''
+ ),
+ expandButtonText: textNullable(
+ 'The text for the expand button (expand-button-text)',
+ ''
+ ),
+ }),
+ },
+};
+
+export const inline = (args) => {
+ const {
+ codeAssistiveText,
+ copyButtonAssistiveText,
+ copyButtonFeedbackText,
+ copyButtonFeedbackTimeout,
+ colorScheme,
+ onClick,
+ } = args?.['bx-code-snippet'] ?? {};
+ return html`
+ node -v
+ `;
+};
+
+inline.storyName = 'Inline';
+
+inline.parameters = {
+ knobs: defaultKnobs,
+};
+
+export const skeletonSingleLine = () =>
+ html` ` here is inside a scrolling container
+ content: none;
+ }
+
+ code {
+ overflow: hidden;
+ }
+ }
+ }
+
+ .#{$prefix}-ce--snippet-container--expanded {
+ max-height: rem(1500px);
+ transition: max-height $duration--moderate-01 motion(standard, productive);
+
+ pre {
+ overflow-x: auto;
+ }
+ }
+}
+
+:host(#{$prefix}-code-snippet[type='inline']) {
+ display: inline-flex;
+ width: auto;
+ height: auto;
+ min-width: auto;
+ max-width: auto;
+ padding: 0;
+
+ &::after {
+ content: none;
+ }
+
+ .#{$prefix}--btn--copy__feedback {
+ // Half of the diagonal line of `0.6rem` square
+ top: rem(6.7882px);
+ }
+}
+
+:host(#{$prefix}-code-snippet-skeleton) {
+ @extend .#{$prefix}--skeleton;
+
+ span {
+ @include skeleton;
+
+ width: 100%;
+ height: 1rem;
+ display: block;
+ margin-top: 0.5rem;
+
+ &:first-child {
+ margin: 0;
+ }
+
+ &:nth-child(2) {
+ width: 85%;
+ }
+
+ &:nth-child(3) {
+ width: 95%;
+ }
+ }
+}
diff --git a/packages/carbon-web-components/src/components/code-snippet/code-snippet.ts b/packages/carbon-web-components/src/components/code-snippet/code-snippet.ts
new file mode 100644
index 00000000000..4a090f6f94b
--- /dev/null
+++ b/packages/carbon-web-components/src/components/code-snippet/code-snippet.ts
@@ -0,0 +1,301 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019, 2022
+ *
+ * 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 { classMap } from 'lit-html/directives/class-map';
+import { TemplateResult } from 'lit-html';
+import { html, property, query, customElement, LitElement } from 'lit-element';
+import ChevronDown16 from '@carbon/icons/lib/chevron--down/16';
+import settings from 'carbon-components/es/globals/js/settings';
+import FocusMixin from '../../globals/mixins/focus';
+import {
+ _createHandleFeedbackTooltip as createHandleCopyButtonFeedbackTooltip,
+ _renderButton as renderCopyButton,
+} from '../copy-button/copy-button';
+import { CODE_SNIPPET_COLOR_SCHEME, CODE_SNIPPET_TYPE } from './defs';
+import styles from './code-snippet.scss';
+
+export { CODE_SNIPPET_COLOR_SCHEME, CODE_SNIPPET_TYPE };
+
+const { prefix } = settings;
+
+/**
+ * @param values The values to render.
+ * @param values.children The child nodes.
+ * @param values.handleClick The handler for the `click` event on the button.
+ * @returns The template result for the expando.
+ */
+const renderExpando = ({
+ children,
+ handleClick,
+}: {
+ children: string | TemplateResult;
+ handleClick: EventListener;
+}) => html`
+
+
+ ${children}
+
+ ${ChevronDown16({
+ 'aria-labeledby': 'button-text',
+ class: `${prefix}--icon-chevron--down ${prefix}--snippet__icon`,
+ role: 'img',
+ })}
+
+`;
+
+/**
+ * @param values The values to render.
+ * @param values.assistiveText The assistive text to announce that the node is for code snippet.
+ * @param [values.expanded] `true` to show the expanded state (for multi-line variant).
+ * @param values.children The child nodes.
+ * @returns The template result for the code snippet.
+ */
+const renderCode = ({
+ assistiveText,
+ expanded,
+ children,
+}: {
+ assistiveText: string;
+ expanded?: boolean;
+ children: string | TemplateResult;
+}) => {
+ const classes = classMap({
+ [`${prefix}--snippet-container`]: true,
+ [`${prefix}-ce--snippet-container--expanded`]: Boolean(expanded),
+ });
+ // Ensures no extra whitespace text node
+ // prettier-ignore
+ return html`
+
+ `;
+};
+
+/**
+ * Basic code snippet.
+ *
+ * @element bx-code-snippet
+ */
+@customElement(`${prefix}-code-snippet`)
+class BXCodeSnippet extends FocusMixin(LitElement) {
+ /**
+ * `true` to expand multi-line variant of code snippet.
+ */
+ private _expanded = false;
+
+ /**
+ * `true` to show the feedback tooltip.
+ */
+ private _showCopyButtonFeedback = false;
+
+ /**
+ * `true` to show the expando.
+ */
+ private _showExpando = false;
+
+ /**
+ * Handles `click` event on the copy button.
+ */
+ private _handleClickCopyButton() {
+ const { ownerDocument: doc } = this;
+ const selection = doc!.defaultView!.getSelection();
+ selection!.removeAllRanges();
+ const code = doc!.createElement('code');
+ code.className = `${prefix}--visually-hidden`;
+ const pre = doc!.createElement('pre');
+ pre.textContent = this.textContent;
+ code.appendChild(pre);
+ // Using `` in shadow DOM seems to lose the LFs in some browsers
+ doc!.body.appendChild(code);
+ const range = doc!.createRange();
+ range.selectNodeContents(code);
+ selection!.addRange(range);
+ doc!.execCommand('copy');
+ this._handleCopyButtonFeedbackTooltip(this.copyButtonFeedbackTimeout);
+ doc!.body.removeChild(code);
+ selection!.removeAllRanges();
+ }
+
+ /**
+ * Handles showing/hiding the feedback tooltip.
+ */
+ private _handleCopyButtonFeedbackTooltip =
+ createHandleCopyButtonFeedbackTooltip(
+ ({ showFeedback = false }: { showFeedback?: boolean }) => {
+ this._showCopyButtonFeedback = showFeedback;
+ this.requestUpdate();
+ }
+ );
+
+ /**
+ * Handles `click` event on the expando.
+ */
+ private _handleClickExpando() {
+ this._expanded = !this._expanded;
+ this.requestUpdate();
+ }
+
+ /**
+ * Handles change in slot content to determine if the content
+ */
+ private _handleSlotChange() {
+ const { type, _preNode: preNode } = this;
+ if (type === CODE_SNIPPET_TYPE.MULTI) {
+ if (preNode.getBoundingClientRect().height > 255) {
+ this._showExpando = true;
+ this.requestUpdate();
+ }
+ }
+ }
+
+ /**
+ * The `` element in the shadow DOM.
+ */
+ @query('pre')
+ private _preNode!: HTMLPreElement;
+
+ /**
+ * An assistive text for screen reader to advice a DOM node is for code snippet.
+ */
+ @property({ attribute: 'code-assistive-text' })
+ codeAssistiveText = 'code-snippet';
+
+ /**
+ * The context content for the collapse button.
+ */
+ @property({ attribute: 'collapse-button-text' })
+ collapseButtonText = 'Show less';
+
+ /**
+ * The color scheme.
+ */
+ @property({ attribute: 'color-scheme', reflect: true })
+ colorScheme = CODE_SNIPPET_COLOR_SCHEME.REGULAR;
+
+ /**
+ * An assistive text for screen reader to announce, telling that the button copies the content to the clipboard.
+ */
+ @property({ attribute: 'copy-button-assistive-text' })
+ copyButtonAssistiveText = 'Copy to clipboard';
+
+ /**
+ * The feedback text for the copy button.
+ */
+ @property({ attribute: 'copy-button-feedback-text' })
+ copyButtonFeedbackText = 'Copied!';
+
+ /**
+ * The number in milliseconds to determine how long the tooltip for the copy button should remain.
+ */
+ @property({ type: Number, attribute: 'copy-button-feedback-timeout' })
+ copyButtonFeedbackTimeout = 2000;
+
+ /**
+ * The context content for the expand button.
+ */
+ @property({ attribute: 'expand-button-text' })
+ expandButtonText = 'Show more';
+
+ /**
+ * The type of code snippet.
+ */
+ @property({ reflect: true })
+ type = CODE_SNIPPET_TYPE.SINGLE;
+
+ createRenderRoot() {
+ return this.attachShadow({
+ mode: 'open',
+ delegatesFocus:
+ Number((/Safari\/(\d+)/.exec(navigator.userAgent) ?? ['', 0])[1]) <=
+ 537,
+ });
+ }
+
+ render() {
+ const {
+ codeAssistiveText,
+ collapseButtonText,
+ copyButtonAssistiveText,
+ copyButtonFeedbackText,
+ expandButtonText,
+ type,
+ _expanded: expanded,
+ _showCopyButtonFeedback: showCopyButtonFeedback,
+ _showExpando: showExpando,
+ _handleClickCopyButton: handleClickCopyButton,
+ _handleClickExpando: handleClickExpando,
+ _handleSlotChange: handleSlotChange,
+ } = this;
+
+ if (type === CODE_SNIPPET_TYPE.SINGLE) {
+ // Ensures no extra whitespace text node
+ // prettier-ignore
+ return html`
+ ${renderCode({
+ assistiveText: codeAssistiveText,
+ expanded,
+ children: html`${collapseButtonText} `
+ : html`${expandButtonText} `,
+ handleClick: handleClickExpando,
+ })}
+ `;
+ }
+
+ // Ensures no extra whitespace text node
+ // prettier-ignore
+ return html`
+ ${renderCopyButton({
+ assistiveText: copyButtonAssistiveText,
+ feedbackText: copyButtonFeedbackText,
+ showFeedback: showCopyButtonFeedback,
+ handleClickButton: handleClickCopyButton,
+ className: `${prefix}--snippet ${prefix}--snippet--inline`,
+ children: html`
+ Option 1
+ Option 2
+ Option 3
+ Option 4
+ Option 5
+ Option 6
+ Option 7
+ Option 8
+
+```
+
+## Selection
+
+When user attempts to select a combo box item, `bx-combo-box-beingselected`
+event fires on ``, which has the following properties in the event
+details:
+
+| Property | Description |
+| -------- | ----------------------------------------- |
+| `item` | The `` being selected. |
+
+`bx-combo-box-beingselected` bubbles and is cancelable. Canceling this event
+means canceling change in selection.
+
+## `` attributes, properties and events
+
+Note: For `boolean` attributes, `true` means simply setting the attribute (e.g.
+``) and `false` means not setting the attribute (e.g.
+`` without `open` attribute).
+
+` attributes and properties
+
+Note: For `boolean` attributes, `true` means simply setting the attribute (e.g.
+``) and `false` means not setting the attribute
+(e.g. `` without `disabled` attribute).
+
+
+ Option 1
+ Option 2
+ Option 3
+ Option 4
+ Option 5
+ Option 6
+ Option 7
+ Option 8
+
+ `;
+};
+
+Default.storyName = 'Default';
+
+export default {
+ title: 'Components/Combo box',
+ parameters: {
+ ...storyDocs.parameters,
+ knobs: {
+ 'bx-combo-box': () => ({
+ open: boolean('Open (open)', false),
+ colorScheme: select('Color scheme (color-scheme)', colorSchemes, null),
+ disabled: boolean('Disabled (disabled)', false),
+ helperText: text('Helper text (helper-text)', 'Optional helper text'),
+ invalid: boolean('Show invalid state (invalid)', false),
+ labelText: text('Label text (label-text)', 'Combo box title'),
+ size: select('Dropdown size (size)', sizes, null),
+ triggerContent: text(
+ 'The placeholder content (trigger-content)',
+ 'Filter...'
+ ),
+ type: select('UI type (type)', types, null),
+ validityMessage: text('The validity message (validity-message)', ''),
+ value: text('The value of the selected item (value)', ''),
+ disableSelection: boolean(
+ 'Disable user-initiated selection change (Call event.preventDefault() in bx-combo-box-beingselected event)',
+ false
+ ),
+ disableToggle: boolean(
+ 'Disable user-initiated toggle of open state (Call event.preventDefault() in bx-combo-box-beingtoggled event)',
+ false
+ ),
+ onBeforeSelect: action('bx-combo-box-beingselected'),
+ onBeforeToggle: action('bx-combo-box-beingtoggled'),
+ onSelect: action('bx-combo-box-selected'),
+ onToggle: action('bx-combo-box-toggled'),
+ }),
+ },
+ },
+};
diff --git a/packages/carbon-web-components/src/components/combo-box/combo-box.scss b/packages/carbon-web-components/src/components/combo-box/combo-box.scss
new file mode 100644
index 00000000000..0e4247ad6fa
--- /dev/null
+++ b/packages/carbon-web-components/src/components/combo-box/combo-box.scss
@@ -0,0 +1,101 @@
+//
+// Copyright IBM Corp. 2019, 2022
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+$css--plex: true !default;
+
+@import 'carbon-components/scss/components/combo-box/combo-box';
+@import 'carbon-components/scss/components/form/form';
+@import 'carbon-components/scss/components/text-input/text-input';
+
+:host(#{$prefix}-combo-box) {
+ outline: none;
+
+ .#{$prefix}--assistive-text {
+ // Hides screen reader cursor
+ left: -100%;
+ top: -100%;
+ }
+
+ .#{$prefix}--label[hidden] {
+ display: none;
+ }
+
+ .#{$prefix}--list-box__field,
+ // To get more specifity than:
+ // https://github.com/carbon-design-system/carbon/blob/v10.16.0/packages/components/src/components/list-box/_list-box.scss#L126
+ .#{$prefix}--list-box[data-invalid] .#{$prefix}--list-box__field {
+ padding: 0;
+ }
+
+ .#{$prefix}--list-box__menu {
+ top: 100%;
+ margin-top: 1px;
+ }
+}
+
+:host(#{$prefix}-combo-box[type='inline']) {
+ @extend .#{$prefix}--list-box__wrapper--inline;
+
+ .#{$prefix}--list-box__field {
+ padding-left: 0;
+ }
+
+ .#{$prefix}--text-input {
+ border-bottom: none;
+ }
+}
+
+:host(#{$prefix}-combo-box-item) {
+ @extend .#{$prefix}--list-box__menu-item;
+
+ display: block;
+
+ .#{$prefix}--list-box__menu-item__option {
+ height: 100%;
+ }
+}
+
+:host(#{$prefix}-combo-box-item[size='sm']) {
+ height: rem(32px);
+
+ .#{$prefix}--list-box__menu-item__option {
+ padding-top: rem(7px);
+ padding-bottom: rem(7px);
+ }
+}
+
+:host(#{$prefix}-combo-box-item[size='xl']) {
+ height: rem(48px);
+
+ .#{$prefix}--list-box__menu-item__option {
+ padding-top: rem(15px);
+ padding-bottom: rem(15px);
+ }
+}
+
+:host(#{$prefix}-combo-box-item[disabled])
+ .#{$prefix}--list-box__menu-item__option {
+ color: $disabled-02;
+ text-decoration: none;
+}
+
+:host(#{$prefix}-combo-box-item[highlighted]) {
+ @extend .#{$prefix}--list-box__menu-item--highlighted;
+}
+
+:host(#{$prefix}-combo-box-item[selected]) {
+ @extend .#{$prefix}--list-box__menu-item--active;
+ @extend .#{$prefix}--list-box__menu-item--highlighted;
+
+ .#{$prefix}--list-box__menu-item__option {
+ color: $text-01;
+ }
+
+ .#{$prefix}--list-box__menu-item__selected-icon {
+ display: block;
+ }
+}
diff --git a/packages/carbon-web-components/src/components/combo-box/combo-box.ts b/packages/carbon-web-components/src/components/combo-box/combo-box.ts
new file mode 100644
index 00000000000..62538e3ebf5
--- /dev/null
+++ b/packages/carbon-web-components/src/components/combo-box/combo-box.ts
@@ -0,0 +1,339 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019, 2022
+ *
+ * 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 settings from 'carbon-components/es/globals/js/settings';
+import { TemplateResult } from 'lit-html';
+import { html, property, query, customElement } from 'lit-element';
+import Close16 from '@carbon/icons/lib/close/16';
+import { findIndex, forEach } from '../../globals/internal/collection-helpers';
+import BXDropdown, { DROPDOWN_KEYBOARD_ACTION } from '../dropdown/dropdown';
+import BXComboBoxItem from './combo-box-item';
+import styles from './combo-box.scss';
+
+export {
+ DROPDOWN_COLOR_SCHEME,
+ DROPDOWN_SIZE,
+ DROPDOWN_TYPE,
+} from '../dropdown/dropdown';
+
+const { prefix } = settings;
+
+/**
+ * Combo box.
+ *
+ * @element bx-combo-box
+ * @fires bx-combo-box-beingselected
+ * The custom event fired before a combo box item is selected upon a user gesture.
+ * Cancellation of this event stops changing the user-initiated selection.
+ * @fires bx-combo-box-beingtoggled
+ * The custom event fired before the open state of this combo box is toggled upon a user gesture.
+ * Cancellation of this event stops the user-initiated toggling.
+ * @fires bx-combo-box-selected - The custom event fired after a combo box item is selected upon a user gesture.
+ * @fires bx-combo-box-toggled - The custom event fired after the open state of this combo box is toggled upon a user gesture.
+ */
+@customElement(`${prefix}-combo-box`)
+class BXComboBox extends BXDropdown {
+ /**
+ * The text content that should be set to the `
+ ${Close16({ 'aria-label': clearSelectionLabel })}
+
+ `;
+ }
+
+ /**
+ * The `aria-label` attribute for the icon to clear selection.
+ */
+ @property({ attribute: 'clear-selection-label' })
+ clearSelectionLabel = '';
+
+ /**
+ * The `aria-label` attribute for the `` when this content switcher item is selected.
+ */
+ @property()
+ value = '';
+
+ createRenderRoot() {
+ return this.attachShadow({
+ mode: 'open',
+ delegatesFocus:
+ Number((/Safari\/(\d+)/.exec(navigator.userAgent) ?? ['', 0])[1]) <=
+ 537,
+ });
+ }
+
+ shouldUpdate(changedProperties) {
+ if (changedProperties.has('selected') || changedProperties.has('target')) {
+ const { selected, target } = this;
+ if (target) {
+ const doc = this.getRootNode() as HTMLDocument;
+ // `doc` can be an element if such element is orphaned
+ const targetNode = doc.getElementById && doc.getElementById(target);
+ if (targetNode) {
+ targetNode.toggleAttribute('hidden', !selected);
+ }
+ }
+ }
+ return true;
+ }
+
+ render() {
+ const { disabled, selected, target } = this;
+ const className = classMap({
+ [`${prefix}--content-switcher-btn`]: true,
+ [`${prefix}--content-switcher--selected`]: selected,
+ });
+ return html`
+
+
+ `;
+ }
+
+ static styles = styles;
+}
+
+export default BXContentSwitcherItem;
diff --git a/packages/carbon-web-components/src/components/content-switcher/content-switcher-story.mdx b/packages/carbon-web-components/src/components/content-switcher/content-switcher-story.mdx
new file mode 100644
index 00000000000..4e551b8614d
--- /dev/null
+++ b/packages/carbon-web-components/src/components/content-switcher/content-switcher-story.mdx
@@ -0,0 +1,49 @@
+import { Props, Description } from '@storybook/addon-docs/blocks';
+import { cdnJs, cdnCss } from '../../globals/internal/storybook-cdn';
+
+# Content switcher
+
+> ๐ก Check our
+> [CodeSandbox](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/basic/components/content-switcher)
+> example implementation.
+
+[](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/basic/components/content-switcher)
+
+Content switcher manipulates the content shown following an exclusive or
+โeither/orโ pattern. It is used to toggle between two or more content sections
+within the same space on screen. Only one section can be shown at a time.
+
+## Getting started
+
+Here's a quick example to get you started.
+
+### JS (via import)
+
+```javascript
+import '@carbon/web-components/es/components/content-switcher/index.js';
+```
+
+
+ Option 1
+ Option 2
+ Option 3
+ Option 4
+ Option 5
+
+```
+
+## `` attributes, properties and events
+
+` attributes and properties
+
+
+ Option 1
+ Option 2
+ Option 3
+ Option 4
+ Option 5
+
+ `;
+};
+
+Default.storyName = 'Default';
+
+export default {
+ title: 'Components/Content switcher',
+ parameters: {
+ ...storyDocs.parameters,
+ knobs: {
+ 'bx-content-switcher': () => ({
+ value: textNullable('The value of the selected item (value)', ''),
+ size: select('Button size (size)', sizes, null),
+ disableSelection: boolean(
+ 'Disable user-initiated selection change (Call event.preventDefault() in bx-content-switcher-beingselected event)',
+ false
+ ),
+ onBeforeSelect: action('bx-content-switcher-beingselected'),
+ onSelect: action('bx-content-switcher-selected'),
+ }),
+ },
+ },
+};
diff --git a/packages/carbon-web-components/src/components/content-switcher/content-switcher.scss b/packages/carbon-web-components/src/components/content-switcher/content-switcher.scss
new file mode 100644
index 00000000000..3c294a9b403
--- /dev/null
+++ b/packages/carbon-web-components/src/components/content-switcher/content-switcher.scss
@@ -0,0 +1,93 @@
+//
+// Copyright IBM Corp. 2019, 2022
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+$css--plex: true !default;
+
+@import 'carbon-components/scss/components/content-switcher/content-switcher';
+
+:host(#{$prefix}-content-switcher) {
+ @extend .#{$prefix}--content-switcher;
+}
+
+:host(#{$prefix}-content-switcher[size='sm']) {
+ @extend .#{$prefix}--content-switcher--sm;
+}
+
+:host(#{$prefix}-content-switcher[size='xl']) {
+ @extend .#{$prefix}--content-switcher--xl;
+}
+
+:host(#{$prefix}-content-switcher-item) {
+ width: 100%;
+ outline: none;
+
+ .#{$prefix}--content-switcher-btn {
+ height: 100%;
+
+ &:first-child,
+ &:last-child {
+ border-radius: 0;
+ border-left: none;
+ border-right: none;
+ }
+
+ &::before {
+ content: '';
+ display: block;
+ height: rem(16px);
+ width: rem(1px);
+ background-color: $content-switcher-divider;
+ position: absolute;
+ z-index: 2;
+ left: 0;
+ }
+
+ &.#{$prefix}--content-switcher--selected,
+ &:focus,
+ &:hover {
+ &::before {
+ background-color: transparent;
+ }
+ }
+
+ &:disabled {
+ border-top-color: $ui-05;
+ border-bottom-color: $ui-05;
+ }
+ }
+}
+
+:host(#{$prefix}-content-switcher-item[hide-divider])
+ .#{$prefix}--content-switcher-btn::before {
+ background-color: transparent;
+}
+
+:host(#{$prefix}-content-switcher-item:first-of-type)
+ .#{$prefix}--content-switcher-btn {
+ border-top-left-radius: rem(4px);
+ border-bottom-left-radius: rem(4px);
+ border-left: rem(1px) solid $ui-05;
+
+ &::before {
+ content: none;
+ }
+
+ &.#{$prefix}--content-switcher--selected {
+ border-left: none;
+ }
+}
+
+:host(#{$prefix}-content-switcher-item:last-of-type)
+ .#{$prefix}--content-switcher-btn {
+ border-top-right-radius: rem(4px);
+ border-bottom-right-radius: rem(4px);
+ border-right: rem(1px) solid $ui-05;
+
+ &.#{$prefix}--content-switcher--selected {
+ border-right: none;
+ }
+}
diff --git a/packages/carbon-web-components/src/components/content-switcher/content-switcher.ts b/packages/carbon-web-components/src/components/content-switcher/content-switcher.ts
new file mode 100644
index 00000000000..d945b170f1f
--- /dev/null
+++ b/packages/carbon-web-components/src/components/content-switcher/content-switcher.ts
@@ -0,0 +1,240 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019, 2022
+ *
+ * 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 { html, property, customElement, LitElement } from 'lit-element';
+import settings from 'carbon-components/es/globals/js/settings';
+import { forEach, indexOf } from '../../globals/internal/collection-helpers';
+import { NAVIGATION_DIRECTION, CONTENT_SWITCHER_SIZE } from './defs';
+import BXSwitch from './content-switcher-item';
+import styles from './content-switcher.scss';
+
+export { NAVIGATION_DIRECTION, CONTENT_SWITCHER_SIZE };
+
+const { prefix } = settings;
+
+/**
+ * @param index The index
+ * @param length The length of the array.
+ * @returns The new index, adjusting overflow/underflow.
+ */
+const capIndex = (index: number, length: number) => {
+ if (index < 0) {
+ return length - 1;
+ }
+ if (index >= length) {
+ return 0;
+ }
+ return index;
+};
+
+/**
+ * Content switcher.
+ *
+ * @element bx-content-switcher
+ * @fires bx-content-switcher-beingselected
+ * The custom event fired before a content switcher item is selected upon a user gesture.
+ * Cancellation of this event stops changing the user-initiated selection.
+ * @fires bx-content-switcher-selected - The custom event fired after a a content switcher item is selected upon a user gesture.
+ */
+@customElement(`${prefix}-content-switcher`)
+class BXContentSwitcher extends LitElement {
+ /**
+ * Handles `mouseover`/`mouseout` events on ``.
+ *
+ * @param event The event.
+ */
+ private _handleHover({ target, type }: MouseEvent) {
+ const { selectorItem } = this.constructor as typeof BXContentSwitcher;
+ const items = this.querySelectorAll(selectorItem);
+ const index =
+ type !== 'mouseover'
+ ? -1
+ : indexOf(items, (target as Element).closest(selectorItem)!);
+ const nextIndex = index < 0 ? index : index + 1;
+ forEach(this.querySelectorAll(selectorItem), (elem, i) => {
+ // Specifies child `` to hide its divider instead of using CSS,
+ // until `:host-context()` gets supported in all major browsers
+ (elem as BXSwitch).hideDivider = i === nextIndex;
+ });
+ }
+
+ /**
+ * @param currentItem The currently selected item.
+ * @param direction The navigation direction.
+ * @returns The item to be selected.
+ */
+ protected _getNextItem(currentItem: BXSwitch, direction: number) {
+ const items = this.querySelectorAll(
+ (this.constructor as typeof BXContentSwitcher).selectorItemEnabled
+ );
+ const currentIndex = indexOf(items, currentItem);
+ const nextIndex = capIndex(currentIndex + direction, items.length);
+ return nextIndex === currentIndex ? null : items[nextIndex];
+ }
+
+ /**
+ * Handles `click` event on the top-level element in the shadow DOM.
+ *
+ * @param event The event.
+ */
+ protected _handleClick({ target }: MouseEvent) {
+ this._handleUserInitiatedSelectItem(target as BXSwitch);
+ }
+
+ /**
+ * Handles `keydown` event on the top-level element in the shadow DOM.
+ *
+ * @param event The event.
+ */
+ protected _handleKeydown({ key }: KeyboardEvent) {
+ if (key in NAVIGATION_DIRECTION) {
+ this._navigate(NAVIGATION_DIRECTION[key]);
+ }
+ }
+
+ /**
+ * Handles user-initiated selection of a content switcher item.
+ *
+ * @param [item] The content switcher item user wants to select.
+ */
+ protected _handleUserInitiatedSelectItem(item: BXSwitch) {
+ if (!item.disabled && item.value !== this.value) {
+ const init = {
+ bubbles: true,
+ composed: true,
+ detail: {
+ item,
+ },
+ };
+ const constructor = this.constructor as typeof BXContentSwitcher;
+ const beforeSelectEvent = new CustomEvent(constructor.eventBeforeSelect, {
+ ...init,
+ cancelable: true,
+ });
+ if (this.dispatchEvent(beforeSelectEvent)) {
+ this._selectionDidChange(item);
+ const afterSelectEvent = new CustomEvent(constructor.eventSelect, init);
+ this.dispatchEvent(afterSelectEvent);
+ }
+ }
+ }
+
+ /**
+ * Navigates through content switcher items.
+ *
+ * @param direction `-1` to navigate backward, `1` to navigate forward.
+ */
+ protected _navigate(direction: number) {
+ const { selectorItemSelected } = this
+ .constructor as typeof BXContentSwitcher;
+ const nextItem = this._getNextItem(
+ this.querySelector(selectorItemSelected) as BXSwitch,
+ direction
+ );
+ if (nextItem) {
+ this._handleUserInitiatedSelectItem(nextItem as BXSwitch);
+ this.requestUpdate();
+ }
+ }
+
+ /**
+ * A callback that runs after change in content switcher selection upon user interaction is confirmed.
+ *
+ * @param itemToSelect A content switcher item.
+ */
+ protected _selectionDidChange(itemToSelect: BXSwitch) {
+ this.value = itemToSelect.value;
+ forEach(
+ this.querySelectorAll(
+ (this.constructor as typeof BXContentSwitcher).selectorItemSelected
+ ),
+ (item) => {
+ (item as BXSwitch).selected = false;
+ }
+ );
+ itemToSelect.selected = true;
+ // Waits for rendering with the new state that updates `tabindex`
+ Promise.resolve().then(() => {
+ itemToSelect.focus();
+ });
+ }
+
+ /**
+ * The value of the selected item.
+ */
+ @property({ reflect: true })
+ value = '';
+
+ /**
+ * Content switcher size.
+ */
+ @property({ reflect: true })
+ size = CONTENT_SWITCHER_SIZE.REGULAR;
+
+ shouldUpdate(changedProperties) {
+ if (changedProperties.has('value')) {
+ const { selectorItem } = this.constructor as typeof BXContentSwitcher;
+ forEach(this.querySelectorAll(selectorItem), (elem) => {
+ (elem as BXSwitch).selected = (elem as BXSwitch).value === this.value;
+ });
+ }
+ return true;
+ }
+
+ /**
+ * A selector that will return content switcher items.
+ */
+ static get selectorItem() {
+ return `${prefix}-content-switcher-item`;
+ }
+
+ /**
+ * A selector that will return enabled content switcher items.
+ */
+ static get selectorItemEnabled() {
+ return `${prefix}-content-switcher-item:not([disabled])`;
+ }
+
+ /**
+ * A selector that will return selected items.
+ */
+ static get selectorItemSelected() {
+ return `${prefix}-content-switcher-item[selected]`;
+ }
+
+ /**
+ * The name of the custom event fired before a content switcher item is selected upon a user gesture.
+ * Cancellation of this event stops changing the user-initiated selection.
+ */
+ static get eventBeforeSelect() {
+ return `${prefix}-content-switcher-beingselected`;
+ }
+
+ /**
+ * The name of the custom event fired after a a content switcher item is selected upon a user gesture.
+ */
+ static get eventSelect() {
+ return `${prefix}-content-switcher-selected`;
+ }
+
+ render() {
+ const { _handleHover: handleHover, _handleKeydown: handleKeydown } = this;
+ return html`
+ ` and interact with the clipboard.
+
+## Getting started
+
+Here's a quick example to get you started.
+
+### JS (via import)
+
+```javascript
+import '@carbon/web-components/es/components/copy-button/index.js';
+```
+
+` attributes and properties
+
+` only. The API is subject to change/removal.
+ *
+ * @param update The callback function that dictates how to update the DOM with new feedback tooltip state.
+ * @returns A function that shows the feedback tooltip for the given duration.
+ * @private
+ */
+export const _createHandleFeedbackTooltip = (
+ update: (properties: { showFeedback?: boolean }) => void
+) => {
+ let timeoutId: number | void;
+ return (timeout: number) => {
+ if (timeoutId) {
+ clearTimeout(timeoutId);
+ timeoutId = undefined;
+ }
+ update({ showFeedback: true });
+ timeoutId = setTimeout(() => {
+ update({ showFeedback: false });
+ }, timeout) as unknown as number;
+ };
+};
+
+/**
+ * Note: For `` only. The API is subject to change/removal.
+ *
+ * @param properties The properties to render.
+ * @returns The template result for copy button from the given properties.
+ * @private
+ */
+export const _renderButton = ({
+ assistiveText,
+ feedbackText,
+ showFeedback = false,
+ className = `${prefix}--snippet-button`,
+ children = html`
+ ${Copy16({ class: `${prefix}--snippet__icon` })}
+ `,
+ handleClickButton,
+}: {
+ assistiveText: string;
+ feedbackText: string;
+ showFeedback?: boolean;
+ className?: string;
+ children?: TemplateResult;
+ handleClickButton: EventListener;
+}) => {
+ const feedbackClasses = classMap({
+ [`${prefix}--btn--copy__feedback`]: true,
+ [`${prefix}--btn--copy__feedback--displayed`]: showFeedback,
+ });
+ return html`
+
+ ${children}
+
+
+ `;
+};
+
+/**
+ * Copy button.
+ *
+ * @element bx-copy-button
+ */
+@customElement(`${prefix}-copy-button`)
+class BXCopyButton extends FocusMixin(LitElement) {
+ /**
+ * Handles showing/hiding the feedback tooltip.
+ */
+ private _handleFeedbackTooltip = _createHandleFeedbackTooltip(
+ ({ showFeedback = false }: { showFeedback?: boolean }) => {
+ this._showFeedback = showFeedback;
+ this.requestUpdate();
+ }
+ );
+
+ /**
+ * `true` to show the feedback tooltip.
+ */
+ private _showFeedback = false;
+
+ /**
+ * Handles `click` event on the copy button.
+ */
+ private _handleClickButton() {
+ this._handleFeedbackTooltip(this.feedbackTimeout);
+ }
+
+ /**
+ * An assistive text for screen reader to announce, telling that the button copies the content to the clipboard.
+ */
+ @property({ attribute: 'button-assistive-text' })
+ buttonAssistiveText = 'Copy to clipboard';
+
+ /**
+ * The feedback text.
+ */
+ @property({ attribute: 'feedback-text' })
+ feedbackText = 'Copied!';
+
+ /**
+ * The number in milliseconds to determine how long the tooltip should remain.
+ */
+ @property({ type: Number, attribute: 'feedback-timeout' })
+ feedbackTimeout = 2000;
+
+ createRenderRoot() {
+ return this.attachShadow({
+ mode: 'open',
+ delegatesFocus:
+ Number((/Safari\/(\d+)/.exec(navigator.userAgent) ?? ['', 0])[1]) <=
+ 537,
+ });
+ }
+
+ render() {
+ const {
+ buttonAssistiveText,
+ feedbackText,
+ _handleClickButton: handleClickButton,
+ _showFeedback: showFeedback,
+ } = this;
+ return _renderButton({
+ assistiveText: buttonAssistiveText,
+ feedbackText,
+ showFeedback,
+ handleClickButton,
+ });
+ }
+
+ static styles = styles;
+}
+
+export default BXCopyButton;
diff --git a/packages/carbon-web-components/src/components/copy-button/index.ts b/packages/carbon-web-components/src/components/copy-button/index.ts
new file mode 100644
index 00000000000..fabcb375b23
--- /dev/null
+++ b/packages/carbon-web-components/src/components/copy-button/index.ts
@@ -0,0 +1,10 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2021
+ *
+ * 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 './copy-button';
diff --git a/packages/carbon-web-components/src/components/data-table/_table-action.scss b/packages/carbon-web-components/src/components/data-table/_table-action.scss
new file mode 100644
index 00000000000..611476abf0b
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/_table-action.scss
@@ -0,0 +1,109 @@
+//
+// Copyright IBM Corp. 2019, 2022
+//
+// 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 'carbon-components/scss/components/button/button';
+@import 'carbon-components/scss/components/search/search';
+@import 'carbon-components/scss/components/data-table/data-table-action';
+
+//
+// Table toolbar
+//
+
+:host(#{$prefix}-table-toolbar) {
+ @extend .#{$prefix}--table-toolbar;
+}
+
+:host(#{$prefix}-table-toolbar-content) {
+ @extend .#{$prefix}--toolbar-content;
+
+ clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%);
+
+ ::slotted(#{$prefix}-overflow-menu) {
+ @include button-reset;
+
+ display: flex;
+ cursor: pointer;
+ height: $layout-04;
+ width: $layout-04;
+ padding: $spacing-md;
+ transition: background-color $duration--fast-02 motion(entrance, productive);
+ }
+
+ ::slotted(#{$prefix}-overflow-menu:hover) {
+ background-color: $hover-field;
+ }
+
+ ::slotted(#{$prefix}-overflow-menu[disabled]:hover) {
+ background-color: transparent;
+ }
+
+ .#{$prefix}--search .#{$prefix}--search-input {
+ // For tool bar animation with (esp.) persistent search box
+ background-color: transparent;
+ }
+}
+
+:host(#{$prefix}-table-toolbar-content[has-batch-actions]) {
+ clip-path: polygon(0 0, 100% 0, 100% 0, 0 0);
+ transform: translate3d(0, 48px, 0);
+ transition: transform $duration--fast-02 motion(standard, productive),
+ clip-path $duration--fast-02 motion(standard, productive);
+}
+
+:host(#{$prefix}-table-toolbar-search) {
+ @extend .#{$prefix}--toolbar-action;
+ @extend .#{$prefix}--toolbar-search-container-expandable;
+
+ flex: none;
+ transition: flex 175ms $carbon--standard-easing;
+
+ .#{$prefix}--search {
+ width: 100%;
+ height: 100%;
+
+ .#{$prefix}--search-magnifier {
+ height: $layout-04;
+ width: $layout-04;
+ padding: $spacing-md;
+ left: 0;
+ cursor: pointer;
+ pointer-events: all;
+ transition: background $duration--fast-02 motion(entrance, productive);
+ }
+
+ .#{$prefix}--search-close {
+ height: $layout-04;
+ width: $layout-04;
+
+ &::before {
+ top: 2px;
+ height: calc(100% - 4px);
+ background-color: $hover-ui;
+ }
+ }
+ }
+}
+
+:host(#{$prefix}-table-toolbar-search[expanded]) {
+ @extend .#{$prefix}--toolbar-search-container-active;
+
+ flex: auto;
+}
+
+:host(#{$prefix}-table-toolbar-search[persistent]) {
+ @extend .#{$prefix}--toolbar-search-container-persistent;
+}
+
+:host(#{$prefix}-table-batch-actions) {
+ @extend .#{$prefix}--batch-actions;
+
+ box-sizing: border-box;
+}
+
+:host(#{$prefix}-table-batch-actions[active]) {
+ @extend .#{$prefix}--batch-actions--active;
+}
diff --git a/packages/carbon-web-components/src/components/data-table/_table-core.scss b/packages/carbon-web-components/src/components/data-table/_table-core.scss
new file mode 100644
index 00000000000..c274a36b90a
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/_table-core.scss
@@ -0,0 +1,190 @@
+//
+// Copyright IBM Corp. 2019, 2022
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+//
+// Table header and table body
+//
+
+:host(#{$prefix}-table) {
+ @extend .#{$prefix}--data-table;
+
+ display: table;
+
+ ::slotted(#{$prefix}-table-head) {
+ @include type-style('heading-01');
+
+ background-color: $ui-03;
+ display: table-header-group;
+ }
+
+ ::slotted(#{$prefix}-table-body) {
+ @include type-style('body-short-01');
+
+ background-color: $ui-01;
+ width: 100%;
+ display: table-row-group;
+ }
+}
+
+//
+// Common style for table cell and table header cell
+//
+
+:host(#{$prefix}-table-header-row) ::slotted(#{$prefix}-table-header-cell),
+:host(#{$prefix}-table-header-row)
+ ::slotted(#{$prefix}-table-header-cell-skeleton),
+:host(#{$prefix}-table-header-row) .#{$prefix}--table-column-checkbox,
+:host(#{$prefix}-table-header-expand-row)
+ ::slotted(#{$prefix}-table-header-cell),
+:host(#{$prefix}-table-header-expand-row)
+ ::slotted(#{$prefix}-table-header-cell-skeleton),
+:host(#{$prefix}-table-header-expand-row) .#{$prefix}--table-expand,
+:host(#{$prefix}-table-header-expand-row) .#{$prefix}--table-column-checkbox,
+:host(#{$prefix}-table-row) ::slotted(#{$prefix}-table-cell),
+:host(#{$prefix}-table-row) ::slotted(#{$prefix}-table-cell-skeleton),
+:host(#{$prefix}-table-row) .#{$prefix}--table-column-checkbox,
+:host(#{$prefix}-table-expand-row) ::slotted(#{$prefix}-table-cell),
+:host(#{$prefix}-table-expand-row) ::slotted(#{$prefix}-table-cell-skeleton),
+:host(#{$prefix}-table-expand-row) .#{$prefix}--table-expand,
+:host(#{$prefix}-table-expand-row) .#{$prefix}--table-column-checkbox {
+ display: table-cell;
+}
+
+//
+// Table header row
+//
+
+:host(#{$prefix}-table-head) ::slotted(#{$prefix}-table-header-row),
+:host(#{$prefix}-table-head) ::slotted(#{$prefix}-table-header-expand-row) {
+ height: $layout-04;
+ display: table-row;
+}
+
+//
+// Table header cell
+//
+
+:host(#{$prefix}-table-header-row),
+:host(#{$prefix}-table-header-expand-row) {
+ outline: none;
+
+ ::slotted(#{$prefix}-table-header-cell),
+ ::slotted(#{$prefix}-table-header-cell-skeleton) {
+ color: $text-01;
+ background-color: $ui-03;
+ text-align: left;
+ display: table-cell;
+ outline: none;
+ }
+
+ ::slotted(#{$prefix}-table-header-cell:last-of-type),
+ ::slotted(#{$prefix}-table-header-cell-skeleton:last-of-type) {
+ position: relative;
+ width: auto;
+ }
+
+ ::slotted(#{$prefix}-table-header-cell),
+ ::slotted(#{$prefix}-table-header-cell-skeleton),
+ .#{$prefix}--table-expand,
+ .#{$prefix}--table-column-checkbox {
+ padding-left: $spacing-04;
+ padding-right: $spacing-04;
+ vertical-align: middle;
+ }
+}
+
+:host(#{$prefix}-table-header-row) {
+ ::slotted(#{$prefix}-table-header-cell:first-of-type),
+ ::slotted(#{$prefix}-table-header-cell-skeleton:first-of-type) {
+ padding-left: $spacing-05;
+ }
+}
+
+//
+// Table row
+//
+
+:host(#{$prefix}-table-body) {
+ ::slotted(#{$prefix}-table-row),
+ ::slotted(#{$prefix}-table-expand-row) {
+ border: none;
+ height: $layout-04;
+ width: 100%;
+ display: table-row;
+ outline: none;
+ }
+}
+
+//
+// Table cell
+//
+
+:host(#{$prefix}-table-row),
+:host(#{$prefix}-table-expand-row) {
+ ::slotted(#{$prefix}-table-cell),
+ ::slotted(#{$prefix}-table-cell-skeleton),
+ .#{$prefix}--table-expand,
+ .#{$prefix}--table-column-checkbox {
+ color: $text-02;
+ border-top: 1px solid $ui-01;
+ border-bottom: 1px solid $ui-03;
+ padding: rem(14px) $spacing-04;
+ padding-bottom: rem(13px);
+ vertical-align: middle;
+ }
+}
+
+:host(#{$prefix}-table-row) {
+ ::slotted(#{$prefix}-table-cell:first-of-type),
+ ::slotted(#{$prefix}-table-cell-skeleton:first-of-type) {
+ padding-left: $spacing-05;
+ }
+
+ ::slotted(#{$prefix}-table-cell:last-of-type),
+ ::slotted(#{$prefix}-table-cell-skeleton:last-of-type) {
+ padding-right: $spacing-05;
+ }
+}
+
+:host(#{$prefix}-table-row[even]) {
+ ::slotted(#{$prefix}-table-cell),
+ ::slotted(#{$prefix}-table-cell-skeleton) {
+ border-bottom: 1px solid $ui-01;
+ }
+}
+
+:host(#{$prefix}-table-row[odd]) {
+ ::slotted(#{$prefix}-table-cell),
+ ::slotted(#{$prefix}-table-cell-skeleton) {
+ background-color: $data-table-zebra-color;
+ border-bottom: 1px solid $data-table-zebra-color;
+ border-top: 1px solid $data-table-zebra-color;
+ }
+}
+
+:host(#{$prefix}-table-row:hover),
+:host(#{$prefix}-table-expand-row:hover) {
+ ::slotted(#{$prefix}-table-cell),
+ ::slotted(#{$prefix}-table-cell-skeleton),
+ .#{$prefix}--table-expand,
+ .#{$prefix}--table-column-checkbox {
+ color: $text-01;
+ background-color: $hover-field;
+ border-bottom-color: $hover-field;
+ border-top-color: $hover-field;
+ }
+}
+
+:host(#{$prefix}-table-row[even]:hover),
+:host(#{$prefix}-table-row[odd]:hover) {
+ ::slotted(#{$prefix}-table-cell),
+ ::slotted(#{$prefix}-table-cell-skeleton) {
+ background-color: $hover-field;
+ border-bottom: 1px solid $hover-field;
+ border-top: 1px solid $hover-field;
+ }
+}
diff --git a/packages/carbon-web-components/src/components/data-table/_table-expandable.scss b/packages/carbon-web-components/src/components/data-table/_table-expandable.scss
new file mode 100644
index 00000000000..ca842c949ba
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/_table-expandable.scss
@@ -0,0 +1,64 @@
+//
+// Copyright IBM Corp. 2020, 2022
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+:host(#{$prefix}-table-expand-row),
+:host(#{$prefix}-table-header-expand-row) {
+ .#{$prefix}--table-expand {
+ display: table-cell;
+ width: 2.5rem;
+ height: 3rem;
+ vertical-align: middle;
+ padding: 0;
+ border-bottom: 1px solid $ui-03;
+ transition: transform $duration--moderate-01 motion(standard, productive);
+ }
+
+ &[expanded] .#{$prefix}--table-expand {
+ border-bottom: 1px solid transparent;
+
+ .#{$prefix}--table-expand__svg {
+ transform: rotate(270deg);
+ }
+ }
+}
+
+:host(#{$prefix}-table-expanded-row) {
+ display: table-row;
+ transition: height $duration--moderate-02 motion(standard),
+ background-color $duration--fast-02 motion(standard);
+
+ &[expanded] {
+ height: auto;
+ }
+
+ td {
+ padding: 0 $spacing-05;
+ vertical-align: middle;
+ height: 0;
+ transition: all $duration--fast-02 motion(standard, productive);
+
+ .#{$prefix}--child-row-inner-container {
+ overflow: hidden;
+ height: 0;
+ }
+ }
+
+ &[expanded] td {
+ border-bottom: 1px solid $ui-03;
+ padding-top: rem(14px);
+ padding-bottom: rem(13px);
+ height: auto;
+
+ .#{$prefix}--child-row-inner-container {
+ height: auto;
+ }
+ }
+
+ &[highlighted] {
+ background-color: $hover-ui;
+ }
+}
diff --git a/packages/carbon-web-components/src/components/data-table/_table-selection.scss b/packages/carbon-web-components/src/components/data-table/_table-selection.scss
new file mode 100644
index 00000000000..c118c68707e
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/_table-selection.scss
@@ -0,0 +1,57 @@
+//
+// Copyright IBM Corp. 2019, 2022
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+//
+// Selection check box
+//
+
+:host(#{$prefix}-table-header-row) .#{$prefix}--table-column-checkbox {
+ position: relative;
+ background-color: $ui-03;
+ // 16px padding left + 8px padding right + 20px checkbox width
+ width: rem(44px);
+ transition: background-color $duration--fast-01 motion(entrance, productive);
+}
+
+:host(#{$prefix}-table-row) .#{$prefix}--table-column-checkbox {
+ .#{$prefix}--checkbox-label {
+ padding-left: $spacing-05;
+ }
+}
+
+:host(#{$prefix}-table-header-row) .#{$prefix}--table-column-checkbox:hover {
+ // Highlight "select all" columns like sorting column
+ background-color: $data-table-column-hover;
+}
+
+:host(#{$prefix}-table-row[size='tall']) .#{$prefix}--table-column-checkbox {
+ padding-top: rem(12px);
+}
+
+//
+// Selected rows
+//
+
+:host(#{$prefix}-table-row[selected]) {
+ ::slotted(#{$prefix}-table-cell),
+ .#{$prefix}--table-column-checkbox {
+ color: $text-01;
+ background-color: $ui-03;
+ border-top: 1px solid $ui-03;
+ //bottom border acts as separator from other rows
+ border-bottom: 1px solid $active-ui;
+ }
+}
+
+:host(#{$prefix}-table-row[selected]:hover) {
+ ::slotted(#{$prefix}-table-cell),
+ .#{$prefix}--table-column-checkbox {
+ background-color: $data-table-column-hover;
+ border-top-color: $data-table-column-hover;
+ border-bottom-color: $data-table-column-hover;
+ }
+}
diff --git a/packages/carbon-web-components/src/components/data-table/_table-sizes.scss b/packages/carbon-web-components/src/components/data-table/_table-sizes.scss
new file mode 100644
index 00000000000..836064be490
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/_table-sizes.scss
@@ -0,0 +1,59 @@
+//
+// Copyright IBM Corp. 2019, 2022
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+//
+// "Compact" table size variant
+//
+
+:host(#{$prefix}-table-head)
+ ::slotted(#{$prefix}-table-header-row[size='compact']),
+:host(#{$prefix}-table-body) ::slotted(#{$prefix}-table-row[size='compact']) {
+ height: rem(24px);
+}
+
+:host(#{$prefix}-table-row[size='compact']) {
+ ::slotted(#{$prefix}-table-cell),
+ ::slotted(#{$prefix}-table-cell-skeleton) {
+ padding-top: rem(2px);
+ padding-bottom: rem(2px);
+ }
+}
+
+//
+// "Short" table size variant
+//
+
+:host(#{$prefix}-table-head)
+ ::slotted(#{$prefix}-table-header-row[size='short']),
+:host(#{$prefix}-table-body) ::slotted(#{$prefix}-table-row[size='short']) {
+ height: rem(32px);
+}
+
+:host(#{$prefix}-table-row[size='short']) {
+ ::slotted(#{$prefix}-table-cell),
+ ::slotted(#{$prefix}-table-cell-skeleton) {
+ padding-top: rem(7px);
+ padding-bottom: rem(6px);
+ }
+}
+
+//
+// "Tall" table size variant
+//
+
+:host(#{$prefix}-table-head)
+ ::slotted(#{$prefix}-table-header-row[size='tall']),
+:host(#{$prefix}-table-body) ::slotted(#{$prefix}-table-row[size='tall']) {
+ height: rem(64px);
+}
+
+:host(#{$prefix}-table-row[size='tall']) {
+ ::slotted(#{$prefix}-table-cell),
+ ::slotted(#{$prefix}-table-cell-skeleton) {
+ padding-top: rem(16px);
+ }
+}
diff --git a/packages/carbon-web-components/src/components/data-table/_table-skeleton.scss b/packages/carbon-web-components/src/components/data-table/_table-skeleton.scss
new file mode 100644
index 00000000000..e43b0bb79ab
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/_table-skeleton.scss
@@ -0,0 +1,24 @@
+//
+// Copyright IBM Corp. 2019, 2022
+//
+// 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 'carbon-components/scss/globals/scss/helper-mixins';
+
+:host(#{$prefix}-table-header-cell-skeleton),
+:host(#{$prefix}-table-cell-skeleton) {
+ span {
+ @include skeleton;
+
+ width: 75%;
+ height: 1rem;
+ display: block;
+ }
+}
+
+:host(#{$prefix}-table-header-cell-skeleton) {
+ border-bottom: 1px solid $brand-01;
+ vertical-align: middle;
+}
diff --git a/packages/carbon-web-components/src/components/data-table/_table-sort.scss b/packages/carbon-web-components/src/components/data-table/_table-sort.scss
new file mode 100644
index 00000000000..8d7185b0e0b
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/_table-sort.scss
@@ -0,0 +1,73 @@
+//
+// Copyright IBM Corp. 2019, 2022
+//
+// 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 'carbon-components/scss/components/data-table/data-table-sort';
+
+:host(#{$prefix}-table-header-row[size='compact'])
+ ::slotted(#{$prefix}-table-header-cell[sort-direction]) {
+ height: rem(24px);
+}
+
+:host(#{$prefix}-table-header-row[size='short'])
+ ::slotted(#{$prefix}-table-header-cell[sort-direction]) {
+ height: rem(32px);
+}
+
+:host(#{$prefix}-table-header-row[size='tall'])
+ ::slotted(#{$prefix}-table-header-cell[sort-direction]) {
+ height: rem(64px);
+}
+
+// Padding of header cell for sorting
+//
+// Let sort button rather than the cell define the padding
+// Ensure sort button takes 100% of the cell, by setting the same height as the parent row
+
+:host(#{$prefix}-table-header-row)
+ ::slotted(#{$prefix}-table-header-cell[sort-direction]) {
+ height: rem(48px);
+ padding-left: 0;
+ padding-right: 0;
+}
+
+:host(#{$prefix}-table-header-cell[sort-direction]) .#{$prefix}--table-sort {
+ height: 100%;
+ padding-left: $spacing-04;
+ padding-right: $spacing-04;
+}
+
+:host(#{$prefix}-table-header-cell[sort-direction]:first-of-type)
+ .#{$prefix}--table-sort {
+ padding-left: $spacing-05;
+}
+
+//
+// Sort icon style
+//
+
+// Show sort icon of primary sorting column or one of hovered column
+:host(#{$prefix}-table-header-cell[sort-active])
+ .bx--table-sort
+ .bx--table-sort__icon,
+:host(#{$prefix}-table-header-cell)
+ .bx--table-sort:hover
+ .bx--table-sort__icon {
+ opacity: 1;
+}
+
+// `carbon-web-components` uses conditional rendering for choosing Arrows16 vs. ArrowDown16,
+// and thus `display:none` here is not needed
+:host(#{$prefix}-table-header-cell[sort-direction])
+ .bx--table-sort
+ .bx--table-sort__icon {
+ display: block;
+}
+
+:host(#{$prefix}-table-header-cell[sort-direction='ascending'])
+ .#{$prefix}--table-sort__icon {
+ transform: rotate(180deg);
+}
diff --git a/packages/carbon-web-components/src/components/data-table/core-library-style-questions.md b/packages/carbon-web-components/src/components/data-table/core-library-style-questions.md
new file mode 100644
index 00000000000..67b43b16117
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/core-library-style-questions.md
@@ -0,0 +1,6 @@
+- `` in addition to `` setting `background-color`:
+ https://github.com/carbon-design-system/carbon/blob/v10.3.0/packages/components/src/components/data-table/_data-table-core.scss#L74-L76
+- Re-definition of text color and border width/style for selected and hovered
+ ` `s:
+ - https://github.com/carbon-design-system/carbon/blob/v10.3.0/packages/components/src/components/data-table/_data-table-core.scss#L78-L83
+ - https://github.com/carbon-design-system/carbon/blob/v10.3.0/packages/components/src/components/data-table/_data-table-core.scss#L304-L314
diff --git a/packages/carbon-web-components/src/components/data-table/data-table-story.mdx b/packages/carbon-web-components/src/components/data-table/data-table-story.mdx
new file mode 100644
index 00000000000..bfab025d27b
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/data-table-story.mdx
@@ -0,0 +1,336 @@
+import { Props, Description } from '@storybook/addon-docs/blocks';
+import { cdnJs, cdnCss } from '../../globals/internal/storybook-cdn';
+
+# Data table
+
+> ๐ก Check our
+> [CodeSandbox](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/basic/components/data-table)
+> example implementation.
+
+[](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/basic/components/data-table)
+
+## Getting started
+
+Here's a quick example to get you started.
+
+Data table in `carbon-web-components` focuses on primitives that constructs
+table UI, consisting of the following:
+
+| Tag | Description | HTML tag counterpart |
+| ------------------------ | --------------- | -------------------- |
+| `` | The container | N/A |
+| `` | The table | `` |
+| `` | The header | `` |
+| `` | The header row | `` in `` |
+| `` | The header cell | `` |
+| `` | The header body | `` |
+| `` | The header row | `` in ` ` |
+| `` | The header cell | `` |
+
+### JS (via import)
+
+```javascript
+import '@carbon/web-components/es/components/data-table/index.js';
+```
+
+
+
+
+
+ Foo
+ Bar
+ Baz
+
+
+
+
+ Foo1
+ Bar1
+ Baz1
+
+
+ Foo2
+ Bar2
+ Baz2
+
+
+ Foo3
+ Bar3
+ Baz3
+
+
+
+
+```
+
+## Row selection
+
+Adding `selection-name` attribute to ``/``
+shows the selection UI in the table row.
+
+The logic of row selection needs to be handled on by the application code. When
+user attempts to change row selection, the following events fire:
+
+| Element | Event | Description |
+| ----------------------- | ------------------------------- | ------------------------------------------------------------- |
+| `` | `bx-table-row-change-selection` | Indicates user-initiated change in selection of a single row. |
+| `` | `bx-table-change-selection-all` | Indicates user-initiated change in selection of all rows. |
+
+Both of above events have the following properties in the event details:
+
+| Property | Description |
+| ---------- | ------------------------ |
+| `selected` | The new selection state. |
+
+Both of above events bubble and are cancelable. Canceling those events mean
+canceling change in selection.
+
+Application code should listen to those events update its internal state of
+table rows. To do so, it's convenient to add a `data-` attribte to each table
+rows so the delegated event handler can see which row the events are from.
+
+Here's an example of [`lit-html`](https://lit-html.polymer-project.org). Note
+that those events are native DOM events, and thus something like
+`document.addEventListener('bx-table-row-change-selection', event => { ... })`
+works, too:
+
+```javascript
+/**
+ * Handles an event to change in selection of rows, fired from ``,
+ * to update application's row selection states.
+ * @param {CustomEvent} event The event.
+ */
+const handleChangeSelection = event => {
+ if (!event.defaultPrevented) {
+ rows = this.rows.map(row => {
+ // The row ID you set to `` the event is fired on
+ const targetRowId = event.target.dataset.rowId;
+ return targetRowId !== row.id
+ ? row
+ : {
+ ...row,
+ selected: event.detail.selected,
+ };
+ });
+ }
+};
+
+/**
+ * Handles an event to change in selection of all rows, fired from ``,
+ * to update application's row selection states.
+ * @param {CustomEvent} event The event.
+ */
+const handleChangeSelectionAll = event => {
+ if (!event.defaultPrevented) {
+ rows = this.rows.map(row => ({
+ ...row,
+ selected: event.detail.selected,
+ }));
+ }
+};
+
+...
+
+html`
+
+
+
+ row.selected)} selection-name="my-row-selection-all">
+ Foo
+ Bar
+ Baz
+
+
+
+ ${rows.map(
+ row => html`
+
+ ${row.foo}
+ ${row.bar}
+ ${row.baz}
+
+ `
+ )}
+
+
+
+`;
+```
+
+## Sorting
+
+Adding `sort-direction` attribute to `` shows the sorting
+UI in the table header cell.
+
+The logic of sorting needs to be handled on by the application code. When user
+attempts to change sorting, `bx-table-header-cell-sort` event is fired, with the
+following properties in the event details:
+
+| Property | Description |
+| ------------------ | ----------------------- |
+| `oldSortDirection` | The old sort direction. |
+| `sortDirection` | The new sort direction. |
+
+`bx-table-header-cell-sort` event bubbles and is cancelable. Canceling
+`bx-table-header-cell-sort` event means canceling change in sort direction.
+
+Application code should listen to those events update its internal state of
+sorting. An example of the logic needed is available in our codesandbox example
+above. To do so, it's convenient to add a `data-` attribte to each table header
+cells so the delegated event handler can see which table column the events are
+from.
+
+Here's an example of [`lit-html`](https://lit-html.polymer-project.org). Note
+that those events are native DOM events, and thus something like
+`document.addEventListener('bx-table-header-cell-sort', event => { ... })`
+works, too:
+
+```javascript
+/**
+ * Handles an event to sort rows, fired from ``, to update application's sorting state.
+ * @param {CustomEvent} event The event.
+ */
+const handleChangeSort = event => {
+ if (!defaultPrevented) {
+ // Changes the sorting state upon user gesture
+ sortInfo = {
+ columnId: event.target.dataset.columnId,
+ direction: event.detail.direction,
+ };
+ }
+};
+
+...
+
+const collator = new Intl.Collator('en'); // Use the locale user is on
+
+/**
+ * Rows sorted by application's sorting state.
+ */
+const sortedRows = rows.slice().sort((lhs, rhs) => {
+ const lhsValue = lhs[sortInfo.columnId];
+ const rhsValue = rhs[sortInfo.columnId];
+ return (sortInfo.direction === 'ascending' ? 1 : -1) * collator.compare(lhsValue, rhsValue);
+});
+
+html`
+
+
+
+
+ Foo
+ Bar
+ Baz
+
+
+
+ ${sortedRows.map(
+ row => html`
+
+ ${row.foo}
+ ${row.bar}
+ ${row.baz}
+
+ `
+ )}
+
+
+
+`;
+```
+
+## Skeleton
+
+For the skeleton variation, utilize ``.
+
+```html
+
+
+
+ Name
+ Protocol
+ Port
+ Rule
+ Attached Groups
+ Status
+
+
+
+
+
+
+
+
+
+
+
+```
+
+## Attributes, properties and events
+
+Note: For `boolean` attributes, `true` means simply setting the attribute (e.g.
+``) and `false` means not setting the attribute (e.g.
+`` without `sort` attribute).
+
+### ``
+
+`
+
+`
+
+`
+
+`
+
+`
+
+`
+
+`
+
+`.
+ *
+ * @param event The event.
+ */
+ private _handleChangeSelection({
+ defaultPrevented,
+ detail,
+ target,
+ }: CustomEvent) {
+ if (!defaultPrevented) {
+ const { rowId: changedRowId } = (target as HTMLElement).dataset;
+ const { selected } = detail;
+ const { _rows: oldRows } = this;
+ this._rows = oldRows!.map((row) =>
+ Number(changedRowId) !== row.id ? row : { ...row, selected }
+ );
+ this.requestUpdate('_rows', oldRows);
+ }
+ }
+
+ /**
+ * Handles an event to change in selection of all rows, fired from ``.
+ *
+ * @param event The event.
+ */
+ private _handleChangeSelectionAll({ defaultPrevented, detail }: CustomEvent) {
+ if (!defaultPrevented) {
+ const { selected } = detail;
+ const { _rows: oldRows, _searchString: searchString } = this;
+ this._rows = this._rows!.map((row) =>
+ searchString && !doesRowMatchSearchString(row, searchString)
+ ? row
+ : { ...row, selected }
+ );
+ this.requestUpdate('_rows', oldRows);
+ }
+ }
+
+ /**
+ * Handles an event to sort rows, fired from ``.
+ *
+ * @param event The event.
+ */
+ private _handleChangeSort({ defaultPrevented, detail, target }: CustomEvent) {
+ if (!defaultPrevented) {
+ const { columnId } = (target as HTMLElement).dataset;
+ const { sortDirection: direction } = detail;
+ const { _sortInfo: oldSortInfo } = this;
+ if (direction === TABLE_SORT_DIRECTION.NONE && columnId !== 'name') {
+ // Resets the sorting, given non-primary sorting column has got in non-sorting state
+ this._sortInfo = this.sortInfo;
+ } else {
+ // Sets the sorting as user desires
+ this._sortInfo = {
+ columnId: columnId!,
+ direction,
+ };
+ }
+ this.requestUpdate('_sortInfo', oldSortInfo);
+ }
+ }
+
+ /**
+ * Handles `bx-pagination-changed-current` event on the pagination UI.
+ *
+ * @param event The event.
+ */
+ private _handleChangeStart({ detail }: CustomEvent) {
+ this.start = detail.start;
+ }
+
+ /**
+ * Handles `bx-pages-select-changed` event on the pagination UI.
+ *
+ * @param event The event.
+ */
+ private _handleChangePageSize({ detail }: CustomEvent) {
+ this.pageSize = detail.value;
+ }
+
+ /**
+ * Handles Delete batch action button.
+ */
+ private _handleDeleteRows() {
+ const { _rows: oldRows, _searchString: searchString } = this;
+ this._rows = oldRows!.filter(
+ (row) => !row.selected || !doesRowMatchSearchString(row, searchString)
+ );
+ this.requestUpdate('_rows', oldRows);
+ }
+
+ /**
+ * Handles Download batch action button.
+ *
+ * @param event The event triggering this action.
+ */
+ private _handleDownloadRows({ target }: MouseEvent) {
+ const blob = new Blob(
+ [JSON.stringify(this._filteredRows!.filter((row) => row.selected))],
+ { type: 'application/json' }
+ );
+ (target as BXBtn).href = URL.createObjectURL(blob);
+ this._handleCancelSelection();
+ }
+
+ /**
+ * @returns The content of the pagination UI.
+ */
+ private _renderPagination() {
+ const {
+ pageSize,
+ start,
+ _filteredRows: filteredRows,
+ _handleChangeStart: handleChangeStart,
+ _handleChangePageSize: handleChangePageSize,
+ } = this;
+ if (typeof pageSize === 'undefined') {
+ return undefined;
+ }
+ return html`
+
+
+ 5
+ 10
+ 15
+
+
+ `;
+ }
+
+ /**
+ * The g11n collator to use.
+ */
+ @property({ attribute: false })
+ collator = new Intl.Collator();
+
+ /**
+ * Data table columns.
+ */
+ @property({ attribute: false })
+ columns?: TDemoTableColumn[];
+
+ /**
+ * Data table rows.
+ */
+ @property({ attribute: false })
+ rows?: TDemoTableRow[];
+
+ /**
+ * Table sorting info.
+ */
+ @property({ attribute: false })
+ sortInfo?: TDemoSortInfo;
+
+ /**
+ * `true` if the the table should support selection UI.
+ */
+ @property({ type: Boolean, reflect: true, attribute: 'has-selection' })
+ hasSelection = false;
+
+ /**
+ * Number of items per page.
+ */
+ @property({ type: Number, attribute: 'page-size' })
+ pageSize!: number;
+
+ /**
+ * The table size.
+ */
+ @property({ reflect: true })
+ size = TABLE_SIZE.REGULAR;
+
+ /**
+ * The table color scheme.
+ */
+ @property({ reflect: true, attribute: 'color-scheme' })
+ colorScheme = TABLE_COLOR_SCHEME.REGULAR;
+
+ /**
+ * The row number where current page start with, index that starts with zero.
+ */
+ @property({ type: Number })
+ start = 0;
+
+ connectedCallback() {
+ super.connectedCallback();
+ if (this._handleChangeSearchString) {
+ this._handleChangeSearchString.cancel();
+ }
+ this._handleChangeSearchString = debounce(
+ this._handleChangeSearchStringImpl as () => void,
+ 500
+ );
+ }
+
+ disconnectedCallback() {
+ if (this._handleChangeSearchString) {
+ this._handleChangeSearchString.cancel();
+ this._handleChangeSearchString = undefined;
+ }
+ super.disconnectedCallback();
+ }
+
+ shouldUpdate(changedProperties) {
+ if (changedProperties.has('sortInfo')) {
+ this._sortInfo = this.sortInfo;
+ }
+ if (changedProperties.has('rows')) {
+ this._rows = this.rows;
+ }
+ if (
+ changedProperties.has('rows') ||
+ changedProperties.has('_rows') ||
+ changedProperties.has('_searchString')
+ ) {
+ const {
+ pageSize,
+ start,
+ _rows: rows,
+ _searchString: searchString,
+ } = this;
+ this._filteredRows = !searchString
+ ? rows!
+ : rows!.filter((row) => doesRowMatchSearchString(row, searchString));
+ const count = this._filteredRows.length;
+ if (count > 0 && start >= count) {
+ this.start = Math.max(
+ start - Math.ceil((start - count) / pageSize) * pageSize,
+ 0
+ );
+ }
+ }
+ return true;
+ }
+
+ render() {
+ const {
+ id: elementId,
+ colorScheme,
+ hasSelection,
+ pageSize = Infinity,
+ start = 0,
+ size,
+ columns,
+ _filteredRows: filteredRows,
+ _handleCancelSelection: handleCancelSelection,
+ _handleDeleteRows: handleDeleteRows,
+ _handleDownloadRows: handleDownloadRows,
+ } = this;
+ const selectionAllName = !hasSelection
+ ? undefined
+ : `__bx-ce-demo-data-table_select-all_${elementId || this._uniqueId}`;
+ const selectedRowsCountInFiltered = filteredRows!.filter(
+ ({ selected }) => selected!
+ ).length;
+ const selectedAllInFiltered =
+ selectedRowsCountInFiltered > 0 &&
+ filteredRows!.length === selectedRowsCountInFiltered;
+ const hasBatchActions = hasSelection && selectedRowsCountInFiltered > 0;
+ const { columnId: sortColumnId, direction: sortDirection } =
+ this._sortInfo!;
+ const sortedRows =
+ sortDirection === TABLE_SORT_DIRECTION.NONE
+ ? filteredRows!
+ : filteredRows!
+ .slice()
+ .sort(
+ (lhs, rhs) =>
+ (this.constructor as typeof BXCEDemoDataTable).collationFactors[
+ sortDirection
+ ] * this._compare(lhs[sortColumnId!], rhs[sortColumnId!])
+ );
+ return html`
+
+
+ Delete ${Delete16({ slot: 'icon' })}
+
+ Download ${Download16({ slot: 'icon' })}
+
+
+
+
+ ${Settings16({ slot: 'icon' })}
+
+ Action 1
+ Action 2
+ Action 3
+
+
+ Primary Button
+
+
+
+
+
+ ${repeat(
+ columns!,
+ ({ id: columnId }) => columnId,
+ ({ id: columnId, sortCycle, title }) => {
+ const sortDirectionForThisCell =
+ sortCycle &&
+ (columnId === sortColumnId
+ ? sortDirection
+ : TABLE_SORT_DIRECTION.NONE);
+ return html`
+
+ ${title}
+
+ `;
+ }
+ )}
+
+
+
+ ${repeat(
+ sortedRows.slice(start, start + pageSize),
+ ({ id: rowId }) => rowId,
+ (row) => {
+ const { id: rowId, selected } = row;
+ const selectionName = !hasSelection
+ ? undefined
+ : `__bx-ce-demo-data-table_${
+ elementId || this._uniqueId
+ }_${rowId}`;
+ const selectionValue = !hasSelection ? undefined : 'selected';
+ return html`
+
+ ${repeat(
+ columns!,
+ ({ id: columnId }) => columnId,
+ ({ id: columnId }) =>
+ html` ${row[columnId]} `
+ )}
+
+ `;
+ }
+ )}
+
+
+ ${this._renderPagination()}
+ `;
+ }
+
+ /**
+ * The map of how sorting direction affects sorting order.
+ */
+ static collationFactors = {
+ [TABLE_SORT_DIRECTION.ASCENDING]: 1,
+ [TABLE_SORT_DIRECTION.DESCENDING]: -1,
+ };
+}
+
+const colorSchemes = {
+ 'Regular color scheme': null,
+ [`Zebra (${TABLE_COLOR_SCHEME.ZEBRA})`]: TABLE_COLOR_SCHEME.ZEBRA,
+};
+
+const sizes = {
+ [`Compact size (${TABLE_SIZE.COMPACT})`]: TABLE_SIZE.COMPACT,
+ [`Short size (${TABLE_SIZE.SHORT})`]: TABLE_SIZE.SHORT,
+ 'Regular size': null,
+ [`Tall size (${TABLE_SIZE.TALL})`]: TABLE_SIZE.TALL,
+};
+
+const defineDemoDataTable = (() => {
+ let hasDemoDataTableDefined;
+ return () => {
+ if (!hasDemoDataTableDefined) {
+ hasDemoDataTableDefined = true;
+ const ce = customElements;
+ // Prevents `web-component-analyzer` from harvesting ``
+ ce.define('bx-ce-demo-data-table', BXCEDemoDataTable);
+ }
+ };
+})();
+
+export const Default = (args) => {
+ const { size } = args?.['bx-table'] ?? {};
+ const { colorScheme } = args?.['bx-table-body'] ?? {};
+ return html`
+
+
+
+ Name
+ Protocol
+ Port
+ Rule
+ Attached Groups
+ Status
+
+
+
+
+ Load Balancer 1
+ HTTP
+ 80
+ Round Robin
+ Maureen's VM Groups
+ Active
+
+
+ Load Balancer 2
+ HTTP
+ 80
+ Round Robin
+ Maureen's VM Groups
+ Active
+
+
+ Load Balancer 3
+ HTTP
+ 80
+ Round Robin
+ Maureen's VM Groups
+ Active
+
+
+
+ `;
+};
+
+Default.storyName = 'Default';
+
+Default.parameters = {
+ knobs: {
+ 'bx-table': () => ({
+ size: select('Table size (size)', sizes, null),
+ }),
+ 'bx-table-body': () => ({
+ colorScheme: select(
+ 'Color scheme (color-scheme in ``)',
+ colorSchemes,
+ null
+ ),
+ }),
+ },
+};
+
+export const expandable = (args) => {
+ const { size } = args?.['bx-table'] ?? {};
+ const { zebra } = args?.['bx-table-body'] ?? {};
+ const handleExpandRowAll = (event) => {
+ const { currentTarget, detail } = event;
+ const rows = currentTarget.querySelectorAll('bx-table-expand-row');
+ Array.prototype.forEach.call(rows, (row) => {
+ row.expanded = detail.expanded;
+ });
+ };
+ const handleExpandRow = (event) => {
+ const { currentTarget } = event;
+ const headerRow = currentTarget.querySelector('bx-table-header-expand-row');
+ const rows = currentTarget.querySelectorAll('bx-table-expand-row');
+ headerRow.expanded = Array.prototype.every.call(
+ rows,
+ (row) => row.expanded
+ );
+ };
+ return html`
+
+
+
+ Name
+ Protocol
+ Port
+ Rule
+ Attached Groups
+ Status
+
+
+
+
+ Load Balancer 1
+ HTTP
+ 80
+ Round Robin
+ Maureen's VM Groups
+ Active
+
+
+ Expandable row content
+ Description here
+
+
+ Load Balancer 2
+ HTTP
+ 80
+ Round Robin
+ Maureen's VM Groups
+ Active
+
+
+ Expandable row content
+ Description here
+
+
+ Load Balancer 3
+ HTTP
+ 80
+ Round Robin
+ Maureen's VM Groups
+ Active
+
+
+ Expandable row content
+ Description here
+
+
+
+ `;
+};
+
+expandable.parameters = {
+ knobs: {
+ ...Default.parameters.knobs,
+ 'bx-table-body': () => ({}),
+ },
+};
+
+export const sortable = (args) => {
+ const { size } = args?.['bx-table'] ?? {};
+ const { onBeforeChangeSelection: onBeforeChangeSelectionAll } =
+ args?.['bx-table-header-row'] ?? {};
+ const { colorScheme } = args?.['bx-table-body'] ?? {};
+ const { hasSelection, disableChangeSelection, onBeforeChangeSelection } =
+ args?.['bx-table-row'] ?? {};
+ const { disableChangeSort, onBeforeSort } =
+ args?.['bx-table-header-cell'] ?? {};
+ const beforeChangeSelectionHandler = {
+ handleEvent(event: CustomEvent) {
+ if (event.type === 'bx-table-change-selection-all') {
+ onBeforeChangeSelectionAll(event);
+ } else {
+ onBeforeChangeSelection(event);
+ }
+ if (disableChangeSelection) {
+ event.preventDefault();
+ }
+ },
+ capture: true, // To prevent the default behavior before `` handles the event
+ };
+ const beforeChangeSortHandler = {
+ handleEvent(event: CustomEvent) {
+ onBeforeSort(event);
+ if (disableChangeSort) {
+ event.preventDefault();
+ }
+ },
+ capture: true, // To prevent the default behavior before `` handles the event
+ };
+ defineDemoDataTable();
+ return html`
+
+
+
+
+ `;
+};
+
+sortable.parameters = {
+ knobs: {
+ ...Default.parameters.knobs,
+ 'bx-table-header-row': () => ({
+ onBeforeChangeSelection: action('bx-table-change-selection-all'),
+ }),
+ 'bx-table-row': () => {
+ const hasSelection = boolean(
+ 'Supports selection feature (has-selection)',
+ false
+ );
+ return {
+ hasSelection,
+ disableChangeSelection:
+ hasSelection &&
+ boolean(
+ 'Disable user-initiated change in selection ' +
+ '(Call event.preventDefault() in bx-table-row-change-selection/bx-table-change-selection-all events)',
+ false
+ ),
+ onBeforeChangeSelection: action('bx-table-row-change-selection'),
+ };
+ },
+ 'bx-table-header-cell': () => ({
+ disableChangeSort: boolean(
+ 'Disable user-initiated change in sorting (Call event.preventDefault() in bx-table-header-cell-sort event)',
+ false
+ ),
+ onBeforeSort: action('bx-table-header-cell-sort'),
+ }),
+ },
+};
+
+export const sortableWithPagination = (args) => {
+ const { size } = args?.['bx-table'] ?? {};
+ const { onBeforeChangeSelection: onBeforeChangeSelectionAll } =
+ args?.['bx-table-header-row'] ?? {};
+ const { colorScheme } = args?.['bx-table-body'] ?? {};
+ const { hasSelection, disableChangeSelection, onBeforeChangeSelection } =
+ args?.['bx-table-row'] ?? {};
+ const { disableChangeSort, onBeforeSort } =
+ args?.['bx-table-header-cell'] ?? {};
+ const beforeChangeSelectionHandler = {
+ handleEvent(event: CustomEvent) {
+ if (event.type === 'bx-table-change-selection-all') {
+ onBeforeChangeSelectionAll(event);
+ } else {
+ onBeforeChangeSelection(event);
+ }
+ if (disableChangeSelection) {
+ event.preventDefault();
+ }
+ },
+ capture: true, // To prevent the default behavior before `` handles the event
+ };
+ const beforeChangeSortHandler = {
+ handleEvent(event: CustomEvent) {
+ onBeforeSort(event);
+ if (disableChangeSort) {
+ event.preventDefault();
+ }
+ },
+ capture: true, // To prevent the default behavior before `` handles the event
+ };
+ defineDemoDataTable();
+ return html`
+
+
+
+
+ `;
+};
+
+sortableWithPagination.storyName = 'Sortable with pagination';
+
+sortableWithPagination.parameters = {
+ knobs: sortable.parameters.knobs,
+};
+
+export const skeleton = (args) => {
+ const { size } = args?.['bx-table'];
+ const { colorScheme } = args?.['bx-table-body'];
+ return html`
+
+
+
+ Name
+ Protocol
+ Port
+ Rule
+ Attached Groups
+ Status
+
+
+
+
+
+
+
+
+
+
+
+ `;
+};
+
+skeleton.parameters = {
+ percy: {
+ skip: true,
+ },
+ knobs: {
+ ...Default.parameters.knobs,
+ },
+};
+
+export default {
+ title: 'Components/Data table',
+ parameters: {
+ ...storyDocs.parameters,
+ },
+};
diff --git a/packages/carbon-web-components/src/components/data-table/data-table.scss b/packages/carbon-web-components/src/components/data-table/data-table.scss
new file mode 100644
index 00000000000..4e14c8b9bc4
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/data-table.scss
@@ -0,0 +1,24 @@
+//
+// Copyright IBM Corp. 2019, 2022
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+$css--plex: true !default;
+
+@import 'carbon-components/scss/globals/scss/vendor/@carbon/elements/scss/type/font-family';
+@import 'carbon-components/scss/components/checkbox/checkbox';
+
+@import 'carbon-components/scss/components/data-table/data-table-core';
+@import 'carbon-components/scss/components/data-table/data-table-expandable';
+@import 'carbon-components/scss/components/data-table/data-table-inline-edit';
+@import 'carbon-components/scss/components/data-table/data-table-skeleton';
+
+@import 'table-action';
+@import 'table-core';
+@import 'table-expandable';
+@import 'table-sizes';
+@import 'table-selection';
+@import 'table-sort';
+@import 'table-skeleton';
diff --git a/packages/carbon-web-components/src/components/data-table/defs.ts b/packages/carbon-web-components/src/components/data-table/defs.ts
new file mode 100644
index 00000000000..1e01363f80b
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/defs.ts
@@ -0,0 +1,102 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2020, 2022
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Table color scheme.
+ */
+export enum TABLE_COLOR_SCHEME {
+ /**
+ * Regular color scheme.
+ */
+ REGULAR = '',
+
+ /**
+ * Color scheme with zebra stripe.
+ */
+ ZEBRA = 'zebra',
+}
+
+/**
+ * Table size.
+ */
+export enum TABLE_SIZE {
+ /**
+ * Compact size.
+ */
+ COMPACT = 'compact',
+
+ /**
+ * Short size.
+ */
+ SHORT = 'short',
+
+ /**
+ * Regular size.
+ */
+ REGULAR = '',
+
+ /**
+ * Tall size.
+ */
+ TALL = 'tall',
+}
+
+/**
+ * Table sort state.
+ */
+export enum TABLE_SORT_DIRECTION {
+ /**
+ * Not sorted.
+ */
+ NONE = 'none',
+
+ /**
+ * Sorted ascendingly.
+ */
+ ASCENDING = 'ascending',
+
+ /**
+ * Sorted descendingly.
+ */
+ DESCENDING = 'descending',
+}
+
+/**
+ * Table sort cycle.
+ */
+export enum TABLE_SORT_CYCLE {
+ BI_STATES_FROM_ASCENDING = 'bi-states-from-ascending',
+ BI_STATES_FROM_DESCENDING = 'bi-states-from-descending',
+ TRI_STATES_FROM_ASCENDING = 'tri-states-from-ascending',
+ TRI_STATES_FROM_DESCENDING = 'tri-states-from-descending',
+}
+
+/**
+ * Mapping of table sort cycles to table sort states.
+ */
+export const TABLE_SORT_CYCLES = {
+ [TABLE_SORT_CYCLE.BI_STATES_FROM_ASCENDING]: [
+ TABLE_SORT_DIRECTION.ASCENDING,
+ TABLE_SORT_DIRECTION.DESCENDING,
+ ],
+ [TABLE_SORT_CYCLE.BI_STATES_FROM_DESCENDING]: [
+ TABLE_SORT_DIRECTION.DESCENDING,
+ TABLE_SORT_DIRECTION.ASCENDING,
+ ],
+ [TABLE_SORT_CYCLE.TRI_STATES_FROM_ASCENDING]: [
+ TABLE_SORT_DIRECTION.NONE,
+ TABLE_SORT_DIRECTION.ASCENDING,
+ TABLE_SORT_DIRECTION.DESCENDING,
+ ],
+ [TABLE_SORT_CYCLE.TRI_STATES_FROM_DESCENDING]: [
+ TABLE_SORT_DIRECTION.NONE,
+ TABLE_SORT_DIRECTION.DESCENDING,
+ TABLE_SORT_DIRECTION.ASCENDING,
+ ],
+};
diff --git a/packages/carbon-web-components/src/components/data-table/index.ts b/packages/carbon-web-components/src/components/data-table/index.ts
new file mode 100644
index 00000000000..c363e4f18c8
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/index.ts
@@ -0,0 +1,25 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2021
+ *
+ * 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 './table';
+import './table-batch-actions';
+import './table-body';
+import './table-cell';
+import './table-cell-skeleton';
+import './table-expand-row';
+import './table-expanded-row';
+import './table-head';
+import './table-header-cell';
+import './table-header-cell-skeleton';
+import './table-header-expand-row';
+import './table-header-row';
+import './table-row';
+import './table-toolbar';
+import './table-toolbar-content';
+import './table-toolbar-search';
diff --git a/packages/carbon-web-components/src/components/data-table/stories/data.ts b/packages/carbon-web-components/src/components/data-table/stories/data.ts
new file mode 100644
index 00000000000..64ac85ebe94
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/stories/data.ts
@@ -0,0 +1,88 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019
+ *
+ * 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 'core-js/modules/es.array.flat.js';
+import 'core-js/modules/es.string.pad-start.js';
+import { TABLE_SORT_DIRECTION } from '../table-header-cell';
+import { TDemoTableColumn, TDemoTableRow, TDemoSortInfo } from './types';
+
+export const columns: TDemoTableColumn[] = [
+ {
+ id: 'name',
+ title: 'Name',
+ sortCycle: 'bi-states-from-ascending',
+ },
+ {
+ id: 'protocol',
+ title: 'Protocol',
+ },
+ {
+ id: 'port',
+ title: 'Port',
+ sortCycle: 'tri-states-from-ascending',
+ },
+ {
+ id: 'rule',
+ title: 'Rule',
+ },
+ {
+ id: 'attachedGroups',
+ title: 'Attached Groups',
+ },
+ {
+ id: 'status',
+ title: 'Status',
+ },
+];
+
+export const rows: TDemoTableRow[] = [
+ {
+ id: 1,
+ name: 'Load Balancer 1',
+ protocol: 'HTTP',
+ port: 80,
+ rule: 'Round Robin',
+ attachedGroups: "Maureen's VM Groups",
+ status: 'Active',
+ },
+ {
+ id: 2,
+ name: 'Load Balancer 2',
+ protocol: 'HTTPS',
+ port: 443,
+ rule: 'Round Robin',
+ attachedGroups: "Maureen's VM Groups",
+ status: 'Active',
+ },
+ {
+ id: 3,
+ selected: true,
+ name: 'Load Balancer 3',
+ protocol: 'HTTP',
+ port: 80,
+ rule: 'Round Robin',
+ attachedGroups: "Maureen's VM Groups",
+ status: 'Active',
+ },
+];
+
+export const rowsMany: TDemoTableRow[] = Array.from(new Array(50))
+ .map((_item, i) =>
+ rows.map((row, j) => ({
+ ...row,
+ id: i * 3 + j,
+ name: `Load Balancer ${String(i * 3 + j + 1).padStart(3, '0')}`,
+ }))
+ )
+ .flat();
+
+export const sortInfo: TDemoSortInfo = {
+ columnId: 'name',
+ direction: TABLE_SORT_DIRECTION.ASCENDING,
+};
diff --git a/packages/carbon-web-components/src/components/data-table/stories/types.ts b/packages/carbon-web-components/src/components/data-table/stories/types.ts
new file mode 100644
index 00000000000..0e47e6fd9a5
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/stories/types.ts
@@ -0,0 +1,36 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019
+ *
+ * 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 { TABLE_SORT_DIRECTION } from '../table-header-cell';
+
+/**
+ * Example data structure of data table column.
+ */
+export type TDemoTableColumn = {
+ id: string;
+ title: string;
+ sortCycle?: string;
+};
+
+/**
+ * Example data structure of data table row.
+ */
+export type TDemoTableRow = {
+ id: number;
+ selected?: boolean;
+ [key: string]: any;
+};
+
+/**
+ * Example structure of table sorting info.
+ */
+export type TDemoSortInfo = {
+ columnId: string;
+ direction: TABLE_SORT_DIRECTION;
+};
diff --git a/packages/carbon-web-components/src/components/data-table/table-batch-actions.ts b/packages/carbon-web-components/src/components/data-table/table-batch-actions.ts
new file mode 100644
index 00000000000..2e49854c8ad
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/table-batch-actions.ts
@@ -0,0 +1,93 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019, 2022
+ *
+ * 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 { html, property, customElement, LitElement } from 'lit-element';
+import settings from 'carbon-components/es/globals/js/settings';
+import styles from './data-table.scss';
+
+const { prefix } = settings;
+
+/**
+ * Table batch actions.
+ *
+ * @element bx-table-batch-actions
+ * @fires bx-table-batch-actions-cancel-clicked - The custom event fired after the Cancel button is clicked.
+ */
+@customElement(`${prefix}-table-batch-actions`)
+class BXTableBatchActions extends LitElement {
+ /**
+ * Handles `click` event on the Cancel button.
+ */
+ private _handleCancel() {
+ const { eventClickCancel } = this.constructor as typeof BXTableBatchActions;
+ this.dispatchEvent(
+ new CustomEvent(eventClickCancel, { bubbles: true, composed: true })
+ );
+ }
+
+ /**
+ * `true` if this batch actions bar should be active.
+ */
+ @property({ type: Boolean, reflect: true })
+ active = false;
+
+ /**
+ * The formatter for selected items. Should be changed upon the locale the UI is rendered with.
+ */
+ @property({ attribute: false })
+ formatSelectedItemsCount = ({ count }) =>
+ `${count} item${count <= 1 ? '' : 's'} selected`;
+
+ /**
+ * Numeric representation of the total number of items selected in a table.
+ * This number is used to derive the selection message.
+ */
+ @property({ type: Number, attribute: 'selected-rows-count' })
+ selectedRowsCount = 0;
+
+ updated(changedProperties) {
+ if (changedProperties.has('active')) {
+ this.setAttribute('tabindex', `${this.active ? '' : '-1'}`);
+ }
+ }
+
+ render() {
+ const {
+ formatSelectedItemsCount,
+ selectedRowsCount,
+ _handleCancel: handleCancel,
+ } = this;
+ return html`
+
+
+ ${formatSelectedItemsCount({ count: selectedRowsCount })}
+
+
+
+ Cancel
+
+
+ `;
+ }
+
+ /**
+ * The name of the custom event fired after the Cancel button is clicked.
+ */
+ static get eventClickCancel() {
+ return `${prefix}-table-batch-actions-cancel-clicked`;
+ }
+
+ static styles = styles;
+}
+
+export default BXTableBatchActions;
diff --git a/packages/carbon-web-components/src/components/data-table/table-body.ts b/packages/carbon-web-components/src/components/data-table/table-body.ts
new file mode 100644
index 00000000000..18da5154575
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/table-body.ts
@@ -0,0 +1,81 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019, 2022
+ *
+ * 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 settings from 'carbon-components/es/globals/js/settings';
+import { html, property, query, customElement, LitElement } from 'lit-element';
+import { TABLE_COLOR_SCHEME } from './defs';
+import BXTableRow from './table-row';
+import styles from './data-table.scss';
+
+const { prefix } = settings;
+
+/**
+ * Data table body.
+ *
+ * @element bx-table-body
+ */
+@customElement(`${prefix}-table-body`)
+class BXTableBody extends LitElement {
+ /**
+ * The `` element in the shadow DOM.
+ */
+ @query('slot')
+ private _slotNode!: HTMLSlotElement;
+
+ /**
+ * Updates `even`/`odd` properties of the child ``s.
+ */
+ private _updateZebra() {
+ const { colorScheme, _slotNode: slotNode } = this;
+ slotNode.assignedNodes().forEach((node) => {
+ if (node.nodeType === Node.ELEMENT_NODE) {
+ const odd = (node as HTMLElement).matches('*:nth-of-type(odd)');
+ (node as BXTableRow).even =
+ colorScheme === TABLE_COLOR_SCHEME.ZEBRA && !odd;
+ (node as BXTableRow).odd =
+ colorScheme === TABLE_COLOR_SCHEME.ZEBRA && odd;
+ }
+ });
+ }
+
+ /**
+ * Handles `slotchange` event in the `` element in the shadow DOM.
+ */
+ private _handleSlotChange = () => {
+ this._updateZebra();
+ };
+
+ /**
+ * The color scheme.
+ */
+ @property({ reflect: true, attribute: 'color-scheme' })
+ colorScheme = TABLE_COLOR_SCHEME.REGULAR;
+
+ connectedCallback() {
+ if (!this.hasAttribute('role')) {
+ this.setAttribute('role', 'rowgroup');
+ }
+ super.connectedCallback();
+ }
+
+ updated(changedProperties) {
+ if (changedProperties.has('colorScheme')) {
+ this._updateZebra();
+ }
+ }
+
+ render() {
+ const { _handleSlotChange: handleSlotChange } = this;
+ return html`
+
+ ${ChevronRight16({ class: `${prefix}--table-expand__svg` })}
+
+
+ ${super._renderFirstCells()}
+ `;
+ }
+
+ /**
+ * `true` if the table row should be expanded.
+ */
+ @property({ type: Boolean, reflect: true })
+ expanded = false;
+
+ updated(changedProperties) {
+ if (changedProperties.has('expanded')) {
+ const { selectorExpandedRow } = this
+ .constructor as typeof BXTableExpandRow;
+ const { expanded, nextElementSibling } = this;
+ if (nextElementSibling?.matches(selectorExpandedRow)) {
+ (nextElementSibling as BXTableExpandedRow).expanded = expanded;
+ }
+ }
+ }
+
+ /**
+ * A selector that will return the corresponding expanded row.
+ */
+ static get selectorExpandedRow() {
+ return `${prefix}-table-expanded-row`;
+ }
+
+ /**
+ * The name of the custom event fired before the expanded state this row is being toggled upon a user gesture.
+ * Cancellation of this event stops the user-initiated action of toggling the expanded state.
+ */
+ static get eventBeforeExpandoToggle() {
+ return `${prefix}-table-row-expando-beingtoggled`;
+ }
+
+ /**
+ * The name of the custom event fired after the expanded state this row is toggled upon a user gesture.
+ */
+ static get eventExpandoToggle() {
+ return `${prefix}-table-row-expando-toggled`;
+ }
+
+ static styles = styles; // `styles` here is a `CSSResult` generated by custom WebPack loader
+}
+
+export default BXTableExpandRow;
diff --git a/packages/carbon-web-components/src/components/data-table/table-expanded-row.ts b/packages/carbon-web-components/src/components/data-table/table-expanded-row.ts
new file mode 100644
index 00000000000..7f0f72b2184
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/table-expanded-row.ts
@@ -0,0 +1,55 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2020, 2022
+ *
+ * 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 { html, property, customElement, LitElement } from 'lit-element';
+import settings from 'carbon-components/es/globals/js/settings';
+import styles from './data-table.scss';
+
+const { prefix } = settings;
+
+/**
+ * Table row of collapsible details.
+ *
+ * @element bx-table-expanded-row
+ */
+@customElement(`${prefix}-table-expanded-row`)
+class BXTableExpandedRow extends LitElement {
+ /**
+ * The colspan.
+ */
+ @property({ type: Number, attribute: 'colspan' })
+ colSpan = 1;
+
+ /**
+ * `true` if the table row should be expanded.
+ */
+ @property({ type: Boolean, reflect: true })
+ expanded = false;
+
+ /**
+ * `true` if the table row should be highlighted.
+ */
+ @property({ type: Boolean, reflect: true })
+ highlighted = false;
+
+ render() {
+ const { colSpan } = this;
+ return html`
+
+
+
+
+ `;
+ }
+
+ static styles = styles; // `styles` here is a `CSSResult` generated by custom WebPack loader
+}
+
+export default BXTableExpandedRow;
diff --git a/packages/carbon-web-components/src/components/data-table/table-head.ts b/packages/carbon-web-components/src/components/data-table/table-head.ts
new file mode 100644
index 00000000000..3fe0cf64420
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/table-head.ts
@@ -0,0 +1,37 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019, 2022
+ *
+ * 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 settings from 'carbon-components/es/globals/js/settings';
+import { html, customElement, LitElement } from 'lit-element';
+import styles from './data-table.scss';
+
+const { prefix } = settings;
+
+/**
+ * Data table header.
+ *
+ * @element bx-table-head
+ */
+@customElement(`${prefix}-table-head`)
+class BXTableHead extends LitElement {
+ connectedCallback() {
+ if (!this.hasAttribute('role')) {
+ this.setAttribute('role', 'rowgroup');
+ }
+ super.connectedCallback();
+ }
+
+ render() {
+ return html`
+
+ ${sortIcon}
+
+ `;
+ }
+ return html`
+ ${html`
+
+ `;
+ }
+
+ /**
+ * `true` if this table row should be disabled.
+ */
+ @property({ type: Boolean, reflect: true })
+ disabled = false;
+
+ /**
+ * `true` if this table row is placed at an even position in parent ``.
+ * `` sets this property, _only_ in zebra stripe mode.
+ *
+ * @private
+ */
+ @property({ type: Boolean, reflect: true })
+ even = false;
+
+ /**
+ * `true` if this table row is placed at an odd position in parent ``.
+ * `` sets this property, _only_ in zebra stripe mode.
+ *
+ * @private
+ */
+ @property({ type: Boolean, reflect: true })
+ odd = false;
+
+ /**
+ * `true` if this table row should be selected.
+ */
+ @property({ type: Boolean, reflect: true })
+ selected = false;
+
+ /**
+ * The `aria-label` attribute for the `` for selection.
+ */
+ @property({ attribute: 'selection-label' })
+ selectionLabel = '';
+
+ /**
+ * The `name` attribute for the `
+ ${result}
+
+ `;
+ }
+
+ /**
+ * The name of the custom event fired after the search content is changed upon a user gesture.
+ */
+ static get eventInput() {
+ // The code uses on in ``, but definition is done also here for React event generation
+ return `${prefix}-search-input`;
+ }
+
+ static styles = styles;
+}
+
+export default BXTableToolbarSearch;
diff --git a/packages/carbon-web-components/src/components/data-table/table-toolbar.ts b/packages/carbon-web-components/src/components/data-table/table-toolbar.ts
new file mode 100644
index 00000000000..6b076bb8d24
--- /dev/null
+++ b/packages/carbon-web-components/src/components/data-table/table-toolbar.ts
@@ -0,0 +1,37 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019, 2022
+ *
+ * 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 { html, customElement, LitElement } from 'lit-element';
+import settings from 'carbon-components/es/globals/js/settings';
+import styles from './data-table.scss';
+
+const { prefix } = settings;
+
+/**
+ * Table toolbar.
+ *
+ * @element bx-table-toolbar
+ */
+@customElement(`${prefix}-table-toolbar`)
+class BXTableToolbar extends LitElement {
+ connectedCallback() {
+ if (!this.hasAttribute('role')) {
+ this.setAttribute('role', 'section');
+ }
+ super.connectedCallback();
+ }
+
+ render() {
+ return html`
+ `;
+ }
+
+ static styles = styles;
+}
+
+export default BXDatePickerInputSkeleton;
diff --git a/packages/carbon-web-components/src/components/date-picker/date-picker-input.ts b/packages/carbon-web-components/src/components/date-picker/date-picker-input.ts
new file mode 100644
index 00000000000..27055de1d68
--- /dev/null
+++ b/packages/carbon-web-components/src/components/date-picker/date-picker-input.ts
@@ -0,0 +1,298 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019, 2022
+ *
+ * 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 { classMap } from 'lit-html/directives/class-map';
+import { html, property, query, customElement, LitElement } from 'lit-element';
+import Calendar16 from '@carbon/icons/lib/calendar/16';
+import settings from 'carbon-components/es/globals/js/settings';
+import ifNonNull from '../../globals/directives/if-non-null';
+import FocusMixin from '../../globals/mixins/focus';
+import ValidityMixin from '../../globals/mixins/validity';
+import { INPUT_SIZE } from '../input/input';
+import {
+ DATE_PICKER_INPUT_COLOR_SCHEME,
+ DATE_PICKER_INPUT_KIND,
+ DATE_PICKER_INPUT_SIZE_HORIZONTAL,
+} from './defs';
+import styles from './date-picker.scss';
+
+export {
+ DATE_PICKER_INPUT_COLOR_SCHEME,
+ DATE_PICKER_INPUT_KIND,
+ DATE_PICKER_INPUT_SIZE_HORIZONTAL,
+};
+
+const { prefix } = settings;
+
+/**
+ * The input box for date picker.
+ *
+ * @element bx-date-picker-input
+ */
+@customElement(`${prefix}-date-picker-input`)
+class BXDatePickerInput extends ValidityMixin(FocusMixin(LitElement)) {
+ /**
+ * The calendar icon.
+ */
+ @query(`.${prefix}--date-picker__icon`)
+ private _iconNode!: SVGElement;
+
+ /**
+ * The `` for the validity message.
+ */
+ @query('slot[name="validity-message"]')
+ private _slotValidityMessage!: HTMLSlotElement;
+
+ /**
+ * `true` if validity message is given via `validityMessage` property or via ``.
+ */
+ private get _hasValidityMessage() {
+ const { validityMessage, _slotValidityMessage: slotValidityMessage } = this;
+ return (
+ validityMessage ||
+ (slotValidityMessage && slotValidityMessage.assignedNodes.length > 0)
+ );
+ }
+
+ /**
+ * Handles `click` event on the calendar icon.
+ *
+ * @param event The event.
+ */
+ private _handleClickWrapper(event: MouseEvent) {
+ if (event.target === this._iconNode) {
+ this.input.focus();
+ }
+ }
+
+ /**
+ * Handles `slotchange` event on ``.
+ */
+ private _handleSlotChangeValidityMessage() {
+ this.requestUpdate();
+ }
+
+ /**
+ * Handles `input` event on `Open calendar `],
+ });
+ }
+
+ /**
+ * @returns The template for the the validity message.
+ */
+ private _renderValidityMessage() {
+ const {
+ validityMessage,
+ _hasValidityMessage: hasValidityMessage,
+ _handleSlotChangeValidityMessage: handleSlotChangeValidityMessage,
+ } = this;
+ return html`
+
+ ${validityMessage}
+
+ `;
+ }
+
+ /**
+ * The `
+ ${labelText}
+
+
+
+ ${this._renderValidityMessage()}
+ `;
+ }
+
+ /**
+ * The default value for `pattern` property.
+ */
+ static defaultPattern = '\\d{1,2}\\/\\d{1,2}\\/\\d{4}';
+
+ /**
+ * The default value for `type` property.
+ */
+ static defaultType = 'text';
+
+ /**
+ * A selector that will return the parent date picker.
+ */
+ static get selectorParent() {
+ return `${prefix}-date-picker`;
+ }
+
+ static styles = styles;
+}
+
+export default BXDatePickerInput;
diff --git a/packages/carbon-web-components/src/components/date-picker/date-picker-story.mdx b/packages/carbon-web-components/src/components/date-picker/date-picker-story.mdx
new file mode 100644
index 00000000000..b51f43803b4
--- /dev/null
+++ b/packages/carbon-web-components/src/components/date-picker/date-picker-story.mdx
@@ -0,0 +1,114 @@
+import { Props, Description } from '@storybook/addon-docs/blocks';
+import { cdnJs, cdnCss } from '../../globals/internal/storybook-cdn';
+
+# Date picker
+
+> ๐ก Check our
+> [CodeSandbox](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/basic/components/date-picker)
+> example implementation.
+
+[](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/basic/components/date-picker)
+
+Date and time pickers allow users to select a single or a range of dates and
+times.
+
+## Getting started
+
+Here's a quick example to get you started.
+
+### JS (via import)
+
+```javascript
+import '@carbon/web-components/es/components/date-picker/index.js';
+```
+
+
+
+
+
+```
+
+## Single date picker
+
+A single Date Picker consists of an input field and a calendar.
+
+```html
+
+
+
+
+```
+
+## Range date picker
+
+A range Date Picker consists of two input fields and a calendar.
+
+```html
+
+
+
+
+
+
+```
+
+## Skeleton
+
+For the skeleton variation, utilize ``.
+
+### Simple
+
+```html
+
+
+```
+
+## `` attributes, properties and events
+
+Note: For `boolean` attributes, `true` means simply setting the attribute (e.g.
+``) and `false` means not setting the attribute (e.g.
+`` without `open` attribute).
+
+` attributes and properties
+
+Note: For `boolean` attributes, `true` means simply setting the attribute (e.g.
+``) and `false` means not setting the attribute
+(e.g. `` without `light` attribute).
+
+)', false),
+ enabledRange: textNullable(
+ 'Minimum/maximum dates in ISO8601 date format, separated by `/` (enabled-range)',
+ ''
+ ),
+ open: boolean('Open (open)', false),
+ value: textNullable(
+ 'Value in ISO8601 date format, separated by `/` (value)',
+ ''
+ ),
+ onAfterChanged: action('bx-date-picker-changed'),
+ onFlatpickrError: action('bx-date-picker-flatpickr-error'),
+ }),
+ 'bx-date-picker-input': () => ({
+ colorScheme: select(
+ 'Color scheme (color-scheme in )',
+ colorSchemes,
+ null
+ ),
+ hideLabel: boolean(
+ 'Hide label (hide-label in )',
+ false
+ ),
+ invalid: boolean('Show invalid state (invalid)', false),
+ labelText: textNullable(
+ 'Label text (label-text in )',
+ 'Date Picker label'
+ ),
+ placeholder: textNullable(
+ 'Placeholder text (placeholder in )',
+ 'mm/dd/yyyy'
+ ),
+ size: select('Input size (size)', sizes, INPUT_SIZE.REGULAR),
+ validityMessage: textNullable(
+ 'The validity message (validity-message)',
+ ''
+ ),
+ onInput: action('input'),
+ }),
+};
+
+const sizesHorizontal = {
+ 'Regular size': null,
+ [`Short size (${DATE_PICKER_INPUT_SIZE_HORIZONTAL.SHORT})`]:
+ DATE_PICKER_INPUT_SIZE_HORIZONTAL.SHORT,
+};
+
+export const Default = (args) => {
+ const { disabled, name, value } = args?.['bx-date-picker'] ?? {};
+ const {
+ colorScheme,
+ hideLabel,
+ invalid,
+ labelText,
+ placeholder,
+ size,
+ sizeHorizontal,
+ validityMessage,
+ } = args?.['bx-date-picker-input'] ?? {};
+ return html`
+
+
+
+
+ `;
+};
+
+Default.storyName = 'Default';
+
+Default.parameters = {
+ knobs: {
+ 'bx-date-picker-input': () => ({
+ ...knobs['bx-date-picker-input'](),
+ sizeHorizontal: select(
+ 'Horizontal size (size-horizontal)',
+ sizesHorizontal,
+ null
+ ),
+ }),
+ },
+};
+
+export const singleWithCalendar = (args) => {
+ const {
+ dateFormat,
+ disabled,
+ enabledRange,
+ name,
+ open,
+ value,
+ onChanged,
+ onFlatpickrError,
+ } = args?.['bx-date-picker'] ?? {};
+ const {
+ colorScheme,
+ hideLabel,
+ invalid,
+ labelText,
+ placeholder,
+ size,
+ validityMessage,
+ onInput,
+ } = args?.['bx-date-picker-input'] ?? {};
+ return html`
+
+
+
+
+ `;
+};
+
+singleWithCalendar.storyName = 'Single with calendar';
+
+singleWithCalendar.parameters = {
+ knobs,
+};
+
+export const rangeWithCalendar = (args) => {
+ const {
+ dateFormat,
+ disabled,
+ enabledRange,
+ name,
+ open,
+ value,
+ onChanged,
+ onFlatpickrError,
+ } = args?.['bx-date-picker'] ?? {};
+ const {
+ colorScheme,
+ hideLabel,
+ invalid,
+ labelText,
+ placeholder,
+ size,
+ validityMessage,
+ onInput,
+ } = args?.['bx-date-picker-input'] ?? {};
+ return html`
+
+
+
+
+
+
+ `;
+};
+
+rangeWithCalendar.storyName = 'Range with calendar';
+
+rangeWithCalendar.parameters = {
+ knobs,
+};
+
+export const skeletonSimple = () =>
+ html` ${story()}
`];
+
+skeletonRange.parameters = {
+ percy: {
+ skip: true,
+ },
+};
+
+export default {
+ title: 'Components/Date picker',
+ parameters: {
+ ...storyDocs.parameters,
+ },
+};
diff --git a/packages/carbon-web-components/src/components/date-picker/date-picker.scss b/packages/carbon-web-components/src/components/date-picker/date-picker.scss
new file mode 100644
index 00000000000..cffdb8994b7
--- /dev/null
+++ b/packages/carbon-web-components/src/components/date-picker/date-picker.scss
@@ -0,0 +1,130 @@
+//
+// Copyright IBM Corp. 2019, 2022
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+$css--plex: true !default;
+
+@import 'carbon-components/scss/globals/scss/css--helpers';
+@import 'carbon-components/scss/components/form/form';
+@import 'carbon-components/scss/components/date-picker/date-picker';
+
+:host(#{$prefix}-date-picker) {
+ @extend .#{$prefix}--date-picker;
+
+ #floating-menu-container {
+ position: absolute;
+ width: 100%;
+ }
+
+ .#{$prefix}--date-picker__calendar.open {
+ margin-top: 0;
+ }
+
+ .flatpickr-next-month,
+ .flatpickr-prev-month {
+ svg {
+ transform: rotate(0) #{'/*rtl:rotate(180deg)*/'};
+ }
+ }
+
+ // _date-picker.scss#L351-L360 in `v10.6.0` tree, coping with the CSS class that latest Flatpickr has
+ .#{$prefix}--date-picker__day.flatpickr-disabled,
+ .flatpickr-day.flatpickr-disabled {
+ cursor: not-allowed;
+ opacity: 0.5;
+ color: $ui-05;
+
+ &:hover {
+ background: transparent;
+ }
+ }
+
+ // _date-picker.scss#L455-L468 in `v10.6.0` tree, coping with the CSS class that latest Flatpickr has
+ .flatpickr-next-month.flatpickr-disabled,
+ .flatpickr-prev-month.flatpickr-disabled {
+ svg {
+ fill: $ui-05;
+ opacity: 0.5;
+ cursor: not-allowed;
+ }
+
+ &:hover {
+ svg {
+ fill: $ui-05;
+ }
+ }
+ }
+}
+
+:host(#{$prefix}-date-picker-input),
+:host(#{$prefix}-date-picker-input-skeleton) {
+ @extend .#{$prefix}--date-picker-container;
+
+ outline: none;
+}
+
+:host(#{$prefix}-date-picker-input[color-scheme='light'])
+ .#{$prefix}--date-picker__input {
+ background: $field-02;
+}
+
+:host(#{$prefix}-date-picker-input[kind='simple']),
+:host(#{$prefix}-date-picker-input-skeleton[kind='simple']) {
+ .#{$prefix}--date-picker__input {
+ width: rem(120px);
+ }
+}
+
+:host(#{$prefix}-date-picker-input[kind='simple'][size-horizontal='short']),
+:host(#{$prefix}-date-picker-input-skeleton[kind='simple'][size-horizontal='short']) {
+ .#{$prefix}--date-picker__input {
+ width: rem(90px);
+ }
+}
+
+:host(#{$prefix}-date-picker-input[kind='single']),
+:host(#{$prefix}-date-picker-input-skeleton[kind='single']) {
+ max-width: rem(288px);
+
+ .#{$prefix}--date-picker__input {
+ width: rem(288px);
+ }
+}
+
+:host(#{$prefix}-date-picker-input[kind='from']),
+:host(#{$prefix}-date-picker-input-skeleton[kind='from']) {
+ margin-right: rem(1px);
+}
+
+:host(#{$prefix}-date-picker-input[kind='from']),
+:host(#{$prefix}-date-picker-input[kind='to']),
+:host(#{$prefix}-date-picker-input-skeleton[kind='from']),
+:host(#{$prefix}-date-picker-input-skeleton[kind='to']) {
+ width: rem(143.5px);
+
+ .#{$prefix}--date-picker__input {
+ width: rem(143.5px);
+ }
+}
+
+:host(#{$prefix}-date-picker-input) ::slotted(.#{$prefix}--date-picker__icon) {
+ position: absolute;
+ right: 1rem;
+ fill: $icon-01;
+ cursor: pointer;
+ z-index: 1;
+}
+
+:host(#{$prefix}-date-picker-input-skeleton) {
+ display: inline-block;
+
+ .#{$prefix}--label {
+ @include skeleton;
+
+ width: rem(75px);
+ height: rem(14px);
+ }
+}
diff --git a/packages/carbon-web-components/src/components/date-picker/date-picker.ts b/packages/carbon-web-components/src/components/date-picker/date-picker.ts
new file mode 100644
index 00000000000..8495b75cdc8
--- /dev/null
+++ b/packages/carbon-web-components/src/components/date-picker/date-picker.ts
@@ -0,0 +1,594 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019, 2022
+ *
+ * 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 { html, property, query, customElement, LitElement } from 'lit-element';
+import flatpickr from 'flatpickr';
+import { Instance as FlatpickrInstance } from 'flatpickr/dist/types/instance';
+import { Locale as FlatpickrLocale } from 'flatpickr/dist/types/locale';
+import {
+ Options as FlatpickrOptions,
+ Plugin as FlatpickrPlugin,
+} from 'flatpickr/dist/types/options';
+import settings from 'carbon-components/es/globals/js/settings';
+import FormMixin from '../../globals/mixins/form';
+import HostListenerMixin from '../../globals/mixins/host-listener';
+import HostListener from '../../globals/decorators/host-listener';
+import { getISODateString, parseISODateString } from './iso-date';
+import BXDatePickerInput from './date-picker-input';
+import appendToPlugin from './append-to-plugin';
+import cssClassPlugin from './css-class-plugin';
+import fixEventsPlugin from './fix-events-plugin';
+import focusPlugin from './focus-plugin';
+import iconPlugin from './icon-plugin';
+import monthSelectPlugin from './month-select-plugin';
+import rangePlugin from './range-plugin';
+import shadowDOMEventPlugin from './shadow-dom-events-plugin';
+import stateHandshakePlugin from './state-handshake-plugin';
+import styles from './date-picker.scss';
+
+const { prefix } = settings;
+
+/**
+ * Date picker modes.
+ */
+enum DATE_PICKER_MODE {
+ /**
+ * Simple mode, without calendar dropdown.
+ */
+ SIMPLE = 'simple',
+
+ /**
+ * Single date mode.
+ */
+ SINGLE = 'single',
+
+ /**
+ * Range mode.
+ */
+ RANGE = 'range',
+}
+
+/**
+ * Date picker.
+ *
+ * @element bx-date-picker
+ * @fires bx-date-picker-changed - The custom event fired on this element when Flatpickr updates its value.
+ */
+@customElement(`${prefix}-date-picker`)
+class BXDatePicker extends HostListenerMixin(FormMixin(LitElement)) {
+ /**
+ * The slotted ``.
+ */
+ private _dateInteractNode: BXDatePickerInput | null = null;
+
+ /**
+ * The element to put calendar dropdown in.
+ */
+ @query('#floating-menu-container')
+ private _floatingMenuContainerNode!: HTMLDivElement;
+
+ /**
+ * The internal placeholder for the `value` property.
+ */
+ private _value!: string;
+
+ /**
+ * @returns The effective date picker mode, determined by the child ``.
+ */
+ private get _mode() {
+ const { selectorInputFrom, selectorInputTo } = this
+ .constructor as typeof BXDatePicker;
+ if (this.querySelector(selectorInputTo)) {
+ return DATE_PICKER_MODE.RANGE;
+ }
+ if (this.querySelector(selectorInputFrom)) {
+ return DATE_PICKER_MODE.SINGLE;
+ }
+ return DATE_PICKER_MODE.SIMPLE;
+ }
+
+ /**
+ * @returns The Flatpickr plugins to use.
+ */
+ private get _datePickerPlugins(): FlatpickrPlugin[] {
+ const {
+ classCalendarContainer,
+ classMonth,
+ classWeekdays,
+ classDays,
+ classWeekday,
+ classDay,
+ classNoBorder,
+ selectorInputFrom,
+ selectorInputTo,
+ _selectorFlatpickrMonthYearContainer: selectorFlatpickrMonthYearContainer,
+ _selectorFlatpickrYearContainer: selectorFlatpickrYearContainer,
+ _selectorFlatpickrCurrentMonth: selectorFlatpickrCurrentMonth,
+ _selectorFlatpickrMonth: selectorFlatpickrMonth,
+ _selectorFlatpickrWeekdays: selectorFlatpickrWeekdays,
+ _selectorFlatpickrDays: selectorFlatpickrDays,
+ _selectorFlatpickrWeekday: selectorFlatpickrWeekday,
+ _selectorFlatpickrDay: selectorFlatpickrDay,
+ _classFlatpickrCurrentMonth: classFlatpickrCurrentMonth,
+ _classFlatpickrToday: classFlatpickrToday,
+ } = this.constructor as typeof BXDatePicker;
+ const {
+ _floatingMenuContainerNode: floatingMenuContainerNode,
+ _mode: mode,
+ } = this;
+ const inputFrom = this.querySelector(selectorInputFrom);
+ const inputTo = this.querySelector(selectorInputTo);
+ const plugins = [
+ appendToPlugin({ appendTo: floatingMenuContainerNode }),
+ cssClassPlugin({
+ classCalendarContainer,
+ classMonth,
+ classWeekdays,
+ classDays,
+ classWeekday,
+ classDay,
+ classNoBorder,
+ selectorFlatpickrMonth,
+ selectorFlatpickrWeekdays,
+ selectorFlatpickrDays,
+ selectorFlatpickrWeekday,
+ selectorFlatpickrDay,
+ classFlatpickrToday,
+ }),
+ fixEventsPlugin({
+ inputFrom: inputFrom as BXDatePickerInput,
+ inputTo: inputTo as BXDatePickerInput,
+ }),
+ focusPlugin({
+ inputFrom: inputFrom as BXDatePickerInput,
+ inputTo: inputTo as BXDatePickerInput,
+ }),
+ iconPlugin(),
+ monthSelectPlugin({
+ selectorFlatpickrMonthYearContainer,
+ selectorFlatpickrYearContainer,
+ selectorFlatpickrCurrentMonth,
+ classFlatpickrCurrentMonth,
+ }),
+ shadowDOMEventPlugin(),
+ stateHandshakePlugin(this),
+ ];
+ if (mode === DATE_PICKER_MODE.RANGE) {
+ // Flatpickr runs event handlers of last registered plugins first.
+ // Ensures `onValueUpdate` of `rangePlugin` runs first
+ // given Flatpickr puts `01/01/1970 to 01/02/1970` to from date
+ // where `rangePlugin` overrides it to separate them to from/to dates.
+ // We want to ensure our handler of `onValueUpdate` (notably one in ``)
+ // gets the `` to communicate values/events with Flatpickr,
+ // but want to use ``.
+ */
+ private _handleSlotChange({ target }: Event) {
+ const { _dateInteractNode: oldDateInteractNode } = this;
+ const dateInteractNode = (target as HTMLSlotElement)
+ .assignedNodes()
+ .find(
+ (node) =>
+ node.nodeType === Node.ELEMENT_NODE &&
+ (node as HTMLElement).matches(
+ (this.constructor as typeof BXDatePicker).selectorInputFrom
+ )
+ );
+ if (oldDateInteractNode !== dateInteractNode) {
+ this._dateInteractNode = dateInteractNode as BXDatePickerInput;
+ this._instantiateDatePicker();
+ }
+ }
+
+ /**
+ * Fires a custom event to notify an error in Flatpickr.
+ */
+ private _handleFlatpickrError = (error: Error) => {
+ this.dispatchEvent(
+ new CustomEvent(
+ (this.constructor as typeof BXDatePicker).eventFlatpickrError,
+ {
+ bubbles: true,
+ cancelable: false,
+ composed: true,
+ detail: {
+ error,
+ },
+ }
+ )
+ );
+ };
+
+ /**
+ * Instantiates Flatpickr.
+ *
+ * @returns The Flatpickr instance.
+ */
+ private _instantiateDatePicker() {
+ this._releaseDatePicker();
+ const { _dateInteractNode: dateInteractNode } = this;
+ // `this._dateInteractNode` won't be there unless there is a slotted ``,
+ // which means Flatpickr will never be instantiated in "simple" mode.
+ if (dateInteractNode && dateInteractNode.input) {
+ this.calendar = flatpickr(
+ dateInteractNode as any,
+ this._datePickerOptions
+ );
+ }
+ return this.calendar;
+ }
+
+ /**
+ * Releases Flatpickr instances.
+ */
+ private _releaseDatePicker() {
+ if (this.calendar) {
+ this.calendar.destroy();
+ this.calendar = null;
+ }
+ return this.calendar;
+ }
+
+ /**
+ * The Flatpickr instance.
+ */
+ calendar: FlatpickrInstance | null = null;
+
+ /**
+ * The date format to let Flatpickr use.
+ */
+ @property({ attribute: 'date-format' })
+ dateFormat!: string;
+
+ /**
+ * Controls the disabled state of the input
+ */
+ @property({ type: Boolean, reflect: true })
+ disabled = false;
+
+ /**
+ * The localization data.
+ */
+ @property({ attribute: false })
+ locale!: FlatpickrLocale;
+
+ /**
+ * The date range that a user can pick in calendar dropdown.
+ */
+ @property({ attribute: 'enabled-range' })
+ enabledRange!: string;
+
+ /**
+ * Name for the input in the `FormData`
+ */
+ @property()
+ name = '';
+
+ /**
+ * `true` if the date picker should be open.
+ */
+ @property({ type: Boolean, reflect: true })
+ open = false;
+
+ /**
+ * The date(s) in ISO8601 format (date portion only), for range mode, '/' is used for separate start/end dates.
+ */
+ @property()
+ get value() {
+ return this._value;
+ }
+
+ set value(value: string) {
+ const { _value: oldValue } = this;
+ this._value = value;
+ this.requestUpdate('value', oldValue);
+ }
+
+ connectedCallback() {
+ super.connectedCallback();
+ this._instantiateDatePicker();
+ }
+
+ disconnectedCallback() {
+ this._releaseDatePicker();
+ super.disconnectedCallback();
+ }
+
+ updated(changedProperties) {
+ const { calendar, disabled, open } = this;
+ const { selectorInputFrom, selectorInputTo } = this
+ .constructor as typeof BXDatePicker;
+ const inputFrom = this.querySelector(
+ selectorInputFrom
+ ) as BXDatePickerInput;
+ const inputTo = this.querySelector(selectorInputTo) as BXDatePickerInput;
+ if (calendar && changedProperties.has('dateFormat')) {
+ const { dateFormat } = this;
+ calendar.set({ dateFormat });
+ }
+ if (changedProperties.has('enabledRange')) {
+ const { enabledRange } = this;
+ const dates = enabledRange
+ .split('/')
+ .map((item) => (!item ? undefined : parseISODateString(item))); // Allows empty start/end
+ if (dates.some((item) => Boolean(item && isNaN(Number(item))))) {
+ // Allows empty start/end
+ throw new Error(
+ `Wrong date format found in \`enabledRange\` property: ${enabledRange}`
+ );
+ }
+ const [minDate, maxDate] = dates;
+ if (minDate && maxDate && minDate > maxDate) {
+ throw new Error(
+ `In \`enabledRange\` property, the end date shouldn't be smaller than the start date. You have: ${enabledRange}`
+ );
+ }
+ if (calendar) {
+ calendar.set({ minDate, maxDate });
+ }
+ }
+ if (changedProperties.has('open') && calendar) {
+ if (open) {
+ calendar.open();
+ } else {
+ calendar.close();
+ }
+ }
+ if (changedProperties.has('disabled')) {
+ [inputFrom, inputTo].forEach((input) => {
+ if (input) {
+ input.disabled = disabled;
+ }
+ });
+ }
+ if (changedProperties.has('value')) {
+ const { value } = this;
+ const dates = value
+ .split('/')
+ .filter(Boolean)
+ .map((item) => parseISODateString(item));
+ if (dates.some((item) => isNaN(Number(item)))) {
+ throw new Error(
+ `Wrong date format found in \`value\` property: ${value}`
+ );
+ }
+ const [startDate, endDate] = dates;
+ if (startDate && endDate && startDate > endDate) {
+ throw new Error(
+ `In \`value\` property, the end date shouldn't be smaller than the start date. You have: ${value}`
+ );
+ }
+ if (calendar) {
+ calendar.setDate(dates);
+ [inputFrom, inputTo].forEach((input, i) => {
+ if (input) {
+ input.value = !dates[i]
+ ? ''
+ : calendar.formatDate(
+ new Date(dates[i]),
+ calendar.config.dateFormat
+ );
+ }
+ });
+ }
+ }
+ }
+
+ render() {
+ const { _handleSlotChange: handleSlotChange } = this;
+ return html`
+ ` for month picker.
+ */
+export interface DatePickerMonthSelectPluginConfig {
+ /**
+ * `true` to use shorthand month.
+ */
+ shorthand?: boolean;
+
+ /**
+ * The CSS selector for the container of month/year selection UI.
+ */
+ selectorFlatpickrMonthYearContainer: string;
+
+ /**
+ * The CSS selector for the container of year selection UI.
+ */
+ selectorFlatpickrYearContainer: string;
+
+ /**
+ * The CSS selector for the text-based month selection UI.
+ */
+ selectorFlatpickrCurrentMonth: string;
+
+ /**
+ * The CSS class for the text-based month selection UI.
+ */
+ classFlatpickrCurrentMonth: string;
+}
+
+/**
+ * @param config Plugin configuration.
+ * @returns A Flatpickr plugin to use text instead of `` for month picker.
+ */
+export default (config: DatePickerMonthSelectPluginConfig): Plugin =>
+ (fp: FlatpickrInstance) => {
+ /**
+ * Replaces `` for month with text content.
+ */
+ const setupElements = () => {
+ const {
+ monthElements,
+ yearElements,
+ currentMonth,
+ l10n,
+ _createElement: createElement,
+ } = fp;
+ if (!monthElements) {
+ return;
+ }
+ const {
+ shorthand,
+ selectorFlatpickrMonthYearContainer,
+ selectorFlatpickrYearContainer,
+ classFlatpickrCurrentMonth,
+ } = config;
+ monthElements.forEach((elem) => {
+ if (!elem.parentNode) return;
+ elem.parentNode.removeChild(elem);
+ });
+ monthElements.splice(
+ 0,
+ monthElements.length,
+ ...monthElements.map(() => {
+ const monthElement = createElement(
+ 'span',
+ classFlatpickrCurrentMonth
+ );
+ monthElement.textContent = monthToStr(
+ currentMonth,
+ shorthand === true,
+ l10n
+ );
+ const monthYearContainer = yearElements[0].closest(
+ selectorFlatpickrMonthYearContainer
+ );
+ if (monthYearContainer) {
+ monthYearContainer.insertBefore(
+ monthElement,
+ yearElements[0].closest(selectorFlatpickrYearContainer)
+ );
+ }
+ return monthElement;
+ })
+ );
+ };
+
+ /**
+ * Updates the text-based month UI with the latest selected date.
+ */
+ const updateCurrentMonth = () => {
+ const { yearElements, currentMonth, l10n } = fp;
+ const {
+ shorthand,
+ selectorFlatpickrMonthYearContainer,
+ selectorFlatpickrCurrentMonth,
+ } = config;
+ const monthStr = monthToStr(currentMonth, shorthand === true, l10n);
+ yearElements.forEach((elem) => {
+ const currentMonthContainer = elem.closest(
+ selectorFlatpickrMonthYearContainer
+ );
+ if (currentMonthContainer) {
+ forEach(
+ currentMonthContainer.querySelectorAll(
+ selectorFlatpickrCurrentMonth
+ ),
+ (monthElement) => {
+ monthElement.textContent = monthStr;
+ }
+ );
+ }
+ });
+ };
+
+ /**
+ * Registers this Flatpickr plugin.
+ */
+ const register = () => {
+ fp.loadedPlugins.push('carbonFlatpickrMonthSelectPlugin');
+ };
+
+ return {
+ onMonthChange: updateCurrentMonth,
+ onValueUpdate: updateCurrentMonth,
+ onOpen: updateCurrentMonth,
+ onReady: [setupElements, updateCurrentMonth, register],
+ };
+ };
diff --git a/packages/carbon-web-components/src/components/date-picker/range-plugin.ts b/packages/carbon-web-components/src/components/date-picker/range-plugin.ts
new file mode 100644
index 00000000000..c0f95a44034
--- /dev/null
+++ b/packages/carbon-web-components/src/components/date-picker/range-plugin.ts
@@ -0,0 +1,62 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019, 2022
+ *
+ * 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 rangePlugin, { Config } from 'flatpickr/dist/plugins/rangePlugin';
+import { Instance as FlatpickrInstance } from 'flatpickr/dist/types/instance';
+import { Plugin } from 'flatpickr/dist/types/options';
+
+/**
+ * @param config Plugin configuration.
+ * @returns
+ * An extension of Flatpickr `rangePlugin` that does the following:
+ *
+ * * Better ensures the calendar dropdown is always aligned to the ``.
+ */
+export default (datePicker: BXDatePicker): Plugin =>
+ (fp: FlatpickrInstance) => {
+ /**
+ * Sets open state.
+ */
+ const setOpen = () => {
+ datePicker.open = true;
+ };
+
+ /**
+ * Sets closed state.
+ */
+ const setClosed = () => {
+ datePicker.open = false;
+ };
+
+ /**
+ * Propagates Flatpickr's `onChange` event to ``.
+ *
+ * @param selectedDates The latest selected dates.
+ */
+ const handleChange = (selectedDates: Date[]) => {
+ const { eventChange } = datePicker.constructor as typeof BXDatePicker;
+ datePicker.dispatchEvent(
+ new CustomEvent(eventChange, {
+ bubbles: true,
+ cancelable: true,
+ composed: true,
+ detail: {
+ selectedDates,
+ },
+ })
+ );
+ };
+
+ /**
+ * Registers this Flatpickr plugin.
+ *
+ * @param calendar The Flatpickr instance.
+ */
+ const register = (_selectedDates, _value, calendar: FlatpickrInstance) => {
+ datePicker.calendar = calendar;
+ fp.loadedPlugins.push('carbonFlatpickrStateHandshakePlugin');
+ };
+
+ return {
+ onOpen: setOpen,
+ onClose: setClosed,
+ onChange: handleChange,
+ onReady: [register],
+ };
+ };
diff --git a/packages/carbon-web-components/src/components/dropdown/defs.ts b/packages/carbon-web-components/src/components/dropdown/defs.ts
new file mode 100644
index 00000000000..16df5ee6da1
--- /dev/null
+++ b/packages/carbon-web-components/src/components/dropdown/defs.ts
@@ -0,0 +1,80 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2020
+ *
+ * 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 { FORM_ELEMENT_COLOR_SCHEME as DROPDOWN_COLOR_SCHEME } from '../../globals/shared-enums';
+
+/**
+ * Navigation direction, associated with key symbols.
+ */
+export const NAVIGATION_DIRECTION = {
+ Up: -1,
+ ArrowUp: -1,
+ Down: 1,
+ ArrowDown: 1,
+};
+
+/**
+ * The keyboard action categories for dropdown.
+ */
+export enum DROPDOWN_KEYBOARD_ACTION {
+ /**
+ * Not doing any action.
+ */
+ NONE = 'none',
+
+ /**
+ * Keyboard action to close menu.
+ */
+ CLOSING = 'closing',
+
+ /**
+ * Keyboard action to navigate back/forward.
+ */
+ NAVIGATING = 'navigating',
+
+ /**
+ * Keyboard action to open/close menu on the trigger button or select/deselect a menu item.
+ */
+ TRIGGERING = 'triggering',
+}
+
+/**
+ * Dropdown size.
+ */
+export enum DROPDOWN_SIZE {
+ /**
+ * Regular size.
+ */
+ REGULAR = '',
+
+ /**
+ * Small size.
+ */
+ SMALL = 'sm',
+
+ /**
+ * Extra large size.
+ */
+ EXTRA_LARGE = 'xl',
+}
+
+/**
+ * Dropdown types.
+ */
+export enum DROPDOWN_TYPE {
+ /**
+ * Regular type.
+ */
+ REGULAR = '',
+
+ /**
+ * Inline type.
+ */
+ INLINE = 'inline',
+}
diff --git a/packages/carbon-web-components/src/components/dropdown/dropdown-item.ts b/packages/carbon-web-components/src/components/dropdown/dropdown-item.ts
new file mode 100644
index 00000000000..fd85f2bdf6a
--- /dev/null
+++ b/packages/carbon-web-components/src/components/dropdown/dropdown-item.ts
@@ -0,0 +1,79 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019, 2022
+ *
+ * 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 settings from 'carbon-components/es/globals/js/settings';
+import { html, property, customElement, LitElement } from 'lit-element';
+import Checkmark16 from '@carbon/icons/lib/checkmark/16';
+import { DROPDOWN_SIZE } from './dropdown';
+import styles from './dropdown.scss';
+
+const { prefix } = settings;
+
+/**
+ * Dropdown item.
+ *
+ * @element bx-dropdown-item
+ * @csspart selected-icon The selected icon.
+ */
+@customElement(`${prefix}-dropdown-item`)
+class BXDropdownItem extends LitElement {
+ /**
+ * `true` if this dropdown item should be disabled.
+ */
+ @property({ type: Boolean, reflect: true })
+ disabled = false;
+
+ /**
+ * `true` if this dropdown item should be highlighted.
+ * If `true`, parent `` selects/deselects this dropdown item upon keyboard interaction.
+ *
+ * @private
+ */
+ @property({ type: Boolean, reflect: true })
+ highlighted = false;
+
+ /**
+ * `true` if this dropdown item should be selected.
+ *
+ * @private
+ */
+ @property({ type: Boolean, reflect: true })
+ selected = false;
+
+ /**
+ * Dropdown size.
+ */
+ @property({ reflect: true })
+ size = DROPDOWN_SIZE.REGULAR;
+
+ /**
+ * The `value` attribute that is set to the parent `` when this dropdown item is selected.
+ */
+ @property()
+ value = '';
+
+ render() {
+ const { selected } = this;
+ return html`
+
+ `;
+ }
+
+ static styles = styles;
+}
+
+export default BXDropdownItem;
diff --git a/packages/carbon-web-components/src/components/dropdown/dropdown-skeleton.ts b/packages/carbon-web-components/src/components/dropdown/dropdown-skeleton.ts
new file mode 100644
index 00000000000..bdac20c0fc2
--- /dev/null
+++ b/packages/carbon-web-components/src/components/dropdown/dropdown-skeleton.ts
@@ -0,0 +1,35 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2019, 2022
+ *
+ * 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 { html, customElement, LitElement } from 'lit-element';
+import settings from 'carbon-components/es/globals/js/settings';
+import styles from './dropdown.scss';
+
+const { prefix } = settings;
+
+/**
+ * Skeleton version of dropdown.
+ */
+@customElement(`${prefix}-dropdown-skeleton`)
+class BXDropdownSkeleton extends LitElement {
+ render() {
+ return html`
+
+ `;
+ }
+
+ static styles = styles;
+}
+
+export default BXDropdownSkeleton;
diff --git a/packages/carbon-web-components/src/components/dropdown/dropdown-story.mdx b/packages/carbon-web-components/src/components/dropdown/dropdown-story.mdx
new file mode 100644
index 00000000000..e17141ab127
--- /dev/null
+++ b/packages/carbon-web-components/src/components/dropdown/dropdown-story.mdx
@@ -0,0 +1,73 @@
+import { Props, Description } from '@storybook/addon-docs/blocks';
+import { cdnJs, cdnCss } from '../../globals/internal/storybook-cdn';
+
+# Dropdown
+
+> ๐ก Check our
+> [CodeSandbox](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/basic/components/dropdown)
+> example implementation.
+
+[](https://codesandbox.io/s/github/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/carbon-web-components/examples/codesandbox/basic/components/dropdown)
+
+Dropdown presents a list of options that can be used to filter or sort existing
+content.
+
+## Getting started
+
+Here's a quick example to get you started.
+
+### JS (via import)
+
+```javascript
+import '@carbon/web-components/es/components/dropdown/index.js';
+```
+
+
+ Foo
+ Bar
+ Baz
+
+```
+
+## Selection
+
+When user attempts to select a dropdown item, `bx-dropdown-beingselected` event
+fires on ``, which has the following properties in the event
+details:
+
+| Property | Description |
+| -------- | ---------------------------------------- |
+| `item` | The `` being selected. |
+
+`bx-dropdown-beingselected` bubbles and is cancelable. Canceling this event
+means canceling change in selection.
+
+## Skeleton
+
+For the skeleton variation, utilize ``.
+
+```html
+` attributes, properties and events
+
+Note: For `boolean` attributes, `true` means simply setting the attribute (e.g.
+``) and `false` means not setting the attribute (e.g.
+`` without `open` attribute).
+
+` attributes and properties
+
+Note: For `boolean` attributes, `true` means simply setting the attribute (e.g.
+``) and `false` means not setting the attribute (e.g.
+`` without `disabled` attribute).
+
+
+ Option 1
+ Option 2
+ Option 3
+ Option 4
+ Option 5
+
+ `;
+};
+
+Default.storyName = 'Default';
+
+Default.parameters = {
+ knobs: {
+ 'bx-dropdown': () => ({
+ open: boolean('Open (open)', false),
+ colorScheme: select('Color scheme (color-scheme)', colorSchemes, null),
+ disabled: boolean('Disabled (disabled)', false),
+ helperText: textNullable(
+ 'Helper text (helper-text)',
+ 'Optional helper text'
+ ),
+ labelText: textNullable('Label text (label-text)', 'Dropdown title'),
+ size: select('Dropdown size (size)', sizes, null),
+ type: select('Dropdown type (type)', types, null),
+ value: textNullable('The value of the selected item (value)', ''),
+ triggerContent: textNullable(
+ 'The default content of the trigger button (trigger-content)',
+ 'Select an item'
+ ),
+ disableSelection: boolean(
+ 'Disable user-initiated selection change (Call event.preventDefault() in bx-dropdown-beingselected event)',
+ false
+ ),
+ disableToggle: boolean(
+ 'Disable user-initiated toggle of open state (Call event.preventDefault() in bx-dropdown-beingtoggled event)',
+ false
+ ),
+ onBeforeSelect: action('bx-dropdown-beingselected'),
+ onBeforeToggle: action('bx-dropdown-beingtoggled'),
+ onSelect: action('bx-dropdown-selected'),
+ onToggle: action('bx-dropdown-toggled'),
+ }),
+ },
+};
+
+export const skeleton = () =>
+ html`
+
+
+
+
+
+