@seniorsistemas/angular-components 19.3.3 → 19.3.4

package/picklist/README.md

@@ -0,0 +1,170 @@
+# Picklist
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente para transferência de itens entre duas listas — disponíveis e selecionados. Suporta arrastar e soltar, filtro por texto, seleção múltipla com checkboxes e templates customizáveis para renderização dos itens.
+
+## Quando usar
+
+- Seleção de múltiplos itens de uma lista para outra (ex: permissões, usuários, produtos)
+- Configuração de associações ou vínculos onde a ordem dos itens selecionados importa
+- Qualquer cenário de transferência bidirecional entre dois conjuntos de dados
+
+## Quando não usar
+
+- Para seleção simples de um único item — use `Select` ou `RadioButton`
+- Para seleção múltipla sem necessidade de duas listas — use `Checkbox` ou `MultiSelect`
+- Quando a lista é muito grande e precisa de paginação — considere uma abordagem diferente
+
+## Instalação
+
+```typescript
+import { PicklistModule } from '@seniorsistemas/angular-components/picklist';
+import { TemplateModule } from '@seniorsistemas/angular-components/template';
+
+@NgModule({ imports: [PicklistModule, TemplateModule] })
+export class MeuModulo {}
+```
+
+## Uso básico
+
+```html
+<s-picklist
+  [itensToSelect]="itensDisponiveis"
+  [selectedItens]="itensSelecionados"
+  (selectedItensChange)="onSelecaoMudou($event)"
+  (itensToSelectChange)="onDisponiveisAtualizado($event)"
+>
+  <ng-template sTemplate="item-to-select" let-item="item">
+    <span>{{ item.nome }}</span>
+  </ng-template>
+  <ng-template sTemplate="selected-item" let-item="item">
+    <span>{{ item.nome }}</span>
+  </ng-template>
+</s-picklist>
+```
+
+> Os dois templates (`item-to-select` e `selected-item`) são **obrigatórios**.
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `itensToSelect` | `PickListItem<any>[]` | `[]` | Sim | Lista de itens disponíveis para seleção (coluna esquerda) |
+| `selectedItens` | `PickListItem<any>[]` | `[]` | Sim | Lista de itens já selecionados (coluna direita) |
+| `availableItensLabel` | `string` | Tradução padrão | Não | Rótulo do cabeçalho da lista de disponíveis |
+| `availableItensPlaceholder` | `string` | `undefined` | Não | Placeholder do campo de busca da lista de disponíveis |
+| `addSelectedItensLabel` | `string` | `undefined` | Não | Rótulo do botão que move itens selecionados para a direita |
+| `addAllItensLabel` | `string` | `undefined` | Não | Rótulo do botão que move todos os disponíveis para a direita |
+| `selectedItensLabel` | `string` | Tradução padrão | Não | Rótulo do cabeçalho da lista de selecionados |
+| `selectedItensPlaceholder` | `string` | `undefined` | Não | Placeholder do campo de busca da lista de selecionados |
+| `removeSelectedItemsLabel` | `string` | `undefined` | Não | Rótulo do botão que remove itens selecionados |
+| `removeAllItemsLabel` | `string` | `undefined` | Não | Rótulo do botão que remove todos os selecionados |
+| `showCheckbox` | `boolean` | `false` | Não | Exibe checkboxes nos itens e "selecionar todos" no cabeçalho |
+| `filterBy` | `string` | `''` | Não | Propriedade do objeto `data` usada para filtrar os itens. Quando definido, exibe campos de busca |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `selectedItensChange` | `EventEmitter<any[]>` | Emitido quando a lista de selecionados muda. Emite os dados brutos (sem o wrapper `PickListItem`) |
+| `itensToSelectChange` | `EventEmitter<any[]>` | Emitido quando a lista de disponíveis muda. Emite os dados brutos (sem o wrapper `PickListItem`) |
+
+### Tipos
+
+```typescript
+interface PickListItem<T> {
+  data: T;          // Dados brutos do item — expostos no template como `let-item="item"`
+  disabled?: boolean; // Impede seleção, movimentação e drag do item
+}
+```
+
+## Exemplos
+
+### Picklist básico
+
+```html
+<s-picklist
+  [itensToSelect]="parseItensPickList(paises)"
+  [selectedItens]="parseItensPickList(paisesSelecionados)"
+  (selectedItensChange)="onSelecaoMudou($event)"
+>
+  <ng-template sTemplate="item-to-select" let-item="item">
+    <span>{{ item.nome }}</span>
+  </ng-template>
+  <ng-template sTemplate="selected-item" let-item="item">
+    <span>{{ item.nome }}</span>
+  </ng-template>
+</s-picklist>
+```
+
+### Com filtro e checkbox
+
+```html
+<s-picklist
+  [itensToSelect]="itensDisponiveis"
+  [selectedItens]="itensSelecionados"
+  [showCheckbox]="true"
+  filterBy="nome"
+  availableItensPlaceholder="Buscar..."
+  selectedItensPlaceholder="Buscar..."
+>
+  <ng-template sTemplate="item-to-select" let-item="item">
+    <span>{{ item.nome }}</span>
+  </ng-template>
+  <ng-template sTemplate="selected-item" let-item="item">
+    <span>{{ item.nome }}</span>
+  </ng-template>
+</s-picklist>
+```
+
+### Com itens desabilitados
+
+```typescript
+import { parseItensPickList } from '@seniorsistemas/angular-components/picklist';
+
+this.itensDisponiveis = parseItensPickList(produtos, (item) => !item.emEstoque);
+```
+
+### Com labels customizados
+
+```html
+<s-picklist
+  [itensToSelect]="itensDisponiveis"
+  [selectedItens]="itensSelecionados"
+  availableItensLabel="Países disponíveis"
+  selectedItensLabel="Países selecionados"
+  addSelectedItensLabel="Incluir →"
+  addAllItensLabel="Incluir todos"
+  removeSelectedItemsLabel="← Excluir"
+  removeAllItemsLabel="Excluir todos"
+>
+  ...
+</s-picklist>
+```
+
+### Utilitário parseItensPickList
+
+```typescript
+import { parseItensPickList } from '@seniorsistemas/angular-components/picklist';
+
+// Sem itens desabilitados
+this.itensToSelect = parseItensPickList(meusObjetos);
+
+// Com função de desabilitação
+this.itensToSelect = parseItensPickList(meusObjetos, (item) => item.bloqueado);
+```
+
+## Acessibilidade
+
+- Os botões de adicionar/remover são elementos `<button>` nativos, navegáveis por teclado
+- O drag & drop usa o CDK do Angular, acessível com mouse
+- Itens desabilitados não podem ser selecionados, movidos ou arrastados
+- Os campos de filtro têm `placeholder` configurável para orientar o usuário
+
+## Componentes relacionados
+
+- [`TokenList`](../token-list/README.md) — exibição de tokens selecionados em modo somente leitura
+- [`Chips`](../chips/README.md) — entrada de múltiplos valores em formato de tags

