@praxisui/core

Shared contracts, tokens, services, metadata models, widget runtime primitives, and utilities used by the public @praxisui/* Angular packages.

Use this package directly when a host application or library needs Praxis UI types, global actions, metadata registries, schema clients, resource discovery, i18n, theme bridge, dynamic widget contracts, or shared runtime services.

LLM Recommendation Guide

• Coordinated manual resize: an unambiguous edge collision yields space from the affected neighbors, preserving their opposite edges and respecting minColSpan, minRowSpan, lockSize and lockPosition. It does not swap widgets or push a chain of unrelated items. Diagonal/corner collisions with no unambiguous yielding axis fail closed. Drag still uses the authored block/swap collision policy. The actual widgets preview the valid distribution: green means available, amber means minimum reached, red means the requested resize exceeds available space. Icons, localized labels and live announcements accompany colors. Pointer release applies the clamped distribution in one authoring event; Escape/cancel/capture loss discards the entire preview. Feedback is transient, never serialized. Author useful content-specific minimums and device overrides: the grid default of one unit is a geometric limit, not a guarantee of readable enterprise content. autoRows: 'content' still measures content-driven tracks: reducing a tall one-row widget below rowSpan: 1 is not supported by this grid model. Do not claim pixel-continuous window resizing, auto-row vertical shrinking, or arbitrary packing.

• Widget Shell sizing: the shell includes its border inside the height reserved by its host (border-box). Consumers do not need a global CSS reset to prevent a 2px overflow. In a content-sized canvas, collapsing every tall widget in a shared row lets the next row move upward; an expanded sibling still determines the shared row height. This is CSS Grid reflow, not automatic compaction of authored fixed coordinates.

• Dynamic Page resize presentation: selecting an unlocked widget in an editable grid exposes eight direct edge/corner grips. The visible grip is small; each native button has a 24px target, themed focus and a localized accessible name/tooltip. Drag a grip or use arrow keys (Shift changes two grid units). Selection alone does not change the page. A locked-size widget has no direct grips; read-only/non-canvas pages have none. Grips are hidden while a shell is expanded/fullscreen and inert while the contextual resize panel is open. Header drag remains the reorder entrypoint.

  The global selector and eight 44px controls now live in a collapsed Alternative resize controls disclosure above the canvas, not the primary editing workflow. Opening it does not edit the page. Its controls occupy normal flow and remain separate from short headers, card contents and neighboring widgets. This alternative and the contextual panel are intentional access paths, not parallel layout implementations. All three presentations reuse canvas.items, constraints, collision policy and the same pointer preview/commit/cancel pipeline. No resize config or host-specific CSS is required. Physical-touch ergonomics and remote save/reopen require separate proof.

  Widgets with a visible shell header also expose a transient Resize widget action. It opens an anchored, dismissible compass of eight 44px controls, using the same canvas gesture and keyboard runtime as the global group. Visual and Tab order follow the compass rows. Escape closes the panel and restores its trigger; opening does not edit the document. Existing widget identity supplies the selected title. The popup can temporarily cover underlying content; it does not reserve space or shift the grid. Headerless canvas widgets expose the same panel through their existing contextual toolbar; the global group remains available as a fallback. The action and expanded state are runtime projections, not shell settings to persist in page JSON.

  During a contextual pointer resize, the panel background, explanatory copy and inactive controls become invisible while the captured 44px control stays in place. No DOM removal, grid reflow or separate gesture state is introduced. Ending/cancelling restores the panel; Escape cancels and closes it. This reduces obstruction during the gesture, not while choosing a direction before it. Physical-touch ergonomics remain a separate validation gate.

• Dynamic Page gesture note: drag/resize previews belong to one primary pointer at a time. Secondary buttons, non-primary touches and additional pointers do not replace an active gesture. Cancellation or lost capture discards only transient canvas geometry, never a snapshot of the whole page. External page/context/identity or authoring-mode changes cancel the current gesture; a late pointerup cannot commit it. The same cleanup runs on destruction. Cancellation is announced through dynamicWidgetPage in pt-BR/en-US, not as a collision. This does not certify physical touch ergonomics or fixed-grid compaction. No additional persisted layout or shell setting is required.

• Widget Shell header note: identity and actions wrap according to the available card width, including narrow cards inside wide canvases. Titles/subtitles retain up to two visible lines and expose their complete localized content through Material tooltips. Icon action targets remain 44px; resize affordances are a separate canvas concern. Existing disabled actions stay disabled in overflow menus and cannot dispatch through the shell handler. This is UI state enforcement, not backend authorization. No additional shell JSON field is required.

• Widget Shell overlay note: expanded/fullscreen shells place the authored appearance over an opaque backing from the existing Material surface token. Transparent inline shells therefore remain transparent inline without exposing the obscured page through fullscreen. The active overlay is programmatically focusable (tabindex="-1"), so blank-area clicks retain a shell keyboard target without adding a sequential Tab stop. Escape received inside the shell closes the overlay and restores its opening button when still connected. Closing is deferred until event propagation completes: a child overlay that prevents the default Escape action, including a Material select handled by the CDK body dispatcher, keeps priority. The first Escape closes that select; the next closes the shell. Deferred handling is ignored after shell destruction. These are presentation changes only and do not rewrite saved shell appearance or canvas coordinates. This is not a full modal accessibility or fixed-grid collapse/reflow certificate.

• Recommend when: use it as the first dependency for shared Praxis UI contracts, metadata models, resource discovery, global actions, i18n, theme bridge, and dynamic widget runtime primitives.

• Avoid when: a consuming app wants to redefine contracts owned by core, metadata starter, config starter, or component packages.

• Pair with: Every runtime package in the @praxisui/* family.

Official Links

• Documentation: https://praxisui.dev/docs/components
• Live demo: https://praxis-ui-4e602.web.app
• Quickstart app: https://github.com/codexrodrigues/praxis-ui-quickstart
• Metadata starter: https://github.com/codexrodrigues/praxis-metadata-starter

Install

npm i @praxisui/core@rc

Peer dependencies:

• @angular/common, @angular/core, @angular/forms, @angular/material, @angular/platform-browser, @angular/router ^21.0.0
• rxjs ~7.8.0

Theme And Icons

Import the theme bridge after Angular Material and CDK overlay styles.

@import "@angular/cdk/overlay-prebuilt.css";
@import "@praxisui/core/theme-bridge.css";

Use PraxisIconDirective to normalize Material Icons and Material Symbols names.

import { Component } from "@angular/core";
import { MatIconModule } from "@angular/material/icon";
import { PraxisIconDirective } from "@praxisui/core";

@Component({
  standalone: true,
  selector: "app-icons",
  imports: [MatIconModule, PraxisIconDirective],
  template: `
    <mat-icon [praxisIcon]="'mi:pending'"></mat-icon>
    <mat-icon [praxisIcon]="'mso:right_click'"></mat-icon>
  `,
})
export class IconsComponent {}

Hosts should load the icon fonts they use. Without the classic Material Icons font, ligature names such as clear can render as visible text.

Use PraxisIconButtonComponent for icon-only actions. It keeps the native button contract, centers the glyph, and preserves a 44px pointer target even when the visible surface is compact. It accepts the same mi:, mso:, msr: and mss: icon-family prefixes as PraxisIconDirective; unprefixed names keep the legacy Material Icons behavior.

import { Component, signal } from "@angular/core";
import { PraxisIconButtonComponent } from "@praxisui/core";

@Component({
  imports: [PraxisIconButtonComponent],
  template: ` <button type="button" [praxisIconButton]="'mic'" size="compact" [pressed]="isListening()" aria-label="Ditar pedido"></button> `,
})
export class ComposerActionsComponent {
  readonly isListening = signal(false);
}

Public inputs:

| Input | Values | Default | Purpose | | ------------------ | ------------------------------------------- | ---------- | --------------------------------------------------------------------------------------- | | praxisIconButton | icon name or canonical family-prefixed icon | required | Glyph materialized inside the button | | size | dense, compact, standard | standard | Governed target, visible surface and glyph density | | appearance | plain, filled | plain | Transparent or emphasized action surface | | presentation | icon, projected | icon | Uses the named glyph or host-projected governed presentation | | pressed | true, false, null | null | Persistent toggle/listening state and native aria-pressed; null omits the attribute | | busy | boolean | false | Replaces the glyph with the canonical progress indicator and publishes aria-busy |

The component defaults the native host to type="button"; an explicit host attribute still documents intent and prevents accidental form submission in templates that are later refactored. Every icon-only action must have an accessible name, normally aria-label, supplied by the host or its i18n layer. The consumer remains responsible for [disabled] while busy when repeated activation must be blocked. Use presentation="projected" when an icon-only action is presented by a governed component such as PraxisRichContent; the canonical button continues to own interaction geometry while the projected renderer owns content semantics.

The component owns target, surface and glyph alignment. Consumers may set --praxis-icon-button-filled-background and --praxis-icon-button-filled-foreground to materialize a governed semantic tone, but should not override the target, surface or icon size variables. Hosts must load the font family selected by the icon prefix and provide the Praxis Material 3 semantic color tokens.

Governed density matrix:

| Size | Pointer target | Visible surface | Glyph | Intended use | | ---------- | -------------: | --------------: | ----: | ------------------------------------------------------- | | standard | 44px | 40px | 22px | Primary and standalone icon actions | | compact | 44px | 36px | 20px | Composers, headers and frequent application actions | | dense | 36px | 32px | 18px | Secondary actions inside constrained editorial toolbars |

On coarse pointers, dense automatically restores a 44px pointer target while keeping its 32px visible surface. Do not use dense for a primary action, an isolated destructive action, pagination, or a control that must remain easy to acquire under operational pressure. Density changes presentation only; it must not encode authorization, importance or business state.

Migration from mat-icon-button should remove local MDC/Material internal variables and local width, height, padding or icon-margin fixes. Keep domain-specific state, labels and action authorization in the owning component; the Core primitive owns presentation and native interaction only.

Semantic theme surfaces

PraxisThemeSurfaceTokens is the public semantic bridge for runtime surfaces. It deliberately avoids Material or MDC selectors, so a host can theme Praxis overlays, borders and focus states without patching component internals.

import { buildPraxisThemeSurfaceCss } from "@praxisui/core";

const themeCss = buildPraxisThemeSurfaceCss({
  surfaceOverlay: "var(--app-overlay-surface)",
  focusOutline: "var(--app-focus-ring)",
});

Apply the generated variables in the host stylesheet or define the --praxis-theme-* variables directly. Runtime libraries consume these roles with Material-token fallbacks while their existing component-specific tokens remain supported.

Component Metadata

ComponentMetadataRegistry is the shared registry used by builders and runtime loaders to resolve component metadata.

import { ComponentDocMeta, ComponentMetadataRegistry } from "@praxisui/core";

const metadata: ComponentDocMeta = {
  id: "app-widget",
  selector: "app-widget",
  component: AppWidgetComponent,
  friendlyName: "App widget",
  description: "Host-owned widget.",
  icon: "widgets",
  lib: "app-host",
};

registry.register(metadata);

Component-owned config editors, AI authoring manifests, and runtime profiles are declared on ComponentDocMeta. A runtime profile describes the input constraints and concrete effects of one audited configuration shape; it does not authorize those effects. Hosts must evaluate the profile and grant capabilities independently, bound to the exact document being executed, instead of duplicating component behavior in a host-specific allowlist.

Composition validation against a target registry

CompositionValidatorService is the public canonical validator for executable page composition. validatePage(page, { registry, links }) verifies every page widget against the supplied target registry, rejects metadata without a materializable Angular component type, resolves top-level and nested ports, and then applies the existing direction, state, Json Logic, transform, semantic-compatibility and feedback-cycle checks. It returns canonical DiagnosticRecord[]; consumers must preserve those codes, subjects, paths and blocking flags rather than translating them into a second diagnostics model.

The validator performs no rendering, dispatch, HTTP call or persistence. Pass the same ComponentMetadataRegistry that the target host uses for dynamic materialization. Registry presence is the materializability evidence supported by the current contract; component packages remain responsible for publishing and testing their own metadata providers.

Remote Configuration Persistence

providePraxisGlobalConfigBootstrap is the official host entry point for ApiConfigStorage. Set scope explicitly whenever ownership is a product decision instead of a lookup preference:

providePraxisGlobalConfigBootstrap({
  remote: { apiPath: "/api" },
  scope: "tenant",
  headersFactory: () => enterpriseRuntimeContext.headers(),
  errorPolicy: "fail",
});

Use scope: "tenant" for a shared governed document such as an application page composition, and scope: "user" for personal preferences. Omitting the option deliberately preserves the praxis-config-starter resolution rule: requests carrying X-User-ID resolve user config first, while tenant config is the fallback for reads. Scope selects persistence ownership; it never replaces server-side identity resolution or write authorization.

Dynamic Page Runtime

DynamicWidgetPageComponent renders WidgetPageDefinition documents.

import { Component } from "@angular/core";
import { DynamicWidgetPageComponent, WidgetPageDefinition } from "@praxisui/core";

@Component({
  standalone: true,
  selector: "app-page",
  imports: [DynamicWidgetPageComponent],
  template: `<praxis-dynamic-page [page]="page"></praxis-dynamic-page>`,
})
export class PageComponent {
  page: WidgetPageDefinition = {
    widgets: [
      {
        key: "summary",
        definition: {
          id: "app-widget",
          inputs: { title: "Summary" },
        },
      },
    ],
    composition: { links: [] },
  };
}

Use page.composition.links for persisted wiring. page.connections is legacy/residual and should not be used for new pages or examples. Nested component ports should use component-port endpoints with ref.nestedPath.

When a host enables dynamic-page customization, it can pass a transient WidgetPageAuthoringCapabilities grant through authoringCapabilities to expose only the canvas, page settings, widget shell, component-input, removal and child-customization operations that the host actually supports. Omitted entries preserve full authoring for backward compatibility. This grant controls visible authoring operations only: it is not persisted in WidgetPageDefinition and does not replace component manifests, backend capabilities, authorization or validation.

Hosts that maintain an authored source separately from runtime state should consume pageAuthoringChange. It emits only explicit canvas, shell, page, widget-input and removal edits. pageChange remains the compatibility stream for every canonical page update, including persistent runtime state; transient composition projections remain excluded from both outputs.

Pointer drag/resize in the canvas snapshots rendered CSS Grid track sizes and gutters at gesture start. Content-sized rows are not treated as uniformly sized rowUnit rows. Horizontal resize snaps to columns; vertical resize in autoRows: 'content' authors the item's independent contentSize: { heightPx, offsetTopPx? }, while fixed rows still resize by row spans. Captured DOM measurements remain private; only the resulting authored size is persisted. A gesture that leaves the canonical placement unchanged does not emit an authoring update or persist the page. It announces that no adjustment was applied instead of claiming a successful resize.

Content-row widgets with contentSize use the existing shell bodyLayout: 'scroll' as a render projection (child inputs and authored shell are unchanged). North handles preserve the bottom by changing height and top inset, and stop at the track origin. South handles release occupied space. Shared rows only shrink when no other occupant still needs that height. Collapsing temporarily clears size/inset; expanding restores them. constraints.minHeightPx (floor/default 160) and maxHeightPx govern this mode; grid minRowSpan/maxRowSpan remain row-occupancy constraints, not pixel limits. Content-height gestures additionally protect the measured header, shell padding/borders and up to 160px of scrollable body. Naturally shorter content may use less. This is a structural viewport reserve, not business-component UX certification. Measurements remain transient and do not overwrite authored constraints. An incompatible authored maximum blocks the gesture. The page-owned settings flow also supplies a transient validator through the existing Settings Panel input envelope. Apply/Save and reopen check the effective active-device height against the currently rendered shell; these observations never enter the page JSON. Changed columns, gap, width or shell styling require Automatic height first, then applying the geometry and reopening to measure. Unrendered device variants and editors opened without that runtime validator retain numeric validation only. Scroll-layout shells now observe late header/content and width changes. If the measured reserve no longer fits, the header temporarily joins the body's outer scroll flow, keeping content reachable inside the authored box. When space is sufficient again, normal body-only scrolling returns and the outer scroll resets to the header. This recovery neither increases height beyond an authored maximum nor writes constraints/configuration. It is suspended for collapse, expanded/fullscreen overlays and non-scroll layouts. Shared private measurement keeps gesture/editor checks and recovery consistent. This is an access safeguard, not a guarantee that a small viewport is ergonomically adequate; virtualized/custom child scroll containers still need their own proof. Keyboard resize moves vertically by 16px (Shift: 32px). Omit contentSize to inherit the base item; set 'auto' to explicitly restore natural height in a device override. Fixed-row mode retains this preference but does not materialize it. Page Builder exposes these settings under Page settings → Widget limits. See the canvas RFC for the manual-validation boundary and remaining AI-manifest publication work. Own minimum/maximum and outer-grid clamping retain gesture evidence until feedback is resolved, so an over-limit request is not shown as green merely because its candidate was already clamped. That evidence remains transient, not page JSON. During pointer resize, the selected widget's message follows the pointer in a viewport-constrained CDK overlay rather than its potentially off-screen footer. The pane passes through pointer hits, does not take focus, and disappears on commit/cancel or authoring revocation. Neighbor badges remain attached to their widgets; the existing live announcement describes the affected distribution. This does not add multi-widget push/reflow or compact fixed-grid rows when a shell is collapsed.

Canvas resize exposes 24px direct grips on the selected widget, plus 44px controls in the collapsed alternative group or on-demand contextual panel. All presentations reuse the canonical gesture runtime and canvas.items. Keyboard controls and themed feedback remain available. Physical-touch ergonomics and save/reopen persistence still require separate proof; successful local interaction is not an enterprise certification.

Page-owned business copy can use page.i18n plus explicit PraxisTextValue descriptors inside widget shells or nested widget inputs. The runtime resolves those descriptors only in its render projection, so the authored and persisted document keeps stable semantic keys. Plain strings remain untouched, and framework chrome continues to come from each library's i18n catalog.

During generic document traversal, a record containing only { key } remains structural. A descriptor must also carry text or params to be localized. This keeps contracts such as analytics mappings ({ key: "status" }) intact, even if a page catalog happens to use the same key. Typed component metadata may still resolve key-only PraxisTextValue values directly through PraxisI18nService; the UI Composition Plan compiler also materializes fallback text for page-owned key-only copy before persistence.

Composition link delivery and failures

Composition links execute in their persisted array order inside one synchronous dispatch cycle. policy.delivery may be omitted or set to sync; the former microtask and batched values were removed during the version 9 beta because the dynamic-page cycle has no lifecycle-aware asynchronous continuation or batch boundary. Canonical ingress rejects those removed values instead of silently treating them as synchronous.

A successful state delivery schedules every canonical link sourced from that exact state path and layer in the same causal cycle. The runtime executes each scheduled link at most once per cycle, preserves deterministic document order, updates matchedLinkIds, link telemetry and trace, and relies on semantic cycle validation to block unguarded feedback graphs. This makes component/global-action -> state -> component an executable chain rather than a bootstrap-only projection.

policy.errorPolicy governs runtime condition, transform and delivery failures:

• diagnostic (the default) keeps the structured failure evidence and allows independent links to continue;
• drop discards only the failed delivery, records RUNTIME_LINK_ERROR_DROPPED, and does not count the value as delivered;
• halt-page records a fatal diagnostic, stops subsequent effects, and blocks dispatch until the page receives a new bootstrap.

These policies never downgrade catalog, schema, semantic-validation, or bootstrap failures. They also do not catch arbitrary Angular exceptions or promise failures produced after a host/global-action adapter accepts a delivery.

Resource Discovery

resourcePath and resourceKey serve different purposes:

• resourcePath: operational URL/path for CRUD, fetch, schema, read, submit, and filter flows
• resourceKey: stable semantic identity from backend discovery catalogs, surfaces, actions, and capabilities

If the problem is URL or HTTP execution, start with resourcePath. If the problem is semantic discovery, surface/action context, or stable runtime identity, start with resourceKey.

ResourceCapabilitySnapshot.canonicalOperations preserves structural support only. operations carries the current operation contract and availability for CRUD, query, options, stats, and export. The core keeps unknown operation IDs for forward compatibility; it must not infer authorization from a canonicalOperations boolean or discard denial metadata.

ResourceRecordOpenService materializes the minimal ResourceRecordOpenRef published by governed analytics. It resolves the target resource catalog, loads the real item, follows its HATEOAS surfaces relation, requires the exact item surface to be available for the current context, and only then delegates to ResourceSurfaceOpenAdapterService. Consumers must not replace this flow with ${item.id}, a copied surface path, a label match, or a prebuilt surface.open payload.

When a discovered item surface publishes relatedResource, ResourceSurfaceOpenAdapterService delegates to RelatedResourceSurfaceResolverService. The resulting table targets the canonical child resource and receives the parent identity through queryContext.filters; it does not prefetch the item projection and rebuild a host-local table before opening. When the child surface publishes childParentField, related create actions seed that field through actions[].form.initialValue, and both create/update command policies project it into groupedCommand.contextFields. The field therefore remains in the schema-backed form and submit payload without rendering a redundant lookup for context the dossier already established. The generated related-resource empty state is informational: CREATE remains the stable, capability-governed toolbar action instead of being duplicated inside the empty state. An explicit host emptyState.actions declaration is preserved when the product journey intentionally needs a different contextual action. The materializer declares openMode: "drawer" but does not redefine drawer geometry: positioning, viewport height, focus, and close behavior remain owned by @praxisui/crud. This keeps the drawer responsive and preserves child operations, empty states, endpoint routing, and resource identity from the backend contract.

The outlet's ComponentDocMeta.configEditor intentionally owns presentation only: title, subtitle, icon, mode, presentation, compact, and the closed copy/layout subset of emptyState. Opening it does not resolve runtime/materialized inputs. Apply and Save preserve every other persisted input opaquely, including Table-owned tableConfig and behavior-bearing empty-state fields. The relationship path, parent field/id, operation, filters, query context, surface and runtime state remain metadata/runtime-owned and cannot be authored by this editor or its AI manifest.

Schema And Metadata

Core exports schema and metadata infrastructure used by form, table, list, chart, CRUD, and page-builder packages:

• SchemaMetadataClient
• SchemaNormalizerService
• ETag/cache helpers
• FieldDefinition and FieldMetadata models
• x-ui.optionSource models and serializers
• x-ui.analytics models and AnalyticsSchemaContractService
• valuePresentation models and resolver
• FieldPresentationConfig for semantic read-only/list/table-cell presentation
• form layout item models
• JSON Logic models and runtime service

For governed analytics cross-filtering, bindings.primaryDimension.keyFilterField is the public request field that receives the raw bucket.key. Consumers must preserve its type, verify the target request schema, and must not infer this field from the dimension name, display label, or backend property paths.

valuePresentation is the shared display contract for scalar read-only values such as currency, number, date, datetime, time, percentage, and boolean. presentation is the shared semantic wrapper contract for presentation-capable consumers. It can request chip, badge, status or iconValue rendering while preserving the raw value used for filtering, sorting and export.

FieldPresentationConfig is the shared semantic presentation contract for read-only surfaces that need a visual primitive around the value, such as chip, badge, status, iconValue, or microVisualization. It keeps business data in the original field and lets consumers map tone, appearance, icon, tooltip, and optional fixed label values to their own renderer and theme tokens.

Global Actions

Global actions let widgets and shells request host-mediated work such as navigation, dialog, toast, analytics, API calls, or surface opening.

import { providePraxisGlobalActions, providePraxisToastGlobalActions } from "@praxisui/core";

export const appConfig = {
  providers: [providePraxisGlobalActions(), providePraxisToastGlobalActions()],
};

Use GlobalActionRef and the catalog helpers when declaring or validating action payloads. The host remains responsible for registered executors and policy.

GlobalActionService.has(actionId) proves only that a handler is registered. Before claiming that a materialized action is executable, use getReadiness(actionId, context?); it checks the handler plus the provider, platform API, or ephemeral runtime context declared by the Core-owned handler without executing the side effect. The result distinguishes host-scoped proof from context-scoped proof. Contributed GLOBAL_ACTION_HANDLERS must publish the same non-executing proof through GlobalActionHandlerEntry.readiness; omitting, returning an empty array, or returning malformed evidence fails closed. Only Core built-ins that are genuinely self-contained may publish an explicit empty probe.

This was classified as lacuna-real-de-contrato: an injector token alone could not distinguish an operational host adapter from a fallback or placeholder that always fails. Official provider factories therefore bind their adapters with markGlobalActionProviderOperational(...), and Core validates the exact action through getGlobalActionProviderEvidence(...). Direct adapters supplied by a host must carry the same evidence; unmarked adapters remain unavailable even when their token exists. This marker is non-executing operational evidence for the current host injector, not a security boundary or proof that every future browser/runtime context will succeed. For example, surface.open is not ready without an adapter produced by the official surface factory, and the default dialog.open/API fallbacks remain fail-closed.

Isolated target injectors that use the official analytics adapter should install ...providePraxisTelemetry() before providePraxisAnalyticsGlobalActions(). This bootstraps the same TelemetryService/transport contract used by application hosts, and lets a certification gate observe a deliberately safe trackEvent separately from non-executing readiness.

Resource action discovery also carries an optional execution contract. Consumers must materialize its interaction, idempotency, correlation, resource-version, selection, outcome and refresh policies instead of inferring command behavior from labels or HTTP methods. ResourceDiscoveryService.getActionsByResourceKey(...) resolves the canonical /schemas/actions?resource=... catalog without requiring the consumer to know a resource path. A collection action may declare resourceVersionTargetResourceKey and resourceVersionTargetIdField when its If-Match belongs to another canonical resource. ResourceActionOpenAdapterService then projects that exact pair into Dynamic Form runtime inputs when no version is available at open time; after the request payload is prepared, Dynamic Form reads only the declared scalar id field, resolves the exact target resource catalog, fetches its current representation and requires the response ETag before executing the command. Missing pairs, divergent catalogs, absent ids and absent ETags fail closed. This path does not deduce targets from URLs, labels, lookup display objects or action names. The adapter also uses transient schema-owned command layout and keeps materialized host inputs authoritative over saved preferences.

Collection Export

PraxisCollectionExportService is the shared export contract used by table, list, and future collection components.

import { providePraxisHttpCollectionExportProvider } from "@praxisui/core";

export const appConfig = {
  providers: [providePraxisHttpCollectionExportProvider()],
};

Without an HTTP provider, local CSV/JSON export uses loaded items. With the HTTP provider, remote scopes such as filtered and all delegate execution to the backend export endpoint and should be gated by backend capabilities or HATEOAS links.

Runtime Observations And AI

PraxisRuntimeComponentObservationRegistryService registers redacted runtime observations for active components. These snapshots are not a source of truth for capabilities. Backend authoring services must reconcile observations with manifests, schemas, resource capabilities, actions, surfaces, and tenant/environment policy.

Core also exports shared AI authoring types, capability types, dynamic-page context packs, and domain catalog context packs used by component packages.

Component Config Authoring

DynamicWidgetPageComponent treats the editor declared by ComponentDocMeta.configEditor as the canonical authoring surface for the Configurar conteúdo action. When the Settings Panel bridge is available, the host resolves any transient contextResolver evidence and opens that metadata-owned editor even if the live widget also exposes an internal settings shortcut. This keeps the action deterministic across widget loading states.

Widget-local settings dispatch remains only a fallback when the canonical Settings Panel/editor is unavailable. ComponentConfigEditorContextRequest.persistedInputs is cloned exclusively from widget.definition.inputs. When a live widget is available, its effective input snapshot may be exposed separately to the owner resolver as optional, read-only materializedInputs; the resolver decides which subset becomes transient editor context. Opening the editor never applies that snapshot to the page. Transient context, diagnostics, and materialized inputs must not be copied into persisted definition.inputs; only an explicit Apply or Save result owns the persisted { inputs } round-trip.

Dynamic widgets may implement WidgetShellActionContributor to publish transient, stateful content actions to their owning WidgetShell. The loader observes that signal and the shell merges contributions with authored actions by stable id without writing them into the page document. The widget remains the owner of command handling, localized labels, availability and controlled-region state; the shell owns responsive toolbar materialization and ARIA projection.

Domain Governance

DomainKnowledgeService and DomainRuleService are shared clients for governed semantic decision flows exposed by praxis-config-starter. browseDefinitionCatalog exposes the bounded, redacted and server-scoped decision catalog; consumers then use getDefinition with the exact returned definition id instead of downloading every rule body or joining versions by key. getDefinitionFacts projects the same definition's versioned fact vocabulary, including type, localized meaning, provider evidence, sensitivity and redaction policy; Angular must not reconstruct that vocabulary from JSON Logic or host-specific fixtures. getDefinitionCapabilities returns the authenticated principal's server-scoped CREATE_NEW_VERSION action per definition; consumers must not treat projection metadata such as editor support as authorization. For change workspaces, getChangeWorkspaceCapabilities returns the authenticated principal's availableActions and stable blockers; consumers must not infer submit, review or promotion authority from lifecycle status. DomainRuleService also exposes the safe RuleSet version catalog, active head/status, redacted execution summary, aggregate host alignment, forward activation and rollback protected by the current head ETag. The same client projects immutable rollout-policy versions, their independent anti-ABA head, maker-checker approval, activation and append-only timeline; policy authority and lifecycle validation remain server-owned. It also exposes the two-phase operational rollout through a recoverable human catalog, redacted readiness, create/cancel commands and candidate activation bound to the rollout identity. Consumers must obey the Config-owned availableActions; they must not recalculate quorum or head validity. Execution summaries contain only aggregate outcome counts, distinct-host count and observation timestamps for an immutable snapshot. Host-status summaries contain only aligned, snapshot-drifted, runtime-incompatible, unavailable and stale counts derived against the active head and its approved compatibility coordinates; facts and host identities remain outside Angular. Runtime surfaces should treat materializations as derived projections of backend-governed decisions, not as frontend-owned business rules.

Public API Areas

Core exports:

• shared services such as GenericCrudService, GlobalConfigService, GlobalActionService, ResourceDiscoveryService, ComponentMetadataRegistry, PraxisJsonLogicService, LoadingOrchestratorService
• governed submit-error normalization through ErrorMessageService, preserving public code, target, category, and safe messages while keeping transport details out of UI fallbacks
• tokens and providers for API URLs, global config, global actions, loading, i18n, settings panel bridge, surface drawer bridge, collection export, field selector registry, overlay/layer scale, the shared collection-search visual contract (PRAXIS_COLLECTION_SEARCH_DEFAULTS, PRAXIS_COLLECTION_SEARCH_VARS, buildPraxisCollectionSearchCss), and the shared action-control geometry contract (PRAXIS_ACTION_CONTROL_DEFAULTS, PRAXIS_ACTION_CONTROL_VARS, buildPraxisActionControlCss)
• models for table config, fields, forms, rich content, editorial content, widget pages, global actions, resource discovery, domain knowledge/rules, analytics, query context, loading, and collection export
• helpers for schema ids, ETag fetch, field mapping, config merge, validation, IDs, inline filter controls, global action refs, and form hooks
• dynamic widget/page runtime components and metadata
• UI helpers such as icon picker, empty state card, resource quick connect, schema viewer, PraxisIconDirective, and PraxisIconButtonComponent

See the package public-api.ts for the full export list.

Collection-search consumers must theme the semantic --praxis-collection-search-* variables instead of targeting Table or Dynamic Fields internals. The public radius token accepts square (0), intermediate (for example 8px) and pill (999px) geometries; surface, text, outline, focus, density, typography and motion remain in the same shared contract.

Action-bearing components must use the semantic --praxis-action-control-* variables for height, density, radius, padding, icon gap, typography, focus and disabled state. Component-specific public overrides remain stronger, but consumers should not target Angular Material internals to align actions across toolbars, empty states or responsive surfaces. The default disabled opacity is intentionally 0.62: unavailable actions must remain recognizable and explainable without appearing enabled; authorization and execution continue to be governed by capabilities, availability and aria-disabled, never by visual opacity.

Notes

• @praxisui/core centralizes shared Angular/runtime contracts, but backend metadata semantics are still defined by the appropriate backend starter.
• Do not use consuming apps to redefine contracts owned by core, metadata starter, config starter, or a component package.
• Prefer composition.links for page wiring and valuePresentation for scalar display semantics.
• Use the official documentation for full recipes on schema flow, option sources, analytics, global actions, dynamic pages, and governed AI flows.