@seniorsistemas/angular-components 19.3.3 → 19.3.4

package/kanban/README.md

@@ -0,0 +1,184 @@
+# Kanban
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de quadro Kanban com suporte a arrastar e soltar colunas e itens. Permite seleção via checkboxes, templates customizáveis para cabeçalho, corpo e rodapé dos cards, e emite eventos de movimentação e seleção.
+
+## Quando usar
+
+- Gerenciamento de tarefas e projetos com workflows visuais (Scrum, Kanban)
+- Visualização e organização de itens distribuídos em estágios ou categorias
+- Interfaces onde o usuário precisa mover itens entre colunas por arrastar e soltar
+
+## Quando não usar
+
+- Listas simples sem necessidade de colunas múltiplas — use uma lista ou tabela
+- Quando os itens não podem ser movidos entre categorias — use abas ou filtros
+
+## Instalação
+
+```typescript
+import { KanbanModule } from '@seniorsistemas/angular-components/kanban';
+
+@NgModule({
+    imports: [KanbanModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-kanban [data]="dadosKanban" (itemsMoved)="onItemMovido($event)"></s-kanban>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `data` | `KanbanData` | — | Sim | Dados do quadro Kanban com colunas e itens. |
+| `showItemCheckboxes` | `boolean` | `true` | Não | Exibe checkboxes de seleção em cada item Kanban. |
+| `showColumnCheckboxes` | `boolean` | `true` | Não | Exibe checkboxes de seleção no cabeçalho de cada coluna. |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `itemsMoved` | `EventEmitter<KanbanItemMovedData>` | Emitido quando o usuário move um item entre colunas ou posições. |
+| `dataUpdated` | `EventEmitter<KanbanData>` | Emitido quando os dados do quadro são atualizados após movimentação. |
+| `itemsSelected` | `EventEmitter<KanbanItem[]>` | Emitido quando a seleção de itens muda, com a lista de itens selecionados. |
+
+### Tipos
+
+```typescript
+interface KanbanData {
+    columns: KanbanColumn[];
+}
+
+interface KanbanColumn {
+    id?: string;
+    title: string;
+    items: KanbanItem[];
+    options?: KanbanColumnOption[];  // Menu de opções no cabeçalho da coluna
+}
+
+interface KanbanItem {
+    data: any;                       // Dados do item (livre)
+    options?: KanbanItemOption[];    // Menu de opções no card
+    disabled?: boolean;              // Bloqueia movimentação e seleção
+    frozen?: boolean;                // Bloqueia movimentação mas permite seleção
+}
+
+interface KanbanItemMovedData {
+    items: KanbanItem[];             // Itens movidos (inclui selecionados)
+    previousColumn: KanbanColumn;   // Coluna de origem
+    targetColumn: KanbanColumn;     // Coluna de destino
+}
+
+interface KanbanColumnOption {
+    label: string;
+    iconClass?: string;
+    command: (column: KanbanColumn) => void;
+}
+
+interface KanbanItemOption {
+    label: string;
+    iconClass?: string;
+    command: (item: KanbanItem) => void;
+}
+```
+
+## Exemplos
+
+### Kanban básico com templates
+
+```typescript
+dadosKanban: KanbanData = {
+    columns: [
+        {
+            id: 'todo',
+            title: 'A Fazer',
+            items: [
+                { data: { id: 1, title: 'Implementar login', assignee: 'João' } },
+                { data: { id: 2, title: 'Configurar banco de dados', assignee: 'Maria' } },
+            ],
+        },
+        { id: 'doing', title: 'Em Progresso', items: [] },
+        { id: 'done', title: 'Concluído', items: [] },
+    ],
+};
+```
+
+```html
+<s-kanban [data]="dadosKanban" (itemsMoved)="onItemMovido($event)">
+    <ng-template sTemplate="item-header" let-item>
+        <h4>{{ item.data.title }}</h4>
+    </ng-template>
+    <ng-template sTemplate="item-body" let-item>
+        <p>{{ item.data.assignee }}</p>
+    </ng-template>
+    <ng-template sTemplate="item-footer" let-item>
+        <span>#{{ item.data.id }}</span>
+    </ng-template>
+</s-kanban>
+```
+
+### Com itens desabilitados e congelados
+
+```typescript
+dadosKanban: KanbanData = {
+    columns: [{
+        id: 'col1',
+        title: 'Coluna',
+        items: [
+            { data: { title: 'Normal' } },
+            { data: { title: 'Bloqueado' }, disabled: true },
+            { data: { title: 'Congelado' }, frozen: true },
+        ],
+    }],
+};
+```
+
+### Com menus de opções
+
+```typescript
+dadosKanban: KanbanData = {
+    columns: [{
+        id: 'backlog',
+        title: 'Backlog',
+        items: [{
+            data: { id: 1, title: 'Feature A' },
+            options: [
+                { label: 'Editar', iconClass: 'far fa-edit', command: (item) => this.editar(item) },
+                { label: 'Excluir', iconClass: 'far fa-trash', command: (item) => this.excluir(item) },
+            ],
+        }],
+        options: [
+            { label: 'Adicionar Tarefa', iconClass: 'far fa-plus', command: (col) => this.adicionar(col) },
+        ],
+    }],
+};
+```
+
+### Templates customizáveis
+
+| Valor do `sTemplate` | Descrição |
+|----------------------|-----------|
+| `item-header` | Cabeçalho do card |
+| `item-body` | Corpo do card |
+| `item-footer` | Rodapé do card |
+| `column-header` | Cabeçalho da coluna |
+| `column-empty-message` | Mensagem exibida quando a coluna está vazia |
+
+## Acessibilidade
+
+- Use Ctrl+Clique para selecionar múltiplos itens antes de arrastar
+- Itens com `disabled: true` não podem ser movidos ou selecionados
+- Itens com `frozen: true` não podem ser movidos mas podem ser selecionados
+- Os checkboxes de seleção de coluna selecionam todos os itens habilitados da coluna
+
+## Componentes relacionados
+
+- [`GridMenu`](../grid-menu/README.md) — menu em grade para navegação e seleção simples

package/label-value/README.md

@@ -0,0 +1,154 @@
+# LabelValue
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente para exibição de pares label/valor em modo somente leitura. Suporta cinco tipos de valor: texto simples, badge, moeda, número e data — cada um com formatação automática adequada ao locale da aplicação.
+
+## Quando usar
+
+- Painéis de visualização de detalhes de entidades (funcionário, produto, pedido)
+- Resumos de formulários antes da submissão
+- Seções de informações em cards ou modais onde os dados não são editáveis
+
+## Quando não usar
+
+- Campos editáveis — use um formulário convencional ou [`InlineEdit`](../inline-edit/README.md)
+- Métricas numéricas com ícone e destaque visual — prefira o componente StatsCard
+
+## Instalação
+
+```typescript
+import { LabelValueModule } from '@seniorsistemas/angular-components/label-value';
+
+@NgModule({
+    imports: [LabelValueModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-label-value [configuration]="{ type: 'Text', title: 'Nome', value: 'João Silva' }"></s-label-value>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `configuration` | `LabelValueConfiguration` | — | Sim | Configuração do par label/valor. O campo `type` determina como o valor é renderizado. |
+
+### Tipos
+
+```typescript
+type LabelValueConfiguration =
+    | TextConfiguration
+    | BadgeConfiguration
+    | CurrencyConfiguration
+    | NumberConfiguration
+    | DateConfiguration;
+
+// Texto simples
+type TextConfiguration = {
+    type: 'Text';
+    title: string;
+    value: string;
+};
+
+// Badge(s)
+type BadgeConfiguration = {
+    type: 'Badge';
+    title: string;
+    value: Partial<Pick<BadgeComponent, 'type' | 'color' | 'text' | 'iconClass' | 'iconPosition'>>[];
+};
+
+// Valor monetário formatado pelo locale
+type CurrencyConfiguration = {
+    type: 'Currency';
+    title: string;
+    value: string | number;
+    currency: string;  // Ex: 'BRL', 'USD', 'EUR'
+};
+
+// Valor numérico formatado pelo locale
+type NumberConfiguration = {
+    type: 'Number';
+    title: string;
+    value: string | number;
+};
+
+// Data formatada com moment.js
+type DateConfiguration = {
+    type: 'Date';
+    title: string;
+    value: string | Date;
+    format?: string;  // Formato moment.js, padrão: 'L'
+};
+```
+
+## Exemplos
+
+### Tipo Text
+
+```html
+<s-label-value [configuration]="{ type: 'Text', title: 'Nome completo', value: 'João Silva' }">
+</s-label-value>
+```
+
+### Tipo Badge com múltiplos badges
+
+```html
+<s-label-value [configuration]="{
+    type: 'Badge',
+    title: 'Permissões',
+    value: [
+        { text: 'Leitura', color: 'blue', iconClass: 'fa fa-eye' },
+        { text: 'Escrita', color: 'green', iconClass: 'fa fa-edit' },
+        { text: 'Admin', color: 'red', iconClass: 'fa fa-shield-alt' }
+    ]
+}"></s-label-value>
+```
+
+### Tipo Currency
+
+```html
+<s-label-value [configuration]="{ type: 'Currency', title: 'Salário', currency: 'BRL', value: 5750.99 }">
+</s-label-value>
+```
+
+### Tipo Date com formato customizado
+
+```html
+<s-label-value [configuration]="{
+    type: 'Date',
+    title: 'Última atualização',
+    value: '2024-11-01T18:21:16Z',
+    format: 'L HH:mm:ss'
+}"></s-label-value>
+```
+
+### Painel de detalhes com múltiplos campos
+
+```html
+<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 24px;">
+    <s-label-value [configuration]="{ type: 'Text', title: 'Nome', value: 'João Silva' }"></s-label-value>
+    <s-label-value [configuration]="{ type: 'Text', title: 'CPF', value: '123.456.789-00' }"></s-label-value>
+    <s-label-value [configuration]="{ type: 'Date', title: 'Admissão', value: '2020-03-01' }"></s-label-value>
+    <s-label-value [configuration]="{ type: 'Currency', title: 'Salário', currency: 'BRL', value: 5750 }"></s-label-value>
+    <s-label-value [configuration]="{ type: 'Badge', title: 'Status', value: [{ text: 'Ativo', color: 'green' }] }"></s-label-value>
+    <s-label-value [configuration]="{ type: 'Number', title: 'Dias trabalhados', value: 1250 }"></s-label-value>
+</div>
+```
+
+## Acessibilidade
+
+- Quando `value` é nulo ou string vazia, exibe a mensagem "Não informado" (internacionalizada via `TranslateModule`)
+- O `title` é sempre exibido em negrito como rótulo do campo
+- Requer `LocaleModule.forRoot()` e `TranslateModule.forRoot()` no módulo raiz para formatação de moeda, número e data
+
+## Componentes relacionados
+
+- [`Badge`](../badge/README.md) — componente de badge usado internamente no tipo Badge
+- [`InlineEdit`](../inline-edit/README.md) — quando os campos precisam ser editáveis inline

package/loading-state/README.md

@@ -0,0 +1,141 @@
+# LoadingState
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente para exibir indicadores de carregamento sobre conteúdo enquanto operações assíncronas estão em andamento. Permite bloquear componentes específicos ou a página inteira, com dois tipos de indicador visual. Também disponível como diretiva estrutural `*sLoadingState`.
+
+## Quando usar
+
+- Carregamento de dados em listas, tabelas ou painéis
+- Processamento de formulários após submissão
+- Operações assíncronas em containers específicos da tela
+- Carregamento inicial da aplicação (com `blockWindow: true` e indicador Logo)
+
+## Quando não usar
+
+- Operações muito rápidas (< 300ms) onde o flash do indicador seria indesejado — o componente já tem delay de 300ms embutido
+- Progresso mensurável — prefira [`Progressbar`](../progressbar/README.md) quando há percentual de conclusão
+
+## Instalação
+
+```typescript
+import { LoadingStateModule } from '@seniorsistemas/angular-components/loading-state';
+
+@NgModule({
+    imports: [LoadingStateModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+### Como componente
+
+```html
+<s-loading-state [loading]="carregando">
+    <div>Conteúdo que será bloqueado durante o carregamento</div>
+</s-loading-state>
+```
+
+### Como diretiva estrutural
+
+```html
+<div *sLoadingState="carregando">
+    Conteúdo que será bloqueado
+</div>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `loading` | `boolean` | — | Sim | Controla o estado de carregamento. Quando `true`, exibe o indicador após 300ms. Quando `false`, remove após 200ms. |
+| `indicator` | `LoadingStateIndicators` | `LoadingStateIndicators.Dots` | Não | Tipo de indicador visual: `dots` (pontos animados) ou `logo` (logotipo animado). |
+| `blockWindow` | `boolean` | `false` | Não | Quando `true`, bloqueia a janela inteira com overlay em vez de apenas o container. |
+| `id` | `string` | `s-loading-state-{auto}` | Não | Identificador único do componente no DOM. |
+
+### Tipos
+
+```typescript
+enum LoadingStateIndicators {
+    Dots = 'dots',  // Indicador de pontos animados (padrão)
+    Logo = 'logo',  // Indicador com logotipo animado
+}
+```
+
+### Diretiva `*sLoadingState`
+
+A diretiva aceita `boolean` ou objeto de configuração:
+
+```html
+<!-- Forma simples -->
+<div *sLoadingState="carregando">Conteúdo</div>
+
+<!-- Forma com configuração -->
+<div *sLoadingState="{ loading: carregando, indicator: 'logo' }">Conteúdo</div>
+```
+
+## Exemplos
+
+### Carregamento de uma seção específica
+
+```html
+<s-loading-state [loading]="carregandoDados" [indicator]="'dots'">
+    <div class="painel">
+        <h3>Dados do Funcionário</h3>
+        <div>{{ dados | json }}</div>
+    </div>
+</s-loading-state>
+```
+
+### Bloqueio da página inteira
+
+```html
+<s-loading-state [loading]="processando" [blockWindow]="true" [indicator]="'logo'">
+    <div class="pagina">
+        <!-- conteúdo da página -->
+    </div>
+</s-loading-state>
+```
+
+### Múltiplos loading states independentes
+
+```html
+<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px;">
+    <div *sLoadingState="carregandoSecao1">
+        <h4>Seção 1</h4>
+        <p>Conteúdo independente</p>
+    </div>
+    <div *sLoadingState="carregandoSecao2">
+        <h4>Seção 2</h4>
+        <p>Conteúdo independente</p>
+    </div>
+    <div *sLoadingState="carregandoSecao3">
+        <h4>Seção 3</h4>
+        <p>Conteúdo independente</p>
+    </div>
+</div>
+```
+
+### Com indicador Logo e configuração via diretiva
+
+```html
+<div *sLoadingState="{ loading: carregando, indicator: 'logo' }">
+    Conteúdo com indicador de logo customizado
+</div>
+```
+
+## Acessibilidade
+
+- O indicador tem delay de bloqueio de 300ms para evitar flash em operações rápidas
+- O delay de desbloqueio é de 200ms para transição suave ao remover o overlay
+- Use `blockWindow: true` com moderação — bloqueia toda interação do usuário com a página
+- O `id` gerado automaticamente é único por instância do componente
+
+## Componentes relacionados
+
+- [`EmptyState`](../empty-state/README.md) — exibir mensagem quando não há conteúdo após o carregamento
+- [`Progressbar`](../progressbar/README.md) — indicar progresso mensurável de operações com percentual
+- [`InfiniteScroll`](../infinite-scroll/README.md) — carregamento progressivo de listas com scroll

package/localized-number-input/README.md

@@ -0,0 +1,128 @@
+# LocalizedNumberInput
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Diretiva de validação para campos `<input>` que verifica se o valor digitado é um número localizado válido, considerando os separadores decimal e de milhar do locale ativo. Integra-se ao sistema de formulários Angular via `NG_VALIDATORS`, adicionando o erro `invalidNumber` quando o valor não é válido.
+
+## Quando usar
+
+- Campos de entrada numérica em formulários que precisam validar o formato localizado (ex: `1.234,56` em pt-BR)
+- Quando o usuário digita livremente e você precisa garantir que o valor é um número no formato correto antes de processar
+- Aplicações multi-locale onde os separadores podem variar
+
+## Quando não usar
+
+- Quando você precisa de formatação visual automática enquanto o usuário digita — prefira uma máscara numérica
+- Para campos de valores inteiros sem casas decimais — use validação nativa do Angular Forms (`Validators.pattern`)
+
+## Instalação
+
+```typescript
+import { LocalizedNumberInputModule } from '@seniorsistemas/angular-components/localized-number-input';
+
+@NgModule({
+    imports: [LocalizedNumberInputModule],
+})
+export class MeuModule {}
+```
+
+**Dependência:** Requer `LocaleModule.forRoot()` configurado no módulo raiz da aplicação.
+
+## Uso básico
+
+```html
+<input sLocalizedNumberInput [precision]="2" formControlName="valor" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `precision` | `number` | `2` | Não | Número máximo de casas decimais aceitas na validação. |
+| `decimalSeparator` | `string` | Locale ativo | Não | Separador decimal personalizado. Usa o do locale ativo se não informado. |
+| `thousandsSeparator` | `string` | Locale ativo | Não | Separador de milhar personalizado. Usa o do locale ativo se não informado. |
+
+### Erros de validação
+
+| Chave | Valor | Condição |
+|-------|-------|----------|
+| `invalidNumber` | `true` | O valor digitado não corresponde ao formato de número localizado esperado. |
+
+## Exemplos
+
+### Validação com locale pt-BR (padrão)
+
+```html
+<form [formGroup]="form">
+    <input
+        sLocalizedNumberInput
+        [precision]="2"
+        formControlName="valor"
+        placeholder="Ex: 1.234,56"
+    />
+    @if (form.get('valor')?.errors?.['invalidNumber'] && form.get('valor')?.dirty) {
+        <small style="color: red;">Número inválido para o locale atual (pt-BR)</small>
+    }
+</form>
+```
+
+### Validação com separadores customizados (en-US)
+
+```html
+<input
+    sLocalizedNumberInput
+    [precision]="2"
+    decimalSeparator="."
+    thousandsSeparator=","
+    formControlName="valorUsd"
+    placeholder="Ex: 1,234.56"
+/>
+```
+
+### Alta precisão decimal (4 casas)
+
+```html
+<input
+    sLocalizedNumberInput
+    [precision]="4"
+    formControlName="cotacao"
+    placeholder="Ex: 1.234,5678"
+/>
+```
+
+### Exibindo erro de validação
+
+```typescript
+@Component({ ... })
+export class MeuComponent {
+    form = new FormGroup({
+        valor: new FormControl(''),
+    });
+
+    get valorInvalido(): boolean {
+        const control = this.form.get('valor');
+        return !!(control?.errors?.['invalidNumber'] && control.dirty);
+    }
+}
+```
+
+```html
+<input sLocalizedNumberInput [precision]="2" formControlName="valor" />
+@if (valorInvalido) {
+    <small>Informe um número válido. Exemplo: 1.234,56</small>
+}
+```
+
+## Acessibilidade
+
+- A diretiva integra-se ao sistema de validação nativo do Angular Forms via `NG_VALIDATORS`
+- O erro `invalidNumber` é adicionado ao `FormControl` para uso com mensagens de validação padrão
+- Use `formControlName` ou `ngModel` para que a validação seja aplicada corretamente
+- Os separadores são obtidos automaticamente do `LocaleService` — não é necessário configurar manualmente para o locale padrão
+
+## Componentes relacionados
+
+- [`NumericMask`](../numeric-mask/README.md) — máscara de entrada com formatação visual automática enquanto o usuário digita
+- [`BigNumberInput`](../bignumber-input/README.md) — máscara para números de grande precisão