@seniorsistemas/angular-components 19.3.3 → 19.3.4

package/infinite-scroll/README.md

@@ -0,0 +1,130 @@
+# InfiniteScroll
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Diretiva de scroll infinito que detecta quando o usuário chega ao final de um elemento com scroll e emite o evento `scrolled`. Deve ser aplicada a um elemento com `overflow` e scroll habilitado.
+
+## Quando usar
+
+- Listas longas carregadas de API com paginação progressiva
+- Feeds de conteúdo (notícias, posts, cards) com carregamento sob demanda
+- Tabelas ou listas com muitos registros onde a paginação clássica é indesejada
+
+## Quando não usar
+
+- Listas curtas onde todos os itens podem ser carregados de uma vez — carregue tudo e exiba diretamente
+- Quando o usuário precisa navegar para uma página específica — prefira paginação com controles numéricos
+
+## Instalação
+
+```typescript
+import { InfiniteScrollModule } from '@seniorsistemas/angular-components/infinite-scroll';
+
+@NgModule({
+    imports: [InfiniteScrollModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<div
+    sInfiniteScroll
+    (scrolled)="carregarMais()"
+    style="overflow-y: auto; height: 400px;"
+>
+    <!-- itens da lista -->
+</div>
+```
+
+## API
+
+### Inputs
+
+Esta diretiva não possui inputs configuráveis.
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `scrolled` | `EventEmitter<number>` | Emitido quando o usuário atinge o final do elemento com scroll. |
+
+## Exemplos
+
+### Lista com carregamento progressivo
+
+```html
+<div
+    sInfiniteScroll
+    (scrolled)="carregarMais()"
+    style="height: 300px; overflow-y: auto;"
+>
+    @for (item of itens; track item.id) {
+        <div>{{ item.nome }}</div>
+    }
+    @if (carregando) {
+        <div>Carregando...</div>
+    }
+</div>
+```
+
+```typescript
+carregarMais() {
+    if (this.carregando) return;
+    this.carregando = true;
+    this.api.buscarItens(this.pagina++).subscribe(novosItens => {
+        this.itens = [...this.itens, ...novosItens];
+        this.carregando = false;
+    });
+}
+```
+
+### Com indicador de fim de lista
+
+```html
+<div sInfiniteScroll (scrolled)="carregarMais()" style="height: 300px; overflow-y: auto;">
+    @for (item of itens; track item) {
+        <div>{{ item }}</div>
+    }
+    @if (carregando) {
+        <div>Carregando...</div>
+    }
+    @if (!temMais && !carregando) {
+        <div>Todos os registros foram carregados.</div>
+    }
+</div>
+```
+
+### Com debounce no callback (recomendado para APIs)
+
+```typescript
+import { Subject } from 'rxjs';
+import { debounceTime } from 'rxjs/operators';
+
+private scroll$ = new Subject<void>();
+
+ngOnInit() {
+    this.scroll$.pipe(debounceTime(300)).subscribe(() => this.buscarProximaPagina());
+}
+
+onScrolled() {
+    this.scroll$.next();
+}
+```
+
+```html
+<div sInfiniteScroll (scrolled)="onScrolled()" style="height: 400px; overflow-y: auto;">
+    <!-- itens -->
+</div>
+```
+
+## Acessibilidade
+
+- O elemento hospedeiro deve ter altura definida e `overflow-y: auto` ou `overflow-y: scroll`
+- A diretiva não possui debounce interno — implemente no callback quando necessário para evitar múltiplas requisições simultâneas
+- O evento `scrolled` é disparado quando `scrollTop > scrollHeight - offsetHeight - 2`
+
+## Componentes relacionados
+
+- [`LoadingState`](../loading-state/README.md) — indicador de carregamento a ser exibido durante o scroll

package/info-sign/README.md

