@praxisui/rich-content 10.0.0-rc.4 → 10.0.0-rc.41

package/README.md

@@ -130,6 +130,75 @@ then resolves bindings and Json Logic without mutating the authored document.
 
 The runtime supports semantic presentation nodes such as text, badges, icons, cards, callouts, key/value lists, stats, tabs, timelines, lookup surfaces, record summaries, action cards, media blocks and presets. Use official docs for the full node vocabulary.
 
+Relational and summary nodes can attach governed `ResourceQuickViewBinding` (`[praxisQuickView]`) so operators can inspect referenced entities in place without leaving the document surface:
+- `recordReference` nodes (`data-testid="rich-record-reference-trigger"`) and `timeline` item/sub-item badges (`item.quickView`).
+- `keyValueList` items (`item.quickView`, `data-testid="rich-key-value-quick-view-trigger"`).
+- `propertySheet` / `dynamicForm` items (`item.quickView`, `data-testid="rich-property-sheet-quick-view-trigger"`), including automatic synthesis via `resolveFieldQuickViewBinding(field)` when items are resolved from a resource schema.
+- `recordSummary` fields (`field.quickView`, `data-testid="rich-record-summary-field-quick-view-trigger"`).
+
+Card nodes (`type: 'card'`) support `media.kind` values `'image'`, `'video'`, `'icon'`, `'avatar'`, `'telemetry'`, `'lottie'`, and `'component'`. When `media.kind === 'component'`, the runtime materializes the component registered in `ComponentMetadataRegistry` under `media.componentId` via `DynamicWidgetLoaderDirective`, forwarding `media.componentInputs` and the active `RichContent` `[context]` so `${...}` template expressions inside `componentInputs` resolve reactively against host/page data sources. Optional `media.width`, `media.height`, `media.aspectRatio`, `media.placement`, and `media.verticalAlign` govern the media slot geometry without custom CSS:
+
+```json
+{
+  "type": "card",
+  "orientation": "horizontal",
+  "title": "Operational Readiness",
+  "content": [],
+  "media": {
+    "kind": "component",
+    "componentId": "custom-telemetry-widget",
+    "placement": "trailing",
+    "verticalAlign": "center",
+    "componentInputs": {
+      "label": "Readiness ${readinessRate}%",
+      "interactive": true
+    }
+  }
+}
+```
+
+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"`). When `itemsExpr` is provided, static `items` may be omitted. 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`, `index`/`$index`, and merged `row` injected into the item's local expression scope (e.g. `titleExpr: "item.stepName"`, `metaExpr: "item.occurredAt"`, `action.availabilityExpr: "item.status == 'pending'"`).
+- **Progressive disclosure (`initialLimit`)**: Set `initialLimit` (positive integer, e.g. `5`) on long audit/workflow timelines to render only the first `N` events initially along with an accessible `"Show all (total) / Show less"` (`aria-expanded`, `aria-controls`) toggle button.
+- **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.
@@ -164,9 +233,17 @@ 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.
+
+Both top-level and nested `icon` and `badge` nodes expose didactic visual appearance controls in the guided editor that persist directly to canonical `node.style` (without requiring host-specific CSS classes):
+
+- **`icon` appearance & surface**: live preview, surface presets (`none`, `softTile`, `circleBadge`, `outlinedTile`, `elevatedTile`), primary controls (`fontSize`, `color`, `background`), progressive disclosure for container box (`width`/`height`, `padding`, `borderRadius`, `borderWidth`, `borderColor`, `boxShadow`), and one-click reset. The renderer applies container styles to the `.prx-rich-node[data-rich-node-type='icon']` wrapper while the inner `.prx-rich-icon` glyph inherits `fontSize` and `color`.
+- **`badge` appearance & typography**: all semantic tones (`neutral`, `primary`, `secondary`, `tertiary`, `info`, `success`, `warning`, `danger`, `error`), live preview with long-text stress toggle, visual presets (`default`, `softPill`, `solidPill`, `outlinedTag`, `compactSquare`), primary controls (`color`, `background`, `borderRadius`, `fontSize`), progressive disclosure (`fontWeight`, `textTransform`, `letterSpacing`, `padding`, `borderWidth`, `borderColor`, `iconSize` mapped to `--prx-rich-badge-icon-size`, `maxWidth`, `whiteSpace`), and one-click reset. The renderer applies `resolveNodeStyles(node)` directly to the `.prx-rich-badge` pill element so background, radius, border, typography and truncation take effect without host CSS workarounds.
+- **Didactic guardrails**: inline warnings for dimension values missing CSS units, low foreground/background contrast detection, and notices when dynamic `styleWhen` rules are active on the same node.
 
-The editor supports structured block authoring, nested card/timeline/action collections, preset selection, validation badges and advanced JSON for less common deep structures. A card body can contain a guided `compose` block, allowing icons, labels, badges, metrics, progress and action buttons bound to several record fields to be arranged in a row or column with governed spacing and wrapping. Labels and validation messages use the rich-content i18n dictionary; override them with `providePraxisRichContentI18n()`.
+Horizontal cards (`orientation: 'horizontal'`) automatically stack media and content into a single column when their container is narrow (`<= 560px`) or on mobile viewports (`<= 640px`). Action editors (`actionButton`, `actionGroup`, `card` primary interaction, `lookupCard`, `relatedRecord`, `actionCard` and `formLauncher`) expose guided controls for literal `action.payload` (`payload.path` for `navigation.openRoute` and `payload` JSON) alongside `action.payloadExpr` bindings, preserving both across round-trip. Labels and validation messages use the rich-content i18n dictionary; override them with `providePraxisRichContentI18n()`.
 
 `PRAXIS_RICH_CONTENT_AUTHORING_MANIFEST` describes governed AI/tooling operations for document replacement, block add/remove/order, text updates, link nodes, media blocks, timeline nodes/items, presets, metadata and sanitization policy. Rich content authoring is structured JSON, not arbitrary HTML or markdown patches.