@cas-smartdesign/list 6.3.0

package/readme.md

@@ -0,0 +1,71 @@
+# @cas-smartdesign/list
+
+An element that renders a given array of items in a list.
+
+## Attributes
+
+- `selection-type`: string
+  - Defines the type of selection that the list uses. Allowed values are:
+    - `single`: the list items can be selected one at a time, the `selected` attribute is set on the selected item
+    - `extended`: multiple list items can be selected, the `selected` attribute is set on the selected items
+    - `trigger-only`: the `selected` attribute is not set on the selected item(s)
+- `role`: string
+  - Aria attribute, default value is "list"
+
+## Properties
+
+- `items`: array
+  - The data to be used by the list.
+- `itemGenerator`: ItemGenerator
+  - A function that creates a HTMLElement from an element of the `items` array to be rendered by the list.
+  - If it is not set then the default implementation is used.
+- `selectedIndexes`: array
+  - The indexes of the currently selected items.
+
+## CSS Custom Properties
+
+- `--sd-list-base-background-color`
+  - Defines the background color of the list
+  - This is only present due to backward compatibility reasons, as it might be easier to change the background of an item with regular css rules
+
+## Custom Events
+
+- `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 `hasModifier` property is true if mouse wheel or ctrl/meta key is down while selection. Note that the auto scroll feature is disabled while middle mouse click.
+
+## Public methods
+
+- `getListItem`
+  - Returns the DOM node that represents the item with the given index
+- `increaseWidthIfNeeded`
+  - The width of the list is increased 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
+
+## Selection state
+
+The list marks the items with `selected` attribute in case if they are selected, but does not define any style for this state.
+The items generated by the `itemGenerator` can use this attribute if custom logic is required.
+
+## 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`.
+
+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.
+
+## Examples