@@ -0,0 +1,111 @@
+# InfoSign
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Diretiva estrutural que exibe um ícone de informação (ⓘ) ao lado do elemento hospedeiro. Ao interagir com o ícone, um tooltip com a mensagem configurada é exibido temporariamente.
+
+## Quando usar
+
+- Labels de campos de formulário com regras de preenchimento específicas (CPF, CNPJ, CEP)
+- Títulos de seções que necessitam de explicação adicional
+- Qualquer elemento de texto que precise de contexto sem sobrecarregar o layout
+
+## Quando não usar
+
+- Quando a informação é crítica e deve estar sempre visível — use texto de ajuda abaixo do campo
+- Para ações com conteúdo rico (listas, links, templates) — prefira [`HelpPopover`](../help-popover/README.md)
+
+## Instalação
+
+```typescript
+import { InfoSignModule } from '@seniorsistemas/angular-components/info-sign';
+
+@NgModule({
+    imports: [InfoSignModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+Como diretiva estrutural, substitui o elemento hospedeiro por um wrapper com o ícone ⓘ ao lado:
+
+```html
+<label *sInfoSign="'Informe o CPF sem pontos e traços'">CPF</label>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Sintaxe no template | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|---------------------|------|--------|:-----------:|-----------|
+| `sInfoSign` | `*sInfoSign="'mensagem'"` | `string` | — | Sim | Mensagem exibida no tooltip. Aceita HTML. |
+| `sInfoSignDisplayTime` | `; displayTime: 5000` | `number` | `5000` | Não | Tempo em ms que o tooltip permanece visível após ser exibido. |
+| `sInfoSignFocusedInputRef` | `; focusedInputRef: ref` | `HTMLInputElement \| HTMLElement \| null` | `null` | Não | Referência a um input. O tooltip aparece ao focar o input quando fornecido. |
+| `sInfoSignUseFocusedInputRef` | `; useFocusedInputRef: true` | `boolean` | `true` | Não | Quando `true`, usa `focusedInputRef` para calcular o posicionamento do ícone. |
+
+## Exemplos
+
+### Em um label de formulário
+
+```html
+<div style="display: flex; flex-direction: column; gap: 4px;">
+    <label *sInfoSign="'Informe o CPF sem pontos e traços. Apenas números.'">
+        CPF
+    </label>
+    <input type="text" placeholder="000.000.000-00" />
+</div>
+```
+
+### Com tempo de exibição customizado
+
+```html
+<span *sInfoSign="'Esta mensagem some em 2 segundos.'; displayTime: 2000">
+    Passe o mouse no ícone
+</span>
+```
+
+### Com conteúdo HTML no tooltip
+
+```html
+<label *sInfoSign="'<strong>Requisitos:</strong><br>• Mínimo 8 caracteres<br>• Letras e números'; displayTime: 8000">
+    Senha
+</label>
+```
+
+### Com referência a um input (tooltip ao focar)
+
+```html
+<label *sInfoSign="'Dica do campo'; focusedInputRef: meuInput">
+    Campo com foco
+</label>
+<input #meuInput type="text" />
+```
+
+### Em múltiplos campos de formulário
+
+```html
+<div style="display: flex; flex-direction: column; gap: 16px;">
+    <div>
+        <label *sInfoSign="'Informe o CPF sem pontos e traços.'">CPF</label>
+        <input type="text" placeholder="000.000.000-00" />
+    </div>
+    <div>
+        <label *sInfoSign="'Data no formato DD/MM/AAAA.'">Data de nascimento</label>
+        <input type="text" placeholder="DD/MM/AAAA" />
+    </div>
+</div>
+```
+
+## Acessibilidade
+
+- É uma diretiva estrutural — o elemento hospedeiro é envolvido por um wrapper com o ícone ao lado
+- O tooltip aparece ao passar o mouse sobre o ícone (padrão) ou ao focar o input referenciado
+- O tooltip some automaticamente após `displayTime` ms (padrão: 5000ms)
+- Aceita HTML no conteúdo do tooltip para mensagens formatadas
+
+## Componentes relacionados
+
+- [`HelpPopover`](../help-popover/README.md) — popover de ajuda com mais opções de conteúdo (header, footer, template)
+- [`Tooltip`](../tooltip/README.md) — tooltip standalone aplicado diretamente em qualquer elemento

package/inline-edit/README.md

@@ -0,0 +1,139 @@
+# InlineEdit
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de edição inline que renderiza dinamicamente campos editáveis a partir de uma lista de configurações. Cada campo exibe o valor atual e permite edição ao clicar, integrando-se a um `FormGroup` Angular.
+
+## Quando usar
+
+- Formulários de detalhes onde o usuário edita campos individualmente sem abrir modal
+- Telas de visualização com edição rápida diretamente no contexto
+- Painéis de configuração onde poucos campos precisam ser editados por vez
+
+## Quando não usar
+
+- Formulários completos com muitos campos obrigatórios simultâneos — use um formulário convencional
+- Quando todos os campos são editados ao mesmo tempo — prefira Dynamic Form
+
+## Instalação
+
+```typescript
+import { InlineEditModule } from '@seniorsistemas/angular-components/inline-edit';
+
+@NgModule({
+    imports: [InlineEditModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-inline-edit [formGroup]="form" [fields]="campos" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `formGroup` | `FormGroup` | `new FormGroup({})` | Não | `FormGroup` Angular ao qual os campos inline serão vinculados. |
+| `fields` | `InlineEditField[]` | `[]` | Não | Lista de configurações dos campos inline a serem renderizados. |
+| `errorMessages` | `any` | `undefined` | Não | Mapa de mensagens de erro customizadas por nome de validador. |
+
+### Tipos
+
+```typescript
+// Classe base — todos os tipos de campo estendem InlineEditField
+abstract class InlineEditField {
+    label: string;        // Rótulo exibido ao lado do campo
+    name: string;         // Nome do FormControl correspondente no FormGroup
+    tooltip?: string;     // Tooltip exibido ao passar o mouse sobre o rótulo
+    errorMessages?: {} | (() => {});  // Mensagens de erro customizadas
+}
+
+// Tipos de campo disponíveis:
+class InlineEditTextField extends InlineEditField {}         // Campo de texto simples
+class InlineEditNumberField extends InlineEditField {}       // Campo numérico
+class InlineEditTextAreaField extends InlineEditField {}     // Área de texto multilinha
+class InlineEditCalendarField extends InlineEditField {}     // Seletor de data
+class InlineEditLookupField extends InlineEditField {}       // Campo de busca avançada
+class InlineEditContentGeneratorField extends InlineEditField {} // Gerador de conteúdo com IA
+```
+
+## Exemplos
+
+### Campos de texto, número e área de texto
+
+```typescript
+import {
+    InlineEditTextField,
+    InlineEditNumberField,
+    InlineEditTextAreaField,
+} from '@seniorsistemas/angular-components/inline-edit';
+
+@Component({ ... })
+export class MeuComponent implements OnInit {
+    form!: FormGroup;
+    campos: InlineEditField[] = [];
+
+    ngOnInit() {
+        this.form = new FormGroup({
+            nome: new FormControl('João Silva'),
+            valor: new FormControl(1500),
+            observacao: new FormControl('Observação inicial'),
+        });
+
+        this.campos = [
+            new InlineEditTextField({ name: 'nome', label: 'Nome', tooltip: 'Nome completo' }),
+            new InlineEditNumberField({ name: 'valor', label: 'Valor', tooltip: 'Valor numérico' }),
+            new InlineEditTextAreaField({ name: 'observacao', label: 'Observação' }),
+        ];
+    }
+}
+```
+
+```html
+<s-inline-edit [formGroup]="form" [fields]="campos"></s-inline-edit>
+```
+
+### Com campo de data
+
+```typescript
+import { InlineEditCalendarField } from '@seniorsistemas/angular-components/inline-edit';
+
+this.form = new FormGroup({
+    dataAdmissao: new FormControl(new Date()),
+});
+
+this.campos = [
+    new InlineEditCalendarField({ name: 'dataAdmissao', label: 'Data de admissão' }),
+];
+```
+
+### Com mensagens de erro customizadas
+
+```typescript
+this.campos = [
+    new InlineEditTextField({
+        name: 'email',
+        label: 'E-mail',
+        errorMessages: {
+            required: 'O e-mail é obrigatório.',
+            email: 'Informe um e-mail válido.',
+        },
+    }),
+];
+```
+
+## Acessibilidade
+
+- Cada campo exibe seu rótulo (`label`) visualmente associado ao controle
+- O `tooltip` opcional fornece contexto adicional ao passar o mouse
+- A edição é ativada por clique e confirmada com Enter ou clique fora do campo
+- Mensagens de validação são exibidas abaixo do campo em caso de erro
+
+## Componentes relacionados
+
+- [`DynamicForm`](../dynamic-form/README.md) — formulário dinâmico completo com todos os campos habilitados simultaneamente

package/insights/README.md

@@ -0,0 +1,159 @@
+# Insights
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de painel lateral de insights com IA. Exibe uma lista de itens de insights em um sidebar, com carregamento assíncrono via `Observable`, feedback de like/dislike, cópia e recarregamento. Suporta templates customizáveis para introdução, estado vazio e sem permissão.
+
+> **Nota:** O seletor `s-ia-insight` e o pacote `ia-insight` estão descontinuados. Use `s-insights` e o pacote `insights` em novos projetos. O seletor antigo será removido na versão 20.0.0.
+
+## Quando usar
+
+- Dashboards que precisam exibir análises geradas por IA em um painel lateral
+- Telas de gestão de RH, financeiro ou operacional com insights contextuais
+- Qualquer interface que precise de análises assíncronas com feedback do usuário
+
+## Quando não usar
+
+- Quando os insights são estáticos e não precisam de carregamento assíncrono — use cards simples
+- Quando não há controle de permissão ou o conteúdo é sempre acessível — simplifique o componente
+
+## Instalação
+
+```typescript
+import { InsightsModule } from '@seniorsistemas/angular-components/insights';
+
+@NgModule({
+    imports: [InsightsModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-insights
+    #insightsRef
+    [insights]="listaInsights"
+    (openInsights)="onAbrir()"
+    (closedInsights)="onFechar()"
+></s-insights>
+
+<s-button label="Abrir Insights" (clicked)="insightsRef.open()"></s-button>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `insights` | `InsightsItem[]` | `[]` | Não | Lista de itens de insight a serem exibidos no painel. |
+| `hasPermission` | `boolean` | `true` | Não | Indica se o usuário tem permissão para ver os insights. Quando `false`, exibe o template de sem permissão. |
+| `introText` | `string` | `undefined` | Não | Texto de introdução exibido no topo do painel (quando sem template customizado). |
+| `emptyText` | `string` | `undefined` | Não | Texto exibido quando não há insights disponíveis. |
+| `noPermissionText` | `string` | `undefined` | Não | Texto exibido quando o usuário não tem permissão. |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `openInsights` | `OutputEmitterRef<void>` | Emitido quando o painel de insights é aberto. |
+| `closedInsights` | `OutputEmitterRef<void>` | Emitido quando o painel de insights é fechado. |
+
+### Tipos
+
+```typescript
+interface InsightsItem {
+    title: string;                          // Título do insight (obrigatório)
+    request$: Observable<string>;           // Observable que retorna o texto do insight (obrigatório)
+    onLikeSelected?: VoidFunction;          // Callback ao clicar em "gostei"
+    onDislikeSelected?: VoidFunction;       // Callback ao clicar em "não gostei"
+    onCopy?: (content: string) => void;     // Callback ao copiar o conteúdo
+    onReload?: VoidFunction;                // Callback ao recarregar o insight
+    onOpenSidebar?: VoidFunction;           // Callback ao abrir o sidebar
+    onCloseSideBar?: VoidFunction;          // Callback ao fechar o sidebar
+    onContentLoaded?: VoidFunction;         // Callback quando o conteúdo é carregado
+}
+```
+
+## Exemplos
+
+### Insights com múltiplos itens
+
+```typescript
+import { timer } from 'rxjs';
+import { first, switchMap } from 'rxjs/operators';
+import { of } from 'rxjs';
+import { InsightsItem } from '@seniorsistemas/angular-components/insights';
+
+insights: InsightsItem[] = [
+    {
+        title: 'Turnover mensal',
+        request$: timer(1000).pipe(first(), switchMap(() =>
+            of('O índice de turnover foi de 4,2%, acima da média do setor (2,8%).')
+        )),
+        onLikeSelected: () => console.log('Gostei'),
+        onCopy: (content) => navigator.clipboard.writeText(content),
+    },
+];
+```
+
+```html
+<s-insights
+    #insightsRef
+    [insights]="insights"
+    [hasPermission]="true"
+    introText="Análises geradas por IA com base nos dados do sistema."
+    (openInsights)="onAbrir()"
+    (closedInsights)="onFechar()"
+></s-insights>
+
+<s-button label="Abrir Insights" priority="primary" (clicked)="insightsRef.open()"></s-button>
+```
+
+### Sem permissão
+
+```html
+<s-insights
+    #insightsRef
+    [insights]="insights"
+    [hasPermission]="false"
+    noPermissionText="Você não tem permissão para visualizar os insights."
+></s-insights>
+<s-button label="Abrir" (clicked)="insightsRef.open()"></s-button>
+```
+
+### Com template customizado de introdução
+
+```html
+<s-insights #insightsRef [insights]="insights" [hasPermission]="true">
+    <ng-template sTemplate="intro">
+        <div style="padding: 12px; background: #eff6ff; border-radius: 6px;">
+            <p style="font-weight: 600; color: #1d4ed8;">Análises com IA</p>
+            <p>Insights gerados automaticamente com base nos dados do último trimestre.</p>
+        </div>
+    </ng-template>
+</s-insights>
+<s-button label="Abrir" (clicked)="insightsRef.open()"></s-button>
+```
+
+### Templates customizáveis
+
+Use `sTemplate` para customizar seções do painel:
+
+| Valor | Descrição |
+|-------|-----------|
+| `sTemplate="intro"` | Conteúdo de introdução no topo do painel |
+| `sTemplate="empty"` | Exibido quando não há insights disponíveis |
+| `sTemplate="no-permission"` | Exibido quando `hasPermission` é `false` |
+
+## Acessibilidade
+
+- O painel é aberto/fechado via métodos `open()` e `close()` na referência do componente (`#ref`)
+- Enquanto o `Observable` não emite, exibe um estado de carregamento animado
+- As ações de like, dislike, cópia e recarregamento estão acessíveis por clique
+
+## Componentes relacionados
+
+- [`LoadingState`](../loading-state/README.md) — indicador de carregamento utilizado internamente
+- [`SlideInBar`](../slide-in-bar/README.md) — painel lateral genérico para outros casos de uso

package/interactive-content/README.md

@@ -0,0 +1,120 @@
+# InteractiveContent
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Diretiva de acessibilidade que torna qualquer elemento HTML interativo, adicionando suporte a eventos de foco e navegação por teclado (Enter e Espaço) além do clique padrão. Gerencia automaticamente o atributo `tabindex`.
+
+## Quando usar
+
+- Tornar elementos não-interativos (`div`, `span`, imagens) acessíveis via teclado
+- Implementar cards clicáveis, itens de lista selecionáveis ou grids interativos
+- Garantir conformidade com WCAG para elementos customizados que simulam botões ou links
+
+## Quando não usar
+
+- Elementos que já são naturalmente interativos (`button`, `a`, `input`) — use os elementos nativos
+- Quando apenas o clique de mouse é necessário e a acessibilidade via teclado não é requisito
+
+## Instalação
+
+```typescript
+import { InteractiveContentDirective } from '@seniorsistemas/angular-components/interactive-content';
+
+@Component({
+    standalone: true,
+    imports: [InteractiveContentDirective],
+})
+export class MeuComponent {}
+```
+
+## Uso básico
+
+```html
+<div (sInteractiveContent)="onAtivar($event)" [focusable]="true">
+    Conteúdo clicável e acessível via teclado
+</div>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `focusable` | `boolean` | `true` | Não | Habilita o foco via teclado adicionando `tabindex="0"` ao elemento. |
+| `disabled` | `boolean` | `false` | Não | Desabilita todos os eventos de interação do elemento. |
+| `stopPropagation` | `boolean` | `false` | Não | Quando `true`, chama `event.stopPropagation()` ao ativar o elemento. |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `sInteractiveContent` | `OutputEmitterRef<PointerEvent \| KeyboardEvent>` | Emitido quando o usuário clica ou pressiona Enter/Espaço no elemento. |
+
+## Exemplos
+
+### Card clicável e acessível
+
+```html
+<div
+    (sInteractiveContent)="onAtivar($event)"
+    [focusable]="true"
+    style="padding: 16px; border: 2px solid #e5e7eb; border-radius: 8px; cursor: pointer;"
+>
+    <p>Elemento interativo</p>
+    <p>Clique ou pressione Enter/Espaço</p>
+</div>
+```
+
+### Cards selecionáveis com destaque visual
+
+```html
+@for (card of cards; track card.id) {
+    <div
+        (sInteractiveContent)="cardSelecionado = card"
+        [focusable]="true"
+        [style.border-color]="cardSelecionado === card ? '#3b82f6' : '#e5e7eb'"
+        style="padding: 16px; border: 2px solid; border-radius: 8px; cursor: pointer;"
+    >
+        {{ card.titulo }}
+    </div>
+}
+```
+
+### Elemento desabilitado
+
+```html
+<div
+    (sInteractiveContent)="onAtivar($event)"
+    [disabled]="!temPermissao"
+    style="padding: 16px; cursor: not-allowed; opacity: 0.6;"
+>
+    Elemento desabilitado
+</div>
+```
+
+### Impedindo propagação de eventos
+
+```html
+<div (click)="onClickExterno()">
+    <div
+        (sInteractiveContent)="onAtivarInterno($event)"
+        [stopPropagation]="true"
+        style="padding: 8px; border: 1px solid #ccc;"
+    >
+        Clique interno (não propaga)
+    </div>
+</div>
+```
+
+## Acessibilidade
+
+- Adiciona `tabindex="0"` automaticamente ao elemento quando `focusable` é `true`
+- Emite o evento `sInteractiveContent` ao clicar ou pressionar Enter/Espaço
+- Com `disabled: true`, o `tabindex` é definido como `-1` e eventos são ignorados
+- Remove os event listeners automaticamente ao destruir o componente
+
+## Componentes relacionados
+
+- [`Button`](../button/README.md) — botão nativo com acessibilidade integrada; prefira quando a semântica de botão é adequada
+- [`MouseEvents`](../mouse-events/README.md) — diretivas para eventos de mouse avançados (long press, double click)