@marianmeres/stuic 3.174.0 → 3.176.0

package/AGENTS.md

@@ -23,7 +23,7 @@
 
 ```
 src/lib/
-├── components/     # 78 component directories
+├── components/     # 79 component directories
 ├── actions/        # 16 Svelte actions (use: directives)
 ├── attachments/    # Svelte attachments ({@attach} — preferred for new DOM helpers)
 ├── utils/          # 55 utility modules (48 on the barrel)
@@ -146,7 +146,7 @@ so it is the only confusable pair — do not "fix" one into the other.
 
 ### Domain Docs
 
-- [Components](./docs/domains/components.md) — 78 component directories, Props pattern, snippets
+- [Components](./docs/domains/components.md) — 79 component directories, Props pattern, snippets
 - [Theming](./docs/domains/theming.md) — CSS tokens, dark mode, themes
 - [CSS presets](./docs/domains/css-presets.md) — ratio-locked frame (letterbox), safe-area, scrollbar
 - [Actions](./docs/domains/actions.md) — 16 Svelte directives

package/dist/components/DataTable/DataTable.svelte

@@ -237,7 +237,7 @@
 	import Button from "../Button/Button.svelte";
 	import EmptyState from "../EmptyState/EmptyState.svelte";
 	import Pagination from "../Pagination/Pagination.svelte";
-	import Thc, { isTHCNotEmpty, getTHCStringContent } from "../Thc/Thc.svelte";
+	import Thc, { isTHCNotEmpty } from "../Thc/Thc.svelte";
 
 	let {
 		columns,
@@ -746,7 +746,7 @@
 							<div class={!unstyled ? "stuic-data-table-card-row" : undefined}>
 								<span class={!unstyled ? "stuic-data-table-card-label" : undefined}>
 									{#if isTHCNotEmpty(col.label)}
-										{getTHCStringContent(col.label) || col.key}
+										<Thc thc={col.label!} />
 									{:else}
 										{col.key}
 									{/if}

package/dist/components/DescriptionList/DescriptionList.svelte

@@ -0,0 +1,262 @@
+<script lang="ts" module>
+	import type { HTMLAttributes } from "svelte/elements";
+	import type { Snippet } from "svelte";
+	import type { THC } from "../Thc/Thc.svelte";
+
+	/** Row shape: label above value, label beside value, or the former until there is room */
+	export type DescriptionListLayout = "auto" | "stacked" | "columns";
+
+	/**
+	 * Where `layout="auto"` switches to columns, measured on the list's OWN inline size.
+	 * The names and numbers of Tailwind's `@xs`…`@xl` container variants.
+	 */
+	export type DescriptionListColumnsFrom = "xs" | "sm" | "md" | "lg" | "xl";
+
+	/** Hairlines: between rows only, around the whole list, or none */
+	export type DescriptionListDivide = "none" | "inside" | "outside";
+
+	/** How a long value behaves */
+	export type DescriptionListWrap = "anywhere" | "truncate" | "normal";
+
+	/** Text alignment of the value column */
+	export type DescriptionListValueAlign = "start" | "end";
+
+	export interface DescriptionListItem {
+		/** Keyed `{#each}` identity. Falls back to the index. */
+		key?: string | number;
+		/** The term (`<dt>`) */
+		label: THC;
+		/**
+		 * The details (`<dd>`). A number is `String()`-ed. `undefined`, `null` or `""`
+		 * → `emptyValue` (`null` is accepted because that is what an API row holds).
+		 */
+		value?: THC | number | null;
+		/**
+		 * A second `<dd>` under the value — a unit, a qualifier, a "vs. last month".
+		 * In the columns state it sits under the value column, never under the label.
+		 */
+		description?: THC | null;
+		/**
+		 * Wraps the value in `<a href>`. Plain link only; anything more (`target`, `rel`,
+		 * `onclick`) is the snippet / `children` form — same rule as `Stat` and `Timeline`.
+		 */
+		href?: string | null;
+		/**
+		 * `title` attribute on the value `<dd>`. When the effective wrap is `"truncate"`
+		 * and `value` is a non-empty plain string, it defaults to that value — a clipped
+		 * value must stay reachable.
+		 */
+		title?: string;
+		/** `lang` on the `<dt>` */
+		labelLang?: string;
+		/** `lang` on the value `<dd>` */
+		valueLang?: string;
+		/** `data-emphasis` on the row: full-strength label color and semibold value — the *Total* row */
+		emphasis?: boolean;
+		/** Per-row override of the list's `wrap` */
+		wrap?: DescriptionListWrap;
+		/** Class for this row (`div`), merged after `classItem` */
+		class?: string;
+		/** Class for this row's `<dt>`, merged after `classLabel` */
+		classLabel?: string;
+		/** Class for this row's value `<dd>`, merged after `classValue` */
+		classValue?: string;
+		/** Class for this row's description `<dd>`, merged after `classDescription` */
+		classDescription?: string;
+	}
+
+	export interface DescriptionListSnippetArg {
+		item: DescriptionListItem;
+		index: number;
+	}
+
+	export interface Props extends Omit<HTMLAttributes<HTMLDListElement>, "children"> {
+		/** The rows, in order. Data-driven form. */
+		items?: DescriptionListItem[];
+		/**
+		 * Compositional form: rendered inside the `<dl>` *instead of* `items`. Write
+		 * `<div><dt>…</dt><dd>…</dd></div>` per row; the structural CSS styles it identically.
+		 */
+		children?: Snippet;
+		/**
+		 * `"stacked"`: label above value, always. `"columns"`: label beside value, always.
+		 * `"auto"` (default): stacked until the list itself is `columnsFrom` wide, then columns.
+		 */
+		layout?: DescriptionListLayout;
+		/**
+		 * The **list's own** inline size at which `"auto"` switches to columns:
+		 * 20 / 24 / 28 / 32 / 36rem. Ignored unless `layout="auto"`.
+		 */
+		columnsFrom?: DescriptionListColumnsFrom;
+		/**
+		 * `"inside"` (default): a hairline *between* rows only (a list inside a card, drawer
+		 * or panel — the box supplies the outer edge). `"outside"`: plus one above the first
+		 * and below the last (a list loose on a page). `"none"`: no rules.
+		 */
+		divide?: DescriptionListDivide;
+		/**
+		 * How a long value behaves. `"anywhere"` (default) never lets a value push the page
+		 * sideways. `"truncate"` clips to one line with an ellipsis. `"normal"` leaves the
+		 * browser default. Per-item override via `item.wrap`.
+		 */
+		wrap?: DescriptionListWrap;
+		/**
+		 * Text alignment of the value column. `"end"` is the totals shape — pair it with
+		 * `--stuic-description-list-label-width: 1fr`.
+		 */
+		valueAlign?: DescriptionListValueAlign;
+		/**
+		 * Rendered in the `<dd>` when an item's `value` is `undefined`, `null` or `""`.
+		 * Pass `""` to render an empty cell.
+		 */
+		emptyValue?: THC;
+		/** Override the `<dt>` content for every row */
+		renderLabel?: Snippet<[DescriptionListSnippetArg]>;
+		/** Override the value `<dd>` content for every row */
+		renderValue?: Snippet<[DescriptionListSnippetArg]>;
+		/** Override the whole row *content* (the `<div>` stays — it is what the grid is on) */
+		renderItem?: Snippet<[DescriptionListSnippetArg]>;
+		/** Skip all default styling */
+		unstyled?: boolean;
+		/** Additional CSS classes */
+		class?: string;
+		/** Class for every row (`div`) */
+		classItem?: string;
+		/** Class for every `<dt>` */
+		classLabel?: string;
+		/** Class for every value `<dd>` */
+		classValue?: string;
+		/** Class for every description `<dd>` */
+		classDescription?: string;
+		/** Bindable element reference */
+		el?: HTMLDListElement;
+	}
+</script>
+
+<script lang="ts">
+	import { twMerge } from "../../utils/tw-merge.js";
+	import Thc, { isTHCNotEmpty } from "../Thc/Thc.svelte";
+
+	let {
+		items,
+		children,
+		layout = "auto",
+		columnsFrom = "sm",
+		divide = "inside",
+		wrap = "anywhere",
+		valueAlign = "start",
+		emptyValue = "—",
+		renderLabel,
+		renderValue,
+		renderItem,
+		unstyled = false,
+		class: classProp,
+		classItem: classItemProp,
+		classLabel: classLabelProp,
+		classValue: classValueProp,
+		classDescription: classDescriptionProp,
+		el = $bindable(),
+		...rest
+	}: Props = $props();
+
+	/** Emptiness of a VALUE is deliberately not `isTHCNotEmpty`: `0` is a value, not empty. */
+	const _isEmptyValue = (v: THC | number | undefined | null): boolean =>
+		v === undefined || v === null || v === "";
+
+	const _value = (item: DescriptionListItem): THC => {
+		if (_isEmptyValue(item.value)) return emptyValue;
+		return typeof item.value === "number" ? String(item.value) : (item.value as THC);
+	};
+
+	const _wrap = (item: DescriptionListItem): DescriptionListWrap => item.wrap ?? wrap;
+
+	// A clipped value must stay reachable. Only a plain string can become a title —
+	// html/component/snippet values have no string to put there (pass `item.title`).
+	const _title = (item: DescriptionListItem): string | undefined => {
+		if (item.title !== undefined) return item.title;
+		if (_wrap(item) !== "truncate") return undefined;
+		return typeof item.value === "string" && item.value !== "" ? item.value : undefined;
+	};
+
+	let _class = $derived(
+		unstyled ? classProp : twMerge("stuic-description-list", classProp)
+	);
+
+	const _classItem = (item: DescriptionListItem) =>
+		unstyled
+			? twMerge(classItemProp, item.class)
+			: twMerge("stuic-description-list-item", classItemProp, item.class);
+
+	const _classLabel = (item: DescriptionListItem) =>
+		unstyled
+			? twMerge(classLabelProp, item.classLabel)
+			: twMerge("stuic-description-list-label", classLabelProp, item.classLabel);
+
+	const _classValue = (item: DescriptionListItem) =>
+		unstyled
+			? twMerge(classValueProp, item.classValue)
+			: twMerge("stuic-description-list-value", classValueProp, item.classValue);
+
+	const _classDescription = (item: DescriptionListItem) =>
+		unstyled
+			? twMerge(classDescriptionProp, item.classDescription)
+			: twMerge(
+					"stuic-description-list-description",
+					classDescriptionProp,
+					item.classDescription
+				);
+
+	// An empty list with `divide="outside"` would draw two rules around a void.
+	let _render = $derived(!!children || !!items?.length);
+</script>
+
+{#if _render}
+	<dl
+		bind:this={el}
+		class={_class}
+		data-layout={!unstyled ? layout : undefined}
+		data-columns-from={!unstyled && layout === "auto" ? columnsFrom : undefined}
+		data-divide={!unstyled ? divide : undefined}
+		data-wrap={!unstyled ? wrap : undefined}
+		data-value-align={!unstyled ? valueAlign : undefined}
+		{...rest}
+	>
+		{#if children}
+			{@render children()}
+		{:else}
+			{#each items ?? [] as item, index (item.key ?? index)}
+				<div
+					class={_classItem(item)}
+					data-emphasis={!unstyled && item.emphasis ? "" : undefined}
+					data-wrap={!unstyled ? item.wrap : undefined}
+				>
+					{#if renderItem}
+						{@render renderItem({ item, index })}
+					{:else}
+						<dt class={_classLabel(item)} lang={item.labelLang}>
+							{#if renderLabel}
+								{@render renderLabel({ item, index })}
+							{:else}
+								<Thc thc={item.label} />
+							{/if}
+						</dt>
+						<dd class={_classValue(item)} lang={item.valueLang} title={_title(item)}>
+							{#if renderValue}
+								{@render renderValue({ item, index })}
+							{:else if item.href}
+								<a href={item.href}><Thc thc={_value(item)} /></a>
+							{:else}
+								<Thc thc={_value(item)} />
+							{/if}
+						</dd>
+						{#if isTHCNotEmpty(item.description)}
+							<dd class={_classDescription(item)}>
+								<Thc thc={item.description!} />
+							</dd>
+						{/if}
+					{/if}
+				</div>
+			{/each}
+		{/if}
+	</dl>
+{/if}

package/dist/components/DescriptionList/DescriptionList.svelte.d.ts

@@ -0,0 +1,127 @@
+import type { HTMLAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
+import type { THC } from "../Thc/Thc.svelte";
+/** Row shape: label above value, label beside value, or the former until there is room */
+export type DescriptionListLayout = "auto" | "stacked" | "columns";
+/**
+ * Where `layout="auto"` switches to columns, measured on the list's OWN inline size.
+ * The names and numbers of Tailwind's `@xs`…`@xl` container variants.
+ */
+export type DescriptionListColumnsFrom = "xs" | "sm" | "md" | "lg" | "xl";
+/** Hairlines: between rows only, around the whole list, or none */
+export type DescriptionListDivide = "none" | "inside" | "outside";
+/** How a long value behaves */
+export type DescriptionListWrap = "anywhere" | "truncate" | "normal";
+/** Text alignment of the value column */
+export type DescriptionListValueAlign = "start" | "end";
+export interface DescriptionListItem {
+    /** Keyed `{#each}` identity. Falls back to the index. */
+    key?: string | number;
+    /** The term (`<dt>`) */
+    label: THC;
+    /**
+     * The details (`<dd>`). A number is `String()`-ed. `undefined`, `null` or `""`
+     * → `emptyValue` (`null` is accepted because that is what an API row holds).
+     */
+    value?: THC | number | null;
+    /**
+     * A second `<dd>` under the value — a unit, a qualifier, a "vs. last month".
+     * In the columns state it sits under the value column, never under the label.
+     */
+    description?: THC | null;
+    /**
+     * Wraps the value in `<a href>`. Plain link only; anything more (`target`, `rel`,
+     * `onclick`) is the snippet / `children` form — same rule as `Stat` and `Timeline`.
+     */
+    href?: string | null;
+    /**
+     * `title` attribute on the value `<dd>`. When the effective wrap is `"truncate"`
+     * and `value` is a non-empty plain string, it defaults to that value — a clipped
+     * value must stay reachable.
+     */
+    title?: string;
+    /** `lang` on the `<dt>` */
+    labelLang?: string;
+    /** `lang` on the value `<dd>` */
+    valueLang?: string;
+    /** `data-emphasis` on the row: full-strength label color and semibold value — the *Total* row */
+    emphasis?: boolean;
+    /** Per-row override of the list's `wrap` */
+    wrap?: DescriptionListWrap;
+    /** Class for this row (`div`), merged after `classItem` */
+    class?: string;
+    /** Class for this row's `<dt>`, merged after `classLabel` */
+    classLabel?: string;
+    /** Class for this row's value `<dd>`, merged after `classValue` */
+    classValue?: string;
+    /** Class for this row's description `<dd>`, merged after `classDescription` */
+    classDescription?: string;
+}
+export interface DescriptionListSnippetArg {
+    item: DescriptionListItem;
+    index: number;
+}
+export interface Props extends Omit<HTMLAttributes<HTMLDListElement>, "children"> {
+    /** The rows, in order. Data-driven form. */
+    items?: DescriptionListItem[];
+    /**
+     * Compositional form: rendered inside the `<dl>` *instead of* `items`. Write
+     * `<div><dt>…</dt><dd>…</dd></div>` per row; the structural CSS styles it identically.
+     */
+    children?: Snippet;
+    /**
+     * `"stacked"`: label above value, always. `"columns"`: label beside value, always.
+     * `"auto"` (default): stacked until the list itself is `columnsFrom` wide, then columns.
+     */
+    layout?: DescriptionListLayout;
+    /**
+     * The **list's own** inline size at which `"auto"` switches to columns:
+     * 20 / 24 / 28 / 32 / 36rem. Ignored unless `layout="auto"`.
+     */
+    columnsFrom?: DescriptionListColumnsFrom;
+    /**
+     * `"inside"` (default): a hairline *between* rows only (a list inside a card, drawer
+     * or panel — the box supplies the outer edge). `"outside"`: plus one above the first
+     * and below the last (a list loose on a page). `"none"`: no rules.
+     */
+    divide?: DescriptionListDivide;
+    /**
+     * How a long value behaves. `"anywhere"` (default) never lets a value push the page
+     * sideways. `"truncate"` clips to one line with an ellipsis. `"normal"` leaves the
+     * browser default. Per-item override via `item.wrap`.
+     */
+    wrap?: DescriptionListWrap;
+    /**
+     * Text alignment of the value column. `"end"` is the totals shape — pair it with
+     * `--stuic-description-list-label-width: 1fr`.
+     */
+    valueAlign?: DescriptionListValueAlign;
+    /**
+     * Rendered in the `<dd>` when an item's `value` is `undefined`, `null` or `""`.
+     * Pass `""` to render an empty cell.
+     */
+    emptyValue?: THC;
+    /** Override the `<dt>` content for every row */
+    renderLabel?: Snippet<[DescriptionListSnippetArg]>;
+    /** Override the value `<dd>` content for every row */
+    renderValue?: Snippet<[DescriptionListSnippetArg]>;
+    /** Override the whole row *content* (the `<div>` stays — it is what the grid is on) */
+    renderItem?: Snippet<[DescriptionListSnippetArg]>;
+    /** Skip all default styling */
+    unstyled?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+    /** Class for every row (`div`) */
+    classItem?: string;
+    /** Class for every `<dt>` */
+    classLabel?: string;
+    /** Class for every value `<dd>` */
+    classValue?: string;
+    /** Class for every description `<dd>` */
+    classDescription?: string;
+    /** Bindable element reference */
+    el?: HTMLDListElement;
+}
+declare const DescriptionList: import("svelte").Component<Props, {}, "el">;
+type DescriptionList = ReturnType<typeof DescriptionList>;
+export default DescriptionList;

package/dist/components/DescriptionList/README.md

@@ -0,0 +1,254 @@
+# DescriptionList
+
+The term-and-value list — the read-only block on every detail page, drawer and back-office
+panel. Renders the HTML the spec intends: `<dl>` › `<div>` per pair › `<dt>` + `<dd>`, with
+an optional second `<dd>` qualifying the value. No ARIA is added or needed — a `<dl>`
+already has list semantics, which is the reason to render one instead of nested `<div>`s.
+
+Two ways to feed it, both first-class: `items` for flat lists, `children` for markup-heavy
+ones. The CSS is written on the _structure_ (`dl > div > dt`), so a hand-written
+`<div><dt/><dd/></div>` renders identically to a generated row.
+
+The default layout (`"auto"`) puts the label **over** the value while the list is narrow
+and **beside** it once the list itself is wide enough — a container query, not a media
+query, so a narrow list inside a wide page stays stacked.
+
+Not an editor (that is `FieldKeyValues`), not a table. A run of numbers that should be a
+table is a table.
+
+## Props
+
+| Prop               | Type                                   | Default      | Description                                                                                    |
+| ------------------ | -------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------- |
+| `items`            | `DescriptionListItem[]`                | -            | The rows, in order. Data-driven form                                                           |
+| `children`         | `Snippet`                              | -            | Compositional form: rendered inside the `<dl>` _instead of_ `items`                            |
+| `layout`           | `"auto" \| "stacked" \| "columns"`     | `"auto"`     | Label over value, label beside value, or the former until the list is `columnsFrom` wide       |
+| `columnsFrom`      | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"sm"`       | The **list's own** width at which `"auto"` flips: 20 / 24 / 28 / 32 / 36rem. Only for `"auto"` |
+| `divide`           | `"none" \| "inside" \| "outside"`      | `"inside"`   | Hairlines between rows only, around the whole list as well, or none                            |
+| `wrap`             | `"anywhere" \| "truncate" \| "normal"` | `"anywhere"` | How a long value behaves. Per-row override via `item.wrap`                                     |
+| `valueAlign`       | `"start" \| "end"`                     | `"start"`    | Text alignment of the value column (`"end"` is the totals shape)                               |
+| `emptyValue`       | `THC`                                  | `"—"`        | Rendered when an item's `value` is `undefined`, `null` or `""`. Pass `""` for an empty cell    |
+| `renderLabel`      | `Snippet<[DescriptionListSnippetArg]>` | -            | Override the `<dt>` content for every row                                                      |
+| `renderValue`      | `Snippet<[DescriptionListSnippetArg]>` | -            | Override the value `<dd>` content for every row                                                |
+| `renderItem`       | `Snippet<[DescriptionListSnippetArg]>` | -            | Override the whole row _content_ (the `<div>` stays — it is what the grid is on)               |
+| `unstyled`         | `boolean`                              | `false`      | Skip all default styling (no classes, no data attributes)                                      |
+| `class`            | `string`                               | -            | Additional CSS classes on the `<dl>` (merged via twMerge)                                      |
+| `classItem`        | `string`                               | -            | Class for every row `<div>`                                                                    |
+| `classLabel`       | `string`                               | -            | Class for every `<dt>`                                                                         |
+| `classValue`       | `string`                               | -            | Class for every value `<dd>`                                                                   |
+| `classDescription` | `string`                               | -            | Class for every description `<dd>`                                                             |
+| `el`               | `HTMLDListElement`                     | -            | Element reference (bindable)                                                                   |
+
+Any other attribute (`aria-label`, `data-*`, `style`, `lang`, …) is passed to the `<dl>`.
+
+Empty `items` with no `children` renders **nothing** — not even the `<dl>`: an empty list
+with `divide="outside"` would otherwise draw two rules around a void.
+
+### `DescriptionListItem`
+
+| Field              | Type                  | Description                                                                                             |
+| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------------- |
+| `key`              | `string \| number`    | Keyed `{#each}` identity. Falls back to the index                                                       |
+| `label`            | `THC`                 | The term (`<dt>`). Required                                                                             |
+| `value`            | `THC \| number`       | The details (`<dd>`). A number is `String()`-ed; missing → `emptyValue`                                 |
+| `description`      | `THC`                 | A second `<dd>` under the value — a unit, a qualifier. In the columns state it sits under the value     |
+| `href`             | `string`              | Wraps the value in `<a href>`. Plain link only; anything more is the snippet / `children` form          |
+| `title`            | `string`              | `title` on the value `<dd>`. Auto-filled from a plain-string value under `wrap="truncate"` unless given |
+| `labelLang`        | `string`              | `lang` on the `<dt>`                                                                                    |
+| `valueLang`        | `string`              | `lang` on the value `<dd>`                                                                              |
+| `emphasis`         | `boolean`             | `data-emphasis` on the row: full-strength label color and semibold value — the _Total_ row              |
+| `wrap`             | `DescriptionListWrap` | Per-row override of the list's `wrap`                                                                   |
+| `class`            | `string`              | Class for this row, merged after `classItem`                                                            |
+| `classLabel`       | `string`              | Class for this `<dt>`, merged after `classLabel`                                                        |
+| `classValue`       | `string`              | Class for this value `<dd>`, merged after `classValue`                                                  |
+| `classDescription` | `string`              | Class for this description `<dd>`, merged after `classDescription`                                      |
+
+### Snippet Props
+
+All three receive `DescriptionListSnippetArg` = `{ item, index }`, as in `Timeline`.
+
+## Usage
+
+### Basic
+
+```svelte
+<script lang="ts">
+	import { DescriptionList } from "@marianmeres/stuic";
+</script>
+
+<DescriptionList
+	items={[
+		{ label: "Reference", value: "REF-2026-0042" },
+		{ label: "Created", value: "Sep 1, 2026" },
+		{ label: "Owner", value: null }, // renders the em dash
+	]}
+/>
+```
+
+### A detail block (the reference shape)
+
+Stacked while narrow, two columns once the list itself has room, interior hairlines, a
+truncated URL that stays reachable through its `title`, and a qualifier line under a count:
+
+```svelte
+<DescriptionList
+	class="mt-3 text-sm"
+	items={[
+		{ label: "Reference", value: doc.reference, classValue: "font-mono font-semibold" },
+		{
+			label: "Share link",
+			value: shareUrl(doc),
+			href: shareUrl(doc),
+			wrap: "truncate",
+		},
+		{
+			label: "Downloads",
+			value: downloadCount,
+			description: "in the last 30 days",
+			classValue: "tabular-nums",
+		},
+	]}
+/>
+```
+
+### Totals
+
+```svelte
+<DescriptionList
+	layout="columns"
+	valueAlign="end"
+	divide="none"
+	style="--stuic-description-list-label-width: 1fr;"
+	items={[
+		{ label: "Subtotal", value: "$120.00" },
+		{ label: "Tax", value: "$25.20" },
+		{ label: "Total", value: "$145.20", emphasis: true, class: "border-t mt-1 pt-2" },
+	]}
+/>
+```
+
+### The `children` form
+
+For rows the data form cannot express — a link with `target`/`rel`, a conditional row, a
+button inside a value. The structural CSS styles it identically, so **no layout utility is
+needed on the consumer side**; `data-wrap` and `data-emphasis` on a hand-written row are
+honoured by the same selectors the data form uses.
+
+```svelte
+<DescriptionList class="mt-3 text-sm">
+	<div>
+		<dt>Reference</dt>
+		<dd class="font-mono text-base font-semibold">{doc.reference}</dd>
+	</div>
+	<div data-wrap="truncate">
+		<dt>Share link</dt>
+		<dd title={shareUrl(doc)}>
+			<a href={shareUrl(doc)} target="_blank" rel="noopener noreferrer">
+				{shareUrl(doc)}
+			</a>
+		</dd>
+	</div>
+	{#if downloadCount !== null}
+		<div>
+			<dt>Downloads</dt>
+			<dd class="tabular-nums">{downloadCount}</dd>
+			<dd>in the last 30 days</dd>
+		</div>
+	{/if}
+</DescriptionList>
+```
+
+One `<div>` per pair is the contract: it is what the spec provides for grouping a term with
+its details, and it is what lets each row be a grid without subgrid. Bare `<dt>`/`<dd>`
+children of the `<dl>` are valid HTML but get no row styling.
+
+### Snippet overrides
+
+```svelte
+<DescriptionList {items}>
+	{#snippet renderValue({ item })}
+		<Pill label={item.value} intent="success" />
+	{/snippet}
+</DescriptionList>
+```
+
+## Layout
+
+`layout="auto"` makes the `<dl>` an inline-size container (named
+`stuic-description-list`) and switches the **rows** to a two-column grid at `columnsFrom` —
+an element cannot query itself, so the query is on the list and the styling is on its rows.
+
+Two consequences worth knowing:
+
+- **The list measures itself, not the viewport.** A 200px-wide list on a 1400px page stays
+  stacked. That is the whole point: `sm:` would have flipped it while it was still 200px.
+- **`container-type: inline-size` gives the `<dl>` inline-axis size containment**, so its
+  min-content contribution to a flex parent is zero — the list can sit beside a fixed-width
+  element and shrink to whatever is left. `min-w-0 flex-1` on the consumer side is already
+  there (the base rule sets `min-width: 0` in the static layouts too).
+
+The breakpoint is a prop on a fixed scale rather than a token because
+`@container (min-width: var(--x))` is not valid CSS — size queries take literals only. The
+scale is Tailwind's own `@xs`…`@xl`, so a consumer who would have typed `@min-[24rem]`
+writes `columnsFrom="sm"`.
+
+## Dividers
+
+`divide="inside"` (default) draws `n − 1` rules — a list inside a card, drawer or panel,
+where the box supplies the outer edge; the first and last rows sit flush with it.
+`divide="outside"` draws `n + 1` and keeps the outer padding — a list loose on a page,
+where the top and bottom lines are what close it. `divide="none"` draws none.
+
+## Wrapping
+
+`wrap="anywhere"` (default) never lets a value push the page sideways. It is
+`overflow-wrap: anywhere` and not `break-word` on purpose: only `anywhere` is counted in
+min-content sizing, so an inline-block inside a value cannot overflow the column it was
+meant to respect.
+
+`wrap="truncate"` clips to one line with an ellipsis — for a value that is chrome (an ID, a
+URL that is also a link). The `title` is auto-filled from a plain-string value so the
+clipped text stays reachable; for an html/component/snippet value there is no string to put
+there, so pass `item.title`. A `href` value must stay `display: inline` for the `<dd>`'s
+`text-overflow` to clip it — do not make the link `inline-block`.
+
+`wrap="normal"` leaves the browser default. Any of the three can be set per row via
+`item.wrap` (or `data-wrap` on a hand-written row), which wins over the list-level value.
+
+## CSS Variables
+
+| Variable                                              | Default                               | Description                                                                                |
+| ----------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `--stuic-description-list-label-width`                | `minmax(7rem, 10rem)`                 | Label track (any `grid-template-columns` value; not declared — fallback at the usage site) |
+| `--stuic-description-list-gap-x`                      | `1.5rem`                              | Label ↔ value, columns state                                                               |
+| `--stuic-description-list-gap-y`                      | `0.125rem`                            | Label ↕ value, stacked state                                                               |
+| `--stuic-description-list-item-padding-y`             | `0.5rem`                              | Row padding, both states                                                                   |
+| `--stuic-description-list-rule-color`                 | `var(--stuic-color-border)`           | Hairline color                                                                             |
+| `--stuic-description-list-rule-width`                 | `1px`                                 | Hairline thickness                                                                         |
+| `--stuic-description-list-label-font-size`            | `var(--text-sm)`                      | Label size                                                                                 |
+| `--stuic-description-list-label-font-weight`          | `var(--font-weight-medium)`           | Label weight                                                                               |
+| `--stuic-description-list-label-text`                 | `var(--stuic-color-muted-foreground)` | Label color                                                                                |
+| `--stuic-description-list-value-text`                 | `var(--stuic-color-foreground)`       | Value color (size is inherited)                                                            |
+| `--stuic-description-list-description-font-size`      | `var(--text-sm)`                      | Description size                                                                           |
+| `--stuic-description-list-description-text`           | `var(--stuic-color-muted-foreground)` | Description color                                                                          |
+| `--stuic-description-list-label-text-emphasis`        | `var(--stuic-color-foreground)`       | Label color on an `emphasis` row                                                           |
+| `--stuic-description-list-value-font-weight-emphasis` | `var(--font-weight-semibold)`         | Value weight on an `emphasis` row                                                          |
+
+The value deliberately has no font-size token: it inherits, so `class="text-sm"` on the
+`<dl>` scales the list. The rule tokens are the component's own (like `Separator`) rather
+than the `--stuic-border-width` tier, so a theme that zeroes box borders keeps its
+hairlines.
+
+## Data Attributes
+
+On the `<dl>`: `data-layout`, `data-columns-from` (only when `layout="auto"`),
+`data-divide`, `data-wrap`, `data-value-align`. On each row `<div>`: `data-wrap` (when
+`item.wrap` is set) and `data-emphasis` (empty attribute). `unstyled` removes all of them
+along with the classes.
+
+## Accessibility
+
+The rendered `<dl>` carries list semantics natively — no `role` is added. One term per row:
+a second `<dt>` in the same group is valid HTML but lands in the value column; use two rows
+instead. `lang` per row (`labelLang` / `valueLang`) is for a localized label or a
+fallback-language value inside a page that declares another language.

package/dist/components/DescriptionList/index.css

@@ -0,0 +1,264 @@
+/* ============================================================================
+   DESCRIPTION LIST COMPONENT TOKENS
+   Override globally: :root { --stuic-description-list-label-width: auto; }
+   Override locally:  <DescriptionList style="--stuic-description-list-gap-x: 1rem;">
+   ============================================================================ */
+
+:root {
+	/* Layout */
+	--stuic-description-list-gap-x: 1.5rem; /* label <-> value, columns state */
+	--stuic-description-list-gap-y: 0.125rem; /* label <-> value, stacked state */
+	--stuic-description-list-item-padding-y: 0.5rem; /* row padding, both states */
+
+	/* `--stuic-description-list-label-width` is deliberately NOT declared: it is read
+	   as a fallback argument at the usage site (`minmax(7rem, 10rem)`) so a scoped
+	   override on any ancestor works — see "Fallback Pattern" in docs/conventions.md. */
+
+	/* Rules */
+	--stuic-description-list-rule-color: var(--stuic-color-border);
+	--stuic-description-list-rule-width: 1px;
+
+	/* Label */
+	--stuic-description-list-label-font-size: var(--text-sm);
+	--stuic-description-list-label-font-weight: var(--font-weight-medium);
+	--stuic-description-list-label-text: var(--stuic-color-muted-foreground);
+
+	/* Value — inherits font-size, so `class="text-sm"` on the <dl> scales the whole list */
+	--stuic-description-list-value-text: var(--stuic-color-foreground);
+
+	/* Description (the second <dd>) */
+	--stuic-description-list-description-font-size: var(--text-sm);
+	--stuic-description-list-description-text: var(--stuic-color-muted-foreground);
+
+	/* Emphasis row */
+	--stuic-description-list-label-text-emphasis: var(--stuic-color-foreground);
+	--stuic-description-list-value-font-weight-emphasis: var(--font-weight-semibold);
+}
+
+@layer components {
+	/* ============================================================================
+	   BASE — selected STRUCTURALLY (`dl > div > dt`), not by class, so a hand-written
+	   `<div><dt/><dd/></div>` child renders identically to a generated `items` row.
+	   The per-element classes exist only as merge targets for `classLabel` & co.
+	   ============================================================================ */
+
+	.stuic-description-list {
+		/* UA gives <dl> a 1em block margin and <dd> a 40px inline start margin */
+		margin: 0;
+		/* A list in a flex/grid parent shrinks to its share instead of pushing it wider.
+		   In `layout="auto"` the container-type below already implies this; declaring it
+		   here means the static layouts behave the same way. */
+		min-width: 0;
+	}
+
+	/* Stacked is the base state: label over value. */
+	.stuic-description-list > div {
+		display: flex;
+		flex-direction: column;
+		row-gap: var(--stuic-description-list-gap-y);
+		padding-block: var(--stuic-description-list-item-padding-y);
+		min-width: 0;
+	}
+
+	.stuic-description-list > div > dt {
+		min-width: 0;
+		font-size: var(--stuic-description-list-label-font-size);
+		font-weight: var(--stuic-description-list-label-font-weight);
+		color: var(--stuic-description-list-label-text);
+	}
+
+	.stuic-description-list > div > dd {
+		margin: 0;
+		min-width: 0;
+		color: var(--stuic-description-list-value-text);
+	}
+
+	/* The second <dd> on the same term is the qualifier line. */
+	.stuic-description-list > div > dd + dd {
+		font-size: var(--stuic-description-list-description-font-size);
+		color: var(--stuic-description-list-description-text);
+	}
+
+	/* ============================================================================
+	   LAYOUT — "columns" is static; "auto" is the same row grid behind a container
+	   query on the LIST's own inline size (an element cannot query itself, so the
+	   container is the <dl> and the query styles its rows).
+	   ============================================================================ */
+
+	.stuic-description-list[data-layout="columns"] > div {
+		display: grid;
+		grid-template-columns:
+			var(--stuic-description-list-label-width, minmax(7rem, 10rem))
+			/* minmax(0, 1fr) and not 1fr: a grid item's automatic minimum size refuses
+			   to shrink below its content, so `wrap="truncate"` would overflow instead
+			   of clipping. */
+			minmax(0, 1fr);
+		column-gap: var(--stuic-description-list-gap-x);
+		align-items: baseline;
+	}
+
+	.stuic-description-list[data-layout="columns"] > div > dd + dd {
+		grid-column: 2;
+	}
+
+	.stuic-description-list[data-layout="auto"] {
+		/* Named so the query below can only ever resolve against this <dl>, never
+		   against a consumer's own @container ancestor. */
+		container-name: stuic-description-list;
+		container-type: inline-size;
+	}
+
+	/* The breakpoint cannot be a token: `@container (min-width: var(--x))` is not valid
+	   CSS — size queries take literals only. Hence a prop on a fixed scale mapped to a
+	   data attribute, and one block per step. Values are Tailwind's @xs…@xl. */
+
+	@container stuic-description-list (min-width: 20rem) {
+		.stuic-description-list[data-layout="auto"][data-columns-from="xs"] > div {
+			display: grid;
+			grid-template-columns:
+				var(--stuic-description-list-label-width, minmax(7rem, 10rem))
+				minmax(0, 1fr);
+			column-gap: var(--stuic-description-list-gap-x);
+			align-items: baseline;
+		}
+		.stuic-description-list[data-layout="auto"][data-columns-from="xs"] > div > dd + dd {
+			grid-column: 2;
+		}
+	}
+
+	@container stuic-description-list (min-width: 24rem) {
+		.stuic-description-list[data-layout="auto"][data-columns-from="sm"] > div {
+			display: grid;
+			grid-template-columns:
+				var(--stuic-description-list-label-width, minmax(7rem, 10rem))
+				minmax(0, 1fr);
+			column-gap: var(--stuic-description-list-gap-x);
+			align-items: baseline;
+		}
+		.stuic-description-list[data-layout="auto"][data-columns-from="sm"] > div > dd + dd {
+			grid-column: 2;
+		}
+	}
+
+	@container stuic-description-list (min-width: 28rem) {
+		.stuic-description-list[data-layout="auto"][data-columns-from="md"] > div {
+			display: grid;
+			grid-template-columns:
+				var(--stuic-description-list-label-width, minmax(7rem, 10rem))
+				minmax(0, 1fr);
+			column-gap: var(--stuic-description-list-gap-x);
+			align-items: baseline;
+		}
+		.stuic-description-list[data-layout="auto"][data-columns-from="md"] > div > dd + dd {
+			grid-column: 2;
+		}
+	}
+
+	@container stuic-description-list (min-width: 32rem) {
+		.stuic-description-list[data-layout="auto"][data-columns-from="lg"] > div {
+			display: grid;
+			grid-template-columns:
+				var(--stuic-description-list-label-width, minmax(7rem, 10rem))
+				minmax(0, 1fr);
+			column-gap: var(--stuic-description-list-gap-x);
+			align-items: baseline;
+		}
+		.stuic-description-list[data-layout="auto"][data-columns-from="lg"] > div > dd + dd {
+			grid-column: 2;
+		}
+	}
+
+	@container stuic-description-list (min-width: 36rem) {
+		.stuic-description-list[data-layout="auto"][data-columns-from="xl"] > div {
+			display: grid;
+			grid-template-columns:
+				var(--stuic-description-list-label-width, minmax(7rem, 10rem))
+				minmax(0, 1fr);
+			column-gap: var(--stuic-description-list-gap-x);
+			align-items: baseline;
+		}
+		.stuic-description-list[data-layout="auto"][data-columns-from="xl"] > div > dd + dd {
+			grid-column: 2;
+		}
+	}
+
+	/* ============================================================================
+	   DIVIDERS
+	   ============================================================================ */
+
+	.stuic-description-list[data-divide="inside"] > div + div,
+	.stuic-description-list[data-divide="outside"] > div {
+		border-top: var(--stuic-description-list-rule-width) solid
+			var(--stuic-description-list-rule-color);
+	}
+
+	.stuic-description-list[data-divide="outside"] > div:last-child {
+		border-bottom: var(--stuic-description-list-rule-width) solid
+			var(--stuic-description-list-rule-color);
+	}
+
+	/* Inside a box, the first and last rows sit flush with the box's own edges. With
+	   OUTSIDE rules the padding is what keeps the text off the rule, so it stays. */
+	.stuic-description-list:not([data-divide="outside"]) > div:first-child {
+		padding-top: 0;
+	}
+
+	.stuic-description-list:not([data-divide="outside"]) > div:last-child {
+		padding-bottom: 0;
+	}
+
+	/* ============================================================================
+	   WRAPPING — `anywhere` and not `break-word` on purpose: only `anywhere` counts in
+	   min-content sizing, so an inline-block inside the value cannot overflow the
+	   column it was meant to respect.
+	   ============================================================================ */
+
+	.stuic-description-list[data-wrap="anywhere"] > div > dd {
+		overflow-wrap: anywhere;
+	}
+
+	.stuic-description-list[data-wrap="truncate"] > div > dd {
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	/* Row-level override (`item.wrap`, or `data-wrap` on a hand-written row). Same
+	   specificity as the list-level rules above — one class, one attribute, two
+	   elements — so it wins by source order. This block MUST stay after that one. */
+	.stuic-description-list > div[data-wrap="normal"] > dd {
+		overflow-wrap: normal;
+		white-space: normal;
+		overflow: visible;
+		text-overflow: clip;
+	}
+
+	.stuic-description-list > div[data-wrap="anywhere"] > dd {
+		overflow-wrap: anywhere;
+		white-space: normal;
+		overflow: visible;
+		text-overflow: clip;
+	}
+
+	.stuic-description-list > div[data-wrap="truncate"] > dd {
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	/* ============================================================================
+	   VALUE ALIGNMENT + EMPHASIS (the totals shape)
+	   ============================================================================ */
+
+	.stuic-description-list[data-value-align="end"] > div > dd {
+		text-align: end;
+	}
+
+	.stuic-description-list > div[data-emphasis] > dt {
+		color: var(--stuic-description-list-label-text-emphasis);
+	}
+
+	.stuic-description-list > div[data-emphasis] > dd {
+		font-weight: var(--stuic-description-list-value-font-weight-emphasis);
+	}
+}

package/dist/components/DescriptionList/index.d.ts

@@ -0,0 +1 @@
+export { default as DescriptionList, type Props as DescriptionListProps, type DescriptionListItem, type DescriptionListSnippetArg, type DescriptionListLayout, type DescriptionListColumnsFrom, type DescriptionListDivide, type DescriptionListWrap, type DescriptionListValueAlign, } from "./DescriptionList.svelte";

package/dist/components/DescriptionList/index.js

@@ -0,0 +1 @@
+export { default as DescriptionList, } from "./DescriptionList.svelte";

package/dist/components/Input/FieldAssets.svelte

@@ -387,7 +387,7 @@
 	// aria-live announcement text for reorder actions
 	let liveAnnouncement = $state("");
 	let parentHiddenInputEl: HTMLInputElement | undefined = $state();
-	let hasLabel = $derived(isTHCNotEmpty(label) || typeof label === "function");
+	let hasLabel = $derived(isTHCNotEmpty(label));
 	let inputEl = $state<HTMLInputElement>()!;
 	// Outer wrapper for scrollIntoView and focus targeting.
 	let wrapEl: HTMLDivElement | undefined = $state();

package/dist/components/Input/FieldCheckbox.svelte

@@ -151,10 +151,11 @@
 					classLabel
 				)}
 			>
-				{#if isTHCNotEmpty(label)}
-					<Thc thc={label as THC} forceAsHtml />
-				{:else}
+				<!-- a snippet label first: it takes `{ id }`, which `Thc` cannot pass -->
+				{#if typeof label === "function"}
 					{@render (label as SnippetWithId)({ id })}
+				{:else if isTHCNotEmpty(label)}
+					<Thc thc={label as THC} forceAsHtml />
 				{/if}
 			</div>
 		{/if}

package/dist/components/Input/_internal/FieldRadioInternal.svelte

@@ -147,10 +147,11 @@
 					classLabel
 				)}
 			>
-				{#if isTHCNotEmpty(label)}
-					<Thc thc={label as THC} forceAsHtml />
-				{:else}
+				<!-- a snippet label first: it takes `{ id }`, which `Thc` cannot pass -->
+				{#if typeof label === "function"}
 					{@render (label as SnippetWithId)({ id })}
+				{:else if isTHCNotEmpty(label)}
+					<Thc thc={label as THC} forceAsHtml />
 				{/if}
 			</div>
 		{/if}

package/dist/components/Input/_internal/InputWrap.svelte

@@ -82,7 +82,7 @@
 		}
 	});
 
-	let hasLabel = $derived(isTHCNotEmpty(label) || typeof label === "function");
+	let hasLabel = $derived(isTHCNotEmpty(label));
 </script>
 
 {#snippet snippetOrThc({ id, value }: { id: string; value?: SnippetWithId | THC })}

package/dist/components/Thc/README.md

@@ -26,15 +26,21 @@ type THC =
 
 ### `isTHCNotEmpty(value)`
 
-Checks if a THC value has renderable content.
+Checks if a THC value has renderable content — every form `Thc` itself can render.
 
 ```ts
 isTHCNotEmpty("Hello"); // true
 isTHCNotEmpty({ text: "Hi" }); // true
+isTHCNotEmpty(mySnippet); // true
+isTHCNotEmpty({ snippet }); // true
 isTHCNotEmpty(""); // false
 isTHCNotEmpty(null); // false
 ```
 
+> **Note:** a snippet label that needs an argument (e.g. the `{ id }` the `Field*`
+> components pass) must be rendered directly, not through `Thc` — `Thc` renders a bare
+> snippet with no arguments. Test `typeof value === "function"` first in that case.
+
 ### `getTHCStringContent(value)`
 
 Extracts string content from a THC value.

package/dist/components/Thc/Thc.svelte

@@ -70,13 +70,18 @@
 	/**
 	 * Checks if a THC value has renderable content.
 	 *
+	 * Covers every form `Thc` itself can render: non-empty text/html, a component,
+	 * a `{ snippet }`, and a bare snippet function.
+	 *
 	 * @param m - The THC value to check
-	 * @returns `true` if the value contains non-empty text, html, or a component
+	 * @returns `true` if the value contains renderable content
 	 *
 	 * @example
 	 * ```ts
 	 * isTHCNotEmpty("Hello");           // true
 	 * isTHCNotEmpty({ text: "Hi" });    // true
+	 * isTHCNotEmpty(mySnippet);         // true
+	 * isTHCNotEmpty({ snippet });       // true
 	 * isTHCNotEmpty("");                // false
 	 * isTHCNotEmpty(null);              // false
 	 * ```
@@ -87,7 +92,10 @@
 			_is(m) ||
 			_is((m as WithText)?.text) ||
 			_is((m as WithHtml)?.html) ||
-			!!(m as WithComponent)?.component
+			!!(m as WithComponent)?.component ||
+			// a bare snippet is a function; `{ snippet }` is the object form
+			typeof m === "function" ||
+			!!(m as WithSnippet)?.snippet
 		);
 	}
 

package/dist/components/Thc/Thc.svelte.d.ts

@@ -58,13 +58,18 @@ export interface Props extends Record<string, any> {
 /**
  * Checks if a THC value has renderable content.
  *
+ * Covers every form `Thc` itself can render: non-empty text/html, a component,
+ * a `{ snippet }`, and a bare snippet function.
+ *
  * @param m - The THC value to check
- * @returns `true` if the value contains non-empty text, html, or a component
+ * @returns `true` if the value contains renderable content
  *
  * @example
  * ```ts
  * isTHCNotEmpty("Hello");           // true
  * isTHCNotEmpty({ text: "Hi" });    // true
+ * isTHCNotEmpty(mySnippet);         // true
+ * isTHCNotEmpty({ snippet });       // true
  * isTHCNotEmpty("");                // false
  * isTHCNotEmpty(null);              // false
  * ```

package/dist/index.css

@@ -95,6 +95,7 @@ In practice:
 @import "./components/CopyButton/index.css";
 @import "./components/CronInput/index.css";
 @import "./components/DataTable/index.css";
+@import "./components/DescriptionList/index.css";
 @import "./components/DismissibleMessage/index.css";
 @import "./components/DropdownMenu/index.css";
 @import "./components/EmailVerifyForm/index.css";

package/dist/index.d.ts

@@ -46,6 +46,7 @@ export * from "./components/ContextMenu/index.js";
 export * from "./components/CopyButton/index.js";
 export * from "./components/CronInput/index.js";
 export * from "./components/DataTable/index.js";
+export * from "./components/DescriptionList/index.js";
 export * from "./components/DismissibleMessage/index.js";
 export * from "./components/Drawer/index.js";
 export * from "./components/DropdownMenu/index.js";

package/dist/index.js

@@ -52,6 +52,7 @@ export * from "./components/ContextMenu/index.js";
 export * from "./components/CopyButton/index.js";
 export * from "./components/CronInput/index.js";
 export * from "./components/DataTable/index.js";
+export * from "./components/DescriptionList/index.js";
 export * from "./components/DismissibleMessage/index.js";
 export * from "./components/Drawer/index.js";
 export * from "./components/DropdownMenu/index.js";

package/docs/domains/components.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-78 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
+79 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
 
 ## Component Categories
 
@@ -105,6 +105,7 @@
 | Thc                 | Flexible renderer for text, HTML, components, or snippets                                            |
 | Card                | Flexible card with image, title, footer; vertical/horizontal layout                                  |
 | Stat                | KPI/stat card: label + value + delta with trend arrow and semantic coloring                          |
+| DescriptionList     | Term/value list (`<dl>`): stacked or two-column by container query, hairlines, truncation, totals    |
 | Timeline            | Vertical event list on a rail: dot/icon/custom markers, inline or opposite time, alternate layout    |
 | TrendChart          | Svelte wrapper for `@marianmeres/trend-chart` (subpath-only: `@marianmeres/stuic/trend-chart`)       |
 | Tree                | Hierarchical tree view with keyboard nav and drag-and-drop                                           |
@@ -970,6 +971,55 @@ Prefix: `--stuic-copy-button-*` (the surface themes via `--stuic-button-*`)
 
 ---
 
+## DescriptionList
+
+The term-and-value list — the read-only block on every detail page, drawer and back-office panel. Renders `<dl>` › `<div>` per pair › `<dt>` + `<dd>` (plus an optional second `<dd>` qualifying the value), which is what the spec provides for grouping a term with its details and what lets each row be a grid without subgrid. No ARIA is added: a `<dl>` already has list semantics. Two equal ways to feed it — `items` for flat lists, `children` for markup-heavy ones — because the CSS selects **structurally** (`dl > div > dt`, `> div > dd + dd`), so a hand-written row renders identically to a generated one. Not an editor (that is `FieldKeyValues`) and not a table.
+
+### Exports
+
+| Export                       | Kind      | Description                                                                                              |
+| ---------------------------- | --------- | -------------------------------------------------------------------------------------------------------- |
+| `DescriptionList`            | component | Main component                                                                                           |
+| `DescriptionListProps`       | type      | Props type                                                                                               |
+| `DescriptionListItem`        | type      | `{ key?, label, value?, description?, href?, title?, labelLang?, valueLang?, emphasis?, wrap?, class* }` |
+| `DescriptionListLayout`      | type      | `"auto" \| "stacked" \| "columns"`                                                                       |
+| `DescriptionListColumnsFrom` | type      | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` (20 / 24 / 28 / 32 / 36rem)                                       |
+| `DescriptionListDivide`      | type      | `"none" \| "inside" \| "outside"`                                                                        |
+| `DescriptionListWrap`        | type      | `"anywhere" \| "truncate" \| "normal"`                                                                   |
+| `DescriptionListValueAlign`  | type      | `"start" \| "end"`                                                                                       |
+| `DescriptionListSnippetArg`  | type      | `{ item, index }` — argument of all three snippets                                                       |
+
+### Key Props
+
+| Prop          | Type                                   | Default      | Description                                                                         |
+| ------------- | -------------------------------------- | ------------ | ----------------------------------------------------------------------------------- |
+| `items`       | `DescriptionListItem[]`                | —            | The rows, in order (label/value/description are THC)                                |
+| `children`    | `Snippet`                              | —            | Rendered inside the `<dl>` _instead of_ `items`                                     |
+| `layout`      | `"auto" \| "stacked" \| "columns"`     | `"auto"`     | Label over value, beside it, or the former until the list is `columnsFrom` wide     |
+| `columnsFrom` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"sm"`       | The **list's own** width at which `"auto"` flips. Dropped unless `layout="auto"`    |
+| `divide`      | `"none" \| "inside" \| "outside"`      | `"inside"`   | n−1 rules (list in a box), n+1 (list loose on a page), or none                      |
+| `wrap`        | `"anywhere" \| "truncate" \| "normal"` | `"anywhere"` | Long-value behavior; per-row override via `item.wrap`                               |
+| `valueAlign`  | `"start" \| "end"`                     | `"start"`    | `"end"` is the totals shape (pair with `--stuic-description-list-label-width: 1fr`) |
+| `emptyValue`  | `THC`                                  | `"—"`        | Used when `value` is `undefined`/`null`/`""` — `0` is a value, not empty            |
+
+Snippets (all receive `{ item, index }`): `renderLabel`, `renderValue`, `renderItem` (the row `<div>` stays — it is what the grid is on). Class slots: `class`, `classItem`, `classLabel`, `classValue`, `classDescription`, each also available per item. Empty `items` with no `children` renders **nothing**, not an empty `<dl>`.
+
+### Why a container query
+
+`layout="auto"` makes the `<dl>` a named inline-size container (`stuic-description-list`) and flips its **rows** to a two-column grid at `columnsFrom` — an element cannot query itself. The viewport answers a different question: a 200px-wide list inside a 1400px page must stay stacked, and `sm:` would have flipped it. The breakpoint is a prop on a fixed scale (Tailwind's `@xs`…`@xl`) and not a token because `@container (min-width: var(--x))` is not valid CSS — size queries take literals. Side effect worth knowing: `container-type: inline-size` gives the list inline-axis containment, so its min-content contribution to a flex parent is zero (the list can sit beside a fixed-width element and shrink into what is left; `min-w-0` is already there in the static layouts too).
+
+### Row-level contract (works in both forms)
+
+`data-wrap="anywhere|truncate|normal"` and `data-emphasis` on a row `<div>` are honoured by the same selectors the data form uses, so `children` rows opt into per-row wrapping and the _Total_ look without a prop. Under `wrap="truncate"` a plain-string value auto-fills the `<dd>`'s `title` (a clipped value must stay reachable); pass `item.title` for html/component/snippet values.
+
+### CSS Tokens
+
+Prefix: `--stuic-description-list-*`
+
+`label-width` (not declared — fallback `minmax(7rem, 10rem)` at the usage site), `gap-x`, `gap-y`, `item-padding-y`, `rule-color`, `rule-width`, `label-font-size`, `label-font-weight`, `label-text`, `value-text`, `description-font-size`, `description-text`, `label-text-emphasis`, `value-font-weight-emphasis`
+
+---
+
 ## EmptyState
 
 Icon + title + description + CTA placeholder for empty lists, tables, and search results. Centered, non-interactive; the CTA area is a snippet filled with consumer `Button`s/links. Pairs naturally with `DataTable` ("no rows") and search UIs ("no results").

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.174.0",
+	"version": "3.176.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",