From e7dc3575d1086a5992543c84d0507a84666d6e32 Mon Sep 17 00:00:00 2001
From: Laura Benz <48948963+L-M-K-B@users.noreply.github.com>
Date: Mon, 15 May 2023 13:57:18 +0200
Subject: [PATCH] Design System: Refactor IconButton and update documentation
 (#66774)

* refactor: remove unnecessary styling and adjust to button styling

* refactor: improve story

* refactor: use new default styling for border radius

* refactor: add missing pseudo classes and clean up

* refactor: repair disabled styling and add to story

* refactor: clean up and apply styles defined in figma

* refactor: set hover background in a pseudo-element

* refactor: unify large sizes

* refactor: add information for further use

* refactor: add comment

* refactor: comments and clean up import

* refactor: add changes after code review

* refactor: replace some bad example code in documentation

* refactor: update comment

Co-authored-by: Joao Silva <100691367+JoaoSilvaGrafana@users.noreply.github.com>

* refactor: add changes requested in review

* refactor: move deprecation warning

* refactor: replace padding

* refactor: remove local styling

* refactor: create separate stories for different examples

* refactor: change style of story

* refactor: replace absolute value by variable

* Update toggles_gen.go

---------

Co-authored-by: Joao Silva <100691367+JoaoSilvaGrafana@users.noreply.github.com>
---
 .../src/components/Button/Button.mdx          |   7 +
 .../src/components/Button/Button.story.tsx    |   8 +-
 .../src/components/Button/Button.tsx          |   5 +-
 .../src/components/IconButton/IconButton.mdx  |  14 +-
 .../IconButton/IconButton.story.tsx           | 121 +++++++++++++-----
 .../src/components/IconButton/IconButton.tsx  |  82 ++++++------
 .../components/PanelChrome/PanelChrome.mdx    |  38 ++++--
 .../src/components/Toggletip/Toggletip.mdx    |   4 +-
 .../unified/components/DynamicTable.tsx       |   7 +-
 9 files changed, 176 insertions(+), 110 deletions(-)

diff --git a/packages/grafana-ui/src/components/Button/Button.mdx b/packages/grafana-ui/src/components/Button/Button.mdx
index e4e64d11380..cce79cbf3bd 100644
--- a/packages/grafana-ui/src/components/Button/Button.mdx
+++ b/packages/grafana-ui/src/components/Button/Button.mdx
@@ -1,10 +1,17 @@
 import { Meta, Preview, ArgTypes } from '@storybook/blocks';
 import { Button, LinkButton } from './Button';
+import { Alert } from '../Alert/Alert';
 
 <Meta title="MDX|Button" component={Button} />
 
 # Button
 
+<Alert severity="warning" title={'Please note:'}>
+  After reviewing this component we are asking you to use the IconButton when you require a button with only an icon.
+</Alert>
+
+When using a button please always follow a11y rules (e.g. W3C Recommendation [3.3.2 Labels or instructions](https://www.w3.org/TR/WCAG21/#labels-or-instructions)) and make sure the context in which the button is located is also communicated by screen readers.
+
 ## Primary
 
 Used for "call to action", i.e. triggering the main action. There should never be more than one on a page. If you need multiple buttons for different actions, decide which action is the most important and make that the primary `Button`. All other `Button` components should be secondary.
diff --git a/packages/grafana-ui/src/components/Button/Button.story.tsx b/packages/grafana-ui/src/components/Button/Button.story.tsx
index 336304028df..64e7362fb34 100644
--- a/packages/grafana-ui/src/components/Button/Button.story.tsx
+++ b/packages/grafana-ui/src/components/Button/Button.story.tsx
@@ -1,7 +1,7 @@
 import { StoryFn } from '@storybook/react';
 import React from 'react';
 
-import { ComponentSize } from '../../types/size';
+import { ComponentSize } from '../../types';
 import { withCenteredStory } from '../../utils/storybook/withCenteredStory';
 import { Card } from '../Card/Card';
 import { HorizontalGroup, VerticalGroup } from '../Layout/Layout';
@@ -69,12 +69,6 @@ export const Examples: StoryFn<typeof Button> = () => {
         </Button>
       </HorizontalGroup>
       <div />
-      <HorizontalGroup spacing="lg">
-        <div>With icon only</div>
-        <Button icon="cloud" size="sm" />
-        <Button icon="cloud" size="md" />
-        <Button icon="cloud" size="lg" />
-      </HorizontalGroup>
       <div />
       <Button icon="plus" fullWidth>
         Button with fullWidth
diff --git a/packages/grafana-ui/src/components/Button/Button.tsx b/packages/grafana-ui/src/components/Button/Button.tsx
index f9e0fa680ae..a90e029e14e 100644
--- a/packages/grafana-ui/src/components/Button/Button.tsx
+++ b/packages/grafana-ui/src/components/Button/Button.tsx
@@ -5,8 +5,8 @@ import { colorManipulator, GrafanaTheme2, ThemeRichColor } from '@grafana/data';
 
 import { useTheme2 } from '../../themes';
 import { getFocusStyles, getMouseFocusStyles } from '../../themes/mixins';
+import { ComponentSize } from '../../types';
 import { IconName } from '../../types/icon';
-import { ComponentSize } from '../../types/size';
 import { getPropertiesForButtonSize } from '../Forms/commonStyles';
 import { Icon } from '../Icon/Icon';
 import { PopoverContent, Tooltip, TooltipPlacement } from '../Tooltip';
@@ -60,6 +60,7 @@ export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
       iconOnly: !children,
     });
 
+    // In order to standardise Button please always consider using IconButton when you need a button with an icon only
     const button = (
       <button className={cx(styles.button, className)} type={type} {...otherProps} ref={ref}>
         {icon && <Icon name={icon} size={size} className={styles.icon} />}
@@ -175,7 +176,7 @@ export const getButtonStyles = (props: StyleProps) => {
       lineHeight: `${theme.spacing.gridSize * height - 2}px`,
       verticalAlign: 'middle',
       cursor: 'pointer',
-      borderRadius: theme.shape.borderRadius(1),
+      borderRadius: theme.shape.radius.default,
       '&:focus': focusStyle,
       '&:focus-visible': focusStyle,
       '&:focus:not(:focus-visible)': getMouseFocusStyles(theme),
diff --git a/packages/grafana-ui/src/components/IconButton/IconButton.mdx b/packages/grafana-ui/src/components/IconButton/IconButton.mdx
index 8321dbbdb11..cc6a022d1c4 100644
--- a/packages/grafana-ui/src/components/IconButton/IconButton.mdx
+++ b/packages/grafana-ui/src/components/IconButton/IconButton.mdx
@@ -1,12 +1,20 @@
-import { Meta, Story, Preview, ArgTypes } from '@storybook/blocks';
+import { Meta, ArgTypes } from '@storybook/blocks';
 import { IconButton } from './IconButton';
+import { Alert } from '../Alert/Alert';
 
 <Meta title="MDX|IconButton" component={IconButton} />
 
 # IconButton
 
-This component looks like just an icon but behaves like a button. It fulfils an action when you click it and has hover and focus states. You can choose which icon size you would like to use.
+This component looks just like an icon but behaves like a button. It fulfils an action when you click it and has hover and focus states. You can choose which icon size you would like to use.
 
-`IconButton` is best used when an actual button would look out of place, for example when you want to place a solitary clickable icon next to text. An example where an `IconButton` is used in Grafana is the top left back arrow in the panel edit mode.
+`IconButton` is best used when you only want an icon instead of a button with text, for example when you want to place a solitary clickable icon next to text. An example where an `IconButton` is used in Grafana is the hamburger icon at the top left which opens the new navigation.
+
+Always keep in mind to add text for a tooltip and an aria label.
+
+<Alert severity="warning" title={'Please note:'}>
+  After reviewing this component we would like you to know that there are only 5 sizes available (sizes xs to xl). Sizes
+  xxl and xxxl are now shown in size xl as well and will be deprecated in the future.
+</Alert>
 
 <ArgTypes of={IconButton} />
diff --git a/packages/grafana-ui/src/components/IconButton/IconButton.story.tsx b/packages/grafana-ui/src/components/IconButton/IconButton.story.tsx
index 4af1e6dd8dc..8f5e3d40e97 100644
--- a/packages/grafana-ui/src/components/IconButton/IconButton.story.tsx
+++ b/packages/grafana-ui/src/components/IconButton/IconButton.story.tsx
@@ -5,11 +5,15 @@ import React from 'react';
 import { useTheme2 } from '../../themes';
 import { IconSize, IconName } from '../../types';
 import { withCenteredStory } from '../../utils/storybook/withCenteredStory';
-import { VerticalGroup } from '../Layout/Layout';
+import { HorizontalGroup, VerticalGroup } from '../Layout/Layout';
 
 import { IconButton, IconButtonVariant, Props as IconButtonProps } from './IconButton';
 import mdx from './IconButton.mdx';
 
+interface ScenarioProps {
+  background: 'canvas' | 'primary' | 'secondary';
+}
+
 const meta: Meta<typeof IconButton> = {
   title: 'Buttons/IconButton',
   component: IconButton,
@@ -35,29 +39,84 @@ const meta: Meta<typeof IconButton> = {
   },
 };
 
-export const Examples = () => {
-  return (
-    <div>
-      <RenderScenario background="canvas" />
-      <RenderScenario background="primary" />
-      <RenderScenario background="secondary" />
-    </div>
-  );
-};
-
 export const Basic: StoryFn<typeof IconButton> = (args: IconButtonProps) => {
   return <IconButton {...args} />;
 };
 
-interface ScenarioProps {
-  background: 'canvas' | 'primary' | 'secondary';
-}
-
-const RenderScenario = ({ background }: ScenarioProps) => {
-  const theme = useTheme2();
-  const sizes: IconSize[] = ['sm', 'md', 'lg', 'xl', 'xxl'];
+export const ExamplesSizes = () => {
+  const sizes: IconSize[] = ['xs', 'sm', 'md', 'lg', 'xl'];
   const icons: IconName[] = ['search', 'trash-alt', 'arrow-left', 'times'];
-  const variants: IconButtonVariant[] = ['secondary', 'primary', 'destructive'];
+  const variants: IconButtonVariant[] = ['primary', 'secondary', 'destructive'];
+
+  return (
+    <div
+      className={css`
+        button {
+          margin-right: 8px;
+          margin-left: 8px;
+          margin-bottom: 20px;
+        }
+      `}
+    >
+      <HorizontalGroup spacing="md">
+        {variants.map((variant) => {
+          return (
+            <div key={variant}>
+              <p>{variant}</p>
+              {icons.map((icon) => {
+                return (
+                  <div
+                    className={css`
+                      display: flex;
+                    `}
+                    key={icon}
+                  >
+                    {sizes.map((size) => (
+                      <span key={icon + size}>
+                        <IconButton name={icon} size={size} variant={variant} />
+                      </span>
+                    ))}
+                  </div>
+                );
+              })}
+            </div>
+          );
+        })}
+        <div>
+          <p>disabled</p>
+          {icons.map((icon) => (
+            <div
+              className={css`
+                display: flex;
+              `}
+              key={icon}
+            >
+              {sizes.map((size) => (
+                <span key={icon + size}>
+                  <IconButton name={icon} size={size} disabled />
+                </span>
+              ))}
+            </div>
+          ))}
+        </div>
+      </HorizontalGroup>
+    </div>
+  );
+};
+
+export const ExamplesBackground = () => {
+  return (
+    <div>
+      <RenderBackgroundScenario background="canvas" />
+      <RenderBackgroundScenario background="primary" />
+      <RenderBackgroundScenario background="secondary" />
+    </div>
+  );
+};
+
+const RenderBackgroundScenario = ({ background }: ScenarioProps) => {
+  const theme = useTheme2();
+  const variants: IconButtonVariant[] = ['primary', 'secondary', 'destructive'];
 
   return (
     <div
@@ -67,25 +126,21 @@ const RenderScenario = ({ background }: ScenarioProps) => {
         button {
           margin-right: 8px;
           margin-left: 8px;
-          margin-bottom: 8px;
         }
       `}
     >
       <VerticalGroup spacing="md">
         <div>{background}</div>
-        {variants.map((variant) => {
-          return (
-            <div key={variant}>
-              {icons.map((icon) => {
-                return sizes.map((size) => (
-                  <span key={icon + size}>
-                    <IconButton name={icon} size={size} variant={variant} />
-                  </span>
-                ));
-              })}
-            </div>
-          );
-        })}
+        <div
+          className={css`
+            display: flex;
+          `}
+        >
+          {variants.map((variant) => {
+            return <IconButton name="times" size="xl" variant={variant} key={variant} />;
+          })}
+          <IconButton name="times" size="xl" disabled />
+        </div>
       </VerticalGroup>
     </div>
   );
diff --git a/packages/grafana-ui/src/components/IconButton/IconButton.tsx b/packages/grafana-ui/src/components/IconButton/IconButton.tsx
index 2eeb1e604d3..a4c1b846c60 100644
--- a/packages/grafana-ui/src/components/IconButton/IconButton.tsx
+++ b/packages/grafana-ui/src/components/IconButton/IconButton.tsx
@@ -1,11 +1,11 @@
 import { css, cx } from '@emotion/css';
 import React from 'react';
 
-import { GrafanaTheme2, colorManipulator } from '@grafana/data';
+import { GrafanaTheme2, colorManipulator, deprecationWarning } from '@grafana/data';
 
-import { useTheme2 } from '../../themes/ThemeContext';
+import { useTheme2, stylesFactory } from '../../themes';
 import { getFocusStyles, getMouseFocusStyles } from '../../themes/mixins';
-import { stylesFactory } from '../../themes/stylesFactory';
+import { ComponentSize } from '../../types';
 import { IconName, IconSize, IconType } from '../../types/icon';
 import { Icon } from '../Icon/Icon';
 import { getSvgSize } from '../Icon/utils';
@@ -13,10 +13,12 @@ import { TooltipPlacement, PopoverContent, Tooltip } from '../Tooltip';
 
 export type IconButtonVariant = 'primary' | 'secondary' | 'destructive';
 
+type LimitedIconSize = ComponentSize | 'xl';
+
 export interface Props extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   /** Name of the icon **/
   name: IconName;
-  /** Icon size */
+  /** Icon size - sizes xxl and xxxl are deprecated and when used being decreased to xl*/
   size?: IconSize;
   /** Type of the icon - mono or default */
   iconType?: IconType;
@@ -46,12 +48,22 @@ export const IconButton = React.forwardRef<HTMLButtonElement, Props>(
     ref
   ) => {
     const theme = useTheme2();
-    const styles = getStyles(theme, size, variant);
+    let limitedIconSize: LimitedIconSize;
+
+    // very large icons (xl to xxxl) are unified to size xl
+    if (size === 'xxl' || size === 'xxxl') {
+      deprecationWarning('IconButton', 'size="xxl" and size="xxxl"', 'size="xl"');
+      limitedIconSize = 'xl';
+    } else {
+      limitedIconSize = size;
+    }
+
+    const styles = getStyles(theme, limitedIconSize, variant);
     const tooltipString = typeof tooltip === 'string' ? tooltip : '';
 
     const button = (
       <button ref={ref} aria-label={ariaLabel || tooltipString} {...restProps} className={cx(styles.button, className)}>
-        <Icon name={name} size={size} className={styles.icon} type={iconType} />
+        <Icon name={name} size={limitedIconSize} className={styles.icon} type={iconType} />
       </button>
     );
 
@@ -69,9 +81,11 @@ export const IconButton = React.forwardRef<HTMLButtonElement, Props>(
 
 IconButton.displayName = 'IconButton';
 
-const getStyles = stylesFactory((theme: GrafanaTheme2, size: IconSize, variant: IconButtonVariant) => {
-  const pixelSize = getSvgSize(size);
-  const hoverSize = Math.max(pixelSize / 3, 8);
+const getStyles = stylesFactory((theme: GrafanaTheme2, size, variant: IconButtonVariant) => {
+  // overall size of the IconButton on hover
+  // theme.spacing.gridSize originates from 2*4px for padding and letting the IconSize generally decide on the hoverSize
+  const hoverSize = getSvgSize(size) + theme.spacing.gridSize;
+
   let iconColor = theme.colors.text.primary;
 
   if (variant === 'primary') {
@@ -82,47 +96,34 @@ const getStyles = stylesFactory((theme: GrafanaTheme2, size: IconSize, variant:
 
   return {
     button: css`
-      width: ${pixelSize}px;
-      height: ${pixelSize}px;
-      background: transparent;
-      border: none;
-      color: ${iconColor};
-      padding: 0;
-      margin: 0;
-      outline: none;
-      box-shadow: none;
-      display: inline-flex;
-      align-items: center;
-      justify-content: center;
-      position: relative;
-      border-radius: ${theme.shape.borderRadius()};
       z-index: 0;
-      margin-right: ${theme.spacing(0.5)};
+      position: relative;
+      margin: 0 ${theme.spacing(0.5)} 0 0;
+      box-shadow: none;
+      border: none;
+      display: inline-flex;
+      background: transparent;
+      justify-content: center;
+      align-items: center;
+      padding: 0;
+      color: ${iconColor};
 
       &[disabled],
       &:disabled {
         cursor: not-allowed;
         color: ${theme.colors.action.disabledText};
         opacity: 0.65;
-        box-shadow: none;
       }
 
       &:before {
-        content: '';
-        display: block;
-        opacity: 1;
+        z-index: -1;
         position: absolute;
+        width: ${hoverSize}px;
+        height: ${hoverSize}px;
+        border-radius: ${theme.shape.radius.default};
+        content: '';
         transition-duration: 0.2s;
         transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
-        z-index: -1;
-        bottom: -${hoverSize}px;
-        left: -${hoverSize}px;
-        right: -${hoverSize}px;
-        top: -${hoverSize}px;
-        background: none;
-        border-radius: 50%;
-        box-sizing: border-box;
-        transform: scale(0);
         transition-property: transform, opacity;
       }
 
@@ -136,22 +137,15 @@ const getStyles = stylesFactory((theme: GrafanaTheme2, size: IconSize, variant:
       }
 
       &:hover {
-        color: ${iconColor};
-
         &:before {
           background-color: ${variant === 'secondary'
             ? theme.colors.action.hover
             : colorManipulator.alpha(iconColor, 0.12)};
-          border: none;
-          box-shadow: none;
-          opacity: 1;
-          transform: scale(0.8);
         }
       }
     `,
     icon: css`
       vertical-align: baseline;
-      display: flex;
     `,
   };
 });
diff --git a/packages/grafana-ui/src/components/PanelChrome/PanelChrome.mdx b/packages/grafana-ui/src/components/PanelChrome/PanelChrome.mdx
index ad804c4c65e..b06139a6bd6 100644
--- a/packages/grafana-ui/src/components/PanelChrome/PanelChrome.mdx
+++ b/packages/grafana-ui/src/components/PanelChrome/PanelChrome.mdx
@@ -1,13 +1,13 @@
-import { Meta, Preview, ArgTypes } from '@storybook/blocks';
+import { css } from '@emotion/css';
+import { Meta } from '@storybook/addon-docs/blocks';
 import { PanelChrome } from './PanelChrome';
-import { LoadingIndicator } from './LoadingIndicator';
 
 import { action } from '@storybook/addon-actions';
-import { DashboardStoryCanvas } from '../../utils/storybook/DashboardStoryCanvas';
 import { HorizontalGroup } from '../Layout/Layout';
 import { LoadingState } from '@grafana/data';
-import { Button } from '../Button/Button.tsx';
+import { Button } from '../Button';
 import { Menu } from '../Menu/Menu';
+import { IconButton } from '../IconButton/IconButton';
 
 <Meta title="MDX|PanelChrome" component={PanelChrome} />
 
@@ -306,10 +306,17 @@ Component used for rendering content wrapped in the same style as grafana panels
 <PanelChrome
   title="My awesome panel title"
   titleItems={
-    <div>
-      <Button fill="text" icon="github" variant="secondary" tooltip="extra content to render" />
-      <Button fill="text" icon="sliders-v-alt" variant="secondary" tooltip="extra content2 to render" />
-    </div>
+    <>
+      <IconButton
+        className={css`
+          margin-right: 10px;
+        `}
+        name="github"
+        variant="secondary"
+        tooltip="extra content to render"
+      />
+      <IconButton name="sliders-v-alt" variant="secondary" tooltip="extra content2 to render" />
+    </>
   }
   actions={
     <Button size="sm" variant="secondary" key="A">
@@ -342,10 +349,17 @@ Component used for rendering content wrapped in the same style as grafana panels
   <PanelChrome
     title="My awesome panel title"
     titleItems={
-      <div>
-        <Button fill="text" icon="github" variant="secondary" tooltip="extra content to render" />
-        <Button fill="text" icon="sliders-v-alt" variant="secondary" tooltip="extra content2 to render" />
-      </div>
+      <>
+        <IconButton
+          className={css`
+            margin-right: 10px;
+          `}
+          name="github"
+          variant="secondary"
+          tooltip="extra content to render"
+        />
+        <IconButton name="sliders-v-alt" variant="secondary" tooltip="extra content2 to render" />
+      </>
     }
     actions={
       <Button size="sm" variant="secondary" key="A">
diff --git a/packages/grafana-ui/src/components/Toggletip/Toggletip.mdx b/packages/grafana-ui/src/components/Toggletip/Toggletip.mdx
index 3ab45a47194..111569e56f7 100644
--- a/packages/grafana-ui/src/components/Toggletip/Toggletip.mdx
+++ b/packages/grafana-ui/src/components/Toggletip/Toggletip.mdx
@@ -71,9 +71,7 @@ return (
     closeButton={true}
     onClose={onClose}
   >
-    <Button type="button">
-      <Icon name="question-circle" />
-    </Button>
+    <IconButton name="question-circle" tooltip="IconButton containing a Toggletip" />
   </Toogletip>
 );
 ```
diff --git a/public/app/features/alerting/unified/components/DynamicTable.tsx b/public/app/features/alerting/unified/components/DynamicTable.tsx
index 29ee2eeac96..3e99d226239 100644
--- a/public/app/features/alerting/unified/components/DynamicTable.tsx
+++ b/public/app/features/alerting/unified/components/DynamicTable.tsx
@@ -125,9 +125,8 @@ export const DynamicTable = <T extends object>({
                 <div className={cx(styles.cell, styles.expandCell)}>
                   <IconButton
                     aria-label={`${isItemExpanded ? 'Collapse' : 'Expand'} row`}
-                    size="lg"
+                    size="md"
                     data-testid="collapse-toggle"
-                    className={styles.expandButton}
                     name={isItemExpanded ? 'angle-down' : 'angle-right'}
                     onClick={() => toggleExpanded(item)}
                     type="button"
@@ -278,9 +277,5 @@ const getStyles = <T extends unknown>(
         padding: ${theme.spacing(1)} 0 0 0;
       }
     `,
-    expandButton: css`
-      margin-right: 0;
-      display: block;
-    `,
   });
 };