@praxisui/tabs 8.0.0-beta.2 → 8.0.0-beta.20

package/README.md

@@ -75,13 +75,46 @@ Inputs
 - `componentInstanceId?: string` Opcional para desambiguar múltiplas instâncias com o mesmo `tabsId` na mesma rota.
 - `form?: FormGroup` FormGroup opcional para campos dinâmicos declarados em `content`.
 - `context?: any` Contexto propagado a widgets internos (via `DynamicWidgetLoader`).
+- `selectedIndex?: number` Índice ativo controlado por composição; não reemite `selectedIndexChange`.
 - `enableCustomization?: boolean` Exibe botão de edição quando verdadeiro (abre o editor).
 
 Outputs
 - `selectedIndexChange: number` Índice selecionado atualizado (ambos modos).
 - `selectedTabChange: MatTabChangeEvent` Evento nativo do MatTabGroup.
 - `focusChange, animationDone, indexFocused, selectFocusedIndex` Eventos nativos do Angular Material.
-- `widgetEvent: { tabId?, tabIndex?, linkId?, linkIndex?, sourceId, output?, payload? }` Reemissão de eventos dos widgets internos com contexto da aba/link.
+- `widgetEvent: WidgetEventEnvelope` Bridge avançada/legado para transporte de eventos dos widgets internos com contexto da aba/link. Para conexões novas de widgets internos, use `composition.links` com `component-port + nestedPath`.
+
+## Uso Controlado por Composição
+
+`selectedIndex` é a porta pública para controlar a aba ativa a partir de estado externo ou de outro componente. Quando esse input é aplicado, o componente atualiza a aba ativa sem reemitir `selectedIndexChange`, evitando ciclos entre `state -> selectedIndex` e `selectedIndexChange -> state`.
+
+Padrão recomendado para páginas dinâmicas:
+
+- grave a seleção do usuário com `selectedIndexChange -> state`;
+- projete o estado de volta com `state -> selectedIndex`;
+- declare `selectedIndex` depois de `config` em `bindingOrder`, para que a configuração seja carregada antes da seleção controlada;
+- não persista `inputs.selectedIndex` estático em recipes quando a seleção vem de `composition.links`.
+
+Quando existe configuração persistida por `tabsId`, o valor controlado por `selectedIndex` vence a restauração local depois do carregamento da config. Essa projeção controlada não grava uma nova preferência no storage; somente interações diretas do usuário persistem seleção. Isso mantém o estado canônico da composição como fonte de verdade da navegação ativa sem transformar navegação transitória em configuração salva. Em modo `nav`, o índice controla `nav.links`; em modo `group`, controla `tabs`.
+
+Exemplo canônico:
+
+```json
+{
+  "links": [
+    {
+      "id": "tabs.selectedIndexChange->state.navigation.activeTabIndex",
+      "from": { "kind": "component-port", "ref": { "widget": "workspaceTabs", "port": "selectedIndexChange" } },
+      "to": { "kind": "state", "ref": { "path": "navigation.activeTabIndex", "layer": "values", "write": true } }
+    },
+    {
+      "id": "state.navigation.activeTabIndex->tabs.selectedIndex",
+      "from": { "kind": "state", "ref": { "path": "navigation.activeTabIndex", "layer": "values" } },
+      "to": { "kind": "component-port", "ref": { "widget": "workspaceTabs", "port": "selectedIndex" } }
+    }
+  ]
+}
+```
 
 Persistência
 - Quando `tabsId` é fornecido, a configuração é salva/recuperada em `AsyncConfigStorage` na chave `tabs:<component_id>`.
