name: List
purpose: Render flat, grouped, tree, or virtualized item lists with declarative selection and slots.

appearance:
  default: Compact borderless rows with a transparent background and small text.
  selected: Theme-primary text emphasis without a filled active background.
  summary: Uses opacity-75 so it stays visually secondary while inheriting the selected row color.
  tree: Uses compact pt-1/pb-0 spacing; expandable parent nodes use the caret without a second folder icon.

attributes:
  mode: [normal, group, tree]
  fast: "boolean — virtual scrolling"
  collapsible: "boolean — collapsible tree nodes"
  auto-select: "boolean — clicked item id -> selectedItem"
  auto-select-group: "boolean — clicked group id -> selectedGroup"
  idfield: id
  labelfield: label
  summaryfield: summary
  groupidfield: id
  grouplabelfield: label
  groupsummaryfield: summary
  groupfield: group
  parentfield: parent
  iconfield: "Optional item field containing a Bootstrap Icons suffix; falls back to itemicon when empty."

state:
  list: 'Array of item objects. Declarative form: `$.state.list="users"`.'
  groups: 'Array of group objects when mode=group. Declarative form: `$.state.groups="groups"`.'
  filter: String or object filter.
  order: Field name, `-name`, or `name desc`.
  selectedItem: Selected item id (written by auto-select).
  selectedGroup: Selected group id (written by auto-select-group).

properties:
  filterFunc: Custom item predicate.
  orderFunc: Custom sorting comparator.

methods:
  collapseAll: "Collapse every parent node when mode=tree and collapsible is enabled."
  expandAll: "Expand every parent node when mode=tree and collapsible is enabled."
  isAllCollapsed: "Return whether every expandable tree node is collapsed."
  toggleAll: "Expand a fully collapsed tree, otherwise collapse all expandable nodes."

events:
  change:
    detail: selectedItem
  itemclick:
    detail: "{ item, index }"
  groupclick:
    detail: "{ item, index }"

slots:
  item: Replace the complete item row.
  item-actions: Render at the right side of every item row.
  group-actions: Render at the right side of every group row.

rules:
  - With fast, a custom item row must retain list-group-item and $onupdate.
  - Use event.stopPropagation() for action controls that must not select the row.
  - 'Non-default field mapping is declarative: `idfield="key" labelfield="title" summaryfield="desc"`.'
  - 'Per-item icons are opt-in: set `iconfield="icon"`; values such as `person` render the `bi-person` class and empty values fall back to itemicon.'
  - 'Tree toolbars may call `collapseAll()`, `expandAll()`, or `toggleAll()`; these methods are no-ops outside a collapsible tree.'
  - Default label and summary areas truncate to one line. The primary label keeps its natural width up to 75%; the fill summary receives at least 25% and uses the remaining width. An empty summary leaves the full row to the label. Slotted item-actions and group-actions preserve application-provided layout classes, including wrapping behavior.

examples: |
  <script>
    const users = [
      { id: 'ada', label: 'Ada', summary: 'Admin', icon: 'person' },
      { id: 'lin', label: 'Lin', summary: 'Editor', icon: 'pencil' }
    ]
    const groups = [{ id: 'ops', label: 'Operations' }]
    const groupedUsers = [{ id: 'ada', label: 'Ada', group: 'ops' }]
    const treeUsers = [
      { id: 'root', label: 'Root', parent: '' },
      { id: 'child', label: 'Child', parent: 'root' }
    ]
  </script>

  <List $.state.list="users" auto-select></List>

  <List $.state.list="users" iconfield="icon"></List>

  <List $.state.list="users" auto-select>
    <button slot="item-actions" $onclick="event.stopPropagation(); edit(item)">Edit</button>
  </List>

  <List mode="group" $.state.groups="groups" $.state.list="groupedUsers"></List>

  <List mode="tree" collapsible $.state.list="treeUsers"></List>

  <List fast $.state.list="users"></List>

data_shape:
  item: "{ id, label, summary }"
  group: "{ id, label, summary }"
  tree_item: "{ id, label, summary, parent }"

tests:
  - List.test.html