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

package/src/lib/praxis-tabs.json-api.md

@@ -0,0 +1,978 @@
+---
+title: "praxis-tabs JSON API (Canonical)"
+slug: "praxis-tabs-json-api"
+doc_type: "api-reference"
+component: "praxis-tabs"
+document_kind: "json-api-canonical"
+reference_mode: "canonical"
+contract_format: "json"
+contract_source: "runtime-and-code"
+description: "Referencia canonica do contrato JSON do componente praxis-tabs."
+category: "components"
+sub_category: "tabs"
+audience:
+  - "frontend"
+  - "architect"
+  - "platform-team"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+source_of_truth:
+  - "projects/praxis-tabs/src/lib/praxis-tabs.ts"
+  - "projects/praxis-tabs/src/lib/praxis-tabs.spec.ts"
+  - "projects/praxis-tabs/src/lib/praxis-tabs-widget-event.spec.ts"
+  - "projects/praxis-tabs/src/lib/praxis-tabs.metadata.ts"
+  - "projects/praxis-tabs/src/lib/praxis-tabs-config-editor.ts"
+  - "projects/praxis-tabs/src/lib/quick-setup/tabs-quick-setup.component.ts"
+  - "projects/praxis-tabs/src/lib/ai/tabs-ai.adapter.ts"
+  - "projects/praxis-tabs/src/lib/ai/tabs-ai-capabilities.ts"
+  - "projects/praxis-tabs/src/lib/ai/tabs-context-pack.ts"
+source_of_truth_last_verified: "2026-03-05"
+last_updated: "2026-03-05"
+toc: true
+sidebar: true
+tags:
+  - "json-api"
+  - "canonical-contract"
+  - "praxis-tabs"
+api_stability: "canonical"
+schema_verified: true
+runtime_verified: false
+editor_coverage_verified: false
+runtime_scope: "public"
+legacy_paths_present: false
+has_known_mismatches: true
+related_components: []
+---
+
+# praxis-tabs
+
+Este documento e a referencia canonica da API JSON de praxis-tabs.
+
+## Summary
+
+- Tipo documental: API reference canonica de contrato JSON.
+- Source of truth: runtime e codigo declarados no frontmatter.
+- Objetivo operacional: consulta rapida, auditavel e deterministica sob pressao.
+- Resumo funcional herdado: `praxis-tabs` e um runtime declarativo de navegacao por abas orientado a metadata: voce descreve estrutura, comportamento e conteudo em JSON (`TabsMetadata`) e o motor renderiza a UI com padrao corporativo (persistencia, lazy loading, reorder, widgets e editor em runtime). Nao e apenas um wrapper de `mat-tab-group`: e um host config-first para escalar UIs dinamicas com governanca.
+
+## Scope and positioning
+
+- Escopo: contrato JSON publico e limites de comportamento observavel.
+- Fora de escopo: tutorial de adocao e walkthrough operacional detalhado.
+- Posicionamento: referencia canonicamente governada para consumidores, arquitetos e mantenedores.
+
+## Source of truth
+
+| Source | Kind | Notes |
+| --- | --- | --- |
+| projects/praxis-tabs/src/lib/praxis-tabs.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-tabs/src/lib/praxis-tabs.spec.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-tabs/src/lib/praxis-tabs-widget-event.spec.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-tabs/src/lib/praxis-tabs.metadata.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-tabs/src/lib/praxis-tabs-config-editor.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-tabs/src/lib/quick-setup/tabs-quick-setup.component.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-tabs/src/lib/ai/tabs-ai.adapter.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-tabs/src/lib/ai/tabs-ai-capabilities.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-tabs/src/lib/ai/tabs-context-pack.ts | runtime-code | Source de implementacao declarado no repositorio. |
+
+## Support legend
+
+- Active: suportado e observado no runtime atual.
+- Partial: suporte parcial, com restricoes conhecidas.
+- Declared-only: declarado em tipos/schema sem ligacao runtime confirmada.
+- Schema-only: presente em schema/modelo sem confirmacao de execucao.
+- Deprecated: mantido por compatibilidade legada com migracao prevista.
+
+## Contract classification
+
+### Canonical paths (public contract)
+
+| Path | Type | Required | Default | Status | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `group.alignTabs` | not-specified | not-specified | n/a | Active | `mat-align-tabs` |
+| `group.animationDuration` | not-specified | not-specified | n/a | Active | `effectiveAnimationDuration()` |
+| `group.ariaLabel` | not-specified | not-specified | n/a | Active | atributo no `mat-tab-group` |
+| `group.ariaLabelledby` | not-specified | not-specified | n/a | Active | atributo no `mat-tab-group` |
+| `group.color` | not-specified | not-specified | n/a | Active | prop Material M2 |
+| `group.backgroundColor` | not-specified | not-specified | n/a | Active | prop Material M2 |
+| `group.contentTabIndex` | not-specified | not-specified | n/a | Declared-only | sem binding no template; manter fora do contrato público |
+| `group.disablePagination` | not-specified | not-specified | n/a | Active | prop `mat-tab-group` |
+| `group.disableRipple` | not-specified | not-specified | n/a | Active | prop `mat-tab-group` |
+| `group.dynamicHeight` | not-specified | not-specified | n/a | Active | prop `mat-tab-group` |
+| `group.fitInkBarToContent` | not-specified | not-specified | n/a | Active | prop `mat-tab-group` |
+| `group.headerPosition` | not-specified | not-specified | n/a | Active | prop `mat-tab-group` |
+| `group.preserveContent` | not-specified | not-specified | n/a | Active | prop `mat-tab-group` |
+| `group.selectedIndex` | not-specified | not-specified | n/a | Active | estado interno + persistencia + clamp |
+
+### Supported legacy paths
+
+Nenhum path legado suportado foi identificado nesta revisão baseada em evidência textual preservada.
+
+### Internal-only paths
+
+| Path | Internal consumer | Runtime presence | Public support | Notes |
+| --- | --- | --- | --- | --- |
+| `tabs:{componentKey}` | persistência interna (`ASYNC_CONFIG_STORAGE`) | Yes | No | Namespace interno para salvar/restaurar `TabsMetadata`. |
+| `groupLoaded/navLoaded` | lazy-load cache interno | Yes | No | Estado transitório de render de abas/links carregados. |
+
+### Experimental paths
+
+| Path | Enablement (flag/guard) | Stability | Rollout notes | Notes |
+| --- | --- | --- | --- | --- |
+| `behavior.lazyLoad` | flag no contrato + caches internos | Partial | Cobrir casos de reorder/close com regressão visual | Ativo no runtime com política de cache por índice. |
+
+## Overview
+
+Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecnico existente. O conteudo detalhado anterior foi preservado para manter rastreabilidade historica e reduzir perda de contexto.
+
+## Public contract surface
+
+### Top-level configuration blocks
+
+| Block | Purpose | Required | Merge strategy | Notes |
+| --- | --- | --- | --- | --- |
+| `appearance` | Densidade, tema e tokens visuais | No | deep-merge | Aplica classes/tokens em runtime por instância. |
+| `behavior` | Lazy load, closeable e reorderable | No | deep-merge | Controla interação e ciclo de conteúdo por aba/link. |
+| `accessibility` | A11y e redução de movimento | No | deep-merge | `reduceMotion` altera duração efetiva de animação. |
+| `group` | Configuração do `mat-tab-group` | No | deep-merge | Inclui seleção inicial e props de navegação Material. |
+| `tabs[]` | Definição de abas (modo group) | No | replace-array | Conteúdo/widgts por aba e metadados de label. |
+| `nav` | Definição de links (modo nav) | No | deep-merge | Alternativa ao modo group com links configuráveis. |
+
+### Nested configuration blocks
+
+| Path | Type | Required | Default | Constraints | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `group.alignTabs` | not-specified | not-specified | n/a | component-defined | `mat-align-tabs` |
+| `group.animationDuration` | not-specified | not-specified | n/a | component-defined | `effectiveAnimationDuration()` |
+| `group.ariaLabel` | not-specified | not-specified | n/a | component-defined | atributo no `mat-tab-group` |
+| `group.ariaLabelledby` | not-specified | not-specified | n/a | component-defined | atributo no `mat-tab-group` |
+| `group.color` | not-specified | not-specified | n/a | component-defined | prop Material M2 |
+| `group.backgroundColor` | not-specified | not-specified | n/a | component-defined | prop Material M2 |
+| `group.contentTabIndex` | not-specified | not-specified | n/a | Declared-only | sem binding no template; tipado apenas para compatibilidade transitória |
+| `group.disablePagination` | not-specified | not-specified | n/a | component-defined | prop `mat-tab-group` |
+| `group.disableRipple` | not-specified | not-specified | n/a | component-defined | prop `mat-tab-group` |
+| `group.dynamicHeight` | not-specified | not-specified | n/a | component-defined | prop `mat-tab-group` |
+
+### Input bindings
+
+| Binding/Path | Type | Required | Source | Runtime normalization | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `config` | `TabsMetadata \| null` | No | component-input/storage | `syncSelectionFromConfig()` + clamp | Contrato principal da navegação por abas. |
+| `tabsId` | `string` | Yes (logical) | component-input | component key builder | Necessário para escopo de persistência. |
+| `componentInstanceId` | `string \| undefined` | No | component-input | component key scoping | Isola armazenamento por instância. |
+| `enableCustomization` | `boolean` | No | component-input | boolean coercion | Habilita operações de edição/quick setup. |
+| `form` | `FormGroup \| null` | No | component-input | passthrough | Contexto de formulário para conteúdo dinâmico interno. |
+| `context` | `Record<string, any> \| null` | No | component-input | passthrough | Contexto adicional repassado a widgets internos. |
+
+### Output events
+
+| Event | Payload | Trigger | Stability | Notes |
+| --- | --- | --- | --- | --- |
+| `animationDone` | `void` | Final da animacao no `mat-tab-group` | Partial | Preservado da documentação anterior. |
+| `focusChange` | `MatTabChangeEvent` | Mudanca de foco em aba (group) | Partial | Preservado da documentação anterior. |
+| `selectedIndexChange` | `number` | Selecao em `onSelectedIndexChange` (group) e `onNavClick` (nav) | Partial | Preservado da documentação anterior. |
+| `selectedTabChange` | `MatTabChangeEvent` | Troca de aba no `mat-tab-group` | Partial | Preservado da documentação anterior. |
+| `indexFocused` | `number` | Evento nativo de foco indexado (Material) | Partial | Preservado da documentação anterior. |
+| `selectFocusedIndex` | `number` | Evento nativo de selecao por foco (Material) | Partial | Preservado da documentação anterior. |
+| `widgetEvent` | `{ tabId?, tabIndex?, linkId?, linkIndex?, sourceId, output?, payload? }` | Reemissao de evento vindo de widget interno com contexto de localizacao | Partial | Preservado da documentação anterior. |
+
+### External side channels
+
+| Channel | Direction | Contract | Failure mode | Notes |
+| --- | --- | --- | --- | --- |
+| `ASYNC_CONFIG_STORAGE` | bidirectional | `loadConfig/saveConfig/clearConfig` | fail-open | Persistência de seleção e configuração das abas. |
+| `SettingsPanelService` | bidirectional | `open(...).applied$/saved$` | fail-open | Editor runtime e quick setup sem recarregar host. |
+| `MatSnackBar` | outbound notify | `open(message, ...)` | fail-soft | Feedback de reset de preferências. |
+
+### Host/runtime dependencies
+
+| Dependency | Required | Environment | Purpose | Notes |
+| --- | --- | --- | --- | --- |
+| `ASYNC_CONFIG_STORAGE` | Yes | browser/dev/prod | persistência | Carrega/salva `TabsMetadata` por chave de componente. |
+| `SettingsPanelService` | Yes | browser/dev/prod | editor runtime | Integra editor e quick setup de abas. |
+| `ComponentKeyService` | Yes | browser/dev/prod/ssr | chave de escopo | Evita colisão de estado entre instâncias. |
+| `MatTabsModule` | Yes | browser/dev/prod | render base | Runtime principal para modo group. |
+| `DynamicWidgetLoaderDirective` | Optional per config | browser/dev/prod | widgets internos | Reemite eventos via `widgetEvent`. |
+| `MatSnackBar` | Optional | browser/dev/prod | UX feedback | Avisos operacionais como reset de preferências. |
+
+## Coverage matrix
+
+| Surface | Verified | Coverage status | Evidence | Notes |
+| --- | --- | --- | --- | --- |
+| Runtime | false | Partial | source_of_truth + conteudo preservado | Revisao estrutural concluida; validacao comportamental fina pode exigir follow-up. |
+| Schema/Types | true | Partial | interfaces/modelos citados | Mapeamento formal de todos os campos ainda pode requerer refinamento. |
+| Editor/Tooling | false | Partial | secoes de editor quando presentes | Cobertura de editor/tooling nem sempre confirmada por evidencia direta. |
+
+## Runtime coverage boundaries
+
+- Cobertura consolidada com base em documentacao existente e source of truth declarado.
+- Comportamentos fora de evidencia direta foram marcados como not-yet-verified ou Partial.
+- Compatibilidade legada, quando detectada, foi separada em classificacao explicita.
+
+## Resolution model
+
+### Merge order
+
+1. contrato em `@Input() config` (quando fornecido)
+2. hidratação opcional de storage no `ngOnInit()`
+3. normalização de seleção via `syncSelectionFromConfig()`
+4. persistência incremental após mudanças (`persistConfig`)
+
+### Fallback order
+
+config explícita -> config persistida -> seleção clamp para `0` quando índice inválido/ausente.
+
+### Override points
+
+- `@Input() config`, `@Input() tabsId`, `@Input() componentInstanceId`
+- editor runtime (`openEditor`, `openQuickSetup`)
+- persistência por host (`ASYNC_CONFIG_STORAGE`)
+
+### Runtime normalization
+
+- `clampIndex()` evita seleção fora de faixa após reorder/remove.
+- `syncSelectionFromConfig()` reconcilia estado de seleção para modos group/nav.
+- `effectiveAnimationDuration()` aplica `reduceMotion` como override de duração.
+
+### Precedence rules
+
+- seleção runtime (`selectedIndexSignal/currentNavIndex`) é derivada de `config` e sempre clamped.
+- eventos de editor `saved` e `applied` sobrescrevem config atual; `saved` também persiste.
+- ausência de `tabsId` mantém componente funcional, mas sem persistência.
+
+## Validation and error semantics
+
+### Validation model
+
+| Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
+| --- | --- | --- | --- | --- |
+| `tabsId` para persistência | init/runtime | warning + disable persistence | `praxis-tabs:missing-tabs-id` | Fluxo visual continua sem restore/save de estado. |
+| índices de seleção (`group.selectedIndex`, `nav.selectedIndex`) | runtime | clamp para faixa válida | n/a | Previne acesso fora dos limites após mudanças dinâmicas. |
+| payload de reorder/nav click inválido | runtime | ignore operation | n/a | Guardas de índice evitam mutações incorretas. |
+| valores CSS inseguros em appearance | runtime sanitize | sanitize/ignore | n/a | `sanitizeCssValue()` limita superfícies de injeção de estilo. |
+
+### Error semantics
+
+Predomina tratamento fail-open com guardas de índice e persistência opcional. Falhas em storage ou operações inválidas não derrubam renderização das abas.
+
+### Fail-open / fail-closed behavior
+
+| Condition | Mode | Runtime behavior | Consumer impact |
+| --- | --- | --- | --- |
+| Falha em `loadConfig/saveConfig` | fail-open | mantém config em memória | sem perda de navegação atual |
+| índice inválido após reorder/remove | fail-open | clamp para índice seguro | evita erro de render/navegação |
+| operação de drag inválida | fail-open | ignora mutação | sem corrupção de estado |
+| config ausente ou parcial | fail-soft | renderiza estado mínimo (sem abas/links) | componente permanece estável |
+
+### Invalid or unknown field handling
+
+- Campos desconhecidos: comportamento depende da estrategia do componente (ignore, warn ou reject).
+- Campos invalidos: podem gerar fallback, warning ou falha conforme implementacao.
+- Registrar divergencias observadas em Known limitations and mismatches.
+
+### Runtime warnings vs hard failures
+
+| Condition | Severity | Observability | Consumer action |
+| --- | --- | --- | --- |
+| partial-or-declared-only-coverage | warning | logs/eventos do componente | confirmar ligacao runtime antes de uso critico |
+
+## Detailed API
+
+### Preserved technical reference (normalized from previous revision)
+
+`praxis-tabs` e um runtime declarativo de navegacao por abas orientado a metadata: voce descreve estrutura, comportamento e conteudo em JSON (`TabsMetadata`) e o motor renderiza a UI com padrao corporativo (persistencia, lazy loading, reorder, widgets e editor em runtime). Nao e apenas um wrapper de `mat-tab-group`: e um host config-first para escalar UIs dinamicas com governanca.
+
+### Prova em 20 segundos
+
+Cole este JSON e renderize tabs funcionais sem reescrever template:
+
+```json
+{
+  "behavior": { "lazyLoad": true },
+  "group": { "selectedIndex": 0, "stretchTabs": true },
+  "tabs": [
+    { "id": "dados", "textLabel": "Dados" },
+    { "id": "itens", "textLabel": "Itens" }
+  ]
+}
+```
+
+- Troque `textLabel` e a UI muda sem alterar o componente host.
+- Ative `widgets` por aba e a composicao passa a ser metadata-driven.
+- As regras de selecao e persistencia continuam previsiveis e versionaveis.
+
+Ver demo/recipe no workspace de exemplos: `examples/ai-recipes/praxis-tabs.json`
+
+### Table of contents
+
+- [Start here](#start-here)
+  - [Promessa e limites](#promessa-e-limites)
+  - [Dicionario oficial](#dicionario-oficial)
+  - [Status model](#status-model)
+  - [Checklist corporativo pre-flight](#checklist-corporativo-pre-flight)
+- [Guia operacional (produto)](#guia-operacional-produto)
+  - [Controle de entrada e saida](#controle-de-entrada-e-saida)
+  - [Precedencia de modo e fluxo de render](#precedencia-de-modo-e-fluxo-de-render)
+  - [Persistencia, identidade e compatibilidade](#persistencia-identidade-e-compatibilidade)
+  - [Controle de comportamento](#controle-de-comportamento)
+  - [Acessibilidade e motion](#acessibilidade-e-motion)
+  - [Conteudo dinamico e widgets](#conteudo-dinamico-e-widgets)
+  - [Operacao em runtime (editor, quick setup, AI)](#operacao-em-runtime-editor-quick-setup-ai)
+- [Contrato tecnico completo (referencia)](#contrato-tecnico-completo-referencia)
+  - [Interfaces do contrato](#interfaces-do-contrato)
+  - [Matriz top-level](#matriz-top-level)
+  - [Appearance API (deep dive)](#appearance-api-deep-dive)
+  - [Behavior API](#behavior-api)
+  - [Accessibility API](#accessibility-api)
+  - [Group API (`group` + `tabs[]`)](#group-api-group--tabs)
+  - [Nav API (`nav` + `links[]`)](#nav-api-nav--links)
+  - [Complete JSON path index](#complete-json-path-index)
+- [Styling](#styling)
+- [Examples](#examples)
+- [Known limitations and mismatches](#known-limitations-and-mismatches)
+- [Source references](#source-references)
+- [Referencias oficiais Angular](#referencias-oficiais-angular)
+
+### Start here
+
+#### Promessa e limites
+
+**O que isso habilita:** composicao de tabs por contrato JSON, com dois modos (`group` e `nav`) e integracao nativa com widgets Praxis.
+
+**Quando usar:** quando o objetivo e evoluir fluxo de tela por configuracao (config-first), sem replicar logica de UI em cada feature.
+
+**Exemplo minimo:** defina `group + tabs[]` para fluxo simples ou `nav + links[]` para shell modular.
+
+Garantias principais (hoje):
+
+- Precedencia explicita de modo de render.
+- Clamp de indices de selecao.
+- Persistencia por identidade (`tabsId` + `componentInstanceId` + rota).
+- Reemissao de eventos de widgets com contexto (`tabId/tabIndex` ou `linkId/linkIndex`).
+
+Limites explicitos (hoje):
+
+- Alguns campos existem para compatibilidade futura e ainda nao mudam o runtime.
+- `events` e placeholder de contrato (nao aciona runtime por si).
+- Em coexistencia `tabs[]` + `nav.links[]`, o modo `nav` vence por precedencia.
+
+#### Dicionario oficial
+
+Use estes termos como linguagem padrao da plataforma:
+
+- `config-first`: comportamento nasce do JSON, nao de branching em template.
+- `metadata-driven`: estrutura e regras sao dados versionaveis.
+- `runtime de UI`: motor que interpreta contrato e renderiza.
+- `policy-ready`: contrato com precedencia, limites e pontos de governanca.
+- `compatibilidade`: campos declarados podem existir antes do binding de runtime.
+- `garantia`: comportamento confirmado por implementacao ativa.
+
+#### Status model
+
+Padrao oficial para cada recurso/campo:
+
+- `Status: Active` - funciona no runtime atual.
+- `Status: Partial` - parte ativa, parte ainda sem binding.
+- `Status: Derived` - nao e configurado de forma autoritativa, mas o runtime calcula o valor a partir de outro estado.
+- `Status: Stored-only` - persiste no config, sem efeito direto na UI.
+- `Status: Declared-only` - declarado em tipos/schema sem binding publico confirmado.
+
+#### Checklist corporativo pre-flight
+
+- Defina `tabsId` estavel por tela.
+- Em multi-instancia na mesma rota, use `componentInstanceId`.
+- Mantenha ids unicos em `tabs[].id` e `nav.links[].id`.
+- Para `behavior.lazyLoad=true`, valide UX da primeira ativacao em abas pesadas.
+- Restrinja origem de `appearance.customCss` em ambientes com governanca de seguranca.
+- Valide payload de `widgetEvent` no host antes de executar regra de negocio.
+
+### Guia operacional (produto)
+
+#### Controle de entrada e saida
+
+**O que isso habilita:** contrato claro entre host e runtime (`inputs`) e telemetria/eventos (`outputs`).
+
+**Quando usar:** em telas que precisam integrar tabs com formulario, widgets e analytics de interacao.
+
+**Exemplo minimo:** passar `config`, `tabsId`, `form` e escutar `(widgetEvent)`.
+
+`Status: Active`.
+
+##### Component inputs
+
+| Input | Tipo | Required | Default | O que controla | Status |
+| --- | --- | --- | --- | --- | --- |
+| `config` | `TabsMetadata \| null` | No | `null` | Contrato JSON principal | Active |
+| `tabsId` | `string` | Sim (logico) | sem default | Identidade para persistencia | Active |
+| `componentInstanceId` | `string \| undefined` | No | `undefined` | Isolamento de instancias iguais | Active |
+| `enableCustomization` | `boolean` | No | `false` | FAB de edicao + quick setup + AI assistant | Active |
+| `form` | `FormGroup \| null` | No | `null` | Base para `content` dinamico | Active |
+| `context` | `Record<string, any> \| null` | No | `null` | Contexto entregue aos widgets internos | Active |
+
+Notas operacionais:
+
+- `content` nao renderiza se `form` for `null`.
+- `widgets` renderizam com fallback de contexto para `{}`.
+
+##### Component outputs
+
+| Output | Payload | Quando dispara | Status |
+| --- | --- | --- | --- |
+| `animationDone` | `void` | Final da animacao no `mat-tab-group` | Active |
+| `focusChange` | `MatTabChangeEvent` | Mudanca de foco em aba (group) | Active |
+| `selectedIndexChange` | `number` | Selecao em `onSelectedIndexChange` (group) e `onNavClick` (nav) | Active |
+| `selectedTabChange` | `MatTabChangeEvent` | Troca de aba no `mat-tab-group` | Active |
+| `indexFocused` | `number` | Evento nativo de foco indexado (Material) | Active |
+| `selectFocusedIndex` | `number` | Evento nativo de selecao por foco (Material) | Active |
+| `widgetEvent` | `{ tabId?, tabIndex?, linkId?, linkIndex?, sourceId, output?, payload? }` | Reemissao de evento vindo de widget interno com contexto de localizacao | Active |
+
+#### Precedencia de modo e fluxo de render
+
+**O que isso habilita:** decisao deterministica de runtime entre `group mode` e `nav mode`.
+
+**Quando usar:** quando o mesmo componente precisa alternar de UX por contrato, sem trocar codigo host.
+
+**Exemplo minimo:** defina `nav.links[]`; se vazio, runtime usa `tabs[]`.
+
+`Status: Active`.
+
+Precedencia de render:
+
+1. Se `config.nav.links.length > 0`, entra em `nav mode`.
+2. Caso contrario, usa `group mode`.
+
+Fluxo simplificado:
+
+1. Recebe `config`.
+2. Normaliza indices com clamp.
+3. Resolve modo por precedencia.
+4. Renderiza `content` e `widgets` por aba/link.
+5. Persiste estado/config quando chave de storage existe.
+
+#### Persistencia, identidade e compatibilidade
+
+**O que isso habilita:** estado de selecao e configuracao consistentes entre sessoes e contextos.
+
+**Quando usar:** em produtos com multi-tela, multi-instancia e operacao por settings panel.
+
+**Exemplo minimo:** usar `tabsId` estavel + `componentInstanceId` para diferenciar instancias.
+
+`Status: Active`.
+
+- Chave de persistencia: `tabs:<componentKeyId>`.
+- `componentKeyId` deriva de:
+  - `componentType='praxis-tabs'`
+  - `tabsId`
+  - `componentInstanceId`
+  - contexto de rota (`ActivatedRoute`)
+
+Pontos que persistem config/estado:
+
+- `ngOnChanges(config)`
+- `onSelectedIndexChange`
+- `onNavClick`
+- `onNavDrop`
+- `closeTab`
+- `moveTab`
+- `applyConfigFromAdapter`
+- callbacks `applied$` e `saved$` do editor/quick setup
+
+Sem `tabsId` valido:
+
+- runtime segue funcional,
+- mas nao persiste,
+- e registra warning deduplicado via `LoggerService.warnOnce`.
+
+#### Controle de comportamento
+
+**O que isso habilita:** ligamento declarativo de lazy load, fechamento e reorder por JSON.
+
+**Quando usar:** quando UX de operacao muda por tela, mas com o mesmo runtime.
+
+**Exemplo minimo:** `"behavior": { "lazyLoad": true, "closeable": true }`.
+
+`Status: Active`.
+
+| Campo | Tipo | Efeito | Status |
+| --- | --- | --- | --- |
+| `behavior.lazyLoad` | `boolean` | Render sob demanda por primeira ativacao | Active |
+| `behavior.closeable` | `boolean` | Exibe botao de fechar em labels de tab | Active |
+| `behavior.reorderable` | `boolean` | Nav com drag-drop e group com mover esquerda/direita | Active |
+
+#### Acessibilidade e motion
+
+**O que isso habilita:** modo de contraste/movimento reduzido e atributos ARIA de grupo/tab.
+
+**Quando usar:** em contextos WCAG e politicas corporativas de acessibilidade.
+
+**Exemplo minimo:** `"accessibility": { "highContrast": true, "reduceMotion": true }`.
+
+`Status: Partial`.
+
+Ativo no runtime:
+
+- `accessibility.highContrast` -> classe `high-contrast`
+- `accessibility.reduceMotion` -> classe `reduce-motion` + `effectiveAnimationDuration=0ms`
+- `group.ariaLabel`, `group.ariaLabelledby`
+- `tabs[].ariaLabel`, `tabs[].ariaLabelledby`
+
+Ainda sem binding direto:
+
+- `accessibility.ariaLabels`
+- `accessibility.keyboardNavigation`
+
+#### Conteudo dinamico e widgets
+
+**O que isso habilita:** tabs como host de formulario dinamico e modulos ricos, sem acoplamento no template host.
+
+**Quando usar:** quando cada aba/link precisa conter componentes heterogeneos e eventos de negocio.
+
+**Exemplo minimo:** `tabs[].widgets` com `praxis-table`, `praxis-list` ou `praxis-crud`.
+
+`Status: Active`.
+
+Duas estrategias por aba/link:
+
+1. **Campos dinamicos (`content`)**
+  - esperado: metadata de fields
+  - render: `DynamicFieldLoaderDirective`
+  - prerequisito: `form` fornecido pelo host
+
+2. **Widgets (`widgets`)**
+  - esperado: `WidgetDefinition[]`
+  - render: `DynamicWidgetLoaderDirective`
+  - contexto: `context` (fallback `{}`)
+
+Formato de `widgetEvent`:
+
+- group mode: `{ tabId, tabIndex, sourceId, output, payload }`
+- nav mode: `{ linkId, linkIndex, sourceId, output, payload }`
+
+#### Operacao em runtime (editor, quick setup, AI)
+
+**O que isso habilita:** ciclo config-first completo (criar, editar, ajustar e versionar contrato).
+
+**Quando usar:** em squads que precisam reduzir tempo de mudanca de UI sem rebuild completo.
+
+**Exemplo minimo:** `enableCustomization=true` para habilitar editor, quick setup e assistente AI.
+
+`Status: Active`.
+
+Fluxos disponiveis:
+
+1. **Editor completo (`PraxisTabsConfigEditor`)**
+  - id: `praxis-tabs-editor:<key>`
+  - cobre comportamento, estilo, tabs, links e widgets
+  - sincroniza por `applied$` e `saved$`
+
+2. **Quick setup (`TabsQuickSetupComponent`)**
+  - id: `praxis-tabs-quick-setup:<key>`
+  - bootstrap rapido de `group+tabs` ou `nav+links`
+  - normaliza labels e descarta vazios
+
+3. **Semantic assistant (`PraxisAiAssistantShellComponent` + `TabsAgenticAuthoringTurnFlow` + `TabsAiAdapter`)**
+  - abre shell compartilhado e registra sessao global quando `enableCustomization=true`
+  - rejeita patch JSON livre
+  - exige `componentEditPlan` manifest-backed antes de qualquer apply local
+  - roteia prompts de regra/governanca para `domain-rules/intake`
+
+Governanca recomendada:
+
+- tratar AI como acelerador de autoria, nao como bypass de validacao.
+- manter revisao funcional com base em contrato e limites ativos.
+
+### Contrato tecnico completo (referencia)
+
+#### Interfaces do contrato
+
+**O que isso habilita:** contrato tipado para autoria, validacao e compatibilidade.
+
+**Quando usar:** em validadores, geradores de config, editors e testes de regressao.
+
+**Exemplo minimo:** `TabsMetadata` como payload unico do runtime.
+
+```ts
+interface TabsMetadata {
+  meta?: any;
+  appearance?: TabsAppearanceConfig;
+  behavior?: TabsBehaviorConfig;
+  events?: TabsEventConfig;
+  accessibility?: TabsAccessibilityConfig;
+  group?: TabGroupMetadata;
+  tabs?: TabMetadata[];
+  nav?: TabNavMetadata;
+}
+```
+
+#### Matriz top-level
+
+**O que isso habilita:** leitura executiva do que esta ativo, parcial, armazenado ou apenas declarado.
+
+**Quando usar:** em onboarding tecnico e revisao de impacto de mudanca.
+
+**Exemplo minimo:** revisar `behavior`, `group/tabs`, `nav/links` antes de configurar.
+
+| Caminho | Status | Observacao |
+| --- | --- | --- |
+| `meta` | Stored-only | Bag livre, sem consumo direto no runtime |
+| `appearance` | Partial | Maioria ativa; parte dos tokens e declarativa |
+| `behavior` | Active | Lazy load, close e reorder ativos |
+| `events` | Stored-only | Placeholder de contrato |
+| `accessibility` | Partial | `highContrast/reduceMotion` ativos |
+| `group` | Partial | Quase completo; `contentTabIndex` sem binding |
+| `tabs[]` | Partial | Principal ativo; alguns campos sao metadado |
+| `nav` | Partial | Principal ativo; `links[].active` sem binding |
+
+#### Appearance API (deep dive)
+
+**O que isso habilita:** densidade, tema e estilo runtime por instancia.
+
+**Quando usar:** para padronizar visual sem duplicar CSS por tela.
+
+**Exemplo minimo:** `appearance.density` + `appearance.tokens`.
+
+Campos:
+
+- `density`
+- `themeClass`
+- `customCss`
+- `tokens`
+
+##### density
+
+| Campo | Opcoes | Status | Runtime |
+| --- | --- | --- | --- |
+| `appearance.density` | `compact \| comfortable \| spacious` | Active | classes `density-*` |
+
+##### themeClass
+
+| Campo | Status | Runtime |
+| --- | --- | --- |
+| `appearance.themeClass` | Active | `[ngClass]` no root |
+
+##### customCss
+
+| Campo | Status | Runtime |
+| --- | --- | --- |
+| `appearance.customCss` | Active | Aplicado via `safeCustomCss()` |
+
+Politica de bloqueio atual:
+
+- bloqueia `@import`
+- bloqueia `expression(`
+- bloqueia `behavior:`
+- bloqueia `</style`
+- bloqueia `<script`
+- bloqueia `url(javascript:...)`
+- bloqueia `url(data:text/html...)`
+
+##### tokens (runtime CSS)
+
+Tokens mapeados no runtime:
+
+- `active-indicator-color`
+- `active-focus-indicator-color`
+- `active-hover-indicator-color`
+- `active-label-text-color`
+- `active-focus-label-text-color`
+- `active-hover-label-text-color`
+- `inactive-label-text-color`
+- `inactive-hover-label-text-color`
+- `inactive-focus-label-text-color`
+- `pagination-icon-color`
+- `divider-color`
+- `background-color`
+
+Token declarado sem efeito atual:
+
+- `inactive-ripple-color` (`Status: Declared-only`)
+
+Escopo de estilo:
+
+- seletor base: `.praxis-tabs-root[data-tabs-id="<scope>"]`
+- `<scope>` e sanitizado de `tabsId + componentInstanceId`
+
+#### Behavior API
+
+**O que isso habilita:** toggle declarativo de comportamento central do runtime.
+
+**Quando usar:** para ajustar UX por tela sem ramificar componente host.
+
+**Exemplo minimo:** habilitar `lazyLoad` em abas pesadas.
+
+| Campo | Tipo | Status |
+| --- | --- | --- |
+| `behavior.lazyLoad` | `boolean` | Active |
+| `behavior.closeable` | `boolean` | Active |
+| `behavior.reorderable` | `boolean` | Active |
+
+Detalhes:
+
+- `closeable` mostra botao de fechar no label de tab.
+- `reorderable`:
+  - nav: drag-and-drop horizontal (`cdkDropList`)
+  - group: botoes esquerda/direita no label da tab
+
+#### Accessibility API
+
+**O que isso habilita:** contrato unico para requisitos de acessibilidade.
+
+**Quando usar:** em times com gate WCAG e criterios de release por a11y.
+
+**Exemplo minimo:** `highContrast` + `reduceMotion`.
+
+| Campo | Status | Observacao |
+| --- | --- | --- |
+| `accessibility.highContrast` | Active | classe `high-contrast` |
+| `accessibility.reduceMotion` | Active | classe `reduce-motion` + `effectiveAnimationDuration=0ms` |
+| `accessibility.ariaLabels` | Declared-only | manter fora do contrato publico ate existir binding |
+| `accessibility.keyboardNavigation` | Declared-only | manter fora do contrato publico ate existir binding |
+
+Atributos ARIA ativos via `group`/`nav`/`tabs`:
+
+- `group.ariaLabel`
+- `group.ariaLabelledby`
+- `nav.ariaLabel`
+- `nav.ariaLabelledby`
+- `tabs[].ariaLabel`
+- `tabs[].ariaLabelledby`
+
+#### Group API (`group` + `tabs[]`)
+
+**O que isso habilita:** modo classico de tabs com cabecalho/conteudo no `mat-tab-group`.
+
+**Quando usar:** para fluxos por secao com trocas previsiveis no mesmo contexto de pagina.
+
+**Exemplo minimo:** `group.selectedIndex` + `tabs[].textLabel`.
+
+##### `group`
+
+| Caminho | Status | Runtime |
+| --- | --- | --- |
+| `group.alignTabs` | Active | `mat-align-tabs` |
+| `group.animationDuration` | Active | `effectiveAnimationDuration()` |
+| `group.ariaLabel` | Active | atributo no `mat-tab-group` |
+| `group.ariaLabelledby` | Active | atributo no `mat-tab-group` |
+| `group.color` | Active | prop Material M2 |
+| `group.backgroundColor` | Active | prop Material M2 |
+| `group.contentTabIndex` | Declared-only | sem binding no template |
+| `group.disablePagination` | Active | prop `mat-tab-group` |
+| `group.disableRipple` | Active | prop `mat-tab-group` |
+| `group.dynamicHeight` | Active | prop `mat-tab-group` |
+| `group.fitInkBarToContent` | Active | prop `mat-tab-group` |
+| `group.headerPosition` | Active | prop `mat-tab-group` |
+| `group.preserveContent` | Active | prop `mat-tab-group` |
+| `group.selectedIndex` | Active | estado interno + persistencia + clamp |
+| `group.stretchTabs` | Active | `mat-stretch-tabs` |
+
+##### `tabs[]`
+
+| Caminho | Status | Runtime |
+| --- | --- | --- |
+| `tabs[].id` | Active | id da tab + contexto de evento |
+| `tabs[].ariaLabel` | Active | atributo por tab |
+| `tabs[].ariaLabelledby` | Active | atributo por tab |
+| `tabs[].textLabel` | Active | label exibido |
+| `tabs[].labelClass` | Active | classe de label |
+| `tabs[].bodyClass` | Active | classe de body |
+| `tabs[].disabled` | Active | desabilita tab |
+| `tabs[].content` | Active | `DynamicFieldLoaderDirective` (requer `form`) |
+| `tabs[].widgets` | Active | `DynamicWidgetLoaderDirective` |
+| `tabs[].isActive` | Declared-only | sem binding direto |
+| `tabs[].origin` | Declared-only | sem binding direto |
+| `tabs[].position` | Declared-only | sem binding direto |
+
+#### Nav API (`nav` + `links[]`)
+
+**O que isso habilita:** modo de navegacao por links com painel unificado e reorder por drag.
+
+**Quando usar:** para shells de pagina e navegacao horizontal mais proxima de menu.
+
+**Exemplo minimo:** `nav.selectedIndex` + `nav.links[]`.
+
+##### `nav`
+
+| Caminho | Status | Runtime |
+| --- | --- | --- |
+| `nav.animationDuration` | Active | `effectiveAnimationDuration()` |
+| `nav.ariaLabel` | Active | atributo no `mat-tab-nav-bar` |
+| `nav.ariaLabelledby` | Active | atributo no `mat-tab-nav-bar` |
+| `nav.color` | Active | prop Material Nav |
+| `nav.backgroundColor` | Active | prop Material Nav |
+| `nav.disablePagination` | Active | prop Material Nav |
+| `nav.disableRipple` | Active | prop Material Nav |
+| `nav.fitInkBarToContent` | Active | prop Material Nav |
+| `nav.selectedIndex` | Active | estado interno + persistencia + clamp |
+| `nav.stretchTabs` | Active | prop Material Nav |
+| `nav.links` | Active | fonte de nav mode |
+
+##### `nav.links[]`
+
+| Caminho | Status | Runtime |
+| --- | --- | --- |
+| `nav.links[].id` | Active | preservacao de selecao no reorder + contexto |
+| `nav.links[].label` | Active | label exibido |
+| `nav.links[].active` | Derived | ativo real e derivado de `currentNavIndex` |
+| `nav.links[].disabled` | Active | desabilita link |
+| `nav.links[].disableRipple` | Active | override por link |
+| `nav.links[].fitInkBarToContent` | Active | override por link |
+| `nav.links[].content` | Active | `DynamicFieldLoaderDirective` (requer `form`) |
+| `nav.links[].widgets` | Active | `DynamicWidgetLoaderDirective` |
+
+#### Complete JSON path index
+
+| JSON path | Status | Observacao |
+| --- | --- | --- |
+| `meta` | Stored-only | bag livre sem binding direto |
+| `appearance` | Partial | bloco ativo com ressalvas em token |
+| `appearance.density` | Active | classes `density-*` |
+| `appearance.themeClass` | Active | classe no root |
+| `appearance.customCss` | Active | filtrado por seguranca |
+| `appearance.tokens` | Active | mapeado por `styleCss()` |
+| `appearance.tokens.active-indicator-color` | Active | css runtime |
+| `appearance.tokens.active-focus-indicator-color` | Active | css runtime |
+| `appearance.tokens.active-hover-indicator-color` | Active | css runtime |
+| `appearance.tokens.active-label-text-color` | Active | css runtime |
+| `appearance.tokens.active-focus-label-text-color` | Active | css runtime |
+| `appearance.tokens.active-hover-label-text-color` | Active | css runtime |
+| `appearance.tokens.inactive-label-text-color` | Active | css runtime |
+| `appearance.tokens.inactive-hover-label-text-color` | Active | css runtime |
+| `appearance.tokens.inactive-focus-label-text-color` | Active | css runtime |
+| `appearance.tokens.inactive-ripple-color` | Declared-only | nao mapeado no render atual |
+| `appearance.tokens.pagination-icon-color` | Active | css runtime |
+| `appearance.tokens.divider-color` | Active | css runtime |
+| `appearance.tokens.background-color` | Active | css runtime |
+| `behavior` | Active | bloco runtime |
+| `behavior.lazyLoad` | Active | lazy content |
+| `behavior.closeable` | Active | fechar aba |
+| `behavior.reorderable` | Active | reorder nav/group |
+| `events` | Stored-only | placeholder |
+| `accessibility` | Partial | parcial |
+| `accessibility.ariaLabels` | Declared-only | nao expor como contrato publico |
+| `accessibility.keyboardNavigation` | Declared-only | nao expor como contrato publico |
+| `accessibility.highContrast` | Active | classe root |
+| `accessibility.reduceMotion` | Active | classe root + duracao |
+| `group` | Partial | quase completo |
+| `group.alignTabs` | Active | material prop |
+| `group.animationDuration` | Active | runtime duration |
+| `group.ariaLabel` | Active | aria attr |
+| `group.ariaLabelledby` | Active | aria attr |
+| `group.color` | Active | material M2 |
+| `group.contentTabIndex` | Declared-only | sem binding |
+| `nav.ariaLabel` | Active | aria attr |
+| `nav.ariaLabelledby` | Active | aria attr |
+| `group.disablePagination` | Active | material prop |
+| `group.disableRipple` | Active | material prop |
+| `group.dynamicHeight` | Active | material prop |
+| `group.fitInkBarToContent` | Active | material prop |
+| `group.headerPosition` | Active | material prop |
+| `group.preserveContent` | Active | material prop |
+| `group.selectedIndex` | Active | clamp + persist |
+| `group.stretchTabs` | Active | material prop |
+| `group.backgroundColor` | Active | material M2 |
+| `tabs` | Partial | principal ativo |
+| `tabs[].id` | Active | id/ctx |
+| `tabs[].ariaLabel` | Active | aria attr |
+| `tabs[].ariaLabelledby` | Active | aria attr |
+| `tabs[].textLabel` | Active | label |
+| `tabs[].labelClass` | Active | class |
+| `tabs[].bodyClass` | Active | class |
+| `tabs[].disabled` | Active | disable |
+| `tabs[].content` | Active | dynamic fields |
+| `tabs[].widgets` | Active | dynamic widgets |
+| `tabs[].isActive` | Declared-only | sem binding |
+| `tabs[].origin` | Declared-only | sem binding |
+| `tabs[].position` | Declared-only | sem binding |
+| `nav` | Partial | principal ativo |
+| `nav.animationDuration` | Active | runtime duration |
+| `nav.color` | Active | material nav |
+| `nav.backgroundColor` | Active | material nav |
+| `nav.disablePagination` | Active | material nav |
+| `nav.disableRipple` | Active | material nav |
+| `nav.fitInkBarToContent` | Active | material nav |
+| `nav.selectedIndex` | Active | clamp + persist |
+| `nav.stretchTabs` | Active | material nav |
+| `nav.links` | Active | fonte do modo nav |
+| `nav.links[].id` | Active | merge/reorder context |
+| `nav.links[].label` | Active | label |
+| `nav.links[].active` | Derived | derivado por indice |
+| `nav.links[].disabled` | Active | disable |
+| `nav.links[].disableRipple` | Active | override |
+| `nav.links[].fitInkBarToContent` | Active | override |
+| `nav.links[].content` | Active | dynamic fields |
+| `nav.links[].widgets` | Active | dynamic widgets |
+
+### Styling
+
+Camadas de estilo no runtime:
+
+1. classes de densidade/acessibilidade no root
+2. `themeClass` opcional
+3. CSS custom filtrado (`customCss`)
+4. CSS de tokens gerado em runtime (`styleCss`)
+
+Boas praticas corporativas:
+
+- prefira `appearance.tokens` para ajustes tematicos
+- use `customCss` so para excecoes governadas
+- mantenha `tabsId` estavel para escopo visual previsivel
+
+### Examples
+
+### Minimal valid
+
+```json
+{
+  "behavior": { "lazyLoad": true },
+  "group": { "selectedIndex": 0, "stretchTabs": true },
+  "tabs": [
+    { "id": "dados", "textLabel": "Dados" },
+    { "id": "itens", "textLabel": "Itens" }
+  ]
+}
+```
+
+### Typical/common
+
+```json
+{}
+```
+
+### Advanced
+
+```json
+{}
+```
+
+### Enterprise scenario
+
+```json
+{}
+```
+
+## Known limitations and mismatches
+
+| Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
+| --- | --- | --- | --- | --- | --- |
+| coverage/mapping | Evidência textual preservada indica itens Partial/Declared-only. | Cobertura confirmada por evidência runtime + schema + editor. | Pode gerar uso de paths não totalmente ligados. | to-be-linked | next-doc-cycle |
+
+## Compatibility and migration notes
+
+| Concern | Affected versions | Migration action | Deadline | Notes |
+| --- | --- | --- | --- | --- |
+| legacy aliases and mixed status vocabulary | pre-canonical docs | manter apenas taxonomia canonica nas secoes novas e reduzir termos legados em revisoes incrementais | ongoing | backward compatibility documental ainda existe em secoes historicas |
+
+## Source references
+
+| Source type | Path/URL | Why it is source of truth | Last verified (YYYY-MM-DD) | Notes |
+| --- | --- | --- | --- | --- |
+| local-file | projects/praxis-tabs/src/lib/praxis-tabs.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-tabs/src/lib/praxis-tabs.spec.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-tabs/src/lib/praxis-tabs-widget-event.spec.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-tabs/src/lib/praxis-tabs.metadata.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-tabs/src/lib/praxis-tabs-config-editor.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-tabs/src/lib/quick-setup/tabs-quick-setup.component.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-tabs/src/lib/ai/tabs-ai.adapter.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-tabs/src/lib/ai/tabs-ai-capabilities.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
+| local-file | projects/praxis-tabs/src/lib/ai/tabs-context-pack.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |