{
  "name": "DescriptionList",
  "source": "src/components/DescriptionList.tsx",
  "propsType": "DescriptionListProps",
  "description": "DescriptionList — label–value pairs: a record's details, a settings\nsummary, a review step.\n\nWHY `<dl>` AND NOT A TABLE OR A GRID OF DIVS\n\nA `<dl>` is the element for name–value groups, and a screen reader says\nso: it announces a list with its count, and reads each term with its\nvalue. A two-column table claims rows and columns that nobody compares\ndown; a grid of `<div>`s says nothing at all, so \"Owner\" and \"Priya Shah\"\narrive as two unrelated lines. Each pair is wrapped in a `<div>`, which\nHTML allows inside a `<dl>`, so the layouts can style a pair as a unit.\n\nEMPTY IS SAID, NOT DRAWN ONLY\n\nAn unset value is shown as an em dash — the convention every record page\nuses — but \"—\" is read as \"dash\", or skipped, depending on the reader.\nThe dash is hidden from assistive technology and `emptyText` is read in\nits place, so \"Last run: Not set\" is heard where \"Last run: —\" is seen.",
  "import": "import { DescriptionList } from 'ionbase-ui';",
  "status": "stable",
  "summary": "Label–value pairs as a real `<dl>` — a record's details, a settings summary, a wizard's review step. Three layouts; an empty value is shown as \"—\" and read as words.",
  "useWhen": [
    "showing a record's details as named values — Owner, Team, Last run",
    "summarising what was entered before it is submitted — a wizard's review step",
    "a strip of facts under a heading or on a card"
  ],
  "useInstead": [
    {
      "when": "several records share the same fields and are compared down a column",
      "use": "Table",
      "why": "a table is for comparing rows; a description list is one record's values"
    },
    {
      "when": "the values are editable here",
      "use": "SettingRow or a Form",
      "why": "a description list is read-only; an editable value is a field with a label, not a term"
    },
    {
      "when": "a handful of headline numbers",
      "use": "StatTile",
      "why": "a stat leads with the number at display size; a description list reads label first, at body size"
    }
  ],
  "variants": {
    "layout": {
      "horizontal": {
        "use": "the default — a record's details, the term beside its value. Stacks when the list itself is narrower than 24rem"
      },
      "stacked": {
        "use": "a narrow column — a SidePanel, a card's side — term above value"
      },
      "row": {
        "use": "a strip of short facts under a heading or in a card: pairs side by side at their own width, wrapping when out of room"
      }
    }
  },
  "a11y": {
    "requires": [
      "DescriptionListItem children only — each renders a `<div>` holding one `<dt>` and one `<dd>`",
      "`emptyText` in the user's language when the page is not in English"
    ],
    "guarantees": [
      "a `<dl>` of `<dt>` terms and `<dd>` definitions, so each value is read with its term and the list with its count",
      "an empty value — null, undefined, false or '' — is drawn as \"—\" hidden from assistive technology and read as `emptyText` (\"Not set\")",
      "0 is a value, not an empty one",
      "`horizontal` stacks by the list's own width (a container query), so one list is right in a page and in a 22rem panel",
      "long values — IDs, URLs — wrap inside their column rather than overflowing it",
      "horizontal fills its parent's width; stacked and row size to their content, and none collapses in a shrink-to-fit parent such as a card's side column"
    ],
    "notes": [
      "a value can be any content — a Badge, a Link, an Avatar with a name. Keep it to one value per term; several values are one `<dd>` holding a list",
      "the term is text/secondary and the value text/default, so the eye lands on the value"
    ]
  },
  "antiPatterns": [
    {
      "dont": "a grid of <div>s with a label and a value in each",
      "do": "<DescriptionList><DescriptionListItem term=\"Owner\">Priya Shah</DescriptionListItem></DescriptionList>",
      "why": "divs say nothing: \"Owner\" and \"Priya Shah\" are read as two unrelated lines"
    },
    {
      "dont": "a two-column <table> of labels and values",
      "do": "<DescriptionList>",
      "why": "a table announces rows and columns and invites comparing down a column; there is nothing to compare"
    },
    {
      "dont": "<DescriptionListItem term=\"Last run\">—</DescriptionListItem>",
      "do": "<DescriptionListItem term=\"Last run\">{lastRun}</DescriptionListItem> — pass null when there is none",
      "why": "a typed dash is read as \"dash\" or skipped; an empty value is read as \"Not set\""
    }
  ],
  "stylesheet": "src/styles/description-list.css",
  "tokens": [
    "--font-family-sans",
    "--spacing-12",
    "--spacing-2",
    "--spacing-32",
    "--spacing-8",
    "--text-default",
    "--text-secondary",
    "--text-tertiary",
    "--type-body-sm",
    "--type-body-sm-line-height"
  ],
  "props": {
    "layout": {
      "type": "DescriptionListLayout | undefined",
      "required": false,
      "origin": "own",
      "description": "`horizontal` (default): term beside its value, for a record's details —\nit stacks when the list is narrower than 24rem. `stacked`: term above\nvalue, one pair per line, for a narrow column. `row`: stacked pairs side\nby side at their own width, wrapping when out of room — a strip of\nshort facts under a heading.",
      "values": [
        "horizontal",
        "stacked",
        "row"
      ]
    },
    "emptyText": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "What an empty value is read as. It is shown as \"—\", which a screen\nreader reads as \"dash\" or not at all. Default \"Not set\" — pass the\ntranslation."
    },
    "children": {
      "type": "React.ReactNode",
      "required": true,
      "origin": "own",
      "description": "DescriptionListItem children."
    }
  },
  "propCounts": {
    "own": 3,
    "aria": 0,
    "dom": 277,
    "other": 0
  }
}