@praxisui/rich-content 8.0.0-beta.7 → 8.0.0-beta.70

package/README.md

@@ -61,6 +61,30 @@ settings-panel editor for `praxis-rich-content`. Hosts such as
 `@praxisui/page-builder` should open this editor from the component metadata
 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`, `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.
+
+Runtime conditional metadata is governed by the shared JSON Logic contract:
+`visibleWhen` and `loadWhen` gate rendering, `disabledWhen` disables interactive
+surfaces, and `classWhen`/`styleWhen` apply declarative visual state. Invalid
+visibility/loading/style rules fail closed by not rendering or not applying the
+rule; invalid `disabledWhen` fails safe by disabling the action surface.
+
 The editor receives the widget input envelope and returns the same canonical
 shape expected by the runtime:
 
@@ -85,6 +109,165 @@ Authoring labels, helper text and validation messages use the rich-content i18n
 dictionary. Apps can provide overrides with `providePraxisRichContentI18n()` or
 reuse `resolvePraxisRichContentText()` when extending the canonical editor.
 
+The editor validates the public `RichContentDocument` contract before
+Apply/Save. Hosts that need the same checks outside the settings panel can use
+`validateRichContentDocument()` from `@praxisui/rich-content` to reject
+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(...)`; when `action.confirmMessage` is
+  present, runtime first calls `hostCapabilities.confirmAction(...)` and fails
+  closed without dispatch if the host does not confirm
+- 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`
+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 node settings, `timeline.items[]`, preset refs
+and sanitization policy.
+Security-sensitive policy edits and destructive removals require confirmation
+before a patch can be compiled.
+
+Link authoring uses a first-class `link` node with `label`, `href`, `target`
+and `rel`; unsafe protocols are rejected by `validateRichContentDocument()`.
+
+Each operation declares its own editable target resolver, ambiguity policy,
+preconditions, validators, affected paths, effects and typed submission impact.
+Document, block, text, link, media, timeline, preset, metadata and sanitization
+operations are `config-only` because they edit the structured widget input
+contract. `display.mode.set` is `visual-only` because it changes `layout` and
+`rootClassName` without mutating the `RichContentDocument`.
+
 ## Layout Modes
 
 The component defaults to `layout="block"` to preserve document-style rendering.