@terminus/ui-selection-list

v5.0.0

Published

3 years ago

<h1>Selection List</h1>

Downloads

0High
0Medium
0Low

bmalinconico-terminus

atlwendy

terminus_devops

Installation

Use the ng add command to quickly install all the needed dependencies:

ng add @terminus/ui-selection-list

CSS imports

In your top-level stylesheet, add these imports:

@import '~@terminus/design-tokens/css/library-design-tokens.css';
@import '~@terminus/ui-styles/terminus-ui.css';

CSS resources

Load the needed font families by adding this link to the <head> of your application:

<link href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,400;0,500;0,700;1,400&display=swap" rel="stylesheet">

Usage

Pass a collection of ts-option components inside the selection-list:

<ts-selection-list [formControl]="myCtrl">
 <ts-option
    *ngFor="let state of states | async"
    [value]="state"
    [option]="state"
  >
    {{ state.name }}
  </ts-option>
</ts-selection-list>

Duplicate selections

By default, duplicate selections are ignored. They can be allowed via a flag:

<ts-selection-list
  [formControl]="myCtrl"
  [allowMultiple]="true"
  [allowDuplicateSelections]="true"
>
  ...
</ts-selection-list>

Keeping the panel open

By default, the panel will close after each selection. It can be forced to stay open via a flag.

NOTE: While the panel seems to stay open, it is actually closing and reopening immediately. That is why the @Input is named reopenAfterSelection

<ts-selection-list
  [formControl]="myCtrl"
  [allowMultiple]="true"
  [reopenAfterSelection]="true"
>
  ...
</ts-selection-list>

Debouncing queries

By default, the input query will be debounced 200ms. This time may be adjusted as needed:

<ts-selection-list
  [formControl]="myCtrl"
  [debounceDelay]="400"
>
  ...
</ts-selection-list>

Minimum characters

By default, at least two characters must be typed before the query is fired. This limit may be adjusted:

<ts-selection-list
  [formControl]="myCtrl"
  [minimumCharacters]="4"
>
  ...
</ts-selection-list>

Formatting

For complex object support, a formatter function may be passed in to define the view value:

<ts-selection-list
  [formControl]="myCtrl"
  [displayFormatter]="formatDisplay"
>
  ...
</ts-selection-list>

import { TsSelectionListFormatter } from '@terminus/ui-selection-list';

public formatDisplay: TsSelectionListFormatter = v => v.name;

Complex comparator

To compare custom objects, a compare function may be passed in:

<ts-selection-list
  [formControl]="myCtrl"
  [valueComparator]="myCompareFunction"
>
  ...
</ts-selection-list>

import { TsSelectionListComparator } from '@terminus/ui-selection-list';

public myCompareFunction: TsSelectionListComparator = (a, b) => a.id === b.id;

Standard dropdown mode (no typing)

If the component should act as a standard dropdown with no ability to type a query, set the flag allowUserInput to false. By default it is true.

<ts-selection-list
  [formControl]="myCtrl"
  [allowUserInput]="false"
>
  ...
</ts-selection-list>

Hint

A custom hint message can be displayed:

<ts-selection-list hint="Select at least one item"></ts-selection-list>

Error message

A custom error message can be displayed:

<ts-selection-list errorMessage="My error message!"></ts-selection-list>

noValidationOrHint

A flag to define whether this selectionlist field needs validation or hint. If it needs validation or hint, a padding bottom is added for the message, otherwise, no padding at the bottom.

<ts-selection-list
  [formControl]="myCtrl"
  [noValidationOrHint]="true"
></ts-selection-list>

Minimal

A minimal style is available:

<ts-selection-list [isMinimal]="true"></ts-selection-list>

Show progress

A progress indicator can be shown programmatically:

<ts-selection-list [showProgress]="true"></ts-selection-list>

Events

| Event | Description | Payload | |:---------------------|:-------------------------------------------|:------------------------| | backdropClicked | Fired when the overlay backdrop is clicked | void | | closed | Fired when the panel is closed | void | | duplicateSelection | Fired when a duplicate selection is made | TsSelectionListChange | | opened | Fired when the panel is opened | void | | optionSelected | Fired when an option is selected | TsSelectionListChange | | optionDeselected | Fired when an option is deselected | TsSelectionListChange | | queryChange | Fired when the search query changes | string | | selectionChange | Fired when the selected tab changes | TsSelectionListChange |

<ts-selection-list (selectionChange)="whenSelectionChanges($event)">
  ...
</ts-selection-list>

The TsSelectionListChange structure:

class TsSelectionListChange<T = unknown> {
  constructor(
    // The associated selection list instance
    public source: TsSelectionListComponent,
    // The value
    public value: T,
  ) {}
}

Test Helpers

Some helpers are exposed to assist with testing. These are imported from @terminus/ui-selection-list/testing;

[source]

| Function | |------------------------------------| | getSelectionListDebugElement | | getSelectionListInput | | getAllSelectionListDebugElements | | getAllSelectionListInstances | | getSelectionListInstance | | getSelectionListElement | | getSelectionListTriggerElement | | getAllOptionInstances | | getOptionInstance | | getOptionElement | | getAllOptgroups | | getOptgroup | | getOptgroupElement |