@cas-smartdesign/virtual-list

A list element with ui-virtualization and infinite scrolling.

Attributes

- item-height
- Defines the height in px of the list items.
- item-count
- Defines the virtual number of items in the list.
- selection-type
- Defines the mode of selection handling
- Available values: "trigger-only", "single", "multi"
- focus-index
- Defines the index of currently focused item
- role: string
- Aria attribute, default value is "list"

Properties

The following properties are available:

- items _any[] (default=empty)_
- Contains data for the currently rendered list items.
- itemGenerator _ItemGenerator (default is the generator inside the list-item element)_
- A method that renders the list items.
- itemHeight _number (default=50)_
- Reflects the corresponding attribute
- itemCount _number (default=0)_
- Reflects the corresponding attribute
- selectionType _string (default="trigger-only")_
- Reflects the corresponding attribute
- focusIndex _number (default=undefined)_
- Reflects the corresponding attribute
- selectedIndices _number[] (default=empty)_
- Contains the indices of the selected items.

CSS Custom Properties

- --sd-virtual-list-focus-highlight-color
- Defines the focus highlight color for list items, defaults to #1467ba
- --sd-virtual-list-item-separator-color
- Defines the separator color for list items, defaults to #d9d9d9

Custom events

- data-request
- Sent after scrolling the list
- Contains the starting and ending index that is visible in the list
- selection
- Dispatched when one of the items is selected/deselected
- Contains the index of the item and a selected flag which is when false indicates that the item is deselected
- The originalEvent a mouse or keyboard event that triggered the selection event.

Public methods

- getListItem
- Returns the DOM node that represents the item with the given index
- Note that only visible items can be accessed this way
- scrollToItem
- Scrolls the list to the item with the given index
- increaseWidthOnNextRenderIfNeeded
- The width of the list is increased on the next rendering phase to an extent, that all texts in the list-items are visible without ellipsis.
- If the list has already reached it's maximum width, then line clamp may be enabled on the items to wrap the content if possible.
- Note that this functionality works only if sd-list-items are rendered in the list

A11Y

The default _role_ is listbox, with the corresponding option role on the items, since most of the time this element is used with a selection state.
It ensures the items have an associated id which is used to update aria-activedescendant.
The selection is also marked with aria-selected.
The items are updated with the aria-setsize & aria-posinset attributes. The former one is -1 if the final size is not known to indicate infinite scrolling state.

Please note that the selection type trigger-only does not provide any accessibility event in case of a selection,
but it can be added externally for example with an aria-live area where the content can notify about the selection.
Although normally the page would change by such a selection, so it may not be necessary to do this notification.

Attributes managed on items

In addition to above mentioned aria attributes, the items are marked with certain custom attributes:

- focused
- Set if the item is currently focused.
- selected
- Set if the item is selected.
- item-index
- The index of the item.
- last
- Set if the item is the last in the currently rendered set of items.