@praxisui/rich-content 8.0.0-beta.19 → 8.0.0-beta.20

package/README.md

@@ -63,11 +63,18 @@ instead of creating local rich-content JSON editors.
 
 The canonical editor provides structured block authoring for common top-level
 nodes (`text`, `badge`, `icon`, `image`, `metric`, `progress`, `compose`,
-`link`, `card`, `mediaBlock`, `timeline` and `preset`), including add, reorder, inline
-removal confirmation and field-level editing. It also supports nested authoring
-for `card.content[]`, `compose.items[]` and `timeline.items[]`, plus governed
-preset selection from `PRAXIS_RICH_BLOCK_PRESETS`. Common node metadata such as
-`testId`, `className`, a simple `visibleWhen` equality rule and one safe inline
+`link`, `actionButton`, `card`, `callout`, `ctaGroup`, `keyValueList`,
+`emptyState`, `propertySheet`, `statGroup`, `tabs`, `recordSummary`, `lookupResult`, `lookupCard`, `relatedRecord`,
+`actionCard`, `collapsibleCard`, `disclosure`, `accordion`, `formLauncher`, `mediaBlock`,
+`timeline` and `preset`), including add, reorder, inline removal confirmation
+and field-level editing. It also supports nested authoring for
+`card.content[]`, named card slots, `compose.items[]`, `timeline.items[]` and
+governed action collections such as `callout.actions[]`,
+`recordSummary.actions[]`, `lookupCard.secondaryActions[]`, `actionCard.secondaryActions[]` and
+`disclosure.actions[]`, plus governed preset selection from
+`PRAXIS_RICH_BLOCK_PRESETS`. Common node metadata such as `testId`,
+`className`, capability-gated visibility (`requiresCapabilities` and
+`capabilityMode`), a simple `visibleWhen` equality rule and one safe inline
 style declaration can be edited visually. Advanced JSON remains available for
 less common nested fields and deep structures, but it is no longer the only
 authoring path.
@@ -102,6 +109,134 @@ Apply/Save. Hosts that need the same checks outside the settings panel can use
 unsupported document versions, unknown node types, unsafe URLs, unsafe style
 values and malformed nested nodes before persistence.
 
