EWC treeselect Component

A dropdown box, which presents a hierarchical tree view, including checkbox-based multi-selection and integrated filtering.

Documentation

For features, requirements, specification and test cases, see documentation

Screenshot

API

Attributes and Properties

The following attributes and properties are available and can be modified at runtime:

| Attribute | Property | Default | Run-time modifiable | Description |----------------|------------|---------|---------------------|----- | - | data (setter)| | no | Sets the items ("options"). Please see here for the format and an example. | allow-empty-selection| - | false | yes | Should it be possible to have no element selected at all? false when attribute is missing or set to "false", true otherwise | ignore-case | - | true | no | Should letter casing be ignored in the query input regarding search/filter functionality. false when attribute is missing or set to "false", true otherwise | - | selectCallback (setter) | - | yes | If set, is invoked after a user clicks/enter-keys an item but before it is actually selected/deselected. If callback returns false, no actual de-/selection happens - true permits the de-/selection. | - | selected (getter) | | | Returns array of objects of currently selected items. Each object has "id" and "label" property. | - | texts (setter) | | yes | setting all or a subset of all texts. see here for details. | - | isOpen (getter) | - | | true if the dropdown is visible, false if not | - | toggle (setter) | | yes | opens/closes the dropdown | - | open (setter) | | yes | opens the dropdown | - | close (setter) | | yes | closes the dropdown

selectCallback

The callback receives two parameters: clickedItemData and selectedItems.

• clickedItemData: an object w/ props "id", "label" of the clicked item, as well as "isGoingToBeSelected", which is true in case the user attempts a selection, false in case of deselection.

// Example of clickedItemData:
{id: '11', label: 'Tofu', isGoingToBeSelected: true}

• selectedItems is an array, containing objects (w/ props "id" and "label") of the currently selected items.

reset button

• if the reset button was pressed, the callback will also get invoked. id and label, both is "reset"; isGoingToBeSelected is null in that case.

Event

• onSelected: Is fired when a selection actually happened - i.e.
  • in case selectCallback is omitted: always
  • in case selectCallback is set and returns true

The event's detail property is an array. It contains objects of all selected elements (properties id and label), similar to selected getter.

Style

| Custom Property | Default | Description |---------------------|---------|----- |--dropdown-height | 400px | determines the height of the dropdown

Texts

These are the default texts:

DEFAULT_TEXTS = {
  resetLabel: "Reset",
  clearLabel: "Clear",
  generalLabel: "A list of items",
  collectiveTerm: "Items selected",
  queryPlaceholder: "Search...",
  modeSearch: "Show all",
  modeFilterMatch: "Search results",
  modeFilterSelected: "Show selected",
  aria: {
    queryInput: "Search the list below",
    modeControls: "Filter options",
    prevMatch: "Previous match",
    nextMatch: "Next match",
    checked: "checked",
    unchecked: "unchecked",
    itemList: "Item List",
    expand: "Expand or contract subitems",
    status: "X items selected and Y search matches"  // X and Y are replaced by numbers during runtime
  },
  messages: {
    noContent: "No items available",
    noMatch: "No matching items",
    noSelected: "No items selected"
  }
}

Any or all of these can be modified at runtime by calling the texts setter which accepts an object (full or partial) with properties as shown above.

For example, setting just the "noSelected" text:

theComponent.texts = {messages:{noSelected:"No se seleccionaron elementos"}}

Usage

Installation

npm install @ewc-lib/ewc-treeselect

Import the component in your application:

// Using ES modules
import "@ewc-lib/ewc-css-common/custom-props.css";
import '@ewc-lib/ewc-treeselect';

Note about ewc-css-common

• "ewc-css-common/custom-props.css" is necessary for the correct styling of this component.
• It needs to be imported by the host project because it's not imported by this component implicitly.

Notes

Accessibility

The component is designed with accessibility in mind:

• Keyboard navigable element
• Sufficient color contrast

Browser Support

• Chrome (latest)
• Firefox (latest)
• Edge (latest)

License

European Union Public License (EUPL)

Changelog

• 1.0.0-alpha

  • auto-expand matches
  • a11y announcements
  • search highlight colors
  • configurable texts
  • significant refactoring

• 0.0.8-alpha

  • clear btn keyboard
  • onSelectedCallback for reset-btn,
  • mark nav visible
  • btn sizes
  • prev/next mark btn style/beaviour
  • debounce query input
  • clear-btn hover/focus style
  • autoSelectChildren per item, default false
  • hasCheckbox and isExpanded per item
  • use ewc-css CSS custom props
  • clear-btn styling
  • checkbox visible per item
  • focus list-item and kbd nav
  • hover listitem, expand btn
  • focus head on esc-keypress
  • mouse cursor
  • expanded, disabled and selection announcements
  • expansion settable for each item

• 0.0.7-alpha

  • add config options to demo page
  • collective term support runtime modification
  • focus after kbd opening dropdown

• 0.0.6-alpha

  • fix Missing items in show-selected mode
  • fix Reset btn height
  • Avoid event fired on Collapse/Expand

• 0.0.5-alpha

  • styling

• 0.0.4-alpha

  • improved screenreader support

• 0.0.3-alpha

  • refactoring

• 0.0.2-alpha

  • first alpha RC

• 0.0.1-alpha

  • intial commit