@praxisui/tabs 9.0.0-beta.1 → 9.0.0-beta.2

package/README.md

@@ -1,7 +1,7 @@
 ---
 title: "Tabs"
 slug: "tabs-overview"
-description: "Visao geral do @praxisui/tabs com modos group/nav, conteudo metadata-driven, persistencia por tabsId e editor integrado."
+description: "Public npm documentation for @praxisui/tabs: group/nav modes, metadata-driven content, controlled selected index, persistence and runtime authoring."
 doc_type: "reference"
 document_kind: "component-overview"
 component: "tabs"
@@ -24,7 +24,7 @@ icon: "tabs"
 toc: true
 sidebar: true
 search_boost: 1.0
-reading_time: 12
+reading_time: 5
 estimated_setup_time: 20
 version: "1.0"
 related_docs:
@@ -35,291 +35,122 @@ keywords:
   - "mat-tab-group"
   - "tab nav"
   - "tabsId persistence"
-last_updated: "2026-03-07"
+last_updated: "2026-06-16"
 ---
 
-# @praxisui/tabs — Praxis Tabs
+# @praxisui/tabs
 
-## Documentation
+`@praxisui/tabs` renders configurable group tabs and navigation tabs for Praxis UI Angular applications. Install it when a host needs metadata-driven tab composition, nested widgets, runtime editing, persisted configuration and controlled navigation state.
 
-- Documentação oficial: https://praxisui.dev/components/tabs
-- Aplicação de referência: https://github.com/codexrodrigues/praxis-ui-quickstart
-- Demo publicado: https://praxis-ui-4e602.web.app
-- Indicado para: navegacao por abas metadata-driven com persistencia, widgets internos e editor em runtime
+Use this package for UI composition. The host still owns route-level state, domain persistence, widget data providers and authorization.
 
-## When to use
-
-- Organizar conteudo em grupos ou navegacao por abas com metadados
-- Persistir configuracao e comportamento por instancia de tabs
-- Compor tabs com widgets e campos dinamicos sem implementar cada variacao manualmente
-
-Componente de abas (grupo e nav) configurável por metadados, com suporte a widgets internos, presets de estilo e editor integrado via Settings Panel.
-
-## Instalação
+## Install
 
 ```bash
 npm i @praxisui/tabs@latest
 ```
 
 Peer dependencies:
-- `@angular/core` `^21.0.0`
-- `@angular/common` `^21.0.0`
-- `@angular/forms` `^21.0.0`
-- `@angular/router` `^21.0.0`
-- `@angular/cdk` `^21.0.0`
-- `@angular/material` `^21.0.0`
-- `@praxisui/core` `^9.0.0-beta.1`
-- `@praxisui/dynamic-fields` `^9.0.0-beta.1`
-- `@praxisui/settings-panel` `^9.0.0-beta.1`
-- `@praxisui/ai` `^9.0.0-beta.1`
+
+- `@angular/common`, `@angular/core`, `@angular/forms`, `@angular/router`, `@angular/cdk`, `@angular/material` `^21.0.0`
+- `@praxisui/core`, `@praxisui/dynamic-fields`, `@praxisui/settings-panel`, `@praxisui/ai` `^9.0.0-beta.1`
 - `rxjs` `~7.8.0`
 
-## Minimal standalone tabs
+Runtime dependency included by the package:
+
+- `immer` `^10.1.1`
+
+## Minimal Standalone Tabs
 
 ```ts
 import { Component } from '@angular/core';
-import { PraxisTabs } from '@praxisui/tabs';
+import { PraxisTabs, type TabsMetadata } from '@praxisui/tabs';
 
 @Component({
   selector: 'app-tabs-host',
   standalone: true,
   imports: [PraxisTabs],
-  template: `<praxis-tabs tabsId="profile-tabs" [config]="config" />`,
+  template: `
+    <praxis-tabs
+      tabsId="profile-tabs"
+      [config]="config"
+      [selectedIndex]="selectedIndex"
+      (selectedIndexChange)="selectedIndex = $event"
+    />
+  `,
 })
 export class TabsHostComponent {
-  config = {
-    mode: 'group',
+  selectedIndex = 0;
+
+  readonly config: TabsMetadata = {
+    group: { selectedIndex: 0, stretchTabs: true },
     tabs: [
-      { id: 'summary', label: 'Summary' },
-      { id: 'history', label: 'History' },
+      { id: 'summary', textLabel: 'Summary' },
+      { id: 'history', textLabel: 'History' },
     ],
   };
 }
 ```
 
