SuperSelect components (HDS-3221)

.changeset/hot-grapes-rule.md

@@ -0,0 +1,5 @@
+---
+"@hashicorp/design-system-components": minor
+---
+
+`SuperSelect` - added components for single and multiple selection based on [PowerSelect](https://ember-power-select.com/)

packages/components/package.json

@@ -49,6 +49,7 @@
     "ember-focus-trap": "^1.1.0",
     "ember-keyboard": "^8.2.1",
     "ember-modifier": "^4.1.0",
+    "ember-power-select": "^8.2.0",
     "ember-stargate": "^0.4.3",
     "ember-style-modifier": "^3.0.1",
     "ember-truth-helpers": "^4.0.3",
@@ -60,8 +61,10 @@
     "@babel/core": "^7.24.5",
     "@babel/plugin-transform-typescript": "^7.23.6",
     "@babel/runtime": "^7.24.5",
+    "@ember/test-helpers": "^3.3.0",
     "@embroider/addon-dev": "^4.3.1",
     "@glimmer/component": "^1.1.2",
+    "@glimmer/tracking": "^1.1.2",
     "@glint/core": "^1.4.0",
     "@glint/environment-ember-loose": "^1.4.0",
     "@glint/template": "^1.4.0",
@@ -75,6 +78,8 @@
     "@typescript-eslint/parser": "^6.14.0",
     "babel-plugin-ember-template-compilation": "^2.2.4",
     "concurrently": "^8.2.2",
+    "ember-basic-dropdown": "^8.1.0",
+    "ember-concurrency": "^4.0.2",
     "ember-template-lint": "^4.18.2",
     "ember-template-lint-plugin-prettier": "^4.2.0",
     "eslint": "^8.52.0",
@@ -188,6 +193,13 @@
       "./components/hds/form/radio/group.js": "./dist/_app_/components/hds/form/radio/group.js",
       "./components/hds/form/select/base.js": "./dist/_app_/components/hds/form/select/base.js",
       "./components/hds/form/select/field.js": "./dist/_app_/components/hds/form/select/field.js",
+      "./components/hds/form/super-select/after-options.js": "./dist/_app_/components/hds/form/super-select/after-options.js",
+      "./components/hds/form/super-select/multiple/base.js": "./dist/_app_/components/hds/form/super-select/multiple/base.js",
+      "./components/hds/form/super-select/multiple/field.js": "./dist/_app_/components/hds/form/super-select/multiple/field.js",
+      "./components/hds/form/super-select/option-group.js": "./dist/_app_/components/hds/form/super-select/option-group.js",
+      "./components/hds/form/super-select/placeholder.js": "./dist/_app_/components/hds/form/super-select/placeholder.js",
+      "./components/hds/form/super-select/single/base.js": "./dist/_app_/components/hds/form/super-select/single/base.js",
+      "./components/hds/form/super-select/single/field.js": "./dist/_app_/components/hds/form/super-select/single/field.js",
       "./components/hds/form/text-input/base.js": "./dist/_app_/components/hds/form/text-input/base.js",
       "./components/hds/form/text-input/field.js": "./dist/_app_/components/hds/form/text-input/field.js",
       "./components/hds/form/textarea/base.js": "./dist/_app_/components/hds/form/textarea/base.js",

packages/components/src/components/hds/form/label/index.hbs

@@ -3,7 +3,7 @@
   Copyright (c) HashiCorp, Inc.
   SPDX-License-Identifier: MPL-2.0
 }}
-<label class={{this.classNames}} for={{@controlId}} ...attributes>
+<label class={{this.classNames}} for={{@controlId}} id={{this.id}} ...attributes>
   {{yield}}
   <Hds::Form::Indicator @isRequired={{@isRequired}} @isOptional={{@isOptional}} />
 </label>

packages/components/src/components/hds/form/label/index.js

@@ -4,8 +4,22 @@
  */
 
 import Component from '@glimmer/component';