+### Timeline authoring
+
+`timeline` is a governed rich-content block, not a local page-builder widget.
+The public document contract supports node-level presentation fields
+`orientation`, `order`, `position`, `connectorVariant`, `connectorColor`,
+`markerVariant`, `markerColor` and `markerStyle`, plus item-level `opposite`
+and `oppositeExpr` content. `orientation` accepts `vertical` or `horizontal`;
+`order` accepts `normal` or `reverse`, allowing hosts and agents to publish the
+same lifecycle data as a vertical document flow, a horizontal process rail or a
+reverse chronological activity stream without reshaping `timeline.items[]`.
+Timeline items may override `connectorVariant`, `connectorColor`, `markerColor`
+and `markerStyle` when a specific step needs status or exception emphasis.
+These fields are available through the canonical rich-content editor, validated
+by `validateRichContentDocument()` and consumed directly by the runtime
+renderer.
+
+Use timeline node settings when the host needs to publish lifecycle, workflow or
+operational history as portable `RichContentDocument` JSON. Use item-level
+fields such as `title`, `subtitle`, `meta`, `icon`, `badge` and `opposite` for
+display data, with `*Expr` variants when the values come from the widget
+context.
+
+## Semantic blocks and interactive surfaces
+
+`@praxisui/rich-content` now supports a broader contract for configuration-first
+platform surfaces:
+
+- semantic editorial blocks such as `callout`, `keyValueList`, `emptyState`,
+`recordSummary`, `statGroup`, `tabs`, `lookupResult`, `lookupCard`, `relatedRecord`, `actionCard`, `collapsibleCard`,
+  `disclosure` and `accordion`
+- interactive buttons through `actionButton`, mediated by
+  `hostCapabilities.dispatchAction(...)`
+- governed action surfaces such as `lookupCard`, `relatedRecord`, `actionCard` and `formLauncher`, which keep
+  the document canonical while delegating execution to host capabilities
+- capability-gated visibility through `requiresCapabilities` and
+  `capabilityMode`
+- richer `card` composition through semantic surface fields (`variant`, `tone`,
+  `size`, `density`, `orientation`), optional `media`, `headerAction`,
+  whole-card `interaction`, accessibility overrides and named slots (`header`,
+  `body`, `footer`, `actions`, `aside`) while preserving the required
+  `content[]` path for existing consumers
+
+This keeps purely visual content (`card`, `callout`, `keyValueList`) distinct
+from host-mediated interaction (`actionButton`) without introducing ad hoc host
+JSON.
+
+Example semantic card surface:
+
+```ts
+const document: RichContentDocument = {
+  kind: 'praxis.rich-content',
+  version: '1.0.0',
+  nodes: [
+    {
+      type: 'card',
+      titleExpr: '${decision.title}',
+      subtitleExpr: '${decision.source}',
+      variant: 'elevated',
+      tone: 'info',
+      size: 'lg',
+      orientation: 'horizontal',
+      media: {
+        kind: 'icon',
+        icon: 'psychology',
+        label: 'AI-authored decision surface',
+        placement: 'leading',
+      },
+      interaction: {
+        mode: 'action',
+        action: { actionId: 'decision.open' },
+      },
+      accessibility: {
+        role: 'button',
+        ariaLabel: 'Open decision surface',
+      },
+      content: [
+        { type: 'text', textExpr: '${decision.summary}' },
+      ],
+    },
+  ],
+};
+```
+
+## Governed presets
+
+The preset registry still uses `PRAXIS_RICH_BLOCK_PRESETS`, and the lib now also
+publishes `providePraxisDefaultRichBlockPresets()` with a small canonical starter
+set for configuration-first hosts:
+
+- `callout-guidance`
+- `empty-state-launcher`
+- `record-summary-compact`
+
+For widget hosts such as `@praxisui/page-builder`, the component metadata also
+publishes insertion presets through `ComponentDocMeta.insertionPresets`. The
+current canonical starter set is:
+
+- `editorial-card`
+- `callout-guidance`
+- `cta-group`
+- `knowledge-surface`
+- `lookup-card`
+- `related-record`
+- `action-card`
+- `approval-audit-surface`
+- `approval-decision-surface`
+- `approval-review-surface`
+- `approval-sla-triage-surface`
+- `approval-delegation-exception-surface`
+- `employee-insight-surface`
+- `hr-compensation-review-surface`
+- `hr-performance-review-surface`
+- `hr-promotion-review-surface`
+- `hr-offboarding-surface`
+- `hr-succession-planning-surface`
+- `hr-leave-absence-surface`
+- `hr-internal-mobility-surface`
+- `onboarding-journey-surface`
+- `onboarding-equipment-access-recovery-surface`
+- `onboarding-day-30-coaching-surface`
+- `onboarding-manager-follow-up-surface`
+- `onboarding-readiness-surface`
+- `stat-group`
+- `timeline-surface`
+- `tabs-surface`
+
+Hosts can use the defaults directly or provide their own governed preset pack.
+
 ## Agentic Authoring Contract
 
 `@praxisui/rich-content` publishes an executable `ComponentAuthoringManifest`
@@ -110,7 +245,8 @@ through `PRAXIS_RICH_CONTENT_AUTHORING_MANIFEST`.
 The manifest treats rich content as structured `RichContentDocument` data, not
 HTML or markdown patches. It governs document replacement, block add/remove,
 block order, text updates, canonical link nodes, common node metadata,
-`mediaBlock` fields, `timeline.items[]`, preset refs and sanitization policy.
+`mediaBlock` fields, timeline node settings, `timeline.items[]`, preset refs
+and sanitization policy.
 Security-sensitive policy edits and destructive removals require confirmation
 before a patch can be compiled.