@seniorsistemas/angular-components 19.3.3 → 19.3.4

package/slide-in-bar/README.md

@@ -0,0 +1,122 @@
+# SlideInBar
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de painel deslizante lateral que expande e colapsa ao clicar em um botão de toggle. Em telas pequenas (largura <= 420px), entra automaticamente em modo overlay, sobrepondo o conteúdo.
+
+> **Nota:** O seletor `s-slide-panel` e o pacote `slide-panel` estão descontinuados. Use `s-slide-in-bar` e o pacote `slide-in-bar` em novos projetos. O seletor antigo será removido na versão 20.0.0.
+
+## Quando usar
+
+- Filtros laterais em listas e tabelas que podem ser ocultados para dar mais espaço ao conteúdo
+- Painéis de detalhes ou configurações que coexistem com o conteúdo principal
+- Propriedades ou atributos de um elemento selecionado na área principal
+- Quando o painel deve empurrar o layout adjacente (`noOverlap`) ou flutuar sobre ele
+
+## Quando não usar
+
+- Painéis que precisam de overlay com backdrop — prefira `Sidebar`
+- Conteúdo que deve aparecer temporariamente em resposta a uma ação — prefira `Dialog` ou `Sidebar`
+
+## Instalação
+
+```typescript
+import { SlideInBarModule, SlideInBarService } from '@seniorsistemas/angular-components/slide-in-bar';
+
+@NgModule({
+  imports: [SlideInBarModule],
+  providers: [SlideInBarService],
+})
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-slide-in-bar (panelOpened)="onAbrir()" (panelClosed)="onFechar()">
+  <div slide-content>
+    <!-- conteúdo do painel deslizante -->
+  </div>
+  <div side-content>
+    <!-- conteúdo principal ao lado do painel -->
+  </div>
+</s-slide-in-bar>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `id` | `string` | `slide-panel-{n}` | Não | Identificador único do painel. Usado pelo `SlideInBarService` para fechar programaticamente |
+| `openIcon` | `string` | `'fas fa-chevron-right'` | Não | Classe Font Awesome do ícone no botão de abertura |
+| `closeIcon` | `string` | `'fas fa-chevron-left'` | Não | Classe Font Awesome do ícone no botão de fechamento |
+| `cache` | `boolean` | `false` | Não | Mantém o conteúdo no DOM quando fechado, preservando estado interno |
+| `createOpen` | `boolean` | `false` | Não | Inicia o painel já aberto |
+| `noOverlap` | `boolean` | `false` | Não | O painel empurra o layout adjacente em vez de sobrepor o conteúdo |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `panelOpened` | `EventEmitter<void>` | Emitido quando o painel é aberto pelo usuário |
+| `panelClosed` | `EventEmitter<void>` | Emitido quando o painel é fechado pelo usuário |
+
+## Exemplos
+
+### Painel de filtros
+
+```html
+<div style="display: flex; height: 400px;">
+  <s-slide-in-bar [cache]="true" (panelOpened)="onAbrir()">
+    <div slide-content style="padding: 16px; min-width: 200px;">
+      <h4>Filtros</h4>
+      <!-- inputs de filtro -->
+    </div>
+    <div side-content style="padding: 16px; flex: 1;">
+      <!-- conteúdo principal (tabela, lista) -->
+    </div>
+  </s-slide-in-bar>
+</div>
+```
+
+### Iniciando aberto com ícones customizados
+
+```html
+<s-slide-in-bar
+  [createOpen]="true"
+  openIcon="fas fa-plus"
+  closeIcon="fas fa-minus"
+>
+  <div slide-content>Conteúdo do painel</div>
+  <div side-content>Conteúdo principal</div>
+</s-slide-in-bar>
+```
+
+### Fechando programaticamente via serviço
+
+```typescript
+constructor(private slideInBarService: SlideInBarService) {}
+
+fecharPainel(): void {
+  this.slideInBarService.closeModal('meu-painel-id');
+}
+```
+
+```html
+<s-slide-in-bar id="meu-painel-id">
+  <div slide-content>Painel</div>
+  <div side-content>Conteúdo</div>
+</s-slide-in-bar>
+```
+
+## Acessibilidade
+
+- O botão de toggle é focável via teclado e pode ser acionado com `Enter` ou `Espaço`
+- Em telas com largura <= 420px, o painel entra automaticamente em modo overlay
+- A animação de abertura/fechamento tem duração de 200ms para não prejudicar a experiência de usuários sensíveis a movimento
+
+## Componentes relacionados
+
+- [`Sidebar`](../sidebar/README.md) — painel lateral com backdrop e suporte a templates customizados

package/slider/README.md

@@ -0,0 +1,127 @@
+# Slider
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de controle deslizante para seleção de valores numéricos dentro de um intervalo definido. Suporta modo simples (um valor) e modo de intervalo (dois valores: início e fim). Implementa `ControlValueAccessor` para integração com Angular Forms.
+
+## Quando usar
+
+- Seleção de um valor dentro de um intervalo contínuo (volume, brilho, porcentagem)
+- Filtros de faixa de valores (faixa de preço, temperatura, população)
+- Controles onde a posição relativa é mais relevante que o valor exato
+
+## Quando não usar
+
+- Entrada de valores numéricos precisos — prefira `NumberInput` com campo de texto
+- Intervalos com muitos passos discretos onde a precisão é crítica — prefira um campo com máscara numérica
+- Valores que não se encaixam em uma progressão linear
+
+## Instalação
+
+```typescript
+import { SliderModule } from '@seniorsistemas/angular-components/slider';
+
+@NgModule({ imports: [SliderModule] })
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<!-- Slider simples -->
+<s-slider formControlName="volume" [min]="0" [max]="100" [step]="5" />
+
+<!-- Slider de intervalo -->
+<s-slider formControlName="faixa" [multiple]="true" [min]="0" [max]="1000" />
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `value` | `number \| [number, number]` | `0` | Não | Valor atual. No modo range é `[inicio, fim]` |
+| `multiple` | `boolean` | `false` | Não | Habilita modo de intervalo (dois thumbs) |
+| `min` | `number` | `0` | Não | Valor mínimo do intervalo |
+| `max` | `number` | `100` | Não | Valor máximo do intervalo |
+| `step` | `number` | `1` | Não | Incremento aplicado a cada movimento do thumb |
+| `minValueLabel` | `string` | `undefined` | Não | Label exibido abaixo do valor mínimo |
+| `maxValueLabel` | `string` | `undefined` | Não | Label exibido abaixo do valor máximo |
+| `disabled` | `boolean` | `false` | Não | Desabilita a interação do usuário |
+| `hiddenThumb` | `boolean` | `false` | Não | Oculta visualmente o thumb (exibe apenas a barra de progresso) |
+| `tabindex` | `number` | `0` | Não | Ordem de tabulação do elemento |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `valueChange` | `EventEmitter<number \| [number, number]>` | Emitido quando o valor é alterado pelo usuário |
+
+## Exemplos
+
+### Slider simples com labels
+
+```html
+<s-slider
+  [(ngModel)]="populacao"
+  [min]="0"
+  [max]="220"
+  [step]="5"
+  minValueLabel="0M"
+  maxValueLabel="220M"
+  (valueChange)="onMudanca($event)"
+></s-slider>
+```
+
+### Slider de intervalo
+
+```html
+<s-slider
+  [(ngModel)]="faixaTemperatura"
+  [multiple]="true"
+  [min]="-20"
+  [max]="50"
+  [step]="1"
+  minValueLabel="-20°C"
+  maxValueLabel="50°C"
+></s-slider>
+```
+
+### Integração com Reactive Forms
+
+```html
+<form [formGroup]="form">
+  <s-slider
+    formControlName="desconto"
+    [min]="0"
+    [max]="100"
+    [step]="5"
+    minValueLabel="0%"
+    maxValueLabel="100%"
+  ></s-slider>
+</form>
+```
+
+### Slider desabilitado (somente leitura)
+
+```html
+<s-slider [value]="45" [min]="0" [max]="100" [disabled]="true"></s-slider>
+```
+
+### Apenas barra de progresso (sem thumb)
+
+```html
+<s-slider [value]="65" [min]="0" [max]="100" [hiddenThumb]="true"></s-slider>
+```
+
+## Acessibilidade
+
+- Navegação por teclado: `ArrowLeft`/`ArrowRight` para decrementar/incrementar o valor em `step` unidades
+- No modo de intervalo (`multiple`), as setas movem o intervalo inteiro mantendo a largura
+- O atributo `tabindex` controla a ordem de tabulação
+- Tooltips sobre os thumbs exibem os valores atuais visualmente
+
+## Componentes relacionados
+
+- [`NumberInput`](../number-input/README.md) — entrada numérica precisa com campo de texto

package/speech-recognition/README.md

@@ -0,0 +1,104 @@
+# SpeechRecognition
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Componente de reconhecimento de voz que integra a Web Speech API para transcrever a fala do usuário em texto, inserida diretamente em um `<textarea>` fornecido. Suporta também text-to-speech para leitura em voz alta do conteúdo do campo.
+
+> **Nota:** Este componente é utilizado internamente pelo `TextAreaComponent` quando `speechRecognition: true`. Para uso em campos de texto simples, prefira o `TextAreaComponent`.
+
+## Quando usar
+
+- Campos de texto onde o usuário pode preferir ditar em vez de digitar
+- Acessibilidade para usuários com dificuldade de digitação
+- Formulários de observações ou descrições longas
+- Ditado de textos longos em múltiplas sessões (`keepContext: true`)
+
+## Quando não usar
+
+- Ambientes sem suporte à Web Speech API (Firefox, Safari) — o componente não renderiza nesses browsers
+- Campos de texto curtos onde a digitação é mais eficiente
+- Contextos sem acesso ao microfone do dispositivo
+
+## Instalação
+
+```typescript
+import { SpeechRecognitionModule } from '@seniorsistemas/angular-components/speech-recognition';
+
+@NgModule({ imports: [SpeechRecognitionModule] })
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<textarea #meuTextArea rows="5" placeholder="Digite ou use o microfone..."></textarea>
+<s-speech-recognition
+  [textAreaElement]="meuTextArea"
+  (recognizedText)="onTextoReconhecido($event)"
+></s-speech-recognition>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `textAreaElement` | `HTMLTextAreaElement` | — | Sim | Referência ao elemento `<textarea>` nativo que receberá o texto transcrito |
+| `keepContext` | `boolean` | `false` | Não | Quando `true`, o texto reconhecido é adicionado ao texto existente em vez de substituí-lo |
+| `speechRecognitionPlaceholder` | `string` | `''` | Não | Placeholder exibido no textarea durante o reconhecimento de voz |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `recognizedText` | `EventEmitter<string>` | Emitido quando o reconhecimento é concluído e aprovado pelo usuário. Emite o texto transcrito |
+
+## Exemplos
+
+### Uso padrão com textarea
+
+```html
+<div style="display: flex; align-items: flex-start; gap: 8px;">
+  <textarea
+    #textAreaRef
+    rows="5"
+    placeholder="Digite ou use o microfone..."
+    style="flex: 1;"
+  ></textarea>
+  <s-speech-recognition
+    [textAreaElement]="textAreaRef"
+    [keepContext]="false"
+    speechRecognitionPlaceholder="Ouvindo..."
+    (recognizedText)="onReconhecido($event)"
+  ></s-speech-recognition>
+</div>
+```
+
+### Ditado acumulativo (keepContext)
+
+```html
+<div style="display: flex; align-items: flex-start; gap: 8px;">
+  <textarea
+    #textAreaRef
+    rows="5"
+    placeholder="Cada reconhecimento adiciona ao texto existente..."
+    style="flex: 1;"
+  ></textarea>
+  <s-speech-recognition
+    [textAreaElement]="textAreaRef"
+    [keepContext]="true"
+  ></s-speech-recognition>
+</div>
+```
+
+## Acessibilidade
+
+- Requer suporte do browser à Web Speech API (compatível com Chrome e Edge)
+- Ao iniciar o reconhecimento, o textarea é bloqueado para edição até o usuário aprovar ou descartar o texto reconhecido
+- Após o reconhecimento, botões de **Aprovar** e **Descartar** são exibidos, permitindo confirmação antes de aplicar o texto
+- O botão de text-to-speech lê o conteúdo atual do textarea em voz alta, com controles de velocidade (0.5x, 1x, 1.5x, 2x)
+
+## Componentes relacionados
+
+- [`TextArea`](../text-area/README.md) — área de texto com Speech Recognition integrado via prop `speechRecognition`

package/split-button/README.md

@@ -0,0 +1,126 @@
+# SplitButton
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Botão composto com ação principal e dropdown de opções adicionais. Ao clicar no botão principal emite `buttonClicked`; ao clicar no ícone de seta abre ou fecha o dropdown com a lista de `options`.
+
+## Quando usar
+
+- Ação dominante (ex.: Adicionar) com variantes relacionadas (Atualizar, Alterar, Remover)
+- Toolbars com uma ação principal e ações secundárias no mesmo botão
+- Exportação de dados em múltiplos formatos (PDF, Excel, CSV)
+
+## Quando não usar
+
+- Todas as ações têm igual relevância — prefira múltiplos botões separados
+- Há uma única ação — prefira um `Button` simples
+- As ações secundárias são navigacionais — prefira `TieredMenu` separado
+
+## Instalação
+
+```typescript
+import { SplitButtonModule } from '@seniorsistemas/angular-components/split-button';
+
+@NgModule({ imports: [SplitButtonModule] })
+export class MeuModule {}
+```
+
+## Uso básico
+
+```html
+<s-split-button
+  label="Adicionar"
+  iconClass="far fa-plus"
+  [options]="opcoes"
+  (buttonClicked)="onAdicionar()"
+/>
+```
+
+## API
+
+### Inputs
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `label` | `string` | — | Sim | Rótulo do botão principal |
+| `iconClass` | `string` | — | Sim | Classe Font Awesome do ícone exibido no botão principal |
+| `options` | `SplitButtonOption[]` | — | Sim | Lista de opções exibidas no dropdown |
+| `type` | `SplitButtonType` | `'primary'` | Não | Estilo visual do botão: `'primary'`, `'secondary'` ou `'default'` |
+| `disabled` | `boolean` | `false` | Não | Desabilita o botão principal e o dropdown |
+
+### Outputs
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `buttonClicked` | `EventEmitter<void>` | Emitido quando o usuário clica no botão principal (não no dropdown) |
+
+### Tipos
+
+```typescript
+interface SplitButtonOption {
+  title: string;       // Texto exibido no dropdown
+  action: () => void;  // Função executada ao clicar na opção
+}
+
+type SplitButtonType = 'primary' | 'secondary' | 'default';
+```
+
+## Exemplos
+
+### Botão primário com operações CRUD
+
+```html
+<s-split-button
+  label="Adicionar"
+  iconClass="far fa-plus"
+  type="primary"
+  [options]="opcoesCrud"
+  (buttonClicked)="onAdicionar()"
+></s-split-button>
+```
+
+```typescript
+opcoesCrud: SplitButtonOption[] = [
+  { title: 'Atualizar', action: () => this.atualizar() },
+  { title: 'Alterar', action: () => this.alterar() },
+  { title: 'Remover', action: () => this.remover() },
+];
+```
+
+### Exportação em múltiplos formatos
+
+```html
+<s-split-button
+  label="Exportar"
+  iconClass="fa fa-download"
+  type="primary"
+  [options]="opcoesExportar"
+></s-split-button>
+```
+
+```typescript
+opcoesExportar: SplitButtonOption[] = [
+  { title: 'Exportar PDF', action: () => this.exportarPDF() },
+  { title: 'Exportar Excel', action: () => this.exportarExcel() },
+  { title: 'Exportar CSV', action: () => this.exportarCSV() },
+];
+```
+
+### Visão geral dos tipos
+
+```html
+<s-split-button label="Adicionar" iconClass="far fa-plus" type="primary" [options]="opcoes"></s-split-button>
+<s-split-button label="Alterar" iconClass="far fa-pencil" type="secondary" [options]="opcoes"></s-split-button>
+<s-split-button label="Remover" iconClass="far fa-trash" type="default" [options]="opcoes"></s-split-button>
+```
+
+## Acessibilidade
+
+- O botão principal é focável via teclado e pode ser acionado com `Enter` ou `Espaço`
+- Clicar fora do componente fecha o dropdown automaticamente via `HostListener`
+- O estado desabilitado impede interação tanto no botão principal quanto no dropdown e nas opções
+
+## Componentes relacionados
+
+- [`Button`](../button/README.md) — botão de ação individual com suporte a menu via `menuOptions`
+- [`TieredMenu`](../tiered-menu/README.md) — menu dropdown com submenus aninhados

package/spotlight/README.md

@@ -0,0 +1,200 @@
+# Spotlight
+
+![Status](https://img.shields.io/badge/status-stable-brightgreen)
+
+Sistema de destaque guiado que combina máscara de fundo semitransparente com um popover informativo posicionado ao lado de um elemento alvo. Suporta destaque simples (passo único) e tours guiados com múltiplos passos e navegação sequencial.
+
+## Quando usar
+
+- Onboarding de novos usuários apresentando funcionalidades pela primeira vez
+- Destacar um campo ou ação importante em resposta a uma regra de negócio
+- Tours guiados para apresentar uma tela complexa em sequência lógica
+- Dicas contextuais disparadas por clique ou por lógica da aplicação
+
+## Quando não usar
+
+- Ajuda contextual estática sempre visível — prefira `HelpPopover`
+- Dicas simples ao passar o mouse — prefira `Tooltip`
+- Mensagens de alerta críticas que exigem uma ação imediata — prefira `Dialog`
+
+## Instalação
+
+```typescript
+import {
+  SpotlightTourService,
+  SpotlightStepDirective,
+} from '@seniorsistemas/angular-components/spotlight';
+
+@Component({
+  standalone: true,
+  imports: [SpotlightStepDirective],
+  providers: [SpotlightTourService],
+})
+export class MeuComponent {
+  private readonly tourService = inject(SpotlightTourService);
+}
+```
+
+## Uso básico
+
+```html
+<!-- Marque os elementos alvo com a diretiva -->
+<button [sSpotlightStep]="'meu-botao'">Clique aqui</button>
+```
+
+```typescript
+// Destaque simples em um elemento
+this.tourService.spotlight('meu-botao', {
+  title: 'Novo recurso',
+  message: 'Este botão agora tem uma função adicional.',
+  position: 'bottom-center',
+});
+
+// Tour guiado com múltiplos passos
+this.tourService.start([
+  { stepId: 'passo-1', title: 'Início', message: 'Descrição do passo 1' },
+  { stepId: 'passo-2', title: 'Configuração', message: 'Descrição do passo 2' },
+]);
+```
+
+## API
+
+### Diretiva `[sSpotlightStep]`
+
+| Propriedade | Tipo | Obrigatório | Descrição |
+|-------------|------|:-----------:|-----------|
+| `sSpotlightStep` | `string` | Sim | ID único do passo do tour ao qual este elemento está associado |
+
+### SpotlightComponent (popover isolado)
+
+| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
+|-------------|------|--------|:-----------:|-----------|
+| `title` | `string \| TemplateRef<any>` | `''` | Não | Título exibido no cabeçalho do popover |
+| `message` | `string \| TemplateRef<any>` | `undefined` | Não | Mensagem principal do popover |
+| `content` | `TemplateRef<any> \| null` | `null` | Não | Template para área de mídia/conteúdo customizado |
+| `position` | `SpotlightPosition` | `'bottom-center'` | Não | Posição do popover em relação ao elemento alvo |
+| `currentStep` | `number` | `1` | Não | Número do passo atual (1-based) |
+| `totalSteps` | `number` | `1` | Não | Total de passos do tour |
+| `showDoNotShowAgain` | `boolean` | `true` | Não | Exibe o checkbox "Não mostrar novamente" (apenas em modo simples) |
+| `actions` | `SpotlightStepAction[]` | `[]` | Não | Botões adicionais no rodapé do popover |
+| `arrowOffsetPx` | `number \| null` | `null` | Não | Deslocamento em pixels para posicionar a seta manualmente |
+
+### Outputs do SpotlightComponent
+
+| Evento | Tipo | Descrição |
+|--------|------|-----------|
+| `closed` | `OutputEmitterRef<void>` | Emitido ao clicar no botão de fechar (X) |
+| `next` | `OutputEmitterRef<void>` | Emitido ao clicar em "Próximo" |
+| `previous` | `OutputEmitterRef<void>` | Emitido ao clicar em "Voltar" |
+| `understand` | `OutputEmitterRef<void>` | Emitido ao clicar em "Entendido" (modo simples) |
+
+### Tipos
+
+```typescript
+type SpotlightPosition =
+  | 'top-start' | 'top-center' | 'top-end'
+  | 'right-start' | 'right-center' | 'right-end'
+  | 'bottom-start' | 'bottom-center' | 'bottom-end'
+  | 'left-start' | 'left-center' | 'left-end';
+
+interface SpotlightStep {
+  stepId: string;
+  title?: string | TemplateRef<any>;
+  message?: string | TemplateRef<any>;
+  position?: SpotlightPosition;
+  showDoNotShowAgain?: boolean;
+  dismissible?: boolean;
+  actions?: SpotlightStepAction[];
+}
+
+interface SpotlightStepAction {
+  label: string;
+  handler: () => void;
+}
+```
+
+### SpotlightTourService — API pública
+
+| Método/Propriedade | Descrição |
+|---|---|
+| `spotlight(stepId, config)` | Exibe destaque simples em um elemento |
+| `start(steps)` | Inicia tour guiado com múltiplos passos |
+| `next()` | Avança para o próximo passo |
+| `previous()` | Retorna ao passo anterior |
+| `stop(event?)` | Encerra o tour |
+| `isActive` | Signal: indica se o tour está ativo |
+| `currentIndex` | Signal: índice (0-based) do passo atual |
+| `totalSteps` | Signal computado: total de passos |
+| `stopped$` | Observable emitido ao encerrar o tour |
+| `stepChanged$` | Observable emitido ao mudar de passo |
+
+## Exemplos
+
+### Destaque simples
+
+```typescript
+this.tourService.spotlight('campo-obrigatorio', {
+  title: 'Campo obrigatório',
+  message: 'Este campo deve ser preenchido antes de continuar.',
+  position: 'bottom-center',
+  showDoNotShowAgain: true,
+  dismissible: true,
+});
+```
+
+### Tour guiado com 3 passos
+
+```typescript
+this.tourService.start([
+  {
+    stepId: 'btn-novo',
+    title: 'Passo 1 — Criar',
+    message: 'Use este botão para criar um novo registro.',
+    position: 'bottom-center',
+  },
+  {
+    stepId: 'filtro-data',
+    title: 'Passo 2 — Filtrar',
+    message: 'Filtre por período usando este campo de data.',
+    position: 'bottom-start',
+  },
+  {
+    stepId: 'btn-exportar',
+    title: 'Passo 3 — Exportar',
+    message: 'Exporte os dados filtrados em diferentes formatos.',
+    position: 'top-center',
+  },
+]);
+
+// Reagir ao encerramento
+this.tourService.stopped$.subscribe(event => {
+  if (event.doNotShowAgain) {
+    // salvar preferência do usuário
+  }
+});
+```
+
+### Spotlight bloqueado (não pode ser fechado pelo backdrop)
+
+```typescript
+this.tourService.spotlight('elemento-alvo', {
+  title: 'Ação obrigatória',
+  message: 'Você deve completar esta ação antes de continuar.',
+  position: 'bottom-center',
+  dismissible: false,
+  showDoNotShowAgain: false,
+});
+```
+
+## Acessibilidade
+
+- O popover utiliza `role="dialog"` com `aria-labelledby` e `aria-describedby` referenciando título e mensagem
+- O foco é gerenciado via CDK FocusTrap: ao abrir, o foco vai para o primeiro elemento interativo do popover
+- Pressionar `Escape` fecha o spotlight quando `dismissible !== false`
+- A posição do popover se ajusta automaticamente quando há pouco espaço na viewport
+- Suporte completo à navegação por teclado (Tab, Shift+Tab, Enter, Escape)
+
+## Componentes relacionados
+
+- [`HelpPopover`](../help-popover/README.md) — popover de ajuda contextual fixo em elementos de formulário
+- [`Tooltip`](../tooltip/README.md) — dica de conteúdo simples ao passar o mouse