@praxisui/tabs 0.0.1

package/LICENSE

@@ -0,0 +1,7 @@
+This package is licensed under the Apache License, Version 2.0.
+
+For the full license text, see the repository root LICENSE file:
+../../LICENSE
+
+Apache License 2.0: https://www.apache.org/licenses/LICENSE-2.0
+

package/README.md

@@ -0,0 +1,127 @@
+# @praxis/tabs — Praxis Tabs
+
+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
+
+- 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`.
+- Lazy load opcional do conteúdo para melhor desempenho.
+- Eventos reemitidos com contexto (para conexões entre widgets/páginas).
+
+## 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.
+- `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).
+
+Outputs
+- `selectedIndexChange: number` Índice selecionado atualizado (ambos modos).
+- `selectedTabChange: MatTabChangeEvent` Evento nativo do MatTabGroup.
+- `focusChange, animationDone, indexFocused, selectFocusedIndex` Eventos nativos do Angular Material.
+- `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>`.
+
+## 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?: { 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; };
+  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 };
+}
+```
+
+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.
+
+## Editor de Configuração (Settings Panel)
+
+Abrindo o editor completo programaticamente:
+
+```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`.
+
+Quick Setup
+- `openQuickSetup()` abre `TabsQuickSetupComponent` para criação rápida de abas/links.
+- `applied$`/`saved$` aplicam a configuração ao componente.
+
+## Eventos e Conexões
+
+`widgetEvent` reemite eventos de widgets internos com contexto da origem, permitindo conexões no Builder/Graph:
+
+- Forma do evento: `{ tabId?, tabIndex?, linkId?, linkIndex?, sourceId, output?, payload }`.
+- De um componente interno para fora:
+  - From: `{ widget: '<key do tabs>', output: 'widgetEvent' }`
+  - Map (exemplo tabela interna): `payload.payload.id`
+  - To: `<widget externo>.<input>`
+- De fora para um componente interno (dot-path):
+  - Grupo: `inputs.config.tabs[<idx>].widgets[<widx>].inputs.<input>`
+  - Nav: `inputs.config.nav.links[<idx>].widgets[<widx>].inputs.<input>`
+
+## 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.
+
+## Exemplo Mínimo
+
+```html
+<praxis-tabs [config]="tabsCfg" [tabsId]="'cliente-tabs'" [editModeEnabled]="true" (widgetEvent)="onWidgetEvent($event)"></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' } }] },
+  ],
+};
+```
+
+## 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`).
+
+## 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.