@seniorsistemas/angular-components 19.2.0 → 19.3.1

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;
+};

package/spotlight/lib/spotlight/types/spotlight-stop-event.d.ts

@@ -0,0 +1,13 @@
+export type SpotlightStopReason = 'completed' | 'interrupted' | 'dismissed';
+export interface SpotlightStopEvent {
+    reason: SpotlightStopReason;
+    doNotShowAgain: boolean;
+    stepId: string;
+    stepIndex: number;
+    totalSteps: number;
+}
+export interface SpotlightStepChangedEvent {
+    stepId: string;
+    stepIndex: number;
+    totalSteps: number;
+}

package/spotlight/public-api.d.ts

@@ -0,0 +1,6 @@
+export { SpotlightStepDirective } from './lib/spotlight/spotlight-step.directive';
+export { SpotlightTourService } from './lib/spotlight/spotlight-tour.service';
+export { SpotlightComponent } from './lib/spotlight/spotlight.component';
+export type { SpotlightPosition } from './lib/spotlight/types/spotlight-position';
+export type { SpotlightConfig, SpotlightStep, SpotlightStepAction } from './lib/spotlight/types/spotlight-step';
+export type { SpotlightStepChangedEvent, SpotlightStopEvent, SpotlightStopReason, } from './lib/spotlight/types/spotlight-stop-event';