Praxis Core Surface Materialization
Use this skill for the first implementation step that turns canonical backend resource metadata into surface.open payloads and renderable Angular widgets.
This is a materialization skill, not a backend contract skill. praxis-metadata-starter owns resources, /schemas/filtered, /schemas/actions, /schemas/surfaces, capabilities, HATEOAS links, x-ui, and operation semantics. @praxisui/core consumes those contracts and projects them into stable Angular runtime payloads.
Source Audit
Inspect the affected source before changing code or guidance:
projects/praxis-core/AGENTS.mdprojects/praxis-core/src/public-api.tswhen surface payload models, adapters, materializers, related-resource outlets, action editors, presets, or providers are exported or public consumption changesprojects/praxis-core/docs/schema-flow.mdprojects/praxis-core/docs/rfc-surface-open.mdprojects/praxis-core/src/lib/models/resource-discovery.model.tsprojects/praxis-core/src/lib/models/surface-action.model.tsprojects/praxis-core/src/lib/services/resource-discovery.service.tsprojects/praxis-core/src/lib/services/resource-record-open.service.tsprojects/praxis-core/src/lib/services/resource-action-open-adapter.service.tsprojects/praxis-core/src/lib/services/resource-surface-open-adapter.service.tsprojects/praxis-core/src/lib/services/surface-open-materializer.service.tsprojects/praxis-core/src/lib/services/related-resource-surface-resolver.service.tsprojects/praxis-core/src/lib/surfaces/praxis-related-resource-outlet.component.tsprojects/praxis-core/src/lib/actions/editors/surface-open-action-editor.component.tsprojects/praxis-core/src/lib/actions/surface-open-presets.ts- focused specs for the touched adapter/materializer/resolver and the direct consumer.
Canonical Flow
Use the hypermedia-first path:
- Start from a
RestApiResponse<T>or explicit resource discovery context. - Resolve
_links.surfaces,_links.actions, or_links.capabilitieswithResourceDiscoveryService. - Preserve
resourceKeyas semantic identity andresourcePathas operational address. - Convert catalog items with the core adapter:
ResourceSurfaceOpenAdapterServicefor surfaces.ResourceActionOpenAdapterServicefor typed workflow actions.RelatedResourceSurfaceResolverServicefor child resource tables.
- Execute through
GlobalActionRef { actionId: 'surface.open', payload }. - Let
SurfaceOpenMaterializerServicehydrate item read projections when the surface response must become a renderable widget.
Do not reconstruct resource keys, schema URLs, submit URLs, read URLs, or action ids from labels, DOM text, route fragments, endpoint naming conventions, or command strings.
For a governed nominal row that references a record owned by another resource,
preserve only ResourceRecordOpenRef { sourceIdentityField, target: { resourceKey, surfaceId } }. On each click, use ResourceRecordOpenService to:
- fetch the current principal's aggregate target catalog and accept only the
exact available surface or
resource-context-required; - read the declared source identity field without falling back to
item.id; - load the target item through the catalog
resourcePath; - follow the item's
_links.surfacesrelation; - require the exact
ITEMsurface withavailability.allowed=true; - materialize with
ResourceSurfaceOpenAdapterServiceand execute the result assurface.open.
Fail closed on identity, catalog, HATEOAS, path, or availability divergence.
Keep detailed diagnostics internal and show a safe localized failure. Do not
persist copied paths, schemas, widgets, presentation, a prebuilt payload, or an
authoring-time availability decision inside recordOpen. Preserve this field
through component and Page Builder round-trips, but do not expose it as a
free-form component editor or AI-manifest choice.
Legacy or AI-created row actions may sometimes arrive as surface.open,
dynamicPage.surface.open, or an unbound action label from older persisted table
configs. Treat that only as a compatibility grounding step into an already
declared record surface/capability context. Once the surface is identified, stop
using the legacy action shape and rematerialize through ResourceSurfaceOpenAdapterService
and GlobalActionRef { actionId: 'surface.open', payload }. Do not generalize
label matching into a new authoring route for choosing surfaces.
Materialization Rules
resourceKeyidentifies the resource semantically in action/surface/capability catalogs.resourcePathremains the base operational resource path. Do not append/api,/filter,/{id}, schema paths, action paths, or query strings to it.SurfaceCatalogItem.pathplusmethodbecomessubmitUrl/submitMethodonly for writable form surfaces.ActionCatalogItem.requestSchemaUrlbecomes dynamic-formschemaUrl;ActionCatalogItem.path/methodbecomes submit target.- Item-scoped actions and surfaces require either an explicit
resourceIdor a binding such aspayload.row.id. - Governed nominal-row opening must re-resolve the current principal and record context at execution time; authoring-time catalogs are grounding evidence, not runtime authority.
- Collection
VIEWandREAD_PROJECTIONsurfaces materialize topraxis-table; itemFORM,PARTIAL_FORM,VIEW, andREAD_PROJECTIONsurfaces materialize topraxis-dynamic-form. - Related resources should use
surface.relatedResourceand resolver output rather than host-local parent/child filter conventions. Keep the contextual collection read target and child command target distinct:SurfaceCatalogItem.pathmaterializes the parent-scopedreadUrl, whilerelatedResource.childResourcePathis the base for create, update, and delete. DerivechildParentFieldfrom the selected parent for create, expose only operations declared inchildOperations, and resolve only the declaredparentIdPathVariable. If the child path is absent, unsafe, or retains any unresolved placeholder, remove executable child actions and report fail-closed diagnostics; never reuse the contextualreadUrlas a mutation fallback. - Availability, denied operations, and permission-limited states must come from capabilities, catalog availability, or HATEOAS links, not frontend guesses.
- Preserve the materialization provenance carried in
payload.context.resource,payload.context.surface, andpayload.context.action. Consumers may display titles, subtitles, icons, shell state, and hydrated widget inputs, but must not replace the context with labels, generated ids, component names, selected row text, or host-local route state. - Consumer events such as table
recordSurfaceOpen,dynamicPage.surface.open, selected row snapshots, and feedback messages are runtime telemetry and host orchestration. They may carryselectedRow,selectedRows,selectedCount, table id, and error diagnostics, but the surface payload itself must continue to come from the core adapter/materializer and its backend catalog provenance. SurfaceOpenPayload.onResultandsurface.resultare declarative continuation hooks for a governed result. They do not make the surface the primary owner of business state, resource identity, permission, or semantic decision. Route returned results throughGlobalActionRef, composition links, or backend-confirmed actions; do not mutate host state from a surface result by local command parsing.SurfaceOpenMaterializerServicemay hydrate read projections and add materialization diagnostics such asreadUrl,dataShape,recordCount, and presentation mode. Treat those as derived runtime evidence. Do not use a successful hydration, fallback form projection, or unavailable data diagnostic as proof that the backend authorized an edit, action, or alternate resource target.- Treat materialized
widget.inputs,bindingOrder, hydrated rows, fallback projections, and diagnostics as derived runtime payload for the opened surface. They are not a Page Builderdefinition.inputsauthoring source, not a child component config editor result, and not a replacement for metadata/HATEOAS/capability catalogs. If a consumer wants to persist a reusable page or widget configuration, persist only the owning component's canonical config or the authoredGlobalActionRef/composition link that can rematerialize the surface from canonical metadata.
Aderence Inventory
Before adding a new adapter, field, input, or public type, classify the need:
ja-suportado-so-ux: catalog/capability/link already exists; editor or host does not expose it.ja-suportado-mal-nomeado-ou-mal-materializado: host manually builds URLs, strings, legacysurface.openactions, or row-action label bindings that should ground to declared surfaces and then use core adapters.suportado-parcialmente: core can express the surface, but materializer, binding, diagnostics, docs, or consumer proof is incomplete.lacuna-real-de-contrato: no backend catalog/capability/link or core payload field can express the operation.
Only lacuna-real-de-contrato justifies changing a canonical backend or public core contract.
Validation
For registered widget input controls, audit ComponentDocMeta.inputs.type before
adding an editor contract. Finite literal unions and nullable booleans must preserve
their scalar types through select, apply, JSON and reopen. Distinguish omission from
explicit null/false; preserve and flag out-of-catalog persisted values until an
explicit replacement. Do not classify quoted enum content such as input-first as
an object/JSON type. Include long metadata descriptions in screenshot checks so
helper text neither overlaps the next row nor stretches adjacent controls.
Before adding input-group contracts, inspect existing presets, explicit authored inputs and exact binding targets. Disclosure must not emit or persist changes; keep control membership stable during same-widget host echoes so edits cannot move the focused control. Preserve collapsed values and invalid drafts. Resolve copy through the existing editorial registry: the component owner registers localized labels/help, while the consumer merges copy only onto raw declarations, never editorial types/defaults or undeclared inputs. Prove locale and host-copy overrides with the real owner provider, plus a no-change disclosure interaction.
For raw Surface JSON drafts, bind validationChange into the owning editor's
aggregate validity and count invalid-only edits as dirty. A valid last emitted
payload does not prove that visible raw text is valid. Preserve draft text/errors
across parent echoes and tab navigation; an authoritative field replacement may
replace its stale draft. Child teardown releases its validity contribution, so
handle discard or preserve the child before switching/removing it. Prove independent
errors, correction, blocked Apply/Save, and invalid-only cancellation through the
actual consumer. Audit every consumer separately; Core support does not certify
that Form, List, Table and connection editors all propagate the state.
Use mounted editor identity for independent validation contributions; mutable
action labels or indices are not stable identities. Explicit Reset/Cancel can call
discardInvalidDrafts() to clear raw errors without emitting a payload. A
validation-only notification must not rewrite another invalid JSON editor. Verify
deferred document validation also respects pending raw errors, and exercise the
mounted child when opening a connection transaction to catch teardown losses.
Use the smallest proof that exercises the changed flow:
- discovery plus adapter/materializer flow:
npm run test:core -- --include=projects/praxis-core/src/lib/services/resource-discovery.service.spec.ts --include=projects/praxis-core/src/lib/services/resource-action-open-adapter.service.spec.ts --include=projects/praxis-core/src/lib/services/resource-surface-open-adapter.service.spec.ts --include=projects/praxis-core/src/lib/services/surface-open-materializer.service.spec.ts
- governed nominal-row opening plus list and Page Builder preservation:
npm run test:core -- --include=projects/praxis-core/src/lib/services/resource-record-open.service.spec.ts --include=projects/praxis-core/src/lib/services/resource-discovery.service.spec.ts --include=projects/praxis-core/src/lib/services/resource-surface-open-adapter.service.spec.ts
npm run ng -- test praxis-list --watch=false --progress=false --include=projects/praxis-list/src/lib/components/praxis-list.component.spec.ts --include=projects/praxis-list/src/lib/editors/list-config-editor.component.spec.ts --include=projects/praxis-list/src/lib/list-editor-capability.spec.ts --include=projects/praxis-list/src/lib/ai/praxis-list-authoring-manifest.spec.ts
npm run ng -- test praxis-page-builder --watch=false --progress=false --include=projects/praxis-page-builder/src/lib/ai/page-builder-ui-composition-plan.spec.ts
- related-resource surfaces, outlet registration, and command-path materialization:
npm run test:core -- --include=projects/praxis-core/src/lib/services/related-resource-surface-resolver.service.spec.ts --include=projects/praxis-core/src/lib/surfaces/praxis-related-resource-outlet.component.spec.ts --include=projects/praxis-core/src/lib/services/surface-outlet-registry.service.spec.ts --include=projects/praxis-core/src/lib/services/surface-open-materializer.service.spec.ts
For writable related resources, assert both halves explicitly: GET remains on the parent-scoped surface path, POST/PUT/DELETE use the canonical child path, create derives the parent field, and an unresolved child placeholder produces no toolbar/action metadata.
surface.openauthoring/editor presets:
npm run test:core -- --include=projects/praxis-core/src/lib/actions/editors/surface-open-action-editor.component.spec.ts --include=projects/praxis-core/src/lib/actions/surface-open-presets.spec.ts
- dynamic widget page surface materialization:
npm run test:core -- --include=projects/praxis-core/src/lib/widgets/dynamic-widget-page-record-surface-open.spec.ts
- CRUD consumer materialization when
schemaUrl,readUrl,submitUrl,submitMethod, availability, or adapter payload handoff changes:
npm run ng -- test praxis-crud --watch=false --progress=false --include=projects/praxis-crud/src/lib/praxis-crud.component.spec.ts --include=projects/praxis-crud/src/lib/crud-launcher.service.spec.ts --include=projects/praxis-crud/src/lib/dynamic-form-dialog-host.component.spec.ts
- direct visual/runtime E2E proof only when rendered table/form/list behavior changes:
npx playwright test projects/praxis-table/test-dev/e2e/surface-open-funcionarios-demo.playwright.spec.ts
npx playwright test projects/praxis-dynamic-form/test-dev/e2e/surface-open-form-demo.playwright.spec.ts
npx playwright test projects/praxis-list/test-dev/e2e/surface-open-list-demo.playwright.spec.ts
For public or cross-lib changes, also run npm run build:praxis-core and a direct consumer build selected by actual imports (praxis-table, praxis-crud, praxis-dynamic-form, praxis-list, praxis-dialog, or praxis-page-builder).
For the first resolution step of an issue, also do a local audit: prove that generated payloads include the right resourceKey, resourcePath, schemaUrl, readUrl, submitUrl, bindingOrder, availability state, and user-visible failure behavior.
Companion Skills
- Use
praxis-core-resource-runtimefor broader schema/resource runtime work. - Use
praxis-core-global-action-payloadswhen the surface is executed, edited, or validated asGlobalActionRef. - Use
praxis-dialog-surface-global-actionswhen the visual provider is dialog/drawer. - Use
praxis-rich-crud-screen-authoringwhen building a CRUD screen on top of resolved surfaces. - Use
praxis-angular-public-api-governancefor exported contract changes.