@praxisui/table 1.0.0-beta.1 → 1.0.0-beta.10

package/README.md

@@ -1,10 +1,10 @@
-# @praxis/table
+# @praxisui/table
 
 > Componente de tabela empresarial avançado com arquitetura unificada
 
 ## 🌟 Visão Geral
 
-A biblioteca `@praxis/table` fornece um componente de tabela robusto e altamente configurável para aplicações Angular empresariais. Com a nova arquitetura unificada, oferece uma experiência de desenvolvimento simplificada mantendo todos os recursos avançados.
+A biblioteca `@praxisui/table` fornece um componente de tabela robusto e altamente configurável para aplicações Angular empresariais. Com a nova arquitetura unificada, oferece uma experiência de desenvolvimento simplificada mantendo todos os recursos avançados.
 
 ## ✨ Características Principais
 
@@ -34,6 +34,188 @@ A biblioteca `@praxis/table` fornece um componente de tabela robusto e altamente
 - **Toolbar Editor**: Personalização de ações
 - **Messages Editor**: Textos e localização
 
+Nota (Regras)
+- A antiga aba visual genérica foi removida deste pacote. Um editor especializado para regras da Tabela está em desenvolvimento e já pode ser usado no painel de configuração.
+
+### 🧩 Editor de Regras (column-first)
+
+O novo editor é "column-first" e usa uma tipagem compartilhada com o Editor de Colunas. Principais pontos:
+
+- Escopo: aplique regras na linha inteira (rowConditionalStyles) ou em uma coluna específica (columns[].conditionalStyles).
+- Operadores por tipo: o conjunto de operadores é filtrado por tipo (string/number/date/boolean/enum).
+- Editores de valor dinâmicos: inputs numéricos, listas (CSV/múltipla seleção), datepickers.
+- Grupos lógicos: construa condições com AND/OR/NOT e reordene via arrastar-e-soltar (CDK DragDrop).
+- Preview: execute “Testar” para ver quantas linhas seriam afetadas pelas regras ativas.
+- Import/Export: exporta JSON sem o campo `enabled`; importa com validação de DSL e sanitização de estilos (allowlist).
+
+Exemplos de DSL:
+
+```text
+contains(status, 'Ativo')
+not (status in ['A', 'I'])
+(price >= 10 and price <= 20)
+(createdAt >= '2024-10-01' and createdAt <= '2024-10-31')
+(name == null or name == '')
+active == true
+```
+
+Notas sobre enum/CSV:
+- Para campos enumerados, as opções são inferidas de `valueMapping` da coluna ou de `fields?.options`.
+- Para `in/not in` em números/strings, use CSV (ex.: `10, 20, 30` ou `Alice, Bob`).
+
+#### Extensões de DSL (JSON/Tempo)
+
+Você pode registrar funções adicionais no `DslParser` do app host para expressões com JSON e data/tempo.
+
+Exemplo rápido (registro direto):
+```ts
+import { DslParser } from '@praxisui/specification';
+import { registerJsonDslFunctions, registerDateDslFunctions } from '@praxisui/table';
+
+const parser = new DslParser<any>();
+registerJsonDslFunctions(parser);
+registerDateDslFunctions(parser);
+```
+
+Exemplos de DSL:
+- `jsonGet(payload, '$.user.name') == 'Alice'`
+- `hasJsonKey(payload, '$.meta.etag')`
+- `jsonPathMatches(payload, '$.roles[0]', '^admin$')`
+
+Guia completo: `projects/praxis-table/docs/DSL-Extensions-Guide.md`
+
+#### 🎨 Efeitos (Conteúdo C)
+
+O bloco de Efeitos permite aplicar estilo e visuais quando a condição é verdadeira:
+
+- Toolbar de texto com ícones (negrito, itálico, sublinhado) e presets rápidos (tachado, maiúsculas/minúsculas/capitalizar, tamanho +/- e reset).
+- Presets de feedback com ícones (sucesso, aviso, erro, info) — mantêm o rótulo via tooltip e `aria-label`.
+- “Posição do valor” como grupo de alternância (antes / entre-1 / entre-2 / depois / oculto).
+- “Ordem dos visuais” com seletor compacto (3 mais comuns) e menu para opções extras.
+- Layout do compose: espaçamento, alinhamento, quebra de linha e reticências.
+
+Dicas
+- Use “Resetar texto” para reverter efeitos de texto sem perder cor de fundo/borda.
+- Para acessibilidade, os grupos possuem `role="toolbar"`, tooltips e navegação por teclado consistente.
+
+Como reverter efeitos
+- “Reset Text” remove apenas propriedades de tipografia e transformação de texto.
+- “Limpar efeitos” apaga classe e estilo livres do bloco rápido.
+
+Observação: capturas de tela “antes/depois” podem ser adicionadas no PR conforme necessário.
+
+#### Relacionais (lookup)
+
+Campos relacionais (FK/objetos) podem ser editados no Rules Editor com busca assíncrona (typeahead) e seleção single/multiple.
+
+Boas práticas
+- Informe `resourcePath` (ou `endpoint`) no `FieldDefinition` para habilitar o lookup via `GenericCrudService` do host.
+- Defina `valueField` (chave estável, tipicamente `id`) e `displayField` (label amigável, como `name`).
+- Para múltipla seleção, use `multiple: true` no `FieldDefinition` quando aplicável.
+- No runtime, registre as funções JSON no parser (ver guia) para que as expressões de ID/JSON funcionem: `jsonGet/hasJsonKey/jsonPathMatches`.
+- APIs com busca: suporte a um parâmetro livre de texto (por ex. `search`) facilita a experiência do autocomplete.
+
+Exemplo de FieldDefinition (lookup)
+```ts
+import type { FieldDefinition } from '@praxisui/core';
+
+const fields: FieldDefinition[] = [
+  {
+    name: 'customer',
+    type: 'object',
+    // Habilita o lookup via GenericCrudService
+    resourcePath: 'customers',
+    // Mapeia o id/label que virão do backend
+    valueField: 'id',
+    displayField: 'name',
+    // Se quiser multiseleção em todo o app
+    // multiple: true,
+  },
+];
+```
+
+Operadores e DSL gerada (relacional)
+- `id ==` → `jsonGet(customer, '$.id') == 10`
+- `id in` → `jsonGet(customer, '$.id') in [10, 20]`
+- `has property` → `hasJsonKey(customer, '$.meta.etag')`
+- Condições por caminho (join simples): use `key ==` (JSON Path + valor)
+
+UI (no editor)
+- `id ==` (single): autocomplete + chip “label [id]” com ação “Limpar”.
+- `id in` (multi): autocomplete + chips removíveis por item.
+- `has property`: input do caminho (ex.: `$.meta.etag`).
+
+Formato esperado do payload (relacional)
+
+Para que o editor/preview e o runtime avaliem corretamente as regras relacionais, o valor do campo deve ser um objeto (ou compatível com JSON) contendo ao menos o identificador e, opcionalmente, propriedades exibidas:
+
+```ts
+// Exemplo de linha (row) com campo relacional "customer"
+const row = {
+  id: 123,
+  customer: {
+    id: 10,          // ← usado em id == / id in via jsonGet(customer, '$.id')
+    name: 'ACME',    // ← usado para exibir label no autocomplete/chip
+    meta: { etag: 'v1' },
+  },
+};
+
+// Regras DSL comuns
+// id ==
+//   jsonGet(customer, '$.id') == 10
+// id in
+//   jsonGet(customer, '$.id') in [10, 20]
+// has property
+//   hasJsonKey(customer, '$.meta.etag')
+// caminho/valor (join simples)
+//   jsonGet(customer, '$.name') == 'ACME'
+```
+
+Notas
+- O editor usa `displayField` (ex.: `name`) para compor o rótulo, e `valueField` (ex.: `id`) para gerar a DSL.
+- Se o backend devolver o relacionamento já "normalizado" (ex.: `customerId` e `customerName` na mesma linha), você ainda pode expressar condições com operadores padrão (`==`, `in`) no campo numérico/literal — a abordagem relacional é útil quando o payload contém o objeto.
+
+Onde é consumido (preview e runtime)
+
+- Preview/validação no Editor de Regras (usa `DslParser` interno):
+  - Validação da expressão (parse): projects/praxis-table/src/lib/rules-editor/table-rules-editor.component.ts:536
+  - Preview “Testar” (parse + evaluate): projects/praxis-table/src/lib/rules-editor/table-rules-editor.component.ts:909
+- Runtime na Tabela (aplica `rowConditionalStyles`/`conditionalStyles`):
+  - Parser interno do componente: projects/praxis-table/src/lib/praxis-table.ts:282
+
+Observação
+- Ao registrar funções via `DslParserFactory` (ex.: `registerJsonDslFunctions`/`registerDateDslFunctions`), use a mesma estratégia para o parser que avalia regras no runtime (Tabela) e para qualquer serviço que precise avaliar DSL. O Editor usa um parser interno para validação/preview; as funções de data já são suportadas por padrão, e as de JSON podem exigir extensão no runtime (ver guia).
+
+Exemplo de Provider (recomendado)
+
+```ts
+import { Injectable } from '@angular/core';
+import { DslParser } from '@praxisui/specification';
+import { registerJsonDslFunctions, registerDateDslFunctions } from '@praxisui/table';
+
+@Injectable({ providedIn: 'root' })
+export class DslParserFactory {
+  private parser: DslParser<any>;
+
+  constructor() {
+    this.parser = new DslParser<any>();
+    registerJsonDslFunctions(this.parser);
+    registerDateDslFunctions(this.parser);
+  }
+
+  get(): DslParser<any> {
+    return this.parser;
+  }
+}
+
+// Em um componente/serviço que avalia regras:
+// constructor(factory: DslParserFactory) {
+//   const parser = factory.get();
+//   const spec = parser.parse("jsonGet(payload, '$.user.name') == 'Alice'");
+//   const ok = spec.isSatisfiedBy({ payload: { user: { name: 'Alice' } } });
+// }
+```
+
 ### ⚙️ Painel de Configurações
 
 Para abrir o painel de configurações, habilite o modo de edição na tabela:
@@ -178,6 +360,46 @@ sequenceDiagram
 - Virtualização: habilite em Comportamento → Virtualização para listas grandes (requer altura de linha previsível).
 - Densidade e linhas de grade: ajuste em Comportamento → Aparência rápida (compacta/confortável/espaçosa; bordas horizontais/verticais).
 
+## Rolagem Horizontal (owner do scroll)
+
+Por padrão, a `<praxis-table>` agora assume a responsabilidade pela rolagem horizontal quando o conteúdo excede a largura do container. Isso evita cortes de conteúdo e comportamentos inconsistentes entre projetos.
+
+### Input: `horizontalScroll`
+
+```
+@Input() horizontalScroll: 'auto' | 'wrap' | 'none' = 'auto';
+```
+
+- `auto` (padrão): a tabela cria um viewport com `overflow-x: auto` e permite que a tabela interna cresça com `width: max-content`. Quando a soma das colunas > container, aparece a barra de rolagem horizontal neste viewport.
+- `wrap`: permite quebra de linha nas células (libera `white-space: normal`), reduzindo a largura necessária; ideal quando você prefere minimizar a rolagem horizontal.
+- `none`: desabilita o comportamento interno; o host (página) deve fornecer o container com `overflow-x: auto` e as regras de largura necessárias.
+
+Exemplo:
+
+```html
+<!-- Comportamento padrão (auto) -->
+<praxis-table resourcePath="employees"></praxis-table>
+
+<!-- Reduz rolagem: permite quebra de linha nas células -->
+<praxis-table resourcePath="employees" horizontalScroll="wrap"></praxis-table>
+
+<!-- Host controla o scroll horizontal -->
+<div class="table-shell" style="overflow-x:auto">
+  <praxis-table resourcePath="employees" horizontalScroll="none"></praxis-table>
+  <!-- host pode usar width: max-content na tabela interna conforme seu design system -->
+</div>
+```
+
+### Editor de Configuração (Settings Panel)
+
+Na aba “Visão Geral & Comportamento”, há um seletor “Scroll Horizontal” com as opções `Auto`, `Wrap` e `Host` (none). As alterações podem ser aplicadas (Aplicar) ou salvas (Salvar & Fechar). O valor é persistido junto com outras preferências da tabela.
+
+### Notas
+
+- O caminho virtual (CDK Virtual Scroll) permanece sendo o owner da rolagem vertical; o viewport horizontal é um contêiner externo que não interfere no scroll vertical.
+- Cabeçalho sticky continua funcional. Teste combinações com colunas sticky/virt para seu caso.
+- Para grids alternativos (ex.: Kendo), as mesmas regras de `max-content`/`min-width: 100%` se aplicam ao elemento de tabela interno.
+
 ## Virtualização (CDK)
 
 Quando `behavior.virtualization.enabled` estiver ativo, as linhas da tabela são renderizadas com `cdk-virtual-scroll-viewport` (cabeçalho permanece igual).