-## Visão Geral
-
-- 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 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
-
-Selector
-- `praxis-tabs`
-
-Inputs
-- `config: TabsMetadata | null` Metadados completos para aparência, comportamento e conteúdo.
-- `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`).
-- `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.
-- `configChange: TabsConfigChangeEvent` Emite `inputPatch.config` quando autoria assistida altera `TabsMetadata`, permitindo que hosts persistam a nova configuração no manifesto/página canônica.
-- `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>`.
-- O `component_id` é derivado via `ComponentKeyService` (inclui rota, tipo de componente, `tabsId` e `componentInstanceId` quando informado).
-
-## Empty State e Quick Setup
+## Main Inputs And Outputs
 
-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)
-
-```ts
-export interface TabsMetadata {
-  appearance?: {
-    density?: 'compact' | 'comfortable' | 'spacious';
-    themeClass?: string;
-    customCss?: string;             // CSS injetado inline
-    tokens?: Partial<TabsStyleTokens>; // tokens -> CSS gerado em runtime
-  };
-  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; 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 };
-}
-```
+- `config: TabsMetadata | null`: canonical tabs/nav configuration.
+- `tabsId: string`: stable id used for local configuration persistence.
+- `componentInstanceId?: string`: disambiguates multiple instances with the same `tabsId`.
+- `form?: FormGroup`: form context for dynamic field content.
+- `context?: unknown`: context passed to nested widgets.
+- `selectedIndex?: number`: controlled active tab index.
+- `enableCustomization?: boolean`: shows runtime editing affordances.
+- `selectedIndexChange`: emits user tab changes.
+- `configChange`: emits host-persistable config patches after runtime authoring.
+- `widgetEvent`: legacy/advanced bridge for nested widget events; prefer composition links for new integrations.
 
-Tokens de Estilo (M3 aproximados)
-- Exemplos: `active-indicator-color`, `active-label-text-color`, `inactive-label-text-color`, `pagination-icon-color`, `divider-color`, `background-color`.
-- São transformados em CSS scoped por `data-tabs-id` em tempo de execução.
+Controlled `selectedIndex` updates the active tab without re-emitting `selectedIndexChange`, which prevents loops in dynamic-page state projections.
 
-## Editor de Configuração (Settings Panel)
+## Metadata Shape
 
-Abrindo o editor completo programaticamente:
+`TabsMetadata` supports two primary modes:
 
 ```ts
-const ref = settings.open({
-  id: `praxis-tabs-editor:${tabsId || 'default'}`,
-  title: 'Configurar Tabs',
-  content: { component: PraxisTabsConfigEditor, inputs: { config, tabsId } },
-});
-ref.applied$.subscribe(value => apply(value)); // mantém painel aberto
-ref.saved$.subscribe(value => apply(value));   // fecha painel
-```
-
-Contrato do Editor (`PraxisTabsConfigEditor` implementa `SettingsValueProvider`):
-- `isDirty$`, `isValid$`, `isBusy$` controlam a habilitação dos botões.
-- `getSettingsValue()` e `onSave()` retornam `{ config: TabsMetadata }`.
-- Abas do editor: Comportamento, Grupo, Nav, JSON, Estilo, Abas, Links.
-- 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.
-- `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.
-- **Current-area authoring:** pedidos como “nesta aba”, “aba atual” ou “dentro da aba” devem materializar `tab.content.set` no item ativo/resolvido, não `tab.add`; criar nova aba exige intenção explícita como “nova aba” ou “adicionar aba”.
-- **Registry projection:** o manifesto é exportado no `public-api` e projetado em `components['praxis-tabs'].authoringManifest` pelo AI Registry.
-
-### Praxis Semantic Assistant
-
-When `enableCustomization=true`, `praxis-tabs` opens the shared `PraxisAiAssistantShellComponent` and registers a minimized global session instead of embedding the legacy `PraxisAiAssistantComponent`.
-
-- The assistant context is safe and semantic: component identity, tabs id, current mode, tab/link counts, field-name digest, manifest reference and governance hints.
-- Business-rule, policy, compliance, publication, materialization or enforcement prompts are routed to governed `domain-rules/intake` handoff and are not applied as local tabs configuration.
-- Free JSON patches from the backend are rejected. Local apply remains blocked until the response is compiled from a manifest-backed `componentEditPlan` validated against `PRAXIS_TABS_AUTHORING_MANIFEST`.
-- `TabsAiAdapter.applyPatch(...)` remains available for legacy/editor internals, but the new assistant turn flow does not use it as an ungoverned patch path.
-
-## Eventos e Conexões
-
-Para conexoes canonicas de widgets internos, use `composition.links` com endpoint `component-port + nestedPath`.
-
-Exemplo de output de uma lista dentro da primeira tab:
+const groupTabs: TabsMetadata = {
+  behavior: { lazyLoad: true },
+  group: { selectedIndex: 0, dynamicHeight: true },
+  tabs: [
+    { id: 'general', textLabel: 'General' },
+    { id: 'orders', textLabel: 'Orders', widgets: [{ id: 'praxis-table' }] },
+  ],
+};
 
