Praxis Form Layout Canvas
This praxis-form-* skill family is the canonical Codex skill surface for @praxisui/dynamic-form and projects/praxis-dynamic-form; do not create parallel praxis-dynamic-form-* guidance unless this family cannot express a proven contract gap.
Use this skill for Dynamic Form layout, visual blocks, canvas, and schema-driven layout materialization. Layout is a governed projection of field metadata and authoring config; it must not become a second source of business semantics.
Source Audit
Inspect the affected source:
projects/praxis-dynamic-form/AGENTS.mdprojects/praxis-dynamic-form/src/lib/dynamic-form-editor-document.model.tsprojects/praxis-dynamic-form/src/lib/praxis-dynamic-form-widget-config-editor.tsprojects/praxis-dynamic-form/src/lib/filter-form/praxis-filter-form-widget-config-editor.tsprojects/praxis-dynamic-form/src/lib/ai/praxis-dynamic-form-authoring-manifest.tsprojects/praxis-dynamic-form/src/lib/ai/dynamic-form-rule-authoring-context.tsprojects/praxis-dynamic-form/src/lib/layout-editor/**projects/praxis-dynamic-form/src/lib/canvas/**projects/praxis-dynamic-form/src/lib/services/dynamic-form-layout.service.tsprojects/praxis-dynamic-form/src/lib/services/form-layout.service.tsprojects/praxis-dynamic-form/src/lib/services/form-config.service.tsprojects/praxis-dynamic-form/src/lib/utils/normalize-form-config.tsprojects/praxis-dynamic-form/src/lib/utils/section-header.utils.tsprojects/praxis-dynamic-form/src/lib/utils/visual-block-rule-content-overrides.util.tsprojects/praxis-dynamic-form/docs/schema-driven-layout-materialization-rfc.mdprojects/praxis-dynamic-form/docs/layout-items-visual-blocks.mdprojects/praxis-dynamic-form/docs/dynamic-form-authoring-document-semantics.mdprojects/praxis-dynamic-form/docs/dynamic-form-rules-authoring-plan.mdprojects/praxis-dynamic-form/docs/dynamic-form-visual-builder-parity-audit.mdprojects/praxis-dynamic-form/docs/hot-metadata-updates.md- related JSON API docs such as
layout-editor/praxis-layout-editor.json-api.mdandconfig-editor/praxis-dynamic-form-config-editor.json-api.md
Inspect @praxisui/core form layout models when changing FormConfig, FormLayout, FormColumn.items, visual block rules, or DynamicFormLayoutPolicy.
Concrete @praxisui/core files to inspect for layout ownership and schema materialization:
projects/praxis-core/src/lib/models/form/form-config.model.tsprojects/praxis-core/src/lib/models/form/form-config.model.spec.tsprojects/praxis-core/src/lib/models/form/form-layout-items.model.tsprojects/praxis-core/src/lib/helpers/ensure-ids.helper.tsprojects/praxis-core/src/lib/helpers/ensure-ids.helper.spec.tsprojects/praxis-core/src/lib/helpers/form-layout-materializer.tsprojects/praxis-core/src/lib/helpers/form-layout-materializer.spec.tsprojects/praxis-core/src/lib/services/surface-open-materializer.service.tsprojects/praxis-core/src/lib/services/surface-open-materializer.service.spec.tsprojects/praxis-core/src/lib/widgets/dynamic-widget-loader.directive.tsprojects/praxis-core/src/lib/widgets/dynamic-widget-loader.directive.spec.ts
Canonical Layout Rules
FormColumn.items[]is the canonical order for fields and visual blocks inside a column.fields[]is only a compatibility/migration projection.- API fields remain in
fieldMetadata[]and appear in layout asitems[]withkind: "field". - Visual blocks are
items[]withkind: "richContent"and a validRichContentDocument. - Visual blocks do not create
FormControl, do not enterfieldMetadata[], and do not enter submit payloads. - Presets are authoring shortcuts only; persisted runtime semantics are still rich content documents.
DynamicFormAuthoringDocumentis the complete authoring snapshot. Do not persist runtime/discovery-only values such as hostschemaUrl,submitUrl, orsubmitMethodinside authoring bindings.- Numeric layout authoring must match Core's integer grid domains and the runtime utility classes. Test fractional, non-finite, out-of-range, and inherited values through the column editor and JSON apply path. Runtime recovery must not silently rewrite the authored document; invalid drafts must block Apply/Save and identify the field and breakpoint. Revalidate JSON at Apply time, not only after a debounced edit.
- Row occupancy is authoring guidance, not a requirement to fill 12 units. Include responsive offsets, exclude breakpoint-hidden columns and columns with only statically hidden fields, and preserve intentional whitespace. Empty draft columns and visual blocks still participate. Suggestions must remain explicit, use the same occupancy calculation and never rewrite metadata or layout on inspection. Do not present this static guidance as a simulation of record-dependent rules.
- Visibility commands must preserve geometry, ordering and style. Before changing smaller breakpoints, resolve inheritance so that an action scoped to them does not unintentionally hide larger breakpoints. Test presets against a customized column, not only default full-width fixtures.
- Layout editor, canvas editor, config editor, JSON editor, and AI authoring must round-trip the same
FormConfig.sections[].rows[].columns[].items[]semantics. - For individual field movement, expose and validate the existing selected-field Move field dialog as a keyboard-accessible alternative to drag. Choose section/row/column and position through
moveLayoutItemById; preserve item IDs, metadata, mixed-item order and empty containers. The destination column owns geometry/style. Opening/cancelling must not dirty the document; reject an obsolete destination snapshot and move focus to the selected field after confirmation. Validate Apply → Save/close → Save page → reload separately, then restore the baseline when simulating on a user composition. - Destination summaries must derive from canonical
items[]and metadata labels, preserve stable IDs as option values, account for visual blocks/empty destinations, and bound long lists without treating static summaries as visibility/permission simulation. - For visual-block destinations, reuse the internal
visual-block-label.tsextraction shared with the row editor. Bound plain-text previews and distinguish identical/empty blocks by original column item position (including the moving field); never use preview text or position as persisted identity, evaluate bindings/HTML, or infer a preset from CSS classes. Validate duplicate text with distinct IDs and multiline options in a narrow dialog. - Visual-block preview shortcuts must handle Enter/Space only when the preview itself is the event target. Nested native buttons own their activation: do not open the content editor or prevent Space on their behalf. Validate menu open/remove by keyboard, preview edit/select shortcuts, unchanged document on inspection, and add/remove returning to a clean draft. After insertion/reorder/column movement, continue focus on the selected block; after removal, select/focus its preserved column. Guard deferred focus against a newer selection. Test through a parent that clones emitted config: object-reference equality alone must not suppress valid focus restoration.
- Scope
DynamicFormLayoutServiceto eachLayoutEditorComponentdraft: rootchanges$is observed by live forms, so using that root instance for draft operations bypasses Apply and leaks cancelled changes into runtime. Validate both same-page discard/reopen and explicit Apply; a reload or an unchanged HTTP payload alone cannot prove draft isolation. - Section quick rename must reuse
FormSection.titleand the existing update event, preserve IDs/structure/appearance, reject blank names, and support Enter/Escape with focus return. Empty-section guidance should invoke the existing add-row command with translated copy and host tokens. When validating section removal, check that eligible unplaced API fields return to the palette without deleting metadata, then discard/reopen on the same page; visual blocks belong to the removed structure and are not recoverable API fields. Tests of output-driven operations must reproduce the owning editor's output-to-input binding. - Section spacing is
FormSection.gapBottom, the space after the whole section, not a column gap or editor density. InspectLayoutEditorComponent.canApplyAll/applyGapToAllanddocs/section-spacing-authoring-2026-09-08.md: fill only absent/null values, preserve explicit zero and other authored gaps, reject negative/non-finite proposals, and emit nothing for a proposal change or an ineligible document. Do not generate or consultgapCustomizedas a second source of eligibility. Validate through the owning output-to-input flow, including same-page discard/reopen; a draft-only check does not prove persisted runtime spacing. - Rule targets may include visual blocks, sections, rows, columns, actions, and fields, but visual-block rules remain visual-only and must not mutate domain payload semantics.
- Normalize IDs and legacy layout shape through the shared core helpers.
ensureIds(...)must preserve rich content items, normalize legacyfields[]into canonicalitems[], and keepfields[]synchronized as a field-only projection. - Use
getFormColumnFieldNames(...)/layout item helpers instead of readingcolumn.fieldsdirectly when code must understand current field order. - Surface materialization can project read data into Dynamic Form
initialValueand a transient schemalayoutPolicy; that is runtime materialization, not authored localFormConfig.sections. - Dynamic widget loading must pass
layoutPolicyand related runtime inputs through to Dynamic Form instead of flattening them into host-specific config. - "Add API field" means place an existing
fieldMetadata[].nameinto canonicalitems[](kind: "field") and preservefieldMetadata[]. It is not permission to create DTO/schema fields, clone metadata, or patch backend semantics from the canvas. - Audit the existing column-menu Add API field path before inventing another placement contract. Explain it in palette/empty-column copy, validate Enter/arrow navigation, and focus the inserted field after rendering: the old menu trigger may be destroyed by the layout update. Tab must continue into the field controls; reject already placed/unknown candidates and verify discard/reopen returns the field to the available catalogue.
- Local fields are a separate authoring path and must carry safe local semantics such as
source: "local",transient: true, andsubmitPolicy: "omit"unless a submit contract explicitly owns them. Do not use a local field to stand in for missing backend metadata.
Do not represent visual guidance as local fields, transient fields, DTO fields, or backend metadata unless it is genuinely domain data.
Schema-Driven Layout Policy
Treat schema-driven layout as opt-in and explicit:
- default remains authored config.
layoutPolicy.source = "schema"makes schema metadata the layout source for that runtime surface.compactPresentationwithintent: "detail"is for read-only detail summaries.groupedCommandis for create/edit command forms.groupedCommand.partialRowStrategyis the canonical policy for incomplete rows. Defaultpreservekeeps authored/schema widths unchanged.fill-compatiblemay widen only eligible, known, non-compact controls to the next supported grid span (3,4,6,8,12) so the visible row fills 12 columns; it must not rewrite the underlying field width contract.- Resolve
fill-compatibleindependently for each visible row and each active responsive breakpoint. Hidden fields change row membership, so a desktop projection cannot be reused for tablet or narrow layouts. Dynamic Form owns this runtime projection and should use its named form-row container rather than global viewport guesses. - Put
container-type/container-nameon an element with measurable inline size that actually contains the responsive columns, such as.form-row.grid-12. Never name adisplay: contentswrapper as the query container: its zero-size box leaves responsive span classes present in the DOM but permanently inactive. - authored
FormConfig.sectionsmust not be silently overwritten unless policy says schema owns layout. - non-layout config, such as actions, messages, hooks, behavior, submit behavior, and hints, can still come from authored config.
DynamicFormLayoutPolicy.schemaTypeandschemaOperationmust agree with the schema URL when declared. Detail/read-only surfaces use response schema; create/edit command surfaces use request schema.SurfaceOpenMaterializerServicemay default read projections tocompactPresentation+schemaType: "response"and related command forms togroupedCommand+schemaType: "request". Fix this materializer or discovery metadata before copying local sections into consumers.- With
layoutPolicy.source="schema"andpersistence="transient", generated sections, rows, columns,items[], spans, and section order are runtime projections. Opening the editor or Settings Panel must not convert them into authored config unless an explicit detach/authorable flow is chosen.
Classify repeated local section configs as ja-suportado-mal-nomeado-ou-mal-materializado or suportado-parcialmente before proposing backend metadata changes. The backend may already publish group, order, width, labels, help text, read-only hints, and presentation metadata.
Grouped command context
groupedCommand.contextFields preserves declared hidden metadata fields in the form
and submission while excluding them from interactive layout. Inspect Core's
form-layout-materializer.ts and tests for this split. Selection IDs and expected
versions materialized by resource-action discovery must survive; do not expose them
as editable fields or restore them with a host submit hook. Verify metadata retention,
layout omission and the actual request payload, including hidden context fields.
Inventory Before New Contract
ja-suportado-so-ux:items[], layout policy, visual block, or schema metadata already supports the need, but the canvas/editor does not expose the workflow clearly.ja-suportado-mal-nomeado-ou-mal-materializado: localsections,fields[], visual seeds, labels, or presets duplicate semantics already present infieldMetadata[],items[], schema metadata, orDynamicFormAuthoringDocument.suportado-parcialmente: runtime layout works, but editor round-trip, canvas state, JSON editor, AI manifest, visual builder parity, docs, responsive UX, or submit-boundary tests are incomplete.lacuna-real-de-contrato: noFormConfig,FormLayout,FormColumn.items,DynamicFormLayoutPolicy, authoring document, schema metadata, or visual-block contract can represent the layout decision.
Only lacuna-real-de-contrato justifies a new public layout contract. Otherwise, repair the missing projection, editor affordance, validation, or documentation in the existing chain.
AI/Canvas Rules
- AI and canvas authoring must resolve the semantic layout operation first: add API field, reorder field, add visual block, move section/row/column, apply preset, materialize schema layout, or configure compact/grouped presentation.
- Do not route layout intent primarily by text labels, section names, CSS classes, or visual position guesses. Use canonical field names, layout item IDs,
kind, authoring manifest operations, and schema metadata as grounding. - Canvas state may store selection, focus, draft edits, drag state, or diagnostics. It must not become the owner of field order, field semantics, visual block document shape, submit payload, or schema-derived layout policy.
- When schema owns layout, generated sections are transient. Do not persist generated schema sections back into authored config unless the product explicitly supports an authoring conversion flow.
- When authored config owns layout, schema metadata can enrich labels, help, width, group, and read-only hints, but it must not silently overwrite authored structure.
- For Ergon or other migration consumers, treat repeated hand-authored sections as transitional debt when DTO/schema metadata can own grouping/order. Document consumer work separately instead of hardcoding Ergon-specific shortcuts into Praxis.
- For Ergon-style operational screens, prefer schema-owned grouping/order/width for scalable detail and command surfaces. If the layout only looks correct after local sections, local labels, duplicated visual seeds, or fake hidden fields, route the gap to metadata/schema materialization or consumer follow-up instead of institutionalizing that screen as a Praxis layout pattern.
Validation
- Layout editor:
npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/layout-editor/layout-editor.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/layout-editor/field-configurator.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/layout-editor/row-configurator.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/layout-editor/section-configurator.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/layout-editor/apply-section-preset.util.spec.ts --include=projects/praxis-dynamic-form/src/lib/layout-editor/visual-block-presets.spec.ts - Canvas editor:
npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/canvas/components/section-editor/section-editor.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/canvas/components/row-editor/row-editor.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/canvas/components/column-editor/column-editor.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/canvas/components/canvas-toolbar/canvas-toolbar.component.spec.ts - Schema/layout services:
npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/services/dynamic-form-layout.service.spec.ts --include=projects/praxis-dynamic-form/src/lib/services/form-layout.service.spec.ts --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.layout-policy.spec.ts - Core layout contracts:
npx ng test praxis-core --watch=false --progress=false --include=projects/praxis-core/src/lib/models/form/form-config.model.spec.ts --include=projects/praxis-core/src/lib/helpers/ensure-ids.helper.spec.ts --include=projects/praxis-core/src/lib/helpers/form-layout-materializer.spec.ts - Surface materialization:
npx ng test praxis-core --watch=false --progress=false --include=projects/praxis-core/src/lib/services/surface-open-materializer.service.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-widget-loader.directive.spec.ts - Authoring document/config editor:
npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form-authoring-protocol.spec.ts --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form-widget-config-editor.spec.ts --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.config-editor.spec.ts --include=projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.spec.ts - AI/rule layout authoring:
npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/ai/praxis-dynamic-form-authoring-manifest.spec.ts --include=projects/praxis-dynamic-form/src/lib/ai/dynamic-form-rule-authoring-context.spec.ts --include=projects/praxis-dynamic-form/src/lib/ai/dynamic-form-agentic-authoring-turn-flow.spec.ts --include=projects/praxis-dynamic-form/src/lib/utils/rule-authoring-diagnostics.spec.ts - Visual blocks:
npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/utils/visual-block-rule-content-overrides.util.spec.ts --include=projects/praxis-dynamic-form/src/lib/utils/rule-converters.spec.ts - Submit boundary: add
normalize-submit-payload.spec.tswhen layout/visual-block changes could affect payload construction. - Browser layout: Playwrights such as
projects/praxis-dynamic-form/test-dev/e2e/visual-blocks-responsive-ux.playwright.spec.ts,projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-layout.playwright.spec.ts, and narrow viewport checks when UI layout changed. - Grouped-command partial-row changes must include core materializer tests for
preserve, eligible widening, fixed/compact exclusions, and deterministic spans; Dynamic Form DOM/diagnostic tests; andschema-layout-policy-demo.playwright.spec.tsgeometry at desktop, tablet, and narrow widths. npm run build:praxis-dynamic-formwhen public exports, layout models, config editor, runtime layout services, or generated presets change.npm run validate:published-doc-assetsandnpm run generate:registry:ingestionwhen public docs, JSON API docs, or generated AI/registry surfaces change.
Companion Skills
- Use
praxis-form-schema-runtime-modeswhenlayoutPolicy, generated presets, or presentation mode depend on schema-driven create/edit/view runtime. - Use
praxis-form-runtime-submitwhen layout affects runtime form construction or submit payload boundaries. - Use
praxis-form-authoring-settingswhen layout is edited through config editor, Settings Panel, JSON editor, or apply/save/reset. - Use
praxis-form-editor-document-roundtripwhen layout changes must persist throughDynamicFormAuthoringDocumentand reopen exactly. - Use
praxis-form-ai-rules-validationwhen layout or visual blocks are authorable by AI/rules. - Use
praxis-ui-product-designfor visual hierarchy, density, accessibility, and screenshot validation. - Use
praxis-dynamic-fields-editorialwhen field discovery or editor metadata coverage changes.