From cf5dc882f29bcaf9f00a4af5765bf052d19d0a36 Mon Sep 17 00:00:00 2001
From: Alison Joseph <alison.joseph@us.ibm.com>
Date: Wed, 20 Nov 2024 09:25:33 -0600
Subject: [PATCH] feat(checkbox): replace slug prop with decorator (#18040)

* feat(checkbox): replace slug prop with decorator

* chore: update tests

* chore: add test

* chore: typo

* Update packages/react/src/components/Checkbox/Checkbox.tsx

Co-authored-by: Ariella Gilmore <ariellalgilmore@gmail.com>

* Update packages/react/src/components/CheckboxGroup/CheckboxGroup.tsx

Co-authored-by: Ariella Gilmore <ariellalgilmore@gmail.com>

* chore: cleanup styles

* feat: update checkbox decorator styles

* chore: typo

* chore: cleanup styles

* chore: format

* chore: revert storybook test changes

* chore: typo

---------

Co-authored-by: Ariella Gilmore <ariellalgilmore@gmail.com>
Co-authored-by: Guilherme Datilio Ribeiro <guilhermedatilio@gmail.com>
---
 .../__snapshots__/PublicAPI-test.js.snap      | 14 ++---
 .../components/Checkbox/Checkbox.stories.js   | 10 ++--
 .../src/components/Checkbox/Checkbox.tsx      | 54 +++++++++++++++----
 .../Checkbox/__tests__/Checkbox-test.js       | 34 +++++++++++-
 .../CheckboxGroup/CheckboxGroup-test.js       | 19 ++++++-
 .../CheckboxGroup/CheckboxGroup.tsx           | 52 ++++++++++++++----
 .../scss/components/checkbox/_checkbox.scss   | 31 ++++++++++-
 7 files changed, 179 insertions(+), 35 deletions(-)

diff --git a/packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap b/packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap
index 58a02b6cce38..8ca88ff17d11 100644
--- a/packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap
+++ b/packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap
@@ -613,6 +613,9 @@ Map {
       "className": Object {
         "type": "string",
       },
+      "decorator": Object {
+        "type": "node",
+      },
       "defaultChecked": Object {
         "type": "bool",
       },
@@ -648,9 +651,7 @@ Map {
       "readOnly": Object {
         "type": "bool",
       },
-      "slug": Object {
-        "type": "node",
-      },
+      "slug": [Function],
       "title": Object {
         "type": "string",
       },
@@ -671,6 +672,9 @@ Map {
       "className": Object {
         "type": "string",
       },
+      "decorator": Object {
+        "type": "node",
+      },
       "helperText": Object {
         "type": "node",
       },
@@ -699,9 +703,7 @@ Map {
       "readOnly": Object {
         "type": "bool",
       },
-      "slug": Object {
-        "type": "node",
-      },
+      "slug": [Function],
       "warn": Object {
         "type": "bool",
       },
diff --git a/packages/react/src/components/Checkbox/Checkbox.stories.js b/packages/react/src/components/Checkbox/Checkbox.stories.js
index ba8aff5eccee..1c6da060394c 100644
--- a/packages/react/src/components/Checkbox/Checkbox.stories.js
+++ b/packages/react/src/components/Checkbox/Checkbox.stories.js
@@ -124,7 +124,7 @@ const AILabelFunc = (kind) => (
 
 export const withAILabel = () => (
   <div className="ai-label-check-radio-container">
-    <CheckboxGroup legendText="Group Label" slug={AILabelFunc()}>
+    <CheckboxGroup legendText="Group Label" decorator={AILabelFunc()}>
       <Checkbox labelText={`Checkbox label`} id="checkbox-label-1" />
       <Checkbox labelText={`Checkbox label`} id="checkbox-label-2" />
       <Checkbox labelText={`Checkbox label`} id="checkbox-label-3" />
@@ -134,12 +134,12 @@ export const withAILabel = () => (
       <Checkbox
         labelText={`Checkbox label`}
         id="checkbox-label-4"
-        slug={AILabelFunc()}
+        decorator={AILabelFunc()}
       />
       <Checkbox
         labelText={`Checkbox label`}
         id="checkbox-label-5"
-        slug={AILabelFunc()}
+        decorator={AILabelFunc()}
       />
       <Checkbox labelText={`Checkbox label`} id="checkbox-label-6" />
     </CheckboxGroup>
@@ -148,12 +148,12 @@ export const withAILabel = () => (
       <Checkbox
         labelText={`Checkbox label`}
         id="checkbox-label-7"
-        slug={AILabelFunc('inline')}
+        decorator={AILabelFunc('inline')}
       />
       <Checkbox
         labelText={`Checkbox label`}
         id="checkbox-label-8"
-        slug={AILabelFunc('inline')}
+        decorator={AILabelFunc('inline')}
       />
       <Checkbox labelText={`Checkbox label`} id="checkbox-label-9" />
     </CheckboxGroup>
diff --git a/packages/react/src/components/Checkbox/Checkbox.tsx b/packages/react/src/components/Checkbox/Checkbox.tsx
index 277198c75c99..1ed09ec09e91 100644
--- a/packages/react/src/components/Checkbox/Checkbox.tsx
+++ b/packages/react/src/components/Checkbox/Checkbox.tsx
@@ -6,9 +6,10 @@
  */
 
 import PropTypes from 'prop-types';
-import React, { ReactNode } from 'react';
+import React, { ReactElement, ReactNode } from 'react';
 import classNames from 'classnames';
 import { Text } from '../Text';
+import deprecate from '../../prop-types/deprecate';
 import { usePrefix } from '../../internal/usePrefix';
 import { WarningFilled, WarningAltFilled } from '@carbon/icons-react';
 import { useId } from '../../internal/useId';
@@ -32,6 +33,11 @@ export interface CheckboxProps
    */
   labelText: NonNullable<ReactNode>;
 
+  /**
+   * **Experimental**: Provide a `decorator` component to be rendered inside the `Checkbox` component
+   */
+  decorator?: ReactNode;
+
   /**
    * Specify whether the underlying input should be checked by default
    */
@@ -68,6 +74,7 @@ export interface CheckboxProps
   invalidText?: ReactNode;
 
   /**
+   * @deprecated please use decorator instead.
    * **Experimental**: Provide a `Slug` component to be rendered inside the `Checkbox` component
    */
   slug?: ReactNode;
@@ -102,6 +109,7 @@ const Checkbox = React.forwardRef(
   (
     {
       className,
+      decorator,
       helperText,
       id,
       labelText,
@@ -146,18 +154,30 @@ const Checkbox = React.forwardRef(
         [`${prefix}--checkbox-wrapper--invalid`]: !readOnly && invalid,
         [`${prefix}--checkbox-wrapper--warning`]: showWarning,
         [`${prefix}--checkbox-wrapper--slug`]: slug,
+        [`${prefix}--checkbox-wrapper--decorator`]: decorator,
       }
     );
     const innerLabelClasses = classNames(`${prefix}--checkbox-label-text`, {
       [`${prefix}--visually-hidden`]: hideLabel,
     });
 
-    let normalizedSlug;
-    if (slug && React.isValidElement(slug)) {
-      const size = slug.props?.['kind'] === 'inline' ? 'md' : 'mini';
-      normalizedSlug = React.cloneElement(slug as React.ReactElement<any>, {
-        size,
-      });
+    let normalizedDecorator = React.isValidElement(slug ?? decorator)
+      ? (slug ?? decorator)
+      : null;
+    if (
+      normalizedDecorator &&
+      normalizedDecorator['type']?.displayName === 'AILabel'
+    ) {
+      const size =
+        (normalizedDecorator as ReactElement).props?.['kind'] === 'inline'
+          ? 'md'
+          : 'mini';
+      normalizedDecorator = React.cloneElement(
+        normalizedDecorator as React.ReactElement<any>,
+        {
+          size,
+        }
+      );
     }
 
     return (
@@ -203,7 +223,15 @@ const Checkbox = React.forwardRef(
           title={title}>
           <Text className={innerLabelClasses}>
             {labelText}
-            {normalizedSlug}
+            {slug ? (
+              normalizedDecorator
+            ) : decorator ? (
+              <div className={`${prefix}--checkbox-wrapper-inner--decorator`}>
+                {normalizedDecorator}
+              </div>
+            ) : (
+              ''
+            )}
           </Text>
         </label>
         <div className={`${prefix}--checkbox__validation-msg`}>
@@ -239,6 +267,11 @@ Checkbox.propTypes = {
    */
   className: PropTypes.string,
 
+  /**
+   * **Experimental**: Provide a decorator component to be rendered inside the `Checkbox` component
+   */
+  decorator: PropTypes.node,
+
   /**
    * Specify whether the underlying input should be checked by default
    */
@@ -300,7 +333,10 @@ Checkbox.propTypes = {
   /**
    * **Experimental**: Provide a `Slug` component to be rendered inside the `Checkbox` 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.'
+  ),
 
   /**
    * Specify a title for the <label> node for the Checkbox
diff --git a/packages/react/src/components/Checkbox/__tests__/Checkbox-test.js b/packages/react/src/components/Checkbox/__tests__/Checkbox-test.js
index 274ed2489a39..20851a03f807 100644
--- a/packages/react/src/components/Checkbox/__tests__/Checkbox-test.js
+++ b/packages/react/src/components/Checkbox/__tests__/Checkbox-test.js
@@ -199,7 +199,8 @@ describe('Checkbox', () => {
     expect(onChange).not.toHaveBeenCalled();
   });
 
-  it('should respect slug prop', () => {
+  it('should respect deprecated slug prop', () => {
+    const spy = jest.spyOn(console, 'warn').mockImplementation(() => {});
     const { container } = render(
       <Checkbox
         defaultChecked
@@ -212,5 +213,36 @@ describe('Checkbox', () => {
     expect(container.firstChild).toHaveClass(
       `${prefix}--checkbox-wrapper--slug`
     );
+    spy.mockRestore();
+  });
+
+  it('should respect decorator prop', () => {
+    const { container } = render(
+      <Checkbox
+        defaultChecked
+        labelText="Checkbox label"
+        id="checkbox-label-1"
+        decorator={<AILabel />}
+      />
+    );
+
+    expect(container.firstChild).toHaveClass(
+      `${prefix}--checkbox-wrapper--decorator`
+    );
+  });
+
+  it('should set size to "md" when decorator kind is "inline"', () => {
+    const { container } = render(
+      <Checkbox
+        defaultChecked
+        labelText="Checkbox label"
+        id="checkbox-label-2"
+        decorator={<AILabel kind="inline" />}
+      />
+    );
+
+    expect(
+      container.querySelector('.cds--ai-label__button--md')
+    ).toBeInTheDocument();
   });
 });
diff --git a/packages/react/src/components/CheckboxGroup/CheckboxGroup-test.js b/packages/react/src/components/CheckboxGroup/CheckboxGroup-test.js
index 48daafcba87c..6fd7a5ad574f 100644
--- a/packages/react/src/components/CheckboxGroup/CheckboxGroup-test.js
+++ b/packages/react/src/components/CheckboxGroup/CheckboxGroup-test.js
@@ -150,7 +150,8 @@ describe('CheckboxGroup', () => {
     );
   });
 
-  it('should respect slug prop', () => {
+  it('should respect deprecated slug prop', () => {
+    const spy = jest.spyOn(console, 'warn').mockImplementation(() => {});
     const { container } = render(
       <CheckboxGroup
         className="some-class"
@@ -160,7 +161,23 @@ describe('CheckboxGroup', () => {
     );
 
     expect(container.firstChild).toHaveClass(`${prefix}--checkbox-group--slug`);
+    spy.mockRestore();
   });
+
+  it('should respect decorator prop', () => {
+    const { container } = render(
+      <CheckboxGroup
+        className="some-class"
+        legendText="Checkbox heading"
+        decorator={<AILabel />}
+      />
+    );
+
+    expect(container.firstChild).toHaveClass(
+      `${prefix}--checkbox-group--decorator`
+    );
+  });
+
   it('should render checkboxes horizontally', () => {
     const { container } = render(
       <CheckboxGroup orientation="horizontal" legendText="test-horizental-prop">
diff --git a/packages/react/src/components/CheckboxGroup/CheckboxGroup.tsx b/packages/react/src/components/CheckboxGroup/CheckboxGroup.tsx
index f03104bfa542..4179e982f48a 100644
--- a/packages/react/src/components/CheckboxGroup/CheckboxGroup.tsx
+++ b/packages/react/src/components/CheckboxGroup/CheckboxGroup.tsx
@@ -6,8 +6,9 @@
  */
 
 import PropTypes from 'prop-types';
-import React, { ReactNode } from 'react';
+import React, { ReactElement, ReactNode } from 'react';
 import cx from 'classnames';
+import deprecate from '../../prop-types/deprecate';
 import { usePrefix } from '../../internal/usePrefix';
 import { WarningFilled, WarningAltFilled } from '@carbon/icons-react';
 import { useId } from '../../internal/useId';
@@ -15,6 +16,7 @@ import { useId } from '../../internal/useId';
 export interface CheckboxGroupProps {
   children?: ReactNode;
   className?: string;
+  decorator?: ReactNode;
   helperText?: ReactNode;
   invalid?: boolean;
   invalidText?: ReactNode;
@@ -22,6 +24,10 @@ export interface CheckboxGroupProps {
   orientation?: 'horizontal' | 'vertical';
   legendText: ReactNode;
   readOnly?: boolean;
+  /**
+   * * @deprecated please use decorator instead.
+   * **Experimental**: Provide a `Slug` component to be rendered inside the `Checkbox` component
+   */
   slug?: ReactNode;
   warn?: boolean;
   warnText?: ReactNode;
@@ -35,6 +41,7 @@ export interface CustomType {
 const CheckboxGroup: React.FC<CheckboxGroupProps> = ({
   children,
   className,
+  decorator,
   helperText,
   invalid,
   invalidText,
@@ -70,19 +77,26 @@ const CheckboxGroup: React.FC<CheckboxGroupProps> = ({
     [`${prefix}--checkbox-group--invalid`]: !readOnly && invalid,
     [`${prefix}--checkbox-group--warning`]: showWarning,
     [`${prefix}--checkbox-group--slug`]: slug,
+    [`${prefix}--checkbox-group--decorator`]: decorator,
   });
 
-  // Slug is always size `mini`
-  let normalizedSlug;
+  // AILabel always size `mini`
+  let normalizedDecorator = React.isValidElement(slug ?? decorator)
+    ? (slug ?? decorator)
+    : null;
   if (
-    React.isValidElement(slug) &&
-    (slug['type'] as any)?.displayName === 'AILabel'
+    normalizedDecorator &&
+    normalizedDecorator['type']?.displayName === 'AILabel'
   ) {
-    normalizedSlug = React.cloneElement(slug, {
-      size: 'mini',
-      kind: 'default',
-    } as CustomType);
+    normalizedDecorator = React.cloneElement(
+      normalizedDecorator as React.ReactElement<any>,
+      {
+        size: 'mini',
+        kind: 'default',
+      }
+    );
   }
+
   return (
     <fieldset
       className={fieldsetClasses}
@@ -95,7 +109,15 @@ const CheckboxGroup: React.FC<CheckboxGroupProps> = ({
         className={`${prefix}--label`}
         id={legendId || rest['aria-labelledby']}>
         {legendText}
-        {normalizedSlug}
+        {slug ? (
+          normalizedDecorator
+        ) : decorator ? (
+          <div className={`${prefix}--checkbox-group-inner--decorator`}>
+            {normalizedDecorator}
+          </div>
+        ) : (
+          ''
+        )}
       </legend>
       {children}
       <div className={`${prefix}--checkbox-group__validation-msg`}>
@@ -130,6 +152,11 @@ CheckboxGroup.propTypes = {
    */
   className: PropTypes.string,
 
+  /**
+   * **Experimental**: Provide a decorator component to be rendered inside the `CheckboxGroup` component
+   */
+  decorator: PropTypes.node,
+
   /**
    * Provide text for the form group for additional help
    */
@@ -168,7 +195,10 @@ CheckboxGroup.propTypes = {
   /**
    * **Experimental**: Provide a `Slug` component to be rendered inside the `CheckboxGroup` 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.'
+  ),
 
   /**
    * Specify whether the form group is currently in warning state
diff --git a/packages/styles/scss/components/checkbox/_checkbox.scss b/packages/styles/scss/components/checkbox/_checkbox.scss
index 628496f5b3f1..7bdaa776145f 100644
--- a/packages/styles/scss/components/checkbox/_checkbox.scss
+++ b/packages/styles/scss/components/checkbox/_checkbox.scss
@@ -367,12 +367,30 @@
     transform: scale(1.2) rotate3d(0.5, 1, 0, 158deg);
   }
 
-  // Slug styles
+  //-----------------------------------------------
+  // Decorator
+  //-----------------------------------------------
+  .#{$prefix}--checkbox-group--decorator legend.#{$prefix}--label,
+  .#{$prefix}--checkbox-wrapper--decorator .#{$prefix}--checkbox-label-text {
+    display: flex;
+  }
+  // Remove v12
   .#{$prefix}--checkbox-group--slug legend.#{$prefix}--label,
   .#{$prefix}--checkbox-wrapper--slug .#{$prefix}--checkbox-label-text {
     display: flex;
   }
 
+  .#{$prefix}--checkbox-group--decorator
+    legend.#{$prefix}--label
+    .#{$prefix}--checkbox-group-inner--decorator
+    > *,
+  .#{$prefix}--checkbox-wrapper--decorator
+    .#{$prefix}--checkbox-label-text
+    .#{$prefix}--checkbox-wrapper-inner--decorator
+    > * {
+    margin-inline-start: $spacing-03;
+  }
+  // Remove v12
   .#{$prefix}--checkbox-group--slug
     legend.#{$prefix}--label
     .#{$prefix}--ai-label,
@@ -386,6 +404,13 @@
     margin-inline-start: $spacing-03;
   }
 
+  .#{$prefix}--checkbox-wrapper--decorator
+    .#{$prefix}--checkbox-label-text
+    .#{$prefix}--ai-label__button--inline {
+    line-height: inherit;
+    margin-block-start: convert.to-rem(-1px);
+  }
+  // Remove v12
   .#{$prefix}--checkbox-wrapper--slug
     .#{$prefix}--checkbox-label-text
     .#{$prefix}--ai-label__button--inline,
@@ -396,7 +421,9 @@
     margin-block-start: convert.to-rem(-1px);
   }
 
-  // horizontal checkbox group
+  //-----------------------------------------------
+  // Horizontal group
+  //-----------------------------------------------
   .#{$prefix}--checkbox-group--horizontal {
     position: relative;
     display: flex;