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

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)

Supported legacy paths

Nenhum path legado suportado foi identificado nesta revisão baseada em evidência textual preservada.

Internal-only paths

Experimental paths

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

Nested configuration blocks

Input bindings

Output events

External side channels

Host/runtime dependencies

Coverage matrix

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

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

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

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:

{
  "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
  • Promessa e limites
  • Dicionario oficial
  • Status model
  • Checklist corporativo pre-flight
• Guia operacional (produto)
  • Controle de entrada e saida
  • Precedencia de modo e fluxo de render
  • Persistencia, identidade e compatibilidade
  • Controle de comportamento
  • Acessibilidade e motion
  • Conteudo dinamico e widgets
  • Operacao em runtime (editor, quick setup, AI)
• Contrato tecnico completo (referencia)
  • Interfaces do contrato
  • Matriz top-level
  • Appearance API (deep dive)
  • Behavior API
  • Accessibility API
  • Group API (group + tabs[])
  • Nav API (nav + links[])
  • Complete JSON path index
• Styling
• Examples
• Known limitations and mismatches
• Source references
• 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

Notas operacionais:

• content nao renderiza se form for null.
• widgets renderizam com fallback de contexto para {}.

Component outputs

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.

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

1. 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$

1. Quick setup (TabsQuickSetupComponent)

• id: praxis-tabs-quick-setup:<key>
• bootstrap rapido de group+tabs ou nav+links
• normaliza labels e descarta vazios

1. 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.

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.

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

themeClass

customCss

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.

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.

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

tabs[]

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

nav.links[]

Complete JSON path index

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

{
  "behavior": { "lazyLoad": true },
  "group": { "selectedIndex": 0, "stretchTabs": true },
  "tabs": [
    { "id": "dados", "textLabel": "Dados" },
    { "id": "itens", "textLabel": "Itens" }
  ]
}

Typical/common

{}

Advanced

{}

Enterprise scenario

{}

Known limitations and mismatches

Compatibility and migration notes

Source references