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

package/src/lib/quick-setup/tabs-quick-setup.json-api.md

@@ -0,0 +1,491 @@
+---
+title: "tabs-quick-setup JSON API (Canonical)"
+slug: "tabs-quick-setup-json-api"
+doc_type: "api-reference"
+component: "tabs-quick-setup"
+document_kind: "json-api-canonical"
+reference_mode: "canonical"
+contract_format: "json"
+contract_source: "runtime-and-code"
+description: "Referencia canonica do contrato JSON do componente tabs-quick-setup."
+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/quick-setup/tabs-quick-setup.component.ts"
+  - "projects/praxis-tabs/src/lib/praxis-tabs.ts"
+source_of_truth_last_verified: "2026-03-05"
+last_updated: "2026-03-05"
+toc: true
+sidebar: true
+tags:
+  - "json-api"
+  - "canonical-contract"
+  - "tabs-quick-setup"
+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: []
+---
+
+# tabs-quick-setup
+
+Este documento e a referencia canonica da API JSON de tabs-quick-setup.
+
+## 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: `tabs-quick-setup` e o acelerador de bootstrap do `praxis-tabs`: ele gera um contrato inicial valido em segundos para `group mode` ou `nav mode`. Nao substitui o editor completo; ele reduz tempo de partida com um payload limpo e previsivel.
+
+## 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/quick-setup/tabs-quick-setup.component.ts | runtime-code | Source de implementacao declarado no repositorio. |
+| projects/praxis-tabs/src/lib/praxis-tabs.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 mode` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
+| `nav mode` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
+| `tabs[].id/textLabel` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
+| `nav.links[].id/label` | not-specified | not-specified | n/a | Active | Preservado da documentação anterior. |
+| `behavior.*` | not-specified | not-specified | n/a | Partial | Preservado da documentação anterior. |
+| `appearance.*` | not-specified | not-specified | n/a | Partial | Preservado da documentação anterior. |
+| `widgets/content` | not-specified | not-specified | n/a | Partial | Preservado da documentação anterior. |
+| `events/accessibility/meta` | not-specified | not-specified | n/a | Partial | Preservado da documentação anterior. |
+
+### 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 |
+| --- | --- | --- | --- | --- |
+| not-yet-mapped | not-yet-verified | not-yet-verified | No | Caminhos internos nao mapeados explicitamente nesta revisao automatizada. |
+
+### Experimental paths
+
+| Path | Enablement (flag/guard) | Stability | Rollout notes | Notes |
+| --- | --- | --- | --- | --- |
+| not-yet-mapped | not-yet-verified | Experimental | not-yet-verified | Registrar somente quando houver evidencia em runtime/codigo. |
+
+## 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 |
+| --- | --- | --- | --- | --- |
+| tabs[] | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Active. |
+| nav | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Active. |
+| behavior | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Partial. |
+| appearance | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Partial. |
+| widgets/content | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Partial. |
+| events/accessibility/meta | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 1 path(s) mapeado(s), status predominante Partial. |
+
+### Nested configuration blocks
+
+| Path | Type | Required | Default | Constraints | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `group mode` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
+| `nav mode` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
+| `tabs[].id/textLabel` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
+| `nav.links[].id/label` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
+| `behavior.*` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
+| `appearance.*` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
+| `widgets/content` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
+| `events/accessibility/meta` | not-specified | not-specified | n/a | component-defined | Preservado da documentação anterior. |
+
+### Input bindings
+
+| Binding/Path | Type | Required | Source | Runtime normalization | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `config` | `TabsMetadata` | opcional | component-input | not-yet-verified | Preservado da documentação anterior. |
+
+### Output events
+
+| Event | Payload | Trigger | Stability | Notes |
+| --- | --- | --- | --- | --- |
+| component-outputs | see-detailed-api | runtime-event | Partial | Eventos preservados na referência detalhada. |
+
+### External side channels
+
+| Channel | Direction | Contract | Failure mode | Notes |
+| --- | --- | --- | --- | --- |
+| host/services/storage | bidirectional | see-detailed-api | not-yet-verified | Side channels dependem do componente e do host consumidor. |
+
+### Host/runtime dependencies
+
+| Dependency | Required | Environment | Purpose | Notes |
+| --- | --- | --- | --- | --- |
+| see-source-of-truth | true | browser/dev/prod/ssr | runtime linkage | Confirmar por componente quando necessario. |
+
+## 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. defaults do componente
+2. contrato JSON recebido
+3. overrides de host/runtime
+4. normalizacoes internas
+
+### Fallback order
+
+contrato explicito -> aliases legados (quando suportados) -> defaults internos -> comportamento seguro
+
+### Override points
+
+- inputs publicos do componente
+- configuracao JSON de runtime
+- integracoes de host (servicos/tokens/adapters)
+
+### Runtime normalization
+
+Campos e aliases preservados do documento anterior devem convergir progressivamente para paths canonicos declarados.
+
+### Precedence rules
+
+Quando houver conflito entre alias e path canonico, priorizar path canonico e manter alias apenas para backward compatibility.
+
+## Validation and error semantics
+
+### Validation model
+
+| Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
+| --- | --- | --- | --- | --- |
+| see-detailed-api | runtime | warn-or-reject | not-yet-standardized | Semantica de validacao preservada do documento anterior. |
+
+### Error semantics
+
+Erros devem ser classificados em warnings recuperaveis versus falhas bloqueantes. Quando a evidencia nao estiver explicita, tratar como not yet verified.
+
+### Fail-open / fail-closed behavior
+
+| Condition | Mode | Runtime behavior | Consumer impact |
+| --- | --- | --- | --- |
+| invalid-or-unknown-field | component-defined | not-yet-verified | Variavel por componente; requer verificacao em runtime. |
+
+### 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)
+
+`tabs-quick-setup` e o acelerador de bootstrap do `praxis-tabs`: ele gera um contrato inicial valido em segundos para `group mode` ou `nav mode`. Nao substitui o editor completo; ele reduz tempo de partida com um payload limpo e previsivel.
+
+### Prova em 20 segundos
+
+Defina modo e labels e gere automaticamente a base de configuracao:
+
+```json
+{
+  "mode": "group",
+  "labels": ["Dados Gerais", "Historico"],
+  "dynamicHeight": true,
+  "stretchTabs": true
+}
+```
+
+Saida gerada pelo quick setup:
+
+```json
+{
+  "config": {
+    "group": {
+      "dynamicHeight": true,
+      "stretchTabs": true,
+      "selectedIndex": 0
+    },
+    "tabs": [
+      { "id": "tab1", "textLabel": "Dados Gerais" },
+      { "id": "tab2", "textLabel": "Historico" }
+    ]
+  }
+}
+```
+
+### Table of contents
+
+- [Start here](#start-here)
+  - [Promessa e limites](#promessa-e-limites)
+  - [Status model](#status-model)
+  - [Checklist de uso rapido](#checklist-de-uso-rapido)
+- [Guia operacional (produto)](#guia-operacional-produto)
+  - [Entrada e saida](#entrada-e-saida)
+  - [Fluxo operacional](#fluxo-operacional)
+  - [Regras de geracao](#regras-de-geracao)
+  - [Cobertura do contrato](#cobertura-do-contrato)
+- [Contrato tecnico completo (referencia)](#contrato-tecnico-completo-referencia)
+  - [Modelo interno (`QuickSetupModel`)](#modelo-interno-quicksetupmodel)
+  - [Coverage matrix](#coverage-matrix)
+- [Examples](#examples)
+- [Known limitations and mismatches](#known-limitations-and-mismatches)
+- [Source references](#source-references)
+
+### Start here
+
+#### Promessa e limites
+
+**O que isso habilita:** criacao imediata de estrutura de tabs com contrato valido para runtime.
+
+**Quando usar:** no inicio de uma tela nova ou quando o usuario precisa sair do zero rapidamente.
+
+**Exemplo minimo:** 2 labels + modo `group`.
+
+Garantias (hoje):
+
+- gera payload consistente no formato `{ config }`.
+- normaliza labels (trim + descarte de vazios).
+- define `selectedIndex=0` no modo escolhido.
+
+Limites (hoje):
+
+- nao gera `widgets`, `content`, `appearance` ou `behavior`.
+- nao cobre ajustes finos de acessibilidade/eventos.
+- nao valida colisoes avancadas de id apos merges externos.
+
+#### Status model
+
+Padrao oficial neste documento:
+
+- `Status: Active` - comportamento efetivo do assistente.
+- `Status: Stored-only` - dado existente no contrato, mas nao gerado aqui.
+- `Status: Planned` - reservado para evolucao futura.
+
+#### Checklist de uso rapido
+
+- Escolha `mode` antes de cadastrar labels.
+- Cadastre pelo menos 1 label valido.
+- Use o output como base e refine no `praxis-tabs-config-editor`.
+- Renomeie ids tecnicos (`tab1`, `link1`) quando houver regra de negocio.
+
+### Guia operacional (produto)
+
+#### Entrada e saida
+
+**O que isso habilita:** integracao objetiva com `SettingsPanelService`.
+
+**Quando usar:** em fluxo de quick start com apply/save imediato.
+
+**Exemplo minimo:** `content.component = TabsQuickSetupComponent`.
+
+`Status: Active`.
+
+##### Entrada (`SETTINGS_PANEL_DATA`)
+
+| Campo | Tipo | Required | Status | Observacao |
+| --- | --- | --- | --- | --- |
+| `config` | `TabsMetadata` | opcional | Active | seed para `mode`, labels e toggles |
+
+##### Saida (`SettingsValueProvider`)
+
+| Superficie | Tipo | Status | Observacao |
+| --- | --- | --- | --- |
+| `isDirty$` | `BehaviorSubject<boolean>` | Active | compara model atual com snapshot inicial |
+| `isValid$` | `BehaviorSubject<boolean>` | Active | true quando existe ao menos 1 label valido |
+| `isBusy$` | `BehaviorSubject<boolean>` | Active | reservado para fluxo async |
+| `getSettingsValue()` | `() => { config: TabsMetadata }` | Active | usado em `applied$` |
+| `onSave()` | `() => { config: TabsMetadata }` | Active | usado em `saved$` |
+
+#### Fluxo operacional
+
+**O que isso habilita:** bootstrap com poucos passos e baixo risco.
+
+**Quando usar:** para desbloquear rapidamente a primeira versao da tela.
+
+**Exemplo minimo:** labels + toggles basicos + salvar.
+
+`Status: Active`.
+
+1. Recebe seed opcional (`config`).
+2. Normaliza labels iniciais (trim e remove vazios).
+3. Permite editar `mode`, labels e toggles basicos.
+4. Valida formulario (`isValid$`).
+5. Retorna `{ config }` para apply/save.
+
+#### Regras de geracao
+
+**O que isso habilita:** previsibilidade de output entre squads e ambientes.
+
+**Quando usar:** para padronizar bootstrap em produto enterprise.
+
+**Exemplo minimo:** `mode='nav'` gera `nav.links[]` com ids tecnicos sequenciais.
+
+`Status: Active`.
+
+1. `mode='group'`:
+  - gera `group.selectedIndex=0`
+  - respeita `dynamicHeight` e `stretchTabs`
+  - gera `tabs[]` por labels normalizados
+
+2. `mode='nav'`:
+  - gera `nav.selectedIndex=0`
+  - respeita `stretchTabs`
+  - gera `links[]` por labels normalizados
+
+3. IDs:
+  - `tab1..N` / `link1..N`
+  - host pode substituir por ids de negocio
+
+4. Validacao:
+  - labels invalidos nao entram no payload
+
+#### Cobertura do contrato
+
+**O que isso habilita:** entendimento rapido de ate onde vai o quick setup.
+
+**Quando usar:** antes de prometer cobertura total do `TabsMetadata`.
+
+**Exemplo minimo:** saber que `widgets` nao sao gerados aqui.
+
+`Status: Partial`.
+
+- Coberto: estrutura base de `group/tabs` ou `nav/links`.
+- Nao coberto: `behavior`, `appearance`, `widgets`, `content`, `events`, `accessibility` avancada.
+
+### Contrato tecnico completo (referencia)
+
+#### Modelo interno (`QuickSetupModel`)
+
+```ts
+interface QuickSetupModel {
+  mode: 'group' | 'nav';
+  labels: string[];
+  dynamicHeight?: boolean;
+  stretchTabs?: boolean;
+}
+```
+
+#### Coverage matrix
+
+| Geracao | Status | Regra |
+| --- | --- | --- |
+| `group mode` | Active | gera `group.selectedIndex=0`, `group.dynamicHeight`, `group.stretchTabs`, `tabs[]` |
+| `nav mode` | Active | gera `nav.selectedIndex=0`, `nav.stretchTabs`, `links[]` |
+| `tabs[].id/textLabel` | Active | ids sequenciais `tab1..N` |
+| `nav.links[].id/label` | Active | ids sequenciais `link1..N` |
+| `behavior.*` | Stored-only | quick setup nao gera esse bloco |
+| `appearance.*` | Stored-only | quick setup nao gera esse bloco |
+| `widgets/content` | Stored-only | quick setup nao gera widgets nem fields |
+| `events/accessibility/meta` | Stored-only | nao gerados pelo assistente |
+
+### Examples
+
+### Minimal valid
+
+```json
+{
+  "mode": "group",
+  "labels": ["Dados Gerais", "Historico"],
+  "dynamicHeight": true,
+  "stretchTabs": true
+}
+```
+
+### Typical/common
+
+```json
+{
+  "config": {
+    "group": {
+      "dynamicHeight": true,
+      "stretchTabs": true,
+      "selectedIndex": 0
+    },
+    "tabs": [
+      { "id": "tab1", "textLabel": "Dados Gerais" },
+      { "id": "tab2", "textLabel": "Historico" }
+    ]
+  }
+}
+```
+
+### 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 | unificar para taxonomia canonica (Active/Partial/Declared-only/...) | next-doc-cycle | manter backward compatibility documentada |
+
+## 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/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/praxis-tabs.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |