@marianmeres/stuic 3.169.0 → 3.170.0

package/dist/components/Timeline/index.css

@@ -0,0 +1,311 @@
+/* ============================================================================
+   TIMELINE COMPONENT TOKENS
+   Override globally: :root { --stuic-timeline-marker-size: 1rem; }
+   Override locally:  <Timeline style="--stuic-timeline-gap-vertical: 1rem;">
+   ============================================================================ */
+
+/* prettier-ignore */
+:root {
+	/* Layout */
+	--stuic-timeline-gap: 1rem;                /* column gap: opposite ↔ rail ↔ content */
+	--stuic-timeline-gap-vertical: 1.5rem;     /* distance between items */
+	--stuic-timeline-line-height: 1.5rem;      /* first-line box the marker centers on */
+
+	/* Connector (the vertical rail line) */
+	--stuic-timeline-connector-thickness: 2px;
+	--stuic-timeline-connector-bg: var(--stuic-color-border);
+
+	/* Marker: dot (no icon) */
+	--stuic-timeline-marker-size: 0.75rem;
+	--stuic-timeline-marker-bg: var(--stuic-color-muted-foreground);
+
+	/* Marker: icon bubble (item.icon) and custom (renderMarker) */
+	--stuic-timeline-marker-size-icon: 2rem;
+	--stuic-timeline-marker-bg-icon: var(--stuic-color-muted);
+	--stuic-timeline-marker-text-icon: var(--stuic-color-muted-foreground);
+	--stuic-timeline-marker-icon-size: 1rem;   /* svg inside the bubble */
+
+	/* Marker ring: separates the marker from the line running behind it */
+	--stuic-timeline-marker-ring-width: 2px;
+	--stuic-timeline-marker-ring-color: var(--stuic-color-background);
+
+	/* Time */
+	--stuic-timeline-time-font-size: var(--text-sm);
+	--stuic-timeline-time-text: var(--stuic-color-muted-foreground);
+
+	/* Title */
+	--stuic-timeline-title-font-size: var(--text-base);
+	--stuic-timeline-title-font-weight: var(--font-weight-medium);
+	--stuic-timeline-title-text: var(--stuic-color-foreground);
+
+	/* Description */
+	--stuic-timeline-description-font-size: var(--text-sm);
+	--stuic-timeline-description-text: var(--stuic-color-muted-foreground);
+	--stuic-timeline-description-margin-top: 0.125rem;
+
+	/* Footer */
+	--stuic-timeline-footer-gap: 0.5rem;
+	--stuic-timeline-footer-margin-top: 0.5rem;
+}
+
+@layer components {
+	/* ============================================================================
+	   BASE — the list is a grid; every item is a subgrid row, so the rail (and
+	   the opposite time column) line up across items regardless of content.
+	   ============================================================================ */
+
+	.stuic-timeline {
+		display: grid;
+		column-gap: var(--stuic-timeline-gap);
+		list-style: none;
+		margin: 0;
+		padding: 0;
+	}
+
+	.stuic-timeline[data-align="start"][data-time-position="inline"] {
+		grid-template-columns: auto minmax(0, 1fr);
+	}
+
+	.stuic-timeline[data-align="start"][data-time-position="opposite"] {
+		grid-template-columns: auto auto minmax(0, 1fr);
+	}
+
+	.stuic-timeline[data-align="alternate"] {
+		grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr);
+	}
+
+	.stuic-timeline-item {
+		display: grid;
+		grid-column: 1 / -1;
+		grid-template-columns: subgrid;
+		padding-bottom: var(--stuic-timeline-gap-vertical);
+	}
+
+	.stuic-timeline-item:last-child {
+		padding-bottom: 0;
+	}
+
+	/* every cell sits on the item's single row; columns are assigned below */
+	.stuic-timeline-opposite,
+	.stuic-timeline-rail,
+	.stuic-timeline-content {
+		grid-row: 1;
+		min-width: 0;
+	}
+
+	/* ============================================================================
+	   COLUMN PLACEMENT
+	   ============================================================================ */
+
+	/* start + inline: rail | content */
+	.stuic-timeline[data-align="start"][data-time-position="inline"] .stuic-timeline-rail {
+		grid-column: 1;
+	}
+	.stuic-timeline[data-align="start"][data-time-position="inline"]
+		.stuic-timeline-content {
+		grid-column: 2;
+	}
+
+	/* start + opposite: time | rail | content */
+	.stuic-timeline[data-align="start"][data-time-position="opposite"]
+		.stuic-timeline-opposite {
+		grid-column: 1;
+		text-align: end;
+	}
+	.stuic-timeline[data-align="start"][data-time-position="opposite"]
+		.stuic-timeline-rail {
+		grid-column: 2;
+	}
+	.stuic-timeline[data-align="start"][data-time-position="opposite"]
+		.stuic-timeline-content {
+		grid-column: 3;
+	}
+
+	/* alternate: centered rail; odd items → content end side, even → start side */
+	.stuic-timeline[data-align="alternate"] .stuic-timeline-rail {
+		grid-column: 2;
+	}
+	.stuic-timeline[data-align="alternate"]
+		.stuic-timeline-item:nth-child(odd)
+		.stuic-timeline-content {
+		grid-column: 3;
+	}
+	.stuic-timeline[data-align="alternate"]
+		.stuic-timeline-item:nth-child(odd)
+		.stuic-timeline-opposite {
+		grid-column: 1;
+		text-align: end;
+	}
+	.stuic-timeline[data-align="alternate"]
+		.stuic-timeline-item:nth-child(even)
+		.stuic-timeline-content {
+		grid-column: 1;
+		text-align: end;
+	}
+	.stuic-timeline[data-align="alternate"]
+		.stuic-timeline-item:nth-child(even)
+		.stuic-timeline-opposite {
+		grid-column: 3;
+	}
+	.stuic-timeline[data-align="alternate"]
+		.stuic-timeline-item:nth-child(even)
+		.stuic-timeline-footer {
+		justify-content: flex-end;
+	}
+
+	/* ============================================================================
+	   RAIL + CONNECTOR
+	   The line runs behind the marker in two halves (top → marker center, marker
+	   center → bottom) so no item needs to know its neighbour's marker size. The
+	   marker's center is always at half the first-line height.
+	   ============================================================================ */
+
+	.stuic-timeline-rail {
+		position: relative;
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+	}
+
+	.stuic-timeline-rail::before,
+	.stuic-timeline-rail::after {
+		content: "";
+		position: absolute;
+		left: 50%;
+		width: var(--stuic-timeline-connector-thickness);
+		transform: translateX(-50%);
+		background: var(--stuic-timeline-connector-bg);
+	}
+
+	.stuic-timeline-rail::before {
+		top: 0;
+		height: calc(var(--stuic-timeline-line-height) / 2);
+	}
+
+	/* the item's bottom padding (gap-vertical) lies outside the grid row, so reach
+	   through it — the next item's ::before picks the line up at its top edge */
+	.stuic-timeline-rail::after {
+		top: calc(var(--stuic-timeline-line-height) / 2);
+		bottom: calc(-1 * var(--stuic-timeline-gap-vertical));
+	}
+
+	.stuic-timeline-item:first-child .stuic-timeline-rail::before,
+	.stuic-timeline-item:last-child .stuic-timeline-rail::after {
+		display: none;
+	}
+
+	/* ============================================================================
+	   MARKER
+	   ============================================================================ */
+
+	.stuic-timeline-marker {
+		position: relative;
+		z-index: 1;
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		flex-shrink: 0;
+		box-sizing: border-box;
+		width: var(--_marker-size);
+		height: var(--_marker-size);
+		/* center on the first line of the content (may go negative for big markers) */
+		margin-top: calc((var(--stuic-timeline-line-height) - var(--_marker-size)) / 2);
+		border-radius: var(--stuic-timeline-marker-radius, calc(infinity * 1px));
+		box-shadow: 0 0 0 var(--stuic-timeline-marker-ring-width)
+			var(--stuic-timeline-marker-ring-color);
+	}
+
+	.stuic-timeline-marker[data-marker="dot"] {
+		--_marker-size: var(--stuic-timeline-marker-size);
+		background: var(--stuic-timeline-marker-bg);
+	}
+
+	.stuic-timeline-marker[data-marker="icon"] {
+		--_marker-size: var(--stuic-timeline-marker-size-icon);
+		background: var(--stuic-timeline-marker-bg-icon);
+		color: var(--stuic-timeline-marker-text-icon);
+	}
+
+	.stuic-timeline-marker[data-marker="icon"] svg {
+		display: block;
+		width: var(--stuic-timeline-marker-icon-size);
+		height: var(--stuic-timeline-marker-icon-size);
+	}
+
+	/* custom (renderMarker): only the box — the snippet brings its own look */
+	.stuic-timeline-marker[data-marker="custom"] {
+		--_marker-size: var(--stuic-timeline-marker-size-icon);
+	}
+
+	/* ============================================================================
+	   INTENT — dot fills with the color, the bubble takes a soft tint
+	   ============================================================================ */
+
+	.stuic-timeline-item[data-intent="primary"] {
+		--_intent: var(--stuic-color-primary);
+	}
+	.stuic-timeline-item[data-intent="accent"] {
+		--_intent: var(--stuic-color-accent);
+	}
+	.stuic-timeline-item[data-intent="destructive"] {
+		--_intent: var(--stuic-color-destructive);
+	}
+	.stuic-timeline-item[data-intent="warning"] {
+		--_intent: var(--stuic-color-warning);
+	}
+	.stuic-timeline-item[data-intent="success"] {
+		--_intent: var(--stuic-color-success);
+	}
+
+	.stuic-timeline-item[data-intent] .stuic-timeline-marker[data-marker="dot"] {
+		background: var(--_intent);
+	}
+
+	.stuic-timeline-item[data-intent] .stuic-timeline-marker[data-marker="icon"] {
+		background: color-mix(in srgb, var(--_intent) 15%, var(--stuic-color-background));
+		color: var(--_intent);
+	}
+
+	/* ============================================================================
+	   CONTENT: time, title, description, footer
+	   ============================================================================ */
+
+	.stuic-timeline-time {
+		display: block;
+		font-size: var(--stuic-timeline-time-font-size);
+		line-height: var(--stuic-timeline-line-height);
+		color: var(--stuic-timeline-time-text);
+	}
+
+	.stuic-timeline-title {
+		font-size: var(--stuic-timeline-title-font-size);
+		font-weight: var(--stuic-timeline-title-font-weight);
+		line-height: var(--stuic-timeline-line-height);
+		color: var(--stuic-timeline-title-text);
+		overflow-wrap: anywhere;
+	}
+
+	.stuic-timeline-link {
+		color: inherit;
+		text-decoration: none;
+	}
+
+	.stuic-timeline-link:hover {
+		text-decoration: underline;
+	}
+
+	.stuic-timeline-description {
+		margin-top: var(--stuic-timeline-description-margin-top);
+		font-size: var(--stuic-timeline-description-font-size);
+		color: var(--stuic-timeline-description-text);
+		overflow-wrap: anywhere;
+	}
+
+	.stuic-timeline-footer {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		gap: var(--stuic-timeline-footer-gap);
+		margin-top: var(--stuic-timeline-footer-margin-top);
+	}
+}

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

