GrDescriptionList

• the card of an object — the summary of an order, a profile, a document: labels on the left, values in a column on the right;
• technical details — identifiers, hashes, MIME types, versions: a long value wraps instead of pushing the layout apart;
• some of the values are not text — a status badge, a relative time, a link are substituted with a slot on a particular pair;
• there are many pairs — up to four columns fold a long list without tearing the pairs apart;
• metadata as a caption to something else — “Messages: 3 · Created: 12.04” inside a list item: flow lets the pairs run as a line rather than as a column.

A pair is wrapped into a <div>: such nesting is valid by HTML5 and is needed for the layout. That is the very reason the component exists — hand-written markup twice produced a <dl> with bare <div> elements inside. It looked like a list, but it was not a pair of terms: neither for a parser nor for a screen reader was there a property or a value there.

null, undefined and '' give a dash (emptyText, the #empty slot), but the row stays. “The field exists, the value does not” and “the field does not exist” are different statements; a dropped row breaks both the alignment and the reading.

Zero does not count as emptiness: 0 is a value.

inline keeps the labels in a column of labelWidth, otherwise the values shift on every row by the length of the label — exactly what the column is there for.

stackBelow (in pixels) switches the layout to stacked when the container is narrower than the threshold: in a narrow column a fixed label squeezes the value down to one letter per line. It is the container that is measured, not the viewport — pairs live in a narrow card on a wide screen too. Before mounting, the layout that was set applies, so the server render is stable.

The threshold applies only to inline: the column of labels is the only thing that breaks in a narrow container. flow wraps by itself, and there is nothing to replace it with.

columns lays the pairs out with a grid rather than with column-count: a pair is a grid item and is not torn between columns.

The number of columns is chosen by CSS from the width of the container: columns: 4 means “up to four”. If there is room for four, there will be four; if there is room for two, there will be two; and in a column of 290px there will be one.

Media queries are unsuitable here in principle: they measure the screen, while the list lives in a card. On a wide monitor two columns would switch on inside a narrow one, a label of fixed width would eat almost all of the room, and the value would wrap character by character — “30” printed as “3” and “0” on two lines. The number shown becomes wrong, and that is no longer a matter of taste.

The threshold below which a column is not divided is --gr-description-list-column-min (12rem by default). Everything is computed in pure CSS: no measurements, no JS, no divergence between the server and the client.

With inline the threshold is higher: the label and the value stand side by side, so the column has to hold both — labelWidth plus --gr-description-list-value-min (5rem). Without that addition a column as wide as a single label leaves the value a few pixels, and it is the value that then wraps character by character: the same defect, only in other numbers. In stacked and flow the width of the label does not enter the calculation — the value is under it there, not beside it.

inline and stacked both put the pairs one under another. When the pairs are short and serve as a caption to something else — “Messages: 3 · Created: 12.04 · Last: yesterday” inside a list item — a column is not what is needed: what is needed is a line that flows across the width and wraps.

<GrDescriptionList :items="meta" layout="flow" />

The root is not a grid here, so columns, divided and labelWidth do not apply: a line has neither columns nor a row that can be marked off with a rule.

The semantics does not suffer in the process — it is still a real <dl> with dt/dd pairs, not text with colons.

A red label reads as “the field is broken”, although the problem is with the quantity. That is why the tone of a pair colours the <dd> and does not touch the <dt>.

#value-<name> and #label-<name> work for pairs that have a name set: a GrBadge, a relative time and links regularly stand in the pairs. Pairs without a name remain strings — the key exists precisely so that a slot addresses one pair rather than all of them at once.

The component does not edit the values, does not sort the pairs and does not group them into sections. Sections are a GrCard with a title around several lists.