@cas-smartdesign/token-selector

A token-selector element based on lit-element with SmartDesign look & feel.

Note: This is a preview version of the sd-token-selector element. Some features like for example declarative support for the element is not fully supported and guaranteed.

Attributes - Token-Selector

• selection-mode : string (default = "multi")
  • multi: it is possible to select, delesect existing tokens or create new ones with the help of a sd-lit-input element.
  • remove-only: there is no sd-lit-input element shown, tokens may only be removed.
  • In addition the property usage of items and selectedIndexes differs. Further information below.
• placeholder : string (default = null)
  • Defines the default text content of the selector if there is no selected token present. Just like a placeholder for an HTML input element.
• suggest-list-class : string (default = null)
  • The classname of the suggestion list.
• aria-disabled : boolean (default = absent)
  • Value true disables the editing possibilities. Any other values or the absence of the attribute means the selector is editable.
• role : string (default = 'listbox')
• aria-multiselectable : boolean (default = true)
• aria-activedescendant : string (default = null)
  • The id attribute of the currently active sd-token.
• aria-haspopup : string (default = 'listbox')
  • Set only for multi selection mode when the selector has a listbox popup.
• token-type : string (default = null)
  • Shown as a drag shadow suffix after the amount when moving multiple tokens. Without it the drag source is used as a drag image with an indicator from the amount of additional selected tokens.
• drop : boolean (default = absent)
  • Present with empty value when the selector is a potential drop candidate.
• drag-source: boolean (default = absent)
  • Present with empty value while an active dragging started from this selector.
• case-sensitive : boolean (default = absent)
  • Based on its presence - regardless the value - the token-selector differentiates values with or without case sensitive checking.

Properties - Token-Selector

• selectionMode : string (default = "multi")
  • Reflects the corresponding attribute.
• items : array (default = empty)
  • The data to be used by the token-selector.
  • remove-only
    • The passed items are directly visualized as tokens
  • multi select
    • The passed items are used as the datasource of the token-selector.
    • Based on this datasource, tokens are visualized when selectedIndexes are present.
    • In addition the datasource is used for the token suggestions, which will be shown when the user starts typing.
• selectedIndexes : array (default = empty)
  • The indexes of the currently selected items.
  • Only relevant when the selection mode is multi
• placeholder : string (default = null)
  • Reflects the corresponding attribute.
• suggestListClass : string (default = null)
  • Reflects the suggest-list-class attribute.
• disabled : boolean (default = false)
  • Reflects the aria-disabled attribute.
• tokenGenerator: Default value is the one from the token element.
  • Tokens can be further customized in addition to the regular properties.
• autoSuggestItemGenerator: Default value is the one from the list-item element.
  • Auto suggest items can be further customized in addition to the regular properties.
• tokenType : string (default = null)
  • Reflects the token-type attribute.
• caseSensitive : boolean (default = null)
  • Reflects the case-sensitive attribute.
• suggestionFilter: Function (searchTerm: string, allTokens: TokenData[]) => TokenData[]
  • A custom filter function can be passed to override the default caption based search of suggestions.

In addition it allows to inject elements with slot named additional-content that is shown right after the tokens part.

Attributes/properties - delegated to the internal sd-lit-input

• placeholder : string (default = null)
• inputLabel : string (default = null)
• validationMessage : string (default = null)
• validationIconSrc : string (default = null)
• validationLevel : string (default = null)

Attributes - Token

• value : string (default = "")
  • The displayed value of the token.
• type : string (default = "")
  • The type of the token. Used to mark tokens by usecases.
• aria-disabled : boolean (default = false)
  • Indicates if the token can be edited or removed for example. An edited token may provide a delete button as well.
• aria-current : boolean (default = false)
  • Indicates if the token is the active descendant of the relevant sd-token-selector.
• aria-checked : boolean (default = false)
  • Indicates if the token is checked for potentially batch actions like removal or drag and drop.
• aria-selected : boolean (default = true)
• Set to true initially since every visible token element in a sd-token-selector can be considered as selected. The non-selected ones are not present in the DOM normally.

Properties - Token

• value, type
  • Reflect the corresponding attributes.
• icon: string (default = "")
  • Defines the icon url. If present the icon is shown at the start of the token.
• iconPlaceholder : string (default = "")
  • Defines the placeholder icon of the token
• iconBackgroundColor: string (default = "")
  • Defines the background color of the icon container. Only relevant when the icon has a transparent background.
• disabled
  • Reflects the aria-disabled attribute.
• current
  • Reflects the aria-current attribute.
• checked
  • Reflects the aria-checked attribute.

In addition it allows to inject elements with slots named before-icon & after-icon.

CSS Custom Properties & parts

• --sd-token-background-color
  • Defines the background color of the token.
• --sd-token-border
  • Defines the border of the token.
• --sd-token-focused-border
  • Defines the border of the currently active, focused token.
• --sd-token-icon-background-color
  • Defines the icon background color of the token.
• --sd-token-delete-icon-color
  • Defines the color of the delete icon in the default state
• --sd-token-delete-icon-color-hover
  • Defines the color of the delete icon in the hover state
• remove-only-placeholder part
  • Applies to the placeholder text which is shown when the selector has no selection in remove-only mode.
• icon part of tokens
  • Applies to the icon element within the wrapper around it that defines the iconBackgroundColor for example.

Custom Events

• token-clicked
  • Dispatched when a token is clicked.
  • Contains the index of the token in the items list and the referenced HTML Element.
• tokens-removed
  • Dispatched when the remove button of a token is clicked or checked tokens are removed via keyboard.
  • Contains the indexes of the removed tokens in the items list.
  • Contains also an updated list of selectedIndices if the selection-mode is multi.
• tokens-selected
  • Dispatched when an existing and not yet selected token was selected.
  • Contains the indexes of the selected tokens in the items list and the updated selectedIndices.
• token-created
  • Dispatched when a not existing token value was submitted.
  • Contains the value of the new token.
• auto-suggest-initialized
  • Dispatched when the auto suggest popover is shown for the first time.