@praxisui/page-builder 1.0.0-beta.5 → 1.0.0-beta.52

package/README.md

@@ -1,5 +1,12 @@
 # @praxisui/page-builder
 
+## 🔰 Exemplos / Quickstart
+
+Para ver esta biblioteca em funcionamento em uma aplicação completa, utilize o projeto de exemplo (Quickstart):
+
+- Repositório: https://github.com/codexrodrigues/praxis-ui-quickstart
+- O Quickstart demonstra a integração das bibliotecas `@praxisui/*` em um app Angular, incluindo instalação, configuração e uso em telas reais.
+
 Ferramentas de edição para páginas dinâmicas baseadas em Gridster. Inclui o conjunto de editores (Builder, Graph), paleta de componentes e toolbars para montar e inspecionar conexões entre widgets definidos por metadata (`GridPageDefinition` do `@praxisui/core`). Integra com o `@praxisui/settings-panel` para abrir editores em painel lateral e oferece um modo de diálogo fullscreen para edição visual.
 
 ## Instalação
@@ -24,12 +31,82 @@ Este pacote expõe os editores e utilitários usados pelo componente de página
 - `ConnectionBuilderComponent` — lista e edita conexões (from.output → to.input) com filtros, agrupamentos e validação.
 - `ConnectionGraph` (uso integrado) — visualiza nós/portas/arestas; suporta arrastar para criar conexões e abrir o Builder.
 - `ComponentPaletteDialog` — paleta para adicionar widgets à página.
-- `FloatingToolbar` e `TileToolbar` — ações rápidas (adicionar, conexões, configurações, salvar, pré‑visualizar).
+- `FloatingToolbar` e `TileToolbar` — ações rápidas (adicionar, conexões, configurar widget, configurar card, salvar, pré‑visualizar).
 
 Os editores podem ser abertos:
 - Via `SettingsPanelService` (painel lateral) — recomendado para fluxo dentro do app.
 - Como diálogo fullscreen (Material Dialog) para uma experiência imersiva de edição.
 
