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

package/README.md

@@ -26,7 +26,7 @@ npm i @praxisui/dynamic-form@latest
 Peer dependencies:
 
 - `@angular/common`, `@angular/core`, `@angular/forms`, `@angular/cdk`, `@angular/material`, `@angular/router` `^21.0.0`
-- `@praxisui/ai`, `@praxisui/core`, `@praxisui/dynamic-fields`, `@praxisui/metadata-editor`, `@praxisui/rich-content`, `@praxisui/settings-panel`, `@praxisui/visual-builder` `^9.0.0-beta.4`
+- `@praxisui/ai`, `@praxisui/core`, `@praxisui/dynamic-fields`, `@praxisui/metadata-editor`, `@praxisui/rich-content`, `@praxisui/settings-panel`, `@praxisui/visual-builder` `^9.0.0-beta.12`
 - `rxjs` `^7.8.0`
 
 ## Minimum Local Runtime
@@ -101,6 +101,140 @@ For schema-driven backend surfaces, prefer explicit `schemaUrl`, `submitUrl`, an
 
 When using resource, schema, read, or submit flows, the host must provide the effective API/CRUD service wiring for that scope.
 
+Schema-driven layout materialization is opt-in through `layoutPolicy`. Use it when the backend
+schema already publishes enough `x-ui` metadata for the runtime to build the layout without
+local `FormConfig.sections`.
+
+```html
+<praxis-dynamic-form
+  formId="employee-detail"
+  mode="view"
+  schemaUrl="/schemas/filtered?path=/api/employees/{id}&operation=get&schemaType=response"
+  [initialValue]="employee"
+  [layoutPolicy]="{
+    source: 'schema',
+    intent: 'detail',
+    preset: 'compactPresentation',
+    lifecycle: 'live',
+    persistence: 'transient',
+    schemaOperation: 'detail',
+    schemaType: 'response'
+  }">
+</praxis-dynamic-form>
+```
+
+For create/edit command forms, the policy must point at a request schema, normally through an
+explicit `schemaUrl` containing `schemaType=request` and `operation=post|put|patch`. If the
+declared `schemaUrl` conflicts with `layoutPolicy.schemaType` or `layoutPolicy.schemaOperation`,
+the runtime fails initialization instead of rendering a form from the wrong business contract.
+
+`layoutPolicy.source = "schema"` ignores authored or persisted `sections`, but preserves
+non-layout host/persisted concerns such as `actions`, `api`, `messages`, rules, hooks and rich
+blocks. Host-provided non-layout config has precedence over persisted config.
+
+When `mode="view"` and the host does not provide `presentationModeGlobal`, a schema policy with
+`intent: "detail"` or `preset: "compactPresentation"` also enables presentation rendering. Hosts
+that need traditional disabled controls for the same schema can pass `[presentationModeGlobal]="false"`.
+For compact detail screens, explicit schema `x-ui.width` values are honored as 12-column spans so
+fieldsets can render multiple read-only fields per row. Fields without an explicit width remain
+full-width to preserve existing layouts. Generated compact sections also receive semantic header
+icons derived from their group role, while field icons continue to come from existing schema
+metadata.
+In runtime rendering, compact detail containers are kept visible only when at least one referenced
+field can actually be materialized after metadata visibility, `visible=false`, `hidden=true` and
+field-rule overrides are applied. Boolean detail fields are valid presentation content, including
+`false` values; marker/flag groups should render their boolean values, not collapse them as empty
+strings. If a section has no materialized fields, the runtime hides the section instead of leaving
+an orphan title.
+When a migrated detail surface needs the summary density to win over generic schema widths, set
+`detailSummary.widthPrecedence: "summary"` together with `columns` or `responsiveColumns`. The
+default is `"schema"`, so existing forms keep honoring `x-ui.width` unless the summary policy
+explicitly opts into overriding it for the compact read-only surface.
+Use `"summary"` for curated operational summaries. If a field contains long narrative text,
+legal content, observations, or values that require scan width, keep schema precedence for that
+surface or exclude the field from the compact summary and expose it in a secondary detail group.
+
+For fields published by the backend schema, server DTO metadata remains authoritative for semantic presentation data such as `label`, `hint`, `helpText`, `tooltip`, `tooltipOnHover`, and icon metadata. Local `FormConfig` should customize layout, grouping, transient fields, actions, and host-specific behavior, but it should not redefine DTO-owned field semantics.
+
+Field-level access metadata follows the same authority boundary. When the backend publishes `x-ui.fieldAccess`, `@praxisui/core` preserves it in `FieldMetadata.fieldAccess` and `@praxisui/dynamic-form` can materialize it as hidden or read-only UX when the host supplies explicit `FormConfig.metadata.fieldAccessAuthorities` or enterprise runtime `authorities`. The runtime does not infer field authorities from `capabilities`; backend filtering and submit validation remain the security boundary.
+
+Dense operational forms should keep DTO `hint`/`helpText` intact and use `FormConfig.helpPresentation` to choose the visual policy. For drawers or command forms, prefer `display: "auto"` with `preferPopoverForControls` for controls such as `toggle`, `checkbox`, and `select`; validation errors remain inline regardless of this policy. Field-level `helpDisplay` is still authoritative when present, including `helpDisplay: "auto"` for DTOs that need a local threshold.
+
+Submit failures published in the Praxis `RestApiResponse.errors` envelope are materialized by the
+runtime. A safe public `message` is shown to the user, while an error with a `target` matching a
+form control is also attached to that control and marked as touched. Existing client validators
+are preserved, and only the previous server error is cleared before a new submit attempt. Targets
+may use Angular dotted paths or JSON Pointer syntax. Unknown targets remain form-level feedback;
+the client does not guess a field from error text, codes, keywords, or private database details.
+Generic network, validation, server, and save fallbacks use the platform i18n keys under
+`global.submitError.*`; backend-owned business messages remain authoritative.
+
+Example backend-owned `x-ui` metadata:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "frequencyType": {
+      "type": "string",
+      "x-ui": {
+        "label": "Frequency type",
+        "controlType": "async-select",
+        "helpText": "Select the operational class used by payroll and timekeeping rules.",
+        "tooltip": "Backend-owned DTO semantics; local FormConfig cannot override it.",
+        "tooltipOnHover": true,
+        "icon": "calendar_month",
+        "iconPosition": "start",
+        "iconColor": "primary",
+        "endpoint": "/api/frequency-types/options/filter",
+        "filterField": "name",
+        "sortField": "name",
+        "sortOrder": "asc",
+        "optionsPageSize": 20
+      }
+    }
+  }
+}
+```
+
+In that flow, local `FormConfig` may place `frequencyType` in sections, rows, tabs, custom actions, or corporate-only local fields. It should not persist competing `label`, `helpText`, `tooltip`, or icon metadata for `frequencyType`, because the next schema reconciliation will restore the backend DTO semantics.
+
+### ErgonX migration baseline
+
+For ErgonX-style migrations, use schema-driven layout as the preferred target once the DTO/schema is semantically ready. Treat local `FormConfig.sections` as a temporary bridge, not as the standard for hundreds of screens.
+
+Recommended defaults:
+
+- detail/read-only: `layoutPolicy.source = "schema"`, `intent = "detail"`, `preset = "compactPresentation"`, `persistence = "transient"` and a response schema;
+- create/edit: `layoutPolicy.source = "schema"`, `intent = "command"`, `preset = "groupedCommand"`, `persistence = "transient"` and a request schema;
+- `groupedCommand` expands a single orphan `md`/`lg` field to the full row by default. Set `layoutPolicy.groupedCommand.orphanFieldExpansion = "preserve"` for intentionally compact rows, or `"all"` to expand orphan `xs`/`sm` fields too;
+- dense command drawers: `helpPresentation.display = "auto"` with popover preference for select, checkbox, toggle, date and numeric controls;
+- operational input-heavy forms: `fieldIconPolicy = "presentation-only"` unless the icon is part of the actual affordance.
+
+Schema-driven command forms do not need to declare empty manual sections. Keep host config focused on behavior, messages, actions and field metadata that is genuinely local:
+
+```ts
+const commandConfig: FormConfig = {
+  metadata: { source: 'schema' },
+  behavior: {
+    disableMountAnimation: true,
+    focusFirstError: true,
+    scrollToErrors: true,
+  },
+  messages: {
+    submitSuccess: 'Registro salvo.',
+    submitError: 'Não foi possível salvar o registro.',
+  },
+};
+```
+
+Pair this config with an explicit schema source, such as `[schemaUrl]`,
+`[submitUrl]`, `[submitMethod]` and, in detached hosts, `[apiEndpointKey]` or
+`[apiUrlEntry]`. A sectionless config is valid only when the schema/runtime
+source is the canonical owner of field grouping and controls.
+
+Do not use Angular config to fix weak DTO semantics. Missing grouping, vague `helpText`, generic labels, raw coded values, wrong control types or absent option metadata should return to backend DTO/schema hardening. The detailed migration checklist lives in `docs/schema-driven-layout-materialization-rfc.md`.
+
 ## Runtime Inputs And Outputs
 
 Common inputs:
@@ -112,7 +246,7 @@ Common inputs:
 - `apiEndpointKey`, `apiUrlEntry`
 - `actions`, `layout`, `backConfig`, `hooks`
 - `enableCustomization`
-- `readonlyModeGlobal`, `disabledModeGlobal`, `presentationModeGlobal`, `visibleGlobal`
+- `readonlyModeGlobal`, `disabledModeGlobal`, `presentationModeGlobal`, `fieldIconPolicy`, `visibleGlobal`
 - `notifyIfOutdated`, `snoozeMs`, `autoOpenSettingsOnOutdated`
 - `domainRules`
 - `editorialContext`
@@ -131,6 +265,16 @@ Common outputs:
 
 `formSubmit` exposes both persistence data and full UI state:
 
+`schemaUrl`/the request schema is the only source of editable controls and the
+command payload. `responseSchemaUrl` is diagnostic response evidence; hosts must
+not use it to merge response-only properties into edit controls. Record identity
+belongs in an external read-only context component and never in `formData`.
+
+During hydration, properties absent from request-schema `fieldMetadata` do not
+create Angular form controls, so they are absent from both `rawFormData` and the
+prepared PUT/PATCH payload. Nested collection identity remains governed by its
+own item-schema submit contract.
+
 - `formData`: filtered backend payload after submit policies are applied
 - `rawFormData`: complete form value bag, including UI-only values
 
@@ -169,10 +313,70 @@ Do not model backend DTO fields as local/transient fields. If a field belongs to
 - `kind: "field"` references `fieldMetadata[].name`.
 - `kind: "richContent"` hosts a `RichContentDocument` and does not enter `fieldMetadata`, `formData`, or HTTP payloads.
 - `formRules` govern visibility, required state, values, labels, styles, and other whitelisted runtime properties.
+- `formRulesState` is internal visual-builder state. LLMs and external tools should not write it directly.
 - `formCommandRules` are used for governed side effects such as global actions.
 
 Presentation formatting of field values is resolved by `@praxisui/dynamic-fields` from field metadata such as `valuePresentation`.
 
+### Compact Presentation Preset
+
+For dense enterprise read-only screens, `DynamicFormLayoutService.generateFormConfigFromMetadata`
+can materialize a compact presentation layout directly from governed field metadata:
+
+```ts
+const config = layout.generateFormConfigFromMetadata(fields, {
+  layoutPreset: 'compactPresentation',
+  presentationRoleMap: {
+    Identificacao: 'core-attributes',
+    Regras: 'technical-scope',
+    Marcadores: 'behavior-flags',
+  },
+});
+```
+
+The preset keeps field semantics in `FieldMetadata`, creates compact rows from field width/data
+type, derives semantic section header icons from group roles, marks generated sections with
+`className: "pdx-presentation-section ..."`, and annotates
+metadata with `generatedLayoutPreset: "compactPresentation"` and `presentationDensity: "compact"`.
+Boolean fields are displayed through the canonical `valuePresentation: { type: "boolean" }` path,
+so DTO-normalized booleans and legacy display values such as `S/N` are formatted by
+`@praxisui/dynamic-fields`.
+
+When a compact read-only screen needs operational signals, use `formBlocksBefore` with a short
+`RichContentDocument` strip such as `metric` and `progress` nodes. Keep those blocks visual-only:
+they must not duplicate DTO fields in `fieldMetadata`, enter `formData`, or push the first business
+field below the useful viewport. Larger guidance cards, timelines, and stat groups belong in a
+dedicated row, side context, or a separate rich-content demonstration tab rather than the compact
+detail header.
+
+The runtime exposes host-themeable CSS variables for this mode:
+
+- `--pdx-presentation-label-width`
+- `--pdx-presentation-label-size`
+- `--pdx-presentation-value-size`
+- `--pdx-presentation-row-gap`
+- `--pdx-presentation-section-gap`
+- `--pdx-presentation-flag-height`
+- `--pdx-presentation-flag-padding`
+- `--pdx-presentation-flag-radius`
+- `--pdx-presentation-flag-font-size`
+
+Use this preset for read/detail surfaces. Do not use it to replace backend DTO documentation,
+business validation, or editable command forms. In table/detail workbenches, keep the table
+selection and the detail `initialValue` synchronized in the host; the compact form only renders
+the selected DTO state.
+
+## LLM-Safe Authoring Subset
+
+For AI-generated or tool-generated configuration, prefer canonical `FormConfig` JSON and keep edits reviewable:
+
+- Write rule suggestions to `formRules[]` with `metadata: { origin: "llm", reviewStatus: "pending" }`.
+- Do not write `formRulesState`; the editor may derive it after human review when the rule is visually representable.
+- Treat simple field comparisons, scalar literals, field-to-field comparisons, and `and`/`or` groups as the stable visual round-trip subset.
+- Treat advanced JsonLogic such as `!`, `xor`, `implies`, `between`, `notIn`, custom functions, context operands, and computed expressions as runtime-supported JSON-only unless a focused visual round-trip test exists.
+- Use only properties allowed by the target rule schema. Unsupported or sanitized properties appear in rule diagnostics and should be fixed before publication.
+- Keep side effects in `formCommandRules` with structured `globalAction: { actionId, payload }`; do not encode commands inside `formRules[].effect.properties`.
+
 ## Visual Editor
 
 Use `PraxisDynamicFormConfigEditor` directly or enable customization on the runtime.
@@ -192,6 +396,8 @@ dialog.open(PraxisDynamicFormConfigEditor, {
 
 The editor preserves the same `FormConfig` contract used by the runtime. Field type names, descriptions, and icons come from the dynamic-fields editorial metadata chain, not from a local map inside Dynamic Form.
 
+Runtime-only rules remain valid JSON when they pass diagnostics, but they may open in JSON review instead of the visual rule builder until their condition and effect shape are covered by the visual-safe subset.
+
 ## AI Authoring
 
 `PRAXIS_DYNAMIC_FORM_AUTHORING_MANIFEST` declares executable operations for governed edits to:
@@ -205,6 +411,8 @@ The editor preserves the same `FormConfig` contract used by the runtime. Field t
 
 The manifest is meant to keep AI-generated patches compatible with the visual editor and the runtime `FormConfig` contract.
 
+Rule operations in the manifest write `formRules[]`, require pending review metadata, and intentionally avoid `formRulesState`. A valid JsonLogic condition is not automatically a visual round-trip guarantee; LLMs should use the safe subset above unless the operation explicitly targets a JSON-only/runtime-only path.
+
 ## Public API
 
 Main exports: