@praxisui/page-builder 3.0.0-beta.9 → 5.0.0-beta.0

package/README.md

@@ -1,22 +1,22 @@
 # @praxisui/page-builder
 
-Ferramentas de edicao para paginas dinamicas canonicas baseadas em `praxis-dynamic-page`, com builders visuais, palette, graph e integracao com `@praxisui/settings-panel`.
+Ferramentas de edicao para paginas dinamicas canonicas baseadas em `praxis-dynamic-page`, com palette, configuracao de pagina/widget e integracao com `@praxisui/settings-panel`.
 
 ## Documentation
 
-- Documentação oficial: https://praxisui.dev
-- Aplicação de referência: https://github.com/codexrodrigues/praxis-ui-quickstart
-- Indicado para: times que precisam montar dashboards e paginas metadata-driven com edicao visual corporativa
+- Documentacao oficial: https://praxisui.dev
+- Aplicacao de referencia: https://github.com/codexrodrigues/praxis-ui-quickstart
+- Indicado para: times que precisam configurar paginas metadata-driven sobre o runtime canonico
 
 ## When to use
 
-- Montar paginas dinamicas com widgets, conexoes e layout visual
-- Entregar experiencia de builder para usuarios internos ou squads de configuracao
+- Montar paginas dinamicas com widgets e layout visual sobre o runtime canonico
+- Entregar experiencia de configuracao de pagina/widget sem depender de editor visual de conexoes
 - Integrar page composition com IA, settings panel e contratos compartilhados do Praxis UI
 
-Inclui o conjunto de editores (Builder, Graph), paleta de componentes e toolbars para montar e inspecionar conexões entre widgets definidos por metadata (`WidgetPageDefinition` 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.
+O pacote permanece focado no shell canonico de authoring em torno de `praxis-dynamic-page`: palette, page settings, widget shell e catalogos de IA. A composicao declarativa de conexoes deve ser feita exclusivamente via JSON/configuracao canonica no `@praxisui/core`; os editores visuais legados de conexoes sairam do escopo ativo desta fase.
 
-## Instalação
+## Instalacao
 
 ```bash
 npm i @praxisui/page-builder
@@ -31,23 +31,22 @@ Peer dependencies (Angular v20):
 - `@praxisui/core` `*`
 - `@praxisui/settings-panel` `*`
 
-## Visão Geral
+## Visao Geral
 
-Este pacote expõe os editores e utilitários usados pelo builder canônico de página dinâmica:
-- `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, configurar widget, configurar card, salvar, pré‑visualizar).
+Este pacote expoe o shell ativo do builder canonico de pagina dinamica:
+- `ComponentPaletteDialogComponent` para adicionar widgets a pagina.
+- `FloatingToolbarComponent` e `TileToolbarComponent` para acoes rapidas de add/save/preview/configuracao.
+- visualizador inicial de conexoes somente leitura para inspecao de `composition.links`.
+- `WidgetShellEditorComponent` e `DynamicPageConfigEditorComponent` para authoring de shell/canvas sem redefinir a semantica canonica de composicao.
 
-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.
+Conexoes continuam pertencendo ao contrato `WidgetPageDefinition`, mas a criacao/manutencao delas nesta fase deve acontecer por JSON/configuracao canonica e nao por builder/graph/editor visual legado.
+O viewer ativo nesta fase existe apenas para inspecao contextual do contrato canonico e nao para editar links inline.
 
 ## 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.
+Para que o assistente de IA consiga configurar os inputs dos widgets, registre os catalogos de capacidades no bootstrap da aplicacao.
 
-Opção recomendada (registro automático via provider + InjectionToken):
+Opcao recomendada (registro automatico via provider + InjectionToken):
 
 ```ts
 import { bootstrapApplication } from '@angular/platform-browser';
@@ -70,7 +69,7 @@ bootstrapApplication(AppComponent, {
 });
 ```
 
-Registro manual (útil para apps que precisam customizar o mapa):
+Registro manual (util para apps que precisam customizar o mapa):
 
 ```ts
 import { registerWidgetAiCatalogs } from '@praxisui/page-builder';
@@ -88,8 +87,7 @@ Registro via token:
 
 ## Settings Panel Bridge
 
-Para abrir "Configurações da Página" e editores no painel lateral, o host deve
-registrar o bridge do Settings Panel:
+Para abrir "Configuracoes da Pagina" e editores de shell no painel lateral, o host deve registrar o bridge do Settings Panel:
 
 ```ts
 import { SETTINGS_PANEL_BRIDGE } from '@praxisui/core';
@@ -103,19 +101,19 @@ providers: [
 ]
 ```
 
-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`)
+Catalogos 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
 
