@praxisui/list 8.0.0-beta.20 → 8.0.0-beta.22

package/README.md

@@ -325,6 +325,49 @@ actions: [
 ```
 
 When `globalAction` is set, `actionClick` is **not emitted** by default. Use `emitLocal: true` to emit both.
+Prefer structured `payload` in visual authoring. `payloadExpr` remains an explicit advanced escape hatch in
+`GlobalActionRef`; when present without `payload`, the runtime forwards the ref to `GlobalActionService` without
+synthetic `{ item, index }` payload so the global action can evaluate the expression against its own execution context.
+Changing `actionId` in the editor clears stale payload from the previous action.
+
+## Conditional rules
+
+`rules.itemStyles` and `rules.slotOverrides` use Json Logic in the row context (`{ row: item }`). Existing flat rule fields are still supported, and the runtime also accepts canonical effect arrays aligned with `PraxisRuntimeConditionalEffectRule`.
+
+```ts
+rules: {
+  itemStyles: [
+    {
+      id: 'risk-critical',
+      condition: { "===": [{ "var": "row.risk" }, "critical"] },
+      effects: [
+        {
+          kind: 'item-style',
+          class: 'risk-critical',
+          border: '2px solid #b00020',
+          background: '#fde7ec',
+        },
+      ],
+    },
+  ],
+  slotOverrides: [
+    {
+      id: 'risk-icon',
+      slot: 'trailing',
+      condition: { "===": [{ "var": "row.risk" }, "critical"] },
+      effects: [
+        {
+          kind: 'slot-override',
+          template: { type: 'icon', expr: 'priority_high', color: 'warn' },
+          class: 'risk-icon',
+        },
+      ],
+    },
+  ],
+}
+```
+
+For compatibility, `class`, `style`, `border`, `background`, `template` and `hide` may still be declared directly on the rule. When `effects` is present, the first valid effect is used as the canonical payload and direct fields remain fallback values.
 
 For internal navigation from a row or item button, use `navigation.openRoute` and bind the selected item id into `query` or `state`:
 
@@ -392,6 +435,15 @@ Outputs:
 - **Examples/evals:** fixtures cover every operation family in the manifest, including title/subtitle binding, action creation/update/removal, status badge, selection mode, missing field rejection, skin, toolbar, export, accessibility, event mapping, row layout, expansion, data modes, i18n, empty state and conditional row styling.
 - **Declared-only semantics:** fields documented as declared-only remain authorable only as config/editor round-trip fields and are guarded by `declared-only-runtime-warning`; the manifest does not claim runtime behavior that the component does not implement.
 
+### Praxis Semantic Assistant
+
+When `enableCustomization=true`, `praxis-list` opens the shared `PraxisAiAssistantShellComponent` and registers a minimized global session instead of embedding the legacy `PraxisAiAssistantComponent`.
+
+- The assistant context is safe and semantic: component identity, list id, resource path, schema field names, item-count digest, manifest reference and governance hints.
+- Business-rule, policy, compliance, publication, materialization or enforcement prompts are routed to governed `domain-rules/intake` handoff and are not applied as local list configuration.
+- Free JSON patches from the backend are rejected. Local apply remains blocked until the response is compiled from a manifest-backed `componentEditPlan` validated against `PRAXIS_LIST_AUTHORING_MANIFEST`.
+- `ListAiAdapter.applyPatch(...)` remains available for legacy/editor internals, but the new assistant turn flow does not use it as an ungoverned patch path.
+
 ## Known limitations and mismatches
 
 1. `layout.virtualScroll` and `layout.stickySectionHeader` exist in the contract/editor, but have no runtime implementation.