@seniorsistemas/angular-components 19.3.3 → 19.3.4

package/global-search/README.md

@@ -0,0 +1,151 @@
+# GlobalSearch
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de busca global com campo de input, dropdown de resultados animado, estado de carregamento, empty state e suporte a itens customizáveis via `s-global-search-dropdown-item`. Os resultados são projetados via `ng-content`.
+
+## Quando usar
+
+- Busca global na topbar da aplicação para pesquisar entidades (colaboradores, clientes, documentos)
+- Pesquisa com resultados em dropdown com link para busca avançada
+- Interfaces que precisam de busca rápida com feedback de carregamento e estado vazio
+
+## Quando não usar
+
+- Busca com seleção de valor vinculada a um `FormControl` — use [`Autocomplete`](../autocomplete/README.md)
+- Filtros de listagem local — use um campo de texto simples com pipe de filtro
+
+## Instalação
+
+```typescript
+import { GlobalSearchModule } from '@seniorsistemas/angular-components/global-search';
+
+@Component({ standalone: true, imports: [GlobalSearchModule] })
+export class MeuComponent {}
+```
+
+## Uso básico
+
+```html
+<s-global-search
+  totalItensLabel="resultados encontrados"
+  showMoreLabel="Ver busca avançada"
+  [totalElements]="total"
+  [isLoading]="carregando"
+  (searched)="onSearch($event)"
+  (moreShown)="onVerMais()"
+>
+  @for (item of resultados; track item.id) {
+    <s-global-search-dropdown-item
+      [primaryLabel]="item.nome"
+      [secondaryLabel]="item.cargo"
+    ></s-global-search-dropdown-item>
+  }
+</s-global-search>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `totalItensLabel` | `string` | — | Sim | Label que acompanha o total de resultados no rodapé |
+| `showMoreLabel` | `string` | — | Sim | Rótulo do link para exibir mais resultados |
+| `placeholder` | `string` | — | — | Placeholder do input de busca |
+| `delay` | `number` | `500` | — | Tempo de debounce em ms antes de emitir o evento de busca |
+| `isLoading` | `boolean` | `false` | — | Exibe indicador de carregamento no dropdown |
+| `totalElements` | `number` | — | — | Número total de resultados encontrados |
+| `emptyTitle` | `string` | — | — | Título do empty state quando não há resultados |
+| `emptyDescription` | `string` | — | — | Descrição do empty state exibida abaixo do título |
+| `emptyIcon` | `string` | — | — | Classe do ícone exibido no empty state |
+| `showFooter` | `boolean` | `true` | — | Exibe o rodapé com link "ver mais" e contagem de resultados |
+| `id` | `string` | `s-global-search-{n}` | — | Identificador único do componente |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `searched` | `EventEmitter<string>` | Emitido ao digitar no campo (com debounce), com o valor atual |
+| `focused` | `EventEmitter<boolean>` | Emitido quando o campo ganha (`true`) ou perde (`false`) foco |
+| `moreShown` | `EventEmitter<void>` | Emitido ao clicar no link para exibir mais resultados |
+
+## Exemplos
+
+### Busca com resultados dinâmicos
+
+```html
+<s-global-search
+  totalItensLabel="colaboradores encontrados"
+  showMoreLabel="Ver busca avançada"
+  [totalElements]="resultados.length"
+  [isLoading]="carregando"
+  placeholder="Buscar colaborador..."
+  emptyTitle="Nenhum resultado encontrado"
+  emptyDescription="Tente buscar por outro termo"
+  emptyIcon="fa fa-search"
+  (searched)="onSearch($event)"
+  (moreShown)="irParaBuscaAvancada()"
+>
+  @for (item of resultados; track item.id) {
+    <s-global-search-dropdown-item
+      [primaryLabel]="item.nome"
+      [secondaryLabel]="item.cargo"
+      [tertiaryLabel]="item.departamento"
+      iconClass="far fa-user"
+      size="standart"
+    ></s-global-search-dropdown-item>
+  }
+</s-global-search>
+```
+
+```typescript
+resultados: any[] = [];
+carregando = false;
+
+onSearch(query: string) {
+  if (!query) { this.resultados = []; return; }
+  this.carregando = true;
+  this.searchService.buscar(query).subscribe(data => {
+    this.resultados = data;
+    this.carregando = false;
+  });
+}
+```
+
+### Sem rodapé
+
+```html
+<s-global-search
+  totalItensLabel="itens"
+  showMoreLabel="Ver mais"
+  [showFooter]="false"
+  (searched)="onSearch($event)"
+>
+  <!-- itens -->
+</s-global-search>
+```
+
+### s-global-search-dropdown-item
+
+Campos do componente de item de resultado:
+
+| Propriedade | Tipo | Descrição |
+|-------------|------|-----------|
+| `primaryLabel` | `string` | Texto principal do item (obrigatório) |
+| `secondaryLabel` | `string` | Texto secundário |
+| `tertiaryLabel` | `string` | Texto terciário |
+| `iconClass` | `string` | Classe de ícone Font Awesome |
+| `imageSource` | `string` | URL de imagem (thumbnail) |
+| `size` | `'standart' \| 'medium' \| 'small'` | Tamanho do item |
+
+## Acessibilidade
+
+- O campo de busca possui suporte a `placeholder` e pode receber `aria-label` via configuração
+- O dropdown abre automaticamente ao digitar e fecha ao limpar o campo
+- Os itens do dropdown são elementos clicáveis com rótulo visível via `primaryLabel`
+
+## Componentes relacionados
+
+- [`Autocomplete`](../autocomplete/README.md) — busca com seleção de valor vinculada a formulário
+- [`Topbar`](../topbar/README.md) — barra superior onde o GlobalSearch é tipicamente posicionado

package/grid-menu/README.md

@@ -0,0 +1,123 @@
+# GridMenu
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de menu em grade que exibe uma coleção de itens como cards clicáveis. Suporta seleção de item ativo, ícones Font Awesome e itens desabilitados.
+
+## Quando usar
+
+- Menus de navegação rápida em dashboards ou launchers de módulos
+- Atalhos para ações frequentes dispostos em grade
+- Menus onde o usuário precisa indicar qual módulo ou contexto está ativo (modo selecionável)
+
+## Quando não usar
+
+- Menus com hierarquia (submenus) — prefira [`TieredMenu`](../tiered-menu/README.md)
+- Listas longas de itens com mais de uma coluna de informação — prefira uma tabela ou lista
+
+## Instalação
+
+```typescript
+import { GridMenuModule } from '@seniorsistemas/angular-components/grid-menu';
+
+@NgModule({
+    imports: [GridMenuModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-grid-menu [items]="menuItems" [useFontAwesomeIcons]="true" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `items` | `GridMenuItem \| GridMenuItem[]` | `[]` | Não | Lista de itens exibidos no grid. Valores nulos resultam em lista vazia. |
+| `useFontAwesomeIcons` | `boolean` | `false` | Não | Quando `true`, o campo `icon` é tratado como classe Font Awesome. Quando `false`, como URL de imagem SVG. |
+| `selectable` | `boolean` | `false` | Não | Habilita o modo de seleção. O item clicado fica marcado como ativo. |
+| `selected` | `GridMenuItem` | — | Não | Item atualmente selecionado. Suporta two-way binding via `[(selected)]`. |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `selectedChange` | `EventEmitter<GridMenuItem>` | Emitido quando o usuário seleciona um novo item. Usado para two-way binding com `[(selected)]`. |
+
+### Tipos
+
+```typescript
+type GridMenuItem = {
+    icon?: string;                         // Classe FA (ex: 'fa-home') ou URL de imagem SVG
+    label?: string;                        // Texto exibido abaixo do ícone
+    action: () => void;                    // Função executada ao clicar (obrigatório)
+    disabled?: boolean | (() => boolean);  // Desabilita o item
+    active?: boolean;                      // Estado de seleção ativo (gerenciado internamente)
+};
+```
+
+## Exemplos
+
+### Menu básico com ícones Font Awesome
+
+```html
+<s-grid-menu
+    [items]="items"
+    [useFontAwesomeIcons]="true"
+    [selectable]="false"
+></s-grid-menu>
+```
+
+```typescript
+items: GridMenuItem[] = [
+    { icon: 'fa-home', label: 'Início', action: () => this.navegar('home') },
+    { icon: 'fa-user', label: 'Perfil', action: () => this.navegar('perfil') },
+    { icon: 'fa-cog', label: 'Configurações', action: () => this.navegar('config') },
+];
+```
+
+### Menu com seleção e two-way binding
+
+```html
+<s-grid-menu
+    [items]="items"
+    [useFontAwesomeIcons]="true"
+    [selectable]="true"
+    [(selected)]="itemSelecionado"
+    (selectedChange)="onItemSelecionado($event)"
+></s-grid-menu>
+<div>Selecionado: {{ itemSelecionado?.label }}</div>
+```
+
+### Menu com itens desabilitados
+
+```html
+<s-grid-menu
+    [items]="itemsComDesabilitados"
+    [useFontAwesomeIcons]="true"
+></s-grid-menu>
+```
+
+```typescript
+itemsComDesabilitados: GridMenuItem[] = [
+    { icon: 'fa-home', label: 'Início', action: () => {} },
+    { icon: 'fa-lock', label: 'Bloqueado', action: () => {}, disabled: true },
+    { icon: 'fa-cog', label: 'Dinâmico', action: () => {}, disabled: () => !this.temPermissao },
+];
+```
+
+## Acessibilidade
+
+- Cada item do grid é um elemento clicável — utilize o `label` para descrição adequada
+- Itens desabilitados bloqueiam interação e não emitem eventos
+- O estado ativo (`active`) é visualmente distinguido para indicar a seleção atual
+
+## Componentes relacionados
+
+- [`TieredMenu`](../tiered-menu/README.md) — quando precisar de menus com hierarquia e submenus
+- [`NavigationButton`](../navigation-button/README.md) — quando precisar de navegação sequencial entre etapas

package/help-popover/README.md

@@ -0,0 +1,134 @@
+# HelpPopover
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Diretiva que exibe um popover de ajuda ao clicar no elemento hospedeiro. Suporta conteúdo como texto simples ou `TemplateRef`, com cabeçalho, rodapé, ícone, botão de fechar e posicionamento automático.
+
+## Quando usar
+
+- Explicar campos de formulário com regras complexas de preenchimento
+- Fornecer contexto adicional sobre funcionalidades sem sobrecarregar a interface
+- Quando o conteúdo de ajuda é extenso demais para um tooltip simples
+
+## Quando não usar
+
+- Mensagens curtas ao passar o mouse — prefira [`Tooltip`](../tooltip/README.md)
+- Ícone de informação simples ao lado de um label — prefira [`InfoSign`](../info-sign/README.md)
+
+## Instalação
+
+```typescript
+import { HelpPopoverModule } from '@seniorsistemas/angular-components/help-popover';
+
+@NgModule({
+    imports: [HelpPopoverModule],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<button [sHelpPopover]="'Informe aqui o seu CPF'" popoverPosition="right">?</button>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `sHelpPopover` | `string \| TemplateRef<any> \| null` | `null` | Sim | Conteúdo do popover. Aceita texto simples ou `TemplateRef` Angular. |
+| `closeButton` | `boolean` | `true` | Não | Exibe o botão de fechar (X) no cabeçalho. |
+| `popoverIcon` | `string` | `''` | Não | Classe Font Awesome do ícone exibido no cabeçalho (ex: `'fas fa-info-circle'`). |
+| `popoverHeader` | `string` | `''` | Não | Texto exibido no cabeçalho do popover. |
+| `popoverFooter` | `string` | `''` | Não | Texto exibido no rodapé do popover. |
+| `popoverButtonText` | `string` | `''` | Não | Texto do botão de ação no rodapé. Ao clicar, emite `buttonClicked`. |
+| `popoverPosition` | `HelpPopoverPosition` | `'bottom'` | Não | Posição do popover em relação ao elemento. Reposiciona automaticamente se não houver espaço. |
+| `popoverArrowPosition` | `HelpPopoverArrowPosition` | `'beginning'` | Não | Alinhamento da seta indicadora em relação ao lado do popover. |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `buttonClicked` | `EventEmitter<void>` | Emitido quando o usuário clica no botão de ação do rodapé. |
+
+### Tipos
+
+```typescript
+type HelpPopoverPosition = 'top' | 'right' | 'bottom' | 'left';
+type HelpPopoverArrowPosition = 'beginning' | 'middle' | 'end';
+```
+
+## Exemplos
+
+### Popover básico com texto simples
+
+```html
+<button
+    [sHelpPopover]="'Informe o CPF sem pontos e traços. Apenas números.'"
+    popoverHeader="CPF"
+    popoverIcon="fas fa-info-circle"
+    popoverPosition="right"
+>
+    ?
+</button>
+```
+
+### Popover com template customizado
+
+```html
+<ng-template #ajudaTemplate>
+    <div>
+        <p><strong>Formatos aceitos:</strong></p>
+        <ul>
+            <li>JPG / JPEG</li>
+            <li>PNG</li>
+        </ul>
+    </div>
+</ng-template>
+
+<button [sHelpPopover]="ajudaTemplate" popoverHeader="Upload de imagem">
+    Ajuda
+</button>
+```
+
+### Popover com rodapé e botão de ação
+
+```html
+<button
+    [sHelpPopover]="'Esta funcionalidade permite exportar dados.'"
+    popoverHeader="Exportar dados"
+    popoverFooter="Disponível nos planos Pro e Enterprise."
+    popoverButtonText="Ver planos"
+    (buttonClicked)="abrirPlanos()"
+>
+    Mais informações
+</button>
+```
+
+### Acionamento programático
+
+```html
+<span
+    [sHelpPopover]="'Este campo aceita apenas números inteiros positivos.'"
+    popoverHeader="Formato do campo"
+    popoverPosition="right"
+    #popoverRef="sHelpPopover"
+>
+    Quantidade em estoque
+</span>
+<button (click)="popoverRef.show()">?</button>
+```
+
+## Acessibilidade
+
+- O popover é aberto ao clicar no elemento hospedeiro e fechado ao clicar fora
+- Use `popoverHeader` para fornecer contexto sobre o conteúdo do popover
+- Pode ser acionado programaticamente via `#ref="sHelpPopover"` e `ref.show()`
+- Reposiciona automaticamente quando não há espaço na posição configurada
+
+## Componentes relacionados
+
+- [`InfoSign`](../info-sign/README.md) — ícone de informação simples com tooltip ao passar o mouse
+- [`Tooltip`](../tooltip/README.md) — dica contextual leve ao passar o mouse sobre um elemento

package/ia-insight/README.md

@@ -1,17 +1,35 @@
 # IA Insight (Descontinuado)
 
-> ⚠️ **Este pacote está descontinuado e será removido na versão 20.0.0.**
+![Status](https://img.shields.io/badge/status-deprecated-red)
 
-Este pacote é um alias de compatibilidade para o componente `Insights`.
+> **Este pacote está descontinuado e será removido na versão 20.0.0.**
+
+Este pacote é um alias de compatibilidade para o componente `Insights`. O seletor `s-ia-insight` e o pacote `ia-insight` foram substituídos por `s-insights` e `insights`.
 
 ## Migração
 
-Use `InsightsModule` e `InsightsComponent` de `@seniorsistemas/angular-components/insights` em novos projetos.
+Substitua as importações do pacote antigo pelo novo:
+
+```typescript
+// Antes (descontinuado)
+import { IaInsightModule } from '@seniorsistemas/angular-components/ia-insight';
+
+// Depois (recomendado)
+import { InsightsModule } from '@seniorsistemas/angular-components/insights';
+```
 
-O seletor `s-ia-insight` também está descontinuado — use `s-insights`.
+Substitua o seletor no template:
+
+```html
+<!-- Antes (descontinuado) -->
+<s-ia-insight [insights]="insights"></s-ia-insight>
+
+<!-- Depois (recomendado) -->
+<s-insights [insights]="insights"></s-insights>
+```
 
 ## Documentação
 
 Consulte a documentação completa do componente em:
-- **Storybook**: `Components/Structure/Insights`
-- **Pacote**: `@seniorsistemas/angular-components/insights`
+
+- [`Insights`](../insights/README.md) — documentação atualizada do componente

package/image-cropper/README.md

@@ -0,0 +1,140 @@
+# ImageCropper
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de recorte de imagem baseado na biblioteca `cropperjs`. Exibe um dialog com área interativa para selecionar, recortar e remover imagens, com suporte a proporção de aspecto configurável e recorte circular.
+
+## Quando usar
+
+- Recorte de foto de perfil ou avatar antes do upload
+- Ajuste de imagens com proporção específica (1:1, 16:9, etc.)
+- Fluxos de upload onde o usuário precisa selecionar e ajustar a área da imagem
+
+## Quando não usar
+
+- Visualização simples de imagens sem necessidade de edição — prefira `<img>` ou o componente Thumbnail
+- Upload de imagens sem recorte — use um campo de arquivo comum
+
+## Instalação
+
+```typescript
+import { ImageCropperModule, ImageCropperService } from '@seniorsistemas/angular-components/image-cropper';
+
+@NgModule({
+    imports: [ImageCropperModule],
+    providers: [ImageCropperService],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-image-cropper
+    [(visible)]="cropperVisivel"
+    [imageSource]="imagemBase64"
+    [aspectRatio]="1"
+    (croppedImage)="onImagemRecortada($event)"
+></s-image-cropper>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `visible` | `boolean` | `false` | Não | Controla a visibilidade do dialog. Suporta two-way binding via `[(visible)]`. |
+| `imageSource` | `string` | `undefined` | Não | URL ou base64 da imagem a ser carregada no cropper. |
+| `header` | `string` | `'Recortar imagem'` | Não | Título exibido no cabeçalho do dialog. |
+| `cropLabel` | `string` | `'Recortar'` | Não | Rótulo do botão de confirmar o recorte. |
+| `selectAnotherLabel` | `string` | `'Trocar'` | Não | Rótulo do botão de trocar a imagem. |
+| `removeLabel` | `string` | `'Remover'` | Não | Rótulo do botão de remover a imagem. |
+| `cancelLabel` | `string` | `'Cancelar'` | Não | Rótulo do botão de cancelar. |
+| `emptyStateTitle` | `string` | `'Selecione uma foto...'` | Não | Título do estado vazio (sem imagem selecionada). |
+| `emptyStateActionLabel` | `string` | `'Escolher imagem'` | Não | Rótulo do botão de ação do estado vazio. |
+| `emptyStateIconClass` | `string` | `'fa fa-picture-o'` | Não | Classe do ícone exibido no estado vazio. |
+| `aspectRatio` | `number` | `NaN` | Não | Proporção de aspecto para o recorte. `1` = quadrado, `16/9` = widescreen, `NaN` = livre. |
+| `rounded` | `boolean` | `false` | Não | Quando `true`, exibe a área de recorte no formato circular. |
+| `allowSelectAnother` | `boolean` | `true` | Não | Exibe o botão para trocar a imagem selecionada. |
+| `allowRemove` | `boolean` | `true` | Não | Exibe o botão para remover a imagem. |
+| `allowCancel` | `boolean` | `true` | Não | Exibe o botão de cancelar. |
+| `id` | `string` | `s-image-cropper-{auto}` | Não | Identificador único do componente no DOM. |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `visibleChange` | `EventEmitter<boolean>` | Emitido quando a visibilidade muda, habilitando `[(visible)]`. |
+| `croppedImage` | `EventEmitter<string>` | Emitido com a imagem recortada em formato base64 string. |
+| `croppedCanvas` | `EventEmitter<HTMLCanvasElement>` | Emitido com o `HTMLCanvasElement` resultante do recorte. |
+| `removedImage` | `EventEmitter<void>` | Emitido quando o usuário confirma a remoção da imagem. |
+| `changeImage` | `EventEmitter<void>` | Emitido quando o usuário clica em "Trocar" para selecionar outra imagem. |
+| `cancel` | `EventEmitter<void>` | Emitido quando o usuário cancela o recorte. |
+
+## Exemplos
+
+### Recorte de foto de perfil (1:1 circular)
+
+```html
+<s-button label="Editar foto" (clicked)="cropperVisivel = true"></s-button>
+
+<s-image-cropper
+    [(visible)]="cropperVisivel"
+    [imageSource]="imagemBase64"
+    [aspectRatio]="1"
+    [rounded]="true"
+    header="Foto de perfil"
+    (croppedImage)="fotoPerfil = $event"
+    (changeImage)="selecionarNovaImagem()"
+></s-image-cropper>
+```
+
+### Recorte com proporção livre
+
+```html
+<s-image-cropper
+    [(visible)]="cropperVisivel"
+    [imageSource]="imagemBase64"
+    (croppedImage)="onImagemRecortada($event)"
+    (removedImage)="onImagemRemovida()"
+></s-image-cropper>
+```
+
+### Uso via serviço (recomendado para fluxos simples)
+
+```typescript
+constructor(private imageCropperService: ImageCropperService) {}
+
+abrirCropper(imagemBase64: string) {
+    this.imageCropperService.show({
+        imageSource: imagemBase64,
+        aspectRatio: 1,
+        croppedImage: (imagem) => this.fotoPerfil = imagem,
+        changeImage: () => this.selecionarNovaImagem(),
+    });
+}
+```
+
+### Com header e footer customizados
+
+```html
+<s-image-cropper #cropper [(visible)]="cropperVisivel" [imageSource]="imagemBase64">
+    <s-header>
+        <span>Header Personalizado</span>
+    </s-header>
+    <s-footer>
+        <s-button label="Recortar" priority="primary" (clicked)="cropper.onCropImage()"></s-button>
+    </s-footer>
+</s-image-cropper>
+```
+
+## Acessibilidade
+
+- O dialog possui cabeçalho com título configurável via `header`
+- Os botões de ação têm rótulos customizáveis para internacionalização
+- O estado vazio orienta o usuário sobre a próxima ação via `emptyStateTitle`
+
+## Componentes relacionados
+
+- [`Thumbnail`](../thumbnail/README.md) — exibição da imagem recortada