Praxis Core Global Actions Metadata
Use this skill for shared global action and metadata service contracts in @praxisui/core. Treat actions and metadata as governed semantic contracts, not local command strings or per-component aliases.
Source Audit
Before editing code or guidance, inspect:
projects/praxis-core/AGENTS.md
projects/praxis-core/docs/schema-flow.md
projects/praxis-core/docs/connection-editor.md
projects/praxis-core/src/public-api.ts
projects/praxis-core/src/lib/models/global-action.model.ts
projects/praxis-core/src/lib/tokens/global-action.*
projects/praxis-core/src/lib/services/global-action.service.ts
projects/praxis-core/src/lib/actions/global-action-ref.utils.ts
projects/praxis-core/src/lib/actions/global-action-ui.ts
projects/praxis-core/src/lib/actions/surface-open-presets.ts
projects/praxis-core/src/lib/services/component-metadata-registry.service.ts
projects/praxis-core/src/lib/services/resource-discovery.service.ts
projects/praxis-core/src/lib/schema/schema-metadata-client.ts
projects/praxis-core/src/lib/services/schema-normalizer.service.ts
projects/praxis-core/src/lib/services/domain-catalog.service.ts
projects/praxis-core/src/lib/services/domain-knowledge.service.ts
projects/praxis-core/src/lib/services/domain-rule.service.ts
projects/praxis-core/src/lib/ai/domain-catalog-context-pack.ts
- focused global action, surface open, metadata registry, schema/resource, and consumer specs
Canonical Boundary
@praxisui/core owns GlobalActionRef, global action catalog tokens/providers, GlobalActionService, payload validation, UI schema helpers, surface open presets, component metadata registry, resource discovery service, domain catalog/knowledge/rule services, schema normalization, and shared metadata service contracts.
Consumers may declare package-specific actions and metadata entries, but should not persist command strings, invent local global-action payload shapes, or duplicate schema/resource discovery logic.
When a consumer such as Dynamic Form, Table, Page Builder, dialog/surface editors,
or AI authoring needs side effects, treat GlobalActionRef as the canonical
command contract. The consumer may decide when to execute or present the action,
but the action identity, catalog entry, payload schema, validation, and execution
belong to core.
Action And Metadata Rules
- Persist global actions as
globalAction: { actionId, payload?, payloadExpr?, meta? }.
- Keep local component
action fields for local component/host events only.
- Do not reintroduce command strings such as
showAlert:..., openUrl:..., navigate:..., apiCall:..., or surface.open:{...}.
- Validate required payload keys and payload type with
validateGlobalActionRef(s).
- Use
getGlobalActionUiSchema(...) when authoring structured payload fields.
- Use surface open presets and editors for canonical surface open actions.
- Preserve the full
GlobalActionRef shape across editor round-trips:
actionId, structured payload, advanced payloadExpr, meta, effect
ordering, and policy metadata must not be collapsed into a label, callback,
custom action id, or host command string.
- Prefer structured
payload authored from the catalog/UI schema for the
primary effect. Treat payloadExpr as an advanced runtime projection and
preserve it when no structured payload is authored; do not teach AI or visual
editors to replace normal catalog-backed payload authoring with expressions.
- For
formCommandRules, use effects[].kind: "global-action" plus
effects[].globalAction and execute through GlobalActionService.executeRef.
Dynamic Form is a consumer of the core contract here; it must not redefine
payload schema, action identity, or validation locally.
- If an action id is missing, invalid, or needs a new payload shape, fail closed
or extend the canonical catalog/core contract. Do not downgrade the action to
customAction, a textual action, a local callback, or a generated command
string just to make the editor accept it.
- Treat
GlobalActionResult.data as the result produced by the executed action handler, not as a business authorization,
persistence guarantee, or metadata mutation. Built-in dialog and surface actions may place close/result payloads in data,
but domain continuation must still be modeled by the owning global action, composition dispatch, governed domain decision,
or backend-confirmed command instead of consumers parsing data locally.
- Use component metadata registry for component docs/discovery; do not create package-local registries for shared metadata semantics.
- Use resource/domain services for resource discovery, domain catalog, knowledge, and rules. Do not copy metadata service logic into table/form/list/page-builder consumers.
Inventory Before New Contract
Classify requests before adding action or metadata contracts:
ja-suportado-so-ux: action/catalog/schema metadata exists but the editor or runtime does not expose it well.
ja-suportado-mal-nomeado-ou-mal-materializado: command strings, local action wrappers, aliases, or consumer-only actionId handling should normalize to GlobalActionRef or core metadata services.
suportado-parcialmente: core can represent the action/metadata but payload UI, validation, docs, consumer bridge, editor round-trip, or AI registry projection is incomplete.
lacuna-real-de-contrato: no global action, UI schema, payload validator, resource/domain service, metadata registry, or schema flow can carry the semantic decision.
For real gaps, update core contract, public API, specs, docs, and at least one direct consumer proof.
Validation
Use the smallest reliable proof:
- global action refs, execution, UI schema, and
surface.open editor/presets:
npm run test:core -- --include=projects/praxis-core/src/lib/actions/global-action-ref.utils.spec.ts --include=projects/praxis-core/src/lib/services/global-action.service.spec.ts --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
- component metadata registry and dynamic widget consumption:
npm run test:core -- --include=projects/praxis-core/src/lib/services/component-metadata-registry.service.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-widget-page.component.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-widget-page-runtime-observation.spec.ts
- resource discovery, schema metadata, and schema normalization:
npm run test:core -- --include=projects/praxis-core/src/lib/services/resource-discovery.service.spec.ts --include=projects/praxis-core/src/lib/schema/schema-metadata-client.spec.ts --include=projects/praxis-core/src/lib/services/schema-normalizer.service.spec.ts --include=projects/praxis-core/src/lib/services/schema-normalizer-array.service.spec.ts
- domain catalog, knowledge, rules, and safe timeline projections:
npm run test:core -- --include=projects/praxis-core/src/lib/services/domain-catalog.service.spec.ts --include=projects/praxis-core/src/lib/services/domain-knowledge.service.spec.ts --include=projects/praxis-core/src/lib/services/domain-rule.service.spec.ts --include=projects/praxis-core/src/lib/models/domain-knowledge-timeline.rich-content.spec.ts --include=projects/praxis-core/src/lib/models/domain-rule-timeline.rich-content.spec.ts
- direct consumer specs where actions or metadata are materialized:
npm run test:form -- --include=projects/praxis-dynamic-form/src/lib/action-authoring/global-action-authoring.util.spec.ts --include=projects/praxis-dynamic-form/src/lib/services/domain-rule-form-rules.service.spec.ts
npm run test:table -- --include=projects/praxis-table/src/lib/table-global-action-adapter.spec.ts --include=projects/praxis-table/src/lib/praxis-table-config-editor.global-actions.spec.ts
npm run ng -- test praxis-page-builder --watch=false --progress=false --include=projects/praxis-page-builder/src/lib/editor/component-palette-dialog.component.spec.ts --include=projects/praxis-page-builder/src/lib/editor/connection-editor/connection-editor.component.spec.ts --include=projects/praxis-page-builder/src/lib/ai/page-builder-ai.adapter.spec.ts
- package authoring manifests only when metadata/action catalog changes must be projected to AI authoring:
npm run test:table -- --include=projects/praxis-table/src/lib/ai/praxis-table-authoring-manifest.spec.ts
npm run test:form -- --include=projects/praxis-dynamic-form/src/lib/ai/praxis-dynamic-form-authoring-manifest.spec.ts
npm run ng -- test praxis-page-builder --watch=false --progress=false --include=projects/praxis-page-builder/src/lib/ai/praxis-page-builder-authoring-manifest.spec.ts
For public export changes, run npm run build:praxis-core plus a direct consumer build selected by actual imports. Report which consumers were checked and whether command-string migration, alias cleanup, metadata registry projection, or AI manifest projection remains.
Companion Skills
- Use
praxis-core-global-action-payloads for focused GlobalActionRef, payload schema/UI schema, payloadExpr, validation, onResult, and command-string migration work.
- Use
praxis-core-surface-materialization for resource-derived surface.open payloads, action/surface adapters, related resources, and materializer behavior.
- Use
praxis-core-component-registry-contracts for ComponentMetadataRegistry, component docs metadata, editorial descriptors, ports, insertion presets, and builder/AI registry projection.
- Use
praxis-core-domain-governance-runtime for domain catalog, domain knowledge, domain rules, governed decisions, simulations, publications, and materializations.
- Use
praxis-core-resource-runtime for broader schema/resource discovery, actions, surfaces, capabilities, option sources, related resources, and analytics materialization.
- Use
praxis-dialog-global-actions-ai when dialog global actions or presets are the vertical surface.
- Use
praxis-dialog-surface-global-actions when surface open payloads are materialized through dialog/drawer providers.
- Use
praxis-authoring-editors when global actions are edited through Settings Panel/config editors.
- Use
praxis-angular-public-api-governance and praxis-angular-validation-gates for exports and validation.
1---2name: praxis-core-global-actions-metadata3description: Use when Codex must implement, audit, document, or consume shared `@praxisui/core` global actions and metadata services, including `GlobalActionRef`, global action tokens/providers/catalogs, `GlobalActionService`, global action UI schemas, payload validation, surface open presets/editors, component metadata registry, resource discovery service, domain catalog/knowledge/rule services, schema metadata services, public API, or cross-lib action/metadata integration.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-core-global-actions-metadata6---78# Praxis Core Global Actions Metadata910Use this skill for shared global action and metadata service contracts in `@praxisui/core`. Treat actions and metadata as governed semantic contracts, not local command strings or per-component aliases.1112## Source Audit1314Before editing code or guidance, inspect:1516- `projects/praxis-core/AGENTS.md`17- `projects/praxis-core/docs/schema-flow.md`18- `projects/praxis-core/docs/connection-editor.md`19- `projects/praxis-core/src/public-api.ts`20- `projects/praxis-core/src/lib/models/global-action.model.ts`21- `projects/praxis-core/src/lib/tokens/global-action.*`22- `projects/praxis-core/src/lib/services/global-action.service.ts`23- `projects/praxis-core/src/lib/actions/global-action-ref.utils.ts`24- `projects/praxis-core/src/lib/actions/global-action-ui.ts`25- `projects/praxis-core/src/lib/actions/surface-open-presets.ts`26- `projects/praxis-core/src/lib/services/component-metadata-registry.service.ts`27- `projects/praxis-core/src/lib/services/resource-discovery.service.ts`28- `projects/praxis-core/src/lib/schema/schema-metadata-client.ts`29- `projects/praxis-core/src/lib/services/schema-normalizer.service.ts`30- `projects/praxis-core/src/lib/services/domain-catalog.service.ts`31- `projects/praxis-core/src/lib/services/domain-knowledge.service.ts`32- `projects/praxis-core/src/lib/services/domain-rule.service.ts`33- `projects/praxis-core/src/lib/ai/domain-catalog-context-pack.ts`34- focused global action, surface open, metadata registry, schema/resource, and consumer specs3536## Canonical Boundary3738`@praxisui/core` owns `GlobalActionRef`, global action catalog tokens/providers, `GlobalActionService`, payload validation, UI schema helpers, surface open presets, component metadata registry, resource discovery service, domain catalog/knowledge/rule services, schema normalization, and shared metadata service contracts.3940Consumers may declare package-specific actions and metadata entries, but should not persist command strings, invent local global-action payload shapes, or duplicate schema/resource discovery logic.4142When a consumer such as Dynamic Form, Table, Page Builder, dialog/surface editors,43or AI authoring needs side effects, treat `GlobalActionRef` as the canonical44command contract. The consumer may decide when to execute or present the action,45but the action identity, catalog entry, payload schema, validation, and execution46belong to core.4748## Action And Metadata Rules4950- Persist global actions as `globalAction: { actionId, payload?, payloadExpr?, meta? }`.51- Keep local component `action` fields for local component/host events only.52- Do not reintroduce command strings such as `showAlert:...`, `openUrl:...`, `navigate:...`, `apiCall:...`, or `surface.open:{...}`.53- Validate required payload keys and payload type with `validateGlobalActionRef(s)`.54- Use `getGlobalActionUiSchema(...)` when authoring structured payload fields.55- Use surface open presets and editors for canonical surface open actions.56- Preserve the full `GlobalActionRef` shape across editor round-trips:57 `actionId`, structured `payload`, advanced `payloadExpr`, `meta`, effect58 ordering, and policy metadata must not be collapsed into a label, callback,59 custom action id, or host command string.60- Prefer structured `payload` authored from the catalog/UI schema for the61 primary effect. Treat `payloadExpr` as an advanced runtime projection and62 preserve it when no structured payload is authored; do not teach AI or visual63 editors to replace normal catalog-backed payload authoring with expressions.64- For `formCommandRules`, use `effects[].kind: "global-action"` plus65 `effects[].globalAction` and execute through `GlobalActionService.executeRef`.66 Dynamic Form is a consumer of the core contract here; it must not redefine67 payload schema, action identity, or validation locally.68- If an action id is missing, invalid, or needs a new payload shape, fail closed69 or extend the canonical catalog/core contract. Do not downgrade the action to70 `customAction`, a textual `action`, a local callback, or a generated command71 string just to make the editor accept it.72- Treat `GlobalActionResult.data` as the result produced by the executed action handler, not as a business authorization,73 persistence guarantee, or metadata mutation. Built-in dialog and surface actions may place close/result payloads in `data`,74 but domain continuation must still be modeled by the owning global action, composition dispatch, governed domain decision,75 or backend-confirmed command instead of consumers parsing `data` locally.76- Use component metadata registry for component docs/discovery; do not create package-local registries for shared metadata semantics.77- Use resource/domain services for resource discovery, domain catalog, knowledge, and rules. Do not copy metadata service logic into table/form/list/page-builder consumers.7879## Inventory Before New Contract8081Classify requests before adding action or metadata contracts:8283- `ja-suportado-so-ux`: action/catalog/schema metadata exists but the editor or runtime does not expose it well.84- `ja-suportado-mal-nomeado-ou-mal-materializado`: command strings, local action wrappers, aliases, or consumer-only `actionId` handling should normalize to `GlobalActionRef` or core metadata services.85- `suportado-parcialmente`: core can represent the action/metadata but payload UI, validation, docs, consumer bridge, editor round-trip, or AI registry projection is incomplete.86- `lacuna-real-de-contrato`: no global action, UI schema, payload validator, resource/domain service, metadata registry, or schema flow can carry the semantic decision.8788For real gaps, update core contract, public API, specs, docs, and at least one direct consumer proof.8990## Validation9192Use the smallest reliable proof:9394- global action refs, execution, UI schema, and `surface.open` editor/presets:9596```sh97npm run test:core -- --include=projects/praxis-core/src/lib/actions/global-action-ref.utils.spec.ts --include=projects/praxis-core/src/lib/services/global-action.service.spec.ts --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.ts98```99100- component metadata registry and dynamic widget consumption:101102```sh103npm run test:core -- --include=projects/praxis-core/src/lib/services/component-metadata-registry.service.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-widget-page.component.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-widget-page-runtime-observation.spec.ts104```105106- resource discovery, schema metadata, and schema normalization:107108```sh109npm run test:core -- --include=projects/praxis-core/src/lib/services/resource-discovery.service.spec.ts --include=projects/praxis-core/src/lib/schema/schema-metadata-client.spec.ts --include=projects/praxis-core/src/lib/services/schema-normalizer.service.spec.ts --include=projects/praxis-core/src/lib/services/schema-normalizer-array.service.spec.ts110```111112- domain catalog, knowledge, rules, and safe timeline projections:113114```sh115npm run test:core -- --include=projects/praxis-core/src/lib/services/domain-catalog.service.spec.ts --include=projects/praxis-core/src/lib/services/domain-knowledge.service.spec.ts --include=projects/praxis-core/src/lib/services/domain-rule.service.spec.ts --include=projects/praxis-core/src/lib/models/domain-knowledge-timeline.rich-content.spec.ts --include=projects/praxis-core/src/lib/models/domain-rule-timeline.rich-content.spec.ts116```117118- direct consumer specs where actions or metadata are materialized:119120```sh121npm run test:form -- --include=projects/praxis-dynamic-form/src/lib/action-authoring/global-action-authoring.util.spec.ts --include=projects/praxis-dynamic-form/src/lib/services/domain-rule-form-rules.service.spec.ts122npm run test:table -- --include=projects/praxis-table/src/lib/table-global-action-adapter.spec.ts --include=projects/praxis-table/src/lib/praxis-table-config-editor.global-actions.spec.ts123npm run ng -- test praxis-page-builder --watch=false --progress=false --include=projects/praxis-page-builder/src/lib/editor/component-palette-dialog.component.spec.ts --include=projects/praxis-page-builder/src/lib/editor/connection-editor/connection-editor.component.spec.ts --include=projects/praxis-page-builder/src/lib/ai/page-builder-ai.adapter.spec.ts124```125126- package authoring manifests only when metadata/action catalog changes must be projected to AI authoring:127128```sh129npm run test:table -- --include=projects/praxis-table/src/lib/ai/praxis-table-authoring-manifest.spec.ts130npm run test:form -- --include=projects/praxis-dynamic-form/src/lib/ai/praxis-dynamic-form-authoring-manifest.spec.ts131npm run ng -- test praxis-page-builder --watch=false --progress=false --include=projects/praxis-page-builder/src/lib/ai/praxis-page-builder-authoring-manifest.spec.ts132```133134For public export changes, run `npm run build:praxis-core` plus a direct consumer build selected by actual imports. Report which consumers were checked and whether command-string migration, alias cleanup, metadata registry projection, or AI manifest projection remains.135136## Companion Skills137138- Use `praxis-core-global-action-payloads` for focused `GlobalActionRef`, payload schema/UI schema, payloadExpr, validation, onResult, and command-string migration work.139- Use `praxis-core-surface-materialization` for resource-derived `surface.open` payloads, action/surface adapters, related resources, and materializer behavior.140- Use `praxis-core-component-registry-contracts` for `ComponentMetadataRegistry`, component docs metadata, editorial descriptors, ports, insertion presets, and builder/AI registry projection.141- Use `praxis-core-domain-governance-runtime` for domain catalog, domain knowledge, domain rules, governed decisions, simulations, publications, and materializations.142- Use `praxis-core-resource-runtime` for broader schema/resource discovery, actions, surfaces, capabilities, option sources, related resources, and analytics materialization.143- Use `praxis-dialog-global-actions-ai` when dialog global actions or presets are the vertical surface.144- Use `praxis-dialog-surface-global-actions` when surface open payloads are materialized through dialog/drawer providers.145- Use `praxis-authoring-editors` when global actions are edited through Settings Panel/config editors.146- Use `praxis-angular-public-api-governance` and `praxis-angular-validation-gates` for exports and validation.