@praxisui/page-builder 8.0.0-beta.20 → 8.0.0-beta.22

package/README.md

@@ -36,12 +36,14 @@ Peer dependencies (Angular v20):
 
 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.
+- `FloatingToolbarComponent` para ações de página/canvas e ações contextuais do widget selecionado no runtime `praxis-dynamic-page`. Quando o widget possui `WidgetShell` com cabeçalho visível, as ações editoriais transitórias entram no próprio header do shell; quando não há header, o runtime usa uma toolbar contextual de fallback. Em ambos os casos o widget ativo fica identificado e pode abrir assistente com contexto, configuração e remoção governada sem persistir controles editoriais no `shell.actions`.
 - `ConnectionEditorComponent` para inspecionar, criar e remover conexoes canonicas em `composition.links`.
 - `WidgetShellEditorComponent` e `DynamicPageConfigEditorComponent` para authoring de shell/canvas sem redefinir a semantica canonica de composicao.
 
 Conexoes continuam pertencendo ao contrato `WidgetPageDefinition`. O editor visual do Page Builder cria, remove e edita links inline preservando o envelope canonico `page.composition.links`, incluindo `condition` em Json Logic, `policy` operacional e `transform` canônico, sem introduzir modelo paralelo de grafo. O historico de desfazer/refazer do editor e transitorio: ele reemite snapshots canonicos por `pageChange`, mas nao persiste estado de historico dentro da pagina.
 
+Cada link persistido usa `CompositionLink.id` como identidade estavel. Superficies de authoring tambem devem usar `id` ao criar ou remover links; aliases como `linkId` nao fazem parte do contrato canonico.
+
 O roadmap tecnico para evoluir o editor radial esta registrado em [`connection-editor-reference-study.md`](./connection-editor-reference-study.md).
 
 Nested component ports devem ser modeladas no mesmo contrato `composition.links`, usando `component-port + nestedPath`.
@@ -101,6 +103,12 @@ Para gerar uma página a partir de um prompt usando o backend canônico do `prax
 
 O chrome conversacional do assistente usa `PraxisAiAssistantShellComponent` de `@praxisui/ai`, mas a presença minimizada deve ser renderizada pelo shell da aplicação com `PraxisAiAssistantSessionHostComponent`, lendo o `PraxisAssistantSessionRegistryService`. O Page Builder apenas registra sua sessão com identidade estável e contexto `Page Builder`; a identidade pública continua sendo o copiloto semântico Praxis. 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`.
 
+O composer do Page Builder IA segue o padrão atual de chats LLM: a ação de envio é icon-only, com `aria-label` semântico para gerar preview. O texto não deve aparecer como label visual do botão.
+
+Ao minimizar uma sessão com contexto preservado, o assistente recolhe para o próprio botão `auto_awesome` do Page Builder. O botão troca seu nome acessível para reabrir o copiloto e exibe estado visual minimizado, sem criar um dock local paralelo ao host global de sessões.
+
+A barra de título do assistente deve ser derivada do contexto de abertura. O Page Builder fornece título, subtítulo e badge de modo diferentes para autoria de página, autoria focada em widget, revisão de preview e continuação governada, em vez de exibir uma descrição estática do produto.
+
 ### Agentic Authoring Manifest
 
 `PRAXIS_PAGE_BUILDER_AUTHORING_MANIFEST` declara o contrato executável de authoring do pacote e é exportado pelo `public-api` de `@praxisui/page-builder`.
@@ -111,7 +119,7 @@ As fronteiras canônicas são:
 - o documento persistido continua sendo `WidgetPageDefinition`;
 - `UiCompositionPlan` é apenas o plano intermediário de IA e deve compilar antes do preview/apply local;
 - wiring persistido usa `page.composition.links`, incluindo `nestedPath` para component ports internas;
-- o Page Builder não redefine inputs de widgets filhos. Edições de `definition.inputs` devem delegar para o manifesto do componente filho ou para `ComponentDocMeta.configEditor`;
+- o Page Builder não redefine inputs de widgets filhos. Edições de `definition.inputs` devem delegar para `ComponentDocMeta.authoringManifestRef` ou `ComponentDocMeta.configEditor` publicado pela lib dona do componente;
 - `pageIdentity` e ETag pertencem ao fluxo de persistência do `praxis-config-starter` e não entram no documento runtime da página.
 
 ```ts
@@ -155,6 +163,7 @@ Fluxo canônico:
 - Para cenarios corporativos, mantenha streaming e diagnosticos como capacidades opt-in do host. Streaming melhora feedback percebido em prompts curtos ou ambiguos; diagnosticos exibem prompt/contexto/catalogos e devem ficar restritos a auditoria, suporte ou ambientes controlados.
 - `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.
