# DescriptionList Package: @nannier/canvas Version: 4.1.0 Status: source-snapshot (not proof of an npm release) Source SHA-256: 63292636c7ff2f224185aef7c96ac78124f9170a170b90ee11718addfa280643 Source: `src/molecules/description-lists/description-lists.md` Human reference: https://canvas.nannier.com/components/description-lists ## Public imports ```tsx import { DescriptionList } from "@nannier/canvas"; ``` The following examples are source excerpts. Supply application data and handlers; snippets using `tokens` read `const { tokens } = useTheme()` inside a component. Import React hooks from React. Intentional “Don't” examples illustrate unsupported patterns. Key-value pairs in stacked, two-column, or inline-edit layouts. Used for detail panels, settings, and profile views. Rows flagged `update` carry a working in-place editor: Update opens it, Enter or Save commits the new value and fires `onUpdate`, Escape or Cancel dismisses it. `muted` sets each text value as a note beside its term, in the small type and the muted ink, for a list that explains its terms (a key and its effect) rather than reporting data; a node value renders as given, and a platform skin whose value detail is already the secondary ink keeps its type. The rows axis (pick one; `ruled` wins over `divided`): `divided` draws a hairline under every row but the last, the two-column detail look. `ruled` draws the v4 hand-off's accessibility-card rows: a 1 px top rule on every row, the first included, so the list reads as a table that starts under its caption, each row padded 9 above and below with nothing beside, and in the two-column layout the term hugging its content over a 120 floor with 14 to the value. The density axis: `compact` tightens the ruled rows to the hand-off's semantics-card rows, each padded 8 above and below with 12 to the value, the two-column term a fixed 110 column, and the value at the top of its row (so a wrapping row of badges starts level with its term); the plain and divided rows have no compact step, so `compact` without `ruled` changes nothing. ## Usage ```tsx ``` ## Variants ### Card ```tsx ``` ### Inline Each value sits on the right of its term. A value too wide to fit beside its term (a long id with its Copy button in a narrow sidebar) wraps onto its own line under the term, still at the trailing edge, so the list never runs past its container. ```tsx ``` ### Rich values A row's value can compose real atoms: `status`/`badge` render Badges, `avatars` renders an overlapping AvatarGroup (`overflow` folds the rest into its "+N" chip), and `copyValue` appends a ghost Copy button that hands the string to `onCopy` (wire your clipboard there). ```tsx ``` ### Node values A `term` or `value` may be any node, as a DataTable cell may: a string or number takes the list's own type and the per-item forms (`badge`, `status`, `mono`, `copyValue`, `update`), and any other node renders as given in its place, here a row of Badges. A node value yields to its cell, so a wrapping Row wraps at the cell's width instead of running past the list. An `update` row needs a text value to edit. ```tsx button }, { term: "States", value: disabledbusyloadingpressedfocusedhovered }, { term: "Keyboard", value: "Enter and Space activate it" } ]} /> ``` ### Ruled Every row carries a top rule, the first included, under a caption the parent sets; the term hugs its content over a 120 floor. ```tsx Enter, value: "Activates" }, { term: Space, value: "Activates" }, { term: Tab, value: "Moves focus to the next control" } ]} /> ``` ### Compact ruled The semantics-card rows: 8 above and below, 12 to the value, the term a fixed 110 column and the value at the top of its row. ```tsx button }, { term: "States", value: disabledbusyloadingpressedfocusedhovered }, { term: "ARIA on web", value: aria-busyaria-disabled } ]} /> ``` ### Inline-edit ```tsx ``` ### Muted notes Each value explains its term: a key and what it does, the value in the small type and the muted ink. ```tsx Enter, value: "Activates" }, { term: Space, value: "Activates" }, { term: Tab, value: "Moves focus on" } ]} /> ``` ## Do & Don't ### Two-column **Do** — Fix the label column wide enough for the longest term so every value lines up on one edge. ```tsx ``` **Don't** — A too-narrow label column wraps the longest term and knocks the two columns out of alignment. ```tsx Client identifier clnt_01H2X8K9P3Q7VN4W6R5T0JYMZF Status Active ``` ### Inline-edit **Do** — Give every editable row a trailing Update affordance so the inline editor is discoverable; pressing it opens the editor in place, and Enter or Save commits. ```tsx ``` **Don't** — Editable rows that look identical to read-only ones give no hint a value can be changed. ```tsx ``` ### Stacked **Do** — Keep the label small, uppercase, and muted above a full-weight value so the data stays primary. ```tsx ``` **Don't** — Muting the value and bolding nothing inverts the hierarchy; the label outweighs the data it describes. ```tsx Full name Rachel Chen Email rachel.chen@example.com ``` ## Supported props ### DescriptionListProps | Prop | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | items | DescriptionListItem[] | yes | | | | title | string \| undefined | no | | Card header band (only shown when `card`): a title and optional subtitle. | | subtitle | string \| undefined | no | | Card header band (only shown when `card`): a title and optional subtitle. | | inline | boolean \| undefined | no | false | Layout (pick one; precedence inline > twoColumn > stacked). | | twoColumn | boolean \| undefined | no | false | Layout (pick one; precedence inline > twoColumn > stacked). | | stacked | boolean \| undefined | no | false | Layout (pick one; precedence inline > twoColumn > stacked). | | divided | boolean \| undefined | no | false | Rows (pick one; precedence ruled > divided): a hairline divider beneath every row but the last. | | ruled | boolean \| undefined | no | false | Rows: a 1 px top rule on every row, the first included, with the row padded 9 above and below and the term hugging its content (a 120 floor, 14 to the value), the v4 hand-off's accessibility-card rows. Wins over `divided`. | | compact | boolean \| undefined | no | false | Density: tightens the ruled rows to the v4 hand-off's semantics-card rows (Component.dc.html line 263): 8 above and below the text, 12 to the value, the term a fixed 110 column and the value at the top of its row. Only the ruled rows have a compact step; a plain or divided list is unchanged by it. | | muted | boolean \| undefined | no | false | The values as notes beside their terms: a text value in the small type and the muted ink (400 13/19) instead of the full-weight foreground data, for a list that explains each term (a key and its effect). A node value renders as given, and a platform skin whose value detail is already the secondary ink keeps its type. | | card | boolean \| undefined | no | false | Surface: wrap the list in a card surface. | | onUpdate | ((index: number, value: string) => void) \| undefined | no | | Fires when a row's inline editor commits (Enter or Save): the item index and the new value. | | onCopy | ((value: string) => void) \| undefined | no | | Fires with a row's `copyValue` when its "Copy" button is pressed. | | testID | string \| undefined | no | | E2E hook forwarded to the root element. | | style | LayoutStyle | no | | Composition within a parent only, never a restyle hook and never a width: the parent layout container provides the bounds. | See [installation](https://canvas.nannier.com/ai/4.1.0/installation.md) for required peers and feature fallbacks.