From ba75bce46ef0142cf6c4c63e320d19ae85120958 Mon Sep 17 00:00:00 2001
From: Michael Taranto <michael.taranto@gmail.com>
Date: Wed, 22 May 2024 13:35:34 +1000
Subject: [PATCH] ButtonIcon: Add `small` size

---
 .changeset/few-ravens-cheat.md                |  22 ++++
 .changeset/mighty-comics-tan.md               |  14 +++
 .../components/Autosuggest/Autosuggest.tsx    |   1 +
 .../components/ButtonIcon/ButtonIcon.docs.tsx |  28 +++--
 .../ButtonIcon/ButtonIcon.gallery.tsx         |  58 ++++++----
 .../ButtonIcon/ButtonIcon.playroom.tsx        |   9 +-
 .../ButtonIcon/ButtonIcon.screenshots.tsx     | 102 ++++++++++++------
 .../ButtonIcon/ButtonIcon.snippets.tsx        |  11 ++
 .../lib/components/ButtonIcon/ButtonIcon.tsx  |  23 ++--
 .../FieldButtonIcon/FieldButtonIcon.tsx       |   1 +
 .../src/__snapshots__/contract.test.ts.snap   |   1 +
 11 files changed, 203 insertions(+), 67 deletions(-)
 create mode 100644 .changeset/few-ravens-cheat.md
 create mode 100644 .changeset/mighty-comics-tan.md

