@praxisui/dynamic-form 9.0.0-beta.9 → 9.0.0-rc.1

package/docs/dynamic-form-visual-builder-parity-audit.md

@@ -0,0 +1,268 @@
+---
+title: "Dynamic Form Visual Builder Parity Audit"
+slug: "dynamic-form-visual-builder-parity-audit"
+description: "Auditoria de claims, paridade runtime/editor e plano de melhoria para o fluxo de regras do Dynamic Form com Visual Builder."
+doc_type: "audit"
+document_kind: "host-guide"
+category: "architecture"
+audience:
+  - "frontend"
+  - "platform-team"
+  - "architect"
+  - "llm-integrator"
+level: "advanced"
+status: "draft"
+owner: "praxis-ui"
+tags:
+  - "dynamic-form"
+  - "visual-builder"
+  - "rules"
+  - "json-logic"
+  - "llm"
+toc: true
+sidebar: false
+reading_time: "18 min"
+last_updated: "2026-06-17"
+source_of_truth:
+  - "projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.html"
+  - "projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.ts"
+  - "projects/praxis-dynamic-form/src/lib/utils/rule-converters.ts"
+  - "projects/praxis-dynamic-form/src/lib/utils/rule-authoring-diagnostics.ts"
+  - "projects/praxis-dynamic-form/src/lib/services/form-rules.service.ts"
+  - "projects/praxis-core/src/lib/models/form/rule-property.schema.ts"
+  - "projects/praxis-visual-builder/src/lib/praxis-visual-builder.ts"
+  - "projects/praxis-visual-builder/src/lib/services/rule-builder.service.ts"
+  - "projects/praxis-visual-builder/src/lib/components/field-condition-editor.component.ts"
+  - "projects/praxis-visual-builder/src/lib/ai/praxis-visual-builder-authoring-manifest.ts"
+---
+
+# Dynamic Form Visual Builder Parity Audit
+
+## Classification
+
+`docs-apenas` for this artifact.
+
+This document does not change runtime behavior, public exports, manifest
+operations or npm package documentation. Any follow-up that changes
+`README.md`, public AI manifests, `RULE_PROPERTY_SCHEMA`, JSON Logic parsing,
+`FormLayoutRule`, `formCommandRules` or editor behavior must be reclassified as
+`contrato-publico` or `transversal` before editing.
+
+## Canonical Owner And Boundaries
+
+| Area | Canonical owner | Boundary |
+| --- | --- | --- |
+| `FormConfig`, `formRules`, `formCommandRules`, embedded config editor | `@praxisui/dynamic-form` | Dynamic Form owns the authored form document and editor integration. |
+| JSON Logic visual authoring and `RuleBuilderState` | `@praxisui/visual-builder` | Visual Builder owns visual rule graph, condition authoring and round-trip to serialized JSON expressions. |
+| Allowed rule effect properties | `@praxisui/core` via `RULE_PROPERTY_SCHEMA` | Core owns the canonical property schema consumed by Dynamic Form and authoring tools. |
+| Global action execution shape | `@praxisui/core` / shared action contract | Persisted command effects must use `globalAction: { actionId, payload?, payloadExpr?, meta? }`. |
+| Public docs and npm claims | Package READMEs, landing docs, AI manifests | Public claims must not exceed tested runtime/editor parity. |
+
+## Expert Review Synthesis
+
+Four specialist reviews were requested before creating this artifact:
+
+| Review area | Main confirmation | Required adjustment |
+| --- | --- | --- |
+| Contract/runtime | `formRules`, `formRulesState` and `formCommandRules` are distinct contracts and must not be collapsed. | Build two technical parity matrices instead of one. |
+| UX/design | The issue is a trust gap: the editor suggests some capabilities that are not safely persisted or reopened. | Add a short confidence-hygiene phase before broad UX expansion. |
+| Docs/LLM | Public claims and AI manifests can lead LLMs to generate valid JSON that is not visual-builder compatible. | Add a public-claims matrix and an LLM-safe subset before updating npm docs. |
+| Tests/E2E | Existing tests cover basic rules and commands, but advanced round-trip gaps are under-tested. | Add focused converter/diagnostic specs before broad Playwright flows. |
+
+## Core Problem
+
+The current flow has four different levels of support that are not consistently
+distinguished:
+
+| Level | Meaning |
+| --- | --- |
+| Runtime-supported | The saved JSON/config can be consumed by the runtime. |
+| JSON-authorable | A user or LLM can express the config in JSON. |
+| Visual-authorable | The editor can create and edit it through guided UI. |
+| Visual round-trip stable | The editor can reopen the saved config without semantic drift. |
+
+The risky state is when a capability is runtime-supported or modelled, but the
+editor either hides it behind raw JSON or exposes it without preserving the
+semantic payload.
+
+## Public Claims Matrix
+
+This matrix prevents public docs, npm READMEs and AI manifests from promising
+more than the implementation can safely support.
+
+| Claim / surface | Published or advertised | Implemented | Tested | LLM-safe status | Recommended action |
+| --- | --- | --- | --- | --- | --- |
+| LLMs and consumers should write `formRules`, not `formRulesState` | README now includes an `LLM-Safe Authoring Subset` | Yes | Manifest spec protects AI rule operations from writing `formRulesState` | Safe when stated explicitly | Keep this wording in npm README and landing docs before publication. |
+| Simple field conditions with scalar values and `and/or` round-trip visually | Advertised indirectly by visual rule authoring | Yes | Yes, basic coverage | Safe | Keep as stable visual round-trip subset. |
+| Advanced JSON Logic operators round-trip visually | README and AI manifest now mark advanced operators as runtime JSON-only until focused visual round-trip support exists | Partial | Converter specs cover representative JSON-only operators; manifest spec protects condition descriptions | Not safe for visual claims | Keep runtime JSON-only wording until parser/emitter support exists. |
+| `valueType = field/context/function` is a visual condition capability | UI/model expose it | Field-to-field is implemented; context/function are explicitly blocked until a canonical shape exists | Partial | Field is safe; context/function are not safe | Keep field-to-field as supported; define canonical shapes before enabling context/function. |
+| Context variables are authorable through visual-builder | Manifest now separates registry support from field-condition operands | Registry/config support only | Manifest spec updated | Safe as registry-only; not safe as condition operand | Keep registry wording; define canonical condition operand shape before enabling context references. |
+| `dsl.roundTrip.validate` is a general guarantee | Manifest now scopes it to the runtime-supported visual subset | Limited by supported subset | Manifest spec updated; advanced nodes still insufficient | Safe only when scoped | Keep subset wording; fail or classify unsupported advanced cases. |
+| `surface.open` command payload is visually authorable | Dynamic Form command rules now reuse the canonical `SurfaceOpenActionEditorComponent` | Yes for structured `payload`; `payloadExpr` remains advanced | Focused config-editor spec plus Playwright save/reopen flow | Safe for structured payload | Keep `payloadExpr` as advanced JSON-only; common target coverage includes `praxis-dynamic-form`, `praxis-table` and `praxis-crud`. |
+| `payloadExpr` is missing from UI | JSON contract supports it | Runtime-supported and preserved through advanced JSON | Focused config-editor specs cover preserve-without-payload and replace-when-structured-payload-is-authored | Advanced JSON-only | Treat as deliberate escape hatch unless product decision promotes it to structured UI. |
+| Multiple command effects are authorable | Contract shape is array-based | Primary effect is visually editable; secondary effects are preserved when editing the primary effect | Focused config-editor spec | Not fully LLM-safe for visual authoring | Keep secondary effects JSON-authored until a multi-effect UI is designed. |
+| Visual Builder README npm reflects local source | Published npm can lag local README and search metadata can be stale | npm search and `npm view` show canonical packages published as `9.0.0-beta.20`; retired `@praxisui/specification*` packages are tracked as known retired packages | `release:postflight:npm`, `validate:npm-search-surface`, `validate:npm-docs`, `validate:package-peers` and `audit:npm-packages` pass for the canonical inventory | Safe for version parity; retired npm packages remain visible externally until npm deprecation is executed by an authenticated owner | Keep `@praxisui/specification*` out of active docs, configs and release inventory. |
+
+## Technical Matrix A: `formRules`
+
+This matrix covers `FormLayoutRule`, `RuleBuilderState`, `RULE_PROPERTY_SCHEMA`
+and the visual rule builder embedded in the Dynamic Form config editor.
+
+| Capability | Runtime | JSON authoring | Visual create/edit | Reopen round-trip | Diagnostics | Current classification | Recommended action |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Field target rule | Executes through `FormRulesService` | Yes | Yes | Stable for simple cases | Compatible | Stable visual round-trip | Keep and protect with specs. |
+| Section/action/row/column/visualBlock target rule | Executes when target exists and properties are allowed | Yes | Yes | Covered for known, prefixed and section header action target cases | Compatible or property diagnostics | Stable visual round-trip for covered target types | Keep focused converter and diagnostic coverage for target normalization. |
+| Multiple targets | Runtime shape supports target arrays | Yes | Yes for homogeneous target arrays | Stable for representative field and prefixed non-field targets | Compatible for covered prefixes | Stable for homogeneous target arrays | Add mixed-target visual interaction only if the UI starts allowing heterogeneous target sets. |
+| Simple condition: field op literal | Executes | Yes | Yes | Stable for supported operators | Compatible | Stable visual round-trip | Keep as canonical baseline. |
+| Nested `and/or` | Executes when JSON Logic is valid | Yes | Yes for field-condition groups | Stable for nested `and`/`or` with visual-safe field conditions | Covered by converter specs | Stable visual round-trip for covered subset | Keep separate from advanced operators such as `not`, `xor`, `implies`, `between` and `notIn`. |
+| `not`, `!`, `xor`, `implies` | Runtime support must be verified per operator | JSON may be valid | Model suggests support | Not stable | Runtime-only | Runtime-supported JSON-only or experimental | Do not advertise visual round-trip until parser/emitter support exists. |
+| `between`, `notIn`, null/empty operators | Runtime support must be verified per operator | JSON may be valid | Hidden from visual condition editor until round-trip is canonical | Not stable | Runtime-only / invalid | Runtime-supported JSON-only or experimental | Keep hidden from visual UI; re-enable only with parser/emitter specs. |
+| Compare with another field | JSON Logic can express `{ var: otherField }` | Yes | UI exposes `valueType=field` | Stable after field-to-field round-trip support | Compatible | Stable visual round-trip | Keep and protect with converter/service specs. |
+| Compare with context variable | Depends on context provider semantics | Yes if canonical path exists | Disabled in UI until canonical shape exists | Blocked by validation | Invalid/unsupported | Planned/experimental | Define canonical var path and round-trip before public claim. |
+| Compare with function result | Depends on function registry semantics | Possibly | Disabled in UI until canonical shape exists | Blocked by validation | Invalid/unsupported | Planned/experimental | Keep experimental until function call JSON shape is canonical. |
+| Property effect true values | Runtime sanitizes through property schema utilities | Yes | Yes | Stable for scalar values and covered structured editors | Covered for scalar hydrate and structured emit/hydrate | Stable for covered editors | Keep object-property expansion scoped to high-frequency properties. |
+| Property effect false values | Runtime shape supports false branch | Yes | Yes for structured property editors | Stable for `options`, `validators`, breakpoint maps and `style` | Covered for emit/hydrate | Stable for covered editors | Improve clearer review UI only if product UX requires stronger visual comparison. |
+| Object properties: `style`, `options`, validators, responsive maps | Runtime may accept sanitized values | Yes | `field.options`, `field.validators`, `field.style` and column breakpoint maps (`span`, `offset`, `order`, `hidden`) now have structured editors; `style` supports generic CSS string/number pairs | Partial | Sanitized / unsupported property | Supported partially | Specialize high-frequency style tokens only when product UX requires stronger guided controls. |
+| VisualBlock text/title/message node ids | Runtime supports governed overrides | Yes | Yes through property panel | Stable for value and node-id hydrate/apply | Covered by property-panel specs | Stable guided property path | Keep technical `*NodeId` fields hidden from the primary property selector. |
+| LLM-generated pending review | Adapter rejects direct `formRulesState` writes | Yes via `formRules` | Review flow exists with guarded accept action | Stable when diagnostics are clean | Pending review until accepted | Stable governance path | Preserve; public docs must emphasize reviewed `formRules` and no direct `formRulesState`. |
+| Runtime-only existing rule | Runtime may execute | Yes | Visible as diagnostics, not visually editable | Preserved without visual conversion | Runtime-only with `Ver JSON` action | Supported JSON-only | Keep non-destructive JSON review; add conversion only after a canonical visual shape exists. |
+
+## Technical Matrix B: `formCommandRules`
+
+This matrix covers conditional commands, JSON Logic conditions,
+`GlobalActionRef`, policies and effects.
+
+| Capability | Runtime | JSON authoring | Visual create/edit | Reopen round-trip | Diagnostics | Current classification | Recommended action |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Command condition: simple field op literal | Executes when condition validates | Yes | Yes via condition mode | Stable for simple cases | Preview | Stable visual round-trip | Keep and protect with specs. |
+| Command condition: advanced JSON Logic | Runtime validator may accept broader JSON Logic | Yes | Not fully | Runtime-only in visual editor | Preview/JSON | Runtime-supported JSON-only | Mark clearly; do not imply full visual condition parity. |
+| `dialog.alert` structured payload | Executes via `GlobalActionRef` | Yes | Yes | Covered by E2E | Preview/errors | Stable visual authoring | Keep as baseline. |
+| `surface.open` payload | Executes if valid `GlobalActionRef` | Yes | Structured editor now reused in command rules | Focused spec and Playwright flow cover hydrate/edit/apply/save/reopen | Error/preview | Supported structured path | Keep common target coverage aligned with canonical `SURFACE_OPEN_PRESETS`; focused specs cover dynamic-form/table round-trip and CRUD payload preservation. |
+| `payloadExpr` | Runtime contract supports escape hatch | Yes | Not exposed as primary UI | Preserved when no structured payload is authored; replaced when structured payload is authored | Preview / focused spec | Advanced JSON-only escape hatch | Keep JSON-only unless product decision promotes a structured expression editor. |
+| Multiple effects | Contract uses array | Yes | UI edits the primary global action and preserves secondary effects | Secondary effects are preserved when editing the primary effect | Focused spec protects non-destructive primary-effect edits | Primary visual authoring plus secondary JSON preservation | Design explicit multi-effect UI before advertising full visual authoring. |
+| Policy `distinct` and `distinctBy` | Runtime policy supported | Yes | Yes | Stable for visual edit/apply | Preview | Stable visual authoring | Keep controls scoped to the common command policy path. |
+| Policy `runOnInitialEvaluation` | Runtime skips initial command execution unless explicitly enabled | Yes | Yes | Stable for hydrate/preview/apply | Preview | Stable visual authoring | Keep explicit because initial side effects are high-risk. |
+| Other trigger modes / while-true behavior | Runtime behavior may be limited | JSON may express variants | Not exposed as visual controls | JSON-authored policy fields are preserved when editing visual fields | Focused spec protects non-destructive policy round-trip | Runtime-supported JSON-only | Keep JSON-only until runtime semantics are aligned; do not advertise full visual trigger authoring. |
+| Invalid command payload | Runtime should reject or fail safely | Yes | Yes for catalog-required payload keys | Covered for `dialog.alert` and `surface.open` incomplete payloads | Authoring error / invalid preview | Stable for catalog-required keys | Keep deeper structural validation in the shared global-action catalog/runtime, not in the Dynamic Form editor. |
+
+## Confidence Hygiene Backlog
+
+These items are intentionally smaller than full parity work. They reduce false
+signals before expanding the editor.
+
+| Item | Class | Reason | Risk | Validation |
+| --- | --- | --- | --- | --- |
+| Remove visible placeholder buttons or implement their actions | `ja-suportado-mal-nomeado-ou-mal-materializado` | Placeholder actions damage authoring trust. | Low if hidden; medium if implemented. | Component spec or focused Playwright interaction. |
+| Fix mojibake in critical editor surfaces | `ja-suportado-so-ux` | Corrupted labels weaken UX and LLM-facing docs; clear-column copy now has i18n-backed coverage. | Low, but encoding-sensitive. | `row-configurator` spec asserts clear-column copy has no `Ã`/`Â`; continue scanning broader editor surfaces. |
+| Mark unsupported visual condition options as unavailable | `suportado-parcialmente` | `context` and `function` operands are shown as JSON-only and normalized out of visual authoring; unsupported operators such as `between`, `notIn`, null/empty and regex operators are hidden until parser/emitter support exists; `literal`, `field` and the visual-safe operator subset remain authorable. | Medium; may appear as feature removal. | `field-condition-editor` spec covers visual-safe valueType normalization, visual-safe operator filtering and unsupported reopened operators. |
+| Replace native `confirm()` in authoring chrome | `ja-suportado-so-ux` | Platform authoring now uses the governed Material confirmation dialog for clearing column content. | Low. | `row-configurator` spec covers cancel and confirm flows. |
+| Improve runtime-only rule state actions | `ja-suportado-mal-nomeado-ou-mal-materializado` | Runtime-only diagnostics now expose a non-destructive `Ver JSON` action that opens JSON review without rewriting visual state. | Low/medium. | Config editor spec covers JSON review navigation without mutating `formRulesState`. |
+| Add focused advanced-condition gap specs | `docs-apenas` | Converter specs now explicitly preserve `!`, `xor`, `implies`, `between` and `notIn` as JSON-only instead of silently implying visual round-trip support. | Low; test-only guard. | `rule-converters` spec documents unsupported visual shapes without changing runtime behavior. |
+| Keep target normalization parity specs | `docs-apenas` | Prefix handling for `visualBlock`, `section`, row, column and action targets is protected against false runtime-only diagnostics and round-trip drift. | Low; test-only guard. | `rule-converters` and `rule-authoring-diagnostics` specs cover explicitly typed prefixed targets, multiple prefixed non-field targets and section header actions. |
+
+## Visual QA Findings
+
+The first browser-level validation of the expanded rule property panel found two
+runtime/editor gaps that unit specs did not expose:
+
+| Finding | Cause | Resolution | Evidence |
+| --- | --- | --- | --- |
+| Numeric structured fields could fail in the browser while unit specs passed | Angular `input type="number"` can write a numeric value into `ngModel`, while the editor builders expected string-only `.trim()` semantics. | Structured builders now normalize editor values through a shared string conversion before validation and persistence. | Focused Playwright flow covers `style`, `options`, `validators` and column `span`. |
+| A property-panel apply could be overwritten by a stale visual-builder echo | The config editor accepted a delayed `rulesChanged` event after applying a newer property-panel state. | The config editor now suppresses stale builder echoes until the expected property-panel state is observed. | Config-editor spec simulates stale echo after applying column `span`; Playwright confirms visual round-trip. |
+
+## Follow-Up Implementation Order
+
+1. Baseline current tests before behavior changes.
+2. Add focused unit specs that document current advanced-condition gaps. Completed for unary negation and unsupported advanced operator shapes in `rule-converters.spec.ts`.
+3. Add focused unit specs for target normalization and multiple prefixed non-field targets. Completed in `rule-converters.spec.ts` and `rule-authoring-diagnostics.spec.ts`.
+4. Decide the operator and `valueType` policy. Completed by keeping `literal` and `field` as visual-safe operands, disabling `context` and `function`, and hiding unsupported operators from the visual condition editor until round-trip support exists.
+5. Update public claims and AI manifest language to match the supported subset. Completed for Dynamic Form README and AI rule-operation condition descriptions.
+6. Expand editors for the next highest-frequency JSON-only command/property
+   paths. Completed for structured `surface.open`, scalar property hydration,
+   `propertiesWhenFalse` hydration, visual-block node-id guided properties,
+   command payload fail-closed validation and non-destructive preservation of
+   secondary command effects/policy fields.
+7. Keep `payloadExpr`, secondary effects, advanced condition operators,
+   `context/function` operands and non-common trigger policies as JSON-only
+   until each one has a canonical visual shape and focused round-trip specs.
+8. Add focused Playwright flows only after contract and converter behavior are
+   explicit.
+9. Validate npm publication and landing links after GitHub Actions publishes a
+   new package version. Completed for version parity after aligning local
+   package manifests to the published `9.0.0-beta.20`; legacy
+   `@praxisui/specification*` packages are retired known packages, not active
+   release inventory.
+
+## NPM Publication Check
+
+Registry checks on 2026-06-17 show the canonical `@praxisui/*` packages
+published as `9.0.0-beta.9` with `latest` also pointing to `9.0.0-beta.9`.
+The local workspace manifests were aligned from `9.0.0-beta.4` to
+`9.0.0-beta.9`, so the existing postflight validators now pass for canonical
+version parity.
+
+Commands run:
+
+```powershell
+npm search praxisui --json
+npm view @praxisui/table-rule-builder version dist-tags homepage repository.url bugs.url --json
+cmd.exe /c npm run validate:npm-registry -- --published
+cmd.exe /c npm run validate:npm-search-surface
+cmd.exe /c npm run validate:package-peers
+cmd.exe /c npm run validate:npm-docs
+cmd.exe /c npm run audit:npm-packages
+```
+
+Resolved:
+
+- `validate:npm-registry -- --published` passes after local package manifests
+  were aligned to `9.0.0-beta.9`.
+- `validate:npm-search-surface` passes for the 22 canonical packages after the
+  local-vs-search version drift was removed.
+- `validate:package-peers`, `validate:npm-docs` and `audit:npm-packages` pass
+  for the aligned package metadata.
+
+Retired package policy:
+
+- npm search can still report `@praxisui/specification` and
+  `@praxisui/specification-core` at `1.0.0-beta.28`.
+- They are tracked as known retired packages and must stay out of active docs,
+  workspace paths, test libs and release inventory.
+- External npm deprecation still requires an authenticated package owner.
+
+## Validation Plan
+
+Before functional changes:
+
+```powershell
+cmd.exe /c npx ng test praxis-visual-builder --watch=false --browsers=ChromeHeadless
+cmd.exe /c npx ng test praxis-dynamic-form --watch=false --browsers=ChromeHeadless --include=projects/praxis-dynamic-form/src/lib/utils/rule-converters.spec.ts --include=projects/praxis-dynamic-form/src/lib/utils/rule-authoring-diagnostics.spec.ts
+```
+
+For authoring flows after behavior changes:
+
+```powershell
+cmd.exe /c npx playwright test projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-rules.playwright.spec.ts
+cmd.exe /c npx playwright test projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-command-rules.playwright.spec.ts
+cmd.exe /c npx playwright test projects/praxis-dynamic-form/test-dev/e2e/surface-open-form-demo.playwright.spec.ts
+```
+
+Use Playwright screenshots as visual evidence only. Functional assertions should
+prefer config JSON, diagnostics state and stable `data-testid` selectors.
+
+## Ready Criteria For The Next Public Docs Update
+
+- Public README claims are mapped to `stable visual round-trip`,
+  `runtime-supported JSON-only` or `planned/experimental`.
+- AI manifest operations that cannot round-trip are downgraded, made explicit
+  as experimental, or backed by focused tests.
+- Structured command payloads, scalar properties, false-branch property values
+  and visual-block guided properties are backed by focused round-trip specs
+  before being described as visually authorable.
+- `formRulesState` is documented as internal editor state, never as an LLM write
+  target.
+- NPM package page, `npm view`, dist-tags, landing page and official links are
+  checked after publication.
+- The LLM-safe subset is explicit: simple JSON Logic field comparisons,
+  `and/or`, existing targets, properties allowed by `RULE_PROPERTY_SCHEMA`,
+  reviewed `formRules`, no direct `formRulesState`, no JavaScript/textual DSL.