@seniorsistemas/angular-components 19.2.0 → 19.3.0

package/spotlight/README.md

@@ -0,0 +1,311 @@
+# Spotlight
+
+## Descrição
+
+O Spotlight é uma biblioteca para criação de **tours guiados** (onboarding com múltiplos passos) e **destaques simples** (dicas únicas sobre um elemento). O posicionamento do popover é gerenciado automaticamente pelo Angular CDK, com fallbacks inteligentes para manter o popover sempre visível.
+
+Dois modos de operação:
+
+- **Tour**: sequência de passos com navegação Próximo / Voltar / Concluído, contador de progresso, focus trap e bloqueio de scroll.
+- **Destaque simples**: popover único com botão "Entendi" e opção de "Não mostrar novamente".
+
+## Instalação
+
+```bash
+npm install @seniorsistemas/angular-components/spotlight
+```
+
+## Conceitos
+
+### Diretiva `sSpotlightStep`
+
+Registra um elemento do DOM como alvo de um passo do tour. Deve ser aplicada ao elemento que receberá o destaque.
+
+```html
+<button sSpotlightStep="meu-botao">Salvar</button>
+```
+
+O valor do atributo é o `stepId`, que deve corresponder ao `stepId` definido nos passos do tour.
+Quando o valor do binding muda dinamicamente, a diretiva desregistra o ID anterior e registra o novo automaticamente.
+
+### `SpotlightTourService`
+
+Serviço singleton que controla o estado do tour. Injete-o no componente que inicia o tour.
+
+---
+
+## Tour (múltiplos passos)
+
+### 1. Marque os elementos no template
+
+```html
+<input sSpotlightStep="produto-nome" ... />
+<select sSpotlightStep="produto-categoria" ... />
+<button sSpotlightStep="salvar-btn">Salvar</button>
+```
+
+### 2. Inicie o tour pelo serviço
+
+```typescript
+import { SpotlightTourService, SpotlightStep } from '@seniorsistemas/angular-components/spotlight';
+
+@Component({ ... })
+export class MeuComponent {
+  private readonly tourService = inject(SpotlightTourService);
+
+  private readonly passos: SpotlightStep[] = [
+    {
+      stepId: 'produto-nome',
+      title: 'Nome do produto',
+      message: 'Informe o nome completo do produto.',
+      position: 'bottom-center',
+    },
+    {
+      stepId: 'produto-categoria',
+      title: 'Categoria',
+      message: 'Selecione a categoria correta.',
+      position: 'bottom-end',
+      beforeNext: () => {
+        // Executado antes de avançar — útil para trocar abas, expandir seções, etc.
+        this.activeTab.set('detalhes');
+      },
+    },
+    {
+      stepId: 'salvar-btn',
+      title: 'Salvar',
+      message: 'Clique aqui para salvar as alterações.',
+      position: 'top-center',
+    },
+  ];
+
+  public iniciarTour(): void {
+    this.tourService.start(this.passos);
+  }
+}
+```
+
+### 3. Reaja aos eventos do tour
+
+```typescript
+private readonly destroyRef = inject(DestroyRef);
+
+public constructor() {
+  this.tourService.stopped$
+    .pipe(takeUntilDestroyed(this.destroyRef))
+    .subscribe((event) => {
+      // Salve o estado para persistência
+      localStorage.setItem('tour-onboarding', JSON.stringify({
+        reason: event.reason,           // 'completed' | 'interrupted'
+        doNotShowAgain: event.doNotShowAgain,
+        stepIndex: event.stepIndex,
+      }));
+    });
+}
+```
+
+---
+
+## Destaque Simples
+
+Use `tourService.spotlight()` para exibir um destaque em um único elemento.
+
+```html
+<div sSpotlightStep="novo-recurso">...</div>
+```
+
+```typescript
+import { SpotlightTourService, SpotlightConfig } from '@seniorsistemas/angular-components/spotlight';
+
+@Component({ ... })
+export class MeuComponent {
+  private readonly tourService = inject(SpotlightTourService);
+
+  public mostrarDica(): void {
+    const config: SpotlightConfig = {
+      title: 'Novidade!',
+      message: 'Este recurso foi adicionado recentemente.',
+      position: 'bottom-center',
+      // showDoNotShowAgain é true por padrão — passe false para suprimir o checkbox
+      dismissible: true,
+    };
+
+    this.tourService.spotlight('novo-recurso', config);
+  }
+}
+```
+
+Ao encerrar, `stopped$` emite com `reason: 'dismissed'` (usuário fechou) ou `reason: 'completed'` (clicou em "Entendi"). Quando `doNotShowAgain` é `true`, salve essa preferência para não exibir novamente.
+
+---
+
+## `SpotlightStep`
+
+| Propriedade | Tipo | Obrigatório | Descrição |
+|---|---|---|---|
+| `stepId` | `string` | ✓ | Identificador único do passo. Deve corresponder ao valor do `sSpotlightStep` no template. |
+| `title` | `string \| TemplateRef<any>` | ✓ | Título do popover (máx. recomendado: 30 caracteres). |
+| `message` | `string \| TemplateRef<any>` | ✓ | Texto descritivo (máx. recomendado: 75 caracteres). |
+| `position` | `SpotlightPosition` | — | Posição preferida do popover. Padrão: `'bottom-center'`. |
+| `content` | `TemplateRef<any> \| null` | — | Conteúdo visual customizado (imagem, gif, vídeo) exibido acima da mensagem. |
+| `actions` | `SpotlightStepAction[]` | — | Botões de ação customizados exibidos antes dos botões de navegação. |
+| `showBackdrop` | `boolean` | — | Exibe o backdrop escurecido ao redor do elemento destacado. Padrão: `true`. |
+| `dismissible` | `boolean` | — | Permite fechar o spotlight clicando fora ou pressionando Escape. Padrão: `true`. |
+| `beforeNext` | `() => void \| Promise<void>` | — | Callback executado antes de avançar para o próximo passo. Suporta async/await. |
+| `beforePrevious` | `() => void \| Promise<void>` | — | Callback executado antes de voltar ao passo anterior. Suporta async/await. |
+
+## `SpotlightConfig`
+
+Equivalente ao `SpotlightStep` sem `stepId`, `beforeNext` e `beforePrevious`. Usado exclusivamente com `tourService.spotlight()`. Inclui a propriedade adicional:
+
+| Propriedade | Tipo | Descrição |
+|---|---|---|
+| `showDoNotShowAgain` | `boolean` | Exibe o checkbox "Não mostrar novamente". Padrão: `true`. Passe `false` para suprimir. |
+
+## `SpotlightStepAction`
+
+| Propriedade | Tipo | Descrição |
+|---|---|---|
+| `label` | `string` | Texto do botão. |
+| `handler` | `() => void` | Função executada ao clicar no botão. |
+
+---
+
+## `SpotlightTourService`
+
+### Propriedades
+
+| Propriedade | Tipo | Descrição |
+|---|---|---|
+| `isActive` | `Signal<boolean>` | `true` enquanto o tour estiver ativo. |
+| `currentStep` | `Signal<SpotlightStep \| undefined>` | Passo atualmente exibido. |
+| `currentIndex` | `Signal<number>` | Índice do passo atual (base 0). |
+| `totalSteps` | `Signal<number>` | Total de passos do tour. |
+| `stopped$` | `Observable<SpotlightStopEvent>` | Emite quando o tour é encerrado. |
+| `stepChanged$` | `Observable<SpotlightStepChangedEvent>` | Emite ao mudar de passo (incluindo o primeiro). |
+
+### Métodos
+
+| Método | Descrição |
+|---|---|
+| `start(steps: SpotlightStep[])` | Inicia o tour com a lista de passos fornecida. Ignora arrays vazios. Se houver um tour ativo, encerra-o (emitindo `stopped$`) antes de iniciar o novo. |
+| `spotlight(stepId, config: SpotlightConfig)` | Exibe um destaque simples em um único elemento. |
+| `next(doNotShowAgain?: boolean)` | Avança para o próximo passo ou conclui o tour. |
+| `previous()` | Volta ao passo anterior. |
+| `stop(event?: Partial<SpotlightStopEvent>)` | Encerra o tour programaticamente. |
+| `registerElement(stepId, el)` | Registra um elemento (usado internamente pela diretiva). |
+| `unregisterElement(stepId)` | Remove o registro de um elemento. |
+| `getElement(stepId)` | Retorna o `ElementRef` registrado para o `stepId`. |
+
+---
+
+## Eventos (`SpotlightStopEvent`)
+
+Emitido por `stopped$` ao encerrar o tour.
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `reason` | `SpotlightStopReason` | Razão do encerramento. |
+| `doNotShowAgain` | `boolean` | `true` se o usuário marcou "Não mostrar novamente". |
+| `stepId` | `string` | `stepId` do passo em que o tour foi encerrado. |
+| `stepIndex` | `number` | Índice (base 0) do passo em que o tour foi encerrado. |
+| `totalSteps` | `number` | Total de passos do tour. |
+
+### `SpotlightStopReason`
+
+| Valor | Quando ocorre | Comportamento recomendado |
+|---|---|---|
+| `'completed'` | Usuário clicou em "Concluído" ou "Entendi" | Nunca reexibir |
+| `'interrupted'` | Usuário fechou o tour antes de concluir (X, Escape, clique fora) | Reexibir na próxima sessão |
+| `'dismissed'` | Usuário fechou um destaque simples | Reexibir após cooldown |
+
+### `SpotlightStepChangedEvent`
+
+Emitido por `stepChanged$` a cada mudança de passo.
+
+| Campo | Tipo | Descrição |
+|---|---|---|
+| `stepId` | `string` | `stepId` do novo passo. |
+| `stepIndex` | `number` | Índice (base 0) do novo passo. |
+| `totalSteps` | `number` | Total de passos do tour. |
+
+---
+
+## Posições Disponíveis (`SpotlightPosition`)
+
+| Valor | Descrição |
+|---|---|
+| `'top-start'` | Acima do elemento, alinhado à esquerda |
+| `'top-center'` | Acima do elemento, centralizado |
+| `'top-end'` | Acima do elemento, alinhado à direita |
+| `'bottom-start'` | Abaixo do elemento, alinhado à esquerda |
+| `'bottom-center'` | Abaixo do elemento, centralizado |
+| `'bottom-end'` | Abaixo do elemento, alinhado à direita |
+| `'left-start'` | À esquerda do elemento, alinhado ao topo |
+| `'left-center'` | À esquerda do elemento, centralizado |
+| `'left-end'` | À esquerda do elemento, alinhado à base |
+| `'right-start'` | À direita do elemento, alinhado ao topo |
+| `'right-center'` | À direita do elemento, centralizado |
+| `'right-end'` | À direita do elemento, alinhado à base |
+
+> O CDK ajusta automaticamente a posição quando não há espaço suficiente, garantindo que o popover sempre permaneça visível.
+
+---
+
+## Persistência
+
+A persistência do estado (se o tour já foi visto, preferência "Não mostrar novamente", etc.) é responsabilidade do produto consumidor. Use os dados emitidos por `stopped$` para implementar a estratégia adequada:
+
+```typescript
+this.tourService.stopped$.subscribe((event) => {
+  const estado = {
+    reason: event.reason,
+    doNotShowAgain: event.doNotShowAgain,
+    contentVersion: 'v2', // versão do conteúdo do tour, controlada pelo produto
+  };
+  localStorage.setItem('tour-onboarding', JSON.stringify(estado));
+});
+
+// Na inicialização:
+const salvo = JSON.parse(localStorage.getItem('tour-onboarding') ?? 'null');
+const deveExibir =
+  !salvo ||
+  salvo.contentVersion !== 'v2' ||          // novo conteúdo → reexibir
+  salvo.reason === 'interrupted';            // não concluiu → reexibir
+
+if (deveExibir && !salvo?.doNotShowAgain) {
+  // Chamar tourService.start(passos) no momento adequado
+}
+```
+
+---
+
+## Telemetria
+
+Use os observables do serviço para enviar eventos ao seu sistema de analytics:
+
+```typescript
+// Tour iniciado (step 0)
+this.tourService.stepChanged$
+  .pipe(filter((e) => e.stepIndex === 0 && e.totalSteps > 1))
+  .subscribe(() => analytics.track('tour_viewed'));
+
+// Tour concluído
+this.tourService.stopped$
+  .pipe(filter((e) => e.reason === 'completed' && e.totalSteps > 1))
+  .subscribe(() => analytics.track('tour_completed'));
+
+// Tour interrompido
+this.tourService.stopped$
+  .pipe(filter((e) => e.reason === 'interrupted'))
+  .subscribe(() => analytics.track('tour_interrupted'));
+
+// Destaque simples fechado
+this.tourService.stopped$
+  .pipe(filter((e) => e.reason === 'dismissed'))
+  .subscribe(() => analytics.track('spotlight_dismissed'));
+
+// "Não mostrar novamente" marcado
+this.tourService.stopped$
+  .pipe(filter((e) => e.doNotShowAgain))
+  .subscribe(() => analytics.track('spotlight_do_not_show_again_checked'));
+```

