@marianmeres/stuic 3.167.0 → 3.169.0

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

@@ -0,0 +1,86 @@
+import type { HTMLAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
+import type { THC } from "../Thc/Thc.svelte";
+import type { TranslateFn } from "../../types.js";
+export type StepperOrientation = "horizontal" | "vertical";
+export type StepperLabelPosition = "end" | "below";
+export type StepperStepState = "completed" | "current" | "upcoming";
+export type StepperClickable = "none" | "completed" | "all";
+export interface StepperStep {
+    /** Step label */
+    label: THC;
+    /** Optional secondary line under the label */
+    description?: THC;
+    /**
+     * Raw svg/html string rendered inside the indicator instead of the step number
+     * (e.g. an `@marianmeres/icons-fns` render result). Completed/error markers
+     * still take precedence.
+     */
+    icon?: string;
+    /** Marks the step as failed — destructive coloring + "×" indicator */
+    error?: boolean;
+    /** Never clickable, regardless of the `clickable` policy */
+    disabled?: boolean;
+}
+export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** The steps to render. Plain strings are shorthand for `{ label }`. */
+    steps: (StepperStep | string)[];
+    /**
+     * Zero-based index of the current step (default 0) — aligns with
+     * `@marianmeres/wizard`'s `step.index`. Steps before it render as completed,
+     * steps after it as upcoming. Pass `steps.length` to mark every step
+     * completed (wizard done). Out-of-range values are clamped.
+     */
+    current?: number;
+    /**
+     * Navigation callback. When provided (and `clickable` is not "none"), steps
+     * render as buttons and eligible ones fire this on click. The current step
+     * never fires.
+     */
+    onSelect?: (index: number, step: StepperStep) => void;
+    /**
+     * Which steps may be clicked when `onSelect` is present. `"completed"`
+     * (default): only completed steps — the "go back and revisit" wizard rule.
+     * `"all"`: any non-disabled step. `"none"`: display-only.
+     */
+    clickable?: StepperClickable;
+    /** Layout direction (default "horizontal") */
+    orientation?: StepperOrientation;
+    /**
+     * Horizontal orientation only: labels to the right of the indicator
+     * (`"end"`, default) or centered below it (`"below"` — the classic
+     * checkout header).
+     */
+    labelPosition?: StepperLabelPosition;
+    /** Disable all interaction (e.g. while a step is submitting) */
+    disabled?: boolean;
+    /** i18n translate function (see `createStepperT`) */
+    t?: TranslateFn;
+    /** Override the indicator bubble content */
+    renderIndicator?: Snippet<[
+        {
+            index: number;
+            step: StepperStep;
+            state: StepperStepState;
+        }
+    ]>;
+    /** Skip all default styling */
+    unstyled?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+    /** Class for every step item (`li`) */
+    classStep?: string;
+    /** Class for the indicator bubble */
+    classIndicator?: string;
+    /** Class for the label */
+    classLabel?: string;
+    /** Class for the description */
+    classDescription?: string;
+    /** Class for the connector line between steps */
+    classConnector?: string;
+    /** Bindable element reference */
+    el?: HTMLElement;
+}
+declare const Stepper: import("svelte").Component<Props, {}, "el">;
+type Stepper = ReturnType<typeof Stepper>;
+export default Stepper;

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

@@ -0,0 +1,17 @@
+import type { StepperMessages } from "./i18n.js";
+/**
+ * Slovak message catalog for `Stepper`. 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 { Stepper, createStepperT, STEPPER_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createStepperT(STEPPER_MESSAGES_SK);
+ * </script>
+ *
+ * <Stepper {steps} {current} {t} />
+ * ```
+ */
+export declare const STEPPER_MESSAGES_SK: StepperMessages;

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

@@ -0,0 +1,21 @@
+/**
+ * Slovak message catalog for `Stepper`. 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 { Stepper, createStepperT, STEPPER_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createStepperT(STEPPER_MESSAGES_SK);
+ * </script>
+ *
+ * <Stepper {steps} {current} {t} />
+ * ```
+ */
+export const STEPPER_MESSAGES_SK = {
+    stepper: "Priebeh",
+    step_x_of_y: "Krok {step} z {stepCount}",
+    completed: "Dokončený",
+    failed: "Zlyhal",
+};

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

