@seniorsistemas/angular-components 19.9.1 → 19.9.2

package/fesm2022/seniorsistemas-angular-components-spotlight.mjs

@@ -197,6 +197,67 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "18.2.14", ngImpo
             args: [{ selector: 's-spotlight', standalone: true, imports: [CommonModule, ButtonModule, CheckboxComponent, TranslateModule], template: "<div\n    [attr.role]=\"totalSteps() > 1 ? 'dialog' : 'tooltip'\"\n    [attr.aria-modal]=\"totalSteps() > 1 ? 'true' : null\"\n    [attr.aria-labelledby]=\"titleId\"\n    [attr.aria-describedby]=\"descId\"\n    class=\"flex max-w-[342px]\"\n    [ngClass]=\"isArrowLeft || isArrowRight ? 'flex-row' : 'flex-col'\"\n>\n    @if (isArrowTop) {\n        <ng-container *ngTemplateOutlet=\"arrowTopTemplate\"></ng-container>\n    }\n\n    @if (isArrowLeft) {\n        <ng-container *ngTemplateOutlet=\"arrowLeftTemplate\"></ng-container>\n    }\n\n    <div\n        class=\"relative flex w-full flex-col overflow-hidden rounded-[4px] bg-grayscale-0\"\n        style=\"\n            box-shadow:\n                0 3px 5px rgba(0, 0, 0, 0.2),\n                0 1px 18px rgba(0, 0, 0, 0.12),\n                0 6px 10px rgba(0, 0, 0, 0.14);\n        \"\n    >\n        <!-- Regi\u00E3o aria-live para anuncia\u00E7\u00E3o de mudan\u00E7a de passo para leitores de tela -->\n        <span\n            class=\"sr-only\"\n            aria-live=\"polite\"\n            aria-atomic=\"true\"\n        >\n            @if (totalSteps() > 1) {\n                {{\n                    'platform.angular_components.step_progress'\n                        | translate: { current: currentStep(), total: totalSteps() }\n                }}\n            }\n        </span>\n        <div class=\"flex h-[40px] w-full items-center justify-between p-[12px]\">\n            <div class=\"flex min-w-0 flex-1 items-center gap-[8px]\">\n                <h2\n                    [id]=\"titleId\"\n                    class=\"flex-1 overflow-hidden overflow-ellipsis whitespace-nowrap font-open-sans text-[14px] font-bold leading-[1.5] text-grayscale-90\"\n                >\n                    @if (titleTemplate) {\n                        <ng-container *ngTemplateOutlet=\"titleTemplate\"></ng-container>\n                    } @else {\n                        {{ titleString }}\n                    }\n                </h2>\n            </div>\n            <button\n                (click)=\"onClose()\"\n                class=\"flex h-[16px] w-[16px] flex-none items-center justify-center text-grayscale-90 transition-colors hover:text-grayscale-100\"\n                [attr.aria-label]=\"'platform.angular_components.close' | translate\"\n            >\n                <i class=\"fas fa-times\"></i>\n            </button>\n        </div>\n\n        @if (content()) {\n            <ng-container *ngTemplateOutlet=\"content()\"></ng-container>\n        }\n\n        <div class=\"flex w-full flex-col items-start gap-[20px] bg-grayscale-0 p-[12px]\">\n            <div\n                [id]=\"descId\"\n                class=\"w-full whitespace-pre-wrap font-open-sans text-[14px] font-normal leading-[1.5] text-grayscale-90\"\n            >\n                @if (messageTemplate) {\n                    <ng-container *ngTemplateOutlet=\"messageTemplate\"></ng-container>\n                } @else {\n                    {{ messageString }}\n                }\n            </div>\n\n            <div class=\"flex w-full flex-wrap gap-3\">\n                @if (totalSteps() > 1) {\n                    <p class=\"font-open-sans text-[14px] font-normal leading-[1.5] text-grayscale-90\">\n                        {{\n                            'platform.angular_components.step_counter'\n                                | translate: { current: currentStep(), total: totalSteps() }\n                        }}\n                    </p>\n                }\n\n                @if (totalSteps() === 1 && showDoNotShowAgain()) {\n                    <s-checkbox\n                        [checked]=\"isDoNotShowAgainChecked()\"\n                        (checkedChange)=\"toggleDoNotShowAgain()\"\n                        [label]=\"'platform.angular_components.dont_show_again' | translate\"\n                    ></s-checkbox>\n                }\n\n                <div\n                    class=\"flex flex-wrap items-start justify-end gap-[8px]\"\n                    [ngClass]=\"totalSteps() > 1 ? 'w-full' : ''\"\n                >\n                    @for (action of actions(); track action.label) {\n                        <s-button\n                            [label]=\"action.label\"\n                            (clicked)=\"action.handler()\"\n                            priority=\"default\"\n                            size=\"small\"\n                            class=\"flex-none\"\n                        ></s-button>\n                    }\n\n                    @if (totalSteps() > 1 && currentStep() > 1) {\n                        <s-button\n                            [label]=\"'platform.angular_components.back' | translate\"\n                            (clicked)=\"onPrevious()\"\n                            priority=\"default\"\n                            size=\"small\"\n                            class=\"flex-none\"\n                        ></s-button>\n                    }\n\n                    <s-button\n                        [label]=\"\n                            totalSteps() <= 1\n                                ? ('platform.angular_components.understood' | translate)\n                                : currentStep() < totalSteps()\n                                  ? ('platform.angular_components.next' | translate)\n                                  : ('platform.angular_components.complete' | translate)\n                        \"\n                        (clicked)=\"totalSteps() > 1 ? onNext() : onUnderstand()\"\n                        priority=\"secondary\"\n                        size=\"small\"\n                        class=\"flex-none\"\n                    ></s-button>\n                </div>\n            </div>\n        </div>\n    </div>\n\n    @if (isArrowBottom) {\n        <ng-container *ngTemplateOutlet=\"arrowBottomTemplate\"></ng-container>\n    }\n\n    @if (isArrowRight) {\n        <ng-container *ngTemplateOutlet=\"arrowRightTemplate\"></ng-container>\n    }\n</div>\n\n<!-- Arrow Templates -->\n<ng-template #arrowTopTemplate>\n    <div\n        class=\"relative z-10 flex h-[8px] w-full px-[12px] py-0\"\n        [ngClass]=\"arrowAlignmentClass\"\n        [ngStyle]=\"arrowPaddingStyle\"\n    >\n        <svg\n            width=\"16\"\n            height=\"8\"\n            viewBox=\"0 0 16 8\"\n            fill=\"none\"\n            xmlns=\"http://www.w3.org/2000/svg\"\n            class=\"text-grayscale-0\"\n            [ngClass]=\"arrowRotation\"\n        >\n            <path\n                d=\"M0 8L8 0L16 8\"\n                fill=\"currentColor\"\n            />\n        </svg>\n    </div>\n</ng-template>\n\n<ng-template #arrowBottomTemplate>\n    <div\n        class=\"relative z-10 flex h-[8px] w-full px-[12px] py-0\"\n        [ngClass]=\"arrowAlignmentClass\"\n        [ngStyle]=\"arrowPaddingStyle\"\n    >\n        <svg\n            width=\"16\"\n            height=\"8\"\n            viewBox=\"0 0 16 8\"\n            fill=\"none\"\n            xmlns=\"http://www.w3.org/2000/svg\"\n            class=\"text-grayscale-0\"\n            [ngClass]=\"arrowRotation\"\n        >\n            <path\n                d=\"M0 8L8 0L16 8\"\n                fill=\"currentColor\"\n            />\n        </svg>\n    </div>\n</ng-template>\n\n<ng-template #arrowLeftTemplate>\n    <div\n        class=\"relative z-10 flex w-[8px] flex-col items-center self-stretch px-0\"\n        [ngClass]=\"arrowAlignmentClass\"\n        [ngStyle]=\"arrowPaddingStyle\"\n    >\n        <svg\n            width=\"16\"\n            height=\"8\"\n            viewBox=\"0 0 16 8\"\n            fill=\"none\"\n            xmlns=\"http://www.w3.org/2000/svg\"\n            class=\"text-grayscale-0\"\n            [ngClass]=\"arrowRotation\"\n        >\n            <path\n                d=\"M0 8L8 0L16 8\"\n                fill=\"currentColor\"\n            />\n        </svg>\n    </div>\n</ng-template>\n\n<ng-template #arrowRightTemplate>\n    <div\n        class=\"relative z-10 flex w-[8px] flex-col items-center self-stretch px-0\"\n        [ngClass]=\"arrowAlignmentClass\"\n        [ngStyle]=\"arrowPaddingStyle\"\n    >\n        <svg\n            width=\"16\"\n            height=\"8\"\n            viewBox=\"0 0 16 8\"\n            fill=\"none\"\n            xmlns=\"http://www.w3.org/2000/svg\"\n            class=\"text-grayscale-0\"\n            [ngClass]=\"arrowRotation\"\n        >\n            <path\n                d=\"M0 8L8 0L16 8\"\n                fill=\"currentColor\"\n            />\n        </svg>\n    </div>\n</ng-template>\n\n" }]
         }] });
 
