feat(FilterPanel): new component with label and checkbox (carbon-desi…

…gn-system#4563)

* feat: new filter panel component

* fix: stories and mdx

* fix: remove 'title' usage from filter panel label

* fix: make text req'd

* fix: standardize label and title

* fix: new storybook format

* fix: update storybook documentation

examples/carbon-for-ibm-products/FilterPanel/gallery.config.json

@@ -0,0 +1,12 @@
+{
+  "label": "Filter-Panel",
+  "package-config": {
+    "flags": {
+      "component": {
+        "FilterPanel": true
+      }
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

examples/carbon-for-ibm-products/FilterPanel/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "FilterPanel-component-example",
+  "note": "Run `update-gallery-config to generate."
+}

examples/carbon-for-ibm-products/FilterPanel/src/Example/Example.jsx

@@ -0,0 +1,19 @@
+// cspell:words grafana
+
+import React from 'react';
+
+// ----------------------------------------------------
+// This is an example showing use of the
+// AboutModal component
+// from the @carbon/ibm-products component library.
+// ----------------------------------------------------
+
+import { FilterPanel } from '@carbon/ibm-products';
+
+import './_example.scss';
+
+export const Example = () => {
+  return <FilterPanel />;
+};
+
+export default Example;

examples/carbon-for-ibm-products/FilterPanel/src/Example/_example.scss

@@ -0,0 +1,3 @@
+@use '@carbon/react/scss/spacing' as *;
+
+/* example SCSS */

packages/ibm-products-styles/src/components/FilterPanel/_carbon-imports.scss

@@ -0,0 +1,9 @@
+//
+// Copyright IBM Corp. 2024, 2024
+//
+// 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 any Carbon component styles used from FilterPanel in this file.
+// FilterPanel uses the following Carbon components:

packages/ibm-products-styles/src/components/FilterPanel/_filter-panel-checkbox.scss

@@ -0,0 +1,32 @@
+//
+// Copyright IBM Corp. 2024, 2024
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+/* stylelint-disable max-nesting-depth */
+
+// Standard imports.
+@use '../../global/styles/project-settings' as c4p-settings;
+@use '../../global/styles/mixins';
+
+@use '@carbon/styles/scss/type';
+
+// The block part of our conventional BEM class names (blockClass__E--M).
+$block-class: #{c4p-settings.$pkg-prefix}--filter-panel-checkbox;
+$label: #{c4p-settings.$pkg-prefix}--filter-panel-label;
+
+// Set Carbon's Checkbox label to 100% the width of its container.
+.#{$block-class} .#{c4p-settings.$carbon-prefix}--checkbox-label,
+.#{$block-class} .#{c4p-settings.$carbon-prefix}--checkbox-label-text {
+  width: 100%;
+}
+
+.#{$block-class} .#{$label}__text {
+  @include type.type-style('body-compact-01');
+}
+
+.#{$block-class} .#{$label}__count {
+  @include type.type-style('label-01');
+}

packages/ibm-products-styles/src/components/FilterPanel/_filter-panel-label.scss

@@ -0,0 +1,47 @@
+//
+// Copyright IBM Corp. 2024, 2024
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+/* stylelint-disable max-nesting-depth */
+
+// Standard imports.
+@use '../../global/styles/project-settings' as c4p-settings;
+@use '../../global/styles/mixins';
+
+@use '@carbon/styles/scss/spacing' as *;
+@use '@carbon/styles/scss/theme' as *;
+@use '@carbon/styles/scss/type';
+
+// FilterPanel uses the following Carbon for IBM Products components:
+// TODO: @use(s) of IBM Products component styles used by FilterPanel
+
+// The block part of our conventional BEM class names (blockClass__E--M).
+$block-class: #{c4p-settings.$pkg-prefix}--filter-panel-label;
+
+.#{$block-class} {
+  display: flex;
+  align-items: center;
+}
+
+.#{$block-class}__text {
+  overflow: hidden;
+  flex: 1 1;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.#{$block-class}__count {
+  margin-left: $spacing-04;
+  color: $text-secondary;
+}
+
+// Surround the value with parentheses.
+.#{$block-class}__count::before {
+  content: '(';
+}
+.#{$block-class}__count::after {
+  content: ')';
+}

packages/ibm-products-styles/src/components/FilterPanel/_filter-panel.scss

@@ -0,0 +1,29 @@
+//
+// Copyright IBM Corp. 2024, 2024
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+/* stylelint-disable max-nesting-depth */
+
+// Standard imports.
+@use '../../global/styles/project-settings' as c4p-settings;
+@use '../../global/styles/mixins';
+
+@use '@carbon/styles/scss/spacing' as *;
+@use '@carbon/styles/scss/theme' as *;
+@use '@carbon/styles/scss/type';
+
+// FilterPanel uses the following Carbon for IBM Products components:
+// TODO: @use(s) of IBM Products component styles used by FilterPanel
+
+// The block part of our conventional BEM class names (blockClass__E--M).
+$block-class: #{c4p-settings.$pkg-prefix}--filter-panel;
+
+.#{$block-class}__title {
+  @include type.type-style('body-compact-01');
+
+  margin-top: $spacing-04;
+  margin-bottom: $spacing-04;
+}

packages/ibm-products-styles/src/components/FilterPanel/_index-with-carbon.scss

@@ -0,0 +1,11 @@
+//
+// Copyright IBM Corp. 2024, 2024
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@use './carbon-imports';
+@use './filter-panel';
+@use './filter-panel-checkbox';
+@use './filter-panel-label';

packages/ibm-products-styles/src/components/FilterPanel/_index.scss

