@seniorsistemas/angular-components 19.9.0 → 19.9.2

package/numeric-mask/README.md

@@ -22,11 +22,11 @@ Diretiva Angular para formatação de valores numéricos em campos de input com
 import { NumericMaskDirective } from '@seniorsistemas/angular-components/numeric-mask';
 
 @Component({
-  standalone: true,
-  imports: [NumericMaskDirective, FormsModule],
+    standalone: true,
+    imports: [NumericMaskDirective, FormsModule],
 })
 export class MeuComponent {
-  valor: string | null = null;
+    valor: string | null = null;
 }
 ```
 
@@ -34,12 +34,12 @@ export class MeuComponent {
 
 ```html
 <input
-  type="text"
-  sNumericMask
-  [locale]="'pt-BR'"
-  [minDecimalPlaces]="2"
-  [maxDecimalPlaces]="2"
-  [(ngModel)]="valor"
+    type="text"
+    sNumericMask
+    [locale]="'pt-BR'"
+    [minDecimalPlaces]="2"
+    [maxDecimalPlaces]="2"
+    [(ngModel)]="valor"
 />
 ```
 
@@ -47,15 +47,17 @@ export class MeuComponent {
 
 ### Inputs
 
-| Propriedade | Tipo | Padrão | Obrigatório | Descrição |
-|-------------|------|--------|:-----------:|-----------|
-| `locale` | `string \| undefined` | Locale do `LocaleService` | Não | Locale para formatação (ex: `'pt-BR'`, `'en-US'`). Se omitido, usa o locale do `LocaleService` |
-| `minDecimalPlaces` | `number` | `0` | Não | Número mínimo de casas decimais a exibir |
-| `maxDecimalPlaces` | `number` | `10` | Não | Número máximo de casas decimais permitidas |
-| `allowNegative` | `boolean` | `false` | Não | Permite valores negativos. Use as teclas `+` ou `-` para alternar o sinal |
-| `allowScientificNotation` | `boolean` | `true` | Não | Habilita suporte a notação científica (ex: `1.5e10`) |
-| `min` | `number \| undefined` | `undefined` | Não | Valor mínimo permitido (validação de formulário) |
-| `max` | `number \| undefined` | `undefined` | Não | Valor máximo permitido (validação de formulário) |
+| Propriedade               | Tipo                                                   | Padrão                    | Obrigatório | Descrição                                                                                                                                                         |
+| ------------------------- | ------------------------------------------------------ | ------------------------- | :---------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `locale`                  | `string \| undefined`                                  | Locale do `LocaleService` |     Não     | Locale para formatação (ex: `'pt-BR'`, `'en-US'`). Se omitido, usa o locale do `LocaleService`                                                                    |
+| `minDecimalPlaces`        | `number`                                               | `0`                       |     Não     | Número mínimo de casas decimais a exibir                                                                                                                          |
+| `maxDecimalPlaces`        | `number`                                               | `10`                      |     Não     | Número máximo de casas decimais permitidas                                                                                                                        |
+| `allowNegative`           | `boolean`                                              | `false`                   |     Não     | Permite valores negativos. Use as teclas `+` ou `-` para alternar o sinal                                                                                         |
+| `allowScientificNotation` | `boolean`                                              | `true`                    |     Não     | Habilita suporte a notação científica (ex: `1.5e10`)                                                                                                              |
+| `min`                     | `number \| undefined`                                  | `undefined`               |     Não     | Valor mínimo permitido (validação de formulário)                                                                                                                  |
+| `max`                     | `number \| undefined`                                  | `undefined`               |     Não     | Valor máximo permitido (validação de formulário)                                                                                                                  |
+| `blockDecimalOverflow`    | `boolean`                                              | `true`                    |     Não     | Bloqueia a digitação e a colagem de casas decimais além de `maxDecimalPlaces`. Quando `maxDecimalPlaces` é `0`, o próprio separador decimal não pode ser digitado |
+| `decimalRoundingMode`     | `'preserve' \| 'truncate' \| 'roundUp' \| 'roundDown'` | `'preserve'`              |     Não     | Estratégia aplicada no `blur` quando `blockDecimalOverflow` é `false`. Sem efeito enquanto `blockDecimalOverflow` for `true`                                      |
 
 ### Tipos
 
@@ -69,16 +71,96 @@ type NumericMaskModelValue = string | null;
 
 ```typescript
 // Valor negativo quando allowNegative = false
