@marianmeres/stuic 3.189.0 → 3.190.0

package/AGENTS.md

@@ -23,7 +23,7 @@
 
 ```
 src/lib/
-├── components/     # 80 component directories
+├── components/     # 82 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) — 80 component directories, Props pattern, snippets
+- [Components](./docs/domains/components.md) — 82 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/API.md

@@ -1273,6 +1273,43 @@ Horizontal schedule chart — project plans (task per row, progress, milestones)
 
 The geometry is exported separately for axis-aligned overlays: `buildGanttAxis`, `placeRange`, `placePoint`, `dayToFraction`, `boundsOf`.
 
+#### `ListGroup`
+
+Bordered, rounded box of rows split by hairlines, with an optional header (title + aside) and footer. Each row is one wrapping flex line of parts; `data-grow` on the part that should absorb the slack. Generic over the item type.
+
+| Prop         | Type                                   | Default | Description                                                            |
+| ------------ | -------------------------------------- | ------- | ---------------------------------------------------------------------- |
+| `items`      | `T[]`                                  | —       | The rows (without `renderItem`, each renders as `THC`)                 |
+| `renderItem` | `Snippet<[{ item, index }]>`           | —       | Row content                                                            |
+| `children`   | `Snippet`                              | —       | Hand-written `<li>`s instead of `items` (styled identically)           |
+| `getItemId`  | `(item, index) => string \| number`    | index   | Keyed identity                                                         |
+| `itemProps`  | `(item, index) => ListGroupItemProps`  | —       | Attributes (`data-*`, `class`) on each `<li>`                          |
+| `itemHref`   | `(item, index) => string \| undefined` | —       | Makes the whole row a link                                             |
+| `title`      | `THC`                                  | —       | Header start side; labels the list                                     |
+| `titleLevel` | `1…6`                                  | —       | Render the title as `<hN>` (semantics only)                            |
+| `aside`      | `THC`                                  | —       | Header end side                                                        |
+| `footer`     | `THC`                                  | —       | A line under the rows                                                  |
+| `empty`      | `THC`                                  | —       | Replaces the list when there are no rows; without it, nothing renders  |
+| `listProps`  | `ListGroupListProps`                   | —       | Attributes for the `<ul>` (e.g. `aria-label` when there is no `title`) |
+
+```svelte
+<ListGroup
+	class="text-sm"
+	items={lines}
+	getItemId={(l) => l.id}
+	itemProps={(l) => ({ "data-line": l.id })}
+	title="Loose items"
+	aside="70 pc"
+	empty="Nothing booked yet."
+>
+	{#snippet renderItem({ item })}
+		<span class="font-mono">{item.code}</span>
+		<span data-grow>{item.name}</span>
+		<span>×{item.qty}</span>
+	{/snippet}
+</ListGroup>
+```
+
 #### `ImageCycler`
 
 Auto-cycling image carousel with fade transitions. Preloads next image before displaying. Supports custom title/description snippets.

package/dist/components/ListGroup/ListGroup.fixture.svelte

@@ -0,0 +1,91 @@
+<script lang="ts">
+	// Layout fixture: rows whose parts are DIRECT children of the <li> (a raw snippet can
+	// only render one root element), plus a hand-written `children` form to compare.
+	import ListGroup from "./ListGroup.svelte";
+
+	interface Line {
+		id: number;
+		code: string;
+		name: string;
+		qty: number;
+		location: string;
+	}
+
+	let {
+		width = 1000,
+		mode = "items",
+		linked = false,
+		showRow = false,
+		style,
+		title = "Loose items",
+	}: {
+		width?: number;
+		mode?: "items" | "children" | "children-empty";
+		linked?: boolean;
+		showRow?: boolean;
+		style?: string;
+		title?: string;
+	} = $props();
+
+	const LINES: Line[] = [
+		{
+			id: 1,
+			code: "7QMET2GD",
+			name: "Folding chair",
+			qty: 40,
+			location: "hall-a.floor-a",
+		},
+		{
+			id: 2,
+			code: "89A6KMHY",
+			name: "Carpet tape, double-sided",
+			qty: 3,
+			location: "hall-a-raca.rack-a2.shelf-a2-2.consumables-bin",
+		},
+	];
+</script>
+
+<!-- the theme is not loaded in browser tests: `--stuic-color-border` / `-ring` are undefined, which
+     would make the rule and ring declarations invalid at computed-value time -->
+<div
+	data-testid="frame"
+	style="width: {width}px; --stuic-list-group-rule-color: currentColor; --stuic-list-group-item-ring-color: currentColor;"
+>
+	{#if mode === "items"}
+		<ListGroup
+			items={LINES}
+			getItemId={(l) => l.id}
+			itemHref={linked ? (l) => `#/line/${l.id}` : undefined}
+			{title}
+			{style}
+		>
+			{#snippet renderItem({ item })}
+				<span data-part="code">{item.code}</span>
+				<span data-part="name" data-grow>{item.name}</span>
+				<span data-part="qty">×{item.qty}</span>
+				<span data-part="picked">picked {item.qty}/{item.qty}</span>
+				<span data-part="location">{item.location}</span>
+			{/snippet}
+		</ListGroup>
+	{:else if mode === "children"}
+		<ListGroup {title} {style}>
+			<li data-row="plain">
+				<span data-part="code">7QMET2GD</span>
+				<span data-part="name" data-grow>Folding chair</span>
+			</li>
+			<li data-row="link">
+				<a href="#/search"><span data-part="name" data-grow>Search</span><kbd>/</kbd></a>
+			</li>
+			<li data-row="button">
+				<button type="button"><span>A button row</span></button>
+			</li>
+			<li data-row="stuic">
+				<button type="button" class="stuic-button">Kept</button>
+			</li>
+		</ListGroup>
+	{:else}
+		<ListGroup {title} footer="The footer">
+			{#if showRow}<li>A row</li>{/if}
+		</ListGroup>
+	{/if}
+</div>

package/dist/components/ListGroup/ListGroup.fixture.svelte.d.ts

@@ -0,0 +1,12 @@
+import ListGroup from "./ListGroup.svelte";
+type $$ComponentProps = {
+    width?: number;
+    mode?: "items" | "children" | "children-empty";
+    linked?: boolean;
+    showRow?: boolean;
+    style?: string;
+    title?: string;
+};
+declare const ListGroup: import("svelte").Component<$$ComponentProps, {}, "">;
+type ListGroup = ReturnType<typeof ListGroup>;
+export default ListGroup;

package/dist/components/ListGroup/ListGroup.svelte

@@ -0,0 +1,232 @@
+<script lang="ts" module>
+	import type { HTMLAttributes, HTMLLiAttributes } from "svelte/elements";
+	import type { Snippet } from "svelte";
+	import type { THC } from "../Thc/Thc.svelte";
+
+	/** Renders the title as `<h1>`…`<h6>`. Semantics only — the look never changes. */
+	export type ListGroupTitleLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+	export interface ListGroupSnippetArg<T = unknown> {
+		item: T;
+		index: number;
+	}
+
+	/**
+	 * What `itemProps` may put on a row `<li>` — typically the `data-*` hooks a consumer's
+	 * tests select on. `class` is a plain string so it can be merged after `classItem`.
+	 */
+	export type ListGroupItemProps = Omit<HTMLLiAttributes, "children" | "class"> & {
+		class?: string;
+	};
+
+	/** Attributes for the `<ul>` itself (`class` is `classList`, `role` is fixed) */
+	export type ListGroupListProps = Omit<
+		HTMLAttributes<HTMLUListElement>,
+		"children" | "class" | "role"
+	>;
+
+	export interface Props<T = unknown> extends Omit<
+		HTMLAttributes<HTMLDivElement>,
+		"children" | "title"
+	> {
+		/** The rows, in order. Data-driven form. */
+		items?: T[];
+		/**
+		 * A row's content, rendered inside the `<li>` (or inside the `<a>` when `itemHref`
+		 * returns a href). Without it an item is rendered as `THC`, so `items={["a", "b"]}`
+		 * works as is.
+		 */
+		renderItem?: Snippet<[ListGroupSnippetArg<T>]>;
+		/**
+		 * Compositional form: rendered inside the `<ul>` *instead of* `items`. Write `<li>`s;
+		 * the structural CSS styles them exactly like generated rows.
+		 */
+		children?: Snippet;
+		/** Keyed `{#each}` identity. Defaults to the index. */
+		getItemId?: (item: T, index: number) => string | number;
+		/**
+		 * Attributes spread onto each `<li>` — the `data-*` hooks consumers test against.
+		 * A returned `class` is merged after `classItem`. `null`/`undefined` values omit the
+		 * attribute. Identity comes from `getItemId`, never from here.
+		 */
+		itemProps?: (item: T, index: number) => ListGroupItemProps | undefined;
+		/**
+		 * When it returns a href, the row's content is wrapped in
+		 * `<a class="stuic-list-group-item-link">` and the anchor becomes the row box
+		 * (padding, hover, focus ring). Falsy → a plain row. A linked row must not contain
+		 * other interactive content.
+		 */
+		itemHref?: (item: T, index: number) => string | undefined | null;
+		/** The header's start side. Labels the list (`aria-labelledby`). */
+		title?: THC;
+		/** Render the title as `<hN>` instead of a `<div>`. Semantics only. */
+		titleLevel?: ListGroupTitleLevel;
+		/**
+		 * The header's end side: a sum, a count, a shortfall, an action. Never an automatic
+		 * row count — say what the figure is.
+		 */
+		aside?: THC;
+		/** A line inside the box, under the rows, above a rule. */
+		footer?: THC;
+		/**
+		 * Rendered in place of the `<ul>` when `items` is empty (or absent) and there are no
+		 * `children`. Without it, a group with no rows renders nothing at all.
+		 */
+		empty?: THC;
+		/**
+		 * Attributes for the `<ul>`. The escape hatch for labelling a list that has no
+		 * `title` (`aria-label`, or `aria-labelledby` pointing at a caption outside the box)
+		 * — an `aria-label` on the root `<div>` would name nothing.
+		 */
+		listProps?: ListGroupListProps;
+		/** Skip all default styling */
+		unstyled?: boolean;
+		/** Additional CSS classes for the root */
+		class?: string;
+		/** Class for the header row */
+		classHeader?: string;
+		/** Class for the title */
+		classTitle?: string;
+		/** Class for the aside */
+		classAside?: string;
+		/** Class for the `<ul>` */
+		classList?: string;
+		/** Class for every generated `<li>` */
+		classItem?: string;
+		/** Class for every generated `<a>` (`itemHref`) */
+		classItemLink?: string;
+		/** Class for the empty state */
+		classEmpty?: string;
+		/** Class for the footer */
+		classFooter?: string;
+		/** Bindable root element reference */
+		el?: HTMLDivElement;
+	}
+</script>
+
+<script lang="ts" generics="T = unknown">
+	import { twMerge } from "../../utils/tw-merge.js";
+	import { getId } from "../../utils/get-id.js";
+	import Thc, { isTHCNotEmpty } from "../Thc/Thc.svelte";
+
+	let {
+		items,
+		renderItem,
+		children,
+		getItemId = (_item: T, index: number) => index,
+		itemProps,
+		itemHref,
+		title,
+		titleLevel,
+		aside,
+		footer,
+		empty,
+		listProps,
+		unstyled = false,
+		class: classProp,
+		classHeader: classHeaderProp,
+		classTitle: classTitleProp,
+		classAside: classAsideProp,
+		classList: classListProp,
+		classItem: classItemProp,
+		classItemLink: classItemLinkProp,
+		classEmpty: classEmptyProp,
+		classFooter: classFooterProp,
+		el = $bindable(),
+		...rest
+	}: Props<T> = $props();
+
+	const titleId = getId("stuic-list-group-title-");
+
+	let rows = $derived(items ?? []);
+	let hasRows = $derived(!!children || rows.length > 0);
+	let hasTitle = $derived(isTHCNotEmpty(title));
+	let hasAside = $derived(isTHCNotEmpty(aside));
+	let hasFooter = $derived(isTHCNotEmpty(footer));
+	let hasEmpty = $derived(isTHCNotEmpty(empty));
+
+	let _titleTag = $derived(
+		titleLevel && titleLevel >= 1 && titleLevel <= 6 ? `h${titleLevel}` : "div"
+	);
+
+	// Under `unstyled` a part keeps only the consumer's classes — `undefined` rather than
+	// `class=""` when there are none.
+	const _cls = (base: string, ...extra: (string | undefined)[]) =>
+		(unstyled ? twMerge(...extra) : twMerge(base, ...extra)) || undefined;
+
+	let _class = $derived(unstyled ? classProp : twMerge("stuic-list-group", classProp));
+	let _classHeader = $derived(_cls("stuic-list-group-header", classHeaderProp));
+	let _classTitle = $derived(_cls("stuic-list-group-title", classTitleProp));
+	let _classAside = $derived(_cls("stuic-list-group-aside", classAsideProp));
+	let _classList = $derived(_cls("stuic-list-group-list", classListProp));
+	let _classItemLink = $derived(_cls("stuic-list-group-item-link", classItemLinkProp));
+	let _classEmpty = $derived(_cls("stuic-list-group-empty", classEmptyProp));
+	let _classFooter = $derived(_cls("stuic-list-group-footer", classFooterProp));
+
+	/** `itemProps` split into the attributes to spread and the class to merge */
+	const _itemAttrs = (item: T, index: number) => {
+		const { class: itemClass, ...attrs }: ListGroupItemProps =
+			itemProps?.(item, index) ?? {};
+		return { attrs, class: _cls("stuic-list-group-item", classItemProp, itemClass) };
+	};
+</script>
+
+{#snippet content(item: T, index: number)}
+	{#if renderItem}
+		{@render renderItem({ item, index })}
+	{:else}
+		<Thc thc={item as THC} />
+	{/if}
+{/snippet}
+
+{#if hasRows || hasEmpty}
+	<div bind:this={el} class={_class} {...rest}>
+		<!-- A <div>, not a <header>: outside <main>/sectioning content (a drawer, a
+		     dialog) a <header> is a `banner` landmark, one per group. -->
+		{#if hasTitle || hasAside}
+			<div class={_classHeader}>
+				{#if hasTitle}
+					<svelte:element this={_titleTag} id={titleId} class={_classTitle}>
+						<Thc thc={title!} />
+					</svelte:element>
+				{/if}
+				{#if hasAside}
+					<div class={_classAside}><Thc thc={aside!} /></div>
+				{/if}
+			</div>
+		{/if}
+
+		{#if hasRows}
+			<!-- WebKit drops list semantics from a `list-style: none` <ul> without it -->
+			<ul
+				role="list"
+				aria-labelledby={hasTitle ? titleId : undefined}
+				{...listProps}
+				class={_classList}
+			>
+				{#if children}
+					{@render children()}
+				{:else}
+					{#each rows as item, index (getItemId(item, index))}
+						{@const li = _itemAttrs(item, index)}
+						{@const href = itemHref?.(item, index)}
+						<li {...li.attrs} class={li.class}>
+							{#if href}
+								<a {href} class={_classItemLink}>{@render content(item, index)}</a>
+							{:else}
+								{@render content(item, index)}
+							{/if}
+						</li>
+					{/each}
+				{/if}
+			</ul>
+		{:else}
+			<div class={_classEmpty}><Thc thc={empty!} /></div>
+		{/if}
+
+		<!-- A <div>, not a <footer>: same landmark reason as the header -->
+		{#if hasFooter}
+			<div class={_classFooter}><Thc thc={footer!} /></div>
+		{/if}
+	</div>
+{/if}

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

@@ -0,0 +1,116 @@
+import type { HTMLAttributes, HTMLLiAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
+import type { THC } from "../Thc/Thc.svelte";
+/** Renders the title as `<h1>`…`<h6>`. Semantics only — the look never changes. */
+export type ListGroupTitleLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export interface ListGroupSnippetArg<T = unknown> {
+    item: T;
+    index: number;
+}
+/**
+ * What `itemProps` may put on a row `<li>` — typically the `data-*` hooks a consumer's
+ * tests select on. `class` is a plain string so it can be merged after `classItem`.
+ */
+export type ListGroupItemProps = Omit<HTMLLiAttributes, "children" | "class"> & {
+    class?: string;
+};
+/** Attributes for the `<ul>` itself (`class` is `classList`, `role` is fixed) */
+export type ListGroupListProps = Omit<HTMLAttributes<HTMLUListElement>, "children" | "class" | "role">;
+export interface Props<T = unknown> extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "title"> {
+    /** The rows, in order. Data-driven form. */
+    items?: T[];
+    /**
+     * A row's content, rendered inside the `<li>` (or inside the `<a>` when `itemHref`
+     * returns a href). Without it an item is rendered as `THC`, so `items={["a", "b"]}`
+     * works as is.
+     */
+    renderItem?: Snippet<[ListGroupSnippetArg<T>]>;
+    /**
+     * Compositional form: rendered inside the `<ul>` *instead of* `items`. Write `<li>`s;
+     * the structural CSS styles them exactly like generated rows.
+     */
+    children?: Snippet;
+    /** Keyed `{#each}` identity. Defaults to the index. */
+    getItemId?: (item: T, index: number) => string | number;
+    /**
+     * Attributes spread onto each `<li>` — the `data-*` hooks consumers test against.
+     * A returned `class` is merged after `classItem`. `null`/`undefined` values omit the
+     * attribute. Identity comes from `getItemId`, never from here.
+     */
+    itemProps?: (item: T, index: number) => ListGroupItemProps | undefined;
+    /**
+     * When it returns a href, the row's content is wrapped in
+     * `<a class="stuic-list-group-item-link">` and the anchor becomes the row box
+     * (padding, hover, focus ring). Falsy → a plain row. A linked row must not contain
+     * other interactive content.
+     */
+    itemHref?: (item: T, index: number) => string | undefined | null;
+    /** The header's start side. Labels the list (`aria-labelledby`). */
+    title?: THC;
+    /** Render the title as `<hN>` instead of a `<div>`. Semantics only. */
+    titleLevel?: ListGroupTitleLevel;
+    /**
+     * The header's end side: a sum, a count, a shortfall, an action. Never an automatic
+     * row count — say what the figure is.
+     */
+    aside?: THC;
+    /** A line inside the box, under the rows, above a rule. */
+    footer?: THC;
+    /**
+     * Rendered in place of the `<ul>` when `items` is empty (or absent) and there are no
+     * `children`. Without it, a group with no rows renders nothing at all.
+     */
+    empty?: THC;
+    /**
+     * Attributes for the `<ul>`. The escape hatch for labelling a list that has no
+     * `title` (`aria-label`, or `aria-labelledby` pointing at a caption outside the box)
+     * — an `aria-label` on the root `<div>` would name nothing.
+     */
+    listProps?: ListGroupListProps;
+    /** Skip all default styling */
+    unstyled?: boolean;
+    /** Additional CSS classes for the root */
+    class?: string;
+    /** Class for the header row */
+    classHeader?: string;
+    /** Class for the title */
+    classTitle?: string;
+    /** Class for the aside */
+    classAside?: string;
+    /** Class for the `<ul>` */
+    classList?: string;
+    /** Class for every generated `<li>` */
+    classItem?: string;
+    /** Class for every generated `<a>` (`itemHref`) */
+    classItemLink?: string;
+    /** Class for the empty state */
+    classEmpty?: string;
+    /** Class for the footer */
+    classFooter?: string;
+    /** Bindable root element reference */
+    el?: HTMLDivElement;
+}
+declare function $$render<T = unknown>(): {
+    props: Props<T>;
+    exports: {};
+    bindings: "el";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T = unknown> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "el";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T = unknown>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T = unknown>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const ListGroup: $$IsomorphicComponent;
+type ListGroup<T = unknown> = InstanceType<typeof ListGroup<T>>;
+export default ListGroup;

package/dist/components/ListGroup/README.md

@@ -0,0 +1,299 @@
+# ListGroup
+
+A rounded, bordered box of rows split by hairlines, with an optional header (a title on the
+start side, a figure on the end side) and an optional footer line — the block a back office
+keeps drawing by hand. Each row is **one wrapping flex line** of parts: a code, a name that
+takes the leftover space, a run of facts. Nothing lines up across rows, on purpose: a row
+that carries an extra part does not push its siblings, and in a narrow drawer the trailing
+facts drop under the name one by one.
+
+Renders `<div>` › optional header `<div>` › `<ul role="list">` › `<li>` per row › optional
+footer `<div>`. The list is labelled by the title (`aria-labelledby`), so a screen reader
+announces "Loose items, list, 8 items".
+
+Not a `DataTable` (the rows share no columns — no alignment, sorting, paging or selection),
+not a `DescriptionList` (each row is a different thing, not a property of one thing), not a
+`Card` (no shadow, no padded body). `ListItemButton` is not its row.
+
+## Props
+
+| Prop            | Type                                                      | Default   | Description                                                                                                               |
+| --------------- | --------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `items`         | `T[]`                                                     | -         | The rows, in order. Data-driven form                                                                                      |
+| `renderItem`    | `Snippet<[ListGroupSnippetArg<T>]>`                       | -         | A row's content, inside the `<li>` (or inside the `<a>` with `itemHref`). Without it an item renders as `THC`             |
+| `children`      | `Snippet`                                                 | -         | Compositional form: `<li>`s rendered inside the `<ul>` _instead of_ `items`                                               |
+| `getItemId`     | `(item: T, index: number) => string \| number`            | the index | Keyed `{#each}` identity (same name and default as `DataTable`'s `getRowId`)                                              |
+| `itemProps`     | `(item: T, index: number) => ListGroupItemProps`          | -         | Attributes spread onto each `<li>` — the `data-*` hooks tests select on. A returned `class` merges after `classItem`      |
+| `itemHref`      | `(item: T, index: number) => string \| null \| undefined` | -         | When it returns a href, the row content is wrapped in `<a class="stuic-list-group-item-link">`, which becomes the row box |
+| `title`         | `THC`                                                     | -         | The header's start side; labels the list                                                                                  |
+| `titleLevel`    | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                              | -         | Render the title as `<hN>` instead of a `<div>`. Semantics only — the look never changes                                  |
+| `aside`         | `THC`                                                     | -         | The header's end side: a sum, a shortfall, an action. Pushed to the inline end, `tabular-nums`                            |
+| `footer`        | `THC`                                                     | -         | A line inside the box, under the rows, above a rule                                                                       |
+| `empty`         | `THC`                                                     | -         | Rendered **in place of** the `<ul>` when there are no rows. Without it, a group with no rows renders nothing at all       |
+| `listProps`     | `ListGroupListProps`                                      | -         | Attributes for the `<ul>` — `aria-label`, or `aria-labelledby` pointing at a caption outside the box                      |
+| `unstyled`      | `boolean`                                                 | `false`   | Skip all default styling (no `stuic-*` classes)                                                                           |
+| `class`         | `string`                                                  | -         | Additional CSS classes on the root (merged via twMerge)                                                                   |
+| `classHeader`   | `string`                                                  | -         | The header row                                                                                                            |
+| `classTitle`    | `string`                                                  | -         | The title                                                                                                                 |
+| `classAside`    | `string`                                                  | -         | The aside                                                                                                                 |
+| `classList`     | `string`                                                  | -         | The `<ul>`                                                                                                                |
+| `classItem`     | `string`                                                  | -         | Every generated `<li>`                                                                                                    |
+| `classItemLink` | `string`                                                  | -         | Every generated `<a>` (`itemHref`)                                                                                        |
+| `classEmpty`    | `string`                                                  | -         | The empty state                                                                                                           |
+| `classFooter`   | `string`                                                  | -         | The footer                                                                                                                |
+| `el`            | `HTMLDivElement`                                          | -         | Root element reference (bindable)                                                                                         |
+
+Any other attribute (`data-*`, `style`, `id`, …) goes to the root `<div>`. `title` is
+omitted from the root's HTML attributes because the prop is a `THC`, not the tooltip — as in
+`Card`. An `aria-label` on the root would name nothing (a `<div>` has no role); label a
+title-less list through `listProps`.
+
+The component is generic (`T = unknown`), so `renderItem`, `getItemId`, `itemProps` and
+`itemHref` are typed by your `items`.
+
+### Types
+
+```ts
+interface ListGroupSnippetArg<T> {
+	item: T;
+	index: number;
+}
+type ListGroupTitleLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/** `class` is a string, merged after `classItem` */
+type ListGroupItemProps = Omit<HTMLLiAttributes, "children" | "class"> & {
+	class?: string;
+};
+type ListGroupListProps = Omit<
+	HTMLAttributes<HTMLUListElement>,
+	"children" | "class" | "role"
+>;
+```
+
+## Usage
+
+### A kit group (the reference shape)
+
+```svelte
+<script lang="ts">
+	import { ListGroup } from "@marianmeres/stuic";
+</script>
+
+<ListGroup
+	class="text-sm"
+	items={group.lines}
+	getItemId={(line) => line.booking_id}
+	itemProps={(line) => ({
+		"data-line": "",
+		"data-booking-id": line.booking_id,
+		"data-short": line.short || null,
+	})}
+	titleLevel={3}
+	data-kit-group
+	data-kit={group.key}
+>
+	{#snippet title()}
+		{group.label}
+		{#if group.optional}
+			<span class="text-muted-foreground font-normal">optional</span>
+		{/if}
+	{/snippet}
+	{#snippet aside()}
+		<span>{group.requested} pc</span>
+		{#if group.short > 0}
+			<span class="text-destructive">−{group.short}</span>
+		{/if}
+	{/snippet}
+	{#snippet renderItem({ item: line })}
+		<span class="font-mono">{line.equipment_code}</span>
+		<span data-grow>{line.equipment_name}</span>
+		<span>×{line.requested}</span>
+		<span class="text-muted-foreground">picked {line.picked}/{line.requested}</span>
+		<span class="text-muted-foreground">{line.location}</span>
+	{/snippet}
+</ListGroup>
+```
+
+What is left on the consumer side is content styling only — mono, muted, a state colour.
+No `flex`, `gap`, `px-3 py-2`, `divide-y` or `rounded-md border`.
+
+### Linked rows and a footer
+
+```svelte
+<ListGroup
+	items={hits}
+	getItemId={(hit) => hit.id}
+	itemHref={(hit) => `#/find/${hit.kind}/${hit.id}`}
+	title="Equipment"
+	aside="3 of 15"
+	footer="+12 more — narrow the search."
+>
+	{#snippet renderItem({ item: hit })}
+		<span class="font-mono">{hit.id}</span>
+		<span data-grow>{hit.label}</span>
+		<span class="text-muted-foreground">{hit.meta}</span>
+	{/snippet}
+</ListGroup>
+```
+
+### An empty state
+
+```svelte
+<ListGroup items={crew} title="Crew" empty="Nobody and nothing booked for this job yet.">
+	{#snippet renderItem({ item })}…{/snippet}
+</ListGroup>
+
+<!-- or any THC, e.g. an EmptyState in a snippet -->
+<ListGroup items={scanned} title="Scanned">
+	{#snippet empty()}
+		<EmptyState size="sm" title="Nothing scanned yet" />
+	{/snippet}
+	{#snippet renderItem({ item })}…{/snippet}
+</ListGroup>
+```
+
+### Plain strings
+
+```svelte
+<ListGroup items={["Alpha", "Beta", "Gamma"]} title="Strings" />
+```
+
+### The `children` form
+
+For rows that don't come from one array, or a static list. The CSS selects structurally, so
+hand-written rows render exactly like generated ones — including a row whose only child is
+a link or a button:
+
+```svelte
+<ListGroup title="Shortcuts" class="text-sm">
+	<li><span data-grow>Open the scan hub</span><kbd>S</kbd></li>
+	<li><a href="#/find/search"><span data-grow>Search</span><kbd>/</kbd></a></li>
+	<li><button type="button" onclick={toggle}><span data-grow>Toggle</span></button></li>
+</ListGroup>
+```
+
+`empty` is an `items` feature: the component cannot count what a snippet renders, so
+`children` always renders the `<ul>` it is given. (A `children` list whose rows all render
+away collapses — no stray rule under the header.)
+
+## The row
+
+The row box is the `<li>` — or, on a linked row, the `<a>` (or a `<button>`) that is its only
+child. It is a wrapping flex line: `column-gap` / `row-gap`, `align-items` from a token
+(`center` by default; `baseline` for rows that align on text rather than on pills and
+buttons), and `overflow-wrap: anywhere`, so a long dotted path such as
+`hall-a.rack-a2.shelf-a2-2.bin` breaks instead of pushing a narrow drawer sideways.
+
+### `data-grow` — the part that absorbs the slack
+
+Put `data-grow` on the one part that should take the leftover space and push everything
+after it to the inline end (the name). It gets `flex: 1 1 var(--stuic-list-group-grow-basis)`
+(10rem), `min-width: 0` and a one-line truncation. The **basis**, not a `min-width`, carries
+"claim 10rem before anything wraps": flex line-breaking uses the basis, so the trailing parts
+wrap to the next line once the name would get less than that — and in a container narrower
+than 10rem the name still shrinks and truncates instead of overflowing. A row whose primary
+part should _wrap_ rather than truncate uses `class="flex-1"` and skips `data-grow`.
+
+### Second lines
+
+A child with `basis-full` (or `w-full`) forces a new line inside the same row; the row gap
+spaces it. No attribute is needed:
+
+```svelte
+{#snippet renderItem({ item: c })}
+	<span data-grow class="font-medium">{c.name}</span>
+	<span class="text-muted-foreground">{c.role}</span>
+	{#if c.clash}
+		<span class="text-destructive basis-full">{c.clash}</span>
+	{/if}
+{/snippet}
+```
+
+### Linked rows
+
+`itemHref` (or a hand-written `<li><a href>…</a></li>`) makes the **whole row** the anchor:
+the hit area, the hover background, and an inset focus ring that stays visible inside the
+clipped box, first and last row included. The anchor's accessible name is the whole row's
+text. **A linked row must not contain other interactive content** — a row that needs both a
+link and a button puts the `<a>` on its name in `renderItem`. There is deliberately no
+`onItemClick`: a real link beats a click handler (tab order, `Enter`, middle/cmd-click,
+"copy link address"). A `<button>` alone in a hand-written row gets the same row styling.
+
+A child that carries a stuic component class — a lone `Button`, `Pill` or `ListItemButton`
+— is **not** flattened into the row: it keeps its own box, and the row keeps its padding.
+
+## Empty
+
+- No rows and no `empty` → **nothing renders**, header included (the same rule as
+  `DescriptionList` and `Timeline`), so no `{#if items.length}` wrapper is needed.
+- No rows with `empty` → header, the empty part, footer. The empty part **replaces** the
+  `<ul>` rather than sitting in an `<li>`: a list whose only item says there are no items
+  announces "list, 1 item".
+
+## CSS Variables
+
+| Variable                               | Default                               | Description                                                        |
+| -------------------------------------- | ------------------------------------- | ------------------------------------------------------------------ |
+| `--stuic-list-group-bg`                | `transparent`                         | Box background (the surface behind shows through by default)       |
+| `--stuic-list-group-border-color`      | `var(--stuic-color-border)`           | Box border color                                                   |
+| `--stuic-list-group-border-width`      | `var(--stuic-border-width)`           | Box border width (not declared — tier fallback at the usage site)  |
+| `--stuic-list-group-radius`            | `var(--stuic-radius-container)`       | Box radius (not declared — tier fallback at the usage site)        |
+| `--stuic-list-group-rule-color`        | `var(--stuic-color-border)`           | Hairlines between header, rows and footer                          |
+| `--stuic-list-group-rule-width`        | `1px`                                 | Hairline width                                                     |
+| `--stuic-list-group-item-padding-x`    | `0.75rem`                             | Row inline padding — also the header, empty and footer padding     |
+| `--stuic-list-group-item-padding-y`    | `0.5rem`                              | Row block padding — also the default header, empty, footer padding |
+| `--stuic-list-group-item-gap-x`        | `0.75rem`                             | Gap between row parts (and header parts)                           |
+| `--stuic-list-group-item-gap-y`        | `0.25rem`                             | Gap between wrapped lines of a row                                 |
+| `--stuic-list-group-item-align`        | `center`                              | Row `align-items` (`baseline` for text-aligned rows)               |
+| `--stuic-list-group-grow-basis`        | `10rem`                               | What a `data-grow` part claims before its neighbours wrap          |
+| `--stuic-list-group-item-bg-hover`     | `var(--stuic-color-muted)`            | Linked row hover background                                        |
+| `--stuic-list-group-item-ring-width`   | `2px`                                 | Linked row focus ring width (drawn inset)                          |
+| `--stuic-list-group-item-ring-color`   | `var(--stuic-color-ring)`             | Linked row focus ring color                                        |
+| `--stuic-list-group-transition`        | `var(--stuic-transition)`             | Hover transition (not declared — tier fallback at the usage site)  |
+| `--stuic-list-group-header-padding-y`  | `--stuic-list-group-item-padding-y`   | Header block padding (not declared — fallback at the usage site)   |
+| `--stuic-list-group-header-bg`         | `transparent`                         | Header background                                                  |
+| `--stuic-list-group-title-font-weight` | `var(--font-weight-medium)`           | Title weight                                                       |
+| `--stuic-list-group-title-text`        | `var(--stuic-color-foreground)`       | Title color                                                        |
+| `--stuic-list-group-aside-text`        | `var(--stuic-color-muted-foreground)` | Aside color                                                        |
+| `--stuic-list-group-empty-text`        | `var(--stuic-color-muted-foreground)` | Empty state color                                                  |
+| `--stuic-list-group-footer-text`       | `var(--stuic-color-muted-foreground)` | Footer color                                                       |
+
+**No part declares a font size.** Rows, title, aside, empty and footer all inherit, so
+`class="text-sm"` on the root scales the whole box, and no part can default below the size
+you set. The title differs only in weight, the aside only in colour.
+
+**The header shares the rows' inline padding by construction** — there is no header
+`padding-x` token — so the header text and the row text always start at the same x.
+`--stuic-list-group-header-padding-y` is read as a fallback argument, so a scoped
+`--stuic-list-group-item-padding-y` on one group reaches its header too.
+
+The rules have their own width token (like `DescriptionList` and `Separator`), so a theme
+that zeroes box borders keeps its hairlines.
+
+A denser, muted-header variant is a few overrides:
+
+```svelte
+<ListGroup
+	style="--stuic-list-group-item-padding-x: 1rem;
+		--stuic-list-group-item-padding-y: 0.75rem;
+		--stuic-list-group-bg: var(--stuic-color-background);
+		--stuic-list-group-header-bg: var(--stuic-color-muted);
+		--stuic-list-group-title-font-weight: var(--font-weight-semibold);"
+	{items}
+	title="Before the job"
+/>
+```
+
+## Accessibility
+
+- The root is a `<div>`, not a `<section>`: a labelled `<section>` is a `region` landmark, and
+  a drawer holding six groups would add six. The header and footer are `<div>`s for the same
+  reason — outside `<main>` or sectioning content (a drawer, a dialog), a `<header>` is a
+  `banner` landmark and a `<footer>` a `contentinfo` one.
+- `role="list"` is set explicitly on the `<ul>`: WebKit/VoiceOver drops list semantics from a
+  `list-style: none` list.
+- The title labels the list via `aria-labelledby`. With `titleLevel`, it is also a heading.
+- `unstyled` removes the classes but keeps `role`, `aria-labelledby` and the `itemHref`
+  anchor — they are semantics, not styling.
+- The box is `overflow: clip` (so header and hover backgrounds follow the rounded corners).
+  `clip` creates no scroll container, so sticky content still sticks; stuic's tooltip and
+  popover are `position: fixed` and are not clipped.

package/dist/components/ListGroup/index.css

@@ -0,0 +1,279 @@
+/* ============================================================================
+   LIST GROUP COMPONENT TOKENS
+   Override globally: :root { --stuic-list-group-item-padding-x: 1rem; }
+   Override locally:  <ListGroup style="--stuic-list-group-header-bg: var(--stuic-color-muted);">
+   ============================================================================ */
+
+:root {
+	/* Box — radius and border width are read with a tier fallback at the usage site
+	   (`--stuic-list-group-radius` → `--stuic-radius-container`,
+	   `--stuic-list-group-border-width` → `--stuic-border-width`), never declared here. */
+	--stuic-list-group-bg: transparent;
+	--stuic-list-group-border-color: var(--stuic-color-border);
+
+	/* Rules between header, rows and footer. The component's own width (like
+	   DescriptionList and Separator), so a theme that zeroes box borders keeps them. */
+	--stuic-list-group-rule-color: var(--stuic-color-border);
+	--stuic-list-group-rule-width: 1px;
+
+	/* Rows */
+	--stuic-list-group-item-padding-x: 0.75rem;
+	--stuic-list-group-item-padding-y: 0.5rem;
+	--stuic-list-group-item-gap-x: 0.75rem;
+	--stuic-list-group-item-gap-y: 0.25rem;
+	--stuic-list-group-item-align: center;
+	--stuic-list-group-grow-basis: 10rem; /* what `data-grow` claims before neighbours wrap */
+
+	/* Linked rows */
+	--stuic-list-group-item-bg-hover: var(--stuic-color-muted);
+	--stuic-list-group-item-ring-width: 2px;
+	--stuic-list-group-item-ring-color: var(--stuic-color-ring);
+
+	/* Header. `--stuic-list-group-header-padding-y` is deliberately NOT declared: it is
+	   read as a fallback argument at the usage site, so a scoped override of
+	   `--stuic-list-group-item-padding-y` reaches the header too (declared here, it would
+	   resolve once at :root and ignore every scoped override). */
+	--stuic-list-group-header-bg: transparent;
+	--stuic-list-group-title-font-weight: var(--font-weight-medium);
+	--stuic-list-group-title-text: var(--stuic-color-foreground);
+	--stuic-list-group-aside-text: var(--stuic-color-muted-foreground);
+
+	/* Empty + footer */
+	--stuic-list-group-empty-text: var(--stuic-color-muted-foreground);
+	--stuic-list-group-footer-text: var(--stuic-color-muted-foreground);
+
+	/* Typography: no part declares a size — everything inherits, so `class="text-sm"` on
+	   the root scales the whole box. */
+}
+
+@layer components {
+	/* ============================================================================
+	   BOX
+	   ============================================================================ */
+
+	.stuic-list-group {
+		min-width: 0;
+		background: var(--stuic-list-group-bg);
+		border: var(--stuic-list-group-border-width, var(--stuic-border-width)) solid
+			var(--stuic-list-group-border-color);
+		border-radius: var(--stuic-list-group-radius, var(--stuic-radius-container));
+		/* The header background and a linked row's hover background must follow the
+		   rounded corners. `clip`, not `hidden`: it creates no scroll container, so a
+		   sticky element inside still sticks (`hidden` stays as the fallback for browsers
+		   without `clip`). stuic's tooltip and popover are `position: fixed`, which an
+		   overflow-clipped ancestor does not clip. */
+		overflow: hidden;
+		overflow: clip;
+	}
+
+	/* One rule between consecutive parts (header › list | empty › footer). On the part
+	   that FOLLOWS rather than under the header, so a header over a `children` list that
+	   rendered no rows (hidden below) does not draw a second line against the box. */
+	.stuic-list-group > * + * {
+		border-top: var(--stuic-list-group-rule-width) solid
+			var(--stuic-list-group-rule-color);
+	}
+
+	/* ============================================================================
+	   HEADER — shares the rows' inline padding BY CONSTRUCTION (not a separate
+	   token), so the header text and the row text always start at the same x.
+	   ============================================================================ */
+
+	.stuic-list-group-header {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		column-gap: var(--stuic-list-group-item-gap-x);
+		row-gap: var(--stuic-list-group-item-gap-y);
+		padding-block: var(
+			--stuic-list-group-header-padding-y,
+			var(--stuic-list-group-item-padding-y)
+		);
+		padding-inline: var(--stuic-list-group-item-padding-x);
+		min-width: 0;
+		overflow-wrap: anywhere;
+		background: var(--stuic-list-group-header-bg);
+	}
+
+	.stuic-list-group-title {
+		/* `titleLevel` is semantics only: undo the UA heading margin and size. `font`
+		   (not `font-size`) so the size is inherited, never declared. */
+		margin: 0;
+		font: inherit;
+		font-weight: var(--stuic-list-group-title-font-weight);
+		color: var(--stuic-list-group-title-text);
+		min-width: 0;
+	}
+
+	.stuic-list-group-aside {
+		margin-inline-start: auto;
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		column-gap: var(--stuic-list-group-item-gap-x);
+		row-gap: var(--stuic-list-group-item-gap-y);
+		color: var(--stuic-list-group-aside-text);
+		font-variant-numeric: tabular-nums;
+	}
+
+	/* ============================================================================
+	   LIST + ROWS — selected STRUCTURALLY (`> li`), not by class, so a hand-written
+	   `children` row renders exactly like a generated one. The per-part classes exist
+	   only as merge targets for `classItem` / `classItemLink`.
+
+	   The ROW BOX is the <li>, or — when its only child is a link or a button — that
+	   child. A child carrying a stuic component class (a `Button`, a `Pill`, a
+	   `ListItemButton`) is left alone: it has its own box, and flattening it into the
+	   row would strip its background and border. The generated `itemHref` anchor is
+	   matched by its own class for the same reason.
+	   ============================================================================ */
+
+	.stuic-list-group-list {
+		margin: 0;
+		padding: 0;
+		list-style: none;
+	}
+
+	/* A `children` list whose rows all rendered away (Svelte's anchors are comments) */
+	.stuic-list-group-list:empty {
+		display: none;
+	}
+
+	.stuic-list-group-list > li,
+	.stuic-list-group-list
+		> li
+		> :is(
+			.stuic-list-group-item-link,
+			:is(a, button):only-child:not([class^="stuic-"], [class*=" stuic-"])
+		) {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: var(--stuic-list-group-item-align);
+		column-gap: var(--stuic-list-group-item-gap-x);
+		row-gap: var(--stuic-list-group-item-gap-y);
+		padding-block: var(--stuic-list-group-item-padding-y);
+		padding-inline: var(--stuic-list-group-item-padding-x);
+		min-width: 0;
+		/* A dotted location path ("hall-a.rack-a2.shelf-a2-2.bin") is one unbreakable
+		   word. Without this its min-content pushes a 360px drawer sideways. `anywhere`
+		   and not `break-word`: only `anywhere` counts in min-content sizing. */
+		overflow-wrap: anywhere;
+	}
+
+	.stuic-list-group-list > li + li {
+		border-top: var(--stuic-list-group-rule-width) solid
+			var(--stuic-list-group-rule-color);
+	}
+
+	/* A row whose only child is a link or a button hands the box to that child */
+	.stuic-list-group-list
+		> li:has(
+			> :is(
+				.stuic-list-group-item-link,
+				:is(a, button):only-child:not([class^="stuic-"], [class*=" stuic-"])
+			)
+		) {
+		display: block;
+		padding: 0;
+	}
+
+	/* ============================================================================
+	   LINKED ROWS
+	   ============================================================================ */
+
+	.stuic-list-group-list
+		> li
+		> :is(
+			.stuic-list-group-item-link,
+			:is(a, button):only-child:not([class^="stuic-"], [class*=" stuic-"])
+		) {
+		/* a <button> is shrink-to-fit even as a flex container */
+		width: 100%;
+		box-sizing: border-box;
+		margin: 0;
+		color: inherit;
+		/* for <button> rows */
+		font: inherit;
+		text-align: start;
+		text-decoration: none;
+		background: none;
+		border: 0;
+		border-radius: 0;
+		cursor: pointer;
+		-webkit-tap-highlight-color: transparent;
+		transition: background-color
+			var(--stuic-list-group-transition, var(--stuic-transition));
+	}
+
+	.stuic-list-group-list
+		> li
+		> :is(
+			.stuic-list-group-item-link,
+			:is(a, button):only-child:not([class^="stuic-"], [class*=" stuic-"])
+		):hover:not(:disabled) {
+		background: var(--stuic-list-group-item-bg-hover);
+	}
+
+	.stuic-list-group-list
+		> li
+		> :is(
+			.stuic-list-group-item-link,
+			:is(a, button):only-child:not([class^="stuic-"], [class*=" stuic-"])
+		):focus-visible {
+		outline: var(--stuic-list-group-item-ring-width) solid
+			var(--stuic-list-group-item-ring-color);
+		/* inset: the box clips, and the first/last row sit against its edge */
+		outline-offset: calc(-1 * var(--stuic-list-group-item-ring-width));
+	}
+
+	.stuic-list-group-list
+		> li
+		> :is(
+			.stuic-list-group-item-link,
+			:is(a, button):only-child:not([class^="stuic-"], [class*=" stuic-"])
+		):disabled {
+		cursor: default;
+	}
+
+	/* ============================================================================
+	   ROW CONTENT CONVENTION — `data-grow` on the one part that takes the leftover
+	   space. The BASIS, not a min-width, carries "claim 10rem before anything wraps":
+	   flex line-breaking uses the hypothetical size, so the trailing parts wrap once
+	   the name would get less than that — and in a container narrower than the basis
+	   the part still shrinks and truncates instead of overflowing.
+	   ============================================================================ */
+
+	.stuic-list-group-list > li > [data-grow],
+	.stuic-list-group-list
+		> li
+		> :is(
+			.stuic-list-group-item-link,
+			:is(a, button):only-child:not([class^="stuic-"], [class*=" stuic-"])
+		)
+		> [data-grow] {
+		flex: 1 1 var(--stuic-list-group-grow-basis);
+		min-width: 0;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	/* ============================================================================
+	   EMPTY + FOOTER
+	   ============================================================================ */
+
+	.stuic-list-group-empty,
+	.stuic-list-group-footer {
+		padding-block: var(--stuic-list-group-item-padding-y);
+		padding-inline: var(--stuic-list-group-item-padding-x);
+		overflow-wrap: anywhere;
+	}
+
+	.stuic-list-group-empty {
+		color: var(--stuic-list-group-empty-text);
+	}
+
+	.stuic-list-group-footer {
+		color: var(--stuic-list-group-footer-text);
+	}
+}

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

@@ -0,0 +1 @@
+export { default as ListGroup, type Props as ListGroupProps, type ListGroupSnippetArg, type ListGroupTitleLevel, type ListGroupItemProps, type ListGroupListProps, } from "./ListGroup.svelte";

package/dist/components/ListGroup/index.js

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

package/dist/index.css

@@ -110,6 +110,7 @@ In practice:
 @import "./components/IconSwap/index.css";
 @import "./components/Input/index.css";
 @import "./components/KbdShortcut/index.css";
+@import "./components/ListGroup/index.css";
 @import "./components/ListItemButton/index.css";
 @import "./components/Modal/index.css";
 @import "./components/ModalDialog/index.css";

package/dist/index.d.ts

@@ -66,6 +66,7 @@ export * from "./components/KbdShortcut/index.js";
 export * from "./components/LoginForm/index.js";
 export * from "./components/RegisterForm/index.js";
 export * from "./components/LoginOrRegisterForm/index.js";
+export * from "./components/ListGroup/index.js";
 export * from "./components/ListItemButton/index.js";
 export * from "./components/Modal/index.js";
 export * from "./components/ModalDialog/index.js";

package/dist/index.js

@@ -72,6 +72,7 @@ export * from "./components/KbdShortcut/index.js";
 export * from "./components/LoginForm/index.js";
 export * from "./components/RegisterForm/index.js";
 export * from "./components/LoginOrRegisterForm/index.js";
+export * from "./components/ListGroup/index.js";
 export * from "./components/ListItemButton/index.js";
 export * from "./components/Modal/index.js";
 export * from "./components/ModalDialog/index.js";

package/docs/domains/components.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-80 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
+82 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
 
 ## Component Categories
 
@@ -110,6 +110,7 @@
 | 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    |
+| ListGroup           | Bordered box of wrapping rows (`<ul>`): header title/aside, hairlines, linked rows, empty, footer    |
 | Timeline            | Vertical event list on a rail: dot/icon/custom markers, inline or opposite time, alternate layout    |
 | Gantt               | Horizontal schedule chart: day/week/month axis, bars, milestones, progress, today line               |
 | TrendChart          | Svelte wrapper for `@marianmeres/trend-chart` (subpath-only: `@marianmeres/stuic/trend-chart`)       |
@@ -1088,6 +1089,59 @@ Prefix: `--stuic-description-list-*`
 
 ---
 
+## ListGroup
+
+A rounded, bordered box of rows split by hairlines — optional header (title start, figure end), optional footer line — the block back offices keep hand-rolling. Renders `<div>` › header `<div>` › `<ul role="list">` › `<li>` per row › footer `<div>`. Each row is **one wrapping flex line** of parts (a code, a name that takes the slack, a run of facts), not columns: nothing lines up across rows, and in a narrow drawer the trailing facts drop under the name. Not a `DataTable` (no column model), not a `DescriptionList` (many things, not properties of one), not a `Card` (no shadow, no padded body). Generic over `T`.
+
+### Exports
+
+| Export                | Kind      | Description                                                                           |
+| --------------------- | --------- | ------------------------------------------------------------------------------------- |
+| `ListGroup`           | component | Main component                                                                        |
+| `ListGroupProps`      | type      | Props type (`Props<T>`)                                                               |
+| `ListGroupSnippetArg` | type      | `{ item, index }` — `renderItem`'s argument                                           |
+| `ListGroupTitleLevel` | type      | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                                                          |
+| `ListGroupItemProps`  | type      | `HTMLLiAttributes` minus `children`, with `class?: string` — what `itemProps` returns |
+| `ListGroupListProps`  | type      | `HTMLAttributes<HTMLUListElement>` minus `children`/`class`/`role` — `listProps`      |
+
+### Key Props
+
+| Prop         | Type                                   | Default | Description                                                                               |
+| ------------ | -------------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
+| `items`      | `T[]`                                  | —       | The rows; without `renderItem` an item renders as `THC`                                   |
+| `renderItem` | `Snippet<[{ item, index }]>`           | —       | Row content, inside the `<li>` (or the `itemHref` anchor)                                 |
+| `children`   | `Snippet`                              | —       | `<li>`s rendered inside the `<ul>` _instead of_ `items`                                   |
+| `getItemId`  | `(item, index) => string \| number`    | index   | Keyed `{#each}` identity                                                                  |
+| `itemProps`  | `(item, index) => ListGroupItemProps`  | —       | Attributes on each `<li>` (the `data-*` hooks tests select on); `class` merges last       |
+| `itemHref`   | `(item, index) => string \| undefined` | —       | Wraps the row in `a.stuic-list-group-item-link`, which becomes the row box                |
+| `title`      | `THC`                                  | —       | Header start side; labels the `<ul>` (`aria-labelledby`)                                  |
+| `titleLevel` | `1…6`                                  | —       | `<hN>` instead of `<div>` — semantics only, look unchanged                                |
+| `aside`      | `THC`                                  | —       | Header end side (`tabular-nums`, muted). Never an automatic row count                     |
+| `footer`     | `THC`                                  | —       | A line inside the box under the rows                                                      |
+| `empty`      | `THC`                                  | —       | Replaces the `<ul>` when there are no rows; without it an empty group renders **nothing** |
+| `listProps`  | `ListGroupListProps`                   | —       | Attributes for the `<ul>` — how a title-less list gets `aria-label`/`aria-labelledby`     |
+
+Class slots: `class`, `classHeader`, `classTitle`, `classAside`, `classList`, `classItem`, `classItemLink`, `classEmpty`, `classFooter`. Rest props go to the root `<div>`.
+
+### Row contract (works in both forms)
+
+The CSS selects **structurally** (`ul > li`, `> li > :is(a, button):only-child`), so a hand-written `children` row renders exactly like a generated one. A row whose only child is a plain `<a>`/`<button>` hands the row box (padding, hover, inset focus ring) to it; a child carrying a stuic component class (a lone `Button`, `Pill`, `ListItemButton`) is left alone so it keeps its own box. `data-grow` on one part gives it `flex: 1 1 var(--stuic-list-group-grow-basis)` (10rem) + truncation — the **basis**, not a min-width, is what makes the neighbours wrap once the name would get less than 10rem, while a container narrower than that still shrinks it instead of overflowing. A second line is a child with `basis-full`.
+
+### Deliberate choices
+
+- Root, header and footer are `<div>`s: a labelled `<section>` is a `region` landmark, and outside `<main>`/sectioning content (a drawer, a dialog) a `<header>`/`<footer>` is a `banner`/`contentinfo` landmark — one per group.
+- `role="list"` is explicit (WebKit drops list semantics from `list-style: none`).
+- No part declares a `font-size` — `class="text-sm"` on the root scales the box. The header has no own `padding-x`: it shares the rows', so header and row text always start at the same x. `--stuic-list-group-header-padding-y` is a usage-site fallback, never declared, so a scoped `--stuic-list-group-item-padding-y` reaches the header.
+- `overflow: clip` (not `hidden`) on the box so header/hover backgrounds follow the radius without creating a scroll container.
+
+### CSS Tokens
+
+Prefix: `--stuic-list-group-*`
+
+`bg`, `border-color`, `rule-color`, `rule-width`, `item-padding-x`, `item-padding-y`, `item-gap-x`, `item-gap-y`, `item-align`, `grow-basis`, `item-bg-hover`, `item-ring-width`, `item-ring-color`, `header-bg`, `title-font-weight`, `title-text`, `aside-text`, `empty-text`, `footer-text`. Not declared (usage-site fallbacks): `radius` (→ `--stuic-radius-container`), `border-width` (→ `--stuic-border-width`), `transition` (→ `--stuic-transition`), `header-padding-y` (→ `item-padding-y`).
+
+---
+
 ## 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.189.0",
+	"version": "3.190.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",