@marianmeres/stuic 3.173.0 → 3.175.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)
@@ -101,12 +101,27 @@ Global tokens that control cross-component visual properties. Defined in `src/li
 }
 ```
 
-**Element vs Container classification:**
+**Element vs Button vs Container classification:**
 
 - **Element** (`--stuic-radius`): inputs, badges, list items, checkboxes, tabs — interactive controls
-- **Button** (`--stuic-radius-button`): buttons, button groups — allows rounded buttons even with flat elements
+- **Button** (`--stuic-radius-button`): buttons, split buttons, button groups — allows rounded buttons even with flat elements
 - **Container** (`--stuic-radius-container`): cards, modals, dropdowns, notifications, accordions — content wrappers
 
+**Tier tokens vs component tokens — the mirrored names.** Tier tokens (the table above) are
+`--stuic-{property}-{tier}` and ARE declared in `src/lib/index.css`. Component tokens are the
+transposition, `--stuic-{component}-{property}`, and are NEVER declared — they exist only as
+the first argument of a `var()` fallback:
+
+```css
+border-radius: var(--stuic-button-radius, var(--stuic-radius-button));
+/*                 ^ component token (3)  ^ tier token (2) */
+```
+
+So `--stuic-radius-button` applies to Button, SplitButton and ButtonGroupRadio, while
+`--stuic-button-radius` applies to Button alone. Same for `--stuic-border-width-button` vs
+`--stuic-button-border-width`. `button` is the only tier name that is also a component name,
+so it is the only confusable pair — do not "fix" one into the other.
+
 ---
 
 ## Before Making Changes
@@ -131,7 +146,7 @@ Global tokens that control cross-component visual properties. Defined in `src/li
 
 ### 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/README.md

@@ -57,7 +57,7 @@ STUIC uses a 4-layer CSS variable token system:
 ```
 Layer 1: Theme Tokens (--stuic-color-*)
     ↓
-Layer 2: Structural Tokens (--stuic-radius, --stuic-shadow, --stuic-border-width, --stuic-transition)
+Layer 2: Structural Tokens (--stuic-radius, --stuic-radius-button, --stuic-shadow, ...)
     ↓ (used as fallback defaults)
 Layer 3: Component Tokens (--stuic-button-radius, --stuic-input-accent, etc.)
     ↓ (Tailwind utility class references)
