@marianmeres/stuic 3.173.0 → 3.175.0

package/dist/index.css

@@ -29,6 +29,20 @@ In practice:
    These tokens provide a single point of control for cross-component properties.
    Override globally:  :root { --stuic-radius: 0; }
    Override per-component: --stuic-button-radius: 9999px; (takes precedence)
+
+   NOTE on the mirrored names. The tokens below are TIER tokens, named
+   --stuic-{property}-{tier}, and they ARE declared here. Component override tokens
+   are the transposition, --stuic-{component}-{property}, and are NEVER declared --
+   they exist only as the first argument of a var() fallback at the usage site:
+
+       border-radius: var(--stuic-button-radius, var(--stuic-radius-button));
+                          ^ component token (3)  ^ tier token (2, declared here)
+
+   So --stuic-radius-button (tier) applies to Button, SplitButton and ButtonGroupRadio,
+   while --stuic-button-radius (component) applies to Button alone. Same relationship
+   between --stuic-border-width-button and --stuic-button-border-width. "button" is the
+   only tier name that is also a component name, hence the only confusable pair -- do
+   not "fix" one into the other.
    ============================================================================ */
 :root {
 	/* Radius: three tiers */
@@ -81,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/conventions.md

@@ -43,12 +43,14 @@ Global tokens in `src/lib/index.css` that control cross-component visual propert
 /* Brutalist example — 7 lines to transform everything */
 :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;
 }
 ```
 
@@ -79,16 +81,34 @@ Component CSS must reference shared tokens as **fallbacks at usage sites**, not
 
 Per-component overrides (`--stuic-widget-radius: 0`) still take precedence over the shared fallback.
 
-### Element vs Container
+### Element vs Button vs Container
 
-Two tiers of radius for natural visual hierarchy:
+Three tiers of radius for natural visual hierarchy:
 
-| Tier      | Token                      | Default            | Use for                                               |
-| --------- | -------------------------- | ------------------ | ----------------------------------------------------- |
-| Element   | `--stuic-radius`           | `var(--radius-md)` | Buttons, inputs, badges, list items, checkboxes, tabs |
-| Container | `--stuic-radius-container` | `var(--radius-lg)` | Cards, modals, dropdowns, notifications, accordions   |
+| Tier      | Token                      | Default            | Use for                                             |
+| --------- | -------------------------- | ------------------ | --------------------------------------------------- |
+| Element   | `--stuic-radius`           | `var(--radius-md)` | Inputs, badges, list items, checkboxes, tabs        |
+| Button    | `--stuic-radius-button`    | `var(--radius-md)` | Buttons, split buttons, button groups               |
+| Container | `--stuic-radius-container` | `var(--radius-lg)` | Cards, modals, dropdowns, notifications, accordions |
 
-**Rule of thumb:** if it wraps other interactive elements, it's a container.
+**Rule of thumb:** if it wraps other interactive elements, it's a container. Buttons get
+their own tier so a flat-input theme can still have pill buttons (and vice versa);
+`--stuic-border-width-button` splits out the same way.
+
+### Tier tokens vs component tokens
+
+The two layers use mirrored names, which is easy to misread for the button tier:
+
+| Name                          | Layer               | Declared?             | Scope                         |
+| ----------------------------- | ------------------- | --------------------- | ----------------------------- |
+| `--stuic-radius-button`       | shared tier (2)     | yes, in `index.css`   | every button-family component |
+| `--stuic-button-radius`       | component token (3) | no, fallback arg only | `Button` only                 |
+| `--stuic-border-width-button` | shared tier (2)     | yes, in `index.css`   | every button-family component |
+| `--stuic-button-border-width` | component token (3) | no, fallback arg only | `Button` only                 |
+
+Read it as `--stuic-{property}-{tier}` for tier tokens and `--stuic-{component}-{property}`
+for component tokens. `button` is the only tier name that is also a component name, so it
+is the only pair that reads as a transposition.
 
 ---
 

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/docs/domains/theming.md

@@ -186,39 +186,55 @@ const css = generateThemeCss(custom, "stuic-");
 
 Global tokens defined in `src/lib/index.css` that control cross-component visual properties. Override these to change the entire library's visual character:
 
-| Token                      | Default            | Purpose                                           |
-| -------------------------- | ------------------ | ------------------------------------------------- |
-| `--stuic-radius`           | `var(--radius-md)` | Element-level radius (buttons, inputs, badges)    |
-| `--stuic-radius-container` | `var(--radius-lg)` | Container-level radius (cards, modals, dropdowns) |
-| `--stuic-shadow`           | `var(--shadow-sm)` | Default resting shadow                            |
-| `--stuic-shadow-hover`     | `var(--shadow-md)` | Hover/elevated shadow                             |
-| `--stuic-shadow-overlay`   | `var(--shadow-lg)` | Overlays (dropdowns, notifications)               |
-| `--stuic-shadow-dialog`    | `var(--shadow-xl)` | Dialogs/modals                                    |
-| `--stuic-border-width`     | `1px`              | Default border width                              |
-| `--stuic-transition`       | `150ms`            | Default transition duration                       |
+| Token                         | Default            | Purpose                                                     |
+| ----------------------------- | ------------------ | ----------------------------------------------------------- |
+| `--stuic-radius`              | `var(--radius-md)` | Element-level radius (inputs, badges, list items)           |
+| `--stuic-radius-button`       | `var(--radius-md)` | Button-level radius (buttons, split buttons, button groups) |
+| `--stuic-radius-container`    | `var(--radius-lg)` | Container-level radius (cards, modals, dropdowns)           |
+| `--stuic-shadow`              | `var(--shadow-sm)` | Default resting shadow                                      |
+| `--stuic-shadow-hover`        | `var(--shadow-md)` | Hover/elevated shadow                                       |
+| `--stuic-shadow-overlay`      | `var(--shadow-lg)` | Overlays (dropdowns, notifications)                         |
+| `--stuic-shadow-dialog`       | `var(--shadow-xl)` | Dialogs/modals                                              |
+| `--stuic-border-width`        | `1px`              | Default border width                                        |
+| `--stuic-border-width-button` | `1px`              | Button border width (independent from general elements)     |
+| `--stuic-transition`          | `150ms`            | Default transition duration                                 |
+
+Radius and border-width come in **three tiers** — elements, buttons, containers — so a
+theme can flatten inputs while keeping pill buttons, or vice versa. See
+[Conventions: Element vs Button vs Container](../conventions.md#element-vs-button-vs-container).
 
 Example — brutalist style in 7 lines:
 
 ```css
 :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;
 }
 ```
 
-Components reference these via the fallback pattern (not `:root` declarations):
+Components reference these via the fallback pattern (not `:root` declarations) — the
+per-component token first, the shared tier token as its fallback:
 
 ```css
 .stuic-button {
-	border-radius: var(--stuic-button-radius, var(--stuic-radius));
+	border-radius: var(--stuic-button-radius, var(--stuic-radius-button));
+	/*                 ^ component token      ^ shared tier token */
 }
 ```
 
+> **Note the mirrored names.** `--stuic-radius-button` is the shared tier token (declared
+> in `src/lib/index.css`, applies to every button-family component);
+> `--stuic-button-radius` is the `Button` component's own override token (never declared —
+> it only ever appears as the first argument of a `var()` fallback). Same for
+> `--stuic-border-width-button` vs `--stuic-button-border-width`.
+
 ---
 
 ## Component Tokens
@@ -239,7 +255,7 @@ Override per-component tokens globally:
 
 ```css
 :root {
-	--stuic-button-radius: 9999px; /* Pill buttons — overrides the shared fallback */
+	--stuic-button-radius: 9999px; /* Pill buttons — overrides --stuic-radius-button */
 }
 ```
 
@@ -251,6 +267,34 @@ Override locally:
 
 Some token sets belong to a CSS-only preset rather than to a component — e.g. `--stuic-frame-*` (ratio-locked frame / letterbox). Those are consumer **inputs** that stuic never declares; see [CSS presets](./css-presets.md).
 
+### Pitfall: never pin a nested component's tokens inline
+
+When a component renders another stuic component internally and wants to restyle it, the
+opinionated values must go in the outer component's `index.css`, behind its own
+`--stuic-{outer}-{part}-*` tokens — never into the inner component's inline `style`
+attribute:
+
+```svelte
+<!-- WRONG — an inline custom property outranks every :root declaration for that
+     element and its subtree, so no theme can reach the inner component -->
+<ButtonGroupRadio style="--stuic-button-group-radius: 9999px;" />
+
+<!-- RIGHT — the class carries the look, and `style` stays the caller's escape hatch -->
+<ButtonGroupRadio class="stuic-pricing-table-toggle" style={styleToggle} />
+```
+
+```css
+.stuic-pricing-table-toggle {
+	--stuic-button-group-radius: var(--stuic-pricing-table-toggle-radius, 9999px);
+}
+```
+
+No specificity or `@layer` trick outranks an inline declaration, so the inline form makes
+that part of the component permanently unthemeable. `PricingTable`'s billing toggle is the
+worked example. Note the trade: whatever the outer component declares on the element is no
+longer reachable through the _inner_ component's global token, so document the
+`--stuic-{outer}-*` replacement in the outer component's README.
+
 ---
 
 ## Key Files

package/package.json

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