@praxisui/dynamic-form 9.0.0-beta.9 → 9.0.0-beta.90

package/docs/schema-driven-layout-materialization-rfc.md

@@ -0,0 +1,498 @@
+---
+title: "RFC - Schema-driven Layout Materialization For Dynamic Form"
+doc_type: "rfc"
+component: "praxis-dynamic-form"
+status: "implemented-partial"
+owner: "praxis-ui"
+last_updated: "2026-06-29"
+classification: "contrato-publico, arquitetural"
+---
+
+# RFC - Schema-driven Layout Materialization For Dynamic Form
+
+## Status
+
+Implemented partial, review-revised.
+
+This document records the platform design direction and the first runtime implementation tranche.
+
+Specialized review approved the direction and blocked implementation readiness until ownership, precedence, persistence, preset naming, operation schema source, section id stability and visual acceptance criteria were made explicit. The current implementation keeps schema-driven layout opt-in, validates declared schema URL context, preserves non-layout config concerns, and leaves visual acceptance as a promotion gate.
+
+## Context
+
+Praxis Dynamic Form already consumes backend metadata and can generate form layouts from schema-derived fields. In practice, hosts still repeat `FormConfig.sections` locally for read-only detail views and for create/edit command forms, even when the backend DTOs publish `x-ui` metadata such as `group`, `order`, `width`, labels, help text, read-only hints and presentation metadata.
+
+The Ergon migration exposed this as a recurring platform issue. The `ERGadm00034` screen for codigos de frequencia currently needs local section configs for detail and command forms although the Java DTOs already publish grouped metadata. The same pattern appears in other migrated forms, including regras de frequencia, tipos de rubrica and vinculos funcionais.
+
+This is not an Ergon-only design problem. If every migrated screen must author local `FormConfig.sections`, the platform loses the main benefit of schema-driven UI: one canonical backend contract feeding many hosts consistently.
+
+## Classification
+
+This RFC is classified as `contrato-publico` and `arquitetural`.
+
+The affected public surface is the Dynamic Form layout contract around schema materialization, `FormConfig`, generated presets, and the way consumers opt into generated read-only and editable layouts.
+
+## Impact Map
+
+- Canonical subprojects affected: `praxis-ui-angular`, primarily `@praxisui/dynamic-form` and `@praxisui/core`.
+- Consumers impacted: `ergon-web`, `@praxisui/crud`, surface action launchers, official examples, playgrounds and any host using `schemaUrl`, `resourcePath` or local `FormConfig`.
+- Public docs potentially affected: Dynamic Form README, JSON API docs, authoring docs, docs shell registry, landing-page published guides and AI authoring manifests.
+- Examples and recipes potentially affected: Dynamic Form examples, CRUD dialog examples, schema-driven resource examples and Ergon migration recipes.
+- Minimum validations needed for implementation: focused unit tests for the shared materializer, Dynamic Form runtime tests, CRUD dialog-host tests and visual checks for desktop and narrow viewports.
+- Breaking-change risk: medium if defaults are changed; low if the new behavior is opt-in and authored configs keep precedence by default.
+
+## Problem
+
+The platform currently supports the pieces of schema-driven layout, but the behavior is not materialized as a first-class runtime policy.
+
+Observed gaps:
+
+- `SchemaNormalizerService` normalizes `x-ui` metadata such as `group`, `order`, `width`, visibility and value presentation.
+- `mapFieldDefinitionToMetadata()` preserves the same metadata on `FieldMetadata`.
+- `DynamicFormLayoutService.generateFormConfigFromMetadata()` can create grouped layouts and already supports a compact presentation preset.
+- `PraxisDynamicForm.generatedLayoutPreset` is currently an initial-generation hint. It does not define a durable runtime policy when a host passes a config or when local persisted config exists.
+- `SurfaceOpenMaterializerService` has its own local layout builder, which risks duplicating and diverging from Dynamic Form layout behavior.
+- CRUD dialog flows can render schema-driven forms, but there is no canonical way to ask for a grouped command layout instead of relying on default generated layout or local config.
+
+The result is repeated local `FormConfig.sections` in application screens. This creates drift from the backend DTO contract, increases migration effort and makes the first migrated screens poor templates for hundreds of future screens.
+
+## Existing Capability Assessment
+
+This is `suportado-parcialmente` and `ja-suportado-mal-materializado`, not a complete absence of metadata contract.
+
+The backend can already publish the metadata required for a reasonable layout. The missing platform capability is an explicit, reusable and opt-in runtime materialization policy that turns schema metadata into stable read-only and editable layouts without forcing every host to write sections by hand.
+
+## Goals
+
+- Let hosts render grouped read-only detail views from schema metadata without local `FormConfig.sections`.
+- Let hosts render grouped create/edit command forms from schema metadata without local `FormConfig.sections`.
+- Preserve authored `FormConfig` as the default behavior to avoid breaking existing consumers.
+- Centralize the layout algorithm so Dynamic Form, CRUD and surface action launchers do not diverge.
+- Keep the backend as the canonical owner of field semantics.
+- Allow host config to continue owning non-layout concerns such as actions, messages, hooks and behavior.
+- Provide a migration path for Ergon and other hosts to remove repeated local layout sections gradually.
+
+## Non-goals
+
+- Do not generate DTO documentation from UI labels or property names.
+- Do not move domain semantics from backend DTOs into Angular configs.
+- Do not change Dynamic Form defaults in this RFC.
+- Do not overwrite or silently discard authored `FormConfig.sections`.
+- Do not create an Ergon-specific preset.
+- Do not introduce new backend `x-ui` metadata until existing metadata is proven insufficient.
+
+## Proposed Design
+
+Introduce an opt-in schema-driven layout policy for Dynamic Form.
+
+```ts
+export type DynamicFormLayoutSource = 'authored' | 'schema';
+
+export type DynamicFormSchemaLayoutPreset =
+  | 'default'
+  | 'compactPresentation'
+  | 'groupedCommand';
+
+export type DynamicFormLayoutIntent = 'detail' | 'command';
+
+export type DynamicFormLayoutLifecycle = 'initial' | 'live';
+
+export type DynamicFormLayoutPersistence = 'transient' | 'authorable';
+
+export type DynamicFormLayoutDetachBehavior = 'none' | 'explicit';
+
+export interface DynamicFormDetailSummaryPolicy {
+  includeFields?: readonly string[];
+  excludeFields?: readonly string[];
+  includeGroups?: readonly string[];
+  excludeGroups?: readonly string[];
+  includeRoles?: readonly string[];
+  excludeRoles?: readonly string[];
+  maxFields?: number;
+  fieldPriority?: Record<string, number>;
+  groupPriority?: Record<string, number>;
+  columns?: number;
+  responsiveColumns?: Partial<Record<'xs' | 'sm' | 'md' | 'lg' | 'xl', number>>;
+  widthPrecedence?: 'schema' | 'summary';
+}
+
+export interface DynamicFormLayoutPolicy {
+  source: DynamicFormLayoutSource;
+  preset?: DynamicFormSchemaLayoutPreset;
+  intent?: DynamicFormLayoutIntent;
+  lifecycle?: DynamicFormLayoutLifecycle;
+  persistence?: DynamicFormLayoutPersistence;
+  detachBehavior?: DynamicFormLayoutDetachBehavior;
+  schemaOperation?: 'detail' | 'create' | 'update' | 'view';
+  schemaType?: 'request' | 'response';
+  detailSummary?: DynamicFormDetailSummaryPolicy;
+}
+```
+
+The default policy is equivalent to today's behavior:
+
+```ts
+{
+  source: 'authored',
+  lifecycle: 'initial',
+  persistence: 'authorable'
+}
+```
+
+When `source` is `schema`, the form materializes its layout from current schema metadata. In that mode, `FormConfig.sections` are not the source of truth for layout. The host may still pass the parts of `FormConfig` that are not layout-owned, such as actions, messages, behavior, hooks and submit behavior.
+
+The policy should be explicit. A host that wants a read-only generated detail should request `intent: 'detail'`, `preset: 'compactPresentation'`, `source: 'schema'`, `lifecycle: 'live'` and `persistence: 'transient'`. A host that wants a create/edit form should request `intent: 'command'`, `preset: 'groupedCommand'`, the correct request schema operation and transient schema materialization unless the user explicitly detaches the generated layout.
+
+## Presets
+
+### `compactPresentation` with `intent: 'detail'`
+
+Use for read-only detail surfaces.
+
+Expected behavior:
+
+- Group fields by schema `group`.
+- Sort groups and fields by schema `order`.
+- Respect `formHidden`, visibility rules and read-only presentation metadata.
+- Use a consistent label/value hierarchy with distinct label, value, null and helper states.
+- Use chips only for short statuses, categories or boolean/status values.
+- Keep long values readable, wrapping safely without horizontal scroll.
+- Avoid editable controls.
+- Avoid card grids and decorative section containers as the default for operational detail screens.
+- Preserve stable section ids derived from deterministic group keys.
+- In `mode="view"`, activate presentation rendering when the host does not explicitly provide `presentationModeGlobal`; an explicit `false` keeps the same schema in traditional read-only controls.
+- Honor explicit schema `x-ui.width` as 12-column spans by default so migrated operational detail screens can use dense fieldset rows. Preserve full-width rows when width is absent.
+- Let `layoutPolicy.detailSummary.widthPrecedence: 'summary'` make `detailSummary.columns`/`responsiveColumns` override explicit `x-ui.width` only for the compact read-only summary surface.
+- Treat `widthPrecedence: 'summary'` as a curated-summary density tool: long narrative, legal, multiline or audit-heavy values should stay schema-width owned or be moved out of the compact summary through include/exclude policies.
+- Derive compact section header icons from semantic group roles (`identity`, `rules`, `markers`) while keeping field-level icons owned by existing schema metadata.
+- Allow `layoutPolicy.detailSummary` to select/exclude fields and groups, cap the first compact panel with `maxFields`, and sort with field/group priority when the schema publishes summary/detail roles or priorities.
+- Keep excluded summary fields out of generated rows and mark them hidden in generated field metadata for that transient compact surface, without mutating backend schema semantics.
+
+This preset is the platform replacement for local read-only detail sections in migrated screens.
+
+This RFC keeps the existing public `compactPresentation` vocabulary. It does not introduce `compactGroupedDetail` as a second public alias during beta.
+
+Example policy for a master-detail read-only summary:
+
+```ts
+const detailLayoutPolicy: DynamicFormLayoutPolicy = {
+  source: 'schema',
+  intent: 'detail',
+  preset: 'compactPresentation',
+  lifecycle: 'live',
+  persistence: 'transient',
+  schemaType: 'response',
+  detailSummary: {
+    includeGroups: [
+      'Identificacao',
+      'Marcadores',
+      'Aplicabilidade/preenchimento',
+    ],
+    excludeGroups: ['Escopo', 'Quantidades', 'Empresa'],
+    maxFields: 8,
+    fieldPriority: {
+      codigo: 0,
+      mnemonico: 1,
+      ativo: 2,
+    },
+    columns: 3,
+    responsiveColumns: { xs: 1, sm: 1, md: 2, lg: 3, xl: 3 },
+    widthPrecedence: 'summary',
+  },
+};
+```
+
+### `groupedCommand`
+
+Use for create/edit command forms.
+
+Expected behavior:
+
+- Group fields by schema `group`.
+- Sort groups and fields by schema `order`.
+- Respect validators, required state, disabled/read-only state, help text and option metadata.
+- Use `width` metadata plus field archetype rules to create predictable grid spans.
+- Use full-width rows for long text, descriptions, multiline controls and high-density option controls when needed.
+- Use compact clusters for booleans, short enums and small numeric fields.
+- Expand an otherwise orphan medium/wide field to the full row by default, while preserving compact `xs`/`sm` fields. Use `groupedCommand.orphanFieldExpansion = "preserve"` when the empty space is intentional, or `"all"` when compact orphan fields must also fill the row.
+- Keep validation feedback near the field that caused it.
+- Prefer editable controls over presentation roles.
+- Keep command actions visually stable and accessible.
+- Preserve stable section ids derived from deterministic group keys.
+
+This preset is the platform replacement for local create/edit `FormConfig.sections` when the backend command DTO already publishes sufficient `@UISchema` metadata.
+
+### `default`
+
+Preserve current generated behavior for consumers that only need a basic generated layout.
+
+## Materialization Algorithm
+
+The canonical algorithm should be implemented once and reused.
+
+Proposed flow:
+
+1. Normalize schema metadata through the existing schema normalizer.
+2. Map schema fields to `FieldMetadata`.
+3. Filter out fields hidden for the active form surface.
+4. Group fields by `group`, using a stable fallback group when absent.
+5. Sort groups by the minimum field order inside the group.
+6. Sort fields by `order`, then by stable field key.
+7. Convert `width` metadata to responsive spans.
+8. Create stable section ids from normalized group keys.
+9. Emit generated `FormConfig.sections` with provenance metadata indicating schema materialization.
+10. Merge non-layout host config without letting local field semantics override schema-owned field semantics.
+
+For command forms, the materializer must use the request schema for the active operation. For detail/view surfaces, it must use the response schema for the active detail or view surface. The source operation is part of the policy, not an incidental caller detail.
+
+Stable section ids must be deterministic. The implementation must normalize group keys consistently, remove locale-dependent accents for id generation, lower-case, replace non-alphanumeric runs with `-`, and append a deterministic suffix when collisions occur. If only a human label is available, the generated id is stable only relative to that label and must be treated as generated, not as a durable backend identity.
+
+The width mapping should be centralized. A starting policy:
+
+- `xs` and compact controls: 3 or 4 desktop columns, 12 on narrow screens.
+- `sm`: 4 desktop columns, 12 on narrow screens.
+- `md`: 6 desktop columns, 12 on narrow screens.
+- `lg`, `xl`, multiline and full-width controls: 12 columns unless the preset defines a narrower command layout.
+
+The exact mapping can be tuned in implementation, but it must live in the shared materializer and not in host screens.
+
+## Canonical Ownership
+
+`@praxisui/core` owns the pure materialization helper and the minimal structural types required by both Dynamic Form and core surface materializers.
+
+Candidate owner:
+
+```ts
+materializeFormLayoutFromMetadata(fields, policy)
+```
+
+`@praxisui/dynamic-form` owns the component input, runtime behavior, editor integration, generated `FormConfig` rendering and documentation of how `generatedLayoutPreset` relates to schema materialization.
+
+`@praxisui/crud` consumes the public Dynamic Form policy rather than building its own form layout logic.
+
+Core surface action materializers must stop injecting local `config.sections` for generated layouts once the policy is available. They should pass the schema layout policy plus existing `initialValue`, `mode`, `resourceId`, action and submit inputs.
+
+`praxis-metadata-starter` should not change in the first implementation phase unless a real metadata gap is found after using existing `x-ui` fields.
+
+## Runtime Rules
+
+- Authored config keeps precedence by default.
+- Schema-driven runtime layout must be opt-in.
+- Generated schema sections must not be persisted as authored user config by default.
+- Schema-driven `lifecycle: 'live'` layout must use a transient composition path, not the current initial-generation path that immediately persists generated config.
+- If customization is enabled, the user must explicitly detach the generated layout before it becomes authored config.
+- Local config may provide actions, messages, hooks and behavior while schema remains the source of field semantics.
+- Section ids generated from group names must be stable to support rules, tests and authoring references.
+- If a host passes both authored sections and `source: 'schema'`, schema layout wins only when the policy explicitly requests schema materialization. The component should surface a developer warning in non-production builds.
+- The existing reconciler remains responsible for updating schema-owned field metadata in authored configs. Schema-driven live layout is a separate composition step and must not be implemented as a small extension of the existing reconciler because that reconciler intentionally preserves sections.
+
+### Precedence Matrix
+
+| Policy | Persisted config | Input config sections | Result |
+| --- | --- | --- | --- |
+| `source: 'authored'` | present | any | Use persisted or input-first config according to existing persistence strategy. |
+| `source: 'authored'` | absent | present | Use input config and existing reconciliation behavior. |
+| `source: 'schema', persistence: 'transient'` | present | any | Materialize layout from schema; do not persist generated sections; merge only host-owned non-layout config. |
+| `source: 'schema', persistence: 'transient'` | absent | present | Ignore input `sections`; merge host-owned non-layout config; warn in dev when sections were supplied. |
+| `source: 'schema', persistence: 'authorable'` | any | any | Allowed only after explicit detach; generated sections become authored config from that point forward. |
+
+### Ownership Of Config Fragments
+
+- Layout-owned by schema policy: `sections`, rows, columns, items, generated spans and generated section order.
+- Schema-owned by backend metadata: field labels, field type, required state, read-only state, option metadata, validators, visibility metadata, value presentation and domain semantics.
+- Host-owned by local config: actions, messages, hooks, submit behavior, toolbar/header action composition and screen-specific behavior.
+- Mixed or gated by explicit design review: visual blocks, form blocks, custom content projections and any layout item that is not a direct schema field.
+
+## Migration Plan
+
+### Phase 1 - RFC and platform alignment
+
+- Publish this RFC.
+- Confirm the contract with platform maintainers.
+- Do not change runtime behavior yet.
+
+### Phase 2 - Shared materializer
+
+- Add a pure layout materializer in `@praxisui/core`.
+- Move or align duplicated layout logic used by Dynamic Form and surface materializers.
+- Add focused unit tests for grouping, ordering, width mapping, hidden fields and stable ids.
+
+### Phase 3 - Dynamic Form public opt-in
+
+- Add the layout policy input.
+- Keep `generatedLayoutPreset` working for existing consumers.
+- Document the relationship between legacy initial generation and runtime schema materialization.
+- Keep `compactPresentation` as the detail presentation preset and avoid introducing `compactGroupedDetail` as a public alias.
+- Add tests proving authored config remains default.
+
+### Phase 4 - CRUD and surface actions
+
+- Allow CRUD dialog hosts and surface action launchers to pass the policy.
+- Extend the CRUD dialog data contract so `data.action.form` or `data.inputs` can carry the policy to `<praxis-dynamic-form>`.
+- Use `groupedCommand` for create/edit dialogs where schema metadata is sufficient.
+- Use `compactPresentation` with detail intent for read-only detail actions where appropriate.
+- Replace duplicated `SurfaceOpenMaterializerService` local section generation with the shared materializer or by passing the policy downstream.
+
+### Phase 5 - Ergon migration cleanup
+
+- Remove local repeated `FormConfig.sections` from migrated screens that can rely on schema metadata.
+- Keep local config only for screen-specific actions, labels, hooks or behavior that are not field layout.
+- Validate ERGadm00034 as the reference screen before applying the pattern broadly.
+
+## Acceptance Criteria
+
+- A read-only detail surface can render grouped fields from schema metadata without local sections.
+- A create/edit command form can render grouped fields from schema metadata without local sections.
+- Existing consumers using authored `FormConfig.sections` keep the same default behavior.
+- Dynamic Form and surface action materialization share the same grouping and width algorithm.
+- CRUD dialog forms can opt into `groupedCommand`.
+- Generated section ids are stable.
+- Runtime and presentation mode suppress generated or authored sections/rows/columns that do not contain any visible field or visible rich content block; customization mode still exposes empty containers for authoring.
+- Documentation explains when to use authored config versus schema materialization.
+- Ergon reference screens can remove repeated local layout sections without losing grouping quality.
+- Detail layout has consistent label/value hierarchy, readable null and long-value states, no horizontal scroll on narrow viewports and no editable controls.
+- Command layout handles required, invalid, dirty, disabled, read-only and saving states without shifting or hiding actions.
+- Actions distinguish primary, secondary and destructive intent visually and accessibly.
+- Keyboard focus, tab order, accessible names and contrast meet platform accessibility expectations.
+
+## Validation Plan
+
+Implementation should use focused validation:
+
+- Unit tests for the shared materializer.
+- Dynamic Form tests for config precedence, runtime schema policy and preset selection.
+- Dynamic Form tests proving transient schema sections are not persisted unless explicitly detached.
+- CRUD tests for forwarding the policy to Dynamic Form.
+- Surface materializer tests proving generated local `config.sections` are no longer duplicated.
+- Public API review for exported types and barrels.
+- Focused builds for `@praxisui/core`, `@praxisui/dynamic-form` and a direct consumer.
+- AI authoring manifest and capabilities updates with focused specs where applicable.
+- JSON API docs, README, docs manifest and public docs registry review where applicable.
+- Documentation manifest validation where applicable.
+- Visual validation on desktop and narrow viewport for at least one read-only detail and one command form before promoting the pattern as a migration template.
+- ERGadm00034 visual validation with realistic PT-BR data, empty values, long text, small and large groups, invalid required fields, option source loading/empty states, disabled/read-only states, submit/saving state and dialog/drawer narrow viewport.
+
+Broad workspace builds are not required for the RFC-only step.
+
+## Implementation Notes
+
+- The public input is `layoutPolicy`.
+- `layoutPolicy.source = "schema"` is opt-in. CRUD dialogs do not enable it implicitly.
+- Generated schema sections are transient and are not persisted by the runtime.
+- Host non-layout config has precedence over persisted non-layout config when both exist.
+- Persisted and host-authored `sections` are ignored in schema layout mode.
+- `schemaType` and `schemaOperation` are validated against `schemaUrl` when the URL declares `schemaType` and `operation`.
+- Stable section ids are based on group tokens, not group index.
+
+## Open Questions
+
+- Should operation-level schema metadata eventually declare preferred layout preset for `create`, `update`, `detail` and `view` surfaces after the frontend policy proves stable?
+- Should group icons remain host-authored, come from a platform icon policy, or eventually become backend metadata after a real gap is proven?
+- Should visual blocks participate in schema materialization, or remain explicitly authored only?
+
+## Risks
+
+- Changing defaults would break existing authored layouts. The implementation must avoid this.
+- Duplicating layout algorithms would recreate the current problem in another layer.
+- Treating local host config as field semantics would weaken the backend DTO contract.
+- Adding new metadata too early would expand the public contract before proving existing `x-ui` fields are insufficient.
+- Persisting transient generated layouts by accident would turn schema materialization into silent authored config.
+- Using the wrong operation schema could leak detail-only fields into create/edit forms.
+- Promoting ERGadm00034 as a template before visual validation could institutionalize poor layouts across hundreds of screens.
+
+## Relationship To Ergon Migration
+
+The immediate trigger was ERGadm00034, but the problem already appears across read-only and editable forms in the Ergon migration.
+
+Ergon may continue using local configs as a temporary bridge, but the intended platform direction is to remove repeated `FormConfig.sections` when the backend DTO already publishes complete field metadata.
+
+## ErgonX Migration Playbook
+
+Use this section as the operational checklist before promoting a migrated Ergon screen as a reusable example.
+
+### 1. Prove the DTO/schema is ready
+
+The backend DTO and `/schemas/filtered` response are the source of truth for field semantics. Before a screen uses schema-driven layout, confirm that every visible field has:
+
+- a business label in the correct language;
+- a stable `group` and `order` that match the real business grouping, not only the legacy visual row;
+- an appropriate `controlType`, read-only/required state, validators and option metadata;
+- domain-oriented `helpText` only when the user needs decision support;
+- `width` metadata when the field should share a dense row with related fields;
+- resolved display/value presentation for coded values when the user should not see only raw codes.
+
+Do not compensate for weak DTO metadata with local Angular labels, local help copy, hardcoded option labels, or local concatenation of code and description. If the schema is weak, return to DTO/schema hardening and add schema/OpenAPI tests there.
+
+### 2. Choose the layout policy by surface
+
+Use `layoutPolicy` only when schema metadata is complete enough to generate the layout.
+
+| Surface | Recommended policy | Schema source | Notes |
+| --- | --- | --- | --- |
+| Read-only detail panel | `source: "schema"`, `intent: "detail"`, `preset: "compactPresentation"`, `persistence: "transient"`, optional `detailSummary` | response schema | Use for legacy detail blocks such as identification, rules and markers. |
+| Create/edit drawer or dialog | `source: "schema"`, `intent: "command"`, `preset: "groupedCommand"`, `persistence: "transient"` | request schema | Use only after command DTO metadata and write API gates are ready. |
+| Custom visual composition | `source: "authored"` | authored config | Use for genuinely custom content, embedded child resources or non-field visual blocks. |
+| Transitional migration | authored sections plus schema-owned field metadata | response/request schema | Acceptable while DTO grouping is being corrected; document the temporary debt. |
+
+For command forms, `schemaUrl` must identify the request operation. A create/edit form rendered from a response schema is a contract defect because it can expose read-only, derived or detail-only fields as editable.
+
+### 3. Apply the corporate help policy
+
+Large enterprise forms should not render every DTO description inline. Inline help is useful for short guidance, but dense groups become noisy when every toggle, select and date field owns multiple lines of explanatory text.
+
+Recommended default for Ergon-style command drawers:
+
+```ts
+helpPresentation: {
+  display: 'auto',
+  inlineMaxLength: 48,
+  preferPopoverForControls: ['select', 'checkbox', 'toggle', 'date', 'datepicker', 'numeric'],
+}
+```
+
+Use field-level `helpDisplay` only when the DTO has a specific need:
+
+- `inline`: short mandatory operational clarification that should always be visible;
+- `popover`: longer guidance, policy explanation or rare decision support;
+- `hidden`: text not useful in the current UI surface;
+- `auto`: allow the runtime threshold to decide.
+
+Validation errors are not help text. They remain near the field and must not be moved into the help affordance.
+
+### 4. Keep field icons intentional
+
+For dense command forms, prefer `fieldIconPolicy: "presentation-only"` unless icons are required for recognition. This keeps schema icon metadata useful in read-only presentation while avoiding visual clutter inside every input.
+
+Use `fieldIconPolicy: "all"` only when icons are part of the field affordance or when a migrated screen has explicit visual requirements. Use `none` only for surfaces where icons would compete with compact operational scanning.
+
+### 5. Preserve Praxis actions and loading patterns
+
+Migrated screens should use native Praxis action discovery, surfaces and capabilities for row, collection and global actions. Do not implement an Ergon-local action launcher when the backend publishes actions or surfaces that Praxis can discover.
+
+For loading states, avoid whole-page flicker. Prefer stable shells, table/detail skeletons or top progress indicators that preserve layout while data refreshes. A migration example should prove that refresh, filter, pagination and row selection do not blank the whole screen.
+
+### 6. Visual QA gate for a reference screen
+
+Before using a screen as a migration template, run at least one desktop browser validation with realistic PT-BR data and capture:
+
+- initial loading, loaded, empty and error states;
+- filter/search interaction and pagination;
+- row selection and detail update without page flicker;
+- create/edit drawer with short and long help text;
+- required, invalid, dirty, disabled, read-only and saving states;
+- keyboard tab order, focus visibility, accessible names and contrast;
+- long labels/values without overlap or horizontal scroll in the target desktop viewport.
+
+Mobile can be deferred when the product decision says it is not priority, but narrow drawer behavior still needs enough validation to avoid broken desktop split-screen usage.
+
+### 7. Handoff artifact for each Ergon screen
+
+Each migrated screen should record the following in its Ergon migration folder:
+
+- DTO/schema readiness result and unresolved semantic gaps;
+- chosen `layoutPolicy`, `helpPresentation` and `fieldIconPolicy`;
+- actions consumed from native Praxis discovery and any missing backend capability;
+- visual QA evidence and known accepted deviations;
+- temporary authored config sections that should be removed after DTO/schema hardening.
+
+This keeps ERGadm00034 useful as a repeatable migration reference instead of a one-off visual implementation.