@flywheel-io/vision 2.0.0 → 2.1.0-beta.0

package/src/components/select-menu/multi-select-menu/multi-select-menu.component.ts

@@ -0,0 +1,388 @@
+/* eslint-disable  @typescript-eslint/no-explicit-any */
+import { BooleanInput, coerceBooleanProperty } from '@angular/cdk/coercion';
+import { CdkMenuTrigger } from '@angular/cdk/menu';
+import {
+  AfterContentInit,
+  ChangeDetectorRef,
+  Component,
+  ContentChildren,
+  effect,
+  ElementRef,
+  EventEmitter,
+  forwardRef,
+  HostBinding,
+  HostListener,
+  Input,
+  input,
+  OnDestroy,
+  Output,
+  QueryList,
+  signal,
+  ViewChild,
+  viewChild,
+  ViewChildren,
+  WritableSignal,
+} from '@angular/core';
+import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
+import { Subscription } from 'rxjs';
+
+import { FwMenuComponent } from '../../menu/menu.component';
+import { FwMenuContainerComponent } from '../../menu/menu-container/menu-container.component';
+import { FwMenuItemComponent } from '../../menu/menu-item/menu-item.component';
+
+/**
+ * FwMultiSelect a component for selecting multiple options
+ * @see [Storybook Docs](https://cdn.flywheel.io/docs/vision/master/?path=/docs/form-controls-multi-select--docs)
+ */
+@Component({
+  selector: 'fw-multi-select',
+  templateUrl: './multi-select-menu.component.html',
+  styleUrls: ['./multi-select-menu.component.scss'],
+  providers: [
+    {
+      provide: NG_VALUE_ACCESSOR,
+      useExisting: forwardRef(() => FwMultiSelectMenuComponent),
+      multi: true,
+    },
+  ],
+})
+export class FwMultiSelectMenuComponent implements ControlValueAccessor, AfterContentInit, OnDestroy {
+  @HostListener('document:click') outsideClick(): void {
+    if (this._isOpen) {
+      this.trigger.close();
+      this._isOpen = false;
+    }
+    if (this.trigger && this.trigger.isOpen()) {
+      this._isOpen = true;
+    }
+  }
+
+  // options
+  @Input() options: object[] = [];
+  @Input() valueProperty?: string = 'value';
+  @Input() titleProperty?: string = 'title';
+  @Input() iconProperty?: string = 'icon';
+
+
+  // behaviour
+  @Input() emptyText: string = 'No matches found...';
+  @Input() placeholder: string = 'Select something...';
+  @Input() disabled?: boolean = false;
+  @Input() useCheckbox?: boolean = false;
+  @Input() closeOnSelect?: boolean = true;
+  @Input() maxSelectedShown: number = 100;
+
+  showClear = input(false);
+  showFilter = input(true, { transform: (val: BooleanInput) => coerceBooleanProperty(val) });
+  showSelectionInfo = input(false, { transform: (val: BooleanInput) => coerceBooleanProperty(val) });
+  filterItemsOnSelect = input(true, { transform: (val: BooleanInput) => coerceBooleanProperty(val) });
+
+  // sizing
+  @Input() width: string = '200px';
+  @Input() minHeight: string = '';
+  @Input() maxHeight: string = '200px';
+  @Input() optionsWidth?: string;
+  @Input() minOptionsHeight?: string;
+  @Input() maxOptionsHeight?: string;
+  @Input() size?: 'small' | 'medium' | 'large' = 'medium';
+
+  // view children
+  @ViewChild(CdkMenuTrigger) trigger: CdkMenuTrigger;
+  @ViewChild(FwMenuComponent) menu: FwMenuComponent;
+  menuFilter = viewChild(FwMenuContainerComponent);
+  @ViewChildren(FwMenuItemComponent) renderedMenuItems: QueryList<FwMenuItemComponent>;
+  @ContentChildren(FwMenuItemComponent, { descendants: true }) customMenuItems: QueryList<FwMenuItemComponent>;
+
+  // need this for the template
+  createArray = (d: Iterable<unknown>): unknown[] => Array.from(d);
+
+  // internal state
+  selectedValues: Set<string> = new Set();
+  selectedOptions: object[] = [];
+  displayedOptions: WritableSignal<FwMenuItemComponent[]> = signal([]);
+  focusedIndex = signal(0);
+  touched = false;
+  private subscriptions: Subscription[] = [];
+  private _isOpen = false;
+
+  // eslint-disable-next-line @angular-eslint/no-output-native
+  @Output() change = new EventEmitter<any>();
+
+  @Input()
+  get value(): any[] {
+    return this._value;
+  }
+
+  set value(newValue: any[]) {
+    this.updateValue(newValue);
+  }
+
+  private _value: any[] = [];
+
+  constructor(
+    protected _changeDetectorRef: ChangeDetectorRef,
+    private elementRef: ElementRef,
+  ) {}
+
+  @HostBinding('tabIndex') tabIndex = 0;
+  @HostBinding('style.pointer-events') pointerEvents = 'auto';
+
+  onChange: (value: any[]) => void;
+  onTouched = (): void => {};
+
+  registerOnChange(fn: (value: any[]) => void): void {
+    this.onChange = fn;
+  }
+
+  registerOnTouched(fn: () => void): void {
+    this.onTouched = fn;
+  }
+
+  setDisabledState?(isDisabled: boolean): void {
+    this.disabled = isDisabled;
+  }
+
+  writeValue(value: any[]): void {
+    this.value = value;
+  }
+
+  ngOnDestroy(): void {
+    for (const subscription of this.subscriptions) {
+      subscription.unsubscribe();
+    }
+  }
+
+  ngAfterContentInit(): void {
+    this.registerCustomMenuItems()
+
+    this.customMenuItems.changes.subscribe(() => {
+      this.registerCustomMenuItems();
+    })
+  }
+
+  private registerCustomMenuItems(): void {
+    // first filter any menuItems we've already registered as options
+    const newMenuItems = this.customMenuItems.filter(
+      menuItem => !this.options.find(option => menuItem.value === (option as any).value),
+    )
+
+    newMenuItems.forEach((newMenuItem) => {
+
+      // sync render settings
+      this.customMenuItems.forEach(menuItem => {
+        menuItem.showCheckbox = this.useCheckbox;
+        menuItem.multiSelect = true;
+      });
+
+      // add it to the options
+      // a lot of our value handling logic relies on
+      const newOption = {
+        value: newMenuItem.value,
+        title: newMenuItem.title,
+        icon: newMenuItem.icon,
+      }
+      this.options.push(newOption);
+
+      newMenuItem.mouseEnterHandler.set((event, item) => {
+        this.setFocusedIndex(item);
+      })
+
+      // add click listener
+      const sub = newMenuItem.click.subscribe(value => {
+        this.addValue(value);
+
+        if (this.closeOnSelect) {
+          this.trigger.close();
+        }
+      });
+      this.subscriptions.push(sub);
+    })
+  }
+
+  handleTouched(): void {
+    this.touched = true;
+  }
+
+  handleChipClose(chip: object): void {
+    const newValues = this.value.filter(val => val !== chip[this.valueProperty]);
+    this.updateValue(newValues);
+    this.trigger.close();
+  }
+
+  // handles the value emission from the menu
+  // TODO: make menu a dumb component, it shouldn't be handling values ideally
+  handleMenuChange(e: string[]): void {
+    if (Array.isArray(e)) {
+      if (e.toString() !== this.selectedValues.toString()) {
+        if (this.closeOnSelect) {
+          this.trigger.close();
+        }
+      }
+      this.updateValue(e);
+    }
+  }
+
+
+  // adds a single value
+  addValue(incoming: string): void {
+    const alreadySelected = this.value.includes(incoming);
+
+    if (alreadySelected) {
+      const splicedOut = this.value.toSpliced(this.value.indexOf(incoming), 1);
+      this.updateValue(splicedOut);
+    }
+    else {
+      this.updateValue([...this.value, incoming]);
+    }
+  }
+
+  // handles all the display side effects of a value change
+  updateValue(incomingValues: any[]): void {
+
+    if (!incomingValues) {
+      return;
+    }
+
+    this.selectedValues.clear();
+    this.selectedOptions = [];
+
+    incomingValues.forEach(incoming => {
+
+      if (typeof incoming === 'object') {
+        this.selectedValues.add(incoming[this.valueProperty]);
+        this.selectedOptions.push(incoming);
+
+      } else {
+
+        this.selectedValues.add(incoming);
+
+        const incomingMappedToOption = this.options.find(opt => opt[this.valueProperty] === incoming);
+        this.selectedOptions.push(incomingMappedToOption);
+      }
+    });
+
+    this._value = Array.from(this.selectedValues);
+    if (this.onChange) {
+      this.onChange(this._value);
+    }
+    this.change.emit(this._value);
+    this.postSelectSideEffects();
+  }
+
+  // custom filter for handling filterOnSelect
+  customFilter = (filter: string, menuItems: FwMenuItemComponent[]): FwMenuItemComponent[] => {
+    return menuItems.filter(menuItem => {
+      const filterMatches = menuItem.title.toLowerCase().includes(filter.toLowerCase());
+      const isSelected = this.value.includes(menuItem.value);
+      const filterBecauseSelected = isSelected && this.filterItemsOnSelect();
+
+      return filterMatches && !filterBecauseSelected;
+    })
+  }
+
+  private moveFocused(direction: 'up' | 'down'): void {
+    const options = this.displayedOptions();
+    const index = this.focusedIndex();
+
+    const clampIndex = (n: number): number => {
+      if (n < 0) {
+        return options.length - 1;
+      }
+      else if (n >= options.length) {
+        return 0;
+      }
+
+      return n;
+    }
+
+    const indexChange = direction === 'up' ? -1 : 1;
+
+    const newIndex = clampIndex(index + indexChange);
+    this.focusedIndex.set(newIndex);
+
+    const newlyFocused = this.displayedOptions()[this.focusedIndex()];
+
+    // eslint-disable-next-line @rx-angular/prefer-no-layout-sensitive-apis
+    newlyFocused.scrollIntoView();
+  }
+
+  setFocusedIndex(item: unknown): void {
+    const foundIndex = this.displayedOptions().findIndex(i => i.value === item[this.valueProperty]);
+    this.focusedIndex.set(foundIndex);
+  }
+
+  displayFocusIndicator = effect(() => {
+    this.displayedOptions().forEach((item, index) => {
+      item.focused = index === this.focusedIndex();
+    })
+  })
+
+  /* eslint-disable @typescript-eslint/naming-convention, @rx-angular/prefer-no-layout-sensitive-apis */
+  private keyboardActionMap = {
+    'ArrowDown': () => {
+      this.moveFocused('down');
+    },
+    'ArrowUp': () => {
+      this.moveFocused('up');
+    },
+    'Tab': () => {
+      this.trigger.close();
+      this.elementRef.nativeElement.focus();
+    },
+    'Escape': () => {
+      this.trigger.close();
+      this.elementRef.nativeElement.focus();
+    },
+    'Enter': () => {
+      const selectedMenuItem = this.displayedOptions()[this.focusedIndex()];
+
+      if (!selectedMenuItem) { return }
+
+      this.addValue(selectedMenuItem.value);
+      this.postSelectSideEffects();
+    },
+  }
+
+  private closedTriggerKeyboardActionsMap = {
+    'Enter': () => {
+      this.trigger.open();
+    },
+    'Backspace': () => {
+      this.updateValue(this.value.toSpliced(-1));
+    },
+  }
+  /* eslint-enable */
+
+  // needs to be an arrow function to lock the scope
+  @HostListener('keydown', ['$event'])
+  handleKeyDown = (event: KeyboardEvent): void =>{
+
+    const handler = this.trigger.isOpen() ? this.keyboardActionMap[event.key] : this.closedTriggerKeyboardActionsMap[event.key];
+
+    if (handler) {
+      event.preventDefault();
+      handler();
+    }
+  }
+
+  private postSelectSideEffects(): void {
+    this.menuFilter()?.onFilterChange('');
+
+    this.customMenuItems.forEach(menuItem => {
+      menuItem.selected = this.value.includes(menuItem.value);
+    })
+
+    if (this.closeOnSelect) {
+      setTimeout(() => {
+        this.trigger.close();
+        // eslint-disable-next-line @rx-angular/prefer-no-layout-sensitive-apis
+        this.elementRef.nativeElement.focus();
+      }, 0);
+    } else {
+      setTimeout(() => {
+        this.trigger.open();
+      }, 0);
+
+    }
+  }
+}

package/src/components/select-menu/multi-select-menu/multi-select-menu.mdx

@@ -0,0 +1,27 @@
+import { Canvas, Meta, Primary, Controls } from '@storybook/addon-docs';
+import * as MultiSelectStories from './multi-select-menu.stories'
+
+<Meta of={MultiSelectStories}/>
+
+# MultiSelect
+
+The Vision **MutliSelect** `<fw-multi-select>` is a form control for selecting values from a set of options, similar to the native html `<select multiple="true">` element with the multiple option enabled.
+
+- As with all Vision form components it works with [Angular's form APIs](https://angular.dev/guide/forms)
+- selected results will be shown in a chip grid instead of a `<fw-text-input>`.
+- __value__ will always be an array of strings, you also have __selectedOptions__ if you need the array of selected options objects
+
+much like the single [Select](/docs/form-controls-select--docs) tag your layout code looks almost identical except now you are using the `<fw-multi-select>` tag and the value emitted will be an **array** of strings instead of a single string/object.
+
+<Canvas sourceState='shown' of={MultiSelectStories.Primary}/>
+<Controls of={MultiSelectStories.Primary}/>
+
+## With Cusom Menu items
+
+The multi-select menu can also accept custom menus via the `fw-menu-item`, `fw-menu-header`, `fw-menu-separator`, and `fw-menu-group` as children.
+> Note: Custom menu items cannot be used in conjunction with the `options` prop
+
+<Canvas of={MultiSelectStories.WithCustomOptions}></Canvas>
+
+## MultiSelect Examples
+