+- Enquanto o contrato LLM do Page Builder for metadata-only para anexos, o shell agentic deve ocultar a acao de anexar e desabilitar anexos colados. Nao exponha seletor de arquivo ou paste de imagem como se a LLM fosse processar pixels, PDF ou conteudo binario.
 - Quando `resolveIntent` retornar candidatos ambiguos, o Page Builder deve preservar `quickReplies` como chips clicaveis ricos. Campos como `description`, `icon`, `tone` e `contextHints` pertencem ao contrato do backend e nao devem ser recriados ou descartados no frontend.
 - Hosts podem habilitar `[agenticAuthoringIncludeLlmDiagnostics]="true"` apenas em cenarios de auditoria/debug. O input adiciona `contextHints.includeLlmDiagnostics=true` nas chamadas `resolveIntent` e, quando o backend retorna `llmDiagnostics`, o Page Builder mostra esse JSON em um painel tecnico separado da conversa. O padrao permanece desligado para nao expor prompt/contexto operacional em fluxos comuns.
 - Para criacao de dashboard apos escolha de recurso, `previewPage` pode retornar `uiCompositionPlan.layoutPreset=resource-dashboard`; o builder deve aplicar esse plano como preview de pagina, nao tratar o artefato como fluxo restrito a formulario.
@@ -200,6 +209,99 @@ Exemplo com `praxis-rich-content`: o editor canônico é
 edita `definition.inputs.document`, `layout` e `rootClassName` sem criar uma DSL
 local de page-builder para blocos ricos.
 