package/pin-code-field/README.md

@@ -0,0 +1,137 @@
+# PinCodeField
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente para entrada de códigos PIN ou códigos de verificação (OTP) com campos individuais para cada dígito. Implementa `ControlValueAccessor` para integração nativa com Reactive Forms e Template-Driven Forms do Angular.
+
+## Quando usar
+
+- Códigos de verificação OTP enviados por SMS ou e-mail
+- Autenticação de dois fatores (2FA)
+- PINs numéricos de acesso (ex: cartão de crédito)
+- Códigos de ativação de produto (alfanumérico)
+
+## Quando não usar
+
+- Para senhas textuais sem comprimento fixo — use `<input type="password">` com `sPasswordStrength`
+- Para campos de texto curto com comprimento variável — use `InputText`
+
+## Instalação
+
+```typescript
+import { PinCodeFieldComponent } from '@seniorsistemas/angular-components/pin-code-field';
+
+@Component({
+  standalone: true,
+  imports: [PinCodeFieldComponent, ReactiveFormsModule],
+})
+export class MeuComponent {}
+```
+
+## Uso básico
+
+```html
+<form [formGroup]="form">
+  <s-pin-code-field
+    formControlName="codigo"
+    [length]="6"
+    helpText="Digite o código de 6 dígitos recebido"
+    (codeFilled)="onCodigoConcluido($event)"
+  ></s-pin-code-field>
+</form>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `length` | `number` | `6` | Não | Número de campos de entrada (comprimento do código PIN). Mínimo: 1 |
+| `alphanumeric` | `boolean` | `false` | Não | Permite entrada alfanumérica. Quando `false`, aceita apenas dígitos (0–9) |
+| `helpText` | `string` | `''` | Não | Texto de ajuda exibido abaixo dos campos |
+| `invalid` | `boolean` | `false` | Não | Exibe borda vermelha nos campos. Tipicamente vinculado ao estado `invalid && dirty` do `FormControl` |
+| `disabled` | `boolean` | `false` | Não | Two-way binding para o estado desabilitado. Desabilita todos os campos |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `codeFilled` | `OutputEmitterRef<string>` | Emitido quando todos os campos estão preenchidos. Emite o código completo como string |
+
+## Exemplos
+
+### Código OTP de 6 dígitos com Reactive Forms
+
+```html
+<form [formGroup]="form">
+  <s-pin-code-field
+    formControlName="codigo"
+    [length]="6"
+    [alphanumeric]="false"
+    [invalid]="(form.get('codigo')?.invalid && form.get('codigo')?.dirty) || false"
+    helpText="Digite o código de 6 dígitos recebido"
+    (codeFilled)="onCodigoConcluido($event)"
+  ></s-pin-code-field>
+</form>
+```
+
+### PIN de 4 dígitos
+
+```html
+<s-pin-code-field
+  formControlName="pin"
+  [length]="4"
+  helpText="Digite seu PIN de 4 dígitos"
+></s-pin-code-field>
+```
+
+### Código alfanumérico
+
+```html
+<s-pin-code-field
+  formControlName="chave"
+  [length]="6"
+  [alphanumeric]="true"
+  helpText="Digite o código alfanumérico (letras e números)"
+></s-pin-code-field>
+```
+
+### Estado de erro
+
+```html
+<s-pin-code-field
+  formControlName="codigo"
+  [length]="6"
+  [invalid]="true"
+  helpText="Digite o código de 6 dígitos"
+></s-pin-code-field>
+<p style="color: red;">Código inválido. Tente novamente.</p>
+```
+
+### Desabilitado com valor pré-preenchido
+
+```typescript
+this.form = new FormGroup({
+  codigo: new FormControl('123456'),
+});
+this.form.disable();
+```
+
+```html
+<s-pin-code-field formControlName="codigo" [length]="6"></s-pin-code-field>
+```
+
+## Acessibilidade
+
+- Cada campo de entrada possui ARIA label e role semântico correto
+- Navegação completa por teclado:
+  - `ArrowRight` / `ArrowLeft`: move o foco entre os campos
+  - `Backspace`: limpa o campo atual ou retorna ao anterior
+  - Auto-avança para o próximo campo ao preencher cada dígito
+- Suporte a colar (Ctrl+V / Cmd+V): distribui automaticamente os caracteres válidos entre os campos
+- O componente é marcado como `touched` quando o último campo perde o foco
+
+## Componentes relacionados
+
+- [`PasswordStrength`](../password-strength/README.md) — indicador visual de força de senha

package/product-header/README.md

@@ -1,17 +1,44 @@
-# Product Header (Descontinuado)
+# ProductHeader
 
-> ⚠️ **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 `Topbar`.
+> **Descontinuado** — Este pacote é um alias de compatibilidade para o componente `Topbar` e será removido na versão 20.0.0.
+
+O pacote `product-header` re-exporta `TopbarComponent` e `TopbarModule` do pacote `@seniorsistemas/angular-components/topbar` com os nomes antigos `ProductHeaderComponent` e `ProductHeaderModule`.
+
+## Quando usar
+
+- Apenas para manutenção de código legado que já usa `ProductHeaderComponent` ou `ProductHeaderModule`
+
+## Quando não usar
+
+- Em todo código novo — use `TopbarComponent` ou `TopbarModule` do pacote `@seniorsistemas/angular-components/topbar`
 
 ## Migração
 
-Use `TopbarModule` e `TopbarComponent` de `@seniorsistemas/angular-components/topbar` em novos projetos.
+```typescript
+// Antes (descontinuado)
+import { ProductHeaderModule } from '@seniorsistemas/angular-components/product-header';
 
