feat: Add Inline label text to multiselect (#3737)

Author: mariksav

pages/multiselect/inline-label-text-permutations.page.tsx

@@ -0,0 +1,42 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+
+import Multiselect, { MultiselectProps } from '~components/multiselect';
+
+import createPermutations from '../utils/permutations';
+import PermutationsView from '../utils/permutations-view';
+import ScreenshotArea from '../utils/screenshot-area';
+import { deselectAriaLabel, i18nStrings } from './constants';
+
+const options: MultiselectProps.Options = [
+  { value: 'first', label: 'Simple' },
+  { value: 'second', label: 'Second option' },
+];
+
+const permutations = createPermutations<MultiselectProps>([
+  {
+    placeholder: ['Select an item'],
+    disabled: [false, true],
+    options: [options],
+    selectedOptions: [[], [options[0], options[1]]],
+    deselectAriaLabel: [deselectAriaLabel],
+    i18nStrings: [i18nStrings],
+    inlineLabelText: [
+      'Inline label',
+      'Very long inline label that should wrap into multiple lines on narrow enough viewports',
+    ],
+    inlineTokens: [undefined, true],
+  },
+]);
+
+export default function MultiselectInlineLabelTextPermutations() {
+  return (
+    <>
+      <h1>Multiselect inlineLabelText permutations</h1>
+      <ScreenshotArea>
+        <PermutationsView permutations={permutations} render={permutation => <Multiselect {...permutation} />} />
+      </ScreenshotArea>
+    </>
+  );
+}

src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap

@@ -16468,6 +16468,12 @@ use the \`id\` attribute, consider setting it on a parent element instead.",
       "optional": true,
       "type": "string",
     },
+    {
+      "description": "Specifies an inline label that appears next to the multiselect trigger.",
+      "name": "inlineLabelText",
+      "optional": true,
+      "type": "string",
+    },
     {
       "description": "Shows tokens inside the trigger instead of below it.",
       "name": "inlineTokens",
@@ -74560,6 +74566,14 @@ Component's wrapper class",
             "type": "union",
           },
         },
+        {
+          "name": "findInlineLabel",
+          "parameters": [],
+          "returnType": {
+            "name": "ElementWrapper | null",
+            "type": "union",
+          },
+        },
         {
           "name": "findPlaceholder",
           "parameters": [],
@@ -132505,6 +132519,15 @@ Component's wrapper class",
             "typeArguments": [],
           },
         },
+        {
+          "name": "findInlineLabel",
+          "parameters": [],
+          "returnType": {
+            "name": "ElementWrapper",
+            "type": "reference",
+            "typeArguments": [],
+          },
+        },
         {
           "name": "findPlaceholder",
           "parameters": [],

src/multiselect/__tests__/multiselect.test.tsx

@@ -155,6 +155,30 @@ test('does not render tokens when no tokens are present', () => {
   expect(wrapper.findTokens()).toHaveLength(0);
 });
 
+test('renders inline label text when provided', () => {
+  const { wrapper } = renderMultiselect(
+    <Multiselect selectedOptions={[]} options={defaultOptions} inlineLabelText="Select items:" />
+  );
+  const inlineLabel = wrapper.findInlineLabel();
+  expect(inlineLabel).not.toBeNull();
+  expect(inlineLabel!.getElement()).toHaveTextContent('Select items:');
+});
+
+test('does not render inline label when inlineLabelText is not provided', () => {
+  const { wrapper } = renderMultiselect(<Multiselect selectedOptions={[]} options={defaultOptions} />);
+  const inlineLabel = wrapper.findInlineLabel();
+  expect(inlineLabel).toBeNull();
+});
+
+test('associate label with trigger button', () => {
+  const { wrapper } = renderMultiselect(
+    <Multiselect selectedOptions={[]} options={defaultOptions} inlineLabelText="Select items:" />
+  );
+  const labelForAttribute = wrapper.findInlineLabel()!.getElement()!.getAttribute('for');
+  const triggerId = wrapper.findTrigger().getElement()!.id;
+  expect(labelForAttribute).toBe(triggerId);
+});
+
 test('allows deselecting an option without object equality', () => {
   const onChange = jest.fn();
   const { wrapper } = renderMultiselect(

src/multiselect/interfaces.ts

@@ -10,6 +10,10 @@ export interface MultiselectProps extends BaseSelectProps {
    * Provide an empty array to clear the selection.
    */
   selectedOptions: ReadonlyArray<MultiselectProps.Option>;
+  /**
+   * Specifies an inline label that appears next to the multiselect trigger.
+   */
+  inlineLabelText?: string;
   /**
    * Determines whether the dropdown list stays open after the user selects an item.
    */

src/multiselect/internal.tsx

@@ -46,6 +46,7 @@ const InternalMultiselect = React.forwardRef(
       disabled,
       readOnly,
       ariaLabel,
+      inlineLabelText,
       selectedOptions,
       deselectAriaLabel,
       tokenLimit,
@@ -112,6 +113,7 @@ const InternalMultiselect = React.forwardRef(
         selectedOptions={selectedOptions}
         triggerVariant={inlineTokens ? 'tokens' : 'placeholder'}
         isOpen={multiselectProps.isOpen}
+        inlineLabelText={inlineLabelText}
         {...formFieldContext}
         controlId={controlId}
         ariaLabelledby={joinStrings(formFieldContext.ariaLabelledby, ariaLabelId)}
@@ -207,7 +209,7 @@ const InternalMultiselect = React.forwardRef(
           />
         )}
 
-        <ScreenreaderOnly id={ariaLabelId}>{ariaLabel}</ScreenreaderOnly>
+        <ScreenreaderOnly id={ariaLabelId}>{ariaLabel || inlineLabelText}</ScreenreaderOnly>
       </div>
     );
   }

src/select/parts/styles.scss

@@ -153,6 +153,12 @@ $inlineLabel-border-radius: 2px;
   z-index: 1;
 }
 
+// Specific Styling for Inline Label Text to not overlap with Inline Tokens
+.inline-label-inline-tokens {
+  padding-block-end: 0;
+  transform: translateY(-1.5px);
+}
+
 .disabled-reason-tooltip {
   /* used in test-utils or tests */
 }

src/select/parts/trigger.tsx

@@ -129,7 +129,13 @@ const Trigger = React.forwardRef(
       <>
         {inlineLabelText ? (
           <div className={styles['inline-label-wrapper']}>
-            <label htmlFor={controlId} className={styles['inline-label']}>
+            <label
+              htmlFor={controlId}
+              className={clsx(
+                styles['inline-label'],
+                triggerVariant === 'tokens' && styles['inline-label-inline-tokens']
+              )}
+            >
               {inlineLabelText}
             </label>
             <div className={styles['inline-label-trigger-wrapper']}>{triggerButton}</div>

src/test-utils/dom/multiselect/index.ts

@@ -12,6 +12,7 @@ import buttonTriggerStyles from '../../../internal/components/button-trigger/sty
 import dropdownStatusStyles from '../../../internal/components/dropdown-status/styles.selectors.js';
 import footerStyles from '../../../internal/components/dropdown-status/styles.selectors.js';
 import multiselectStyles from '../../../multiselect/styles.selectors.js';
+import selectPartsStyles from '../../../select/parts/styles.selectors.js';
 import tokenGroupStyles from '../../../token-group/styles.selectors.js';
 
 export default class MultiselectWrapper extends DropdownHostComponentWrapper {
@@ -38,6 +39,10 @@ export default class MultiselectWrapper extends DropdownHostComponentWrapper {
     return this.findByClassName(buttonTriggerStyles.placeholder);
   }
 
+  findInlineLabel(): ElementWrapper | null {
+    return this.findByClassName(selectPartsStyles['inline-label']);
+  }
+
   /**
    * @param options
    * * expandToViewport (boolean) - Use this when the component under test is rendered with an `expandToViewport` flag.