@marianmeres/stuic 3.167.0 → 3.168.0

package/dist/components/Pagination/README.md

@@ -0,0 +1,152 @@
+# Pagination
+
+Standalone pagination control for lists, search results, and custom views. Two
+variants: `compact` — prev / "Page X of Y" / next, which _is_ the pager `DataTable`
+renders internally — and `numbers` — windowed page-number buttons with ellipsis gaps
+(the classic `1 … 4 5 6 … 20`).
+
+Consumes the same `PagingCalcResult` from
+[`@marianmeres/paging-store`](https://github.com/marianmeres/paging-store) that
+`DataTable` does, so one paging store (or one `calculatePaging` call) can feed both.
+For quick standalone use, `total`/`limit`/`offset` props compute the paging
+internally.
+
+## Props
+
+| Prop                 | Type                     | Default     | Description                                                                           |
+| -------------------- | ------------------------ | ----------- | ------------------------------------------------------------------------------------- |
+| `paging`             | `PagingCalcResult`       | -           | Paging metadata (same shape `DataTable` consumes); wins over `total`/`limit`/`offset` |
+| `total`              | `number`                 | -           | Convenience alternative to `paging`: total item count                                 |
+| `limit`              | `number`                 | `10`        | Convenience alternative to `paging`: page size                                        |
+| `offset`             | `number`                 | `0`         | Convenience alternative to `paging`: current offset                                   |
+| `onPageChange`       | `(offset, page) => void` | -           | Navigation callback: new offset (`DataTable`-compatible first arg) + 1-based page     |
+| `variant`            | `"compact" \| "numbers"` | `"compact"` | Prev/info/next, or windowed page-number buttons                                       |
+| `siblingCount`       | `number`                 | `1`         | Numbers variant: pages always shown around the current page                           |
+| `boundaryCount`      | `number`                 | `1`         | Numbers variant: pages always shown at the start and end                              |
+| `showFirstLast`      | `boolean`                | `false`     | Render first/last jump buttons (« »)                                                  |
+| `showInfo`           | `boolean`                | per variant | "Page X of Y" info; defaults `true` for compact, `false` for numbers                  |
+| `hideSinglePage`     | `boolean`                | `true`      | Render nothing when there is at most one page (the `DataTable` rule)                  |
+| `disabled`           | `boolean`                | `false`     | Disable all controls (e.g. while loading)                                             |
+| `size`               | `ButtonSize`             | `"sm"`      | Size preset of the inner Buttons                                                      |
+| `t`                  | `TranslateFn`            | English     | i18n translate function (see below)                                                   |
+| `unstyled`           | `boolean`                | `false`     | Skip pagination styling (inner Buttons keep their own Button styling)                 |
+| `class`              | `string`                 | -           | Additional CSS classes (merged via twMerge)                                           |
+| `classButton`        | `string`                 | -           | Class for every inner button                                                          |
+| `classButtonCurrent` | `string`                 | -           | Extra class for the current-page button (numbers variant)                             |
+| `classInfo`          | `string`                 | -           | Class for the "Page X of Y" info                                                      |
+| `el`                 | `HTMLElement`            | -           | Element reference (bindable)                                                          |
+
+## Snippet Props
+
+| Snippet      | Description                                                              |
+| ------------ | ------------------------------------------------------------------------ |
+| `renderInfo` | Override the "Page X of Y" info content; receives the `PagingCalcResult` |
+
+## Usage
+
+### Basic (compact)
+
+```svelte
+<script lang="ts">
+	import { Pagination } from "@marianmeres/stuic";
+
+	let offset = $state(0);
+</script>
+
+<Pagination total={137} limit={10} {offset} onPageChange={(o) => (offset = o)} />
+```
+
+### With a paging store (shared with DataTable)
+
+The `paging` prop takes the exact object `DataTable` consumes — hide the table's
+built-in pager and drive both from one store:
+
+```svelte
+<script lang="ts">
+	import { DataTable, Pagination } from "@marianmeres/stuic";
+	import { createPagingStore } from "@marianmeres/paging-store";
+
+	const paging = createPagingStore({ total: 137, limit: 10, offset: 0 });
+	const onPageChange = (offset: number) => paging.update({ offset });
+</script>
+
+<DataTable {columns} {data} paging={$paging} showPager={false} />
+<Pagination paging={$paging} {onPageChange} variant="numbers" />
+```
+
+### Numbers variant
+
+```svelte
+<Pagination variant="numbers" total={200} {offset} onPageChange={(o) => (offset = o)} />
+
+<!-- wider window, first/last jumps -->
+<Pagination
+	variant="numbers"
+	siblingCount={2}
+	boundaryCount={2}
+	showFirstLast
+	total={200}
+	{offset}
+	onPageChange={(o) => (offset = o)}
+/>
+```
+
+### i18n
+
+Built-in English; bundled Slovak (`PAGINATION_MESSAGES_SK`) is opt-in. The
+`previous_page`, `next_page` and `page_x_of_y` keys are identical to `DataTable`'s,
+so one merged catalog (and one `t`) can serve both components.
+
+```svelte
+<script lang="ts">
+	import {
+		Pagination,
+		createPaginationT,
+		PAGINATION_MESSAGES_SK,
+	} from "@marianmeres/stuic";
+	const t = createPaginationT(PAGINATION_MESSAGES_SK);
+</script>
+
+<Pagination {paging} {onPageChange} {t} />
+```
+
+### Custom info
+
+```svelte
+<Pagination {paging} {onPageChange}>
+	{#snippet renderInfo(p)}
+		{p.offset + 1}–{Math.min(p.offset + p.limit, p.total)} of {p.total}
+	{/snippet}
+</Pagination>
+```
+
+### Single page
+
+By default nothing renders when there is at most one page (same rule as
+`DataTable`'s internal pager). Keep it visible with `hideSinglePage={false}`.
+
+## Accessibility
+
+- Renders a `<nav aria-label="Pagination">` landmark (label localized via `t`).
+- Every button carries a localized `aria-label`; the current page button (numbers
+  variant) is marked `aria-current="page"`.
+
+## Exports
+
+Besides the component: `paginationRange(currentPage, pageCount, { siblingCount, boundaryCount })`
+— the pure windowing helper behind the numbers variant, usable for fully custom pagers.
+
+## CSS Variables
+
+| Variable                              | Default                          | Description                                        |
+| ------------------------------------- | -------------------------------- | -------------------------------------------------- |
+| `--stuic-pagination-gap`              | `0.5rem`                         | Gap between controls                               |
+| `--stuic-pagination-button-min-width` | `--stuic-button-min-height-sm`   | Min button width (keeps number buttons square-ish) |
+| `--stuic-pagination-info-font-size`   | `--text-sm`                      | Info font size                                     |
+| `--stuic-pagination-info-text`        | `--stuic-color-muted-foreground` | Info color                                         |
+| `--stuic-pagination-ellipsis-text`    | `--stuic-color-muted-foreground` | Ellipsis color                                     |
+
+## Data Attributes
+
+- `data-variant` - `"compact" | "numbers"` (on the root `<nav>`)
+- `data-current` - `"true"` on the current-page button (numbers variant)

package/dist/components/Pagination/i18n-sk.d.ts

@@ -0,0 +1,17 @@
+import type { PaginationMessages } from "./i18n.js";
+/**
+ * Slovak message catalog for `Pagination`. Opt-in — English stays the built-in default,
+ * and this module is only pulled into a bundle when it is actually imported (the
+ * component itself never references it).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Pagination, createPaginationT, PAGINATION_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createPaginationT(PAGINATION_MESSAGES_SK);
+ * </script>
+ *
+ * <Pagination {paging} {onPageChange} {t} />
+ * ```
+ */
+export declare const PAGINATION_MESSAGES_SK: PaginationMessages;

package/dist/components/Pagination/i18n-sk.js

@@ -0,0 +1,24 @@
+/**
+ * Slovak message catalog for `Pagination`. Opt-in — English stays the built-in default,
+ * and this module is only pulled into a bundle when it is actually imported (the
+ * component itself never references it).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Pagination, createPaginationT, PAGINATION_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createPaginationT(PAGINATION_MESSAGES_SK);
+ * </script>
+ *
+ * <Pagination {paging} {onPageChange} {t} />
+ * ```
+ */
+export const PAGINATION_MESSAGES_SK = {
+    previous_page: "Späť",
+    next_page: "Ďalej",
+    first_page: "Prvá strana",
+    last_page: "Posledná strana",
+    page_x_of_y: "Strana {page} z {pageCount}",
+    go_to_page_x: "Prejsť na stranu {page}",
+    pagination: "Stránkovanie",
+};

package/dist/components/Pagination/i18n.d.ts

@@ -0,0 +1,41 @@
+import type { TranslateFn } from "../../types.js";
+/**
+ * The built-in (English) message catalog of `Pagination`. Also the fallback of every
+ * other bundled locale, so a locale missing a key still renders text.
+ *
+ * The `previous_page`, `next_page` and `page_x_of_y` keys are intentionally identical
+ * to `DataTable`'s, so one merged catalog (and one `t`) can serve both components.
+ *
+ * Placeholders are single-brace (`{page}`, `{pageCount}`, ...).
+ */
+export declare const PAGINATION_MESSAGES_EN: {
+    previous_page: string;
+    next_page: string;
+    first_page: string;
+    last_page: string;
+    page_x_of_y: string;
+    go_to_page_x: string;
+    pagination: string;
+};
+/** Every message key `Pagination` may look up. */
+export type PaginationMessageKey = keyof typeof PAGINATION_MESSAGES_EN;
+/** A (possibly partial) catalog for one locale. */
+export type PaginationMessages = Record<PaginationMessageKey, string>;
+/**
+ * Builds the `t` prop of `Pagination` from a message catalog. Unknown or untranslated
+ * keys fall back to `fallbackMessages` (English by default), so a catalog may safely be
+ * partial and never renders a raw key.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Pagination, createPaginationT, PAGINATION_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createPaginationT(PAGINATION_MESSAGES_SK);
+ * </script>
+ *
+ * <Pagination {paging} {onPageChange} {t} />
+ * ```
+ */
+export declare function createPaginationT(messages: Partial<PaginationMessages> | Record<string, string>, fallbackMessages?: Partial<PaginationMessages> | Record<string, string>): TranslateFn;
+/** The component's built-in English `t`. */
+export declare const t_default: TranslateFn;

package/dist/components/Pagination/i18n.js

@@ -0,0 +1,49 @@
+import { isPlainObject } from "../../utils/is-plain-object.js";
+import { replaceMap } from "../../utils/replace-map.js";
+/**
+ * The built-in (English) message catalog of `Pagination`. Also the fallback of every
+ * other bundled locale, so a locale missing a key still renders text.
+ *
+ * The `previous_page`, `next_page` and `page_x_of_y` keys are intentionally identical
+ * to `DataTable`'s, so one merged catalog (and one `t`) can serve both components.
+ *
+ * Placeholders are single-brace (`{page}`, `{pageCount}`, ...).
+ */
+export const PAGINATION_MESSAGES_EN = {
+    previous_page: "Prev",
+    next_page: "Next",
+    first_page: "First page",
+    last_page: "Last page",
+    page_x_of_y: "Page {page} of {pageCount}",
+    go_to_page_x: "Go to page {page}",
+    pagination: "Pagination",
+};
+/**
+ * Builds the `t` prop of `Pagination` from a message catalog. Unknown or untranslated
+ * keys fall back to `fallbackMessages` (English by default), so a catalog may safely be
+ * partial and never renders a raw key.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Pagination, createPaginationT, PAGINATION_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createPaginationT(PAGINATION_MESSAGES_SK);
+ * </script>
+ *
+ * <Pagination {paging} {onPageChange} {t} />
+ * ```
+ */
+export function createPaginationT(messages, fallbackMessages = PAGINATION_MESSAGES_EN) {
+    return (k, values = null, fallback = "") => {
+        const out = messages[k] ??
+            fallbackMessages[k] ??
+            (typeof fallback === "string" ? fallback : k);
+        return isPlainObject(values)
+            ? replaceMap(out, values, {
+                preSearchKeyTransform: (k) => `{${k}}`,
+            })
+            : out;
+    };
+}
+/** The component's built-in English `t`. */
+export const t_default = createPaginationT(PAGINATION_MESSAGES_EN);

package/dist/components/Pagination/index.css

@@ -0,0 +1,50 @@
+/* ============================================================================
+   PAGINATION COMPONENT TOKENS
+   Override globally: :root { --stuic-pagination-gap: 1rem; }
+   Override locally:  <Pagination style="--stuic-pagination-button-min-width: 2rem;">
+   ============================================================================ */
+
+/* prettier-ignore */
+:root {
+	--stuic-pagination-gap: 0.5rem;
+
+	/* Keeps single-character buttons («, ‹, page numbers) square-ish and aligned.
+	   Sized to the `size="sm"` Button height. Text buttons (Prev/Next) simply exceed it. */
+	--stuic-pagination-button-min-width: var(--stuic-button-min-height-sm, 2.75rem);
+
+	/* "Page X of Y" info */
+	--stuic-pagination-info-font-size: var(--text-sm);
+	--stuic-pagination-info-text: var(--stuic-color-muted-foreground);
+
+	/* Ellipsis gap (numbers variant) */
+	--stuic-pagination-ellipsis-text: var(--stuic-color-muted-foreground);
+}
+
+@layer components {
+	.stuic-pagination {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		flex-wrap: wrap;
+		gap: var(--stuic-pagination-gap);
+	}
+
+	.stuic-pagination-button {
+		min-width: var(--stuic-pagination-button-min-width);
+	}
+
+	.stuic-pagination-info {
+		font-size: var(--stuic-pagination-info-font-size);
+		color: var(--stuic-pagination-info-text);
+		white-space: nowrap;
+	}
+
+	.stuic-pagination-ellipsis {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		min-width: var(--stuic-pagination-button-min-width);
+		color: var(--stuic-pagination-ellipsis-text);
+		user-select: none;
+	}
+}

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

@@ -0,0 +1,4 @@
+export { default as Pagination, type Props as PaginationProps, type PaginationVariant, } from "./Pagination.svelte";
+export { paginationRange, type PaginationRangeItem, type PaginationRangeOptions, } from "./pagination-range.js";
+export { createPaginationT, PAGINATION_MESSAGES_EN, type PaginationMessageKey, type PaginationMessages, } from "./i18n.js";
+export { PAGINATION_MESSAGES_SK } from "./i18n-sk.js";

package/dist/components/Pagination/index.js

@@ -0,0 +1,4 @@
+export { default as Pagination, } from "./Pagination.svelte";
+export { paginationRange, } from "./pagination-range.js";
+export { createPaginationT, PAGINATION_MESSAGES_EN, } from "./i18n.js";
+export { PAGINATION_MESSAGES_SK } from "./i18n-sk.js";

package/dist/components/Pagination/pagination-range.d.ts

@@ -0,0 +1,21 @@
+/** One rendered slot of the "numbers" variant: a page number or an ellipsis gap. */
+export type PaginationRangeItem = number | "ellipsis";
+export interface PaginationRangeOptions {
+    /** How many pages to always show around the current page (default 1). */
+    siblingCount?: number;
+    /** How many pages to always show at the start and at the end (default 1). */
+    boundaryCount?: number;
+}
+/**
+ * Computes the windowed page list of the "numbers" variant: boundary pages at both
+ * ends, siblings around the current page, and `"ellipsis"` tokens for the collapsed
+ * gaps. The window is stable — for a given `pageCount` and options, every
+ * `currentPage` yields the same number of slots (no layout jumping while paging).
+ *
+ * @example
+ * ```ts
+ * paginationRange(5, 10); // [1, "ellipsis", 4, 5, 6, "ellipsis", 10]
+ * paginationRange(1, 5);  // [1, 2, 3, 4, 5]
+ * ```
+ */
+export declare function paginationRange(currentPage: number, pageCount: number, options?: PaginationRangeOptions): PaginationRangeItem[];

package/dist/components/Pagination/pagination-range.js

@@ -0,0 +1,41 @@
+/**
+ * Computes the windowed page list of the "numbers" variant: boundary pages at both
+ * ends, siblings around the current page, and `"ellipsis"` tokens for the collapsed
+ * gaps. The window is stable — for a given `pageCount` and options, every
+ * `currentPage` yields the same number of slots (no layout jumping while paging).
+ *
+ * @example
+ * ```ts
+ * paginationRange(5, 10); // [1, "ellipsis", 4, 5, 6, "ellipsis", 10]
+ * paginationRange(1, 5);  // [1, 2, 3, 4, 5]
+ * ```
+ */
+export function paginationRange(currentPage, pageCount, options = {}) {
+    const siblingCount = Math.max(0, Math.floor(options.siblingCount ?? 1));
+    const boundaryCount = Math.max(0, Math.floor(options.boundaryCount ?? 1));
+    if (!Number.isFinite(pageCount) || pageCount <= 0)
+        return [];
+    const page = Math.min(Math.max(1, Math.floor(currentPage) || 1), pageCount);
+    const range = (start, end) => Array.from({ length: end - start + 1 }, (_, i) => start + i);
+    const startPages = range(1, Math.min(boundaryCount, pageCount));
+    const endPages = range(Math.max(pageCount - boundaryCount + 1, boundaryCount + 1), pageCount);
+    const siblingsStart = Math.max(Math.min(page - siblingCount, pageCount - boundaryCount - siblingCount * 2 - 1), boundaryCount + 2);
+    const siblingsEnd = Math.min(Math.max(page + siblingCount, boundaryCount + siblingCount * 2 + 2), endPages.length > 0 ? endPages[0] - 2 : pageCount - 1);
+    return [
+        ...startPages,
+        // start gap: ellipsis, the single page it would hide, or nothing
+        ...(siblingsStart > boundaryCount + 2
+            ? ["ellipsis"]
+            : boundaryCount + 1 < pageCount - boundaryCount
+                ? [boundaryCount + 1]
+                : []),
+        ...range(siblingsStart, siblingsEnd),
+        // end gap: ellipsis, the single page it would hide, or nothing
+        ...(siblingsEnd < pageCount - boundaryCount - 1
+            ? ["ellipsis"]
+            : pageCount - boundaryCount > boundaryCount
+                ? [pageCount - boundaryCount]
+                : []),
+        ...endPages,
+    ];
+}

package/dist/components/Stat/README.md

@@ -0,0 +1,157 @@
+# Stat
+
+A KPI/stat card: a metric label, a prominent value, and an optional delta with trend
+arrow and color-coded semantics (up/down/flat), plus an optional hint, corner icon, and
+footer area (e.g. for a sparkline). Renders as a `<div>`, or as an `<a>`/`<button>` when
+`href`/`onclick` is provided.
+
+## Usage
+
+```svelte
+<script>
+	import { Stat } from "@marianmeres/stuic";
+	// optional, for the sparkline footer example below (see TrendChart's README):
+	import { TrendChart } from "@marianmeres/stuic/trend-chart";
+</script>
+
+<!-- Basic -->
+<Stat
+	label="Total Revenue"
+	value="$45,231.89"
+	delta="+20.1%"
+	trend="up"
+	hint="vs. last month"
+/>
+
+<!-- Trend down (auto-colored destructive) -->
+<Stat
+	label="Bounce Rate"
+	value="47.3%"
+	delta="+2.4%"
+	trend="up"
+	trendIntent="destructive"
+/>
+
+<!-- Down is good here: override the auto color mapping -->
+<Stat label="Churn" value="2.1%" delta="-0.4%" trend="down" trendIntent="success" />
+
+<!-- With a corner icon -->
+<Stat label="Active Users" value="2,338" delta="+180" trend="up">
+	{#snippet renderIcon()}
+		{@html iconUser({ size: 20 })}
+	{/snippet}
+</Stat>
+
+<!-- Clickable (renders as <a>) -->
+<Stat
+	href="/analytics/revenue"
+	label="Revenue"
+	value="$45,231"
+	delta="+20.1%"
+	trend="up"
+/>
+
+<!-- Footer (sparkline, actions, ...) — first-class pairing with the TrendChart
+     wrapper (subpath import; optional @marianmeres/trend-chart peer dep) -->
+<Stat label="Requests" value="1.2M" delta="+8.4%" trend="up">
+	{#snippet renderFooter()}
+		<TrendChart data={[42, 51, 48, 63, 58, 71, 84]} sparkline />
+	{/snippet}
+</Stat>
+
+<!-- Full override -->
+<Stat>
+	<div class="p-4">Completely custom content</div>
+</Stat>
+```
+
+## Props
+
+| Prop             | Type                                                             | Default  | Description                                                                                                                                    |
+| ---------------- | ---------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`          | `THC`                                                            | -        | Small label above the value (metric name)                                                                                                      |
+| `value`          | `THC \| number`                                                  | -        | The primary metric value, preformatted (e.g. `"$45,231.89"`)                                                                                   |
+| `delta`          | `THC \| number`                                                  | -        | Delta/change indicator, preformatted (e.g. `"+20.1%"`)                                                                                         |
+| `trend`          | `"up" \| "down" \| "flat"`                                       | -        | Trend direction — drives the arrow and (via `trendIntent="auto"`) the delta color                                                              |
+| `trendIntent`    | `"auto" \| "success" \| "destructive" \| "warning" \| "neutral"` | `"auto"` | Delta color semantics. `"auto"` maps up→success, down→destructive, flat→neutral. Set explicitly for metrics where down is good (churn, costs). |
+| `showTrendArrow` | `boolean`                                                        | `true`   | Show the trend direction arrow next to the delta                                                                                               |
+| `hint`           | `THC`                                                            | -        | Secondary text next to the delta (e.g. "vs. last month")                                                                                       |
+| `href`           | `string`                                                         | -        | Renders stat as `<a>`                                                                                                                          |
+| `onclick`        | `(e: MouseEvent) => void`                                        | -        | Renders stat as `<button>`                                                                                                                     |
+| `disabled`       | `boolean`                                                        | `false`  | Disabled state (reduced opacity, no interaction)                                                                                               |
+| `unstyled`       | `boolean`                                                        | `false`  | Skip all default styling                                                                                                                       |
+| `class`          | `string`                                                         | -        | Additional CSS classes for the stat shell                                                                                                      |
+| `classLabel`     | `string`                                                         | -        | Additional CSS classes for the label                                                                                                           |
+| `classValue`     | `string`                                                         | -        | Additional CSS classes for the value                                                                                                           |
+| `classDelta`     | `string`                                                         | -        | Additional CSS classes for the delta                                                                                                           |
+| `classHint`      | `string`                                                         | -        | Additional CSS classes for the hint                                                                                                            |
+| `classFooter`    | `string`                                                         | -        | Additional CSS classes for the footer                                                                                                          |
+| `el`             | `HTMLElement`                                                    | -        | Bindable element reference                                                                                                                     |
+
+## Snippets
+
+| Snippet        | Parameters | Description                                       |
+| -------------- | ---------- | ------------------------------------------------- |
+| `children`     | -          | Overrides the entire stat body                    |
+| `renderIcon`   | -          | Icon area in the top-right corner (next to label) |
+| `renderFooter` | -          | Footer area (sparkline, actions, metadata)        |
+
+## CSS Variables
+
+| Variable                              | Default                                                   | Description                         |
+| ------------------------------------- | --------------------------------------------------------- | ----------------------------------- |
+| `--stuic-stat-bg`                     | `var(--stuic-color-card, var(--stuic-color-background))`  | Background color                    |
+| `--stuic-stat-bg-hover`               | `var(--stuic-color-card-hover, var(--stuic-color-muted))` | Hover background (interactive only) |
+| `--stuic-stat-border-width`           | `1px`                                                     | Border width                        |
+| `--stuic-stat-border`                 | `var(--stuic-color-border)`                               | Border color                        |
+| `--stuic-stat-border-hover`           | `var(--stuic-color-border-hover)`                         | Hover border color                  |
+| `--stuic-stat-radius`                 | `var(--radius-lg)`                                        | Border radius                       |
+| `--stuic-stat-shadow`                 | `var(--shadow-sm)`                                        | Box shadow                          |
+| `--stuic-stat-shadow-hover`           | `var(--shadow-md)`                                        | Hover box shadow                    |
+| `--stuic-stat-transition`             | `150ms`                                                   | Transition duration                 |
+| `--stuic-stat-padding`                | `1rem`                                                    | Padding                             |
+| `--stuic-stat-gap`                    | `0.375rem`                                                | Vertical gap between rows           |
+| `--stuic-stat-meta-gap`               | `0.5rem`                                                  | Gap between delta and hint          |
+| `--stuic-stat-delta-gap`              | `0.25rem`                                                 | Gap between arrow and delta text    |
+| `--stuic-stat-label-font-size`        | `var(--text-sm)`                                          | Label font size                     |
+| `--stuic-stat-label-font-weight`      | `var(--font-weight-medium)`                               | Label font weight                   |
+| `--stuic-stat-label-text`             | `var(--stuic-color-muted-foreground)`                     | Label text color                    |
+| `--stuic-stat-value-font-size`        | `var(--text-2xl)`                                         | Value font size                     |
+| `--stuic-stat-value-font-weight`      | `var(--font-weight-semibold)`                             | Value font weight                   |
+| `--stuic-stat-value-line-height`      | `1.2`                                                     | Value line height                   |
+| `--stuic-stat-value-text`             | `var(--stuic-color-foreground)`                           | Value text color                    |
+| `--stuic-stat-delta-font-size`        | `var(--text-sm)`                                          | Delta font size                     |
+| `--stuic-stat-delta-font-weight`      | `var(--font-weight-medium)`                               | Delta font weight                   |
+| `--stuic-stat-delta-text-success`     | `var(--stuic-color-success)`                              | Delta color (success intent)        |
+| `--stuic-stat-delta-text-destructive` | `var(--stuic-color-destructive)`                          | Delta color (destructive intent)    |
+| `--stuic-stat-delta-text-warning`     | `var(--stuic-color-warning)`                              | Delta color (warning intent)        |
+| `--stuic-stat-delta-text-neutral`     | `var(--stuic-color-muted-foreground)`                     | Delta color (neutral intent)        |
+| `--stuic-stat-hint-font-size`         | `var(--text-sm)`                                          | Hint font size                      |
+| `--stuic-stat-hint-text`              | `var(--stuic-color-muted-foreground)`                     | Hint text color                     |
+| `--stuic-stat-icon-text`              | `var(--stuic-color-muted-foreground)`                     | Corner icon color                   |
+| `--stuic-stat-ring-width`             | `3px`                                                     | Focus ring width                    |
+| `--stuic-stat-ring-color`             | `var(--stuic-color-ring)`                                 | Focus ring color                    |
+| `--stuic-stat-opacity-disabled`       | `0.5`                                                     | Disabled opacity                    |
+
+## Notes
+
+- The stat fills its parent container (`width: 100%; height: 100%`). Control sizing via
+  the parent element (typically a CSS grid of KPI cards).
+- The arrow shows the **direction** (`trend`), the color shows the **sentiment**
+  (`trendIntent`). They are deliberately independent: a downward trend can be colored
+  as success (churn, costs, error rate) via `trendIntent="success"`.
+- Values and deltas are rendered as-is — format numbers/percentages/currencies yourself
+  (e.g. via `Intl.NumberFormat`). Bare `number` values are stringified verbatim.
+- The trend arrow is `aria-hidden`; make sure the delta text itself carries the sign
+  (`"+20.1%"`, `"-3%"`) so the direction survives for screen readers.
+- All content props (`label`, `value`, `delta`, `hint`) accept the THC type (plain
+  string, HTML, component, or snippet).
+- When using `href` or `onclick`, the entire stat becomes interactive with hover
+  effects. Avoid placing interactive elements inside `renderFooter` in this case, as it
+  creates invalid nested interactive HTML.
+- Footer sticks to the bottom of the stat via `margin-top: auto` (relevant in
+  equal-height grids).
+- For a sparkline footer, the first-class pairing is the `TrendChart` wrapper
+  (`import { TrendChart } from "@marianmeres/stuic/trend-chart"`) — a subpath
+  export whose `@marianmeres/trend-chart` peer dependency stays opt-in (nothing
+  is bundled unless you use it). See `src/lib/components/TrendChart/README.md`.