diff --git a/.changeset/few-ravens-cheat.md b/.changeset/few-ravens-cheat.md
new file mode 100644
index 00000000000..24eaad4981e
--- /dev/null
+++ b/.changeset/few-ravens-cheat.md
@@ -0,0 +1,22 @@
+---
+'braid-design-system': minor
+---
+
+---
+new:
+  - ButtonIcon
+---
+
+**ButtonIcon:** Add `small` size
+
+Introduce a new `small` size for `ButtonIcon` component.
+This size sits alongside the existing `standard` and `large` sizes.
+
+**EXAMPLE USAGE:**
+```jsx
+<ButtonIcon
+  size="small"
+  icon={<IconEdit />}
+  label="Small size"
+/>
+```
diff --git a/.changeset/mighty-comics-tan.md b/.changeset/mighty-comics-tan.md
new file mode 100644
index 00000000000..d43829f9bea
--- /dev/null
+++ b/.changeset/mighty-comics-tan.md
@@ -0,0 +1,14 @@
+---
+'braid-design-system': patch
+---
+
+---
+updated:
+  - Autosuggest
+  - PasswordField
+  - TextField
+---
+
+Adopt `small` sized `ButtonIcon` for field actions
+
+Switch over to `small` (previously `standard`) sized `ButtonIcon` for field actions such as clear field, or toggle password visibility.
diff --git a/packages/braid-design-system/src/lib/components/Autosuggest/Autosuggest.tsx b/packages/braid-design-system/src/lib/components/Autosuggest/Autosuggest.tsx
index 493e278e8a7..075c99f72c5 100644
--- a/packages/braid-design-system/src/lib/components/Autosuggest/Autosuggest.tsx
+++ b/packages/braid-design-system/src/lib/components/Autosuggest/Autosuggest.tsx
@@ -184,6 +184,7 @@ function SuggestionItem({
               icon={<IconClear />}
               tone="secondary"
               tabIndex={-1}
+              size="small"
               label={clearLabel || 'Clear suggestion'}
               onClick={(event: MouseEvent) => {
                 event.preventDefault();
diff --git a/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.docs.tsx b/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.docs.tsx
index 596d681845b..083761bbeaf 100644
--- a/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.docs.tsx
+++ b/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.docs.tsx
@@ -110,19 +110,33 @@ const docs: ComponentDocs = {
         <>
           <Text>
             The button size can be customised via the <Strong>size</Strong>{' '}
-            prop, which accepts either <Strong>standard</Strong> or{' '}
-            <Strong>large</Strong>.
-          </Text>
-          <Text>
-            Both follow the standard text definition from the theme, where{' '}
-            <Strong>standard</Strong> follows the text size and{' '}
-            <Strong>large</Strong> follows the line height.
+            prop, which accepts either <Strong>small</Strong>,{' '}
+            <Strong>standard</Strong> (default) or <Strong>large</Strong>.
           </Text>
+          <Notice>
+            <Text>
+              The <Strong>standard</Strong> and <Strong>large</Strong> sizes
+              both follow the standard text definition from the theme, where{' '}
+              <Strong>standard</Strong> follows the text size and{' '}
+              <Strong>large</Strong> follows the line height.
+            </Text>
+          </Notice>
         </>
       ),
       Example: () =>
         source(
           <Stack space="gutter">
+            <Inline space="gutter" alignY="center">
+              <ButtonIcon
+                size="small"
+                icon={<IconEdit />}
+                label="Small size"
+                id="size-0"
+              />
+              <Text tone="secondary" size="xsmall">
+                SMALL
+              </Text>
+            </Inline>
             <Inline space="gutter" alignY="center">
               <ButtonIcon
                 size="standard"
diff --git a/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.gallery.tsx b/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.gallery.tsx
index 9024fcd0b94..e37f12a1a84 100644
--- a/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.gallery.tsx
+++ b/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.gallery.tsx
@@ -11,11 +11,13 @@ import {
   IconShare,
   IconAdd,
   IconClear,
+  Stack,
+  Text,
 } from '../';
 
 export const galleryItems: ComponentExample[] = [
   {
-    label: 'Default',
+    label: 'Soft',
     background: 'surface',
     Example: () =>
       source(
@@ -77,27 +79,45 @@ export const galleryItems: ComponentExample[] = [
       ),
   },
   {
-    label: 'Large size',
+    label: 'Sizes',
     background: 'surface',
     Example: () =>
       source(
-        <Inline space="small">
-          <ButtonIcon
-            size="large"
-            variant="soft"
-            icon={<IconAdd />}
-            label="Add"
-            id="buttonicon-large-1"
-          />
-          <ButtonIcon
-            size="large"
-            variant="transparent"
-            bleed={false}
-            icon={<IconAdd />}
-            label="Add"
-            id="buttonicon-large-2"
-          />
-        </Inline>,
+        <Stack space="medium">
+          <Inline space="medium" alignY="center">
+            <ButtonIcon
+              size="small"
+              icon={<IconAdd />}
+              label="Small size"
+              id="size-0"
+            />
+            <Text tone="secondary" size="xsmall">
+              SMALL
+            </Text>
+          </Inline>
+          <Inline space="medium" alignY="center">
+            <ButtonIcon
+              size="standard"
+              icon={<IconAdd />}
+              label="Standard size"
+              id="size-1"
+            />
+            <Text tone="secondary" size="xsmall">
+              STANDARD
+            </Text>
+          </Inline>
+          <Inline space="medium" alignY="center">
+            <ButtonIcon
+              size="large"
+              icon={<IconAdd />}
+              label="Large size"
+              id="size-2"
+            />
+            <Text tone="secondary" size="xsmall">
+              LARGE
+            </Text>
+          </Inline>
+        </Stack>,
       ),
   },
   {
diff --git a/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.playroom.tsx b/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.playroom.tsx
index 240766927cc..40dbda69a2f 100644
--- a/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.playroom.tsx
+++ b/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.playroom.tsx
@@ -5,20 +5,27 @@ import {
   ButtonIcon as BraidButtonIcon,
   buttonIconVariants,
   buttonIconTones,
+  buttonIconSizes,
 } from './ButtonIcon';
 
 export const ButtonIcon = forwardRef<HTMLButtonElement, ButtonIconProps>(
-  ({ variant, id, tone, ...restProps }, ref) => {
+  ({ variant, id, tone, icon, size, ...restProps }, ref) => {
     const fallbackId = useFallbackId();
     const isValidVariant = variant && buttonIconVariants.indexOf(variant) > -1;
     const isValidTone = tone && buttonIconTones.indexOf(tone) > -1;
 
+    if (!icon || typeof icon === 'boolean') {
+      return null;
+    }
+
     return (
       <BraidButtonIcon
         ref={ref}
         id={id ?? fallbackId}
         variant={isValidVariant ? variant : undefined}
         tone={isValidTone ? tone : undefined}
+        icon={icon}
+        size={size && buttonIconSizes.includes(size) ? size : undefined}
         {...restProps}
       />
     );
diff --git a/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.screenshots.tsx b/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.screenshots.tsx
index 676806ffa04..1f72b7732a9 100644
--- a/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.screenshots.tsx
+++ b/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.screenshots.tsx
@@ -15,16 +15,32 @@ export const screenshots: ComponentScreenshot = {
       ),
     },
     {
-      label: 'Soft - large',
+      label: 'Soft',
       background: 'surface',
       Example: () => (
-        <ButtonIcon
-          variant="soft"
-          size="large"
-          icon={<IconBookmark />}
-          label="Bookmark"
-          id="1"
-        />
+        <Inline space="large" alignY="center">
+          <ButtonIcon
+            variant="soft"
+            size="small"
+            icon={<IconBookmark />}
+            label="Small"
+            id="1"
+          />
+          <ButtonIcon
+            variant="soft"
+            size="standard"
+            icon={<IconBookmark />}
+            label="Standard"
+            id="2"
+          />
+          <ButtonIcon
+            variant="soft"
+            size="large"
+            icon={<IconBookmark />}
+            label="Large"
+            id="3"
+          />
+        </Inline>
       ),
     },
     {
@@ -82,25 +98,29 @@ export const screenshots: ComponentScreenshot = {
       label: 'Transparent',
       background: 'surface',
       Example: () => (
-        <ButtonIcon
-          variant="transparent"
-          icon={<IconBookmark />}
-          label="Bookmark"
-          id="1"
-        />
-      ),
-    },
-    {
-      label: 'Transparent - large',
-      background: 'surface',
-      Example: () => (
-        <ButtonIcon
-          variant="transparent"
-          size="large"
-          icon={<IconBookmark />}
-          label="Bookmark"
-          id="1"
-        />
+        <Inline space="large" alignY="center">
+          <ButtonIcon
+            variant="transparent"
+            size="small"
+            icon={<IconBookmark />}
+            label="Small"
+            id="1"
+          />
+          <ButtonIcon
+            variant="transparent"
+            size="standard"
+            icon={<IconBookmark />}
+            label="Standard"
+            id="2"
+          />
+          <ButtonIcon
+            variant="transparent"
+            size="large"
+            icon={<IconBookmark />}
+            label="Large"
+            id="3"
+          />
+        </Inline>
       ),
     },
     {
@@ -122,32 +142,48 @@ export const screenshots: ComponentScreenshot = {
         <Stack space="large" data={{ [debugTouchableAttrForDataProp]: '' }}>
           <Inline space="large">
             <ButtonIcon
+              variant="soft"
               icon={<IconBookmark />}
               label="Bookmark"
-              size="standard"
+              size="small"
               id="1"
             />
             <ButtonIcon
+              variant="soft"
               icon={<IconBookmark />}
               label="Bookmark"
-              size="large"
+              size="standard"
               id="2"
             />
+            <ButtonIcon
+              variant="soft"
+              icon={<IconBookmark />}
+              label="Bookmark"
+              size="large"
+              id="3"
+            />
           </Inline>
           <Inline space="large">
             <ButtonIcon
+              variant="transparent"
               icon={<IconBookmark />}
               label="Bookmark"
-              size="standard"
+              size="small"
+              id="4"
+            />
+            <ButtonIcon
               variant="transparent"
-              id="3"
+              icon={<IconBookmark />}
+              label="Bookmark"
+              size="standard"
+              id="5"
             />
             <ButtonIcon
+              variant="transparent"
               icon={<IconBookmark />}
               label="Bookmark"
               size="large"
-              variant="transparent"
-              id="4"
+              id="6"
             />
           </Inline>
         </Stack>
diff --git a/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.snippets.tsx b/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.snippets.tsx
index ace34b350a3..8c505b7be10 100644
--- a/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.snippets.tsx
+++ b/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.snippets.tsx
@@ -32,6 +32,17 @@ export const snippets: Snippets = [
       />,
     ),
   },
+  {
+    name: 'Small',
+    code: source(
+      <ButtonIcon
+        size="small"
+        icon={<IconAdd />}
+        label="Add"
+        id="buttonicon-small"
+      />,
+    ),
+  },
   {
     name: 'Large',
     code: source(
diff --git a/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.tsx b/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.tsx
index e18788c77ec..fcfc782cba2 100644
--- a/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.tsx
+++ b/packages/braid-design-system/src/lib/components/ButtonIcon/ButtonIcon.tsx
@@ -22,6 +22,7 @@ import {
 import { Text } from '../Text/Text';
 import { Bleed } from '../Bleed/Bleed';
 import { TooltipRenderer } from '../TooltipRenderer/TooltipRenderer';
+import type { Space } from '../../css/atoms/atoms';
 import * as styles from './ButtonIcon.css';
 
 export const buttonIconVariants: Array<
@@ -29,13 +30,15 @@ export const buttonIconVariants: Array<
 > = ['soft', 'transparent'];
 
 export const buttonIconTones = ['neutral', 'secondary'] as const;
+export const buttonIconSizes = ['small', 'standard', 'large'] as const;
 
+type ButtonIconSize = (typeof buttonIconSizes)[number];
 type NativeButtonProps = AllHTMLAttributes<HTMLButtonElement>;
 export interface ButtonIconProps {
   id: string;
   icon: ReactElement<UseIconProps>;
   label: string;
-  size?: 'standard' | 'large';
+  size?: ButtonIconSize;
   tone?: (typeof buttonIconTones)[number];
   type?: 'button' | 'submit' | 'reset';
   variant?: (typeof buttonIconVariants)[number];
@@ -51,7 +54,11 @@ export interface ButtonIconProps {
   tooltipPlacement?: 'bottom' | 'top';
 }
 
-const padding = 'xsmall';
+const padding: Record<ButtonIconSize, Space> = {
+  small: 'xxsmall',
+  standard: 'xsmall',
+  large: 'xsmall',
+};
 
 const PrivateButtonIcon = forwardRef<
   HTMLButtonElement,
@@ -87,12 +94,12 @@ const PrivateButtonIcon = forwardRef<
     } = useButtonStyles({
       variant,
       tone: 'neutral',
-      size: 'standard',
+      size: size === 'small' ? 'small' : 'standard',
       radius: 'full',
     });
 
     assert(
-      icon.props.size === undefined,
+      icon && icon.props.size === undefined,
       "Icons cannot set the 'size' prop when passed to a ButtonIcon component",
     );
 
@@ -109,7 +116,7 @@ const PrivateButtonIcon = forwardRef<
         aria-label={label}
         aria-haspopup={ariaHasPopUp}
         aria-expanded={ariaExpanded}
-        padding={padding}
+        padding={padding[size]}
         onClick={onClick}
         onKeyUp={onKeyUp}
         onKeyDown={onKeyDown}
@@ -132,7 +139,9 @@ const PrivateButtonIcon = forwardRef<
           display="block"
           position="relative"
           className={
-            size === 'large' ? iconContainerSize() : iconSize({ crop: true })
+            size === 'large'
+              ? iconContainerSize()
+              : iconSize({ size, crop: true })
           }
         >
           {cloneElement(icon, { tone: icon.props.tone || tone, size: 'fill' })}
@@ -143,7 +152,7 @@ const PrivateButtonIcon = forwardRef<
     const shouldBleed =
       (typeof bleed === 'undefined' && variant === 'transparent') || bleed;
 
-    return shouldBleed ? <Bleed space={padding}>{button}</Bleed> : button;
+    return shouldBleed ? <Bleed space={padding[size]}>{button}</Bleed> : button;
   },
 );
 
diff --git a/packages/braid-design-system/src/lib/components/private/FieldButtonIcon/FieldButtonIcon.tsx b/packages/braid-design-system/src/lib/components/private/FieldButtonIcon/FieldButtonIcon.tsx
index 673e59de6c8..a6b94c20661 100644
--- a/packages/braid-design-system/src/lib/components/private/FieldButtonIcon/FieldButtonIcon.tsx
+++ b/packages/braid-design-system/src/lib/components/private/FieldButtonIcon/FieldButtonIcon.tsx
@@ -34,6 +34,7 @@ export const FieldButtonIcon = forwardRef<HTMLButtonElement, ButtonIconProps>(
         label={label}
         tone="secondary"
         variant="transparent"
+        size="small"
         onClick={onClick}
         onMouseDown={handleMouseDown}
         tabIndex={-1}
diff --git a/packages/generate-component-docs/src/__snapshots__/contract.test.ts.snap b/packages/generate-component-docs/src/__snapshots__/contract.test.ts.snap
index c8416c93c1d..37d62867d78 100644
--- a/packages/generate-component-docs/src/__snapshots__/contract.test.ts.snap
+++ b/packages/generate-component-docs/src/__snapshots__/contract.test.ts.snap
@@ -2114,6 +2114,7 @@ exports[`ButtonIcon 1`] = `
         | RefObject<HTMLButtonElement>
     size?: 
         | "large"
+        | "small"
         | "standard"
     tabIndex?: number
     tone?: