@praxisui/page-builder 7.0.0-beta.0 → 8.0.0-beta.1

package/README.md

@@ -28,6 +28,7 @@ Peer dependencies (Angular v20):
 - `@angular/forms` `^20.0.0`
 - `@angular/cdk` `^20.0.0`
 - `@angular/material` `^20.0.0`
+- `@praxisui/ai` `*`
 - `@praxisui/core` `*`
 - `@praxisui/settings-panel` `*`
 
@@ -53,6 +54,7 @@ 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 { RICH_CONTENT_AI_CAPABILITIES } from '@praxisui/rich-content';
 import { AppComponent } from './app/app.component';
 
 bootstrapApplication(AppComponent, {
@@ -62,6 +64,7 @@ bootstrapApplication(AppComponent, {
       useValue: {
         'praxis-table': TABLE_AI_CAPABILITIES,
         'praxis-crud': CRUD_AI_CAPABILITIES,
+        'praxis-rich-content': RICH_CONTENT_AI_CAPABILITIES,
       },
     },
     providePageBuilderWidgetAiCatalogs(),
@@ -75,16 +78,53 @@ Registro manual (util para apps que precisam customizar o mapa):
 import { registerWidgetAiCatalogs } from '@praxisui/page-builder';
 import { TABLE_AI_CAPABILITIES } from '@praxisui/table';
 import { CRUD_AI_CAPABILITIES } from '@praxisui/crud';
+import { RICH_CONTENT_AI_CAPABILITIES } from '@praxisui/rich-content';
 
 registerWidgetAiCatalogs({
   'praxis-table': TABLE_AI_CAPABILITIES,
   'praxis-crud': CRUD_AI_CAPABILITIES,
+  'praxis-rich-content': RICH_CONTENT_AI_CAPABILITIES,
 });
 ```
 
 Registro via token:
 - Use o InjectionToken `PAGE_BUILDER_WIDGET_AI_CATALOGS` para fornecer o mapa no host.
 
+## Agentic Authoring
+
+Para gerar uma página a partir de um prompt usando o backend canônico do `praxis-config-starter`, configure `PageBuilderAgenticAuthoringService` com o endpoint interno opt-in `/api/praxis/config/ai/authoring`.
+
+O chrome conversacional do assistente usa `PraxisAiAssistantShellComponent` de `@praxisui/ai`. O Page Builder continua dono da semântica agentic de página: resolução de intenção, preview, apply, save, reopen e compilação do plano validado para `WidgetPageDefinition`.
+
+```ts
+import { PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS } from '@praxisui/page-builder';
+
+providers: [
+  {
+    provide: PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS,
+    useValue: {
+      baseUrl: '/api/praxis/config/ai/authoring',
+      headersFactory: () => ({
+        'X-Tenant-ID': tenantId,
+        'X-User-ID': userId,
+        'X-Env': 'local',
+      }),
+    },
+  },
+]
+```
+
+Fluxo canônico:
+
+- `resolveIntent` envia prompt, pagina atual e widget selecionado para resolver operacao, recurso, schema, surface e elegibilidade.
+- `previewPage` envia o prompt junto de `intentResolution` elegivel e recebe `MinimalFormPlan` + `CompiledFormPatch`.
+- `resolveIntent` e `previewPage` tambem aceitam `sessionId`, `clientTurnId`, `conversationMessages`, `pendingClarification` e `attachmentSummaries` para que respostas curtas e contexto anexado continuem o turno sem reescrever o prompt no frontend.
+- `attachmentSummaries` deve conter apenas metadados serializaveis (`id`, `name`, `kind`, `mimeType`, `sizeBytes`, `source`, `hasPreview`). O frontend nao envia `File`, bytes, base64 nem URLs locais `blob:`. Quando uma pergunta de clarificacao nasce de um turno com anexos, o backend pode ecoar esses resumos em `pendingClarification.diagnostics.attachmentSummaries`; o Page Builder reenvia esse estado no proximo turno.
+- `PageBuilderAiAdapter.applyCompiledFormPatch` aplica somente `compiledFormPatch.patch.page` no runtime do builder.
+- `applyPage` persiste o mesmo `patch.page` em `ui_user_config`, com `componentType`, `componentId`, `scope` e `If-Match` delegados ao backend canônico.
+
+O frontend não deve persistir o envelope completo do patch como payload de runtime. O envelope fica para preview, auditoria e diagnóstico; o documento salvo é a página renderizável.
+
 ## Settings Panel Bridge
 
 Para abrir "Configuracoes da Pagina" e editores de shell no painel lateral, o host deve registrar o bridge do Settings Panel:
@@ -101,10 +141,32 @@ providers: [
 ]
 ```
 
+## Component Config Editors
+
+O page-builder não deve implementar editores locais para os inputs de cada
+widget. Quando um componente registra `ComponentDocMeta.configEditor`, o runtime
+canônico (`praxis-dynamic-page`) injeta a ação "Configurar conteudo" no shell do
+widget e abre o editor declarado pelo dono do componente.
+
+Fluxo canônico:
+
+- a lib dona registra `configEditor` em `ComponentMetadataRegistry`
+- o page-builder habilita customization e fornece `SETTINGS_PANEL_BRIDGE`
+- o editor recebe `{ inputs, widgetKey, widgetType }`
+- `Apply` atualiza `definition.inputs` sem fechar o painel; ele não é rollback transacional e pode ser observado pelo host imediatamente
+- `Save` atualiza `definition.inputs` e persiste a página quando houver `pageIdentity`
+- `Reset` restaura o estado interno do editor para o snapshot aberto; ele não desfaz automaticamente um `Apply` já emitido ao runtime/host
+
+Exemplo com `praxis-rich-content`: o editor canônico é
+`PraxisRichContentConfigEditor`, publicado por `@praxisui/rich-content`. Ele
+edita `definition.inputs.document`, `layout` e `rootClassName` sem criar uma DSL
+local de page-builder para blocos ricos.
+
 Catalogos conhecidos (exports):
 - `TABLE_AI_CAPABILITIES` - `@praxisui/table` (`praxis-table`)
 - `CRUD_AI_CAPABILITIES` - `@praxisui/crud` (`praxis-crud`)
 - `LIST_AI_CAPABILITIES` - `@praxisui/list` (`praxis-list`)
+- `RICH_CONTENT_AI_CAPABILITIES` - `@praxisui/rich-content` (`praxis-rich-content`)
 - `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`)
@@ -126,6 +188,12 @@ O builder canonico expoe authoring de shell/palette sobre `praxis-dynamic-page`.
 
 `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.
 
+Para conteudo editorial rico dentro da pagina, use um widget `praxis-rich-content`
+com `definition.inputs.document: RichContentDocument`. Isso evita criar uma DSL
+local de page-builder para cards, imagens, timelines ou blocos de apresentacao,
+e preserva `WidgetPageDefinition.widgets` como superficie unica de ocupacao do
+canvas.
+
 ## Widget Shell (Dashboard Cards)
 
 Cada widget pode declarar um `shell` para renderizar um card padronizado com cabecalho rico, acoes de contexto e controles de janela (expandir/recolher).
@@ -172,6 +240,8 @@ Exports deste pacote:
 - `WidgetShellEditorComponent`
 - `DynamicPageConfigEditorComponent`
 - `DynamicPageBuilderComponent`
+- `PageBuilderAgenticAuthoringService`
+- `PAGE_BUILDER_AGENTIC_AUTHORING_OPTIONS`
 
 Integracoes comuns:
 - `SettingsPanelService.open({ id, title, content: { component, inputs } })` para page settings e shell editors