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

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

@@ -0,0 +1,331 @@
+/* eslint-disable  @typescript-eslint/no-explicit-any */
+import { CdkMenuTrigger } from '@angular/cdk/menu';
+import {
+  AfterContentInit,
+  ChangeDetectorRef,
+  Component,
+  ContentChildren,
+  EventEmitter,
+  HostListener,
+  Input,
+  OnChanges,
+  OnDestroy,
+  Optional,
+  Output,
+  QueryList,
+  Self,
+  SimpleChanges,
+  ViewChild,
+} from '@angular/core';
+import { ControlValueAccessor, NgControl } from '@angular/forms';
+import { Subscription } from 'rxjs';
+
+import { IconType } from '../icon/icon.types';
+import { FwMenuComponent } from '../menu/menu.component';
+import { FwMenuItemComponent } from '../menu/menu-item/menu-item.component';
+
+@Component({
+  selector: 'fw-select',
+  templateUrl: './select-menu.component.html',
+  styleUrls: ['./select-menu.component.scss'],
+})
+export class FwSelectMenuComponent implements OnChanges, AfterContentInit, OnDestroy, ControlValueAccessor {
+  @HostListener('document:click', ['$event.target']) outsideClick(evt: any): void {
+    if (this._isOpen && evt.nodeName !== 'INPUT') {
+      this.onTouched();
+      this.close();
+      this._isOpen = false;
+    }
+    if (this.trigger && this.trigger.isOpen()) {
+      this._isOpen = true;
+    }
+  }
+
+  // bind it for the template
+  public JSON = JSON;
+
+  @Input() options: object[] = [];
+  @Input() valueProperty?: string = 'value';
+  @Input() useFullOptionAsValue = false;
+  @Input() titleProperty?: string = 'title';
+  @Input() iconProperty?: string = 'icon';
+  @Input() staticIcon?: IconType;
+  @Input() descriptionProperty?: string = 'description';
+  @Input() showFilter?: boolean = false;
+  @Input() showReset?: boolean = false;
+  @Input() disabled?: boolean = false;
+  @Input() errored?: boolean = false;
+  @Input() width: string = '200px';
+  @Input() optionsWidth?: string;
+  @Input() minOptionsHeight?: string;
+  @Input() maxOptionsHeight?: string;
+  @Input() size?: 'small' | 'medium' | 'large' = 'medium';
+  @Input() placeholder: string = 'Select something...';
+  @ViewChild(CdkMenuTrigger) trigger: CdkMenuTrigger;
+  @ViewChild(FwMenuComponent) menu: FwMenuComponent;
+  @ContentChildren(FwMenuItemComponent, { descendants: true }) menuItems: QueryList<FwMenuItemComponent>;
+  // eslint-disable-next-line @angular-eslint/no-output-native
+  @Output() change = new EventEmitter<any>();
+  @Output() readonly filterChanged = new EventEmitter<string>();
+  selectValue: string = '';
+  selectTitle: string = '';
+  selectIcon: string = '';
+  filterValue: string = '';
+  private subscriptions: Subscription[] = [];
+  private _isOpen = false;
+  focused = 0;
+  inFocusOpen = false;
+  preFocusValue: any;
+
+  @Input()
+  get value(): any {
+    return this._value;
+  }
+
+  set value(newValue: any) {
+    this.updateValue(newValue);
+  }
+
+  private _value: any;
+
+  constructor(
+    protected _changeDetectorRef: ChangeDetectorRef,
+    @Optional() @Self() private ngControl: NgControl,
+  ) {
+    // this is just a different way of binding the controlValueAccessor
+    // it can be accessed in the component this way
+    if (this.ngControl) {
+      this.ngControl.valueAccessor = this;
+    }
+  }
+
+  ngOnChanges(changes: SimpleChanges): void {
+    const currentOptions = changes.options?.currentValue;
+
+    // if the options change check if the title we should be displaying has changed
+    if (currentOptions && currentOptions !== changes.options?.previousValue) {
+      const selectedOption = currentOptions.find(item => item['value']?.toString() === this.selectValue);
+
+      if (selectedOption) {
+        this.selectTitle = selectedOption['title'];
+      }
+    }
+  }
+
+  ngAfterContentInit(): void {
+    if (!this.options || (this.options.length === 0 && this.menuItems && this.menuItems.length > 0)) {
+      this.options = [];
+      this.menuItems.forEach(item => {
+        this.options.push({
+          value: item.value.toString(),
+          title: item.title.toString(),
+          icon: item.icon,
+          description: item.description,
+        });
+        const sub = item.click.subscribe(value => this.menu.writeValue(value));
+        this.subscriptions.push(sub);
+        if (item.value.toString() === this.selectValue) {
+          this.selectTitle = item.title.toString();
+          this.selectIcon = item.icon;
+        }
+      });
+    }
+  }
+
+  ngOnDestroy(): void {
+    for (const subscription of this.subscriptions) {
+      subscription.unsubscribe();
+    }
+  }
+
+  get invalid(): boolean {
+    return this.ngControl?.invalid;
+  }
+
+  get touched(): boolean {
+    return this.ngControl?.touched;
+  }
+
+  onChange(newValue: any): void {
+    this._value = typeof newValue === 'object' ? JSON.stringify(newValue) : newValue;
+    this.change.emit(newValue);
+    this.externalOnChange?.(newValue);
+  };
+
+  onTouched = (): void => {
+  };
+
+  externalOnChange;
+  registerOnChange(fn: (value: any) => void): void {
+    this.externalOnChange = fn;
+  }
+
+  registerOnTouched(fn: () => {}): void {
+    this.onTouched = fn;
+  }
+
+  setDisabledState?(isDisabled: boolean): void {
+    this.disabled = isDisabled;
+    // eslint-disable-next-line @rx-angular/no-explicit-change-detection-apis
+    this._changeDetectorRef.markForCheck();
+  }
+
+  writeValue(value: any): void {
+    this.updateValue(value);
+  }
+
+  handleClick(e: string): void {
+    this.onTouched();
+
+    if (this.selectValue === e) {
+      this.close();
+      return;
+    }
+
+    if (this.useFullOptionAsValue) {
+      const parsedValue = JSON.parse(e);
+      this.updateValue(parsedValue);
+    } else {
+      this.updateValue(e);
+    }
+
+    this.close();
+  }
+
+  moveFocused(direction: string): void {
+    switch (direction) {
+      case 'down': {
+        this.focused++;
+        if (this.focused >= this.options.length) {
+          this.focused = 0;
+        }
+        break;
+      }
+      case 'up': {
+        this.focused--;
+        if (this.focused < 0) {
+          this.focused = this.options.length - 1;
+        }
+        break;
+      }
+      default: {
+        this.focused = 0;
+        break;
+      }
+    }
+  }
+
+  handleKeyDown(event: KeyboardEvent): void {
+    if (this.trigger.isOpen()) {
+      if (this.inFocusOpen) {
+        if (event.key === 'ArrowDown') {
+          this.moveFocused('down');
+          this.updateValue(this.options[this.focused]);
+        }
+        if (event.key === 'ArrowUp') {
+          this.moveFocused('up');
+          this.updateValue(this.options[this.focused]);
+        }
+        if (event.key === 'Tab') {
+          this.close();
+          this.inFocusOpen = false;
+          this.updateValue(this.preFocusValue);
+        }
+        if (event.key === 'Enter') {
+          this.close();
+          this.inFocusOpen = false;
+          const newValue = this.useFullOptionAsValue ? this.JSON.parse(this.value) : this.value;
+          this.updateValue(newValue);
+        }
+      } else {
+        this.inFocusOpen = true;
+        this.preFocusValue = this.value;
+      }
+    } else {
+      if (event.key === 'Enter') {
+        this.inFocusOpen = false;
+        this.preFocusValue = this.value;
+      }
+    }
+  }
+
+  handleKeyUp(event: KeyboardEvent): void {
+    if (this.trigger.isOpen()) {
+      if (event.key === 'Escape') {
+        this.close();
+        this.inFocusOpen = false;
+        this.updateValue(this.preFocusValue);
+      }
+    } else {
+      if (this.showReset) {
+        if (event.key === 'Escape') {
+          this.handleReset();
+        }
+      }
+    }
+  }
+
+
+  updateValue(newValue: unknown): void {
+
+    // do housekeeping first
+    this.onTouched();
+
+    // null guard
+    if (!newValue) {
+      this.selectValue = '';
+      this.selectTitle = '';
+      this.selectIcon = '';
+      return this.onChange(newValue);
+    }
+
+    if (typeof newValue === 'object') {
+      this.selectValue = newValue?.[this.valueProperty]?.toString();
+      this.selectTitle = newValue?.[this.titleProperty]?.toString();
+      this.selectIcon = newValue?.[this.iconProperty];
+
+      const changeToEmit = this.useFullOptionAsValue ? newValue : newValue[this.valueProperty];
+      return this.onChange(changeToEmit);
+    }
+
+    // try and find a matching option
+    const matchedOption = this.options.find(option => {
+      const matchesValue = option[this.valueProperty] === newValue;
+      const matchesTitle = option[this.titleProperty] === newValue;
+
+      return matchesValue || matchesTitle;
+    });
+
+    if (matchedOption) {
+      this.selectValue = matchedOption[this.valueProperty]?.toString();
+      this.selectTitle = matchedOption[this.titleProperty]?.toString();
+      this.selectIcon = matchedOption[this.iconProperty];
+
+      const changeToEmit = this.useFullOptionAsValue ? matchedOption : matchedOption[this.valueProperty];
+      return this.onChange(changeToEmit);
+    } else {
+      // fall back to stringify
+      const stringified = newValue.toString() || '';
+      this.selectValue = stringified;
+      this.selectTitle = stringified;
+      return this.onChange(stringified);
+    }
+  }
+
+  handleReset(): void {
+    if (this.showReset) {
+      this.updateValue(null);
+    }
+  }
+
+  close(): void {
+    this.trigger.close();
+    this.filterValue = '';
+    this.filterChanged.emit(this.filterValue);
+  }
+
+  onFilterChanged(value: string): void {
+    this.filterValue = value;
+    this.filterChanged.emit(value);
+  }
+}

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