@@ -0,0 +1 @@
+export { default as Timeline, type Props as TimelineProps, type TimelineItem, type TimelineAlign, type TimelineTimePosition, type TimelineMarkerKind, type TimelineSnippetArg, } from "./Timeline.svelte";

package/dist/components/Timeline/index.js

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

package/dist/index.css

@@ -112,6 +112,7 @@ In practice:
 @import "./components/Switch/index.css";
 @import "./components/TabbedMenu/index.css";
 @import "./components/ThemePreview/index.css";
+@import "./components/Timeline/index.css";
 @import "./components/Tree/index.css";
 @import "./components/TwCheck/index.css";
 @import "./components/UserAvatarMenu/index.css";

package/dist/index.d.ts

@@ -84,6 +84,7 @@ export * from "./components/Switch/index.js";
 export * from "./components/TabbedMenu/index.js";
 export * from "./components/Thc/index.js";
 export * from "./components/ThemePreview/index.js";
+export * from "./components/Timeline/index.js";
 export * from "./components/Tree/index.js";
 export * from "./components/TwCheck/index.js";
 export * from "./components/TypeaheadInput/index.js";

package/dist/index.js

@@ -90,6 +90,7 @@ export * from "./components/Switch/index.js";
 export * from "./components/TabbedMenu/index.js";
 export * from "./components/Thc/index.js";
 export * from "./components/ThemePreview/index.js";
+export * from "./components/Timeline/index.js";
 // NOTE: TrendChart is deliberately NOT exported here. It statically imports the
 // optional @marianmeres/trend-chart peer, which would then be pulled into the
 // root entry graph of every consumer. It ships as the `@marianmeres/stuic/trend-chart`

package/docs/domains/components.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-73 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
+74 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
 
 ## Component Categories
 
@@ -100,6 +100,7 @@
 | Thc                 | Flexible renderer for text, HTML, components, or snippets                                            |
 | Card                | Flexible card with image, title, footer; vertical/horizontal layout                                  |
 | Stat                | KPI/stat card: label + value + delta with trend arrow and semantic coloring                          |
+| Timeline            | Vertical event list on a rail: dot/icon/custom markers, inline or opposite time, alternate layout    |
 | TrendChart          | Svelte wrapper for `@marianmeres/trend-chart` (subpath-only: `@marianmeres/stuic/trend-chart`)       |
 | Tree                | Hierarchical tree view with keyboard nav and drag-and-drop                                           |
 | X                   | Styled close/multiply SVG icon                                                                       |
@@ -1091,6 +1092,43 @@ Prefix: `--stuic-stepper-*`
 
 ---
 
+## Timeline
+
+Vertical event list with markers on a rail — activity feeds, audit logs, order tracking, history pages. A real `<ol>` (explicit `role="list"`); every item has a marker (small dot, icon bubble when `item.icon` is set, or anything via `renderMarker`), an optional time label, title, description and footer. Data-driven (`items`), static by design — no "current" step (use `Stepper` vertical for progress flows). The list is a CSS grid with `subgrid` items, so the rail and the optional time column align across items without fixed widths; the rail line runs behind the markers and a background-colored ring separates them.
+
+### Exports
+
+| Export                 | Kind      | Description                                                         |
+| ---------------------- | --------- | ------------------------------------------------------------------- |
+| `Timeline`             | component | Main component                                                      |
+| `TimelineProps`        | type      | Props type                                                          |
+| `TimelineItem`         | type      | `{ title?, description?, time?, datetime?, icon?, intent?, href? }` |
+| `TimelineAlign`        | type      | `"start" \| "alternate"`                                            |
+| `TimelineTimePosition` | type      | `"inline" \| "opposite"`                                            |
+| `TimelineMarkerKind`   | type      | `"dot" \| "icon" \| "custom"` (the marker's `data-marker`)          |
+| `TimelineSnippetArg`   | type      | `{ item, index }` — argument of all three snippets                  |
+
+### Key Props
+
+| Prop           | Type                      | Default    | Description                                                                   |
+| -------------- | ------------------------- | ---------- | ----------------------------------------------------------------------------- |
+| `items`        | `TimelineItem[]`          | required   | The events, in display order (title/description/time/icon are THC)            |
+| `align`        | `"start" \| "alternate"`  | `"start"`  | Rail on the start side, or centered rail with content alternating sides       |
+| `timePosition` | `"inline" \| "opposite"`  | `"inline"` | Time above the title inside the content, or in its own column across the rail |
+| `formatTime`   | `(datetime, item) => THC` | —          | Fallback label for items with `datetime` but no `time`                        |
+
+`item.datetime` (string or `Date`, serialized to ISO) renders the label as `<time datetime>`; without it the label is a `<span>`. `item.intent` (`IntentColorKey`) fills the dot / soft-tints the bubble. `item.href` renders the title as a link.
+
+Snippets (all receive `{ item, index }`): `renderMarker` (replaces every marker, `data-marker="custom"`), `renderItem` (replaces the whole content cell), `renderFooter` (per-item area under the description). Class slots: `class`, `classItem`, `classMarker`, `classContent`, `classTime`, `classTitle`, `classDescription`, `classFooter`. Markers are `aria-hidden`.
+
+### CSS Tokens
+
+Prefix: `--stuic-timeline-*`
+
+`gap`, `gap-vertical`, `line-height`, `connector-thickness`, `connector-bg`, `marker-size`, `marker-bg`, `marker-size-icon`, `marker-bg-icon`, `marker-text-icon`, `marker-icon-size`, `marker-radius`, `marker-ring-width`, `marker-ring-color`, `time-font-size`, `time-text`, `title-font-size`, `title-font-weight`, `title-text`, `description-font-size`, `description-text`, `description-margin-top`, `footer-gap`, `footer-margin-top`
+
+---
+
 ## CronInput
 
 Cron expression editor with preset selector, manual 5-field editor, raw expression input, human-readable descriptions, and next-run calculation.

package/docs/maybe-todo.md

@@ -59,8 +59,11 @@ Checked first, to avoid false positives:
    `WithSidePanel`, and `persistent-state` already provide the pieces.
 9. **Range slider (dual-thumb)** — `Slider` is deliberately single-value; a min/max
    range variant (price filters etc.) is a recurring ask.
-10. **Timeline / activity feed** — vertical event list with markers; common in
-    admin/audit views.
+10. ~~**Timeline / activity feed**~~ — ✅ shipped (see `src/lib/components/Timeline/`):
+    vertical event list on a rail with dot / icon-bubble / custom (snippet) markers,
+    per-item intent, `<time datetime>` support with an optional formatter, inline or
+    opposite time column, `start` / `alternate` alignment; `subgrid` keeps the columns
+    aligned without fixed widths.
 11. ~~**Stat / KPI card**~~ — ✅ shipped (see `src/lib/components/Stat/`): label +
     value + delta with trend arrow and semantic coloring (`trendIntent` for
     down-is-good metrics), hint, corner icon, footer/sparkline area.

package/package.json

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