@sapphire-caitlyn/schema-kit-ng 0.0.4 → 0.0.6

package/docs/inputs/input-text-area/README.md

@@ -0,0 +1,27 @@
+# input-text-area
+
+Campo de texto com várias linhas (`<textarea>`).
+
+## Uso
+
+```ts
+import { InputTextAreaComponent } from '@schema-kit';
+```
+
+```html
+<input-text-area label="Observações" placeholder="Digite um texto" [formField]="form.observacoes" />
+```
+
+## Inputs
+
+Só os comuns (`label`, `placeholder`, `loading`, `tooltipInfo`): [input-base](../input-base/README.md).
+
+**Valor:** `string | null`
+
+## Slots
+
+- `[slot=input]`: dentro do wrapper `relative` do campo.
+
+## Atenção
+
+- O input `type` existe, mas não tem efeito no `<textarea>`.

package/docs/schema-table/README.md

@@ -0,0 +1,444 @@
+# schema-table
+
+Tela de listagem pronta a partir de um `SchemaService`: busca, um filtro por campo, ordenação, paginação e as ações de
+criar, editar e excluir. As colunas, os filtros e a formatação de cada célula saem do schema do service.
+
+Feita para trabalhar junto com o [schema-view](../schema-view/README.md) (a tela de criar/editar).
+
+## Uso
+
+```ts
+import { SchemaTableComponent, SchemaTableActionsDirective, SchemaTableReplacementForDirective, SchemaTableToolbarDirective } from '@schema-kit';
+```
+
+### 1. O service
+
+A tabela não recebe dados: recebe um `SchemaService`, que sabe o endpoint, o título e o schema dos campos. Os exemplos
+deste README usam este service:
+
+```ts
+import { inject, Injectable } from '@angular/core';
+import { required } from '@angular/forms/signals';
+import { FieldType, IView, SchemaService } from '@schema-kit';
+
+export interface IProduto extends IView {
+  nome: string;
+  preco: number;
+  estoque: number;
+  ativo: boolean;
+  unidade: 'UN' | 'KG' | 'CX';
+  uuidCategoria: string | null;
+  descricao: string | null;
+}
+
+@Injectable({ providedIn: 'root' })
+export class ProdutoService extends SchemaService<IProduto> {
+  constructor() {
+    // `this` não existe antes do super(): injete as dependências em variáveis locais
+    const categoriaService = inject(CategoriaService);
+
+    super({
+      endpoint: '/produtos',
+      title: 'Produtos',
+      bindLabel: 'nome', // texto do registro (confirmação de exclusão, selects de outros services)
+      bindValue: 'uuid', // valor do registro (selects de outros services)
+      schema: {
+        uuid:          { type: FieldType.UUID,     label: 'UUID',      hidden: true },
+        nome:          { type: FieldType.String,   label: 'Nome',      validators: required },
+        preco:         { type: FieldType.Currency, label: 'Preço' },
+        estoque:       { type: FieldType.Number,   label: 'Estoque' },
+        ativo:         { type: FieldType.Bool,     label: 'Ativo',     defaultValue: true },
+        uuidCategoria: {
+          type: FieldType.Select,
+          label: 'Categoria',
+          options: { service: () => categoriaService },
+        },
+        unidade: {
+          type: FieldType.Select,
+          label: 'Unidade',
+          options: {
+            lstOptions: [
+              { id: 'UN', nome: 'Unidade' },
+              { id: 'KG', nome: 'Quilo' },
+              { id: 'CX', nome: 'Caixa' },
+            ],
+            bindValue: 'id',
+            bindLabel: 'nome',
+          },
+        },
+        descricao: { type: FieldType.TextArea, label: 'Descrição', hidden: { hiddenList: true } },
+      },
+    });
+  }
+}
+```
+
+Opções do service usadas pela tabela:
+
+```ts
+interface SchemaServiceOptions<T> {
+  endpoint: string;                       // base das requisições: `${apiUrl}${endpoint}`
+  title: string;                          // breadcrumb da listagem
+  schema: SchemaFieldOptionsRecord<T>;    // campos (colunas, filtros e o form do schema-view)
+  listSchema?: SchemaFieldOptionsRecord<T>; // se informado, define as colunas no lugar de `schema`
+  breadcrumbs?: IBreadcrumbItem[];        // substitui o breadcrumb padrão ([{ label: title }])
+  bindValue: keyof T | ((value: T) => T[keyof T]);
+  bindLabel: keyof T | ((value: T) => string | T[keyof T]);
+}
+```
+
+### 2. As rotas
+
+A tabela navega relativo à rota em que está: **Novo** vai para `./view` e a edição para `./view/:uuid`. Monte as rotas
+assim (é a mesma estrutura que o schema-view espera):
+
+```ts
+const routes: Routes = [
+  { path: '', component: ProdutoListComponent },
+  { path: 'view', component: ProdutoViewComponent },       // criar
+  { path: 'view/:uuid', component: ProdutoViewComponent }, // editar
+];
+```
+
+### 3. O componente
+
+```ts
+@Component({
+  selector: 'produto-list',
+  imports: [SchemaTableComponent],
+  template: `<schema-table [schemaService]="produtoService" />`,
+})
+export class ProdutoListComponent {
+  protected produtoService = inject(ProdutoService);
+}
+```
+
+Só com isso a tela tem: breadcrumb, campo de busca, um botão de filtro por campo, botões **Novo**, **Resetar filtros** e
+**Atualizar**, cabeçalhos ordenáveis, coluna **Ações** (editar e excluir) e paginação.
+
+## Inputs
+
+| Input             | Tipo                   | Padrão      | Descrição                                                                    |
+| ----------------- | ---------------------- | ----------- | ---------------------------------------------------------------------------- |
+| `schemaService`   | `SchemaService<T, IP>` | obrigatório | Fonte dos dados e do schema                                                  |
+| `lstPresetFilters`| `IIndexFilter<T, any>[]` | `[]`      | Filtros fixos, enviados sempre junto com os do usuário. Não aparecem na barra |
+| `noQuery`         | `boolean`              | `false`     | Esconde o campo de busca                                                     |
+| `noNew`           | `boolean`              | `false`     | Esconde o botão Novo                                                         |
+| `editPermissao`   | `string \| null`       | `null`      | Permissão para editar. `null`: sempre permitido. Ver [Permissões](#permissões) |
+| `deletePermissao` | `string \| null`       | `null`      | Permissão para excluir. `null`: sempre permitido                             |
+
+Two-way binding (`model`), para controlar ou ler o estado de fora:
+
+| Model   | Tipo                    | Padrão                            | Descrição                    |
+| ------- | ----------------------- | --------------------------------- | ---------------------------- |
+| `page`  | `number`                | `1`                               | Página atual                 |
+| `limit` | `number`                | `paginationOptions.rows` (20)     | Itens por página             |
+| `sort`  | `IIndexParamsSort<T>[]` | `[]`                              | Ordenação (várias colunas)   |
+
+```html
+<schema-table [schemaService]="produtoService" [(page)]="pagina" [(sort)]="ordenacao" />
+```
+
+## Outputs
+
+| Output | Tipo    | Descrição                                                                           |
+| ------ | ------- | ----------------------------------------------------------------------------------- |
+| `novo` | `Event` | Clique em Novo, antes de navegar. `event.preventDefault()` cancela a navegação      |
+
+Abrir um dialog no lugar da tela de criação:
+
+```html
+<schema-table [schemaService]="produtoService" (novo)="$event.preventDefault(); abrirDialogNovo()" />
+```
+
+## Métodos
+
+| Método      | Descrição                                                                    |
+| ----------- | ---------------------------------------------------------------------------- |
+| `refresh()` | Recarrega a página atual com os mesmos filtros                               |
+| `reset()`   | Volta à página 1, limite padrão, sem ordenação, sem filtros e sem busca      |
+
+```ts
+export class ProdutoListComponent {
+  private table = viewChild.required(SchemaTableComponent);
+
+  async importarPlanilha(arquivo: File) {
+    await this.importacaoService.enviar(arquivo);
+    this.table().refresh();
+  }
+}
+```
+
+## Templates
+
+Passados como `<ng-template>` dentro do `<schema-table>`. Importe a diretiva correspondente no componente que usa a
+tabela.
+
+Cliques no conteúdo de um template (e no texto das células padrão) não chegam à linha: botões, links e inputs funcionam
+sem `stopPropagation`. O resto da linha continua abrindo a edição.
+
+### Ações da linha: `schemaTableActions`
+
+Botões extras em cada linha. Contexto: `$implicit` = o item da linha.
+
+| Input      | Tipo               | Padrão  | Descrição                                                              |
+| ---------- | ------------------ | ------- | ---------------------------------------------------------------------- |
+| `position` | `'start' \| 'end'` | `'end'` | `start`: coluna própria antes das colunas. `end`: na coluna **Ações**, entre editar e excluir |
+
+```html
+<schema-table [schemaService]="produtoService">
+  <ng-template schemaTableActions let-produto>
+    <button hlmBtn size="icon-sm" variant="ghost" (click)="duplicar(produto)" hlmTooltip="Duplicar">
+      <ng-icon name="lucideCopy" />
+    </button>
+  </ng-template>
+
+  <ng-template schemaTableActions position="start" let-produto>
+    <input type="checkbox" (change)="alternarSelecao(produto)" />
+  </ng-template>
+</schema-table>
+```
+
+### Barra de ferramentas: `schemaTableToolbar`
+
+Conteúdo extra na barra do topo. Não tem contexto (`let-*` fica `undefined`).
+
+| Input      | Tipo               | Padrão  | Descrição                                                         |
+| ---------- | ------------------ | ------- | ----------------------------------------------------------------- |
+| `position` | `'start' \| 'end'` | `'end'` | `start`: depois dos filtros, antes de Novo. `end`: depois de Atualizar |
+
+```html
+<schema-table [schemaService]="produtoService">
+  <ng-template schemaTableToolbar position="start">
+    <button hlmBtn size="sm" variant="outline" (click)="exportarCsv()">Exportar</button>
+  </ng-template>
+</schema-table>
+```
+
+### Célula personalizada: `schemaTableReplacementFor`
+
+Substitui a célula de uma coluna. O valor da diretiva é o `index` do campo.
+
+Contexto (`ITemplateContext`):
+
+```ts
+interface ITemplateContext<T, V> {
+  $implicit: T;     // o item da linha
+  value: V;         // item[index]
+  index: keyof T;   // nome do campo
+  label: string;    // label do campo
+  loading: boolean; // true enquanto a célula salva (switch de Bool)
+  readonly: boolean; // `readonly` do campo no schema
+}
+```
+
+```html
+<schema-table [schemaService]="produtoService">
+  <ng-template schemaTableReplacementFor="estoque" let-value="value" let-produto>
+    <span [class.text-destructive]="value === 0">
+      {{ value === 0 ? 'Esgotado' : value + ' ' + produto.unidade }}
+    </span>
+  </ng-template>
+</schema-table>
+```
+
+## Colunas
+
+As colunas são os campos de `listSchema` (se existir) ou de `schema`, na ordem em que foram declarados. Campos com
+`hidden: true` ou `hidden: { hiddenList: true }` não viram coluna nem filtro.
+
+O `label` vira o cabeçalho e o `tooltipInfo` mostra um ícone (?) ao lado dele.
+
+### Formatação padrão por tipo
+
+| Tipo                                     | Célula                                                                     |
+| ---------------------------------------- | -------------------------------------------------------------------------- |
+| `String`, `UUID`, `TextArea`             | O texto. Vazio: `-`                                                        |
+| `Number`                                 | `1.234`                                                                    |
+| `Decimal`                                | `1.234,50`                                                                 |
+| `Currency`                               | `R$ 1.234,50`                                                              |
+| `Date` / `DateTime` / `Time`             | `dd/MM/yyyy` / `dd/MM/yyyy HH:mm:ss` / `HH:mm:ss`                          |
+| `DateSpan` / `DateTimeSpan` / `TimeSpan` | `início - fim`, no formato acima. Ponta aberta: `…`                        |
+| `Cpf`, `Cnpj`, `CpfCnpj`, `Phone`        | Com máscara                                                                |
+| `Mask`                                   | Com a `maskitoOptions` do campo                                            |
+| `Bool`                                   | Switch que **salva na hora** (ver [Bool editável](#bool-editável))         |
+| `Icon`                                   | O ícone                                                                    |
+| `JSON`                                   | Botão que abre um dialog com o JSON formatado e botão de copiar            |
+| `File`                                   | Preview e nome de cada arquivo (URL ou lista de URLs)                      |
+| `Select` com `service`                   | O `bindLabel` do registro relacionado (ver [Select com service](#select-com-service)) |
+| `Select` com `lstOptions`                | **O valor cru** (ex.: `KG`). Use um template para mostrar o label          |
+
+### Template no schema: `listOptions.template`
+
+Para formatar a coluna em todas as tabelas que usam o service, defina no próprio schema. Aceita:
+
+- uma função `(item) => string`;
+- um `TemplateRef` (recebe o mesmo contexto do `schemaTableReplacementFor`);
+- uma classe de componente (renderizada sem inputs: não recebe o item).
+
+```ts
+unidade: {
+  type: FieldType.Select,
+  label: 'Unidade',
+  options: { lstOptions: UNIDADES, bindValue: 'id', bindLabel: 'nome' },
+  listOptions: {
+    template: (produto: IProduto) => UNIDADES.find((u) => u.id === produto.unidade)?.nome ?? '-',
+  },
+},
+```
+
+### Prioridade
+
+1. `schemaTableReplacementFor` no template da tabela;
+2. `listOptions.template` do schema;
+3. formatação padrão do tipo.
+
+### Select com service
+
+Para colunas `Select` com `options.service`, a tabela busca os labels de uma vez para a página toda: um
+`POST ${endpoint do outro service}/index` com os valores da página em `lstUuids`. Se o registro não voltar, a célula
+mostra o valor cru.
+
+```jsonc
+// POST /categorias/index
+{ "lstUuids": ["3f2a…", "9b1c…"], "page": 1, "size": 2 }
+```
+
+### Bool editável
+
+A célula de um `Bool` é um switch. Ao clicar, a tabela envia `PATCH ${endpoint}/${uuid}` só com aquele campo, mostra um
+loading na célula e um toast. Em caso de erro, recarrega a página para desfazer.
+
+```jsonc
+// PATCH /produtos/3f2a…
+{ "ativo": false }
+```
+
+Com `readonly: true` no schema, o switch aparece desabilitado e não salva. Para mostrar texto no lugar do switch,
+substitua a célula:
+
+```html
+<ng-template schemaTableReplacementFor="ativo" let-value="value">
+  {{ value ? 'Sim' : 'Não' }}
+</ng-template>
+```
+
+## Busca, filtros e ordenação
+
+- **Busca:** o texto vai em `query` (com debounce de 400 ms). `noQuery` esconde o campo.
+- **Filtros:** um botão por coluna (campos de `listSchema` ou `schema` sem `hiddenList`). Cada um abre um popover com o
+  input do tipo do campo (debounce de 400 ms). O botão ganha um X para limpar quando há valor. Para filtrar por um campo
+  que não é coluna, use [filtros fixos](#filtros-fixos).
+- **Ordenação:** clicar no cabeçalho alterna `ASC` → `DESC` → sem ordenação. Dá para ordenar por várias colunas: a ordem
+  dos cliques é a ordem enviada.
+- **Resetar filtros** chama `reset()`: limpa busca, filtros, ordenação e volta à página 1.
+
+### Filtro por tipo
+
+| Tipo                                | Input do filtro         | `value` enviado                                  |
+| ----------------------------------- | ----------------------- | ------------------------------------------------ |
+| `String`, `TextArea`                | Texto                   | `string`                                         |
+| `UUID`                              | Texto                   | `string`. Só aplica quando é um UUID válido      |
+| `Mask`                              | Texto com a máscara     | O retorno do `unmaskHandler` (sem ele, o texto mascarado) |
+| `Phone`, `Cpf`, `Cnpj`, `CpfCnpj`   | Input com máscara       | Sem máscara (ex.: `12345678901`)                 |
+| `Number`, `Decimal`, `Currency`     | Mínimo e máximo         | `[min, max]`. Uma ponta pode ser `null`          |
+| `Date`                              | Intervalo de datas      | `[início, fim]` em ISO                           |
+| `DateTime`                          | Intervalo de data/hora  | `[início, fim]` em ISO                           |
+| `Time`                              | Intervalo de horas      | `[início, fim]` em `HH:mm:ss`                    |
+| `Bool`                              | Sim / Não               | `true` / `false`                                 |
+| `Select`                            | O mesmo select do campo | O `bindValue` do item escolhido                  |
+| `Icon`                              | Seletor de ícone        | Nome do ícone                                    |
+| `JSON`, `File`, `*Span`             | Nenhum                  | O botão aparece, mas o popover fica vazio        |
+
+### Filtros fixos
+
+Para restringir a listagem sem o usuário poder mudar (ex.: produtos de uma categoria vinda da rota):
+
+```ts
+export class ProdutosDaCategoriaComponent {
+  uuidCategoria = input.required<string>(); // parâmetro da rota, com withComponentInputBinding()
+
+  protected filtrosFixos = computed<IIndexFilter<IProduto, unknown>[]>(() => [
+    { index: 'uuidCategoria', value: this.uuidCategoria() },
+  ]);
+}
+```
+
+```html
+<schema-table [schemaService]="produtoService" [lstPresetFilters]="filtrosFixos()" />
+```
+
+Filtros fixos com valor vazio (`null`, `''`, `[]`) são ignorados. Eles vão no mesmo `lstFilter` que os do usuário: se o
+usuário filtrar o mesmo campo, os dois são enviados.
+
+## Permissões
+
+`editPermissao` e `deletePermissao` recebem o nome de uma permissão, verificada pela função configurada no
+`SchemaKitModule.forRoot`:
+
+```ts
+SchemaKitModule.forRoot({
+  apiUrlGetter: (env) => env.apiUrl,
+  perfilCheckerFactory: () => {
+    const auth = inject(AuthService); // roda em contexto de injeção
+    return (permissao) => auth.temPermissao(permissao);
+  },
+});
+```
+
+```html
+<schema-table
+  [schemaService]="produtoService"
+  [editPermissao]="'produto.editar'"
+  [deletePermissao]="'produto.excluir'"
+/>
+```
+
+| Permissão de edição | Efeito                                                                 |
+| ------------------- | ---------------------------------------------------------------------- |
+| permitida           | Clique na linha e botão → abrem `./view/:uuid`                         |
+| negada              | Sem botão de editar e a linha não é clicável                           |
+
+| Permissão de exclusão | Efeito                                                                              |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| permitida             | Botão de lixeira: confirma com `Deseja realmente excluir "<bindLabel>"?`, envia `DELETE ${endpoint}/${uuid}` e recarrega |
+| negada                | Sem botão de excluir                                                                |
+
+Não há input para desligar editar/excluir: para uma tabela só de leitura, passe uma permissão que o checker nega. Sem
+`perfilCheckerFactory`, toda permissão informada é negada.
+
+## Contrato com a API
+
+A listagem chama `GET ${apiUrl}${endpoint}/index`. Strings vão como estão; os demais valores vão em JSON. Parâmetros
+`null`, `undefined` e listas vazias não são enviados.
+
+```text
+GET /produtos/index
+  ?page=2
+  &size=20
+  &query=caneta
+  &sort=[{"field":"preco","order":"DESC"},{"field":"nome","order":"ASC"}]
+  &lstFilter=[{"index":"ativo","value":true},{"index":"preco","value":[10,null]}]
+```
+
+A resposta precisa seguir `IPaginatedResult` (a tabela usa `data` e `total`):
+
+```ts
+interface IPaginatedResult<T> {
+  data: T[];
+  total: number; // total de registros com os filtros, para a paginação
+  page: number;
+  size: number;
+}
+```
+
+Cada item precisa ter `uuid` (`T extends IView`): é a chave da linha e o parâmetro da edição/exclusão.
+
+## Celular
+
+Em telas em retrato (`portrait`), as linhas viram cards com `label: valor` de cada coluna. As ações `start` ficam no
+topo do card e as `end` (com excluir) no rodapé. O botão de editar não aparece: o card inteiro abre a edição.
+
+## Atenção
+
+- Mudar filtros, busca ou ordenação não volta para a página 1: em uma página alta, o resultado pode ficar vazio.