feat(ui-shell): HeaderAction supports tooltip (#2111)

Closes #2110

COMPONENT_INDEX.md

@@ -1617,12 +1617,14 @@ None.
 ### Props
 
 | Prop name                  | Required | Kind             | Reactive | Type                                                              | Default value                  | Description                                                                                                                                 |
-| :------------------------- | :------- | :--------------- | :------- | ----------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| :------------------------- | :------- | :--------------- | :------- | ----------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
 | ref                        | No       | <code>let</code> | Yes      | <code>null &#124; HTMLButtonElement</code>                        | <code>null</code>              | Obtain a reference to the button HTML element                                                                                               |
 | isOpen                     | No       | <code>let</code> | Yes      | <code>boolean</code>                                              | <code>false</code>             | Set to `true` to open the panel                                                                                                             |
 | icon                       | No       | <code>let</code> | No       | <code>any</code>                                                  | <code>undefined</code>         | Specify the icon to render when the action panel is closed.<br />Defaults to `&lt;Switcher size={20} /&gt;`                                 |
 | closeIcon                  | No       | <code>let</code> | No       | <code>any</code>                                                  | <code>undefined</code>         | Specify the icon to render when the action panel is open.<br />Defaults to `&lt;Close size={20} /&gt;`                                      |
-| text                       | No       | <code>let</code> | No       | <code>string</code>                                               | <code>undefined</code>         | Specify the text.<br />Alternatively, use the named slot "text" (e.g., `&lt;div slot="text"&gt;...&lt;/div&gt;`) |
+| text                       | No       | <code>let</code> | No       | <code>string</code>                                               | <code>undefined</code>         | Specify the text displayed next to the icon.<br />Alternatively, use the named slot "text" (e.g., `&lt;div slot="text"&gt;...&lt;/div&gt;`) |
+| iconDescription            | No       | <code>let</code> | No       | <code>string</code>                                               | <code>undefined</code>         | Specify an icon tooltip. The tooltip will not be displayed<br />if either the `text` prop or a named slot="text" is used                    |
+| tooltipAlignment           | No       | <code>let</code> | No       | <code>"start" &#124; "center" &#124; "end"</code>                 | <code>"center"</code>          | Set the alignment of the tooltip relative to the icon.<br />Only applies when `iconDescription` is provided                                 |
 | transition                 | No       | <code>let</code> | No       | <code>false &#124; import("svelte/transition").SlideParams</code> | <code>{ duration: 200 }</code> | Customize the panel transition (i.e., `transition:slide`).<br />Set to `false` to disable the transition                                    |
 | preventCloseOnClickOutside | No       | <code>let</code> | No       | <code>boolean</code>                                              | <code>false</code>             | Set to `true` to prevent the panel from closing when clicking outside                                                                       |
 

docs/src/COMPONENT_API.json

@@ -5882,7 +5882,7 @@
         {
           "name": "text",
           "kind": "let",
-          "description": "Specify the text.\nAlternatively, use the named slot \"text\" (e.g., `<div slot=\"text\">...</div>`)",
+          "description": "Specify the text displayed next to the icon.\nAlternatively, use the named slot \"text\" (e.g., `<div slot=\"text\">...</div>`)",
           "type": "string",
           "isFunction": false,
           "isFunctionDeclaration": false,
@@ -5890,6 +5890,29 @@
           "constant": false,
           "reactive": false
         },
+        {
+          "name": "iconDescription",
+          "kind": "let",
+          "description": "Specify an icon tooltip. The tooltip will not be displayed\nif either the `text` prop or a named slot=\"text\" is used",
+          "type": "string",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": false
+        },
+        {
+          "name": "tooltipAlignment",
+          "kind": "let",
+          "description": "Set the alignment of the tooltip relative to the icon.\nOnly applies when `iconDescription` is provided",
+          "type": "\"start\" | \"center\" | \"end\"",
+          "value": "\"center\"",
+          "isFunction": false,
+          "isFunctionDeclaration": false,
+          "isRequired": false,
+          "constant": false,
+          "reactive": false
+        },
         {
           "name": "ref",
           "kind": "let",

src/UIShell/HeaderAction.svelte

@@ -22,12 +22,26 @@
   export let closeIcon = Close;
 
   /**
-   * Specify the text.
+   * Specify the text displayed next to the icon.
    * Alternatively, use the named slot "text" (e.g., `<div slot="text">...</div>`)
    * @type {string}
    */
   export let text = undefined;
 
+  /**
+   * Specify an icon tooltip. The tooltip will not be displayed
+   * if either the `text` prop or a named slot="text" is used
+   * @type {string}
+   */
+  export let iconDescription = undefined;
+
+  /**
+   * Set the alignment of the tooltip relative to the icon.
+   * Only applies when `iconDescription` is provided
+   * @type {"start" | "center" | "end"}
+   */
+  export let tooltipAlignment = "center";
+
   /** Obtain a reference to the button HTML element */
   export let ref = null;
 
@@ -49,6 +63,17 @@
   const dispatch = createEventDispatcher();
 
   let refPanel = null;
+
+  $: hasIconOnly = iconDescription && !(text || $$slots.text);
+  $: buttonClass = [
+    hasIconOnly && "bx--btn bx--btn--primary",
+    hasIconOnly && "bx--tooltip__trigger bx--tooltip--a11y",
+    hasIconOnly && "bx--btn--icon-only bx--btn--icon-only--bottom",
+    hasIconOnly && `bx--tooltip--align-${tooltipAlignment}`,
+    $$restProps.class,
+  ]
+    .filter(Boolean)
+    .join(" ");
 </script>
 
 <svelte:window
@@ -72,12 +97,16 @@
   class:bx--header__action--active={isOpen}
   class:bx--header__action--text={text}
   {...$$restProps}
+  class={buttonClass}
   on:click
   on:click|stopPropagation={() => {
     isOpen = !isOpen;
     dispatch(isOpen ? "open" : "close");
   }}
 >
+  {#if hasIconOnly}
+    <span class:bx--assistive-text={true}>{iconDescription}</span>
+  {/if}
   {#if isOpen}
     <slot name="closeIcon">
       <svelte:component this={closeIcon} size={20} />

tests/HeaderUtilities.test.svelte

@@ -35,6 +35,8 @@
       bind:isOpen
       on:open
       on:close
+      iconDescription="Switcher"
+      tooltipAlignment="start"
       transition={{ duration: 400, easing: quintOut }}
     >
       <HeaderPanelLinks>

types/UIShell/HeaderAction.svelte.d.ts

@@ -25,12 +25,26 @@ type $Props = {
   closeIcon?: any;
 
   /**
-   * Specify the text.
+   * Specify the text displayed next to the icon.
    * Alternatively, use the named slot "text" (e.g., `<div slot="text">...</div>`)
    * @default undefined
    */
   text?: string;
 
+  /**
+   * Specify an icon tooltip. The tooltip will not be displayed
+   * if either the `text` prop or a named slot="text" is used
+   * @default undefined
+   */
+  iconDescription?: string;
+
+  /**
+   * Set the alignment of the tooltip relative to the icon.
+   * Only applies when `iconDescription` is provided
+   * @default "center"
+   */
+  tooltipAlignment?: "start" | "center" | "end";
+
   /**
    * Obtain a reference to the button HTML element
    * @default null