@praxisui/tabs 1.0.0-beta.5 → 1.0.0-beta.52

package/README.md

@@ -1,5 +1,52 @@
+---
+title: "Tabs"
+slug: "tabs-overview"
+description: "Visao geral do @praxisui/tabs com modos group/nav, conteudo metadata-driven, persistencia por tabsId e editor integrado."
+doc_type: "reference"
+document_kind: "component-overview"
+component: "tabs"
+category: "components"
+audience:
+  - "frontend"
+  - "host"
+  - "architect"
+level: "intermediate"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "tabs"
+  - "navigation"
+  - "metadata"
+  - "settings-panel"
+  - "runtime"
+order: 34
+icon: "tabs"
+toc: true
+sidebar: true
+search_boost: 1.0
+reading_time: 12
+estimated_setup_time: 20
+version: "1.0"
+related_docs:
+  - "consumer-integration-quickstart"
+  - "host-integration-guide"
+keywords:
+  - "tabs metadata"
+  - "mat-tab-group"
+  - "tab nav"
+  - "tabsId persistence"
+last_updated: "2026-03-07"
+---
+
 # @praxisui/tabs — Praxis Tabs
 
+## 🔰 Exemplos / Quickstart
+
+Para ver esta biblioteca em funcionamento em uma aplicação completa, utilize o projeto de exemplo (Quickstart):
+
+- Repositório: https://github.com/codexrodrigues/praxis-ui-quickstart
+- O Quickstart demonstra a integração das bibliotecas `@praxisui/*` em um app Angular, incluindo instalação, configuração e uso em telas reais.
+
 Componente de abas (grupo e nav) configurável por metadados, com suporte a widgets internos, presets de estilo e editor integrado via Settings Panel.
 
 ## Visão Geral
@@ -7,9 +54,10 @@ Componente de abas (grupo e nav) configurável por metadados, com suporte a widg
 - Dois modos de renderização: `group` (mat-tab-group) e `nav` (mat-tab-nav-bar).
 - Suporte a conteúdo dinâmico por campo (`DynamicFieldLoader`) e por widget (`DynamicWidgetLoader`).
 - Integração com Settings Panel para edição/configuração em tempo de execução.
-- Persistência opcional de configuração por `tabsId` usando `ConfigStorage`.
+- Persistência de configuração por `tabsId` usando `AsyncConfigStorage` (chave derivada via component_id).
 - Lazy load opcional do conteúdo para melhor desempenho.
 - Eventos reemitidos com contexto (para conexões entre widgets/páginas).
+- Acessibilidade explícita por modo: `group.*` e `tabs[]` no modo group, `nav.*` no modo nav.
 
 ## API do Componente
 
@@ -18,7 +66,8 @@ Selector
 
 Inputs
 - `config: TabsMetadata | null` Metadados completos para aparência, comportamento e conteúdo.
-- `tabsId?: string` Identificador estável para persistir/restaurar a configuração.
+- `tabsId: string` Identificador estável para persistir/restaurar a configuração.
+- `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`).
 - `editModeEnabled?: boolean` Exibe botão de edição quando verdadeiro (abre o editor).
@@ -30,7 +79,18 @@ Outputs
 - `widgetEvent: { tabId?, tabIndex?, linkId?, linkIndex?, sourceId, output?, payload? }` Reemissão de eventos dos widgets internos com contexto da aba/link.
 
 Persistência
-- Quando `tabsId` é fornecido, a configuração é salva/recuperada de `ConfigStorage` na chave `tabs:<tabsId>`.
+- Quando `tabsId` é fornecido, a configuração é salva/recuperada em `AsyncConfigStorage` na chave `tabs:<component_id>`.
+- O `component_id` é derivado via `ComponentKeyService` (inclui rota, tipo de componente, `tabsId` e `componentInstanceId` quando informado).
+
+## Empty State e Quick Setup
+
+Quando o componente inicia sem `tabs` e sem `nav.links`, o runtime exibe um empty state com atalhos de inicializacao:
+
+- criar abas rapidamente via Quick Setup
+- adicionar aba vazia imediatamente
+- abrir editor completo de configuracao
+
+No Quick Setup, ao aplicar/salvar, o componente gera uma `TabsMetadata` minima e passa a renderizar abas/links com persistencia normal.
 
 ## Estrutura de Metadados (resumo)
 
@@ -43,10 +103,10 @@ export interface TabsMetadata {
     tokens?: Partial<TabsStyleTokens>; // tokens -> CSS gerado em runtime
   };
   behavior?: { lazyLoad?: boolean; closeable?: boolean; reorderable?: boolean };
-  accessibility?: { ariaLabels?: Record<string,string>; keyboardNavigation?: boolean; 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; };
+  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 };
+  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 };
 }
 ```
 
@@ -75,6 +135,7 @@ Contrato do Editor (`PraxisTabsConfigEditor` implementa `SettingsValueProvider`)
 - JSON: editor de texto com validação e botão “Formatar”.
 - Estilo: presets de tokens, classe de tema, CSS customizado e snippet SCSS sugerido.
 - Abas/Links: adicionar/remover/reordenar, inserir widgets, presets rápidos (form/table/crud) usando `resourcePath`.
+- O editor cobre apenas caminhos com binding real no runtime; campos sem efeito não são expostos na UI.
 
 Quick Setup
 - `openQuickSetup()` abre `TabsQuickSetupComponent` para criação rápida de abas/links.
@@ -117,11 +178,20 @@ const tabsCfg: TabsMetadata = {
 
 ## Acessibilidade
 
-- Suporte a `aria-label`/`aria-labelledby` em grupo e abas/links.
-- Opções para reduzir animações (`accessibility.reduceMotion`) e alto contraste (`accessibility.highContrast`).
+- Modo `group`: use `group.ariaLabel`, `group.ariaLabelledby`, `tabs[].ariaLabel` e `tabs[].ariaLabelledby`.
+- Modo `nav`: use `nav.ariaLabel` e `nav.ariaLabelledby`.
+- Opções top-level de acessibilidade com binding real: `accessibility.reduceMotion` e `accessibility.highContrast`.
 
 ## Notas
 
 - Para persistência por usuário/escopo, forneça `tabsId` estável e deixe o componente gerir `ConfigStorage`.
 - Tokens de estilo aceitam CSS vars ou cores (`#RRGGBB`/`rgb(...)`).
 - Em M2, `color` e `backgroundColor` seguem as opções do Angular Material; em M3, prefira tokens.
+- A classe de tema é decisão do host (`.dark-theme` ou `.theme-dark`/`.theme-light`); mantenha tokens e componentes no mesmo escopo.
+- `group.contentTabIndex`, `accessibility.ariaLabels` e `accessibility.keyboardNavigation` permanecem fora da superfície pública suportada enquanto não houver binding explícito no DOM.
+
+### Tokens M3 obrigatórios (host)
+
+- Superfícies: `--md-sys-color-surface`, `--md-sys-color-surface-container`, `--md-sys-color-surface-variant`
+- Texto/contorno: `--md-sys-color-on-surface`, `--md-sys-color-on-surface-variant`, `--md-sys-color-outline`, `--md-sys-color-outline-variant`
+- Semânticos: `--md-sys-color-primary`, `--md-sys-color-secondary`, `--md-sys-color-tertiary`, `--md-sys-color-error`