@@ -0,0 +1,35 @@
+import type { TranslateFn } from "../../types.js";
+/**
+ * The built-in (English) message catalog of `Stepper`. Also the fallback of every
+ * other bundled locale, so a locale missing a key still renders text.
+ *
+ * Placeholders are single-brace (`{step}`, `{stepCount}`).
+ */
+export declare const STEPPER_MESSAGES_EN: {
+    stepper: string;
+    step_x_of_y: string;
+    completed: string;
+    failed: string;
+};
+/** Every message key `Stepper` may look up. */
+export type StepperMessageKey = keyof typeof STEPPER_MESSAGES_EN;
+/** A (possibly partial) catalog for one locale. */
+export type StepperMessages = Record<StepperMessageKey, string>;
+/**
+ * Builds the `t` prop of `Stepper` 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 { Stepper, createStepperT, STEPPER_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createStepperT(STEPPER_MESSAGES_SK);
+ * </script>
+ *
+ * <Stepper {steps} {current} {t} />
+ * ```
+ */
+export declare function createStepperT(messages: Partial<StepperMessages> | Record<string, string>, fallbackMessages?: Partial<StepperMessages> | Record<string, string>): TranslateFn;
+/** The component's built-in English `t`. */
+export declare const t_default: TranslateFn;

package/dist/components/Stepper/i18n.js