package/spotlight/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generated bundle index. Do not edit.
+ */
+/// <amd-module name="@seniorsistemas/angular-components/spotlight" />
+export * from './public-api';

package/spotlight/lib/spotlight/spotlight-overlay/spotlight-overlay.component.d.ts

@@ -0,0 +1,70 @@
+import { OnDestroy, OnInit } from '@angular/core';
+import { SpotlightStep } from '../types/spotlight-step';
+import * as i0 from "@angular/core";
+export declare class SpotlightOverlayComponent implements OnInit, OnDestroy {
+    private readonly tourService;
+    private readonly destroyRef;
+    private readonly zone;
+    private readonly cdkOverlay;
+    private readonly environmentInjector;
+    private readonly focusTrapFactory;
+    /** @internal */
+    readonly isActive: import("@angular/core").Signal<boolean>;
+    /** @internal */
+    readonly currentStep: import("@angular/core").Signal<(SpotlightStep & {
+        showDoNotShowAgain?: boolean;
+    }) | undefined>;
+    /** @internal */
+    readonly currentIndex: import("@angular/core").Signal<number>;
+    /** @internal */
+    readonly totalSteps: import("@angular/core").Signal<number>;
+    /** @internal*/
+    readonly targetRect: import("@angular/core").WritableSignal<DOMRect | null>;
+    /** @internal */
+    readonly topMaskStyle: import("@angular/core").Signal<Record<string, string>>;
+    /** @internal */
+    readonly leftMaskStyle: import("@angular/core").Signal<Record<string, string>>;
+    /** @internal */
+    readonly rightMaskStyle: import("@angular/core").Signal<Record<string, string>>;
+    /** @internal */
+    readonly bottomMaskStyle: import("@angular/core").Signal<Record<string, string>>;
+    /** @internal */
+    readonly transparentBlockerStyle: import("@angular/core").Signal<Record<string, string>>;
+    private resizeObserver;
+    private popoverOverlayRef;
+    private popoverComponentRef;
+    private popoverSubs;
+    private focusTrap;
+    private previouslyFocusedElement;
+    constructor();
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    /** @internal */
+    onNext(): void;
+    /** @internal */
+    onPrevious(): void;
+    /** @internal */
+    onClose(): void;
+    /** @internal */
+    onDismiss(): void;
+    private updatePopoverOverlay;
+    private setPopoverZIndex;
+    private attachPopoverPortal;
+    private updatePopoverInputs;
+    private scheduleSync;
+    private activateTourMode;
+    /**
+     * After a step change, moves focus back to the first tabbable element inside the
+     * popover so the user does not lose keyboard position.
+     * No-op when there is no active focus trap (simple spotlight mode).
+     */
+    private scheduleFocusTrapRefocus;
+    private syncDirectionAndArrow;
+    private destroyPopoverOverlay;
+    private updateTargetRect;
+    private refreshRect;
+    private observeElement;
+    private disconnectResizeObserver;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightOverlayComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpotlightOverlayComponent, "s-spotlight-overlay", never, {}, {}, never, never, true, never>;
+}