@@ -87,16 +87,20 @@ Override shared structural tokens to change the entire library's visual characte
 /* Brutalist — sharp, flat, borderless */
 :root {
 	--stuic-radius: 0;
+	--stuic-radius-button: 0;
 	--stuic-radius-container: 0;
 	--stuic-shadow: none;
 	--stuic-shadow-hover: none;
 	--stuic-shadow-overlay: none;
 	--stuic-shadow-dialog: none;
 	--stuic-border-width: 0;
+	--stuic-border-width-button: 0;
 }
 ```
 
-Available tokens: `--stuic-radius`, `--stuic-radius-container`, `--stuic-shadow`, `--stuic-shadow-hover`, `--stuic-shadow-overlay`, `--stuic-shadow-dialog`, `--stuic-border-width`, `--stuic-transition`.
+Available tokens: `--stuic-radius`, `--stuic-radius-button`, `--stuic-radius-container`, `--stuic-shadow`, `--stuic-shadow-hover`, `--stuic-shadow-overlay`, `--stuic-shadow-dialog`, `--stuic-border-width`, `--stuic-border-width-button`, `--stuic-transition`.
+
+Radius and border-width come in three tiers — elements, **buttons**, containers — so you can flatten inputs while keeping pill buttons, or the reverse.
 
 ### Per-Component Customization
 
@@ -104,7 +108,7 @@ Override specific component tokens:
 
 ```css
 :root {
-	--stuic-button-radius: 9999px; /* Pill buttons — overrides the shared --stuic-radius */
+	--stuic-button-radius: 9999px; /* Pill buttons — overrides the shared --stuic-radius-button */
 	--stuic-switch-accent: #10b981; /* Green switches */
 }
 ```

package/dist/components/Button/README.md

@@ -174,16 +174,17 @@ Notes:
 
 ### Component Tokens
 
-| Variable                       | Default                | Description         |
-| ------------------------------ | ---------------------- | ------------------- |
-| `--stuic-button-radius`        | `--radius-md`          | Border radius       |
-| `--stuic-button-font-family`   | `--font-sans`          | Font family         |
-| `--stuic-button-font-weight`   | `--font-weight-medium` | Font weight         |
-| `--stuic-button-transition`    | `100ms`                | Transition duration |
-| `--stuic-button-ring-width`    | `3px`                  | Focus ring width    |
-| `--stuic-button-ring-color`    | `--stuic-color-ring`   | Focus ring color    |
-| `--stuic-button-raised-offset` | `2px`                  | 3D effect offset    |
-| `--stuic-button-raised-color`  | `rgb(0 0 0 / 0.8)`     | 3D shadow color     |
+| Variable                       | Default                        | Description         |
+| ------------------------------ | ------------------------------ | ------------------- |
+| `--stuic-button-radius`        | `--stuic-radius-button`        | Border radius       |
+| `--stuic-button-border-width`  | `--stuic-border-width-button`  | Border width        |
+| `--stuic-button-font-family`   | `--font-sans`                  | Font family         |
+| `--stuic-button-font-weight`   | `--font-weight-medium`         | Font weight         |
+| `--stuic-button-transition`    | `--stuic-transition` (`150ms`) | Transition duration |
+| `--stuic-button-ring-width`    | `3px`                          | Focus ring width    |
+| `--stuic-button-ring-color`    | `--stuic-color-ring`           | Focus ring color    |
+| `--stuic-button-raised-offset` | `2px`                          | 3D effect offset    |
+| `--stuic-button-raised-color`  | `rgb(0 0 0 / 0.8)`             | 3D shadow color     |
 
 ### Size Tokens
 

package/dist/components/ButtonGroupRadio/README.md

@@ -129,34 +129,63 @@ disable the whole group instead, use the top-level `disabled` prop.
 
 ## CSS Variables
 
+All tokens below are **declared** in the component's `:root`. That means a `:root` override
+or a `style` prop override both work, but the `var(--token, <fallback>)` fallbacks visible in
+`index.css` never fire — the defaults are the `:root` values listed here.
+
 ### Component Tokens
 
-| Variable                                 | Default                   | Description                             |
-| ---------------------------------------- | ------------------------- | --------------------------------------- |
-| `--stuic-button-group-radius`            | `var(--radius-md)`        | Border radius for container and buttons |
-| `--stuic-button-group-padding`           | `0.375rem`                | Container padding                       |
-| `--stuic-button-group-gap`               | `0.25rem`                 | Gap between buttons                     |
-| `--stuic-button-group-border-width`      | `1px`                     | Container border width                  |
-| `--stuic-button-group-transition`        | `150ms`                   | Transition duration                     |
-| `--stuic-button-group-ring-width`        | `3px`                     | Focus ring width                        |
-| `--stuic-button-group-ring-color`        | `var(--stuic-color-ring)` | Focus ring color                        |
-| `--stuic-button-group-button-padding-x`  | `0.75rem`                 | Button horizontal padding               |
-| `--stuic-button-group-button-padding-y`  | `0.5rem`                  | Button vertical padding                 |
-| `--stuic-button-group-button-min-height` | `2.75rem`                 | Button min height (44px touch target)   |
+| Variable                                 | Default                   | Description                                    |
+| ---------------------------------------- | ------------------------- | ---------------------------------------------- |
+| `--stuic-button-group-radius`            | `9999px`                  | Border radius for container and buttons (pill) |
+| `--stuic-button-group-padding-x`         | `4px`                     | Container horizontal padding                   |
+| `--stuic-button-group-padding-y`         | `3px`                     | Container vertical padding                     |
+| `--stuic-button-group-gap`               | `0.25rem`                 | Gap between buttons                            |
+| `--stuic-button-group-border-width`      | `1px`                     | Container border width                         |
+| `--stuic-button-group-ring-width`        | `4px`                     | Focus ring width                               |
+| `--stuic-button-group-ring-color`        | `var(--stuic-color-ring)` | Focus ring color                               |
+| `--stuic-button-group-button-padding-x`  | `0.75rem`                 | Button horizontal padding                      |
+| `--stuic-button-group-button-padding-y`  | `0.375rem`                | Button vertical padding                        |
+| `--stuic-button-group-button-min-height` | `2.25rem`                 | Button min height (36px)                       |
+| `--stuic-button-group-transition`        | `var(--stuic-transition)` | Transition duration (not declared — fallback)  |
+
+`--stuic-button-group-transition` is the one exception: it is _not_ declared, so it resolves
+through its usage-site fallback to `--stuic-transition`.
 
 ### Color Tokens
 
-| Variable                                      | Default                                 | Description                      |
-| --------------------------------------------- | --------------------------------------- | -------------------------------- |
-| `--stuic-button-group-bg`                     | `var(--stuic-color-surface)`            | Container background             |
-| `--stuic-button-group-text`                   | `var(--stuic-color-foreground)`         | Container text color             |
-| `--stuic-button-group-border`                 | `var(--stuic-color-border)`             | Container border color           |
-| `--stuic-button-group-button-bg`              | `transparent`                           | Inactive button background       |
-| `--stuic-button-group-button-text`            | `var(--stuic-color-foreground)`         | Inactive button text             |
-| `--stuic-button-group-button-bg-hover`        | `var(--stuic-color-muted)`              | Inactive button hover background |
-| `--stuic-button-group-button-bg-active`       | `var(--stuic-color-primary)`            | Active button background         |
-| `--stuic-button-group-button-text-active`     | `var(--stuic-color-primary-foreground)` | Active button text               |
-| `--stuic-button-group-button-bg-active-hover` | `var(--stuic-color-primary-hover)`      | Active button hover background   |
+| Variable                                        | Default                                   | Description                      |
+| ----------------------------------------------- | ----------------------------------------- | -------------------------------- |
+| `--stuic-button-group-bg`                       | `var(--stuic-color-muted)`                | Container background             |
+| `--stuic-button-group-text`                     | `var(--stuic-color-muted-foreground)`     | Container text color             |
+| `--stuic-button-group-border`                   | `var(--stuic-input-border)`               | Container border color           |
+| `--stuic-button-group-border-focus`             | `var(--stuic-color-primary)`              | Container border on focus-within |
+| `--stuic-button-group-button-bg`                | `transparent`                             | Inactive button background       |
+| `--stuic-button-group-button-text`              | `var(--stuic-color-muted-foreground)`     | Inactive button text             |
+| `--stuic-button-group-button-bg-hover`          | `transparent`                             | Inactive button hover background |
+| `--stuic-button-group-button-text-hover`        | `var(--stuic-color-foreground)`           | Inactive button hover text       |
+| `--stuic-button-group-button-bg-active`         | `var(--stuic-color-surface-1)`            | Active button background         |
+| `--stuic-button-group-button-text-active`       | `var(--stuic-color-surface-1-foreground)` | Active button text               |
+| `--stuic-button-group-button-bg-active-hover`   | `var(--stuic-color-surface-1)`            | Active button hover background   |
+| `--stuic-button-group-button-text-active-hover` | `var(--stuic-color-surface-1-foreground)` | Active button hover text         |
+
+### Size Variants
+
+`size` sets `data-size` on the container, which re-declares a subset of the tokens above.
+`md` is the `:root` default; `sm` and `lg` override these:
+
+| Token                                    | `sm`       | `md` (default) | `lg`       |
+| ---------------------------------------- | ---------- | -------------- | ---------- |
+| `--stuic-button-group-padding-x`         | `3px`      | `4px`          | `8px`      |
+| `--stuic-button-group-padding-y`         | `2px`      | `3px`          | `6px`      |
+| `--stuic-button-group-gap`               | `0.125rem` | `0.25rem`      | `0.375rem` |
+| `--stuic-button-group-button-padding-x`  | `0.5rem`   | `0.75rem`      | `1rem`     |
+| `--stuic-button-group-button-padding-y`  | `0.375rem` | `0.375rem`     | `0.625rem` |
+| `--stuic-button-group-button-min-height` | `2.25rem`  | `2.25rem`      | `3rem`     |
+| overall height                           | 42px       | 44px           | 62px       |
+
+Because the size variants declare these on the container itself, they beat the inherited
+`:root` values — but an inline `style` on the same element still wins over both.
 
 ### Customization Examples
 

package/dist/components/ButtonGroupRadio/index.css

@@ -78,7 +78,9 @@
 	   ============================================================================ */
 
 	.stuic-button-group[data-size="sm"] {
-		--stuic-button-group-padding: 0.25rem;
+		/* overall height = 36px + 2×2px + 2×1px = 42px */
+		--stuic-button-group-padding-x: 3px;
+		--stuic-button-group-padding-y: 2px;
 		--stuic-button-group-gap: 0.125rem;
 		--stuic-button-group-button-padding-x: 0.5rem;
 		--stuic-button-group-button-padding-y: 0.375rem;
@@ -86,7 +88,9 @@
 	}
 
 	.stuic-button-group[data-size="lg"] {
-		--stuic-button-group-padding: 0.5rem;
+		/* overall height = 48px + 2×6px + 2×1px = 62px */
+		--stuic-button-group-padding-x: 8px;
+		--stuic-button-group-padding-y: 6px;
 		--stuic-button-group-gap: 0.375rem;
 		--stuic-button-group-button-padding-x: 1rem;
 		--stuic-button-group-button-padding-y: 0.625rem;

package/dist/components/DescriptionList/DescriptionList.svelte

@@ -0,0 +1,270 @@
+<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();
+
+	// `isTHCNotEmpty` only knows string/text/html/component — a snippet (bare or
+	// `{ snippet }`) is renderable content it reports as empty, which would silently
+	// drop a snippet description. Widen the test here.
+	const _hasContent = (thc: THC | undefined | null): boolean =>
+		typeof thc === "function" ||
+		!!(thc && typeof thc === "object" && "snippet" in thc) ||
+		isTHCNotEmpty(thc);
+
+	/** 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 _hasContent(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;