+/**
+ * Utilitário puro (sem dependência de Angular/NgZone) para aguardar até que a posição
+ * e o tamanho de um elemento parem de mudar — usado para medir corretamente elementos
+ * que podem estar em transição/animação (ex: um menu abrindo) no momento em que o
+ * Spotlight precisa apontar para eles.
+ */
+const DEFAULT_RECT_STABILITY_OPTIONS = {
+    requiredStableSamples: 3,
+    tolerancePx: 0.5,
+    maxWaitMs: 600,
+};
+function isRectStable(a, b, tolerancePx) {
+    return (Math.abs(a.top - b.top) <= tolerancePx &&
+        Math.abs(a.left - b.left) <= tolerancePx &&
+        Math.abs(a.width - b.width) <= tolerancePx &&
+        Math.abs(a.height - b.height) <= tolerancePx);
+}
+/**
+ * Faz polling de `el.getBoundingClientRect()` em frames sucessivos até que
+ * `requiredStableSamples` amostras consecutivas sejam iguais (dentro de `tolerancePx`),
+ * ou até que `maxWaitMs` seja atingido — o que ocorrer primeiro.
+ *
+ * `scheduleFrame`/`cancelFrame`/`now` são injetáveis para permitir testes determinísticos;
+ * por padrão usam as APIs nativas do navegador.
+ */
+function waitForStableRect(el, options = DEFAULT_RECT_STABILITY_OPTIONS, scheduleFrame = requestAnimationFrame, cancelFrame = cancelAnimationFrame, now = () => performance.now()) {
+    let cancelled = false;
+    let frameHandle = 0;
+    let resolveFn;
+    const promise = new Promise((resolve) => {
+        resolveFn = resolve;
+    });
+    const startedAt = now();
+    let lastRect = el.getBoundingClientRect();
+    let stableCount = 1;
+    const tick = () => {
+        if (cancelled)
+            return;
+        const rect = el.getBoundingClientRect();
+        stableCount = isRectStable(rect, lastRect, options.tolerancePx) ? stableCount + 1 : 1;
+        lastRect = rect;
+        if (stableCount >= options.requiredStableSamples) {
+            resolveFn({ rect, timedOut: false });
+            return;
+        }
+        if (now() - startedAt >= options.maxWaitMs) {
+            resolveFn({ rect, timedOut: true });
+            return;
+        }
+        frameHandle = scheduleFrame(tick);
+    };
+    frameHandle = scheduleFrame(tick);
+    return {
+        promise,
+        cancel: () => {
+            cancelled = true;
+            cancelFrame(frameHandle);
+        },
+    };
+}
+
 const POPOVER_WIDTH = 342;
 const SPOTLIGHT_PADDING = 8;
 const ARROW_HALF_SIZE = 8;
@@ -206,6 +267,8 @@ const MASK_BG = 'rgba(0,0,0,0.5)';
 const MASK_TRANSITION = 'all 0.2s ease';
 const OVERLAY_Z = '10000';
 const POPOVER_Z = '10001';
+/** Tempo máximo de espera pelo registro do elemento-alvo (ex: criado dinamicamente dentro de `beforeNext`) antes de recorrer ao popover centralizado. */
+const ELEMENT_WAIT_TIMEOUT_MS = 500;
 function toConnectedPositions(position) {
     const [direction, alignment] = position.split('-');
     const p = SPOTLIGHT_PADDING + 2;
@@ -257,6 +320,13 @@ class SpotlightOverlayComponent {
     totalSteps = this.tourService.totalSteps;
     /** @internal*/
     targetRect = signal(null);
+    /**
+     * Controla se a máscara deve animar a transição entre retângulos (reposicionamento
+     * em vivo, ex: scroll/resize) ou saltar instantaneamente (chegada/saída de um passo).
+     * Ver `setTargetRectImmediate`.
+     */
+    maskTransitionEnabled = signal(true);
+    maskTransitionStyle = computed(() => this.maskTransitionEnabled() ? MASK_TRANSITION : 'none');
     /** @internal */
     topMaskStyle = computed(() => {
         const rect = this.targetRect();
@@ -264,7 +334,7 @@ class SpotlightOverlayComponent {
             position: 'fixed',
             'z-index': OVERLAY_Z,
             background: MASK_BG,
-            transition: MASK_TRANSITION,
+            transition: this.maskTransitionStyle(),
             cursor: 'default',
         };
         if (!rect) {
@@ -287,7 +357,7 @@ class SpotlightOverlayComponent {
             position: 'fixed',
             'z-index': OVERLAY_Z,
             background: MASK_BG,
-            transition: MASK_TRANSITION,
+            transition: this.maskTransitionStyle(),
             cursor: 'default',
             top: `${top}px`,
             left: '0',
@@ -309,7 +379,7 @@ class SpotlightOverlayComponent {
             position: 'fixed',
             'z-index': OVERLAY_Z,
             background: MASK_BG,
-            transition: MASK_TRANSITION,
+            transition: this.maskTransitionStyle(),
             cursor: 'default',
             top: `${top}px`,
             left: `${right}px`,
@@ -329,7 +399,7 @@ class SpotlightOverlayComponent {
             position: 'fixed',
             'z-index': OVERLAY_Z,
             background: MASK_BG,
-            transition: MASK_TRANSITION,
+            transition: this.maskTransitionStyle(),
             cursor: 'default',
             top: `${bottom}px`,
             left: '0',
@@ -353,6 +423,9 @@ class SpotlightOverlayComponent {
     popoverSubs = [];
     focusTrap = null;
     previouslyFocusedElement = null;
+    pendingArrival = null;
+    elementWaitTimerId = null;
+    stabilizeGeneration = 0;
     constructor() {
         combineLatest([
             toObservable(this.currentStep),
@@ -362,34 +435,74 @@ class SpotlightOverlayComponent {
             .pipe(takeUntilDestroyed(this.destroyRef))
             .subscribe(([step, active]) => {
             this.disconnectResizeObserver();
+            this.cancelPendingArrival();
+            const generation = ++this.stabilizeGeneration;
             if (!step || !active) {
-                this.targetRect.set(null);
+                this.setTargetRectImmediate(null);
                 this.destroyPopoverOverlay();
                 return;
             }
             const el = this.tourService.getElement(step.stepId);
             if (el?.nativeElement) {
                 el.nativeElement.scrollIntoView({ block: 'nearest' });
-                const target = el.nativeElement;
-                this.zone.runOutsideAngular(() => {
-                    requestAnimationFrame(() => {
-                        this.zone.run(() => {
-                            if (!this.isActive()) {
-                                return;
-                            }
-                            this.updateTargetRect(target);
-                            this.observeElement(target);
-                            this.updatePopoverOverlay(target, step);
-                        });
-                    });
-                });
+                this.beginArrivalSequence(el.nativeElement, step, generation);
             }
             else {
-                this.targetRect.set(null);
-                this.updatePopoverOverlay(null, step);
+                this.awaitElementRegistration(step, generation);
             }
         });
     }
+    /**
+     * Aguarda o layout do elemento-alvo estabilizar (ex: animação de abertura de um menu
+     * disparada pelo `beforeNext` do passo anterior) antes de medir sua posição definitiva
+     * e posicionar a máscara/popover. Substitui a antiga espera de um único frame, que
+     * capturava o retângulo no meio de animações de terceiros na tela.
+     */
+    beginArrivalSequence(target, step, generation) {
+        this.zone.runOutsideAngular(() => {
+            const handle = waitForStableRect(target);
+            this.pendingArrival = handle;
+            handle.promise.then(({ rect, timedOut }) => {
+                this.zone.run(() => {
+                    if (generation !== this.stabilizeGeneration || !this.isActive()) {
+                        return;
+                    }
+                    if (timedOut) {
+                        console.warn(`[Spotlight] O layout do elemento do passo "${step.stepId}" não estabilizou a tempo; usando a última posição medida.`);
+                    }
+                    this.setTargetRectImmediate(rect);
+                    this.observeElement(target);
+                    this.updatePopoverOverlay(target, step);
+                });
+            });
+        });
+    }
+    /**
+     * Aguarda até `ELEMENT_WAIT_TIMEOUT_MS` pelo registro do elemento-alvo via
+     * `[sSpotlightStep]` (útil quando o `beforeNext` do passo anterior cria o elemento
+     * dinamicamente, ex: abrindo uma aba) antes de recorrer ao popover centralizado.
+     * Mantém o último quadro renderizado durante a espera para evitar um flash.
+     */
+    awaitElementRegistration(step, generation) {
+        this.elementWaitTimerId = setTimeout(() => {
+            this.zone.run(() => {
+                if (generation !== this.stabilizeGeneration) {
+                    return;
+                }
+                console.warn(`[Spotlight] Elemento do passo "${step.stepId}" não foi registrado a tempo; exibindo popover centralizado sem destaque.`);
+                this.setTargetRectImmediate(null);
+                this.updatePopoverOverlay(null, step);
+            });
+        }, ELEMENT_WAIT_TIMEOUT_MS);
+    }
+    cancelPendingArrival() {
+        this.pendingArrival?.cancel();
+        this.pendingArrival = null;
+        if (this.elementWaitTimerId !== null) {
+            clearTimeout(this.elementWaitTimerId);
+            this.elementWaitTimerId = null;
+        }
+    }
     ngOnInit() {
         this.zone.runOutsideAngular(() => {
             const scrollOpts = { capture: true, passive: true };
@@ -417,6 +530,7 @@ class SpotlightOverlayComponent {
         });
     }
     ngOnDestroy() {
+        this.cancelPendingArrival();
         this.destroyPopoverOverlay();
     }
     /** @internal */
@@ -631,6 +745,22 @@ class SpotlightOverlayComponent {
     updateTargetRect(el) {
         this.targetRect.set(el.getBoundingClientRect());
     }
+    /**
+     * Aplica um novo `targetRect` sem animação de transição na máscara — usado ao
+     * chegar/saltar para um alvo novo, onde animar a partir da posição do passo
+     * anterior criaria a falsa impressão de "apontou errado e corrigiu depois".
+     * A transição é reabilitada no frame seguinte para reposicionamentos legítimos
+     * (scroll/resize de um alvo já visível).
+     */
+    setTargetRectImmediate(rect) {
+        this.maskTransitionEnabled.set(false);
+        this.targetRect.set(rect);
+        this.zone.runOutsideAngular(() => {
+            requestAnimationFrame(() => {
+                this.zone.run(() => this.maskTransitionEnabled.set(true));
+            });
+        });
+    }
     refreshRect() {
         const step = this.currentStep();
         if (!step || !this.isActive()) {