@@ -0,0 +1,10 @@
+//
+// Copyright IBM Corp. 2024, 2024
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@use './filter-panel';
+@use './filter-panel-checkbox';
+@use './filter-panel-label';

packages/ibm-products-styles/src/components/_index-with-carbon.scss

@@ -71,3 +71,4 @@
 @use './StringFormatter/index-with-carbon' as *;
 @use './UserAvatar/index-with-carbon' as *;
 @use './StatusIndicator/index-with-carbon' as *;
+@use './FilterPanel/index-with-carbon' as *;

packages/ibm-products-styles/src/components/_index.scss

@@ -79,3 +79,4 @@
 @use './StringFormatter';
 @use './UserAvatar';
 @use './StatusIndicator';
+@use './FilterPanel';

packages/ibm-products/src/components/FilterPanel/FilterPanel.js

@@ -0,0 +1,59 @@
+/**
+ * Copyright IBM Corp. 2024, 2024
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+
+import PropTypes from 'prop-types';
+import cx from 'classnames';
+
+import { getDevtoolsProps } from '../../global/js/utils/devtools';
+import { pkg } from '../../settings';
+
+// The block part of our conventional BEM class names (blockClass__E--M).
+const blockClass = `${pkg.prefix}--filter-panel`;
+const componentName = 'FilterPanel';
+
+/**
+ * The container for filter panel subcomponents.
+ */
+export let FilterPanel = React.forwardRef(
+  ({ children, className, title, ...rest }, ref) => {
+    return (
+      <section
+        {...rest}
+        className={cx(blockClass, className)}
+        ref={ref}
+        {...getDevtoolsProps(componentName)}
+      >
+        {title && <h1 className={`${blockClass}__title`}>{title}</h1>}
+        {children}
+      </section>
+    );
+  }
+);
+
+// Return a placeholder if not released and not enabled by feature flag
+FilterPanel = pkg.checkComponentEnabled(FilterPanel, componentName);
+
+FilterPanel.displayName = componentName;
+
+FilterPanel.propTypes = {
+  /**
+   * Provide the contents of the FilterPanel.
+   */
+  children: PropTypes.node,
+
+  /**
+   * Provide an optional class to be applied to the containing node.
+   */
+  className: PropTypes.string,
+
+  /**
+   * Title text for the filter panel.
+   */
+  title: PropTypes.node,
+};

packages/ibm-products/src/components/FilterPanel/FilterPanel.mdx

@@ -0,0 +1,27 @@
+import { Story, ArgsTable, Source, Canvas } from '@storybook/addon-docs';
+import { CodesandboxLink } from '../../global/js/utils/story-helper';
+import { FilterPanel } from '.';
+import * as FilterPanelStories from './FilterPanel.stories';
+
+# FilterPanel
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Example usage](#example-usage)
+- [Component API](#component-api)
+
+## Overview
+
+The `FilterPanel` allows for an optional title, and acts as the container for
+its subcomponents.
+
+## Example usage
+
+<Canvas>
+  <Story of={FilterPanelStories.Default} />
+</Canvas>
+
+## Component API
+
+<ArgsTable />

packages/ibm-products/src/components/FilterPanel/FilterPanel.stories.js

@@ -0,0 +1,94 @@
+/**
+ * Copyright IBM Corp. 2024, 2024
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+import { action } from '@storybook/addon-actions';
+
+import uuidv4 from '../../global/js/utils/uuidv4';
+
+import { FilterPanel, FilterPanelCheckbox } from '.';
+import mdx from './FilterPanel.mdx';
+
+import styles from './_storybook-styles.scss';
+
+const storyClass = 'filter-panel-stories';
+
+export default {
+  title: 'IBM Products/Components/Filter panel/Filter Panel',
+  component: FilterPanel,
+  tags: ['autodocs'],
+  parameters: {
+    styles,
+    docs: {
+      page: mdx,
+    },
+  },
+  argTypes: {
+    children: { control: { type: {} } },
+    className: { control: { type: {} } },
+    title: {
+      control: {
+        type: 'select',
+        labels: {
+          0: 'No title',
+          1: 'Plain text',
+          2: 'Using markup',
+        },
+      },
+      mapping: {
+        0: null,
+        1: 'Filter panel title',
+        2: (
+          <>
+            <strong>Filter</strong> <em>panel</em> title
+          </>
+        ),
+      },
+      options: [0, 1, 2],
+    },
+  },
+  args: {
+    title: 1,
+  },
+};
+
+const Template = (args) => {
+  return (
+    <div className={`${storyClass}__viewport`}>
+      <FilterPanel {...args}>
+        <FilterPanelCheckbox
+          count={6}
+          labelText="Filter 1"
+          // "id" and "onChange" are pass-through props to Carbon's Checkbox.
+          id={uuidv4()}
+          onChange={(event, { checked, id }) =>
+            action('FilterPanelCheckbox onChange')(checked, id, event)
+          }
+        />
+        <FilterPanelCheckbox
+          count={10}
+          labelText="Filter 2"
+          id={uuidv4()}
+          onChange={(event, { checked, id }) =>
+            action('FilterPanelCheckbox onChange')(checked, id, event)
+          }
+        />
+        <FilterPanelCheckbox
+          count={'1,500'}
+          labelText="Filter 3: really long filter name"
+          id={uuidv4()}
+          onChange={(event, { checked, id }) =>
+            action('FilterPanelCheckbox onChange')(checked, id, event)
+          }
+        />
+      </FilterPanel>
+    </div>
+  );
+};
+
+export const Default = Template.bind({});
+Default.storyName = 'Filter Panel';