# 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 sem bloqueio de interação — prefira [`Progressbar`](../progressbar/README.md) quando não for necessário bloquear o conteúdo

## 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`, `logo` ou `progress-bar`.                                                                       |
| `blockWindow`      | `boolean`                        | `false`                       |     Não     | Quando `true`, bloqueia a janela inteira com overlay em vez de apenas o container.                                                |
| `progressBarMode`  | `'percentage' \| 'intermittent'` | `'intermittent'`              |     Não     | Modo da barra de progresso. Usado apenas quando `indicator` é `ProgressBar`.                                                      |
| `progressBarValue` | `number`                         | `0`                           |     Não     | Valor de progresso de 0 a 100. Usado no modo `'percentage'`.                                                                      |
| `progressBarLabel` | `string`                         | `undefined`                   |     Não     | Texto exibido abaixo da barra. Se omitido, usa `'{value}%'` no modo `'percentage'` ou `'Carregando...'` no modo `'intermittent'`. |
| `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
    ProgressBar = 'progress-bar', // Barra de progresso (intermitente ou percentual)
}

type ProgressBarIndicatorMode = 'percentage' | 'intermittent';
```

### 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>
```

### Barra de progresso intermitente

Útil quando não é possível mensurar o progresso da operação.

```html
<s-loading-state
    [loading]="processando"
    [indicator]="'progress-bar'"
    progressBarMode="intermittent"
>
    <div>Conteúdo sendo processado.</div>
</s-loading-state>
```

### Barra de progresso percentual

Ideal para uploads, downloads ou processos em etapas com progresso mensurável.

```html
<s-loading-state
    [loading]="enviando"
    [indicator]="'progress-bar'"
    progressBarMode="percentage"
    [progressBarValue]="uploadProgress"
    progressBarLabel="Enviando arquivo..."
>
    <div>Conteúdo sendo enviado.</div>
</s-loading-state>
```

### 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