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

package/README.md

@@ -14,6 +14,33 @@
 - 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
+canonical ordered content of a form column. Items with `kind: 'field'` reference
+`fieldMetadata[].name`; items with `kind: 'richContent'` host visual content and
+do not participate in `fieldMetadata`, `formData`, or submit payloads.
+
+`FormColumn.fields` is still accepted as migration input and as a derived
+projection of `kind: 'field'` items. New authors and tools should use `items[]`
+as the canonical source and the helpers exported from
+`form-layout-items.model`.
+
 ## 🌟 Visão Geral
 
 A biblioteca `@praxisui/core` é o núcleo do Praxis UI Workspace, fornecendo interfaces robustas, serviços base e utilitários essenciais para todas as outras bibliotecas do ecossistema. Com a arquitetura unificada, oferece uma experiência de desenvolvimento consistente e type-safe.
@@ -59,6 +86,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 +147,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
@@ -150,6 +222,29 @@ Regra de plataforma: não crie editor local no host para uma semântica que já
 tem dono canônico. Corrija ou publique o `configEditor` no metadata da lib dona
 do componente.
 
+### Component AI authoring manifests
+
+`ComponentDocMeta.authoringManifestRef` é a superfície pública canônica para um
+componente declarar que possui manifesto executável de authoring por IA. O
+manifesto continua pertencendo à lib dona do componente; hosts e page builders
+devem usar esse campo para discovery, delegação e readiness, não para redefinir
+operações internas localmente.
+
+Contrato esperado:
+
+```ts
+registry.register({
+  id: 'praxis-table',
+  selector: 'praxis-table',
+  component: PraxisTable,
+  friendlyName: 'Praxis Table',
+  authoringManifestRef: {
+    componentId: 'praxis-table',
+    source: 'PRAXIS_TABLE_AUTHORING_MANIFEST',
+  },
+});
+```
+
 ### Widget Shell body layout
 
 `WidgetShellConfig.bodyLayout` declares how projected widget content should use
@@ -170,6 +265,28 @@ state, because the fill body intentionally hides overflow.
   [`public-api.ts`](https://github.com/codexrodrigues/praxis/blob/main/frontend-libs/praxis-ui-workspace/projects/praxis-core/src/public-api.ts)
   para a lista consolidada de serviços, tokens, modelos e utilitários disponíveis para importação.
 
+### Collection Export
+
+`PraxisCollectionExportService` é o contrato canônico para exportação de coleções usado por Table, List e próximos componentes de dados.
+
+- sem provider registrado, CSV/JSON local usa `loadedItems` e aplica escape de fórmulas para planilhas;
+- com `providePraxisHttpCollectionExportProvider()`, o host registra o provider HTTP oficial;
+- o provider HTTP envia `POST /{resourcePath}/export` usando `API_URL`;
+- escopos remotos `filtered` e `all` omitem `loadedItems` por padrão e delegam query/sort/paginação/seleção ao backend;
+- a resposta pode ser um arquivo binário com `content-disposition` ou um `PraxisCollectionExportResult` JSON;
+- resultados JSON suportam `status: 'completed' | 'deferred'`, `downloadUrl`, `jobId`, `warnings` e `metadata`;
+- resultados `completed` sem `content` nem `downloadUrl` são tratados como erro de contrato pelo runtime.
+
+```ts
+import { providePraxisHttpCollectionExportProvider } from '@praxisui/core';
+
+export const appConfig = {
+  providers: [
+    providePraxisHttpCollectionExportProvider(),
+  ],
+};
+```
+
 ## 📄 Documentacao Tecnica da Lib
 
 - `projects/praxis-core/docs/connection-editor.md` (historico legado; fora do fluxo ativo)
@@ -199,6 +316,76 @@ 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`.
+
+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`
+- detalhe governado: `detail.kind = surface`, `surfaceId`, `presentation`, `preferredWidget`, `mode`
+- UX de referência: `display.preset`, `usage`, `density`, `selectedLayout`, `resultLayout`, `fields`, `secondaryPropertyPaths`, `badgePropertyPaths`
+
+O bloco `display` descreve intenção de apresentação, não implementação visual local.
+Presets como `directory`, `reference`, `status`, `hierarchical`, `rich` e
+`compact` permitem que a mesma option-source seja usada em formulário, filtro,
+tabela editável, dashboard ou revisão sem duplicar regras no host. O runtime
+pode aplicar overrides locais quando o contexto exigir, mas a semântica
+preferencial continua no `optionSource`.
+Use `display.fields[]` para publicar subinformações ricas do resultado, como
+`cargo`, `departamento`, `dataAdmissao`, `status` ou métricas. Cada campo carrega
+`propertyPath`, `label`, `icon`, `presentation`, `tone` e `format`; o endpoint de
+option-source pode materializar esses campos em `OptionDTO.extra.richFields[]`
+para que runtimes exibam ícones, chips, badges ou valores formatados sem
+heurística local.
+
+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
 
 O `@praxisui/core` trata `x-ui.analytics` como a projeção semantica analitica canonica vinda do backend.
@@ -265,7 +452,7 @@ definition: {
 ```ts
 shell: {
   actions: [
-    { id: 'back', icon: 'arrow_back', command: 'global:navigation.back' }
+    { id: 'back', icon: 'arrow_back', globalAction: { actionId: 'navigation.back' } }
   ]
 }
 ```
@@ -282,6 +469,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)
@@ -1005,6 +1193,9 @@ export interface TableAppearanceConfig;
 export interface ToolbarConfig;
 export interface TableActionsConfig;
 export interface ExportConfig;
+export interface PraxisCollectionExportRequest;
+export interface PraxisCollectionExportProvider;
+export interface PraxisCollectionSelectionState;
 export interface MessagesConfig;
 export interface LocalizationConfig;
 export interface PerformanceConfig;
@@ -1012,6 +1203,8 @@ export interface AccessibilityConfig;
 
 // Serviços
 export class TableConfigService;
+export class PraxisCollectionExportService;
+export class PraxisHttpCollectionExportProvider;
 
 // Helper Functions
 export function createDefaultTableConfig(): TableConfig;
@@ -1020,10 +1213,13 @@ export function isTableConfigV2(config: any): config is TableConfig;
 export function cloneTableConfig(config: TableConfig): TableConfig;
 export function mergeTableConfigs(base: TableConfig, override: Partial<TableConfig>): TableConfig;
 export function getEssentialConfig(config: TableConfig): Partial<TableConfig>;
+export function providePraxisHttpCollectionExportProvider();
 
 // Type Aliases
 export type TableConfig = TableConfigV2;
 export type TableConfigModern = TableConfigV2;
+export type PraxisExportFormat;
+export type PraxisExportScope;
 
 // Legacy (Deprecated)
 export type LegacyTableConfig = TableConfig;