+Exemplo com `praxis-chart`: o editor canônico publicado por
+`@praxisui/charts` usa um adaptador de widget sobre `PraxisChartConfigEditor`.
+O editor de domínio continua editando `PraxisXUiChartContract`; o adaptador
+devolve `{ inputs: { ...chartInputs, chartDocument } }` para que o runtime
+atualize `definition.inputs` sem lógica específica de chart no Page Builder.
+
+Exemplo com `praxis-table`: o editor canônico publicado por `@praxisui/table`
+usa um adaptador de widget sobre `PraxisTableConfigEditor`. O editor de domínio
+continua editando `TableAuthoringDocument`; o adaptador devolve
+`{ inputs: { ...tableInputs, config, resourcePath, horizontalScroll } }`,
+preservando `tableId` e `componentInstanceId` enquanto publica apenas inputs
+declarados pelo contrato público da tabela.
+
+Exemplo com `praxis-dynamic-form`: o editor canônico publicado por
+`@praxisui/dynamic-form` usa um adaptador de widget sobre
+`PraxisDynamicFormConfigEditor`. O editor de domínio continua editando
+`DynamicFormAuthoringDocument`; o adaptador devolve
+`{ inputs: { ...formInputs, config, mode, formId, componentInstanceId } }` e
+projeta preferências públicas como `backConfig`, `notifyIfOutdated`, `snoozeMs`
+e `autoOpenSettingsOnOutdated`. O Page Builder não interpreta campos, regras ou
+seções do formulário.
+
+Exemplo com `praxis-filter-form`: o editor canônico publicado por
+`@praxisui/dynamic-form` também usa `PraxisDynamicFormConfigEditor`, mas por um
+adaptador próprio de widget. O filtro consome o mesmo contrato `FormConfig`,
+enquanto o adaptador devolve somente os inputs públicos do filtro:
+`{ inputs: { ...filterInputs, config, formId, resourcePath, mode } }`.
+
+Exemplo com `praxis-files-upload`: o editor canônico publicado por
+`@praxisui/files-upload` usa um adaptador de widget sobre
+`PraxisFilesUploadConfigEditor`. O editor de domínio continua editando
+`FilesUploadConfig`; o adaptador devolve
+`{ inputs: { ...uploadInputs, config, filesUploadId, componentInstanceId } }`
+e preserva bindings públicos como `baseUrl`, `displayMode`, `context` e
+`enableCustomization`. O Page Builder não interpreta estratégia, limites,
+opções de backend, quotas ou rate-limit.
+
+Exemplo com `praxis-crud`: o editor canônico publicado por `@praxisui/crud`
+usa um adaptador de widget sobre `CrudMetadataEditorComponent`. O editor de
+domínio continua editando `CrudAuthoringDocument`/`CrudMetadata`; o adaptador
+devolve `{ inputs: { ...crudInputs, metadata, crudId, componentInstanceId } }`
+e preserva `context` e `enableCustomization`. O Page Builder não interpreta
+resource binding, tabela interna, open modes, ações ou defaults de
+modal/drawer.
+
+Exemplo com `praxis-list`: o editor canônico publicado por `@praxisui/list`
+usa um adaptador de widget sobre `PraxisListConfigEditor`. O editor de domínio
+continua editando `PraxisListConfig`; o adaptador devolve
+`{ inputs: { ...listInputs, config } }`, preservando `listId` e demais inputs
+do widget.
+
+Exemplo com `praxis-expansion`: o editor canônico publicado por
+`@praxisui/expansion` usa um adaptador de widget sobre
+`PraxisExpansionConfigEditor`. O editor de domínio continua editando
+`ExpansionMetadata`; o adaptador devolve
+`{ inputs: { ...expansionInputs, config } }`, preservando `expansionId` e demais
+inputs do widget. Para widgets recém-inseridos sem `config` inicial, o adaptador
+mantém um fallback estável para não sobrescrever edições durante change
+detection.
+
+Exemplo com `praxis-tabs`: o editor canônico publicado por `@praxisui/tabs`
+usa um adaptador de widget sobre `PraxisTabsConfigEditor`. O editor de domínio
+continua editando `TabsAuthoringDocument`; o adaptador devolve
+`{ inputs: { ...tabsInputs, config, tabsId } }`, preservando bindings como
+`tabsId` e `componentInstanceId` enquanto publica apenas os inputs consumidos
+pelo runtime.
+
+Exemplo com `praxis-stepper`: o editor canônico publicado por
+`@praxisui/stepper` usa um adaptador de widget sobre
+`PraxisStepperConfigEditor`. O editor de domínio continua editando
+`StepperMetadata`; o adaptador devolve
+`{ inputs: { ...stepperInputs, config, stepperId, selectedIndex } }`. Sub-editores
+internos de form/list/upload continuam pertencendo ao editor do stepper. Eles
+devem abrir em host aninhado próprio do `@praxisui/stepper`, mantendo o editor
+pai montado; o Page Builder apenas hospeda o editor publicado pela metadata.
+No fluxo de inclusão, `Apply` e `Save` do sub-editor devem atualizar o mesmo
+widget filho pendente, evitando duplicação de lista/upload dentro do step.
+
+## Child AI Authoring Manifests
+
+Componentes que suportam edições governadas por IA devem publicar
+`ComponentDocMeta.authoringManifestRef` na própria lib dona. O Page Builder usa
+esse sinal apenas para discovery, readiness e delegação; ele não recompila nem
+redeclara operações internas do componente filho.
+
+Exemplos já publicados pelo catálogo de componentes:
+- `praxis-table` -> `PRAXIS_TABLE_AUTHORING_MANIFEST`
+- `praxis-list` -> `PRAXIS_LIST_AUTHORING_MANIFEST`
+- `praxis-dynamic-form` -> `PRAXIS_DYNAMIC_FORM_AUTHORING_MANIFEST`
+- `praxis-tabs` -> `PRAXIS_TABS_AUTHORING_MANIFEST`
+- `praxis-stepper` -> `PRAXIS_STEPPER_AUTHORING_MANIFEST`
+- `praxis-expansion` -> `PRAXIS_EXPANSION_AUTHORING_MANIFEST`
+
 Catalogos conhecidos (exports):
 - `TABLE_AI_CAPABILITIES` - `@praxisui/table` (`praxis-table`)
 - `CRUD_AI_CAPABILITIES` - `@praxisui/crud` (`praxis-crud`)
@@ -226,6 +328,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.
 
+Links para acoes globais tambem pertencem a `composition.links`: use
+`composition.links[].to.kind = "global-action"` com `to.ref.actionId` e, quando necessario,
+`to.ref.payload`, `to.ref.payloadExpr` ou `to.ref.meta`. O Page Builder nao cria executor universal
+nem campos paralelos de comando; ele apenas materializa o `GlobalActionRef` governado que o runtime de composicao
+entrega.
+
 Para conectar portas de widgets internos em containers como `praxis-tabs` ou `praxis-expansion`, use `composition.links[].from/to.ref.nestedPath`.
 `ref.widget` continua sendo o owner top-level no canvas, e o ultimo segmento de `nestedPath` deve ser `kind: "widget"` com `key` estavel.