@praxisui/dynamic-form 9.0.0-beta.22 → 9.0.0-beta.25

package/README.md

@@ -101,8 +101,50 @@ 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.
+
 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.
 
+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.
+
 Example backend-owned `x-ui` metadata:
 
 ```json
@@ -133,6 +175,19 @@ Example backend-owned `x-ui` metadata:
 
 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;
+- 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.
+
+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:
@@ -144,7 +199,7 @@ Common inputs:
 - `apiEndpointKey`, `apiUrlEntry`
 - `actions`, `layout`, `backConfig`, `hooks`
 - `enableCustomization`
-- `readonlyModeGlobal`, `disabledModeGlobal`, `presentationModeGlobal`, `visibleGlobal`
+- `readonlyModeGlobal`, `disabledModeGlobal`, `presentationModeGlobal`, `fieldIconPolicy`, `visibleGlobal`
 - `notifyIfOutdated`, `snoozeMs`, `autoOpenSettingsOnOutdated`
 - `domainRules`
 - `editorialContext`
@@ -206,6 +261,54 @@ Do not model backend DTO fields as local/transient fields. If a field belongs to
 
 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: