@marianmeres/stuic 3.168.0 → 3.170.0

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

@@ -18,7 +18,8 @@ Checked first, to avoid false positives:
 - **Table pagination** — built into `DataTable` (`showpager`)
 - **Multi-select / tags input** — `FieldOptions` (async `getOptions` search, typeahead,
   `cardinality`, option groups, `allowUnknown` for ad-hoc values, `ordered` for manual
-  arrangement). See the note at the bottom on the inline-chip presentation variant.
+  arrangement, `chips` for the inline tag form factor). See the note at the bottom on
+  the inline-chip presentation.
 - **File dropzone** — `actions/file-dropzone` + `FieldFile` / `FieldAssets`
 
 ## Tier 1 — staples nearly every comparable library ships
@@ -58,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.
@@ -82,16 +86,36 @@ Checked first, to avoid false positives:
 ## Note: inline-chip presentation of FieldOptions
 
 Initially listed as a Tier-1 "tags input" gap; retracted — `FieldOptions` covers the
-capability. What stuic lacks is at most the _inline chip form factor_: chips inside the
-field with per-chip remove ×, a text input riding alongside, suggestions in a popover
-without leaving the page. Faster for dense desktop/admin work; the existing modal flow
-is arguably better on mobile.
-
-If ever built, the design to argue for: a presentation mode of `FieldOptions` (the
-selection model — `ItemCollection`, `cardinality`, `allowUnknown` — is already there),
-not a new component. Inline combobox on pointer devices, delegating to the existing
-modal on touch/small screens (`breakpoint.svelte.ts` + `device-pointer.svelte.ts`
-enable the switch).
+capability. What stuic lacked was the _inline chip form factor_. That splits into two
+separable halves, and only the second one has a mobile problem:
+
+1. ~~**Chips as the field's display**~~ — ✅ shipped (`FieldOptions` `chips` prop, see
+   `Input/README.md`): the closed field shows the selection as removable `Pill` chips
+   (per-chip ×, focus kept in the field, `change` dispatched so validation re-runs) plus a
+   trailing button that opens the existing modal; the empty part of the row opens it too.
+   Internally a `FieldLikeButton` sibling (`Input/_internal/FieldLikeChips.svelte`) — the
+   chips carry their own buttons, so they cannot live inside the `<button>` trigger. Works
+   on every device; the one touch concern (× target size) is handled with a padded hit
+   area on `pointer: coarse`.
+2. **Inline adding** (type into the field, suggestions, Enter commits) — not built. This is
+   where every mobile hazard lives (see the reality check below). The design to argue for,
+   if ever built:
+   - a presentation mode of `FieldOptions`, not a new component — the selection model
+     (`ItemCollection`, `cardinality`, `allowUnknown`, `ordered`) is already there. But the
+     engine is currently bound to the modal lifecycle (hydrate on open, fetch while
+     visible, clear on submit) and would need extracting into a shared `.svelte.ts` class
+     rather than more branches in the 1250-line file; that is the real cost
+   - no floating listbox popover: reuse the existing `typeahead` action (ghost text, Tab
+     accepts, Enter commits, Backspace at position 0 removes the last chip via
+     `onDeleteRequest`). No anchored dropdown means the soft-keyboard hazard disappears by
+     construction; the modal stays the browse path via the trailing button. A real list
+     popover can be added later behind the same prop if ghost text proves insufficient
+   - gate it on the `md` breakpoint (`breakpoint.svelte.ts`), not on `DevicePointer` —
+     that util uses `any-pointer`, so a touchscreen laptop counts as coarse and an iPad
+     with a trackpad as fine; the breakpoint is deterministic and testable in the browser
+     suite. If pointer detection is wanted as well, it should be the primary
+     `pointer: coarse`
+   - below the breakpoint, delegate to the modal — i.e. exactly the shipped `chips` mode
 
 Mobile reality check for the inline variant, if it were ever made touch-capable
 instead of delegating:

package/docs/upgrading.md

@@ -99,6 +99,12 @@ interface InputWrapClassProps {
 
 Previously most fields only accepted 5–7 of these. You can now pass any of them to **FieldInput, FieldTextarea, FieldSelect, FieldSwitch, FieldFile, FieldLikeButton, FieldObject, FieldOptions, FieldAssets, FieldPhoneNumber, FieldInputLocalized, FieldKeyValues** uniformly. `FieldCheckbox` and `FieldRadios` use bespoke layouts and keep their own narrower class-prop surface.
 
+### FieldOptions
+
+`chips` prop (opt-in): the closed field shows the selection as inline, removable `Pill` chips plus a trailing button that opens the usual modal. Removing a chip writes `value` and fires `onChange` without the modal. Companion props `classChip` / `chipIntent`; `renderValue` is ignored in this mode. The default rendering is unchanged.
+
+`Pill` gained `dismissLabel` — the accessible name of its × button (default `"Dismiss"`).
+
 ### Checkout
 
 New util:

package/package.json

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