@praxisui/rich-content 10.0.0-rc.33 → 10.0.0-rc.35

package/README.md

@@ -151,6 +151,47 @@ Card nodes (`type: 'card'`) support `media.kind` values `'image'`, `'video'`, `'
 }
 ```
 
+Timeline nodes (`type: 'timeline'`) support both horizontal lifecycle milestone tracks and vertical enterprise activity/workflow feeds:
+
+- **Layout & single-sided vertical collapse**: `itemLayout` (`'stacked' | 'split'`, node-level default or per-item override) places `title`, `avatar` and `subtitle` on the leading side while aligning `badge` and `meta` (such as timestamps or SLA counters) on the trailing edge when set to `'split'`. When `orientation` is `'vertical'` (`position: 'right' | 'left'`) and no item defines `opposite`/`oppositeExpr`, the renderer automatically collapses the unused opposite column (`prx-rich-timeline--single-sided-right` / `prx-rich-timeline--single-sided-left`).
+- **Markers & semantic badges**: `markerStyle` (`'filled' | 'outlined' | 'soft'`) supports rounded soft-tinted squircle icon/number containers (`'soft'`) and halo dots. Items and sub-steps support `badgeTone` (`'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'error' | 'danger' | 'info' | 'neutral'`) for semantic status pills.
+- **Actor avatars & hierarchical sub-steps**: Each item and sub-step can include an inline `avatar` (`RichAvatarNode` with automatic initials fallback if `imageSrc` fails to load) and nested `children` (`RichTimelineItem[]`) rendered with curved branch connectors (`.prx-rich-timeline__subitem-branch`).
+- **Dynamic collection binding (`itemsExpr` & `itemTemplate`)**: Bind `itemsExpr` to an array in `[context]` (e.g. `"row.timelineEvents"`). If the array already contains `RichTimelineItem`-shaped objects, they render directly; when `itemTemplate` is also provided, each raw domain record is evaluated against `itemTemplate` with `item` and `index` injected into the item's local expression scope (e.g. `titleExpr: "item.stepName"`, `metaExpr: "item.occurredAt"`).
+- **Insertion presets**: Component metadata provides both `timeline-surface` (horizontal milestone lifecycle) and `activity-timeline-surface` (vertical activity & fulfillment feed with `itemLayout: 'split'`, `markerStyle: 'soft'`, actor avatar and branch sub-steps).
+
+```json
+{
+  "type": "timeline",
+  "title": "Order & Fulfillment Activity",
+  "orientation": "vertical",
+  "position": "right",
+  "itemLayout": "split",
+  "markerVariant": "icon",
+  "markerStyle": "soft",
+  "items": [
+    {
+      "id": "order-placed",
+      "title": "Order Placed",
+      "icon": "shopping_bag",
+      "markerColor": "info",
+      "badge": "Order #32875",
+      "badgeTone": "info",
+      "meta": "Nov 03, 04:05",
+      "avatar": { "type": "avatar", "name": "John Doe", "initials": "JD" },
+      "children": [
+        {
+          "id": "processing",
+          "title": "Order Processing",
+          "badge": "In progress",
+          "badgeTone": "warning",
+          "meta": "Nov 03, 05:27"
+        }
+      ]
+    }
+  ]
+}
+```
+
 Conditional metadata is governed by the shared JSON Logic contract:
 
 - `visibleWhen` and `loadWhen` gate rendering.
@@ -185,7 +226,7 @@ The validator rejects unsupported document versions, unknown node types, unsafe
 }
 ```
 
-The editor separates authoring into guided editing, preview and advanced JSON tabs. Guided editing keeps the document structure visible while document-level context (`context.scopes`, `context.aliases`) and the selected block expose focused controls. The advanced data/rule section surfaces canonical bindings and JsonLogic fields (`bindings`, `disabledWhen`, `loadWhen`, `classWhen`, `styleWhen`) as focused JSON editors, validates them before apply/save, and keeps the full document JSON synchronized. Preview renders the materialized document without mixing authoring fields, and advanced JSON remains available for diagnostics, migration and less common deep structures.
+The editor separates authoring into guided editing, preview and advanced JSON tabs. Guided editing keeps the document structure visible while document-level context (`context.scopes`, `context.aliases`) and the selected block expose focused controls. The advanced data/rule section surfaces canonical bindings and JsonLogic fields (`bindings`, non-simple `visibleWhen` boolean or composite `all`/`any`/`not` rules, `disabledWhen`, `loadWhen`, `classWhen`, `styleWhen`) as focused JSON editors, validates them before apply/save, and keeps the full document JSON synchronized. Preview renders the materialized document with a deterministic preview context (`buildRichContentPreviewContext`) that preserves authored `document.context` values and seeds representative sample data for unbound `*Expr` paths, pipes (`number`, `currency`, `percent`, `date`), `${...}` / `{{...}}` tokens, aliases and `timeline.itemsExpr`, while advanced JSON remains available for diagnostics, migration and less common deep structures.
 
 The editor supports structured block authoring, nested card/timeline/action collections, card media component discovery via `ComponentMetadataRegistry` (`media.kind = 'component'`), preset selection, validation badges and advanced JSON for less common deep structures. Clearing `rootClassName` emits `rootClassName: ''` so host runtime bindings clear any previously applied class, and the renderer safely ignores `null`/`undefined` or whitespace-only values. Card slots (`header`, `footer`, `aside`), card content and top-level `compose` blocks support nested `compose` structures with both Flex (`direction`, `gap`, `wrap`, `alignItems`) and CSS Grid (`layout: 'grid'`, `columns`, `minColumnWidth`, `gap`, `alignItems`) configurations plus nested items. All nested presenter and action nodes inside `card` (`header`, `content`, `actions`, `footer`, `aside`) and `compose` expose `className` in the guided editor, display explicit target breadcrumbs (`Card › Section › Compose › Item`), and support deep structure tree navigation (`Card -> Slot -> Compose -> Item`) and item reordering.