+export const ID_PREFIX = 'label-';
 
 export default class HdsFormLabelIndexComponent extends Component {
+  /**
+   * Determines the unique ID to assign to the element
+   * @method id
+   * @return {(string|null)} The "id" attribute to apply to the element or null, if no controlId is provided
+   */
+  get id() {
+    let { controlId } = this.args;
+    if (controlId) {
+      return `${ID_PREFIX}${controlId}`;
+    }
+    return null;
+  }
+
   /**
    * Get the class names to apply to the component.
    * @method classNames

packages/components/src/components/hds/form/super-select/after-options.hbs

@@ -0,0 +1,31 @@
+{{! @glint-nocheck: not typesafe yet }}
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+{{#if @showNoSelectedMessage}}
+  <Hds::Text::Body @tag="div" @size="200" class="hds-form-super-select__no-options-selected hds-foreground-strong">
+    No options selected
+  </Hds::Text::Body>
+{{/if}}
+<div class="hds-form-super-select__after-options">
+  {{#if @content}}
+    <Hds::Text::Body @tag="div" @size="100" class="hds-foreground-strong">
+      {{@content}}
+    </Hds::Text::Body>
+  {{else}}
+    {{#if (or @showAll @showSelected @clearSelected)}}
+      {{#if @showOnlySelected}}
+        <Hds::Button @text="Show all" @size="small" @color="secondary" {{on "click" @showAll}} />
+      {{else}}
+        <Hds::Button @text="Show selected" @size="small" @color="secondary" {{on "click" @showSelected}} />
+      {{/if}}
+      {{#if (not-eq @selectedCount "0")}}
+        <Hds::Button @text="Clear selected" @size="small" @color="secondary" {{on "click" @clearSelected}} />
+      {{/if}}
+    {{/if}}
+    <Hds::Text::Body @tag="div" @size="100" class="hds-form-super-select__result-count hds-foreground-strong">
+      {{@resultCountMessage}}
+    </Hds::Text::Body>
+  {{/if}}
+</div>

packages/components/src/components/hds/form/super-select/multiple/base.hbs

@@ -0,0 +1,79 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+{{! Important: if an argument is added in base.hbs, it must also be added/processed in the Base component used in field.hbs }}
+<div class={{this.classNames}} {{style this.dropdownMaxWidthStyle}}>
+  <PowerSelectMultiple
+    @afterOptionsComponent={{if
+      this.showAfterOptions
+      (or
+        @afterOptionsComponent
+        (component
+          "hds/form/super-select/after-options"
+          content=@afterOptionsContent
+          resultCountMessage=this.resultCountMessage
+          showNoSelectedMessage=this.showNoSelectedMessage
+          showOnlySelected=this.showOnlySelected
+          showSelected=this.showSelected
+          showAll=this.showAll
+          clearSelected=this.clearSelected
+          selectedCount=this.selectedCount
+        )
+      )
+    }}
+    @ariaDescribedBy={{@ariaDescribedBy}}
+    @ariaInvalid={{@ariaInvalid}}
+    @ariaLabel={{@ariaLabel}}
+    @ariaLabelledBy={{@ariaLabelledBy}}
+    @beforeOptionsComponent={{@beforeOptionsComponent}}
+    @calculatePosition={{if @verticalPosition undefined this.calculatePosition}}
+    @closeOnSelect={{false}}
+    @disabled={{@disabled}}
+    @dropdownClass={{@dropdownClass}}
+    @extra={{@extra}}
+    @groupComponent={{component "hds/form/super-select/option-group"}}
+    @horizontalPosition={{@horizontalPosition}}
+    @initiallyOpened={{@initiallyOpened}}
+    @labelText={{@labelText}}
+    @loadingMessage={{@loadingMessage}}
+    @matcher={{@matcher}}
+    @matchTriggerWidth={{if @dropdownMaxWidth false @matchTriggerWidth}}
+    @noMatchesMessage={{@noMatchesMessage}}
+    @onBlur={{@onBlur}}
+    @onChange={{@onChange}}
+    @onClose={{@onClose}}
+    @onFocus={{@onFocus}}
+    @onInput={{@onInput}}
+    @onKeydown={{@onKeydown}}
+    @onOpen={{@onOpen}}
+    @options={{@options}}
+    @optionsComponent={{@optionsComponent}}
+    @placeholder={{@placeholder}}
+    @placeholderComponent={{@placeholderComponent}}
+    @preventScroll={{@preventScroll}}
+    @registerAPI={{this.setPowerSelectAPI}}
+    @renderInPlace={{true}}
+    @resultCountMessage={{@resultCountMessage}}
+    @scrollTo={{@scrollTo}}
+    @search={{@search}}
+    @searchEnabled={{@searchEnabled}}
+    @searchField={{@searchField}}
+    @searchMessage={{@searchMessage}}
+    @searchPlaceholder={{this.searchPlaceholder}}
+    @selected={{@selected}}
+    @selectedItemComponent={{@selectedItemComponent}}
+    @tabindex={{@tabindex}}
+    @triggerClass={{@triggerClass}}
+    @triggerComponent={{@triggerComponent}}
+    @triggerId={{@triggerId}}
+    @triggerRole={{@triggerRole}}
+    @typeAheadMatcher={{@typeAheadMatcher}}
+    @verticalPosition={{@verticalPosition}}
+    ...attributes
+    as |option select|
+  >
+    {{! even if technically what is yielded here are _a list_ of options, we've decided to keep the `option` name for consistency with the existing `PowerSelect` API }}
+    {{yield option select}}
+  </PowerSelectMultiple>
+</div>

packages/components/src/components/hds/form/super-select/multiple/base.js

@@ -0,0 +1,145 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import PowerSelectComponent from 'ember-power-select/components/power-select';
+import anchoredPositionModifier from '../../../../../modifiers/hds-anchored-position';
+import { action } from '@ember/object';
+import { tracked } from '@glimmer/tracking';
+
+const DEFAULT_HORIZONTAL_POSITION = 'bottom-start';
+const HORIZONTAL_POSITION_MAPPING = {
+  left: 'bottom-start',
+  center: 'bottom',
+  right: 'bottom-end',
+};
+
+export default class HdsSuperSelectMultipleBaseComponent extends PowerSelectComponent {
+  @tracked powerSelectAPI;
+  @tracked showOnlySelected = false;
+  @tracked showNoSelectedMessage = false;
+
+  get selectedCount() {
+    return this.selected?.length || '0';
+  }
+
+  get optionsCount() {
+    return this.options?.length || '0';
+  }
+
+  get resultCountMessage() {
+    return `${this.selectedCount} selected of ${this.optionsCount} total`;
+  }
+
+  @action calculatePosition(trigger, content) {
+    // use `hds-anchored-position` to calculate and set position
+    anchoredPositionModifier(content, [trigger], {
+      placement: this.args.horizontalPosition
+        ? HORIZONTAL_POSITION_MAPPING[this.args.horizontalPosition]
+        : DEFAULT_HORIZONTAL_POSITION,
+      offsetOptions: 4,
+      enableCollisionDetection: true,
+    });
+    // prevent PowerSelect from setting position
+    return {};
+  }
+
+  /**
+   * This action sets the powerSelectAPI property and optionally calls a registerAPI function.
+   *
+   * @param {Object} powerSelectAPI - The API object for the PowerSelect component.
+   *
+   * If a `registerAPI` function is passed in through the component's arguments,
+   * this function will be called with the `powerSelectAPI` as its argument.
+   * This allows parent components or controllers to have access to the PowerSelect API.
+   *
+   * The `powerSelectAPI` is also stored on the component instance and used in `clearSelected`
+   */
+  @action
+  setPowerSelectAPI(powerSelectAPI) {
+    if (typeof this.args.registerAPI === 'function') {
+      this.args.registerAPI(powerSelectAPI);
+    }
+    this.powerSelectAPI = powerSelectAPI;
+  }
+
+  @action showSelected() {
+    this.showNoSelectedMessage = this.selectedCount === '0';
+    this.showOnlySelected = true;
+  }
+
+  @action showAll() {
+    this.showNoSelectedMessage = false;
+    this.showOnlySelected = false;
+  }
+
+  @action clearSelected() {
+    this.powerSelectAPI.actions.select(null);
+    // show all options after clearing all selection
+    this.showNoSelectedMessage = false;
+    this.showOnlySelected = false;
+  }
+
+  /**
+   * Determine if `@afterOptionsComponent` gets displayed
+   * @param showAfterOptions
+   * @type {boolean}
+   * @default true
+   */
+  get showAfterOptions() {
+    return this.args.showAfterOptions ?? true;
+  }
+
+  // NOTE: The searchPlaceholder doesn't currently work for the multiple select
+  /**
+   * Get the search placeholder text
+   * @param searchPlaceholder
+   * @type {string}
+   * @default 'Search'
+   */
+  get searchPlaceholder() {
+    return this.args.searchPlaceholder ?? 'Search';
+  }
+
+  /**
+   * Get the maxWidth to apply to the dropdown
+   * @param dropdownMaxWidth
+   * @type {string}
+   * @default 'none'
+   */
+  get dropdownMaxWidthStyle() {
+    const maxWidthStyle = {};
+    if (this.args.dropdownMaxWidth) {
+      maxWidthStyle['--hds-form-super-select-dropdown-max-width'] =
+        this.args.dropdownMaxWidth;
+    }
+    return maxWidthStyle;
+  }
+
+  /**
+   * Get the class names to apply to the component.
+   * @method classNames
+   * @return {string} The "class" attribute to apply to the component.
+   */
+  get classNames() {
+    let classes = ['hds-form-super-select', 'hds-form-super-select-multiple'];
+
+    // add a class based on the @matchTriggerWidth argument or whether dropdownMaxWidth is set
+    if (this.args.matchTriggerWidth === false || this.args.dropdownMaxWidth) {
+      classes.push('hds-form-super-select--dropdown-content-auto-width');
+    }
+
+    // add a class based on the @isInvalid argument
+    if (this.args.isInvalid) {
+      classes.push(`hds-form-super-select--is-invalid`);
+    }
+
+    // add a class based on the showOnlySelected
+    if (this.showOnlySelected) {
+      classes.push(`hds-form-super-select--show-only-selected`);
+    }
+
+    return classes.join(' ');
+  }
+}