@@ -1064,6 +1286,51 @@ Notas rápidas (Flow ETag no Filter):
 - 200: atualiza `serverHash/lastVerifiedAt`; marca `outdated=true` apenas quando em customização; não aplica o schema automaticamente.
 - O corpo do schema é baixado apenas quando necessário para renderização (ex.: `alwaysVisibleFields` ou ao abrir o painel Avançado).
 
+## Formatação de Colunas (format)
+
+Cada coluna pode declarar `type` e uma string de formatação `format` consumida pelo `DataFormattingService`. Os tipos suportados são: `string`, `number`, `currency`, `percentage`, `date`, `boolean`, `custom`.
+
+Regra geral: a formatação só é aplicada quando há `format` não vazio e `type !== 'custom'`.
+
+Tipos e padrões de `format`:
+- number (DecimalPipe)
+  - Padrões: `minInt.minFrac-maxFrac`
+  - Exemplos: `1.0-0`, `1.2-2`, `1.0-3|nosep` (remove separador de milhar)
+- currency (CurrencyPipe)
+  - Sintaxe: `CURRENCY|DISPLAY|DECIMALS[|nosep]`
+  - Exemplos: `BRL|symbol|2`, `USD|code|0`, `EUR|symbol|2|nosep`
+- percentage (PercentPipe/DecimalPipe)
+  - Sem multiplicador: `1.0-0` (PercentPipe)
+  - Multiplicar por 100: `1.1-1|x100` (DecimalPipe×100 + `%`)
+- date (DatePipe)
+  - Tokens Angular: `shortDate`, `mediumDate`, `longDate`, `fullDate`, `short`, `shortTime`
+  - Padrões customizados: `dd/MM/yyyy`, `yyyy-MM-dd`, `dd/MM/yyyy HH:mm`
+- string (transformações + truncamento)
+  - Transform: `uppercase` | `lowercase` | `titlecase` | `capitalize` | `none`
+  - Transform + truncar: `<transform>|truncate|<max>|<suffix>`
+  - Exemplos: `uppercase|truncate|50|...`, `titlecase`
+- boolean (pré-definidos ou custom)
+  - Presets: `true-false` | `yes-no` | `active-inactive` | `on-off` | `enabled-disabled`
+  - Custom: `custom|Verdadeiro|Falso`
+
+Exemplos de ColumnDefinition:
+```ts
+{ field: 'salario', type: 'currency', format: 'BRL|symbol|2', header: 'Salário' }
+{ field: 'desconto', type: 'percentage', format: '1.1-1|x100', header: 'Desconto' }
+{ field: 'criadoEm', type: 'date', format: 'dd/MM/yyyy', header: 'Criado em' }
+{ field: 'nome', type: 'string', format: 'titlecase|truncate|32|…', header: 'Nome' }
+{ field: 'ativo', type: 'boolean', format: 'yes-no', header: 'Ativo' }
+```
+
+Observações:
+- `|nosep` remove separadores de milhar da saída formatada.
+- Para datas inválidas ou valores não numéricos, o serviço retorna o valor original (com aviso no console).
+- Colunas com renderizador `custom` não passam por formatação automática.
+
+Exemplos práticos no workspace (rotas):
+- Regras Visuais (Simples): `/table-rules-simple`
+- Regras Visuais (Complexas): `/table-rules-complex`
+
 ## 📊 Roadmap
 
 ### Próximas Versões