@praxisui/core 8.0.0-beta.1 → 8.0.0-beta.12

package/README.md

@@ -14,6 +14,18 @@
 - Keep icon, config and dynamic widget infrastructure aligned in the host app
 - Avoid duplicating low-level primitives across multiple business libraries
 
+## 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.
@@ -120,6 +132,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
@@ -179,6 +227,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)
@@ -208,6 +278,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.
@@ -274,7 +359,7 @@ definition: {
 ```ts
 shell: {
   actions: [
-    { id: 'back', icon: 'arrow_back', command: 'global:navigation.back' }
+    { id: 'back', icon: 'arrow_back', globalAction: { actionId: 'navigation.back' } }
   ]
 }
 ```
@@ -1014,6 +1099,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;
@@ -1021,6 +1109,8 @@ export interface AccessibilityConfig;
 
 // Serviços
 export class TableConfigService;
+export class PraxisCollectionExportService;
+export class PraxisHttpCollectionExportProvider;
 
 // Helper Functions
 export function createDefaultTableConfig(): TableConfig;
@@ -1029,10 +1119,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;