@@ -0,0 +1,222 @@
+import { Canvas, Meta, Primary, Controls } from '@storybook/addon-docs';
+import * as SelectStories from './select-menu.stories'
+
+<Meta of={SelectStories}/>
+
+# Select
+The Vision **Select** `<fw-select>` is a form control for selecting a value from a set of options, similar to the native html `<select>` element.
+
+- it is a **single** option select dropdown. for multiple select see [MultiSelect](/docs/form-controls-multi-select--docs)
+- the select options can be populated via the `[options]` data model array.
+- the default properties it uses from the array are `value, title, icon`
+- defaults can be changed via `[valueProperty], [titleProperty], [iconProperty]`
+- selecting an option will automatically close the window and emit the `valueProperty` of that object as the value.
+- the selected option title and optional icon will be shown in the text box field selector
+
+## Table of Contents
+
+- [Primary Story](#primary-story)
+- [Usage](#usage)
+  - [Complex Object Usage](#complex-object-usage)
+  - [Using Custom Options](#using-custom-options)
+- [State Management](#state-management)
+  - [Managing State Directly](#managing-state-directly)
+  - [ngModel](#ngmodel)
+  - [FormGroup](#formgroup)
+  - [Using the Full Option as Value](#using-the-full-option-as-value)
+  - [Writing Values to the Select](#writing-values-to-the-select)
+
+## Primary Story
+<Primary />
+<Controls />
+
+## Usage
+
+First import the module into your `app.module.ts`
+
+```ts filename="app.module.ts"
+// app.module.ts
+
+import {FwSelectMenuModule} from '@flywheel-io/vision';
+
+@NgModule({
+  imports: [
+      FwSelectMenuModule
+  ]
+})
+```
+
+and then in your layout code add the component
+
+```html
+<!--- your.component.ts --->
+    options: [
+      { title: '1-One', value: 1 },
+      { title: '2-Two', value: 2 },
+      { title: '3-Three', value: 3 },
+      { title: '4-Four', value: 4 },
+    ],
+
+    selectedValue = 2;
+
+<!--- your.component.html --->
+
+<fw-select [options]="options" [value]="selectedValue">
+</fw-select>
+```
+
+<Canvas of={SelectStories.SelectNumber}></Canvas>
+
+### Complex Object Usage
+
+```html
+<!--- your.component.ts --->
+rolePermissions: [
+  { roleName: 'Owner', roleId: 'owner', roleDescription: 'Owner description', roleIcon: 'icon-placeholder' },
+  { roleName: 'Admin', roleId: 'admin', roleDescription: 'Admin description', roleIcon: 'icon-placeholder' },
+  { roleName: 'Developer', roleId: 'developer', roleDescription: 'Developer description', roleIcon: 'icon-placeholder' },
+  { roleName: 'Member', roleId: 'member', roleDescription: 'Member description', roleIcon: 'icon-placeholder' },
+],
+
+selectedPermission = { roleName: 'Developer', roleId: 'developer', roleIcon: 'icon-placeholder' };
+
+<!--- your.component.html --->
+
+<fw-select
+    [options]="rolePermissions"
+    [(ngModel)]="selectedPermission"
+    [valueProperty]="roleId"
+    [titleProperty]="roleName"
+    [iconProperty]="roleIcon"
+    placeholder="Select Role...">
+</fw-select>
+```
+
+<Canvas of={SelectStories.Select}></Canvas>
+
+### Using Custom Options
+
+If you prefer you can also alternatively define your collection of [MenuItem](/story/vision-menu--menu-item) directly in your layout code.
+
+> Note: if doing this with `useFullOptionAsValue` you will need to stringify your values like so `<fw-menu-item value="JSON.stringify(objectToUse)" title="An Object"></fw-menu-item>`
+
+```html
+<!--- your.component.html --->
+
+<fw-select placeholder="Pick a Topic" width="220px" value="release">
+  <fw-menu-item value="release" title="Release Notes" icon="notebook-pen-edit"></fw-menu-item>
+  <fw-menu-item value="documentation" title="Browse Documentation" icon="files"></fw-menu-item>
+  <fw-menu-item value="forum" title="User Forum" icon="message-chat-question-support"></fw-menu-item>
+  <fw-menu-item value="feedback" title="Give Us Feedback" icon="message-question-checkmark"></fw-menu-item>
+  <fw-menu-separator></fw-menu-separator>
+  <fw-menu-item value="bookmark" title="Add Bookmark" icon="add-new-create"></fw-menu-item>
+  <fw-menu-separator></fw-menu-separator>
+  <fw-menu-item value="flywheel" title="Flywheel Enterprise" description="Version 18.22.1"></fw-menu-item>
+</fw-select>
+
+or even in a for loop like so:
+
+<fw-select placeholder="Pick a Topic..." width="100%" [(ngModel)]="selectedItem">
+  <fw-menu-item *ngFor="let item of items" [value]="item.choice" [title]="item.name">
+  </fw-menu-item>
+</fw-select>
+```
+
+<Canvas of={SelectStories.SelectCustom}></Canvas>
+
+
+
+## State Management
+
+### Managing state directly
+```html
+<fw-select [options]="options" [value]="value" (change)="handleChange($event)"></fw-select>
+```
+
+### ngModel
+```html
+<fw-select [options]="options" [(ngModel)]="selected" (ngModelChange)="handleChange($event)"></fw-select>
+```
+
+### FormGroup
+
+```html
+<!--- your.component.ts --->
+options: [
+  { title: 'Owner', value: 'owner', icon: 'icon-placeholder' },
+  { title: 'Admin', value: 'admin', icon: 'icon-placeholder' },
+  { title: 'Developer', value: 'developer', icon: 'icon-placeholder' },
+  { title: 'Member', value: 'member', icon: 'icon-placeholder' },
+],
+
+const formGroup = new FormGroup({
+  role: new FormControl('developer'),
+});
+
+<!--- your.component.html --->
+
+<form [formGroup]="formGroup">
+  <fw-select
+    placeholder="Pick a Role"
+    width="220px"
+    [options]="options"
+    formControlName="role">
+  </fw-select>
+</form>
+```
+
+### Using the Full Option as Value
+
+By default the select will always try to emit the `valueProperty` of the passed option that is selected.
+You can change this behaviour with the `useFullOptionAsValue` input.
+When set to true `useFullOptionAsValue` will make the select emit the full option as it's value, rather than the `valueProperty`.
+
+In the above [Complex Object Usage Example](/docs/form-controls-select--docs#complex-object-usage) for example it would emit
+```
+{ roleName: 'Owner', roleId: 'owner', roleDescription: 'Owner description', roleIcon: 'icon-placeholder' }
+```
+as the value when `useFullOptionAsValue` was set to true
+
+### Writing Values to the Select
+
+There are a couple of ways to programattically write a value to the select:
+binding directly to `value`, or through the `writeValue` function, which is what the Angular form APIs use.
+
+When writing a value to the select if the written value is an object it will handle it as if it was an option,
+meaning it will try to access its `valueProperty` and then emit that as its current value.
+That is unless `useFullOptionAsValue` is true.
+
+> Note: It will accept values that are not part of the `options` array, and will attempt to use the `titleProperty` and `iconProperty` for display of the set value
+
+### example:
+
+```html
+<!--- your.component.ts --->
+options: [
+  { title: 'Owner', id: '1', icon: 'icon-placeholder' },
+  { title: 'Admin', id: '2', icon: 'icon-placeholder' },
+  { title: 'Developer', id: '3', icon: 'icon-placeholder' },
+  { title: 'Member', id: '4', icon: 'icon-placeholder' },
+],
+
+const control = new FormControl();
+
+control.setValue({ title: 'Owner', value: 'owner', icon: 'icon-placeholder' });
+console.log(control.value) // is set to the id which is '1'
+
+
+control.setValue({ title: 'New Role', id: '37' })
+// The select will display 'New Role' as the selected title
+console.log(control.value) // '37'
+
+<!--- your.component.html --->
+
+<fw-select
+  placeholder="Pick a Role"
+  valueProperty="id"
+  [options]="options"
+  formControlName="control">
+</fw-select>
+```
+
+<Canvas of={SelectStories.SelectInAForm}></Canvas>

package/src/components/select-menu/select-menu.module.ts

@@ -0,0 +1,37 @@
+import { CdkMenuModule } from '@angular/cdk/menu';
+import { CommonModule } from '@angular/common';
+import { NgModule } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+
+import { MenuRegisterDirective } from '../../directives/menu-register.directive';
+import { FwButtonModule } from '../button/button.module';
+import { FwChipModule } from '../chip/chip.module';
+import { FwIconModule } from '../icon/icon.module';
+import { FwMenuModule } from '../menu/menu.module';
+import { FwTextInputModule } from '../text-input/text-input.module';
+import { FwMultiSelectMenuComponent } from './multi-select-menu/multi-select-menu.component';
+import { FwSelectMenuComponent } from './select-menu.component';
+
+@NgModule({
+    imports: [
+        CommonModule,
+        CdkMenuModule,
+        FormsModule,
+        FwButtonModule,
+        FwChipModule,
+        FwIconModule,
+        FwMenuModule,
+        FwTextInputModule,
+        MenuRegisterDirective,
+    ],
+  exports: [
+    FwMultiSelectMenuComponent,
+    FwSelectMenuComponent,
+  ],
+  declarations: [
+    FwMultiSelectMenuComponent,
+    FwSelectMenuComponent,
+  ],
+})
+export class FwSelectMenuModule {
+}