From c52884cfc64972d75e133a698417e8d6dab588a3 Mon Sep 17 00:00:00 2001
From: Alison Joseph <alison.joseph@us.ibm.com>
Date: Thu, 21 Nov 2024 09:07:56 -0600
Subject: [PATCH] feat: replace slug with decorator ComboBox, MultiSelect,
 FilterableMultiSelect (#18069)

* feat(combobox): replace slug prop with decorator

* chore: update tests

* feat: add decorator prop to multiselect

* feat: add decorator prop to filterablemultiselect

* chore: format and snapshot

* chore: update form story

* feat: add with ailabel stories to fluid and form stories

* chore:format

---------

Co-authored-by: Guilherme Datilio Ribeiro <guilhermedatilio@gmail.com>
---
 .../__snapshots__/PublicAPI-test.js.snap      | 28 +++++-----
 .../src/components/ComboBox/ComboBox-test.js  | 12 +++++
 .../components/ComboBox/ComboBox.stories.js   |  2 +-
 .../src/components/ComboBox/ComboBox.tsx      | 51 +++++++++++++++----
 .../FluidComboBox/FluidComboBox.stories.js    | 50 +++++++++++++++++-
 .../FluidDropdown/FluidDropdown.stories.js    | 50 +++++++++++++++++-
 .../FluidMultiSelect.stories.js               | 51 ++++++++++++++++++-
 .../react/src/components/Form/Form.stories.js | 12 ++---
 .../MultiSelect/FilterableMultiSelect.tsx     | 51 +++++++++++++++----
 .../MultiSelect/MultiSelect.stories.js        |  5 +-
 .../components/MultiSelect/MultiSelect.tsx    | 51 +++++++++++++++----
 .../__tests__/FilterableMultiSelect-test.js   | 13 +++++
 .../MultiSelect/__tests__/MultiSelect-test.js | 20 ++++++++
 13 files changed, 338 insertions(+), 58 deletions(-)

diff --git a/packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap b/packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap
index 4e35619514b3..138dc96a9985 100644
--- a/packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap
+++ b/packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap
@@ -1265,6 +1265,9 @@ Map {
       "className": Object {
         "type": "string",
       },
+      "decorator": Object {
+        "type": "node",
+      },
       "direction": Object {
         "args": Array [
           Array [
@@ -1375,9 +1378,7 @@ Map {
         ],
         "type": "oneOf",
       },
-      "slug": Object {
-        "type": "node",
-      },
+      "slug": [Function],
       "titleText": Object {
         "type": "node",
       },
@@ -3559,6 +3560,9 @@ Map {
       "compareItems": Object {
         "type": "func",
       },
+      "decorator": Object {
+        "type": "node",
+      },
       "direction": Object {
         "args": Array [
           Array [
@@ -3773,9 +3777,7 @@ Map {
         ],
         "type": "oneOf",
       },
-      "slug": Object {
-        "type": "node",
-      },
+      "slug": [Function],
       "sortItems": Object {
         "type": "func",
       },
@@ -5240,6 +5242,9 @@ Map {
         "compareItems": Object {
           "type": "func",
         },
+        "decorator": Object {
+          "type": "node",
+        },
         "direction": Object {
           "args": Array [
             Array [
@@ -5454,9 +5459,7 @@ Map {
           ],
           "type": "oneOf",
         },
-        "slug": Object {
-          "type": "node",
-        },
+        "slug": [Function],
         "sortItems": Object {
           "type": "func",
         },
@@ -5494,6 +5497,9 @@ Map {
       "compareItems": Object {
         "type": "func",
       },
+      "decorator": Object {
+        "type": "node",
+      },
       "direction": Object {
         "args": Array [
           Array [
@@ -5581,9 +5587,7 @@ Map {
         ],
         "type": "oneOf",
       },
-      "slug": Object {
-        "type": "node",
-      },
+      "slug": [Function],
       "sortItems": Object {
         "type": "func",
       },
diff --git a/packages/react/src/components/ComboBox/ComboBox-test.js b/packages/react/src/components/ComboBox/ComboBox-test.js
index 15576ee7c555..36bca1f45cbb 100644
--- a/packages/react/src/components/ComboBox/ComboBox-test.js
+++ b/packages/react/src/components/ComboBox/ComboBox-test.js
@@ -285,6 +285,7 @@ describe('ComboBox', () => {
   });
 
   it('should respect slug prop', async () => {
+    const spy = jest.spyOn(console, 'warn').mockImplementation(() => {});
     const { container } = render(
       <ComboBox {...mockProps} slug={<AILabel />} />
     );
@@ -292,6 +293,17 @@ describe('ComboBox', () => {
     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`', () => {
diff --git a/packages/react/src/components/ComboBox/ComboBox.stories.js b/packages/react/src/components/ComboBox/ComboBox.stories.js
index 3a355fae4d27..451ace723902 100644
--- a/packages/react/src/components/ComboBox/ComboBox.stories.js
+++ b/packages/react/src/components/ComboBox/ComboBox.stories.js
@@ -197,7 +197,7 @@ export const withAILabel = () => (
       itemToString={(item) => (item ? item.text : '')}
       titleText="ComboBox title"
       helperText="Combobox helper text"
-      slug={aiLabel}
+      decorator={aiLabel}
     />
   </div>
 );
diff --git a/packages/react/src/components/ComboBox/ComboBox.tsx b/packages/react/src/components/ComboBox/ComboBox.tsx
index 1283e740e568..dd49efd7c52c 100644
--- a/packages/react/src/components/ComboBox/ComboBox.tsx
+++ b/packages/react/src/components/ComboBox/ComboBox.tsx
@@ -204,6 +204,11 @@ export interface ComboBoxProps<ItemType>
    */
   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 @@ export interface ComboBoxProps<ItemType>
   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 @@ const ComboBox = forwardRef(
       ariaLabel: deprecatedAriaLabel,
       autoAlign = false,
       className: containerClassName,
+      decorator,
       direction = 'bottom',
       disabled = false,
       downshiftActions,
@@ -694,6 +701,7 @@ const ComboBox = forwardRef(
         [`${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,
       },
     ]);
 
@@ -705,12 +713,20 @@ const ComboBox = forwardRef(
     // 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 {
@@ -1038,7 +1054,15 @@ const ComboBox = forwardRef(
               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(
@@ -1133,6 +1157,11 @@ ComboBox.propTypes = {
    */
   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.
    */
@@ -1283,10 +1312,10 @@ ComboBox.propTypes = {
    */
   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
diff --git a/packages/react/src/components/FluidComboBox/FluidComboBox.stories.js b/packages/react/src/components/FluidComboBox/FluidComboBox.stories.js
index de6e62746430..aefd4f0794aa 100644
--- a/packages/react/src/components/FluidComboBox/FluidComboBox.stories.js
+++ b/packages/react/src/components/FluidComboBox/FluidComboBox.stories.js
@@ -13,7 +13,10 @@ import {
   ToggletipButton,
   ToggletipContent,
 } from '../Toggletip';
-import { Information } from '@carbon/icons-react';
+import { AILabel, AILabelContent, AILabelActions } from '../AILabel';
+import { IconButton } from '../IconButton';
+import { Button } from '../Button';
+import { Information, View, FolderOpen, Folders } from '@carbon/icons-react';
 
 export default {
   title: 'Experimental/Fluid Components/unstable__FluidComboBox',
@@ -92,6 +95,51 @@ export const Condensed = () => (
   </div>
 );
 
+const aiLabel = (
+  <AILabel className="ai-label-container">
+    <AILabelContent>
+      <div>
+        <p className="secondary">AI Explained</p>
+        <h1>84%</h1>
+        <p className="secondary bold">Confidence score</p>
+        <p className="secondary">
+          Lorem ipsum dolor sit amet, di os consectetur adipiscing elit, sed do
+          eiusmod tempor incididunt ut fsil labore et dolore magna aliqua.
+        </p>
+        <hr />
+        <p className="secondary">Model type</p>
+        <p className="bold">Foundation model</p>
+      </div>
+      <AILabelActions>
+        <IconButton kind="ghost" label="View">
+          <View />
+        </IconButton>
+        <IconButton kind="ghost" label="Open Folder">
+          <FolderOpen />
+        </IconButton>
+        <IconButton kind="ghost" label="Folders">
+          <Folders />
+        </IconButton>
+        <Button>View details</Button>
+      </AILabelActions>
+    </AILabelContent>
+  </AILabel>
+);
+
+export const withAILabel = () => (
+  <div style={{ width: '400px' }}>
+    <FluidComboBox
+      onChange={() => {}}
+      id="default"
+      titleText="Label"
+      label="Choose an option"
+      items={items}
+      itemToString={(item) => (item ? item.text : '')}
+      decorator={aiLabel}
+    />
+  </div>
+);
+
 export const Playground = (args) => (
   <div style={{ width: args.playgroundWidth }}>
     <FluidComboBox
diff --git a/packages/react/src/components/FluidDropdown/FluidDropdown.stories.js b/packages/react/src/components/FluidDropdown/FluidDropdown.stories.js
index 953c79134830..fa4d1cf440f8 100644
--- a/packages/react/src/components/FluidDropdown/FluidDropdown.stories.js
+++ b/packages/react/src/components/FluidDropdown/FluidDropdown.stories.js
@@ -13,7 +13,10 @@ import {
   ToggletipButton,
   ToggletipContent,
 } from '../Toggletip';
-import { Information } from '@carbon/icons-react';
+import { AILabel, AILabelContent, AILabelActions } from '../AILabel';
+import { IconButton } from '../IconButton';
+import { Button } from '../Button';
+import { Information, View, FolderOpen, Folders } from '@carbon/icons-react';
 
 export default {
   title: 'Experimental/Fluid Components/unstable__FluidDropdown',
@@ -91,6 +94,51 @@ export const Condensed = () => (
   </div>
 );
 
+const aiLabel = (
+  <AILabel className="ai-label-container">
+    <AILabelContent>
+      <div>
+        <p className="secondary">AI Explained</p>
+        <h1>84%</h1>
+        <p className="secondary bold">Confidence score</p>
+        <p className="secondary">
+          Lorem ipsum dolor sit amet, di os consectetur adipiscing elit, sed do
+          eiusmod tempor incididunt ut fsil labore et dolore magna aliqua.
+        </p>
+        <hr />
+        <p className="secondary">Model type</p>
+        <p className="bold">Foundation model</p>
+      </div>
+      <AILabelActions>
+        <IconButton kind="ghost" label="View">
+          <View />
+        </IconButton>
+        <IconButton kind="ghost" label="Open Folder">
+          <FolderOpen />
+        </IconButton>
+        <IconButton kind="ghost" label="Folders">
+          <Folders />
+        </IconButton>
+        <Button>View details</Button>
+      </AILabelActions>
+    </AILabelContent>
+  </AILabel>
+);
+
+export const withAILabel = () => (
+  <div style={{ width: '400px' }}>
+    <FluidDropdown
+      initialSelectedItem={items[2]}
+      id="default"
+      titleText="Label"
+      label="Choose an option"
+      items={items}
+      itemToString={(item) => (item ? item.text : '')}
+      decorator={aiLabel}
+    />
+  </div>
+);
+
 export const Playground = (args) => (
   <div style={{ width: args.playgroundWidth }}>
     <FluidDropdown
diff --git a/packages/react/src/components/FluidMultiSelect/FluidMultiSelect.stories.js b/packages/react/src/components/FluidMultiSelect/FluidMultiSelect.stories.js
index 6211af47fd60..e06050611ab9 100644
--- a/packages/react/src/components/FluidMultiSelect/FluidMultiSelect.stories.js
+++ b/packages/react/src/components/FluidMultiSelect/FluidMultiSelect.stories.js
@@ -18,7 +18,10 @@ import {
   ToggletipButton,
   ToggletipContent,
 } from '../Toggletip';
-import { Information } from '@carbon/icons-react';
+import { AILabel, AILabelContent, AILabelActions } from '../AILabel';
+import { IconButton } from '../IconButton';
+import { Button } from '../Button';
+import { Information, View, FolderOpen, Folders } from '@carbon/icons-react';
 
 export default {
   title: 'Experimental/Fluid Components/unstable__FluidMultiSelect',
@@ -130,6 +133,52 @@ export const Condensed = () => (
   </div>
 );
 
+const aiLabel = (
+  <AILabel className="ai-label-container">
+    <AILabelContent>
+      <div>
+        <p className="secondary">AI Explained</p>
+        <h1>84%</h1>
+        <p className="secondary bold">Confidence score</p>
+        <p className="secondary">
+          Lorem ipsum dolor sit amet, di os consectetur adipiscing elit, sed do
+          eiusmod tempor incididunt ut fsil labore et dolore magna aliqua.
+        </p>
+        <hr />
+        <p className="secondary">Model type</p>
+        <p className="bold">Foundation model</p>
+      </div>
+      <AILabelActions>
+        <IconButton kind="ghost" label="View">
+          <View />
+        </IconButton>
+        <IconButton kind="ghost" label="Open Folder">
+          <FolderOpen />
+        </IconButton>
+        <IconButton kind="ghost" label="Folders">
+          <Folders />
+        </IconButton>
+        <Button>View details</Button>
+      </AILabelActions>
+    </AILabelContent>
+  </AILabel>
+);
+
+export const withAILabel = () => (
+  <div style={{ width: '400px' }}>
+    <FluidMultiSelect
+      onChange={() => {}}
+      initialSelectedItem={items[2]}
+      id="default"
+      titleText="Label"
+      label="Choose an option"
+      items={items}
+      itemToString={(item) => (item ? item.text : '')}
+      decorator={aiLabel}
+    />
+  </div>
+);
+
 export const Playground = (args) => (
   <div style={{ width: args.playgroundWidth }}>
     <FluidMultiSelect
diff --git a/packages/react/src/components/Form/Form.stories.js b/packages/react/src/components/Form/Form.stories.js
index c80a3339a377..ac7d51780a1f 100644
--- a/packages/react/src/components/Form/Form.stories.js
+++ b/packages/react/src/components/Form/Form.stories.js
@@ -338,7 +338,7 @@ export const withAILabel = (args) => {
             items={items}
             itemToString={(item) => (item ? item.text : '')}
             selectionFeedback="top-after-reopen"
-            slug={aiLabel}
+            decorator={aiLabel}
             {...rest}
           />
           <FilterableMultiSelect
@@ -348,7 +348,7 @@ export const withAILabel = (args) => {
             items={items}
             itemToString={(item) => (item ? item.text : '')}
             selectionFeedback="top-after-reopen"
-            slug={aiLabel}
+            decorator={aiLabel}
             {...rest}
           />
           <ComboBox
@@ -358,7 +358,7 @@ export const withAILabel = (args) => {
             itemToString={(item) => (item ? item.text : '')}
             titleText="ComboBox title"
             helperText="Combobox helper text"
-            slug={aiLabel}
+            decorator={aiLabel}
             {...rest}
           />
           <Select
@@ -442,7 +442,7 @@ export const withAILabel = (args) => {
             label="Choose an option"
             items={items}
             itemToString={(item) => (item ? item.text : '')}
-            slug={aiLabel}
+            decorator={aiLabel}
             {...rest}
           />
         </div>
@@ -456,7 +456,7 @@ export const withAILabel = (args) => {
             label="Choose an option"
             items={items}
             itemToString={(item) => (item ? item.text : '')}
-            slug={aiLabel}
+            decorator={aiLabel}
             {...rest}
           />
         </div>
@@ -471,7 +471,7 @@ export const withAILabel = (args) => {
             label="Choose an option"
             items={items}
             itemToString={(item) => (item ? item.text : '')}
-            slug={aiLabel}
+            decorator={aiLabel}
             {...rest}
           />
         </div>
diff --git a/packages/react/src/components/MultiSelect/FilterableMultiSelect.tsx b/packages/react/src/components/MultiSelect/FilterableMultiSelect.tsx
index a61fa77b9518..e1a5893ab4be 100644
--- a/packages/react/src/components/MultiSelect/FilterableMultiSelect.tsx
+++ b/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.
    */
@@ -281,6 +286,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;
@@ -318,6 +324,7 @@ const FilterableMultiSelect = React.forwardRef(function FilterableMultiSelect<
     clearSelectionDescription = 'Total items selected: ',
     clearSelectionText = 'To clear selection, press Delete or Backspace',
     compareItems = defaultCompareItems,
+    decorator,
     direction = 'bottom',
     disabled = false,
     downshiftProps,
@@ -467,6 +474,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,
     }
   );
@@ -674,12 +682,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(
@@ -916,7 +932,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
@@ -1016,6 +1040,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.
    */
@@ -1139,10 +1168,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,
 
diff --git a/packages/react/src/components/MultiSelect/MultiSelect.stories.js b/packages/react/src/components/MultiSelect/MultiSelect.stories.js
index b6ffbae7c858..819d32671c8c 100644
--- a/packages/react/src/components/MultiSelect/MultiSelect.stories.js
+++ b/packages/react/src/components/MultiSelect/MultiSelect.stories.js
@@ -18,7 +18,6 @@ import ButtonSet from '../ButtonSet';
 import { AILabel, AILabelContent, AILabelActions } from '../AILabel';
 import { IconButton } from '../IconButton';
 import { View, FolderOpen, Folders } from '@carbon/icons-react';
-import { Tabs, Tab, TabList, TabPanels, TabPanel } from '@carbon/react';
 
 export default {
   title: 'Components/MultiSelect',
@@ -483,7 +482,7 @@ export const withAILabel = () => (
       items={items}
       itemToString={(item) => (item ? item.text : '')}
       selectionFeedback="top-after-reopen"
-      slug={aiLabel}
+      decorator={aiLabel}
     />
   </div>
 );
@@ -498,7 +497,7 @@ export const FilterableWithAILabel = () => (
       items={items}
       itemToString={(item) => (item ? item.text : '')}
       selectionFeedback="top-after-reopen"
-      slug={aiLabel}
+      decorator={aiLabel}
     />
   </div>
 );
diff --git a/packages/react/src/components/MultiSelect/MultiSelect.tsx b/packages/react/src/components/MultiSelect/MultiSelect.tsx
index d9d18bddc023..f9917dd75d92 100644
--- a/packages/react/src/components/MultiSelect/MultiSelect.tsx
+++ b/packages/react/src/components/MultiSelect/MultiSelect.tsx
@@ -128,6 +128,11 @@ export interface MultiSelectProps<ItemType>
    */
   clearSelectionText?: string;
 
+  /**
+   * **Experimental**: Provide a `decorator` component to be rendered inside the `MultiSelect` component
+   */
+  decorator?: ReactNode;
+
   /**
    * Specify the direction of the multiselect dropdown. Can be either top or bottom.
    */
@@ -260,6 +265,7 @@ export interface MultiSelectProps<ItemType>
   size?: ListBoxSize;
 
   /**
+   * @deprecated please use decorator instead.
    * **Experimental**: Provide a `Slug` component to be rendered inside the `MultiSelect` component
    */
   slug?: ReactNode;
@@ -296,6 +302,7 @@ const MultiSelect = React.forwardRef(
     {
       autoAlign = false,
       className: containerClassName,
+      decorator,
       id,
       items,
       itemToElement,
@@ -538,6 +545,7 @@ const MultiSelect = React.forwardRef(
         [`${prefix}--list-box__wrapper--fluid--focus`]:
           !isOpen && isFluid && isFocused,
         [`${prefix}--list-box__wrapper--slug`]: slug,
+        [`${prefix}--list-box__wrapper--decorator`]: decorator,
       }
     );
     const titleClasses = cx(`${prefix}--label`, {
@@ -679,12 +687,20 @@ const MultiSelect = React.forwardRef(
         }
       : {};
 
-    // 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 itemsSelectedText =
@@ -773,7 +789,15 @@ const MultiSelect = React.forwardRef(
                 translateWithId={translateWithId}
               />
             </button>
-            {normalizedSlug}
+            {slug ? (
+              normalizedDecorator
+            ) : decorator ? (
+              <div className={`${prefix}--list-box__inner-wrapper--decorator`}>
+                {normalizedDecorator}
+              </div>
+            ) : (
+              ''
+            )}
           </div>
           <ListBox.Menu {...menuProps}>
             {isOpen &&
@@ -886,6 +910,11 @@ MultiSelect.propTypes = {
    */
   compareItems: PropTypes.func,
 
+  /**
+   * **Experimental**: Provide a decorator component to be rendered inside the `MultiSelect` component
+   */
+  decorator: PropTypes.node,
+
   /**
    * Specify the direction of the multiselect dropdown. Can be either top or bottom.
    */
@@ -1019,10 +1048,10 @@ MultiSelect.propTypes = {
    */
   size: ListBoxPropTypes.ListBoxSize,
 
-  /**
-   * **Experimental**: Provide a `Slug` component to be rendered inside the `MultiSelect` 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 a method that sorts all options in the control. Overriding this
diff --git a/packages/react/src/components/MultiSelect/__tests__/FilterableMultiSelect-test.js b/packages/react/src/components/MultiSelect/__tests__/FilterableMultiSelect-test.js
index d992d5b61927..b7287b9d6dbb 100644
--- a/packages/react/src/components/MultiSelect/__tests__/FilterableMultiSelect-test.js
+++ b/packages/react/src/components/MultiSelect/__tests__/FilterableMultiSelect-test.js
@@ -250,6 +250,7 @@ describe('FilterableMultiSelect', () => {
   });
 
   it('should respect slug prop', async () => {
+    const spy = jest.spyOn(console, 'warn').mockImplementation(() => {});
     const { container } = render(
       <FilterableMultiSelect {...mockProps} slug={<AILabel />} />
     );
@@ -258,6 +259,18 @@ describe('FilterableMultiSelect', () => {
     expect(container.firstChild).toHaveClass(
       `${prefix}--list-box__wrapper--slug`
     );
+    spy.mockRestore();
+  });
+
+  it('should respect decorator prop', async () => {
+    const { container } = render(
+      <FilterableMultiSelect {...mockProps} decorator={<AILabel />} />
+    );
+    await waitForPosition();
+
+    expect(container.firstChild).toHaveClass(
+      `${prefix}--list-box__wrapper--decorator`
+    );
   });
 
   it('should place the given id on the listbox wrapper', async () => {
diff --git a/packages/react/src/components/MultiSelect/__tests__/MultiSelect-test.js b/packages/react/src/components/MultiSelect/__tests__/MultiSelect-test.js
index fd977410fd70..8e16e2c4dc20 100644
--- a/packages/react/src/components/MultiSelect/__tests__/MultiSelect-test.js
+++ b/packages/react/src/components/MultiSelect/__tests__/MultiSelect-test.js
@@ -586,6 +586,7 @@ describe('MultiSelect', () => {
     });
 
     it('should respect slug prop', async () => {
+      const spy = jest.spyOn(console, 'warn').mockImplementation(() => {});
       const items = generateItems(4, generateGenericItem);
       const label = 'test-label';
       const { container } = render(
@@ -596,6 +597,25 @@ describe('MultiSelect', () => {
       expect(container.firstChild).toHaveClass(
         `${prefix}--list-box__wrapper--slug`
       );
+      spy.mockRestore();
+    });
+
+    it('should respect decorator prop', async () => {
+      const items = generateItems(4, generateGenericItem);
+      const label = 'test-label';
+      const { container } = render(
+        <MultiSelect
+          id="test"
+          label={label}
+          items={items}
+          decorator={<AILabel />}
+        />
+      );
+      await waitForPosition();
+
+      expect(container.firstChild).toHaveClass(
+        `${prefix}--list-box__wrapper--decorator`
+      );
     });
 
     it('should select all options when isSelectAll property in an item is provided', async () => {