-{ negativeNotAllowed: true }
+{
+    negativeNotAllowed: true;
+}
 
 // Valor abaixo do mínimo
-{ min: { min: number; actual: number } }
+{
+    min: {
+        min: number;
+        actual: number;
+    }
+}
 
 // Valor acima do máximo
-{ max: { max: number; actual: number } }
+{
+    max: {
+        max: number;
+        actual: number;
+    }
+}
 
 // Casas decimais acima do máximo
-{ excessiveDecimalPlaces: { max: number; actual: number } }
+{
+    excessiveDecimalPlaces: {
+        max: number;
+        actual: number;
+    }
+}
+```
+
+## Comportamento de excesso de casas decimais
+
+Por padrão (`blockDecimalOverflow = true`), a digitação e a colagem de valores com mais casas decimais que `maxDecimalPlaces` são bloqueadas no momento da entrada: dígitos excedentes são ignorados imediatamente (sem esperar o `blur`) e, quando `maxDecimalPlaces` é `0`, o próprio separador decimal não pode ser digitado.
+
+Desligando o bloqueio (`[blockDecimalOverflow]="false"`), a digitação volta a ser livre e o input `decimalRoundingMode` passa a controlar o que acontece ao perder o foco (`blur`):
+
+| `decimalRoundingMode` | Comportamento no `blur`                                                                                                                                     |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'preserve'` (padrão) | Comportamento legado: a exibição é truncada, mas o modelo mantém a precisão total do que foi digitado                                                       |
+| `'truncate'`          | Corta as casas excedentes tanto na exibição quanto no modelo, sem arredondar (sempre em direção a zero)                                                     |
+| `'roundUp'`           | Arredonda sempre para o próximo valor representável **acima** (ceiling), mesmo que o excedente seja mínimo — não é arredondamento para o valor mais próximo |
+| `'roundDown'`         | Arredonda sempre para o próximo valor representável **abaixo** (floor), pelo mesmo motivo                                                                   |
+
+```html
+<!-- Padrão: bloqueia a digitação acima de 2 casas decimais -->
+<input
+    type="text"
+    sNumericMask
+    [maxDecimalPlaces]="2"
+    [(ngModel)]="valor"
+/>
+
+<!-- Comportamento legado explícito (digitação livre, modelo com precisão total) -->
+<input
+    type="text"
+    sNumericMask
+    [maxDecimalPlaces]="2"
+    [blockDecimalOverflow]="false"
+    decimalRoundingMode="preserve"
+    [(ngModel)]="valor"
+/>
+
+<!-- Trunca no blur (corta sem arredondar) -->
+<input
+    type="text"
+    sNumericMask
+    [maxDecimalPlaces]="2"
+    [blockDecimalOverflow]="false"
+    decimalRoundingMode="truncate"
+    [(ngModel)]="valor"
+/>
+
+<!-- Arredonda sempre para cima no blur -->
+<input
+    type="text"
+    sNumericMask
+    [maxDecimalPlaces]="2"
+    [blockDecimalOverflow]="false"
+    decimalRoundingMode="roundUp"
+    [(ngModel)]="valor"
+/>
+
+<!-- Arredonda sempre para baixo no blur -->
+<input
+    type="text"
+    sNumericMask
+    [maxDecimalPlaces]="2"
+    [blockDecimalOverflow]="false"
+    decimalRoundingMode="roundDown"
+    [(ngModel)]="valor"
+/>
 ```
 
 ## Exemplos
@@ -87,13 +169,13 @@ type NumericMaskModelValue = string | null;
 
 ```html
 <input
-  type="text"
-  sNumericMask
-  locale="pt-BR"
-  [minDecimalPlaces]="2"
-  [maxDecimalPlaces]="2"
-  placeholder="0,00"
-  [(ngModel)]="valorMonetario"
+    type="text"
+    sNumericMask
+    locale="pt-BR"
+    [minDecimalPlaces]="2"
+    [maxDecimalPlaces]="2"
+    placeholder="0,00"
+    [(ngModel)]="valorMonetario"
 />
 ```
 
@@ -101,14 +183,14 @@ type NumericMaskModelValue = string | null;
 
 ```html
 <input
-  type="text"
-  sNumericMask
-  locale="pt-BR"
-  [minDecimalPlaces]="2"
-  [maxDecimalPlaces]="2"
-  [allowNegative]="true"
-  placeholder="-0,00"
-  [(ngModel)]="variacao"
+    type="text"
+    sNumericMask
+    locale="pt-BR"
+    [minDecimalPlaces]="2"
+    [maxDecimalPlaces]="2"
+    [allowNegative]="true"
+    placeholder="-0,00"
+    [(ngModel)]="variacao"
 />
 <!-- Pressione + ou - para alternar entre positivo e negativo -->
 ```
@@ -117,15 +199,15 @@ type NumericMaskModelValue = string | null;
 
 ```html
 <input
-  type="text"
-  sNumericMask
-  locale="pt-BR"
-  [minDecimalPlaces]="2"
-  [maxDecimalPlaces]="2"
-  [min]="0"
-  [max]="100"
-  placeholder="0,00"
-  [(ngModel)]="percentual"
+    type="text"
+    sNumericMask
+    locale="pt-BR"
+    [minDecimalPlaces]="2"
+    [maxDecimalPlaces]="2"
+    [min]="0"
+    [max]="100"
+    placeholder="0,00"
+    [(ngModel)]="percentual"
 />
 ```
 
@@ -133,13 +215,13 @@ type NumericMaskModelValue = string | null;
 
 ```html
 <input
-  type="text"
-  sNumericMask
-  locale="en-US"
-  [minDecimalPlaces]="2"
-  [maxDecimalPlaces]="2"
-  placeholder="0.00"
-  [(ngModel)]="valor"
+    type="text"
+    sNumericMask
+    locale="en-US"
+    [minDecimalPlaces]="2"
+    [maxDecimalPlaces]="2"
+    placeholder="0.00"
+    [(ngModel)]="valor"
 />
 ```
 
@@ -147,13 +229,13 @@ type NumericMaskModelValue = string | null;
 
 ```html
 <input
-  type="text"
-  sNumericMask
-  locale="pt-BR"
-  [minDecimalPlaces]="0"
-  [maxDecimalPlaces]="4"
-  placeholder="0"
-  [(ngModel)]="quantidade"
+    type="text"
+    sNumericMask
+    locale="pt-BR"
+    [minDecimalPlaces]="0"
+    [maxDecimalPlaces]="4"
+    placeholder="0"
+    [(ngModel)]="quantidade"
 />
 ```
 
@@ -168,3 +250,25 @@ type NumericMaskModelValue = string | null;
 
 - [`NumericPipe`](../numeric/README.md) — formatação de valores numéricos para exibição somente leitura
 - [`NumberInput`](../number-input/src/lib/number-input/README.md) — diretiva descontinuada, use `sNumericMask` em seu lugar
+
+## Migração
+
+### Mudança de comportamento padrão
+
+A partir desta versão, `blockDecimalOverflow` passa a ser `true` por padrão: a digitação e a colagem de valores com mais casas decimais que `maxDecimalPlaces` passam a ser bloqueadas no momento da entrada, em vez de aceitas livremente e truncadas apenas na exibição ao perder o foco.
+
+Para restaurar o comportamento anterior (digitação livre, modelo com precisão total, exibição truncada no `blur`):
+
+```html
+<input
+    type="text"
+    sNumericMask
+    [maxDecimalPlaces]="2"
+    [blockDecimalOverflow]="false"
+    decimalRoundingMode="preserve"
+    [(ngModel)]="valor"
+/>
+```
+
+`decimalRoundingMode="preserve"` já é o padrão — pode ser omitido, mas deixá-lo explícito reforça a intenção do comportamento legado.
+

package/numeric-mask/lib/numeric-mask/numeric-mask.directive.d.ts

@@ -56,6 +56,22 @@ export declare class NumericMaskDirective implements OnInit, OnChanges, ControlV
      * Maximum value allowed
      */
     max: import("@angular/core").InputSignal<number | undefined>;
+    /**
+     * Blocks typing/pasting decimal digits beyond maxDecimalPlaces.
+     * When maxDecimalPlaces is 0, the decimal separator itself cannot be entered.
+     * @default true
+     */
+    blockDecimalOverflow: import("@angular/core").InputSignal<boolean>;
+    /**
+     * Strategy applied on blur when blockDecimalOverflow is false.
+     * 'preserve' keeps the model at full precision; only the display is truncated (legacy behavior).
+     * 'truncate' cuts the excess decimals without rounding (towards zero), updating the model too.
+     * 'roundUp' always rounds to the next representable value above (ceiling), updating the model too.
+     * 'roundDown' always rounds to the next representable value below (floor), updating the model too.
+     * Has no effect while blockDecimalOverflow is true.
+     * @default 'preserve'
+     */
+    decimalRoundingMode: import("@angular/core").InputSignal<"preserve" | "truncate" | "roundUp" | "roundDown">;
     private readonly elementRef;
     private readonly renderer;
     private readonly localeService;
@@ -127,10 +143,21 @@ export declare class NumericMaskDirective implements OnInit, OnChanges, ControlV
      */
     private escapeRegex;
     /**
-     * Truncates a number to the specified decimal places (never rounds)
+     * Truncates (or rounds, depending on roundingMode) a number to the specified decimal places
      * @private
      */
     private truncateToDecimalPlaces;
+    /**
+     * Maps decimalRoundingMode to the corresponding BigNumber rounding mode
+     * @private
+     */
+    private resolveRoundingMode;
+    /**
+     * Limits the decimal part of a value being typed/pasted to maxDecimalPlaces,
+     * preserving any scientific notation exponent untouched
+     * @private
+     */
+    private applyBlockLimit;
     /**
      * Parses a string value to its numeric representation, handling separators and sign
      * Returns BigNumber to preserve full precision and optional number conversion
@@ -172,5 +199,5 @@ export declare class NumericMaskDirective implements OnInit, OnChanges, ControlV
     setDisabledState(isDisabled: boolean): void;
     validate(control: AbstractControl): ValidationErrors | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<NumericMaskDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<NumericMaskDirective, "[sNumericMask]", never, { "locale": { "alias": "locale"; "required": false; "isSignal": true; }; "minDecimalPlaces": { "alias": "minDecimalPlaces"; "required": false; "isSignal": true; }; "maxDecimalPlaces": { "alias": "maxDecimalPlaces"; "required": false; "isSignal": true; }; "allowNegative": { "alias": "allowNegative"; "required": false; "isSignal": true; }; "allowScientificNotation": { "alias": "allowScientificNotation"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "decimalSeparator": { "alias": "decimalSeparator"; "required": false; "isSignal": true; }; "thousandSeparator": { "alias": "thousandSeparator"; "required": false; "isSignal": true; }; }, { "decimalSeparator": "decimalSeparatorChange"; "thousandSeparator": "thousandSeparatorChange"; }, never, never, true, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NumericMaskDirective, "[sNumericMask]", never, { "locale": { "alias": "locale"; "required": false; "isSignal": true; }; "minDecimalPlaces": { "alias": "minDecimalPlaces"; "required": false; "isSignal": true; }; "maxDecimalPlaces": { "alias": "maxDecimalPlaces"; "required": false; "isSignal": true; }; "allowNegative": { "alias": "allowNegative"; "required": false; "isSignal": true; }; "allowScientificNotation": { "alias": "allowScientificNotation"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "blockDecimalOverflow": { "alias": "blockDecimalOverflow"; "required": false; "isSignal": true; }; "decimalRoundingMode": { "alias": "decimalRoundingMode"; "required": false; "isSignal": true; }; "decimalSeparator": { "alias": "decimalSeparator"; "required": false; "isSignal": true; }; "thousandSeparator": { "alias": "thousandSeparator"; "required": false; "isSignal": true; }; }, { "decimalSeparator": "decimalSeparatorChange"; "thousandSeparator": "thousandSeparatorChange"; }, never, never, true, never>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seniorsistemas/angular-components",
-  "version": "19.9.0",
+  "version": "19.9.2",
   "peerDependencies": {
     "@angular/cdk": "^18.2.14",
     "@angular/common": "^18.2.0",
@@ -97,36 +97,36 @@
       "esm": "./esm2022/accordion/seniorsistemas-angular-components-accordion.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-accordion.mjs"
     },
-    "./autocomplete": {
-      "types": "./autocomplete/index.d.ts",
-      "esm2022": "./esm2022/autocomplete/seniorsistemas-angular-components-autocomplete.mjs",
-      "esm": "./esm2022/autocomplete/seniorsistemas-angular-components-autocomplete.mjs",
-      "default": "./fesm2022/seniorsistemas-angular-components-autocomplete.mjs"
-    },
     "./alert": {
       "types": "./alert/index.d.ts",
       "esm2022": "./esm2022/alert/seniorsistemas-angular-components-alert.mjs",
       "esm": "./esm2022/alert/seniorsistemas-angular-components-alert.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-alert.mjs"
     },
+    "./autocomplete": {
+      "types": "./autocomplete/index.d.ts",
+      "esm2022": "./esm2022/autocomplete/seniorsistemas-angular-components-autocomplete.mjs",
+      "esm": "./esm2022/autocomplete/seniorsistemas-angular-components-autocomplete.mjs",
+      "default": "./fesm2022/seniorsistemas-angular-components-autocomplete.mjs"
+    },
     "./badge": {
       "types": "./badge/index.d.ts",
       "esm2022": "./esm2022/badge/seniorsistemas-angular-components-badge.mjs",
       "esm": "./esm2022/badge/seniorsistemas-angular-components-badge.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-badge.mjs"
     },
-    "./bignumber-input": {
-      "types": "./bignumber-input/index.d.ts",
-      "esm2022": "./esm2022/bignumber-input/seniorsistemas-angular-components-bignumber-input.mjs",
-      "esm": "./esm2022/bignumber-input/seniorsistemas-angular-components-bignumber-input.mjs",
-      "default": "./fesm2022/seniorsistemas-angular-components-bignumber-input.mjs"
-    },
     "./breadcrumb": {
       "types": "./breadcrumb/index.d.ts",
       "esm2022": "./esm2022/breadcrumb/seniorsistemas-angular-components-breadcrumb.mjs",
       "esm": "./esm2022/breadcrumb/seniorsistemas-angular-components-breadcrumb.mjs",
       "default": "./fesm2022/seniorsistemas-angular-components-breadcrumb.mjs"
     },
+    "./bignumber-input": {
+      "types": "./bignumber-input/index.d.ts",
+      "esm2022": "./esm2022/bignumber-input/seniorsistemas-angular-components-bignumber-input.mjs",
+      "esm": "./esm2022/bignumber-input/seniorsistemas-angular-components-bignumber-input.mjs",
+      "default": "./fesm2022/seniorsistemas-angular-components-bignumber-input.mjs"
+    },
     "./button": {
       "types": "./button/index.d.ts",
       "esm2022": "./esm2022/button/seniorsistemas-angular-components-button.mjs",

package/sidebar/README.md

@@ -4,11 +4,11 @@
 
 > **Descontinuado** — Este pacote é um alias de compatibilidade para o componente `Drawer` e será removido na versão 20.0.0.
 
-O pacote `sidebar` re-exporta `DrawerComponent` e `DrawerModule` do pacote `@seniorsistemas/angular-components/drawer`.
+O pacote `sidebar` re-exporta `DrawerComponent` e `DrawerModule` do pacote `@seniorsistemas/angular-components/drawer` — tanto sob os nomes novos (`DrawerComponent`/`DrawerModule`) quanto sob os nomes antigos (`SidebarComponent`/`SidebarModule`), para manter compatibilidade com quem já importava por qualquer um dos dois nomes a partir deste pacote.
 
 ## Quando usar
 
-- Apenas para manutenção de código legado que já usa `DrawerComponent` ou `DrawerModule` a partir deste pacote
+- Apenas para manutenção de código legado que já usa `SidebarComponent`/`SidebarModule` (ou `DrawerComponent`/`DrawerModule`) a partir deste pacote
 
 ## Quando não usar
 
@@ -18,7 +18,7 @@ O pacote `sidebar` re-exporta `DrawerComponent` e `DrawerModule` do pacote `@sen
 
 ```typescript
 // Antes (descontinuado)
-import { DrawerModule } from '@seniorsistemas/angular-components/sidebar';
+import { SidebarModule } from '@seniorsistemas/angular-components/sidebar';
 
 // Depois (recomendado)
 import { DrawerModule } from '@seniorsistemas/angular-components/drawer';

package/sidebar/public-api.d.ts

@@ -9,3 +9,13 @@ export declare const DrawerComponent: typeof DrawerComponentOriginal;
  * O pacote sidebar será removido na versão 20.0.0.
  */
 export declare const DrawerModule: typeof DrawerModuleOriginal;