+## AI Capabilities Registration
+
+Para que o assistente de IA consiga configurar os inputs dos widgets, registre os catálogos de capacidades no bootstrap da aplicação.
+
+Opção recomendada (registro automático via provider + InjectionToken):
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { PAGE_BUILDER_WIDGET_AI_CATALOGS, providePageBuilderWidgetAiCatalogs } from '@praxisui/page-builder';
+import { TABLE_AI_CAPABILITIES } from '@praxisui/table';
+import { CRUD_AI_CAPABILITIES } from '@praxisui/crud';
+import { AppComponent } from './app/app.component';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    {
+      provide: PAGE_BUILDER_WIDGET_AI_CATALOGS,
+      useValue: {
+        'praxis-table': TABLE_AI_CAPABILITIES,
+        'praxis-crud': CRUD_AI_CAPABILITIES,
+      },
+    },
+    providePageBuilderWidgetAiCatalogs(),
+  ],
+});
+```
+
+Registro manual (útil para apps que precisam customizar o mapa):
+
+```ts
+import { registerWidgetAiCatalogs } from '@praxisui/page-builder';
+import { TABLE_AI_CAPABILITIES } from '@praxisui/table';
+import { CRUD_AI_CAPABILITIES } from '@praxisui/crud';
+
+registerWidgetAiCatalogs({
+  'praxis-table': TABLE_AI_CAPABILITIES,
+  'praxis-crud': CRUD_AI_CAPABILITIES,
+});
+```
+
+Registro via token:
+- Use o InjectionToken `PAGE_BUILDER_WIDGET_AI_CATALOGS` para fornecer o mapa no host.
+
+## Settings Panel Bridge
+
+Para abrir "Configurações da Página" e editores no painel lateral, o host deve
+registrar o bridge do Settings Panel:
+
+```ts
+import { SETTINGS_PANEL_BRIDGE } from '@praxisui/core';
+import { SettingsPanelService } from '@praxisui/settings-panel';
+
+providers: [
+  {
+    provide: SETTINGS_PANEL_BRIDGE,
+    useExisting: SettingsPanelService,
+  },
+]
+```
+
+Catálogos conhecidos (exports):
+- `TABLE_AI_CAPABILITIES` — `@praxisui/table` (`praxis-table`)
+- `CRUD_AI_CAPABILITIES` — `@praxisui/crud` (`praxis-crud`)
+- `LIST_AI_CAPABILITIES` — `@praxisui/list` (`praxis-list`)
+- `FORM_AI_CAPABILITIES` — `@praxisui/dynamic-form` (`praxis-dynamic-form`)
+- `FILES_UPLOAD_AI_CAPABILITIES` — `@praxisui/files-upload` (`praxis-files-upload`)
+- `STEPPER_AI_CAPABILITIES` — `@praxisui/stepper` (`praxis-stepper`)
+- `TABS_AI_CAPABILITIES` — `@praxisui/tabs` (`praxis-tabs`)
+- `EXPANSION_AI_CAPABILITIES` — `@praxisui/expansion` (`praxis-expansion`)
+
 ## Quick Start (usando a página Gridster)
 
 O componente de página dinâmica (parte do workspace) expõe métodos utilitários para abrir editores. Exemplo de uso no template:
@@ -50,6 +127,96 @@ O componente de página dinâmica (parte do workspace) expõe métodos utilitár
 
 `page` é um `GridPageDefinition` (do `@praxisui/core`) contendo `widgets` e opcionalmente `connections`.
 
+## Widget Shell (Dashboard Cards)
+
+Cada widget pode declarar um `shell` para renderizar um card padronizado com cabeçalho rico,
+ações de contexto e controles de janela (expandir/recolher). Exemplo:
+
+```json
+{
+  "widgets": [
+    {
+      "key": "dados-cadastrais",
+      "definition": { "id": "praxis-list", "inputs": { "listId": "dados", "config": {} } },
+      "layout": { "col": 1, "row": 1, "colSpan": 6, "rowSpan": 4 },
+      "shell": {
+        "kind": "dashboard-card",
+        "icon": "badge",
+        "title": "Dados Cadastrais",
+        "subtitle": "Servidor: Jéssica Techne",
+        "actions": [
+          { "id": "editar", "label": "Editar", "icon": "edit", "variant": "outlined", "emit": "editar" },
+          { "id": "imprimir", "label": "Imprimir", "icon": "print", "variant": "text", "emit": "imprimir" }
+        ],
+        "windowActions": { "collapsible": true, "expandable": true },
+        "appearance": {
+          "card": { "background": "#0b1220", "borderColor": "rgba(255,255,255,0.12)", "borderRadius": "16px" },
+          "header": { "titleColor": "#e6edf3", "subtitleColor": "#9fb0c4", "iconColor": "#8ab4ff" },
+          "typography": { "titleSize": "14px", "titleWeight": "600", "subtitleSize": "12px" }
+        }
+      }
+    }
+  ]
+}
+```
+
+Quando uma ação é clicada, o shell:
+- dispara um evento para o page-builder (`emit`, ou `shell:<id>` por padrão) para uso em `connections`;
+- tenta despachar a ação para o componente interno via método `handleShellAction(action)`.
+
+### Presets visuais (global)
+
+Você pode definir presets globais na página e escolher um preset padrão para todos os cards:
+
+```json
+{
+  "context": {
+    "ui": {
+      "shell": {
+        "preset": "dark-glass",
+        "presets": {
+          "dark-glass": {
+            "card": { "background": "#0b1220", "borderColor": "rgba(255,255,255,0.12)", "borderRadius": "16px" }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+O widget pode sobrescrever:
+
+```json
+{
+  "shell": {
+    "preset": "light-neutral",
+    "appearance": { "header": { "titleColor": "#1f2937" } }
+  }
+}
+```
+
+## Editor do Card (Shell)
+
+O botão "Configurar card" na toolbar do tile abre o editor de shell, permitindo editar
+titulo, subtitulo, icone e acoes do cabecalho. O editor grava os metadados no campo
+`shell` do widget.
+
+Para abrir via API (Settings Panel):
+
+```ts
+import { WidgetShellEditorComponent } from '@praxisui/page-builder';
+
+this.settingsPanel.open({
+  id: 'grid-widget-shell:table',
+  title: 'Configurar Card',
+  content: {
+    component: WidgetShellEditorComponent,
+    inputs: { shell: widget.shell },
+  },
+});
+```
+
 ## Abrindo editores via Settings Panel
 
 Para abrir o Builder/Graph em um painel lateral, injete o `SettingsPanelService` e forneça o conteúdo. O `ConnectionBuilderComponent` é exportado por este pacote.