HDS-5265: Adds a11y guardrails in Dropdown ToggleIcon component (#3087)

Co-authored-by: shleewhite <[email protected]>

Author: annawanggg

.changeset/deep-wings-arrive.md

@@ -0,0 +1,9 @@
+---
+"@hashicorp/design-system-components": major
+---
+
+<!-- START components/dropdown -->
+
+`Dropdown` - Added assertion to the `ToggleIcon` to provide improved developer guidance for the `hasChevron` attribute
+
+<!-- END -->

packages/components/src/components/hds/dropdown/toggle/icon.ts

@@ -7,7 +7,10 @@ import Component from '@glimmer/component';
 import { action } from '@ember/object';
 import { assert } from '@ember/debug';
 import { tracked } from '@glimmer/tracking';
-import { HdsDropdownToggleIconSizeValues } from './types.ts';
+import {
+  HdsDropdownToggleIconSizeValues,
+  HdsDropdownToggleIconAllowedIconValues,
+} from './types.ts';
 
 import type { HdsIconSignature } from '../../icon';
 import type { HdsDropdownToggleIconSizes } from './types';
@@ -20,6 +23,9 @@ export const SIZES: HdsDropdownToggleIconSizes[] = Object.values(
   HdsDropdownToggleIconSizeValues
 );
 
+export const ALLOWED_ICON_LIST: HdsIconSignature['Args']['name'][] =
+  Object.values(HdsDropdownToggleIconAllowedIconValues);
+
 export interface HdsDropdownToggleIconSignature {
   Args: {
     hasChevron?: boolean;
@@ -107,13 +113,25 @@ export default class HdsDropdownToggleIcon extends Component<HdsDropdownToggleIc
   }
 
   /**
-   * Indicates if a dropdown chevron icon should be displayed; should be displayed unless the "more-horizontal" icon is used.
+   * Indicates if a dropdown chevron icon should be displayed; should be displayed unless the "more-horizontal" or "more-vertical" icons are used.
    *
    * @param hasChevron
    * @type {boolean}
    * @default true
    */
   get hasChevron(): boolean {
+    if (
+      this.args.icon &&
+      !ALLOWED_ICON_LIST.includes(this.args.icon) &&
+      this.args.hasChevron === false
+    ) {
+      assert(
+        `@hasChevron for "Hds::Dropdown::Toggle::Icon" must be true unless the icon is one of the following: ${ALLOWED_ICON_LIST.join(
+          ', '
+        )}; received: ${this.args.icon}`
+      );
+    }
+
     return this.args.hasChevron ?? true;
   }
 

packages/components/src/components/hds/dropdown/toggle/types.ts

@@ -22,3 +22,10 @@ export enum HdsDropdownToggleButtonColorValues {
 }
 export type HdsDropdownToggleButtonColors =
   `${HdsDropdownToggleButtonColorValues}`;
+
+export enum HdsDropdownToggleIconAllowedIconValues {
+  MoreHorizontal = 'more-horizontal',
+  MoreVertical = 'more-vertical',
+}
+export type HdsDropdownToggleIconAllowedIcons =
+  `${HdsDropdownToggleIconAllowedIconValues}`;

showcase/tests/integration/components/hds/dropdown/toggle/icon-test.js

@@ -69,7 +69,7 @@ module('Integration | Component | hds/dropdown/toggle/icon', function (hooks) {
   });
   test('toggle-icon renders no chevron when hasChevron is set to false', async function (assert) {
     await render(
-      hbs`<Hds::Dropdown::Toggle::Icon @icon="user" @text="user menu" id="test-toggle-icon" @hasChevron={{false}} />`,
+      hbs`<Hds::Dropdown::Toggle::Icon @icon="more-horizontal" @text="user menu" id="test-toggle-icon" @hasChevron={{false}} />`,
     );
     assert.dom('.hds-icon.hds-icon-chevron-down').doesNotExist();
   });
@@ -155,4 +155,18 @@ module('Integration | Component | hds/dropdown/toggle/icon', function (hooks) {
       throw new Error(errorMessage);
     });
   });
+  test('it should throw an assertion if an incorrect value for @icon is provided while @hasChevron is false', async function (assert) {
+    const errorMessage =
+      '@hasChevron for "Hds::Dropdown::Toggle::Icon" must be true unless the icon is one of the following: more-horizontal, more-vertical; received: apple';
+    assert.expect(2);
+    setupOnerror(function (error) {
+      assert.strictEqual(error.message, `Assertion Failed: ${errorMessage}`);
+    });
+    await render(
+      hbs`<Hds::Dropdown::Toggle::Icon @icon="apple" @text="user menu" @hasChevron={{false}}/>`,
+    );
+    assert.throws(function () {
+      throw new Error(errorMessage);
+    });
+  });
 });

website/docs/components/dropdown/partials/code/component-api.md

@@ -68,7 +68,7 @@ The Dropdown component is composed of different child components each with their
     If an `@isInline` parameter is provided, then the element will be displayed as `inline-block` (useful to achieve specific layouts like in a container with right alignment). Otherwise, it will have a `block` layout.
   </C.Property>
   <C.Property @name="enableCollisionDetection" @type="boolean" @default="false" @values={{array "true" "false"}}>
-     Setting it to `true` will automatically flip the list position to remain visible when near the edges of the viewport.
+    Setting it to `true` will automatically flip the list position to remain visible when near the edges of the viewport.
   </C.Property>
   <C.Property @name="isOpen" @type="boolean" @default="false" @values={{array "true" "false"}}>
     Controls if the list should be rendered initially opened.
@@ -136,7 +136,7 @@ The `Dropdown::Toggle::Icon` component, yielded as contextual component.
     Acceptable value: any [icon](/icons/library) name.
   </C.Property>
   <C.Property @name="hasChevron" @type="boolean" @default="true">
-    Per design, `false` is only currently allowed when the "more-horizontal" icon is used; it is set to `true` by default.
+    Per design, `false` is only currently allowed when the "more-horizontal" or "more-vertical" icons are used; it is set to `true` by default.
   </C.Property>
   <C.Property @name="imageSrc" @type="string"/>
   <C.Property @name="...attributes">
@@ -295,7 +295,7 @@ The `Dropdown::ListItem::Checkmark` component, yielded as contextual component.
   </C.Property>
   <C.Property @name="...attributes">
     This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering).
-    <br/><br/>
+  <br/><br/>
     In this component, the `...attributes` are not supported on the root element (an `<li>` element) but on the underlying element/component (`<button>`, `<a>`, `<LinkTo>` or `<LinkToExternal>` depending on the `@route/@href` arguments).
   </C.Property>
 </Doc::ComponentApi>