@praxisui/core 3.0.0-beta.9 → 5.0.0-beta.0

package/README.md

@@ -119,14 +119,56 @@ Observação: os IDs de widgets usados na página devem estar registrados via `C
 
 ## 📄 Documentacao Tecnica da Lib
 
-- `projects/praxis-core/docs/connection-editor.md`
+- `projects/praxis-core/docs/connection-editor.md` (historico legado; fora do fluxo ativo)
 - `projects/praxis-core/docs/schema-flow.md`
+- `projects/praxis-core/docs/rfc-json-logic-semantics.md`
 
 ## ⚙️ Global Config (bootstrap)
 
 - Use `provideGlobalConfigTenant(...)` para definir o tenant e bloquear o bootstrap até a config remota ser carregada.
 - Se não houver tenant, use `provideGlobalConfigReady()` para apenas aguardar o carregamento remoto.
 
+## `resourcePath` vs `resourceKey`
+
+No runtime Angular, os dois valores coexistem, mas cumprem papeis diferentes:
+
+- `resourcePath` e o endereco operacional usado para CRUD, fetch de schema e submit
+- `resourceKey` e a identidade semantica estavel recebida dos catalogos de discovery do backend
+
+Na pratica:
+
+- o backend publica links como `/schemas/surfaces?resource={resourceKey}` e `/schemas/actions?resource={resourceKey}`
+- o `ResourceDiscoveryService` segue esses links HATEOAS e recebe `resourceKey` de volta nos payloads de surfaces, actions e capabilities
+- os adapters de abertura preservam `resourceKey` no `context.resource` e o usam para gerar ids estaveis de runtime
+
+Regra de leitura:
+
+- se o problema for URL, submit, fetch ou schema, pense primeiro em `resourcePath`
+- se o problema for discovery semantico, contexto de surface/action ou identidade estavel, pense primeiro em `resourceKey`
+
+## `x-ui.analytics` no runtime
+
+O `@praxisui/core` trata `x-ui.analytics` como a projeção semantica analitica canonica vinda do backend.
+
+- o backend publica `x-ui.analytics.projections[]` com `intent`, `source`, `bindings`, `defaults` e `preferredFamilies`
+- o `AnalyticsPresentationResolver` escolhe a familia de apresentacao no runtime
+- `praxis-charts` continua sendo apenas um renderer possivel; ele nao vira a semantica-base do contrato
+
+Regra atual do resolver:
+
+- se houver uma projection com `preferredFamilies` compativel, ela orienta a escolha
+- chart automatico so acontece quando a semantica temporal for inequivoca
+- `analytic-table` nao e a sobra do resolver; ela e uma familia canonica escolhida quando a projection continua valida, mas nao e chart inequivoco
+- nos casos ambiguos, o fallback conservador e `analytic-table`
+- se o host nao expuser `analytic-table` e a semantica continuar ambigua, o resolver falha em vez de forcar `chart`
+- projections `timeseries` devem publicar `defaults.granularity` quando o renderer precisar executar `praxis.stats` sem heuristica local
+
+Shape publico da decisao:
+
+- `projectionId`: id da projection escolhida
+- `family`: familia resolvida (`chart`, `analytic-table`, `kpi`, `summary-list`)
+- `reason`: motivo explicito da decisao, util para debug e suporte
+
 ## 🌐 Global Actions (shell + widgets)
 
 O core agora suporta **ações globais** executadas por widgets e pelo Widget Shell, permitindo integrar navegação, dialog, toast, analytics, API e rotas dinâmicas de forma padronizada.
@@ -988,3 +1030,17 @@ Precedencia:
 Observacoes:
 - `valuePresentation` deve representar valor escalar de display/read-only; nao use para ranges, selections ou IDs semanticos
 - contratos legados como `format`, `numericFormat`, `currency` e `numberFormat` continuam aceitos como bridge de compatibilidade interna, mas novos metadados devem preferir `valuePresentation`
+
+## Analytics Contract Client
+
+`AnalyticsSchemaContractService` e o cliente canônico para hosts que precisam resolver `x-ui.analytics` a partir de `/schemas/filtered`.
+
+Regras:
+- reutiliza `SchemaMetadataClient` + `fetchWithETag`
+- devolve `PraxisXUiAnalytics` tipado
+- falha explicitamente quando `x-ui.analytics.projections[]` nao foi publicado
+
+Uso esperado:
+- `@praxisui/core` busca e valida o contrato semantico
+- bibliotecas verticais, como `@praxisui/charts`, especializam esse contrato para um renderer concreto
+- apps consumidores deixam de reimplementar fetch, cache, ETag e leitura manual de `x-ui.analytics`