@@ -110,8 +143,8 @@ export interface TabsMetadata {
   behavior?: { lazyLoad?: boolean; closeable?: boolean; reorderable?: boolean };
   accessibility?: { highContrast?: boolean; reduceMotion?: boolean };
   group?: { alignTabs?: 'start' | 'center' | 'end'; headerPosition?: 'above'|'below'; selectedIndex?: number; dynamicHeight?: boolean; disableRipple?: boolean; disablePagination?: boolean; fitInkBarToContent?: boolean; stretchTabs?: boolean; color?: 'primary'|'accent'|'warn'; backgroundColor?: 'primary'|'accent'|'warn'|undefined; animationDuration?: string; ariaLabel?: string; ariaLabelledby?: string; };
-  tabs?: Array<{ id?: string; textLabel?: string; disabled?: boolean; labelClass?: string|string[]; bodyClass?: string|string[]; content?: any[]; widgets?: WidgetDefinition[] }>;
-  nav?: { links: Array<{ id?: string; label: string; disabled?: boolean; content?: any[]; widgets?: WidgetDefinition[] }>; selectedIndex?: number; disableRipple?: boolean; disablePagination?: boolean; fitInkBarToContent?: boolean; stretchTabs?: boolean; color?: 'primary'|'accent'|'warn'; backgroundColor?: 'primary'|'accent'|'warn'|undefined; animationDuration?: string; ariaLabel?: string; ariaLabelledby?: string };
+  tabs?: Array<{ id?: string; textLabel?: string; icon?: string; disabled?: boolean; visible?: boolean; labelClass?: string|string[]; bodyClass?: string|string[]; content?: any[]; widgets?: WidgetDefinition[] }>;
+  nav?: { links: Array<{ id?: string; label: string; icon?: string; disabled?: boolean; visible?: boolean; content?: any[]; widgets?: WidgetDefinition[] }>; selectedIndex?: number; disableRipple?: boolean; disablePagination?: boolean; fitInkBarToContent?: boolean; stretchTabs?: boolean; color?: 'primary'|'accent'|'warn'; backgroundColor?: 'primary'|'accent'|'warn'|undefined; animationDuration?: string; ariaLabel?: string; ariaLabelledby?: string };
 }
 ```
 
@@ -146,18 +179,49 @@ Quick Setup
 - `openQuickSetup()` abre `TabsQuickSetupComponent` para criação rápida de abas/links.
 - `applied$`/`saved$` aplicam a configuração ao componente.
 
+## Agentic Authoring
+
+`@praxisui/tabs` publica `PRAXIS_TABS_AUTHORING_MANIFEST` para orientar edições assistidas por IA sobre `TabsMetadata`.
+
+- **Editable targets:** `tab`, `tabLabel`, `tabIcon`, `tabContent`, `activeTab`, `visibility`, `disabledState` e `layout`.
+- **Operation families:** `tab.add`, `tab.remove`, `tab.label.set`, `tab.icon.set`, `tab.order.set`, `tab.disabled.set`, `tab.visible.set`, `tab.active.set`, `layout.variant.set` e `tab.content.set`.
+- **Validation:** ids de abas/links devem ser estáveis e únicos, remoção destrutiva exige confirmação, `group` e `nav` não devem virar modos primários concorrentes, e o round-trip precisa preservar ordem, ids e selected index.
+- **Runtime/editor parity:** `tabs[].icon`, `tabs[].visible`, `nav.links[].icon` e `nav.links[].visible` são campos canônicos editáveis; itens com `visible: false` não são renderizados na navegação.
+- **Registry projection:** o manifesto é exportado no `public-api` e projetado em `components['praxis-tabs'].authoringManifest` pelo AI Registry.
+
 ## Eventos e Conexões
 
-`widgetEvent` reemite eventos de widgets internos com contexto da origem, permitindo conexões no Builder/Graph:
+Para conexoes canonicas de widgets internos, use `composition.links` com endpoint `component-port + nestedPath`.
+
+Exemplo de output de uma lista dentro da primeira tab:
+
+```json
+{
+  "kind": "component-port",
+  "ref": {
+    "widget": "tabs-widget",
+    "nestedPath": [
+      { "kind": "tab", "id": "employees-list", "index": 0 },
+      { "kind": "widget", "key": "employees-list", "componentType": "praxis-list" }
+    ],
+    "port": "itemClick",
+    "direction": "output"
+  }
+}
+```
+
+Regras:
+
+- `ref.widget` e a instancia top-level de `praxis-tabs`;
+- `nestedPath` e relativo a essa instancia e deve terminar em `kind: "widget"` com `key` estavel;
+- `ref.port` e a porta real do widget filho;
+- inputs para filhos nested devem atualizar a configuracao declarativa do filho, nao depender de dot-path publico sobre `config`.
+
+`widgetEvent` continua existindo como bridge avancada/legado para transporte de eventos internos com contexto da origem:
 
 - Forma do evento: `{ tabId?, tabIndex?, linkId?, linkIndex?, sourceId, output?, payload }`.
-- De um componente interno para fora:
-  - From: `{ widget: '<key do tabs>', output: 'widgetEvent' }`
-  - Map (exemplo tabela interna): `payload.payload.id`
-  - To: `<widget externo>.<input>`
-- De fora para um componente interno (dot-path):
-  - Grupo: `inputs.config.tabs[<idx>].widgets[<widx>].inputs.<input>`
-  - Nav: `inputs.config.nav.links[<idx>].widgets[<widx>].inputs.<input>`
+- Nao use `widgetEvent` como caminho principal para authoring novo de nested ports.
+- Nao use dot-path de `config.tabs[].widgets[]` como contrato publico para novos links nested.
 
 ## Lazy Load
 
@@ -167,7 +231,7 @@ Quick Setup
 ## Exemplo Mínimo
 
 ```html
-<praxis-tabs [config]="tabsCfg" [tabsId]="'cliente-tabs'" [enableCustomization]="true" (widgetEvent)="onWidgetEvent($event)"></praxis-tabs>
+<praxis-tabs [config]="tabsCfg" [tabsId]="'cliente-tabs'" [enableCustomization]="true"></praxis-tabs>
 ```
 
 ```ts