feat: replace slug with decorator ComboBox, MultiSelect, FilterableMultiSelect

packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap

@@ -1250,6 +1250,9 @@ Map {
       "className": Object {
         "type": "string",
       },
+      "decorator": Object {
+        "type": "node",
+      },
       "direction": Object {
         "args": Array [
           Array [
@@ -1360,9 +1363,7 @@ Map {
         ],
         "type": "oneOf",
       },
-      "slug": Object {
-        "type": "node",
-      },
+      "slug": [Function],
       "titleText": Object {
         "type": "node",
       },
@@ -3540,6 +3541,9 @@ Map {
       "compareItems": Object {
         "type": "func",
       },
+      "decorator": Object {
+        "type": "node",
+      },
       "direction": Object {
         "args": Array [
           Array [
@@ -3754,9 +3758,7 @@ Map {
         ],
         "type": "oneOf",
       },
-      "slug": Object {
-        "type": "node",
-      },
+      "slug": [Function],
       "sortItems": Object {
         "type": "func",
       },
@@ -5220,6 +5222,9 @@ Map {
         "compareItems": Object {
           "type": "func",
         },
+        "decorator": Object {
+          "type": "node",
+        },
         "direction": Object {
           "args": Array [
             Array [
@@ -5434,9 +5439,7 @@ Map {
           ],
           "type": "oneOf",
         },
-        "slug": Object {
-          "type": "node",
-        },
+        "slug": [Function],
         "sortItems": Object {
           "type": "func",
         },
@@ -5474,6 +5477,9 @@ Map {
       "compareItems": Object {
         "type": "func",
       },
+      "decorator": Object {
+        "type": "node",
+      },
       "direction": Object {
         "args": Array [
           Array [
@@ -5561,9 +5567,7 @@ Map {
         ],
         "type": "oneOf",
       },
-      "slug": Object {
-        "type": "node",
-      },
+      "slug": [Function],
       "sortItems": Object {
         "type": "func",
       },

packages/react/src/components/ComboBox/ComboBox-test.js

@@ -284,13 +284,25 @@ describe('ComboBox', () => {
   });
 
   it('should respect slug prop', async () => {
+    const spy = jest.spyOn(console, 'warn').mockImplementation(() => {});
     const { container } = render(
       <ComboBox {...mockProps} slug={<AILabel />} />
     );
     await waitForPosition();
     expect(container.firstChild).toHaveClass(
       `${prefix}--list-box__wrapper--slug`
     );
+    spy.mockRestore();
+  });
+
+  it('should respect decorator prop', async () => {
+    const { container } = render(
+      <ComboBox {...mockProps} decorator={<AILabel />} />
+    );
+    await waitForPosition();
+    expect(container.firstChild).toHaveClass(
+      `${prefix}--list-box__wrapper--decorator`
+    );
   });
 
   describe('should display initially selected item found in `initialSelectedItem`', () => {

packages/react/src/components/ComboBox/ComboBox.stories.js

@@ -14,6 +14,7 @@ import Button from '../Button';
 import { AILabel, AILabelContent, AILabelActions } from '../AILabel';
 import { IconButton } from '../IconButton';
 import { View, FolderOpen, Folders } from '@carbon/icons-react';
+import { Tooltip } from '../Tooltip';
 import mdx from './ComboBox.mdx';
 
 const items = [
@@ -197,7 +198,20 @@ export const withAILabel = () => (
       itemToString={(item) => (item ? item.text : '')}
       titleText="ComboBox title"
       helperText="Combobox helper text"
-      slug={aiLabel}
+      decorator={aiLabel}
+    />
+    <ComboBox
+      onChange={() => {}}
+      id="carbon-combobox"
+      items={items}
+      itemToString={(item) => (item ? item.text : '')}
+      titleText="ComboBox title"
+      helperText="Combobox helper text"
+      decorator={
+        <Tooltip>
+          <View />
+        </Tooltip>
+      }
     />
   </div>
 );

packages/react/src/components/ComboBox/ComboBox.tsx

@@ -204,6 +204,11 @@
    */
   className?: string;
 
+  /**
+   * **Experimental**: Provide a `decorator` component to be rendered inside the `ComboBox` component
+   */
+  decorator?: ReactNode;
+
   /**
    * Specify the direction of the combobox dropdown. Can be either top or bottom.
    */
@@ -349,6 +354,7 @@
   size?: ListBoxSize;
 
   /**
+   * @deprecated please use decorator instead.
    * **Experimental**: Provide a `Slug` component to be rendered inside the `ComboBox` component
    */
   slug?: ReactNode;
@@ -388,6 +394,7 @@
       ariaLabel: deprecatedAriaLabel,
       autoAlign = false,
       className: containerClassName,
+      decorator,
       direction = 'bottom',
       disabled = false,
       downshiftActions,
@@ -532,12 +539,12 @@
         typeahead
           ? autocompleteCustomFilter({ item: itemToString(item), inputValue })
           : shouldFilterItem
-            ? shouldFilterItem({
-                item,
-                itemToString,
-                inputValue,
-              })
-            : defaultShouldFilterItem()
+          ? shouldFilterItem({
+              item,
+              itemToString,
+              inputValue,
+            })
+          : defaultShouldFilterItem()
       );
 
     useEffect(() => {
@@ -695,6 +702,7 @@
         [`${prefix}--list-box__wrapper--fluid--invalid`]: isFluid && invalid,
         [`${prefix}--list-box__wrapper--fluid--focus`]: isFluid && isFocused,
         [`${prefix}--list-box__wrapper--slug`]: slug,
+        [`${prefix}--list-box__wrapper--decorator`]: decorator,
       },
     ]);
 
@@ -706,12 +714,20 @@
     // needs to be Capitalized for react to render it correctly
     const ItemToElement = itemToElement;
 
-    // Slug is always size `mini`
-    let normalizedSlug;
-    if (slug && slug['type']?.displayName === 'AILabel') {
-      normalizedSlug = React.cloneElement(slug as React.ReactElement<any>, {
-        size: 'mini',
-      });
+    // AILabel always size `mini`
+    let normalizedDecorator = React.isValidElement(slug ?? decorator)
+      ? slug ?? decorator
+      : null;
+    if (
+      normalizedDecorator &&
+      normalizedDecorator['type']?.displayName === 'AILabel'
+    ) {
+      normalizedDecorator = React.cloneElement(
+        normalizedDecorator as React.ReactElement<any>,
+        {
+          size: 'mini',
+        }
+      );
     }
 
     const {
@@ -1035,7 +1051,15 @@
               translateWithId={translateWithId}
             />
           </div>
-          {normalizedSlug}
+          {slug ? (
+            normalizedDecorator
+          ) : decorator ? (
+            <div className={`${prefix}--list-box__inner-wrapper--decorator`}>
+              {normalizedDecorator}
+            </div>
+          ) : (
+            ''
+          )}
           <ListBox.Menu {...menuProps}>
             {isOpen
               ? filterItems(items, itemToString, inputValue).map(
@@ -1130,6 +1154,11 @@
    */
   className: PropTypes.string,
 
+  /**
+   * **Experimental**: Provide a decorator component to be rendered inside the `ComboBox` component
+   */
+  decorator: PropTypes.node,
+
   /**
    * Specify the direction of the combobox dropdown. Can be either top or bottom.
    */
@@ -1280,10 +1309,10 @@
    */
   size: ListBoxPropTypes.ListBoxSize,
 
-  /**
-   * **Experimental**: Provide a `Slug` component to be rendered inside the `ComboBox` component
-   */
-  slug: PropTypes.node,
+  slug: deprecate(
+    PropTypes.node,
+    'The `slug` prop has been deprecated and will be removed in the next major version. Use the decorator prop instead.'
+  ),
 
   /**
    * Provide text to be used in a `<label>` element that is tied to the

packages/react/src/components/MultiSelect/FilterableMultiSelect.tsx

@@ -131,6 +131,11 @@ export interface FilterableMultiSelectProps<ItemType>
    */
   clearSelectionText?: string;
 
+  /**
+   * **Experimental**: Provide a `decorator` component to be rendered inside the `FilterableMultiSelect` component
+   */
+  decorator?: ReactNode;
+
   /**
    * Specify the direction of the multiselect dropdown.
    */
@@ -283,6 +288,7 @@ export interface FilterableMultiSelectProps<ItemType>
   size?: 'sm' | 'md' | 'lg';
 
   /**
+   * @deprecated please use decorator instead.
    * **Experimental**: Provide a `Slug` component to be rendered inside the `Checkbox` component
    */
   slug?: ReactNode;
@@ -312,14 +318,15 @@ export interface FilterableMultiSelectProps<ItemType>
 }
 
 const FilterableMultiSelect = React.forwardRef(function FilterableMultiSelect<
-  ItemType,
+  ItemType
 >(
   {
     autoAlign = false,
     className: containerClassName,
     clearSelectionDescription = 'Total items selected: ',
     clearSelectionText = 'To clear selection, press Delete or Backspace',
     compareItems = defaultCompareItems,
+    decorator,
     direction = 'bottom',
     disabled = false,
     downshiftProps,
@@ -469,6 +476,7 @@ const FilterableMultiSelect = React.forwardRef(function FilterableMultiSelect<
       [`${prefix}--list-box__wrapper--fluid--invalid`]: isFluid && invalid,
       [`${prefix}--list-box__wrapper--fluid--focus`]: isFluid && isFocused,
       [`${prefix}--list-box__wrapper--slug`]: slug,
+      [`${prefix}--list-box__wrapper--decorator`]: decorator,
       [`${prefix}--autoalign`]: autoAlign,
     }
   );
@@ -677,12 +685,20 @@ const FilterableMultiSelect = React.forwardRef(function FilterableMultiSelect<
     }
   }
 
-  // Slug is always size `mini`
-  let normalizedSlug;
-  if (slug && slug['type']?.displayName === 'AILabel') {
-    normalizedSlug = React.cloneElement(slug as React.ReactElement<any>, {
-      size: 'mini',
-    });
+  // AILabel always size `mini`
+  let normalizedDecorator = React.isValidElement(slug ?? decorator)
+    ? slug ?? decorator
+    : null;
+  if (
+    normalizedDecorator &&
+    normalizedDecorator['type']?.displayName === 'AILabel'
+  ) {
+    normalizedDecorator = React.cloneElement(
+      normalizedDecorator as React.ReactElement<any>,
+      {
+        size: 'mini',
+      }
+    );
   }
 
   const className = cx(
@@ -919,7 +935,15 @@ const FilterableMultiSelect = React.forwardRef(function FilterableMultiSelect<
             translateWithId={translateWithId}
           />
         </div>
-        {normalizedSlug}
+        {slug ? (
+          normalizedDecorator
+        ) : decorator ? (
+          <div className={`${prefix}--list-box__inner-wrapper--decorator`}>
+            {normalizedDecorator}
+          </div>
+        ) : (
+          ''
+        )}
 
         <ListBox.Menu {...menuProps}>
           {isOpen
@@ -1019,6 +1043,11 @@ FilterableMultiSelect.propTypes = {
    */
   clearSelectionText: PropTypes.string,
 
+  /**
+   * **Experimental**: Provide a decorator component to be rendered inside the `FilterableMultiSelect` component
+   */
+  decorator: PropTypes.node,
+
   /**
    * Specify the direction of the multiselect dropdown. Can be either top or bottom.
    */
@@ -1142,10 +1171,10 @@ FilterableMultiSelect.propTypes = {
    */
   size: ListBoxPropTypes.ListBoxSize,
 
-  /**
-   * **Experimental**: Provide a `Slug` component to be rendered inside the `FilterableMultiSelect` component
-   */
-  slug: PropTypes.node,
+  slug: deprecate(
+    PropTypes.node,
+    'The `slug` prop has been deprecated and will be removed in the next major version. Use the decorator prop instead.'
+  ),
 
   ...sortingPropTypes,