-O seletor `s-product-header` também está descontinuado — use `s-topbar`.
+// Depois (recomendado)
+import { TopbarModule } from '@seniorsistemas/angular-components/topbar';
+```
+
+```html
+<!-- Antes (descontinuado) -->
+<s-product-header></s-product-header>
+
+<!-- Depois (recomendado) -->
+<s-topbar></s-topbar>
+```
 
 ## Documentação
 
-Consulte a documentação completa do componente em:
+Consulte a documentação completa do componente no Topbar:
+
 - **Storybook**: `Components/Structure/Topbar`
 - **Pacote**: `@seniorsistemas/angular-components/topbar`
+
+## Componentes relacionados
+
+- [`Topbar`](../topbar/README.md) — componente substituto recomendado

package/profile-picture-picker/README.md

@@ -0,0 +1,159 @@
+# ProfilePicturePicker
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente para seleção, recorte e gerenciamento de foto de perfil. Permite selecionar uma imagem via clique ou arrastar e soltar, recortá-la em um cropper integrado e exibi-la como thumbnail. Implementa `ControlValueAccessor` para integração com Angular Forms.
+
+## Quando usar
+
+- Cadastro ou edição de perfil de usuário com foto
+- Formulários que precisam de upload de imagem com recorte antes de salvar
+- Campos de avatar em sistemas de gestão de pessoas
+
+## Quando não usar
+
+- Para upload de arquivos genéricos (documentos, PDFs, etc.) — use `FilePicker`
+- Para seleção de imagem sem recorte — use um input de arquivo simples
+- Quando o aspecto ratio varia dinamicamente por item — configure `aspectRatio` conforme o caso
+
+## Instalação
+
+```typescript
+import { ProfilePicturePickerModule } from '@seniorsistemas/angular-components/profile-picture-picker';
+
+@NgModule({ imports: [ProfilePicturePickerModule] })
+export class MeuModulo {}
+```
+
+## Uso básico
+
+```html
+<s-profile-picture-picker
+  formControlName="avatar"
+  subtitle="Formato: JPG, PNG (máximo de 1 MB)"
+  simpleTitle="Arraste sua foto ou"
+  actionTitle="selecione um arquivo"
+  accept=".png, .jpg"
+  [supportedExtensions]="['png', 'jpg']"
+  [maxFileSize]="1048576"
+  (imageChange)="onImageChange($event)"
+  (removedImage)="onImageRemoved()"
+  (invalidFile)="onArquivoInvalido($event)"
+/>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `subtitle` | `string` | — | Sim | Legenda exibida abaixo do título com orientações de formato e tamanho |
+| `simpleTitle` | `string` | `undefined` | Não | Parte estática do título (antes da ação clicável) |
+| `actionTitle` | `string` | `undefined` | Não | Parte clicável do título — ao clicar, abre o seletor de arquivo |
+| `image` | `string \| ProfilePicturePickerData \| null` | `null` | Não | Imagem atual. Aceita string base64 ou objeto com dados do arquivo |
+| `aspectRatio` | `number` | `1` | Não | Proporção de aspecto do recorte (`1` = quadrado, `16/9` = widescreen) |
+| `accept` | `string` | `undefined` | Não | Atributo `accept` do input de arquivo (ex: `".png, .jpg"`) |
+| `supportedExtensions` | `string[]` | `[]` | Não | Extensões aceitas para validação (ex: `['png', 'jpg']`) |
+| `maxFileSize` | `number` | `undefined` | Não | Tamanho máximo em bytes. Exemplo: `1048576` = 1 MB |
+| `removeButtonLabel` | `string` | Tradução padrão | Não | Texto do botão de remover a foto |
+| `changeButtonLabel` | `string` | Tradução padrão | Não | Texto do botão de alterar a foto |
+| `confirmationTexts` | `ConfirmationTexts` | `undefined` | Não | Textos do diálogo de confirmação de remoção |
+| `cropperLabelsConfig` | `CropperLabelsConfig` | `undefined` | Não | Textos customizados do Image Cropper integrado |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `imageChange` | `EventEmitter<string \| ProfilePicturePickerData>` | Emitido quando uma imagem é selecionada e recortada |
+| `removedImage` | `EventEmitter<void>` | Emitido quando o usuário confirma a remoção da imagem |
+| `invalidFile` | `EventEmitter<FileValidationErrors>` | Emitido quando a validação do arquivo falha |
+| ~~`changedImage`~~ | `EventEmitter<string>` | **Descontinuado** — use `imageChange` |
+
+### Tipos
+
+```typescript
+interface ProfilePicturePickerData {
+  source: File;   // Arquivo original selecionado
+  base64: string; // Imagem recortada em base64
+}
+
+interface FileValidationErrors {
+  file: File | null;
+  validation: 'maxFileSize' | 'maxFileLimit' | 'typeInvalid' | 'unsupportedExtension';
+}
+
+interface ConfirmationTexts {
+  removalHeader: string;       // Título do diálogo de confirmação
+  removalMessage: string;      // Mensagem do diálogo
+  removalAcceptLabel: string;  // Label do botão confirmar
+  removalRejectLabel: string;  // Label do botão cancelar
+}
+
+interface CropperLabelsConfig {
+  header?: string;
+  cropLabel?: string;
+  removeLabel?: string;
+  cancelLabel?: string;
+  selectAnotherLabel?: string;
+  emptyStateTitle?: string;
+  emptyStateActionLabel?: string;
+}
+```
+
+## Exemplos
+
+### Cadastro de novo usuário
+
+```html
+<form [formGroup]="form">
+  <s-profile-picture-picker
+    formControlName="foto"
+    subtitle="Formato: JPG, PNG (máximo de 1 MB)"
+    simpleTitle="Arraste sua foto ou"
+    actionTitle="selecione um arquivo"
+    accept=".png, .jpg"
+    [supportedExtensions]="['png', 'jpg']"
+    [maxFileSize]="1048576"
+    (invalidFile)="onArquivoInvalido($event)"
+  ></s-profile-picture-picker>
+</form>
+```
+
+### Edição com imagem pré-carregada
+
+```html
+<form [formGroup]="form">
+  <!-- O formControl recebe a string base64 da imagem atual -->
+  <s-profile-picture-picker
+    formControlName="foto"
+    subtitle="Formato: JPG, PNG"
+    [changeButtonLabel]="'Trocar foto'"
+    [removeButtonLabel]="'Excluir foto'"
+    [confirmationTexts]="confirmacaoTextos"
+  ></s-profile-picture-picker>
+</form>
+```
+
+### Com aspect ratio widescreen (banner)
+
+```html
+<s-profile-picture-picker
+  formControlName="capa"
+  subtitle="Formato: JPG, PNG — proporção 16:9"
+  [aspectRatio]="16 / 9"
+></s-profile-picture-picker>
+```
+
+## Acessibilidade
+
+- A área de upload aceita foco via teclado e interação por clique
+- O drag & drop é complementar — sempre há o botão clicável como alternativa
+- O diálogo de confirmação de remoção usa PrimeNG `ConfirmDialog`, que é acessível por teclado
+- O thumbnail é decorativo e não carece de texto alternativo quando a imagem é de perfil do usuário logado
+
+## Componentes relacionados
+
+- [`ImageCropper`](../image-cropper/README.md) — cropper de imagem usado internamente
+- [`Thumbnail`](../thumbnail/README.md) — exibição de imagem em miniatura
+- [`FilePicker`](../file-picker/README.md) — seleção de arquivos genérica

