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 | collective-term | - | "Items selected" | no | A text displayed in the head in case >1 items are selected | query-placeholder | - | "Search..." | yes | A text displayed in the search query text input box in case it's empty | 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 | auto-select-children | - | true | yes | Should children also be selected when a parent element is selected? | no-match-infotext| - | "No items available" | no | A text displayed when there is no match for the query input | isLocked | - | false | yes | If true, the component's state can't be modified (eg change selection, search), while interaction that doesn't change it's state are still allowed (eg open/close, change mode, etc.) | reset-label | - | "Reset" | yes | The label for the reset button | clear-label | - | "Clear" | yes | The label for the clear search query button | general-label | - | "" | yes | The label for the whole component. | - | 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.

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.

Methods

| Method | Description |-------------|----- | isOpen() | true if the dropdown is visible, false if not | toggle() | opens/closes the dropdown | open() | opens the dropdown | close() | closes the dropdown

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

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)

Known issues

• searching doesn't expand matched branches (but yellow marks parents' expand button)
• don't yellow-mark the current parent's expand button if a match is only in that parent item, but in no children [currently: any expand btn of a node having a match is yellowed]

Changelog

• 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