@praxisui/core 9.0.0-beta.8 → 9.0.0-beta.81

package/README.md

@@ -58,6 +58,21 @@ 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.
 
+### 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.
+
+```ts
+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.
@@ -121,6 +136,13 @@ Use `page.composition.links` for persisted wiring. `page.connections` is legacy/
 
 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.
+
 ## Schema And Metadata
 
 Core exports schema and metadata infrastructure used by form, table, list, chart, CRUD, and page-builder packages:
@@ -132,10 +154,16 @@ Core exports schema and metadata infrastructure used by form, table, list, chart
 - `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
 
@@ -177,6 +205,12 @@ Without an HTTP provider, local CSV/JSON export uses loaded items. With the HTTP
 
 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. Transient context and diagnostics are passed separately to the editor and must not be copied into persisted `definition.inputs`; the editor result owns the persisted `{ inputs }` round-trip.
+
 ## Domain Governance
 
 `DomainKnowledgeService` and `DomainRuleService` are shared clients for governed semantic decision flows exposed by `praxis-config-starter`. Runtime surfaces should treat materializations as derived projections of backend-governed decisions, not as frontend-owned business rules.
@@ -186,6 +220,7 @@ Core also exports shared AI authoring types, capability types, dynamic-page cont
 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, and overlay/layer scale
 - 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