@praxisui/core 8.0.0-beta.19 → 8.0.0-beta.20

package/README.md

@@ -14,6 +14,21 @@
 - Keep icon, config and dynamic widget infrastructure aligned in the host app
 - Avoid duplicating low-level primitives across multiple business libraries
 
+## Governed Semantic Decisions
+
+`DomainKnowledgeService` is the shared client for the governed Domain Knowledge
+change-set lifecycle exposed by `praxis-config-starter` at
+`/api/praxis/config/domain-knowledge/change-sets`. It intentionally models the
+separate platform boundaries for `create`, `validate`, governed status
+transition and `apply`, so consuming UIs can continue an AI-authored semantic
+decision without treating the frontend as the primary source of business rules.
+
+Use it when a cockpit or runtime needs to propose safe evidence, review a
+change-set projection, approve/reject the proposal, apply an approved change set
+or read back safe summaries. Runtime surfaces must continue to treat the
+resulting materializations as derived projections of the canonical semantic
+decision.
+
 ## Form Layout Contract
 
 `FormColumn.items` and the exported `FormLayoutItem` contract define the
@@ -282,15 +297,56 @@ Regra de leitura:
 
 `@praxisui/core` preserva `x-ui.optionSource` como contrato canônico de opções remotas e lookups de entidade publicados por `/schemas/filtered`.
 
+Os tipos públicos exportados para esse contrato ficam em `option-source.model`:
+
+- `OptionSourceMetadata`
+- `LookupFilteringMetadata`
+- `LookupFilterDefinitionMetadata`
+- `LookupSortOptionMetadata`
+- `LookupFilterRequest`
+- `OptionSourceFilterRequest`
+- `LookupSelectionPolicyMetadata`
+- `LookupCapabilitiesMetadata`
+- `LookupDetailMetadata`
+- `LookupCreateMetadata`
+- `LookupDialogMetadata`
+- `LookupResultColumnMetadata`
+- `EntityLookupDisplayMetadata`
+- `EntityLookupCollectionMetadata`
+- `EntityLookupPayloadMode`
+- `EntityLookupResult`
+- `EntityRef`
+
 Para `RESOURCE_ENTITY`, o `SchemaNormalizerService` mantém a semântica enriquecida usada pelos consumidores:
 
 - identidade: `entityKey`, `valuePropertyPath`, `labelPropertyPath`, `codePropertyPath`
 - exibição: `descriptionPropertyPaths`, `statusPropertyPath`, `disabledReasonPropertyPath`
 - busca e cascata: `searchPropertyPaths`, `dependsOn`, `dependencyFilterMap`
+- filtro rico: `filtering.availableFilters`, `defaultFilters`, `sortOptions`, `defaultSort`, `quickFilterFields`, `searchPlaceholder`
 - seleção: `selectionPolicy.allowedStatuses`, `blockedStatuses`, `allowRetainInvalidExistingValue`
 - operação: `capabilities.byIds`, `navigateToDetail`, `create`, `auditSnapshot`
 - navegação: `detail.hrefTemplate`, `routeTemplate`, `openDetailMode`
 
+O helper `serializeOptionSourceFilterRequest(...)` monta o envelope canônico de
+Cut B para `POST /option-sources/{sourceKey}/options/filter`, preservando um
+único shape para:
+
+- `filter`: filtro legado do recurso hospedeiro
+- `filters`: filtros estruturados do lookup
+- `search`: quick search
+- `sort`: chave metadata-driven de ordenação
+- `includeIds`: reidratação e retenção fora da página atual
+
+Para Cut C, o core também publica helpers canônicos para cardinalidade e
+payload de coleção:
+
+- `resolveEntityLookupPayloadMode(...)`
+- `isEntityLookupPayloadModeCompatible(...)`
+- `serializeEntityLookupValueForPayload(...)`
+
+Assim, `id`, `entityRef`, `ids` e `entityRefs` continuam sob a mesma semântica
+compartilhada entre runtime, submit de formulário e integrações futuras.
+
 O mapper de `FieldDefinition` para `FieldMetadata` deriva apenas a ponte runtime necessária (`dependencyFields` e `dependencyFilterMap`) a partir de `optionSource.dependsOn`. Ele não inventa política de reset, reload ou persistência; essas decisões continuam explícitas no metadata do campo.
 
 ## `x-ui.analytics` no runtime
@@ -376,6 +432,7 @@ shell: {
 - `trackEvent` → `{ eventName, payload }`
 - `log` → `{ level, message, payload }`
 - `api.get` / `api.post` / `api.patch` → `{ url, params|body }`
+- `navigation.openRoute` → `{ path, query?, fragment?, replaceUrl?, state? }`
 - `route.register` → `{ path, componentId|loadChildren, data?, resolve?, guards?, canMatch?, canActivateChild?, replace?, position? }`
 
 ### 5) Rotas dinâmicas (route.register)