@praxisui/core 1.0.0-beta.7 → 2.0.0-beta.0

package/README.md

@@ -2,6 +2,18 @@
 
 > Biblioteca central com interfaces e serviços fundamentais para o Praxis UI Workspace
 
+## Documentation
+
+- Official documentation: https://praxisui.dev
+- Quickstart reference app: https://github.com/codexrodrigues/praxis-ui-quickstart
+- Recommended for: hosts that need the shared contracts, tokens, icons and base services used across `@praxisui/*`
+
+## When to use
+
+- Centralize shared contracts, tokens and utilities across Praxis UI packages
+- Keep icon, config and dynamic widget infrastructure aligned in the host app
+- Avoid duplicating low-level primitives across multiple business libraries
+
 ## 🌟 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.
@@ -35,6 +47,9 @@ A biblioteca `@praxisui/core` é o núcleo do Praxis UI Workspace, fornecendo in
 npm install @praxisui/core
 ```
 
+Exemplo completo (app de referência)
+- Quickstart: https://github.com/codexrodrigues/praxis-ui-quickstart
+
 ### Peer dependencies (Angular v20)
 
 - `@angular/core` `^20.0.0`
@@ -105,6 +120,153 @@ Observação: os IDs de widgets usados na página devem estar registrados via `C
   [`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.
 
+## 📄 Documentacao Tecnica da Lib
+
+- `projects/praxis-core/docs/connection-editor.md`
+- `projects/praxis-core/docs/dynamic-gridster-page.md`
+- `projects/praxis-core/docs/schema-flow.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.
+
+## 🌐 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.
+
+### 1) Providers (plug-and-play no host)
+
+```ts
+import {
+  providePraxisGlobalActions,
+  providePraxisToastGlobalActions,
+  providePraxisAnalyticsGlobalActions,
+} from '@praxisui/core';
+import { providePraxisDialogGlobalActions } from '@praxisui/dialog';
+
+providers: [
+  ...providePraxisGlobalActions({ dialog: false, toast: false, analytics: false }),
+  providePraxisDialogGlobalActions(),
+  providePraxisToastGlobalActions(),
+  providePraxisAnalyticsGlobalActions({ prefix: 'app' }),
+]
+```
+
+### 2) Mapeando outputs para ações globais
+
+`WidgetDefinition.outputs` pode apontar para ações globais:
+
+```ts
+definition: {
+  id: 'praxis-dynamic-form',
+  outputs: {
+    formSubmit: {
+      type: 'api.post',
+      params: { url: '/api/clientes', body: '${payload.formData}' }
+    }
+  }
+}
+```
+
+### 3) Ação global no Widget Shell
+
+```ts
+shell: {
+  actions: [
+    { id: 'back', icon: 'arrow_back', command: 'global:navigation.back' }
+  ]
+}
+```
+
+### 4) Catálogo básico de ações globais
+
+- `navigation.back`
+- `navigation.openExternal` → `{ url }`
+- `dialog.alert` → `{ title, message, variant }`
+- `dialog.prompt` → `{ title, message, placeholder, defaultValue }`
+- `dialog.open` → `{ componentId, inputs, size, data }`
+- `toast.success` / `toast.error` → `{ message }`
+- `clipboard.copy` → `{ text }`
+- `trackEvent` → `{ eventName, payload }`
+- `log` → `{ level, message, payload }`
+- `api.get` / `api.post` / `api.patch` → `{ url, params|body }`
+- `route.register` → `{ path, componentId|loadChildren, data?, resolve?, guards?, canMatch?, canActivateChild?, replace?, position? }`
+
+### 5) Rotas dinâmicas (route.register)
+
+Requer `componentId` **ou** `loadChildren`. Guards são resolvidos pelo host via `GLOBAL_ROUTE_GUARD_RESOLVER`.
+
+```ts
+// payload
+{
+  path: '/clientes/novo',
+  componentId: 'praxis-dynamic-page',
+  data: { pageId: 'clientes-novo' },
+  guards: ['auth', 'permission:clientes.create'],
+  position: 'before-wildcard'
+}
+```
+
+As rotas registradas são persistidas em `GlobalConfig.routes.dynamic`. O host deve re‑hidratar isso no bootstrap (ex.: ler `GlobalConfigService` e re‑aplicar com `route.register`).
+
+### 7) Output mapeado para ação global x conexões
+
+Quando `WidgetDefinition.outputs[output]` aponta para uma ação global (não `'emit'`), o evento **não** é repassado para conexões locais — a ação global tem prioridade.
+
+### 6) Estilo de toast
+
+O estilo padrão usa as classes `.pdx-toast-success` / `.pdx-toast-error`.  
+Inclua estilos equivalentes no app host (ou sobrescreva com `providePraxisToastGlobalActions`).
+
+## 🔎 Schema Viewer (para Showcases)
+
+Para exibir os metadados e schemas usados por um exemplo (ex.: na aba “Schema” de um showcase), use o componente `SchemaViewerComponent` e (opcionalmente) injete o contexto via `SCHEMA_VIEWER_CONTEXT`.
+
+```ts
+import { Component, Provider } from '@angular/core';
+import { PraxisTabs, TabsMetadata } from '@praxisui/tabs';
+import { SchemaViewerComponent, SCHEMA_VIEWER_CONTEXT } from '@praxisui/core';
+
+@Component({
+  standalone: true,
+  selector: 'app-tabs-showcase',
+  imports: [PraxisTabs, SchemaViewerComponent],
+  template: `
+    <!-- Aba Preview -->
+    <praxis-tabs [config]="tabs" tabsId="tabs-preview"></praxis-tabs>
+
+    <!-- Aba Schema -->
+    <praxis-schema-viewer [context]="schemaCtx"></praxis-schema-viewer>
+  `,
+  providers: [
+    {
+      provide: SCHEMA_VIEWER_CONTEXT,
+      useFactory: () => ({
+        componentId: 'praxis-tabs',
+        title: 'Tabs — Schema & Metadata',
+        rawConfig: {
+          group: { alignTabs: 'center', dynamicHeight: true },
+          tabs: [ { id: 't1', textLabel: 'Dados', content: [] } ],
+        } satisfies TabsMetadata,
+      }),
+    } as Provider,
+  ],
+})
+export class TabsShowcaseComponent {
+  tabs: TabsMetadata = { group: { dynamicHeight: true }, tabs: [] };
+  schemaCtx = {
+    componentId: 'praxis-tabs',
+    rawConfig: this.tabs,
+  };
+}
+```
+
+Campos opcionais do contexto (`SchemaViewerContext`):
+- `rawConfig` (JSON usado pelo exemplo), `effectiveConfig` (se houver merge de defaults);
+- `backendSchema` (OpenAPI/JSON Schema) e `schemaMeta` (path/operation/schemaType/schemaHash);
+- `normalizedFields` (se já normalizado; caso contrário, o componente aplica `SchemaNormalizerService`).
+
 ## 🧩 Compatibilidade
 
 - `@praxisui/core` `1.0.0-beta.x` → Angular `20.x`
@@ -322,7 +484,7 @@ interface SortingConfig {
   /** Habilitar ordenação */
   enabled: boolean;
 
-  /** Permitir ordenação múltipla */
+  /** Permitir ordenação múltipla (schema-only no runtime atual) */
   multiSort: boolean;
 
   /** Estratégia de ordenação */
@@ -339,6 +501,8 @@ interface SortingConfig {
 }
 ```
 
+Observação enterprise: `multiSort` está disponível no contrato de schema, porém no runtime atual deve ser tratado como `schema-only` (apenas 1 critério de ordenação efetivo).
+
 ## 🎨 Configurações de Aparência
 
 ### TableAppearanceConfig
@@ -508,7 +672,8 @@ export class MyComponent {
     this.configService.setConfig(this.tableConfig);
 
     // Verificar recursos
-    const hasMultiSort = this.configService.isFeatureEnabled('multiSort');
+    // No runtime atual, multiSort permanece schema-only.
+    const hasMultiSort = false;
     const hasBulkActions = this.configService.isFeatureEnabled('bulkActions');
     const hasExport = this.configService.isFeatureEnabled('export');