@@ -0,0 +1,43 @@
+import { isPlainObject } from "../../utils/is-plain-object.js";
+import { replaceMap } from "../../utils/replace-map.js";
+/**
+ * The built-in (English) message catalog of `Stepper`. Also the fallback of every
+ * other bundled locale, so a locale missing a key still renders text.
+ *
+ * Placeholders are single-brace (`{step}`, `{stepCount}`).
+ */
+export const STEPPER_MESSAGES_EN = {
+    stepper: "Progress",
+    step_x_of_y: "Step {step} of {stepCount}",
+    completed: "Completed",
+    failed: "Failed",
+};
+/**
+ * Builds the `t` prop of `Stepper` 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 { Stepper, createStepperT, STEPPER_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createStepperT(STEPPER_MESSAGES_SK);
+ * </script>
+ *
+ * <Stepper {steps} {current} {t} />
+ * ```
+ */
+export function createStepperT(messages, fallbackMessages = STEPPER_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 = createStepperT(STEPPER_MESSAGES_EN);

package/dist/components/Stepper/index.css

@@ -0,0 +1,302 @@
+/* ============================================================================
+   STEPPER COMPONENT TOKENS
+   Override globally: :root { --stuic-stepper-indicator-size: 2.5rem; }
+   Override locally:  <Stepper style="--stuic-stepper-connector-thickness: 4px;">
+   ============================================================================ */
+
+/* prettier-ignore */
+:root {
+	/* Layout */
+	--stuic-stepper-gap: 0.75rem;                  /* indicator↔label + step↔connector */
+	--stuic-stepper-gap-vertical: 1.75rem;         /* vertical: distance between steps */
+	--stuic-stepper-connector-min-length: 1.5rem;  /* horizontal: shortest connector */
+
+	/* Indicator bubble */
+	--stuic-stepper-indicator-size: 2rem;
+	--stuic-stepper-indicator-border-width: 2px;
+	--stuic-stepper-indicator-font-size: var(--text-sm);
+	--stuic-stepper-indicator-font-weight: var(--font-weight-medium);
+	--stuic-stepper-indicator-bg: transparent;
+	--stuic-stepper-indicator-text: var(--stuic-color-muted-foreground);
+	--stuic-stepper-indicator-border: var(--stuic-color-border);
+	--stuic-stepper-indicator-bg-current: transparent;
+	--stuic-stepper-indicator-text-current: var(--stuic-color-primary);
+	--stuic-stepper-indicator-border-current: var(--stuic-color-primary);
+	--stuic-stepper-indicator-bg-completed: var(--stuic-color-primary);
+	--stuic-stepper-indicator-text-completed: var(--stuic-color-primary-foreground);
+	--stuic-stepper-indicator-border-completed: var(--stuic-color-primary);
+	--stuic-stepper-indicator-bg-error: var(--stuic-color-destructive);
+	--stuic-stepper-indicator-text-error: var(--stuic-color-destructive-foreground);
+	--stuic-stepper-indicator-border-error: var(--stuic-color-destructive);
+
+	/* Label */
+	--stuic-stepper-label-font-size: var(--text-base);
+	--stuic-stepper-label-font-weight: var(--font-weight-medium);
+	--stuic-stepper-label-text: var(--stuic-color-muted-foreground);
+	--stuic-stepper-label-text-current: var(--stuic-color-foreground);
+	--stuic-stepper-label-text-completed: var(--stuic-color-foreground);
+	--stuic-stepper-label-text-error: var(--stuic-color-destructive);
+
+	/* Description */
+	--stuic-stepper-description-font-size: var(--text-sm);
+	--stuic-stepper-description-text: var(--stuic-color-muted-foreground);
+
+	/* Connector line */
+	--stuic-stepper-connector-thickness: 2px;
+	--stuic-stepper-connector-bg: var(--stuic-color-border);
+	--stuic-stepper-connector-bg-completed: var(--stuic-color-primary);
+
+	/* Focus ring */
+	--stuic-stepper-ring-width: 3px;
+	--stuic-stepper-ring-color: var(--stuic-color-ring);
+
+	/* Disabled */
+	--stuic-stepper-opacity-disabled: 0.5;
+}
+
+@layer components {
+	/* ============================================================================
+	   BASE
+	   ============================================================================ */
+
+	.stuic-stepper[data-disabled] {
+		opacity: var(--stuic-stepper-opacity-disabled);
+	}
+
+	.stuic-stepper-list {
+		display: flex;
+		list-style: none;
+		margin: 0;
+		padding: 0;
+	}
+
+	.stuic-stepper-item[data-disabled] {
+		opacity: var(--stuic-stepper-opacity-disabled);
+	}
+
+	/* ============================================================================
+	   TRIGGER (the step content — <button> when interactive, <div> otherwise)
+	   ============================================================================ */
+
+	.stuic-stepper-trigger {
+		display: flex;
+		align-items: center;
+		gap: var(--stuic-stepper-gap);
+		text-align: start;
+		min-width: 0;
+	}
+
+	button.stuic-stepper-trigger {
+		font: inherit;
+		color: inherit;
+		background: none;
+		border: 0;
+		padding: 0;
+		cursor: pointer;
+		-webkit-tap-highlight-color: transparent;
+	}
+
+	button.stuic-stepper-trigger:disabled {
+		cursor: default;
+	}
+
+	button.stuic-stepper-trigger:focus-visible {
+		outline: var(--stuic-stepper-ring-width) solid var(--stuic-stepper-ring-color);
+		outline-offset: 2px;
+		border-radius: var(--stuic-stepper-radius, var(--stuic-radius));
+	}
+
+	/* clickable affordance: label picks up the emphasized color */
+	button.stuic-stepper-trigger:not(:disabled):hover .stuic-stepper-label {
+		color: var(--stuic-stepper-label-text-current);
+	}
+
+	/* ============================================================================
+	   INDICATOR
+	   ============================================================================ */
+
+	.stuic-stepper-indicator {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		flex-shrink: 0;
+		width: var(--stuic-stepper-indicator-size);
+		height: var(--stuic-stepper-indicator-size);
+		border-radius: var(--stuic-stepper-indicator-radius, calc(infinity * 1px));
+		border: var(--stuic-stepper-indicator-border-width) solid
+			var(--stuic-stepper-indicator-border);
+		background: var(--stuic-stepper-indicator-bg);
+		color: var(--stuic-stepper-indicator-text);
+		font-size: var(--stuic-stepper-indicator-font-size);
+		font-weight: var(--stuic-stepper-indicator-font-weight);
+		transition:
+			background var(--stuic-stepper-transition, var(--stuic-transition)),
+			border-color var(--stuic-stepper-transition, var(--stuic-transition)),
+			color var(--stuic-stepper-transition, var(--stuic-transition));
+	}
+
+	.stuic-stepper-indicator svg {
+		display: block;
+		width: 1.25em;
+		height: 1.25em;
+	}
+
+	.stuic-stepper-item[data-state="current"] .stuic-stepper-indicator {
+		background: var(--stuic-stepper-indicator-bg-current);
+		border-color: var(--stuic-stepper-indicator-border-current);
+		color: var(--stuic-stepper-indicator-text-current);
+	}
+
+	.stuic-stepper-item[data-state="completed"] .stuic-stepper-indicator {
+		background: var(--stuic-stepper-indicator-bg-completed);
+		border-color: var(--stuic-stepper-indicator-border-completed);
+		color: var(--stuic-stepper-indicator-text-completed);
+	}
+
+	/* error wins over any state */
+	.stuic-stepper-item[data-error] .stuic-stepper-indicator {
+		background: var(--stuic-stepper-indicator-bg-error);
+		border-color: var(--stuic-stepper-indicator-border-error);
+		color: var(--stuic-stepper-indicator-text-error);
+	}
+
+	/* ============================================================================
+	   TEXT (label + description)
+	   ============================================================================ */
+
+	.stuic-stepper-text {
+		display: flex;
+		flex-direction: column;
+		gap: 0.125rem;
+		min-width: 0;
+	}
+
+	.stuic-stepper-label {
+		font-size: var(--stuic-stepper-label-font-size);
+		font-weight: var(--stuic-stepper-label-font-weight);
+		color: var(--stuic-stepper-label-text);
+		transition: color var(--stuic-stepper-transition, var(--stuic-transition));
+	}
+
+	.stuic-stepper-item[data-state="current"] .stuic-stepper-label {
+		color: var(--stuic-stepper-label-text-current);
+	}
+
+	.stuic-stepper-item[data-state="completed"] .stuic-stepper-label {
+		color: var(--stuic-stepper-label-text-completed);
+	}
+
+	.stuic-stepper-item[data-error] .stuic-stepper-label {
+		color: var(--stuic-stepper-label-text-error);
+	}
+
+	.stuic-stepper-description {
+		font-size: var(--stuic-stepper-description-font-size);
+		color: var(--stuic-stepper-description-text);
+	}
+
+	/* ============================================================================
+	   CONNECTOR
+	   ============================================================================ */
+
+	.stuic-stepper-connector {
+		background: var(--stuic-stepper-connector-bg);
+		transition: background var(--stuic-stepper-transition, var(--stuic-transition));
+	}
+
+	.stuic-stepper-connector[data-state="completed"] {
+		background: var(--stuic-stepper-connector-bg-completed);
+	}
+
+	/* ============================================================================
+	   HORIZONTAL (labels at the end — default)
+	   ============================================================================ */
+
+	.stuic-stepper[data-orientation="horizontal"] .stuic-stepper-list {
+		flex-direction: row;
+		align-items: center;
+		gap: var(--stuic-stepper-gap);
+	}
+
+	.stuic-stepper[data-orientation="horizontal"] .stuic-stepper-item {
+		display: flex;
+		align-items: center;
+		gap: var(--stuic-stepper-gap);
+		flex: 1;
+		min-width: 0;
+	}
+
+	/* the last step carries no connector — don't stretch it */
+	.stuic-stepper[data-orientation="horizontal"] .stuic-stepper-item:last-child {
+		flex: none;
+	}
+
+	.stuic-stepper[data-orientation="horizontal"] .stuic-stepper-connector {
+		flex: 1;
+		min-width: var(--stuic-stepper-connector-min-length);
+		height: var(--stuic-stepper-connector-thickness);
+	}
+
+	/* ============================================================================
+	   HORIZONTAL, LABELS BELOW (classic checkout header)
+	   ============================================================================ */
+
+	.stuic-stepper[data-label-position="below"] .stuic-stepper-item {
+		align-items: flex-start;
+	}
+
+	.stuic-stepper[data-label-position="below"] .stuic-stepper-trigger {
+		flex-direction: column;
+		align-items: center;
+		text-align: center;
+	}
+
+	.stuic-stepper[data-label-position="below"] .stuic-stepper-text {
+		align-items: center;
+	}
+
+	/* keep the connector on the indicator's horizontal axis */
+	.stuic-stepper[data-label-position="below"] .stuic-stepper-connector {
+		margin-top: calc(
+			(var(--stuic-stepper-indicator-size) - var(--stuic-stepper-connector-thickness)) / 2
+		);
+	}
+
+	/* ============================================================================
+	   VERTICAL
+	   ============================================================================ */
+
+	.stuic-stepper[data-orientation="vertical"] .stuic-stepper-list {
+		flex-direction: column;
+	}
+
+	.stuic-stepper[data-orientation="vertical"] .stuic-stepper-item {
+		position: relative;
+		padding-bottom: var(--stuic-stepper-gap-vertical);
+	}
+
+	.stuic-stepper[data-orientation="vertical"] .stuic-stepper-item:last-child {
+		padding-bottom: 0;
+	}
+
+	/* top-align so a multi-line description grows downward, not around the bubble */
+	.stuic-stepper[data-orientation="vertical"] .stuic-stepper-trigger {
+		align-items: flex-start;
+	}
+
+	/* ...while a single-line label still centers against the bubble */
+	.stuic-stepper[data-orientation="vertical"] .stuic-stepper-text {
+		min-height: var(--stuic-stepper-indicator-size);
+		justify-content: center;
+	}
+
+	.stuic-stepper[data-orientation="vertical"] .stuic-stepper-connector {
+		position: absolute;
+		inset-inline-start: calc(
+			(var(--stuic-stepper-indicator-size) - var(--stuic-stepper-connector-thickness)) / 2
+		);
+		top: calc(var(--stuic-stepper-indicator-size) + 0.25rem);
+		bottom: 0.25rem;
+		width: var(--stuic-stepper-connector-thickness);
+	}
+}

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

@@ -0,0 +1,3 @@
+export { default as Stepper, type Props as StepperProps, type StepperStep, type StepperStepState, type StepperOrientation, type StepperLabelPosition, type StepperClickable, } from "./Stepper.svelte";
+export { createStepperT, STEPPER_MESSAGES_EN, type StepperMessageKey, type StepperMessages, } from "./i18n.js";
+export { STEPPER_MESSAGES_SK } from "./i18n-sk.js";

package/dist/components/Stepper/index.js

@@ -0,0 +1,3 @@
+export { default as Stepper, } from "./Stepper.svelte";
+export { createStepperT, STEPPER_MESSAGES_EN, } from "./i18n.js";
+export { STEPPER_MESSAGES_SK } from "./i18n-sk.js";

package/dist/components/TrendChart/README.md

@@ -0,0 +1,123 @@
+# TrendChart
+
+A thin Svelte wrapper around [`@marianmeres/trend-chart`](https://github.com/marianmeres/trend-chart)
+(framework-agnostic, zero-dependency single-series SVG trend chart): reactive `data`
+and `options` props, lifecycle management (create/update/destroy), a `sparkline`
+preset, and automatic STUIC theming (dark mode included) by mapping the chart's
+`--trend-chart-*` CSS hooks to STUIC tokens.
+
+## Installation
+
+This component ships as an **optional subpath export** — the
+`@marianmeres/trend-chart` peer dependency is NOT bundled with stuic and is only
+required if you actually use this component:
+
+```bash
+npm install @marianmeres/trend-chart
+```
+
+```svelte
+<script>
+	import { TrendChart } from "@marianmeres/stuic/trend-chart";
+</script>
+```
+
+It is deliberately not exported from the main `@marianmeres/stuic` barrel, so
+consumers who don't use it never pull the dependency into their module graph.
+
+## Usage
+
+```svelte
+<script>
+	import { TrendChart } from "@marianmeres/stuic/trend-chart";
+
+	let data = $state([3, 5, 4, 8, 6, 9, 7]);
+</script>
+
+<!-- Full chart (axes, gridlines, pan/zoom) — themed via stuic tokens -->
+<TrendChart {data} />
+
+<!-- Sparkline (no axes/grid/interaction, compact height) -->
+<TrendChart {data} sparkline />
+
+<!-- Any @marianmeres/trend-chart option passes through -->
+<TrendChart
+	{data}
+	options={{
+		smooth: true,
+		endDot: true,
+		formatX: (x) => new Date(x).toLocaleDateString(),
+		onPointClick: (e) => console.log(e.point),
+	}}
+/>
+
+<!-- Imperative API via the bindable chart instance -->
+<TrendChart {data} bind:chart />
+<button onclick={() => chart?.resetDomain()}>Reset zoom</button>
+```
+
+Updating `data` (reassignment or deep `$state` mutation) patches the chart in
+place — pan/zoom state is preserved. Changing `options` merges them into the
+running instance.
+
+### With `Stat` (KPI card)
+
+The first-class pairing — a sparkline in a `Stat` footer:
+
+```svelte
+<script>
+	import { Stat } from "@marianmeres/stuic";
+	import { TrendChart } from "@marianmeres/stuic/trend-chart";
+</script>
+
+<Stat label="Requests" value="1.2M" delta="+8.4%" trend="up" hint="last 7 days">
+	{#snippet renderFooter()}
+		<TrendChart data={[42, 51, 48, 63, 58, 71, 84]} sparkline />
+	{/snippet}
+</Stat>
+```
+
+## Props
+
+| Prop        | Type                | Default | Description                                                                                                                                                      |
+| ----------- | ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`      | `TrendData`         | —       | The series: `DataPoint[]` or plain `number[]` shorthand (index becomes x). Reactive.                                                                             |
+| `options`   | `TrendChartOptions` | —       | [`@marianmeres/trend-chart` options](https://github.com/marianmeres/trend-chart/blob/master/API.md), passed through. Reactive. Merged OVER the sparkline preset. |
+| `sparkline` | `boolean`           | `false` | Preset: no axes/grid/pan/zoom/points + compact default height                                                                                                    |
+| `chart`     | `TrendChart`        | —       | Bindable underlying instance (`setDomainX`, `resetDomain`, ...). `undefined` during SSR/before mount.                                                            |
+| `unstyled`  | `boolean`           | `false` | Skip all default styling — including the default height; size the container yourself                                                                             |
+| `class`     | `string`            | -       | Additional CSS classes for the container                                                                                                                         |
+| `el`        | `HTMLElement`       | -       | Bindable element reference (the chart's container)                                                                                                               |
+
+## CSS Variables
+
+| Variable                               | Default                               | Description                       |
+| -------------------------------------- | ------------------------------------- | --------------------------------- |
+| `--stuic-trend-chart-height`           | `8rem`                                | Container height                  |
+| `--stuic-trend-chart-height-sparkline` | `2.5rem`                              | Container height with `sparkline` |
+| `--stuic-trend-chart-line`             | `var(--stuic-color-primary)`          | Line stroke                       |
+| `--stuic-trend-chart-fill`             | `var(--stuic-color-primary)`          | Area fill base color              |
+| `--stuic-trend-chart-grid`             | `var(--stuic-color-border)`           | Gridline stroke                   |
+| `--stuic-trend-chart-label`            | `var(--stuic-color-muted-foreground)` | Axis label color                  |
+| `--stuic-trend-chart-font`             | `var(--font-sans)`                    | Label font family                 |
+| `--stuic-trend-chart-end-dot-ring`     | `var(--stuic-color-background)`       | End-dot/hover-dot ring color      |
+| `--stuic-trend-chart-annotation`       | `var(--stuic-color-warning)`          | Annotation rule + label color     |
+| `--stuic-trend-chart-annotation-halo`  | `var(--stuic-color-background)`       | Halo behind annotation labels     |
+
+These map onto the chart's own `--trend-chart-*` hooks (active because the DOM
+renderer's `cssVars` option defaults to `true`). Any `lineColor`/`fill`/... option
+you pass still acts as the fallback inside the `var()` wrapper.
+
+## Notes
+
+- **Sizing**: the chart measures its container (via `ResizeObserver`), so the
+  container needs a real size. The default styles provide the height
+  (`--stuic-trend-chart-height`); with `unstyled` you must size it yourself, or
+  pass explicit `width`/`height` in `options`.
+- **SSR**: the chart is created in an effect, so the server renders an empty
+  container. For static server-rendered charts use the library's
+  `renderToString` directly.
+- Single-series by design (the underlying library's scope): one line/area — no
+  bars, pies, or multi-series.
+- The chart instance is created once per container; `data`/`options` changes
+  patch it in place, so pan/zoom state survives updates.