-O builder canônico expõe os métodos utilitários de authoring sobre `praxis-dynamic-page`. Exemplo de uso no template:
+O builder canonico expoe authoring de shell/palette sobre `praxis-dynamic-page`. Exemplo de uso no template:
 
 ```html
 <praxis-dynamic-page-builder
@@ -124,89 +122,25 @@ O builder canônico expõe os métodos utilitários de authoring sobre `praxis-d
   [enableCustomization]="true"
   (pageChange)="onPageChange($event)">
 </praxis-dynamic-page-builder>
-
-<!-- Ações auxiliares -->
-<button (click)="page.openConnectionsGraph()">Conexões (Graph)</button>
-<button (click)="page.openConnectionsBuilder()">Conexões (Builder)</button>
-<button (click)="page.openConnectionsEditor()">Editor Visual (Dialog)</button>
 ```
 
-`page` é um `WidgetPageDefinition` (do `@praxisui/core`) contendo `widgets` e opcionalmente `connections`.
+`page` e um `WidgetPageDefinition` (do `@praxisui/core`) contendo `widgets` e opcionalmente `composition.links`. O envelope `composition` e o caminho `composition.links` formam a superficie canonica persistida para wiring da pagina, com `condition` em Json Logic e `policy` para comportamento operacional.
 
 ## 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:
+Cada widget pode declarar um `shell` para renderizar um card padronizado com cabecalho rico, acoes de contexto e controles de janela (expandir/recolher).
 
-```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)`.
+Quando uma acao e clicada, o shell:
+- dispara um evento para o page-builder (`emit`, ou `shell:<id>` por padrao) para uso em `composition.links`;
+- tenta despachar a acao para o componente interno via metodo `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" } }
-  }
-}
-```
+Voce pode definir presets globais na pagina e escolher um preset padrao para todos os cards por JSON no contexto da pagina.
 
 ## 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.
+O botao "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):
 
@@ -223,53 +157,26 @@ this.settingsPanel.open({
 });
 ```
 
-## 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.
-
-```ts
-import { Component } from '@angular/core';
-import { SettingsPanelService } from '@praxisui/settings-panel';
-import { ConnectionBuilderComponent } from '@praxisui/page-builder';
-import type { WidgetInstance, WidgetPageDefinition } from '@praxisui/core';
-
-@Component({ selector: 'app-page-tools', standalone: true })
-export class PageToolsComponent {
-  constructor(private settings: SettingsPanelService) {}
-
-  openBuilder(page: WidgetPageDefinition, widgets: WidgetInstance[]) {
-    this.settings.open({
-      id: 'grid-connections:builder',
-      title: 'Conexões (Builder)',
-      content: { component: ConnectionBuilderComponent, inputs: { page, widgets } },
-    });
-  }
-}
-```
-
-Para abrir o Graph visual como painel, utilize os métodos do componente da página (`page.openConnectionsGraph()`), que encapsulam o componente interno do gráfico.
-
-## Diálogo fullscreen (Graph/Editor Visual)
-
-O fluxo visual completo pode ser aberto em diálogo Material (fullscreen). Caso esteja usando o componente de página, utilize `page.openConnectionsEditor()` para abrir o editor visual; ele lida com a passagem de `page` e `widgets` e propaga o resultado em `pageChange` quando o usuário salva.
-
 ## Dicas
-- O Builder valida se o `output` existe no widget de origem e se o `input` existe no destino.
-- No Graph, ativar “Mostrar portas não conectadas” ajuda a descobrir possibilidades de ligação.
-- Tanto Builder quanto Graph funcionam com `WidgetPageDefinition` em string (JSON) ou objeto.
+
+- Trate `composition.links` como parte do contrato canonico salvo no JSON da pagina.
+- Use `composition.links[].condition` para guardas semanticas em Json Logic e `composition.links[].policy` para debounce/distinct/missing-value.
+- Quando precisar revisar ligacoes, prefira inspecao textual/versionada do contrato e do runtime, nao um editor visual legado.
 
 ## API (resumo)
 
 Exports deste pacote:
-- `ConnectionBuilderComponent`
 - `ComponentPaletteDialogComponent`
 - `FloatingToolbarComponent`
 - `TileToolbarComponent`
+- `WidgetShellEditorComponent`
+- `DynamicPageConfigEditorComponent`
+- `DynamicPageBuilderComponent`
 
-Integrações comuns:
-- `SettingsPanelService.open({ id, title, content: { component, inputs } })`
-- Métodos do componente da página: `openConnectionsGraph()`, `openConnectionsBuilder()`, `openConnectionsEditor()`
+Integracoes comuns:
+- `SettingsPanelService.open({ id, title, content: { component, inputs } })` para page settings e shell editors
 
 ## Links
+
 - Repo: https://github.com/codexrodrigues/praxis
 - Issues: https://github.com/codexrodrigues/praxis/issues