{
  "tag": "ed-list",
  "kind": "component",
  "summary": "A list of entries that are read rather than compared, with an optional title and actions.",
  "status": "experimental",
  "level": "molecule",
  "since": "1.0",
  "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/list/",
  "usage": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/list/usage/",
  "playwright": "getByTestId('…')",
  "dependencies": [
    "ed-checkbox"
  ],
  "use": [
    "A collection of entries read one by one, where each entry makes sense as a whole",
    "A list of recent documents or messages in a client's file, each with a title, a subtitle and a state, opened one by one"
  ],
  "notFor": [
    {
      "when": "Comparing values across entries",
      "instead": "a [Data Grid](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/data-grid)"
    },
    {
      "when": "Records that contain other records",
      "instead": "a [Tree](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/tree)"
    },
    {
      "when": "The product's navigation",
      "instead": "a [Side Menu](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/side-menu)"
    }
  ],
  "rules": [
    {
      "id": "list/read-not-compare",
      "rule": "Use a list for entries that are read one by one. As soon as users scan one value down all entries — sorting by amount, comparing dates — the data belongs in a [Data Grid](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/data-grid) or a plain `<table>`.",
      "why": "A list is read, a table is compared."
    },
    {
      "id": "list/two-lines",
      "rule": "Keep an entry to two lines: what it is about, and whom it belongs to. Whatever would go into a third line belongs into `end` or onto the detail page.",
      "check": "error"
    },
    {
      "id": "list/identifier-first",
      "rule": "Put an identifier first in the primary line, so a truncated label never cuts it off."
    },
    {
      "id": "list/one-leading-element",
      "rule": "Give every entry the same kind of leading element, or none at all — a spacer of the same width where one entry has nothing to show, so the text starts on one edge. Never give an entry a second leading element.",
      "why": "An icon and an avatar side by side leave open which one leads.",
      "check": "error"
    },
    {
      "id": "list/end-columns",
      "rule": "Give each element in `end` a width of its own when several entries carry it, so states, amounts and dates each line up in their own column.",
      "check": "warning"
    },
    {
      "id": "list/end-order",
      "rule": "Keep the order of trailing information: state, amount, date — from the coarsest to the finest."
    },
    {
      "id": "list/end-no-controls",
      "rule": "Never put a button, a link or any other control into `end` — controls go into `actions`.",
      "why": "`end` is part of the entry's click surface.",
      "check": "error"
    },
    {
      "id": "list/state-badge",
      "rule": "Show a state as a badge with a word, not as a colored entry.",
      "check": "warning"
    },
    {
      "id": "list/action-verb",
      "rule": "Label an entry action with the verb alone — \"Approve\", not \"Approve payroll run\".",
      "why": "The entry already names the object.",
      "check": "warning"
    },
    {
      "id": "list/actions-menu",
      "rule": "From the third action on, move the actions into a dropdown and spell out the object in the menu, where the entry is no longer next to it. Put a destructive action last in that menu, behind a divider ([`dropdown/destructive-last`](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/dropdown/usage#rule-dropdown-destructive-last)).",
      "check": "error"
    },
    {
      "id": "list/same-actions-every-entry",
      "rule": "Treat every entry the same: labeled buttons in every row, or a menu in every row — never a mix.",
      "check": "error"
    },
    {
      "id": "list/href-opens-record",
      "rule": "Use `href` when the entry opens its record, so keyboard, middle click and \"open in new tab\" work — the entry is a real link then."
    },
    {
      "id": "list/lead-or-act",
      "rule": "Never combine `href` and actions in one entry — an entry either leads to its record or carries actions of its own. An item with `href` does not render `actions` and warns in the console.",
      "why": "Every click becomes a guess.",
      "check": "error"
    },
    {
      "id": "list/next-icon",
      "rule": "Don't add your own sign that an entry leads on — the `next` icon is it. Replace it through `navigation-icon` only for a link that leaves the product.",
      "check": "error"
    },
    {
      "id": "list/scroll-height",
      "rule": "Give a list that should scroll a height on `ed-list` itself, or let a flex or grid parent limit it — only its body scrolls then, and the frame, the head and the group heads stay. Never wrap it in a scrolling element instead.",
      "why": "The frame and the head would scroll away with it.",
      "check": "error"
    },
    {
      "id": "list/group-one-dimension",
      "rule": "Group by one dimension only — by day or by client, not both — and never nest one group inside another; the inner group warns in the console.",
      "check": "error"
    },
    {
      "id": "list/group-count",
      "rule": "Don't add your own count to a group — every group names its count.",
      "check": "warning"
    },
    {
      "id": "list/timeline-groups",
      "rule": "Name the groups of a timeline \"Today\" and \"Yesterday\" within the week, and give dates before that."
    },
    {
      "id": "list/heading-label",
      "rule": "Slot a heading element into `label` when the title is a section heading of the page."
    },
    {
      "id": "list/plain-inside-containers",
      "rule": "Use `appearance=\"plain\"` for a list inside a card, a drawer or a side panel.",
      "check": "error"
    },
    {
      "id": "list/truncate-per-line",
      "rule": "Opt into truncation per line with `ed-text-truncate` where a column is too narrow for its text."
    },
    {
      "id": "list/disable-the-action",
      "rule": "Disable an action on the action itself when it is unavailable for one entry; `disabled` on the entry is for entries that lead somewhere or can be selected.",
      "check": "error"
    },
    {
      "id": "list/selectable-for-bulk",
      "rule": "Make a list `selectable` when an action acts on several entries at once, and put those bulk actions into the head's `actions`. Never make a list selectable for an action that acts on one entry — put it into that entry's `actions`.",
      "check": "warning"
    },
    {
      "id": "list/open-from-selectable",
      "rule": "Open an entry's record through an action in a selectable list — a selectable entry does not lead anywhere: `href` is ignored there and warns.",
      "check": "error",
      "covered": true
    },
    {
      "id": "list/empty-selection-actions",
      "rule": "Keep the bulk actions visible and disabled while nothing is selected; the count line's \"0 of n selected\" says why. Never hide them, as [`toolbar/unavailable-actions`](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/toolbar/usage#rule-toolbar-unavailable-actions) asks for any unavailable action.",
      "why": "An action nobody sees is one nobody looks for."
    },
    {
      "id": "list/selection-beyond-view",
      "rule": "Keep the selection when users page or filter, and say how much of it is out of view — the product does that beside the list; the list itself does not. A selected entry hidden with `hidden` stays in `selectedItems`, while the count line counts only the entries in view."
    },
    {
      "id": "list/select-all-expanded",
      "rule": "Don't expect select-all to take the entries of a collapsed group — it acts on what is expanded, while the count line counts the whole list."
    },
    {
      "id": "list/dividers",
      "rule": "Don't add your own separators between entries — the list draws a divider between them.",
      "why": "Rows separated by spacing alone read as one block of text.",
      "check": "error"
    },
    {
      "id": "list/no-card-per-entry",
      "rule": "Never wrap each entry in a card to make it look heavier.",
      "why": "A card per row fills two screens with frames around nothing.",
      "check": "error"
    }
  ],
  "api": {
    "attributes": [
      {
        "name": "label",
        "property": "label",
        "type": "string",
        "default": "''",
        "description": "The title, which also names the list. For a heading element, use the `label` slot instead."
      },
      {
        "name": "appearance",
        "property": "appearance",
        "type": "'outlined' | 'plain'",
        "default": "'outlined'",
        "description": "`outlined` draws the frame; `plain` has none, for a list inside a card, drawer or side panel."
      },
      {
        "name": "selectable",
        "property": "selectable",
        "type": "boolean",
        "default": "false",
        "description": "Gives every entry a checkbox and the head a select-all box and a count."
      },
      {
        "name": "dir",
        "property": "dir",
        "type": "string"
      },
      {
        "name": "lang",
        "property": "lang",
        "type": "string"
      }
    ],
    "properties": [
      {
        "name": "selectedItems",
        "type": "EdListItem[]",
        "description": "The selected, enabled entries, in document order — hidden ones included: a filter that hides an\nentry leaves its selection alone."
      }
    ],
    "methods": [
      {
        "name": "getPropertyDescriptor",
        "static": true,
        "parameters": [
          {
            "name": "name",
            "type": "PropertyKey"
          },
          {
            "name": "key",
            "type": "string | symbol"
          },
          {
            "name": "options",
            "type": "PropertyDeclaration"
          }
        ],
        "returns": "PropertyDescriptor | undefined",
        "description": "Wraps the accessor of reflected properties so they always hold a valid value, as a native\nreflected IDL attribute does (`button.type = undefined` reads `submit`):\n\n- A property that declares `useDefault` takes the first value set on an element for its\n  default. That value is its field initializer's: the constructor has finished before markup,\n  a framework or any other code can set anything. Every later `null` or `undefined` means what\n  a dropped prop means on a native element — the attribute is removed: with the attribute\n  there, it is removed and Lit's `useDefault` restores the default without writing it; without\n  one, the property is set to the default. A value set and cleared again before the element\n  updates still writes the default once, from the pending reflection.\n- A Boolean is coerced with `Boolean()`, so `undefined` is `false`.\n\nLit's `useDefault` keeps the initial default out of the DOM. Setting the default explicitly\nwrites it, as `button.type = 'submit'` writes `type`."
      }
    ],
    "events": [
      {
        "name": "ed-list-selection-change",
        "react": "onEdListSelectionChange",
        "type": "{ selection: EdListItem[] }",
        "description": "After the user changed the selection, through an entry or the select-all box. `selection` holds every selected, enabled entry, hidden ones included. Not fired when `selected` or `hidden` is set in code."
      }
    ],
    "slots": [
      {
        "name": "",
        "description": "`<ed-list-item>` and `<ed-list-group>` elements."
      },
      {
        "name": "label",
        "description": "The title, which also names the list. Slot a heading when it is a section heading. Alternatively, use the `label` attribute."
      },
      {
        "name": "actions",
        "description": "Buttons in the head; in a selectable list, the bulk actions."
      }
    ],
    "cssProperties": [],
    "parts": [
      {
        "name": "base",
        "description": "The frame."
      },
      {
        "name": "header",
        "description": "The head."
      },
      {
        "name": "select-all",
        "description": "The select-all box in a selectable list."
      },
      {
        "name": "heading",
        "description": "The wrapper of the title and the count line in a selectable list."
      },
      {
        "name": "label",
        "description": "The wrapper of the title."
      },
      {
        "name": "count",
        "description": "The count line of a selectable list, \"0 of n selected\" included."
      },
      {
        "name": "actions",
        "description": "The wrapper of the `actions` slot."
      },
      {
        "name": "items",
        "description": "The element carrying the list role. It scrolls while the head stays, once the list's height is limited."
      },
      {
        "name": "live-region",
        "description": "Where the list announces the count after a change. Visually hidden."
      }
    ],
    "states": []
  },
  "import": "import '@eurodata/eurodata-ui/dist/components/list/list.js';",
  "react": {
    "component": "EdList",
    "import": "import EdList from '@eurodata/eurodata-ui/dist/react/list/index.js';"
  }
}