@marianmeres/stuic 3.166.0 → 3.168.0

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`.

package/dist/components/Stat/Stat.svelte

@@ -0,0 +1,226 @@
+<script lang="ts" module>
+	import type { HTMLAttributes, HTMLAnchorAttributes } from "svelte/elements";
+	import type { Snippet } from "svelte";
+	import type { THC } from "../Thc/Thc.svelte";
+
+	export type StatTrend = "up" | "down" | "flat";
+
+	export type StatTrendIntent =
+		"auto" | "success" | "destructive" | "warning" | "neutral";
+
+	export interface Props extends Omit<
+		HTMLAttributes<HTMLDivElement>,
+		"children" | "title"
+	> {
+		/** Small label above the value (metric name, e.g. "Revenue") */
+		label?: THC;
+		/** The primary metric value, preformatted (e.g. "$45,231.89") */
+		value?: THC | number;
+		/** Delta/change indicator, preformatted (e.g. "+20.1%") */
+		delta?: THC | number;
+		/** Trend direction — drives the arrow and (via `trendIntent="auto"`) the delta color */
+		trend?: StatTrend;
+		/**
+		 * Delta color semantics. "auto" (default) maps up→success, down→destructive,
+		 * flat→neutral. Set explicitly for metrics where down is good (churn, costs):
+		 * e.g. `trend="down" trendIntent="success"`.
+		 */
+		trendIntent?: StatTrendIntent;
+		/** Show the trend direction arrow next to the delta */
+		showTrendArrow?: boolean;
+		/** Secondary text next to the delta (e.g. "vs. last month") */
+		hint?: THC;
+		/** When provided, the stat renders as <a> */
+		href?: string;
+		/** Disabled state */
+		disabled?: boolean;
+		/** Override the entire stat body */
+		children?: Snippet;
+		/** Icon area in the top-right corner (next to the label) */
+		renderIcon?: Snippet;
+		/** Footer area (sparkline, actions, metadata, etc.) */
+		renderFooter?: Snippet;
+		/** Skip all default styling */
+		unstyled?: boolean;
+		/** Additional CSS classes */
+		class?: string;
+		/** Class for the label */
+		classLabel?: string;
+		/** Class for the value */
+		classValue?: string;
+		/** Class for the delta */
+		classDelta?: string;
+		/** Class for the hint */
+		classHint?: string;
+		/** Class for the footer area */
+		classFooter?: string;
+		/** Bindable element reference */
+		el?: HTMLElement;
+	}
+</script>
+
+<script lang="ts">
+	import { twMerge } from "../../utils/tw-merge.js";
+	import Thc from "../Thc/Thc.svelte";
+	import { iconTrendingUp, iconTrendingDown, iconMinus } from "../../icons/index.js";
+
+	let {
+		label,
+		value,
+		delta,
+		trend,
+		trendIntent = "auto",
+		showTrendArrow = true,
+		hint,
+		href,
+		disabled = false,
+		children,
+		renderIcon,
+		renderFooter,
+		unstyled = false,
+		class: classProp,
+		classLabel: classLabelProp,
+		classValue: classValueProp,
+		classDelta: classDeltaProp,
+		classHint: classHintProp,
+		classFooter: classFooterProp,
+		el = $bindable(),
+		onclick,
+		...rest
+	}: Props = $props();
+
+	const TREND_ICONS: Record<StatTrend, () => string> = {
+		up: () => iconTrendingUp(),
+		down: () => iconTrendingDown(),
+		flat: () => iconMinus(),
+	};
+
+	let _value = $derived(typeof value === "number" ? String(value) : value);
+	let _delta = $derived(typeof delta === "number" ? String(delta) : delta);
+
+	let _resolvedTrendIntent = $derived.by(() => {
+		if (trendIntent !== "auto") return trendIntent;
+		if (trend === "up") return "success";
+		if (trend === "down") return "destructive";
+		return "neutral";
+	});
+
+	let _showArrow = $derived(showTrendArrow && !!trend);
+	let _hasDelta = $derived((delta !== undefined && delta !== null) || _showArrow);
+	let _hasHeader = $derived(!!(label || renderIcon));
+	let _hasMeta = $derived(_hasDelta || !!hint);
+
+	let _class = $derived(unstyled ? classProp : twMerge("stuic-stat", classProp));
+	let _classLabel = $derived(
+		unstyled ? classLabelProp : twMerge("stuic-stat-label", classLabelProp)
+	);
+	let _classValue = $derived(
+		unstyled ? classValueProp : twMerge("stuic-stat-value", classValueProp)
+	);
+	let _classDelta = $derived(
+		unstyled ? classDeltaProp : twMerge("stuic-stat-delta", classDeltaProp)
+	);
+	let _classHint = $derived(
+		unstyled ? classHintProp : twMerge("stuic-stat-hint", classHintProp)
+	);
+	let _classFooter = $derived(
+		unstyled ? classFooterProp : twMerge("stuic-stat-footer", classFooterProp)
+	);
+</script>
+
+{#snippet statInner()}
+	{#if children}
+		{@render children()}
+	{:else}
+		{#if _hasHeader}
+			<div class={unstyled ? undefined : "stuic-stat-header"}>
+				{#if label}
+					<div class={_classLabel}>
+						<Thc thc={label} />
+					</div>
+				{/if}
+				{#if renderIcon}
+					<div class={unstyled ? undefined : "stuic-stat-icon"}>
+						{@render renderIcon()}
+					</div>
+				{/if}
+			</div>
+		{/if}
+		{#if _value !== undefined && _value !== null}
+			<div class={_classValue}>
+				<Thc thc={_value} />
+			</div>
+		{/if}
+		{#if _hasMeta}
+			<div class={unstyled ? undefined : "stuic-stat-meta"}>
+				{#if _hasDelta}
+					<span class={_classDelta}>
+						{#if _showArrow && trend}
+							<span
+								class={unstyled ? undefined : "stuic-stat-trend-arrow"}
+								aria-hidden="true"
+							>
+								{@html TREND_ICONS[trend]()}
+							</span>
+						{/if}
+						{#if _delta !== undefined && _delta !== null}
+							<Thc thc={_delta} />
+						{/if}
+					</span>
+				{/if}
+				{#if hint}
+					<span class={_classHint}>
+						<Thc thc={hint} />
+					</span>
+				{/if}
+			</div>
+		{/if}
+		{#if renderFooter}
+			<div class={_classFooter}>
+				{@render renderFooter()}
+			</div>
+		{/if}
+	{/if}
+{/snippet}
+
+{#if href}
+	<a
+		{href}
+		bind:this={el}
+		class={_class}
+		data-trend={!unstyled && trend ? trend : undefined}
+		data-trend-intent={!unstyled && _hasDelta ? _resolvedTrendIntent : undefined}
+		data-interactive={!unstyled ? "" : undefined}
+		data-disabled={!unstyled && disabled ? "" : undefined}
+		aria-disabled={disabled ? "true" : undefined}
+		{...rest as HTMLAnchorAttributes}
+	>
+		{@render statInner()}
+	</a>
+{:else if onclick}
+	<button
+		type="button"
+		bind:this={el}
+		class={_class}
+		data-trend={!unstyled && trend ? trend : undefined}
+		data-trend-intent={!unstyled && _hasDelta ? _resolvedTrendIntent : undefined}
+		data-interactive={!unstyled ? "" : undefined}
+		data-disabled={!unstyled && disabled ? "" : undefined}
+		{disabled}
+		{onclick}
+		{...rest as any}
+	>
+		{@render statInner()}
+	</button>
+{:else}
+	<div
+		bind:this={el}
+		class={_class}
+		data-trend={!unstyled && trend ? trend : undefined}
+		data-trend-intent={!unstyled && _hasDelta ? _resolvedTrendIntent : undefined}
+		data-disabled={!unstyled && disabled ? "" : undefined}
+		{...rest}
+	>
+		{@render statInner()}
+	</div>
+{/if}

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

@@ -0,0 +1,54 @@
+import type { HTMLAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
+import type { THC } from "../Thc/Thc.svelte";
+export type StatTrend = "up" | "down" | "flat";
+export type StatTrendIntent = "auto" | "success" | "destructive" | "warning" | "neutral";
+export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "title"> {
+    /** Small label above the value (metric name, e.g. "Revenue") */
+    label?: THC;
+    /** The primary metric value, preformatted (e.g. "$45,231.89") */
+    value?: THC | number;
+    /** Delta/change indicator, preformatted (e.g. "+20.1%") */
+    delta?: THC | number;
+    /** Trend direction — drives the arrow and (via `trendIntent="auto"`) the delta color */
+    trend?: StatTrend;
+    /**
+     * Delta color semantics. "auto" (default) maps up→success, down→destructive,
+     * flat→neutral. Set explicitly for metrics where down is good (churn, costs):
+     * e.g. `trend="down" trendIntent="success"`.
+     */
+    trendIntent?: StatTrendIntent;
+    /** Show the trend direction arrow next to the delta */
+    showTrendArrow?: boolean;
+    /** Secondary text next to the delta (e.g. "vs. last month") */
+    hint?: THC;
+    /** When provided, the stat renders as <a> */
+    href?: string;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Override the entire stat body */
+    children?: Snippet;
+    /** Icon area in the top-right corner (next to the label) */
+    renderIcon?: Snippet;
+    /** Footer area (sparkline, actions, metadata, etc.) */
+    renderFooter?: Snippet;
+    /** Skip all default styling */
+    unstyled?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+    /** Class for the label */
+    classLabel?: string;
+    /** Class for the value */
+    classValue?: string;
+    /** Class for the delta */
+    classDelta?: string;
+    /** Class for the hint */
+    classHint?: string;
+    /** Class for the footer area */
+    classFooter?: string;
+    /** Bindable element reference */
+    el?: HTMLElement;
+}
+declare const Stat: import("svelte").Component<Props, {}, "el">;
+type Stat = ReturnType<typeof Stat>;
+export default Stat;