package/progressbar/README.md

@@ -0,0 +1,136 @@
+# Progressbar
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de barra de progresso para representar visualmente o avanço de uma operação. Suporta modo determinado (valor percentual 0–100) e modo indeterminado (animação contínua quando a duração é desconhecida), além de um marcador de valor-alvo para comparação.
+
+## Quando usar
+
+- Processos com percentual de conclusão calculável — uploads, downloads, etapas de um fluxo, metas
+- Operações de duração desconhecida — chamadas de API, processamentos em background (modo indeterminado)
+- Dashboards de desempenho ou KPIs com comparação entre valor atual e meta
+
+## Quando não usar
+
+- Para indicar carregamento simples de página ou componente — use `Spinner` ou `Skeleton`
+- Para representar sequências de etapas com navegação — use `Steps`
+- Quando não há valor numérico mensurável e a duração é desconhecida sem necessidade de label — use `Spinner`
+
+## Instalação
+
+```typescript
+import { ProgressBarModule } from '@seniorsistemas/angular-components/progressbar';
+
+@NgModule({ imports: [ProgressBarModule] })
+export class MeuModulo {}
+```
+
+## Uso básico
+
+```html
+<s-progressbar
+  [value]="75"
+  activeColor="blue"
+  [showValue]="true"
+/>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `activeColor` | `ProgressBarColors` | — | Sim | Cor da barra de progresso ativa |
+| `value` | `number` | — | Não* | Valor atual (0–100). Obrigatório no modo `'determinate'`. Não usar em `'indeterminate'` |
+| `mode` | `ProgressBarMode` | `'determinate'` | Não | Modo de operação da barra |
+| `showValue` | `boolean` | `true` | Não | Exibe o valor percentual dentro da barra (apenas no modo determinado) |
+| `targetValue` | `number` | `undefined` | Não | Valor-alvo (0–100) exibido como marcador de referência (modo determinado) |
+| `label` | `string` | `undefined` | Não | Rótulo exibido abaixo da barra no modo indeterminado |
+| `targetLabel` | `string` | `undefined` | Não | Rótulo do marcador de valor-alvo |
+| `numberFormatOptions` | `Intl.NumberFormatOptions` | `{ style: 'decimal', minimumFractionDigits: 0, maximumFractionDigits: 2, roundingMode: 'trunc' }` | Não | Opções de formatação do valor percentual exibido |
+
+### Tipos
+
+```typescript
+type ProgressBarColors = 'blue' | 'green' | 'red' | 'yellow';
+
+type ProgressBarMode = 'determinate' | 'indeterminate';
+```
+
+### Guia de cores
+
+| Cor | Uso sugerido |
+|-----|-------------|
+| `'blue'` | Progresso neutro ou informativo |
+| `'green'` | Progresso positivo ou concluído com sucesso |
+| `'red'` | Alertas críticos ou progresso negativo |
+| `'yellow'` | Alertas ou progresso intermediário |
+
+## Exemplos
+
+### Modo determinado básico
+
+```html
+<s-progressbar
+  [value]="65"
+  activeColor="blue"
+  [showValue]="true"
+  mode="determinate"
+></s-progressbar>
+```
+
+### Com marcador de meta
+
+```html
+<s-progressbar
+  [value]="45"
+  activeColor="green"
+  [showValue]="true"
+  mode="determinate"
+  [targetValue]="70"
+  targetLabel="Meta 70%"
+></s-progressbar>
+```
+
+### Múltiplas cores
+
+```html
+<s-progressbar [value]="60" activeColor="blue" [showValue]="true" mode="determinate"></s-progressbar>
+<s-progressbar [value]="80" activeColor="green" [showValue]="true" mode="determinate"></s-progressbar>
+<s-progressbar [value]="35" activeColor="red" [showValue]="true" mode="determinate"></s-progressbar>
+<s-progressbar [value]="55" activeColor="yellow" [showValue]="true" mode="determinate"></s-progressbar>
+```
+
+### Sem valor exibido
+
+```html
+<s-progressbar
+  [value]="40"
+  activeColor="blue"
+  [showValue]="false"
+  mode="determinate"
+></s-progressbar>
+```
+
+### Modo indeterminado
+
+```html
+<s-progressbar
+  activeColor="blue"
+  mode="indeterminate"
+  label="Processando dados..."
+></s-progressbar>
+```
+
+## Acessibilidade
+
+- O componente usa elementos semânticos de barra de progresso com valores calculados pelo CSS
+- No modo determinado, o valor percentual é exibido visualmente dentro da barra
+- No modo indeterminado, o `label` fornece contexto textual para leitores de tela sobre o que está sendo processado
+- Erros são lançados em tempo de desenvolvimento se `value` estiver fora do intervalo 0–100 ou se `value`/`targetValue` forem usados em modo `'indeterminate'`
+
+## Componentes relacionados
+
+- [`Spinner`](../spinner/README.md) — indicador de carregamento circular
+- [`Steps`](../steps/README.md) — sequência de etapas com navegação