package/spotlight/lib/spotlight/spotlight-step.directive.d.ts

@@ -0,0 +1,28 @@
+import { OnDestroy } from '@angular/core';
+import * as i0 from "@angular/core";
+/**
+ * Diretiva que registra um elemento do DOM como alvo de um passo do Spotlight Tour.
+ *
+ * Aplique a diretiva em qualquer elemento e forneça um ID único que corresponda
+ * ao `stepId` configurado no `SpotlightTourService`. O elemento será automaticamente
+ * registrado ao ser criado e atualizado caso o ID mude dinamicamente.
+ *
+ * @example
+ * ```html
+ * <button [sSpotlightStep]="'meu-botao'">Clique aqui</button>
+ * ```
+ */
+export declare class SpotlightStepDirective implements OnDestroy {
+    /**
+     * ID único do passo do tour ao qual este elemento está associado.
+     * Deve corresponder ao `stepId` definido em `SpotlightStep`.
+     */
+    sSpotlightStep: import("@angular/core").InputSignal<string>;
+    private readonly el;
+    private readonly tourService;
+    private currentId;
+    constructor();
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightStepDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<SpotlightStepDirective, "[sSpotlightStep]", never, { "sSpotlightStep": { "alias": "sSpotlightStep"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}

package/spotlight/lib/spotlight/spotlight-tour.service.d.ts

@@ -0,0 +1,146 @@
+import { ElementRef } from '@angular/core';
+import { Observable } from 'rxjs';
+import { SpotlightConfig, SpotlightStep } from './types/spotlight-step';
+import { SpotlightStepChangedEvent, SpotlightStopEvent } from './types/spotlight-stop-event';
+import * as i0 from "@angular/core";
+/** @internal */
+type SpotlightStepInternal = SpotlightStep & {
+    showDoNotShowAgain?: boolean;
+};
+/**
+ * Serviço central do Spotlight Tour.
+ *
+ * Gerencia o estado do tour (passos, índice atual, ativo/inativo), a navegação entre
+ * passos e o registro de elementos do DOM associados a cada `stepId`.
+ *
+ * Use `start()` para iniciar um tour com múltiplos passos ou `spotlight()` para
+ * exibir um destaque simples em um único elemento.
+ *
+ * @example
+ * ```typescript
+ * // Tour com múltiplos passos
+ * this.tourService.start([
+ *   { stepId: 'passo-1', title: 'Título', message: 'Mensagem' },
+ *   { stepId: 'passo-2', title: 'Título', message: 'Mensagem' },
+ * ]);
+ *
+ * // Destaque simples
+ * this.tourService.spotlight('meu-elemento', { title: 'Dica', message: 'Detalhes' });
+ * ```
+ */
+export declare class SpotlightTourService {
+    private readonly overlay;
+    private readonly environmentInjector;
+    private overlayRef;
+    private readonly _steps;
+    private readonly _currentIndex;
+    private readonly _isActive;
+    private readonly _registrationVersion;
+    private readonly _registeredElements;
+    private _pendingDoNotShowAgain;
+    private readonly _stopped$;
+    private readonly _stepChanged$;
+    /** Signal somente-leitura que indica se o tour está ativo no momento. */
+    readonly isActive: import("@angular/core").Signal<boolean>;
+    /** Signal somente-leitura com o índice (0-based) do passo exibido atualmente. */
+    readonly currentIndex: import("@angular/core").Signal<number>;
+    /** Signal computado com o total de passos do tour em andamento. */
+    readonly totalSteps: import("@angular/core").Signal<number>;
+    /** Signal computado com os dados do passo atualmente exibido. */
+    readonly currentStep: import("@angular/core").Signal<SpotlightStepInternal | undefined>;
+    /**
+     * Observable emitido quando o tour é encerrado, seja por conclusão, interrupção
+     * ou descarte. Carrega um `SpotlightStopEvent` com o motivo e o estado final.
+     */
+    readonly stopped$: Observable<SpotlightStopEvent>;
+    /**
+     * Observable emitido sempre que o passo exibido muda, incluindo o início do tour.
+     * Carrega um `SpotlightStepChangedEvent` com o `stepId` e o índice do novo passo.
+     */
+    readonly stepChanged$: Observable<SpotlightStepChangedEvent>;
+    /**
+     * Signal somente-leitura incrementado a cada chamada de `registerElement` ou
+     * `unregisterElement`. Permite que outros componentes reajam a mudanças no
+     * registro de elementos sem polling.
+     */
+    readonly registrationVersion: import("@angular/core").Signal<number>;
+    /**
+     * Inicia um tour com a lista de passos fornecida.
+     *
+     * O tour começa pelo primeiro passo da lista. Emite `stepChanged$` para o passo inicial.
+     * Se `steps` for um array vazio, o método não faz nada.
+     * Se já houver um tour ativo, ele é encerrado (emitindo `stopped$` com `reason: 'interrupted'`)
+     * antes de o novo tour começar.
+     *
+     * @param steps Lista de passos a percorrer em ordem.
+     */
+    start(steps: SpotlightStep[]): void;
+    /**
+     * Exibe um destaque simples (passo único) no elemento identificado por `stepId`.
+     *
+     * Equivalente a chamar `start()` com um array de um único passo.
+     * O checkbox "Não mostrar novamente" é exibido por padrão (`showDoNotShowAgain: true`);
+     * passe `showDoNotShowAgain: false` em `config` para suprimi-lo.
+     *
+     * @param stepId ID do elemento registrado via `sSpotlightStep` ou `registerElement`.
+     * @param config Configuração visual e comportamental do destaque.
+     */
+    spotlight(stepId: string, config: SpotlightConfig): void;
+    /**
+     * Avança para o próximo passo do tour.
+     *
+     * Se o passo atual definir `beforeNext`, aguarda sua resolução antes de avançar.
+     * No último passo, encerra o tour com `reason: 'completed'`.
+     *
+     * @param doNotShowAgain Quando `true`, o evento `stopped$` será emitido com
+     *   `doNotShowAgain: true` ao concluir o tour. Relevante apenas no último passo.
+     */
+    next(doNotShowAgain?: boolean): void;
+    /**
+     * Retorna ao passo anterior do tour.
+     *
+     * Se o passo atual definir `beforePrevious`, aguarda sua resolução antes de voltar.
+     * Não faz nada se o tour estiver no primeiro passo.
+     */
+    previous(): void;
+    /**
+     * Encerra o tour imediatamente e emite o evento `stopped$`.
+     *
+     * @param event Dados parciais do evento de parada. Valores não fornecidos são
+     *   preenchidos com os defaults: `reason: 'interrupted'`, `doNotShowAgain: false`
+     *   e o `stepId`/`stepIndex`/`totalSteps` do momento atual.
+     */
+    stop(event?: Partial<SpotlightStopEvent>): void;
+    /**
+     * Registra um elemento do DOM como alvo do passo identificado por `stepId`.
+     *
+     * Normalmente chamado pela diretiva `sSpotlightStep`. Use diretamente apenas
+     * quando precisar registrar elementos criados programaticamente.
+     *
+     * @param stepId ID único do passo ao qual o elemento pertence.
+     * @param el Referência ao elemento do DOM.
+     */
+    registerElement(stepId: string, el: ElementRef): void;
+    /**
+     * Remove o registro do elemento associado a `stepId`.
+     *
+     * Normalmente chamado pela diretiva `sSpotlightStep` no `ngOnDestroy`.
+     *
+     * @param stepId ID do passo cujo elemento deve ser removido.
+     */
+    unregisterElement(stepId: string): void;
+    /**
+     * Retorna o `ElementRef` registrado para o `stepId` informado,
+     * ou `undefined` se nenhum elemento estiver registrado.
+     *
+     * @param stepId ID do passo a buscar.
+     */
+    getElement(stepId: string): ElementRef | undefined;
+    private advance;
+    private retreat;
+    private attachOverlay;
+    private detachOverlay;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightTourService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SpotlightTourService>;
+}
+export {};

package/spotlight/lib/spotlight/spotlight.component.d.ts

@@ -0,0 +1,82 @@
+import { TemplateRef } from '@angular/core';
+import { SpotlightPosition } from './types/spotlight-position';
+import { SpotlightStepAction } from './types/spotlight-step';
+import * as i0 from "@angular/core";
+/**
+ * Componente de popover do Spotlight.
+ *
+ * Exibe o card de destaque com título, mensagem, seta direcional, contador de passos,
+ * botões de navegação e, em modo simples (passo único), o checkbox "não mostrar novamente".
+ *
+ * Este componente é instanciado programaticamente pelo `SpotlightOverlayComponent`
+ * via CDK Overlay. Normalmente não é usado diretamente no template.
+ */
+export declare class SpotlightComponent {
+    /** Título do popover. Aceita string ou `TemplateRef` para conteúdo dinâmico. */
+    title: import("@angular/core").InputSignal<string | TemplateRef<any>>;
+    /** Mensagem principal do popover. Aceita string ou `TemplateRef` para conteúdo dinâmico. */
+    message: import("@angular/core").InputSignal<string | TemplateRef<any> | undefined>;
+    /** Template opcional para área de mídia/conteúdo customizado acima da mensagem. */
+    content: import("@angular/core").InputSignal<TemplateRef<any> | null>;
+    /** Posição do popover em relação ao elemento alvo. @default 'bottom-center' */
+    position: import("@angular/core").InputSignal<SpotlightPosition>;
+    /** Número do passo atual (1-based) exibido no contador. @default 1 */
+    currentStep: import("@angular/core").InputSignal<number>;
+    /** Total de passos do tour, usado no contador e para controle de botões. @default 1 */
+    totalSteps: import("@angular/core").InputSignal<number>;
+    /**
+     * Exibe o checkbox "não mostrar novamente" (apenas em passo único).
+     * Passe `false` para suprimir o checkbox quando não for necessário persistir a preferência.
+     * @default true
+     */
+    showDoNotShowAgain: import("@angular/core").InputSignal<boolean>;
+    /** Lista de botões de ação adicionais exibidos na área de rodapé. */
+    actions: import("@angular/core").InputSignal<SpotlightStepAction[]>;
+    /**
+     * Deslocamento em pixels para posicionar a seta manualmente no eixo principal.
+     * Quando `null`, o alinhamento é controlado pela `position`. @default null
+     */
+    arrowOffsetPx: import("@angular/core").InputSignal<number | null>;
+    /** Emitido ao clicar no botão de fechar (X). */
+    closed: import("@angular/core").OutputEmitterRef<void>;
+    /** Emitido ao clicar em "Próximo". */
+    next: import("@angular/core").OutputEmitterRef<void>;
+    /** Emitido ao clicar em "Voltar". */
+    previous: import("@angular/core").OutputEmitterRef<void>;
+    /** Emitido ao clicar em "Entendido" (modo simples, passo único). */
+    understand: import("@angular/core").OutputEmitterRef<void>;
+    /** Estado atual do checkbox "não mostrar novamente". */
+    isDoNotShowAgainChecked: import("@angular/core").WritableSignal<boolean>;
+    private static instanceCount;
+    /** @internal */
+    protected readonly instanceId: string;
+    /** @internal */
+    readonly titleId: string;
+    /** @internal */
+    readonly descId: string;
+    get titleTemplate(): TemplateRef<any> | null;
+    get titleString(): string;
+    get messageTemplate(): TemplateRef<any> | null;
+    get messageString(): string;
+    get arrowPosition(): SpotlightPosition;
+    get isArrowTop(): boolean;
+    get isArrowBottom(): boolean;
+    get isArrowLeft(): boolean;
+    get isArrowRight(): boolean;
+    get arrowRotation(): string;
+    get arrowAlignmentClass(): string;
+    get arrowPaddingStyle(): Record<string, string>;
+    /** Emite o evento `closed`. Chamado pelo botão de fechar no template. */
+    onClose(): void;
+    /** Emite o evento `next`. Chamado pelo botão "Próximo" no template. */
+    onNext(): void;
+    /** Emite o evento `previous`. Chamado pelo botão "Voltar" no template. */
+    onPrevious(): void;
+    /** Emite o evento `understand`. Chamado pelo botão "Entendido" no template. */
+    onUnderstand(): void;
+    /** Alterna o estado de `isDoNotShowAgainChecked`. */
+    toggleDoNotShowAgain(): void;
+    private getOppositeDirection;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpotlightComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SpotlightComponent, "s-spotlight", never, { "title": { "alias": "title"; "required": false; "isSignal": true; }; "message": { "alias": "message"; "required": false; "isSignal": true; }; "content": { "alias": "content"; "required": false; "isSignal": true; }; "position": { "alias": "position"; "required": false; "isSignal": true; }; "currentStep": { "alias": "currentStep"; "required": false; "isSignal": true; }; "totalSteps": { "alias": "totalSteps"; "required": false; "isSignal": true; }; "showDoNotShowAgain": { "alias": "showDoNotShowAgain"; "required": false; "isSignal": true; }; "actions": { "alias": "actions"; "required": false; "isSignal": true; }; "arrowOffsetPx": { "alias": "arrowOffsetPx"; "required": false; "isSignal": true; }; }, { "closed": "closed"; "next": "next"; "previous": "previous"; "understand": "understand"; }, never, never, true, never>;
+}

package/spotlight/lib/spotlight/types/spotlight-position.d.ts

@@ -0,0 +1 @@
+export 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';

package/spotlight/lib/spotlight/types/spotlight-step.d.ts

@@ -0,0 +1,21 @@
+import { TemplateRef } from '@angular/core';
+import { SpotlightPosition } from './spotlight-position';
+export interface SpotlightStepAction {
+    label: string;
+    handler: () => void;
+}
+export interface SpotlightStep {
+    stepId: string;
+    title: string | TemplateRef<any>;
+    message: string | TemplateRef<any>;
+    position?: SpotlightPosition;
+    content?: TemplateRef<any> | null;
+    actions?: SpotlightStepAction[];
+    showBackdrop?: boolean;
+    dismissible?: boolean;
+    beforeNext?: () => void | Promise<void>;
+    beforePrevious?: () => void | Promise<void>;
+}
+export type SpotlightConfig = Omit<SpotlightStep, 'stepId' | 'beforeNext' | 'beforePrevious'> & {
+    showDoNotShowAgain?: boolean;
+};