@praxisui/core 8.0.0-beta.0 → 8.0.0-beta.11

package/README.md

@@ -59,6 +59,15 @@ Exemplo completo (app de referência)
 
 ### 1) `PraxisIconDirective`
 
+Hosts devem carregar Material Symbols para ícones `mso:*` e Material Icons classic quando usarem `mi:*`, componentes legados baseados em ligature classic, ou `mat-icon.material-icons`. Sem Material Icons classic, a ligature pode aparecer como texto visível, por exemplo `clear` dentro de um select.
+
+Para alinhar tokens e superfícies Angular Material/Praxis, importe o asset canônico do pacote depois do tema Angular Material e do CSS do CDK Overlay:
+
+```scss
+@import "@angular/cdk/overlay-prebuilt.css";
+@import "@praxisui/core/theme-bridge.css";
+```
+
 ```ts
 import { Component } from '@angular/core';
 import { MatIconModule } from '@angular/material/icon';
@@ -111,6 +120,42 @@ export class GridDemoComponent {
 
 Observação: os IDs de widgets usados na página devem estar registrados via `ComponentMetadataRegistry` para que o carregador dinâmico resolva os componentes.
 
+#### Composition links e nested component ports
+
+O wiring persistido de páginas dinâmicas deve usar `page.composition.links`.
+`page.connections` é formato legado/residual e não deve ser usado para novas
+páginas ou exemplos.
+
+Para conectar componentes internos de containers como `praxis-tabs` e
+`praxis-expansion`, use endpoints `component-port` com `ref.nestedPath`:
+
+```json
+{
+  "kind": "component-port",
+  "ref": {
+    "widget": "tabs-widget",
+    "nestedPath": [
+      { "kind": "tab", "id": "analytics", "index": 0 },
+      { "kind": "widget", "key": "sales-chart", "componentType": "praxis-chart" }
+    ],
+    "port": "pointClick",
+    "direction": "output",
+    "componentType": "praxis-chart"
+  }
+}
+```
+
+Regras de plataforma:
+
+- `ref.widget` é sempre o owner top-level presente em `page.widgets`;
+- `nestedPath` é relativo ao owner e deve terminar com segmento
+  `kind: "widget"` contendo `key` estável;
+- `ref.port` representa a porta real do componente filho;
+- `widgetEvent` em containers compostos é bridge avançada/legado, não caminho
+  principal de authoring;
+- `bindingPath` e dot-path profundo não são endereço canônico para nested
+  component ports.
+
 ### Component config editors
 
 `ComponentDocMeta.configEditor` é a superfície pública canônica para um
@@ -199,6 +244,21 @@ 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.optionSource` e Entity Lookup
+
+`@praxisui/core` preserva `x-ui.optionSource` como contrato canônico de opções remotas e lookups de entidade publicados por `/schemas/filtered`.
+
+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`
+- seleção: `selectionPolicy.allowedStatuses`, `blockedStatuses`, `allowRetainInvalidExistingValue`
+- operação: `capabilities.byIds`, `navigateToDetail`, `create`, `auditSnapshot`
+- navegação: `detail.hrefTemplate`, `routeTemplate`, `openDetailMode`
+
+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
 
 O `@praxisui/core` trata `x-ui.analytics` como a projeção semantica analitica canonica vinda do backend.
@@ -265,7 +325,7 @@ definition: {
 ```ts
 shell: {
   actions: [
-    { id: 'back', icon: 'arrow_back', command: 'global:navigation.back' }
+    { id: 'back', icon: 'arrow_back', globalAction: { actionId: 'navigation.back' } }
   ]
 }
 ```