@praxisui/expansion 8.0.0-beta.2 → 8.0.0-beta.21

package/README.md

@@ -130,9 +130,37 @@ const expansionConfig: ExpansionMetadata = {
 };
 ```
 
+## Nested Ports e Conexoes
+
+Para conectar widgets dentro de paineis a estado ou widgets externos, use `composition.links` com endpoint `component-port + nestedPath`.
+
+Exemplo de output de chart dentro do painel `analytics`:
+
+```json
+{
+  "kind": "component-port",
+  "ref": {
+    "widget": "expansion-widget",
+    "nestedPath": [
+      { "kind": "panel", "id": "analytics", "index": 0 },
+      { "kind": "widget", "key": "payroll-chart", "componentType": "praxis-chart" }
+    ],
+    "port": "pointClick",
+    "direction": "output"
+  }
+}
+```
+
+Regras:
+
+- `ref.widget` e a instancia top-level de `praxis-expansion`;
+- o segmento terminal deve ser `kind: "widget"` com `key` estavel;
+- `widgetEvent` permanece como bridge avancada/legado, nao como contrato principal;
+- inputs nested devem atualizar o config declarativo do widget filho, inclusive quando o painel ainda nao montou por lazy loading.
+
 ## Action Row por painel
 
-Adicione botões de ação no rodapé do painel com `actionButtons`. O evento é reemitido via `widgetEvent` com `output: 'action'`.
+Adicione botões de ação no rodapé do painel com `actionButtons`. O evento é reemitido via `widgetEvent` com `output: 'action'`; trate esse fluxo como bridge avancada/legado para acoes de painel, nao como modelo principal de nested component ports.
 
 ```ts
 const expansionConfig: ExpansionMetadata = {
@@ -205,6 +233,40 @@ O componente expõe métodos para controlar a expansão por índice (numérico)
 
 Cada evento inclui `{ panelId?: string; panelIndex: number }` (ou `expanded: boolean` no caso de `expandedChange`).
 
+## Agentic Authoring
+
+O contrato executavel de authoring fica em `PRAXIS_EXPANSION_AUTHORING_MANIFEST`.
+Ele modela edicoes em `ExpansionMetadata` por operacoes atomicas sobre paineis,
+cabecalhos, conteudo lazy, estado expandido/desabilitado e comportamento do
+accordion.
+
+Quando `enableCustomization` esta ativo, o runtime abre o `PraxisAiAssistantShellComponent`
+com contexto semantico dos paineis e registra a sessao no dock global de assistentes.
+O assistente envia estado atual, perfil dos paineis, campos de schema e referencia ao
+manifesto de authoring para a IA. Patches JSON livres nao sao aplicados no runtime:
+mudancas locais devem nascer de um `componentEditPlan` validado pelo manifesto, e
+regras compartilhadas seguem por `domain-rules/intake`.
+
+Cobertura principal:
+
+- `panel.add`, `panel.remove`, `panel.order.set`
+- `panel.title.set`, `panel.description.set`, `panel.icon.set`
+- `panel.disabled.set`
+- `behavior.multiExpand.set`
+- `behavior.defaultExpanded.set`
+- `panel.content.set`
+
+As operacoes preservam `panels[].id` como identidade canonica. Remover um painel
+com `content`, `widgets` ou `actionButtons` exige confirmacao explicita. Quando
+`accordion.multi` estiver desabilitado, somente um painel pode ficar expandido por
+padrao; o authoring deve colapsar os demais ou falhar validacao.
+
+Cada operacao declara `target.resolver`, `preconditions`, `validators`,
+`affectedPaths`, `effects` e `submissionImpact` tipado. Edicoes de conteudo de
+painel podem afetar dados schema-backed porque `panels[].content` hospeda
+`FieldMetadata[]`; widgets filhos continuam governados pelos contratos dos
+respectivos componentes.
+
 ## Tokens de Estilo por instância
 
 Os tokens opcionais em `appearance.tokens` permitem customizações rápidas por instância; por exemplo: