# 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