+/**
+ * @deprecated Use DrawerComponent from '@seniorsistemas/angular-components/drawer'.
+ * O pacote sidebar será removido na versão 20.0.0.
+ */
+export declare const SidebarComponent: typeof DrawerComponentOriginal;
+/**
+ * @deprecated Use DrawerModule from '@seniorsistemas/angular-components/drawer'.
+ * O pacote sidebar será removido na versão 20.0.0.
+ */
+export declare const SidebarModule: typeof DrawerModuleOriginal;

package/spotlight/README.md

@@ -88,6 +88,32 @@ this.tourService.start([
 | `previous` | `OutputEmitterRef<void>` | Emitido ao clicar em "Voltar" |
 | `understand` | `OutputEmitterRef<void>` | Emitido ao clicar em "Entendido" (modo simples) |
 
+### Hooks `beforeNext` / `beforePrevious`
+
+Cada passo pode definir `beforeNext?: () => void | Promise<void>` e `beforePrevious?: () => void | Promise<void>`, executados antes de avançar/retroceder. Se retornarem uma `Promise`, o Spotlight aguarda sua resolução antes de trocar de passo.
+
+Isso é útil quando o próximo passo aponta para um elemento que só existe (ou só chega à posição final) depois de uma ação disparada pelo `beforeNext` — por exemplo, abrir um menu ou uma aba:
+
+```typescript
+this.tourService.start([
+  {
+    stepId: 'abrir-menu',
+    title: 'Abra o menu',
+    message: 'Clique aqui para abrir as opções.',
+    beforeNext: () => this.menuService.open(), // abre um menu com animação CSS
+  },
+  {
+    stepId: 'item-do-menu', // elemento dentro do menu recém-aberto
+    title: 'Selecione aqui',
+    message: 'Este item concentra as opções mais usadas.',
+  },
+]);
+```
+
+**Não é necessário esperar manualmente a animação terminar.** O Spotlight aguarda internamente até que a posição do elemento-alvo do próximo passo se estabilize, tolerando transições CSS típicas de abertura de menus, abas e painéis. Não adicione `setTimeout`/delays artificiais dentro de `beforeNext` — eles são redundantes e, no melhor caso, apenas adicionam espera desnecessária.
+
+Se o elemento do próximo passo ainda não existir no DOM no momento da troca (por exemplo, criado dinamicamente pelo `beforeNext` via `@if`/troca de aba), o Spotlight aguarda brevemente pelo registro automático via `[sSpotlightStep]` antes de recorrer a um popover centralizado sem destaque. Em ambos os casos de espera esgotada, um aviso é emitido no console citando o `stepId` — útil para diagnosticar um `stepId` incorreto ou uma animação anormalmente longa.
+
 ### Tipos
 
 ```typescript
@@ -105,6 +131,8 @@ interface SpotlightStep {
   showDoNotShowAgain?: boolean;
   dismissible?: boolean;
   actions?: SpotlightStepAction[];
+  beforeNext?: () => void | Promise<void>;
+  beforePrevious?: () => void | Promise<void>;
 }
 
 interface SpotlightStepAction {

package/spotlight/lib/spotlight/spotlight-overlay/rect-stability.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+export interface RectStabilityOptions {
+    /** Quantas amostras consecutivas dentro da tolerância definem "estável". */
+    requiredStableSamples: number;
+    /** Diferença máxima (px) entre duas amostras para serem consideradas iguais. */
+    tolerancePx: number;
+    /** Teto de segurança (ms) — nunca esperar além disso. */
+    maxWaitMs: number;
+}
+export declare const DEFAULT_RECT_STABILITY_OPTIONS: RectStabilityOptions;
+export interface StableRectResult {
+    rect: DOMRect;
+    timedOut: boolean;
+}
+export interface StabilizeHandle {
+    readonly promise: Promise<StableRectResult>;
+    cancel(): void;
+}
+/**
+ * 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.
+ */
+export declare function waitForStableRect(el: HTMLElement, options?: RectStabilityOptions, scheduleFrame?: (cb: FrameRequestCallback) => number, cancelFrame?: (handle: number) => void, now?: () => number): StabilizeHandle;

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

@@ -20,6 +20,13 @@ export declare class SpotlightOverlayComponent implements OnInit, OnDestroy {
     readonly totalSteps: import("@angular/core").Signal<number>;
     /** @internal*/
     readonly targetRect: import("@angular/core").WritableSignal<DOMRect | 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`.
+     */
+    private readonly maskTransitionEnabled;
+    private readonly maskTransitionStyle;
     /** @internal */
     readonly topMaskStyle: import("@angular/core").Signal<Record<string, string>>;
     /** @internal */
@@ -36,7 +43,25 @@ export declare class SpotlightOverlayComponent implements OnInit, OnDestroy {
     private popoverSubs;
     private focusTrap;
     private previouslyFocusedElement;
+    private pendingArrival;
+    private elementWaitTimerId;
+    private stabilizeGeneration;
     constructor();
+    /**
+     * 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.
+     */
+    private beginArrivalSequence;
+    /**
+     * 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.
+     */
+    private awaitElementRegistration;
+    private cancelPendingArrival;
     ngOnInit(): void;
     ngOnDestroy(): void;
     /** @internal */
@@ -62,6 +87,14 @@ export declare class SpotlightOverlayComponent implements OnInit, OnDestroy {
     private syncDirectionAndArrow;
     private destroyPopoverOverlay;
     private updateTargetRect;
+    /**
+     * 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).
+     */
+    private setTargetRectImmediate;
     private refreshRect;
     private observeElement;
     private disconnectResizeObserver;