-```json
-{
-  "kind": "component-port",
-  "ref": {
-    "widget": "tabs-widget",
-    "nestedPath": [
-      { "kind": "tab", "id": "employees-list", "index": 0 },
-      { "kind": "widget", "key": "employees-list", "componentType": "praxis-list" }
+const navTabs: TabsMetadata = {
+  nav: {
+    selectedIndex: 0,
+    links: [
+      { id: 'overview', label: 'Overview' },
+      { id: 'settings', label: 'Settings' },
     ],
-    "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 }`.
-- 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
-
-- Ative `behavior.lazyLoad = true` para renderizar conteúdo somente quando a aba/link é visitado.
-- O componente gerencia caches de índices visitados para não re-renderizar desnecessariamente.
+Use stable ids for tabs and nav links. When `tabsId` is provided, the component stores configuration under a key derived from route, component type, `tabsId` and optional `componentInstanceId`.
 
-## Exemplo Mínimo
+## Runtime Authoring
 
-```html
-<praxis-tabs [config]="tabsCfg" [tabsId]="'cliente-tabs'" [enableCustomization]="true"></praxis-tabs>
-```
-
-```ts
-// tabsCfg simples (modo grupo)
-const tabsCfg: TabsMetadata = {
-  group: { selectedIndex: 0 },
-  tabs: [
-    { id: 't1', textLabel: 'Geral', widgets: [{ id: 'praxis-dynamic-form', inputs: { resourcePath: 'clientes' } }] },
-    { id: 't2', textLabel: 'Pedidos', widgets: [{ id: 'praxis-table', inputs: { resourcePath: 'pedidos' } }] },
-  ],
-};
-```
+With `enableCustomization`, the component can open quick setup or the full `PraxisTabsConfigEditor` through Settings Panel. The editor round-trips through `TabsAuthoringDocument`, applies only runtime-backed fields and emits `configChange` so the host can persist canonical page or manifest changes.
 
-Observacao de host:
-- `praxis-table` se auto-hospeda para `GenericCrudService`.
-- `praxis-dynamic-form` remoto continua dependendo de `GenericCrudService` provido pelo host efetivo quando usar `resourcePath`, `resourceId`, schema remoto ou submit remoto.
-- ao embutir `praxis-dynamic-form` em tabs, stepper ou shells equivalentes, nao presumir que o widget sozinho resolve a DI de CRUD.
+`PRAXIS_TABS_AUTHORING_MANIFEST` describes the governed AI/tooling operations for tab add/remove, labels, icons, order, visibility, disabled state, active tab, layout and tab content. Free JSON patches from AI flows are not the public authoring contract.
 
-## Acessibilidade
+## Accessibility
 
-- 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`.
+For group mode, set `group.ariaLabel`, `group.ariaLabelledby`, `tabs[].ariaLabel` or `tabs[].ariaLabelledby` where needed. For nav mode, set `nav.ariaLabel` or `nav.ariaLabelledby`. `accessibility.reduceMotion` and `accessibility.highContrast` are the supported top-level accessibility flags.
 
-## Notas
+## Public API Snapshot
 
-- 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.
+Main exports include `PraxisTabs`, `TabsMetadata`, i18n helpers, runtime metadata, `PraxisTabsConfigEditor`, `PraxisTabsWidgetConfigEditor`, tabs authoring document helpers, AI capabilities and `PRAXIS_TABS_AUTHORING_MANIFEST`.
 
-### Tokens M3 obrigatórios (host)
+## Official Links
 
-- 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`
+- Documentation: https://praxisui.dev/components/tabs
+- Live demo: https://praxis-ui-4e602.web.app
+- Quickstart repository: https://github.com/codexrodrigues/praxis-ui-quickstart
+- Source and issues: https://github.com/codexrodrigues/praxis-ui-angular

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@praxisui/tabs",
-  "version": "9.0.0-beta.1",
+  "version": "9.0.0-beta.2",
   "description": "Configurable tabs (group and nav) for Praxis UI with metadata-driven content and runtime editor.",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
     "@angular/material": "^21.0.0",
     "@angular/cdk": "^21.0.0",
-    "@praxisui/core": "^9.0.0-beta.1",
-    "@praxisui/dynamic-fields": "^9.0.0-beta.1",
-    "@praxisui/settings-panel": "^9.0.0-beta.1",
+    "@praxisui/core": "^9.0.0-beta.2",
+    "@praxisui/dynamic-fields": "^9.0.0-beta.2",
+    "@praxisui/settings-panel": "^9.0.0-beta.2",
     "@angular/forms": "^21.0.0",
     "@angular/router": "^21.0.0",
-    "@praxisui/ai": "^9.0.0-beta.1",
+    "@praxisui/ai": "^9.0.0-beta.2",
     "rxjs": "~7.8.0"
   },
   "dependencies": {
@@ -25,7 +25,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/codexrodrigues/praxis-ui-angular"
+    "url": "git+https://github.com/codexrodrigues/praxis-ui-angular.git"
   },
   "homepage": "https://praxisui.dev",
   "bugs": {