@govbr-ds/webcomponents 2.1.3 → 2.2.0

package/dist/collection/components/scrim/scrim.js

@@ -4,15 +4,36 @@
  */
 import { Host, h, } from "@stencil/core";
 import { generateUniqueId } from "../../shared/utils/id";
+import { getScrollBehavior } from "../../shared/utils/motion";
 import { supportsNativeModalDialog, syncNativeModalDialog } from "../../shared/utils/native-dialog";
+import { resolveAllowedPropValue, resolveIntegerPropValue, resolveNumberPropValue } from "../../shared/utils/props";
 import { createRafBatcher } from "../../shared/utils/raf-batcher";
 import { lockBodyScroll, unlockBodyScroll } from "../../shared/utils/scrollLock";
 /**
- * ## Design System
+ * O componente `br-scrim` é a camada de sobreposição visual (backdrop / máscara) do GovBR-DS, utilizada para escurecer temporariamente a interface e direcionar a atenção da pessoa usuária para um ponto de interesse ou diálogo.
  *
- * Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/scrim?tab=designer).
+ * ### Para que serve
  *
- * @category Feedback
+ * - **Destaque visual exclusivo (Spotlight):** Cria um foco exclusivo sobre determinado elemento da página (como um tour guiado ou tutorial introdutório).
+ * - **Bloqueio de interação com o fundo:** Impede cliques acidentais e rolagem na interface subjacente enquanto uma superfície flutuante estiver ativa.
+ * - **Comportamento acessível de fechamento:** Suporta fechamento ao clicar na máscara ou ao pressionar a tecla Escape, com controle de foco previsível.
+ *
+ * ### Quando utilizar
+ *
+ * - **Utilize quando:**
+ *   - For necessário criar máscaras de fundo personalizadas para fluxos de onboarding, tutoriais ou menus temporários imersivos.
+ * - **Evite e prefira outro componente quando:**
+ *   - Estiver implementando uma caixa de diálogo padrão com cabeçalho, corpo e rodapé (prefira `br-modal`, que já inclui seu próprio scrim interno).
+ *
+ * ### Estrutura e Slots
+ *
+ * O `br-scrim` atua como superfície de sobreposição:
+ * - `default`: Slot para inserção do elemento que receberá o destaque em primeiro plano sobre a máscara.
+ *
+ * Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/scrim?tab=designer).
+ *
+
+ * @category Feedback, Sobreposições
  * @status stable
  * @slot default - Slot para o conteúdo principal a ser exibido sobre o fundo escurecido do scrim.
  * @slot activator - Slot para o elemento ativador do scrim, com prioridade sobre a propriedade activator.
@@ -37,7 +58,7 @@ export class Scrim {
          */
         this.disableCloseOnClick = false;
         /**
-         * Define o valor de z-index do scrim
+         * Define o valor de z-index do scrim. Deve ser um inteiro entre 0 e Number.MAX_SAFE_INTEGER; valores inválidos usam 0.
          */
         this.zIndex = null;
         /**
@@ -53,7 +74,7 @@ export class Scrim {
          */
         this.bgColor = null;
         /**
-         * Define a opacidade personalizada do scrim
+         * Define a opacidade personalizada do scrim. O valor é limitado ao intervalo `0`–`1`; entradas inválidas usam `0.4`.
          */
         this.customOpacity = null;
         /**
@@ -67,12 +88,18 @@ export class Scrim {
          */
         this.displayMode = 'fullscreen';
         /**
-         * Determina quanto de rolagem (em pixels) é necessário para acionar a ação de fechamento automático do scrim.
+         * Determina quanto de rolagem (em pixels) é necessário para acionar a ação de fechamento automático do scrim. Valores negativos usam `0`.
          */
         this.scrollThreshold = 50;
         /**
          * Define o seletor para o elemento activator.
          * Nota: O slot 'activator' tem prioridade sobre esta propriedade.
+         *
+         * @example
+         * ```html
+         * <button id="abrir-ajuda" type="button">Abrir ajuda</button>
+         * <br-scrim activator="#abrir-ajuda">Conteúdo</br-scrim>
+         * ```
          */
         this.activator = null;
         /**
@@ -126,15 +153,34 @@ export class Scrim {
          * - **largura** para âncoras `left` e `right`
          *
          * Só tem efeito quando `variant="legibility"` está definido.
+         *
+         * @example
+         * ```html
+         * <br-scrim variant="legibility" legibility-anchor="bottom" legibility-size="40%">
+         *   Texto sobre a imagem
+         * </br-scrim>
+         * ```
          */
         this.legibilitySize = null;
+        /**
+         * Seletor CSS do elemento que deve receber o posicionamento da variante
+         * `legibility`. Quando não informado (padrão), o alvo é o elemento pai
+         * direto do `<br-scrim>`.
+         */
+        this.legibilityTargetId = null;
         /**
          * Ativa o modo de scrim vazado (variante 'spotlight'), criando uma área de fresta no overlay
          * que destaca o elemento referenciado pelo seletor CSS fornecido.
+         *
+         * @example
+         * ```html
+         * <button id="acao-principal" type="button">Continuar</button>
+         * <br-scrim variant="spotlight" spotlight-target-id="#acao-principal"></br-scrim>
+         * ```
          */
         this.spotlightTargetId = null;
         /**
-         * Espaçamento interno (em pixels) ao redor da área de fresta no scrim vazado.
+         * Espaçamento interno (em pixels) ao redor da área de fresta no scrim vazado. Valores negativos usam `0`.
          */
         this.spotlightPadding = 8;
         /**
@@ -225,10 +271,10 @@ export class Scrim {
             this.toggle();
         };
         this.handleScrollClose = () => {
-            if (this.scrollStrategy === 'close' && this.isActive) {
+            if (this.effectiveScrollStrategy === 'close' && this.isActive) {
                 const currentScroll = this.getScrollPosition();
                 const reference = this.scrollOrigin ?? this.lastScrollTop;
-                if (Math.abs(currentScroll - reference) > this.scrollThreshold) {
+                if (Math.abs(currentScroll - reference) > this.effectiveScrollThreshold) {
                     this.scrollOrigin = null;
                     // Não fecha se tiver modal filha com autoClose=false (padrão)
                     if (this.hasModalWithAutoClose()) {
@@ -320,7 +366,7 @@ export class Scrim {
                 if (this.hasModalWithAutoClose()) {
                     return;
                 }
-                if (this.contentLayout === 'none') {
+                if (this.effectiveContentLayout === 'none') {
                     this.brScrimClose.emit();
                     return;
                 }
@@ -348,14 +394,14 @@ export class Scrim {
             }
         };
         /**
-         * Recalcula as coordenadas do elemento pai via getBoundingClientRect e aplica
+         * Recalcula as coordenadas do alvo via getBoundingClientRect e aplica
          * como estilos inline no div interno, sobrepondo o `inset: 0` do mode-fullscreen.
          */
         this.computeLegibilityRect = () => {
-            const parent = this.el.parentElement;
-            if (parent === null || this.scrimDivRef === null)
+            const target = this.resolveLegibilityTarget();
+            if (target === null || this.scrimDivRef === null)
                 return;
-            const rect = parent.getBoundingClientRect();
+            const rect = target.getBoundingClientRect();
             this.scrimDivRef.style.setProperty('position', 'fixed');
             this.scrimDivRef.style.setProperty('inset', 'unset');
             this.scrimDivRef.style.setProperty('top', '0');
@@ -372,6 +418,40 @@ export class Scrim {
     get isActive() {
         return this.isLegibilityVariant || this.isOpen;
     }
+    get effectiveCustomOpacity() {
+        return resolveNumberPropValue(this.el, 'customOpacity', this.customOpacity, 0, 1, 0.4, {
+            allowNull: true,
+        });
+    }
+    get effectiveScrollThreshold() {
+        return resolveNumberPropValue(this.el, 'scrollThreshold', this.scrollThreshold, 0, Number.MAX_SAFE_INTEGER, 50);
+    }
+    get effectiveSpotlightPadding() {
+        return resolveNumberPropValue(this.el, 'spotlightPadding', this.spotlightPadding, 0, Number.MAX_SAFE_INTEGER, 8);
+    }
+    get effectiveZIndex() {
+        return resolveIntegerPropValue(this.el, 'zIndex', this.zIndex, 0, Number.MAX_SAFE_INTEGER, 0, {
+            allowNull: true,
+        });
+    }
+    get effectivePositionContent() {
+        return resolveAllowedPropValue(this.el, 'positionContent', this.positionContent, ['top', 'center', 'right', 'left', 'bottom'], 'center');
+    }
+    get effectiveScrollStrategy() {
+        return resolveAllowedPropValue(this.el, 'scrollStrategy', this.scrollStrategy, ['block', 'close'], 'block');
+    }
+    get effectiveVariant() {
+        return resolveAllowedPropValue(this.el, 'variant', this.variant, ['focus', 'spotlight', 'legibility'], 'focus');
+    }
+    get effectiveLegibilityAnchor() {
+        return resolveAllowedPropValue(this.el, 'legibilityAnchor', this.legibilityAnchor, ['top', 'bottom', 'left', 'right', 'center'], 'bottom');
+    }
+    get effectiveSpotlightShape() {
+        return resolveAllowedPropValue(this.el, 'spotlightShape', this.spotlightShape, ['rect', 'rounded', 'circle'], 'rect');
+    }
+    get effectiveContentLayout() {
+        return resolveAllowedPropValue(this.el, 'contentLayout', this.contentLayout, ['default', 'none'], 'default');
+    }
     // ======================================================================
     // LIFECYCLE HOOKS E WATCHERS
     // ======================================================================
@@ -393,7 +473,7 @@ export class Scrim {
                 this.brScrimOpen.emit();
             return;
         }
-        if (newValue && this.scrollStrategy === 'close') {
+        if (newValue && this.effectiveScrollStrategy === 'close') {
             const currentScroll = window.scrollY;
             this.lastScrollTop = currentScroll;
             this.scrollOrigin = currentScroll;
@@ -402,7 +482,7 @@ export class Scrim {
         if (this.isActive) {
             this.previouslyFocusedElement = document.activeElement;
             this.applyScrollStrategy();
-            if (this.contentLayout !== 'none' && !this.usesNativeTopLayer) {
+            if (this.effectiveContentLayout !== 'none' && !this.usesNativeTopLayer) {
                 this.addGlobalEventInterception();
                 const hasModalChild = this.findModalChild() !== null;
                 if (hasModalChild) {
@@ -421,7 +501,7 @@ export class Scrim {
             this.closeModalChild();
             this.cleanupSpotlight();
             this.resetScrolling();
-            if (this.contentLayout !== 'none') {
+            if (this.effectiveContentLayout !== 'none') {
                 this.removeGlobalEventInterception();
                 this.restoreFocus();
                 this.brScrimClose.emit();
@@ -431,16 +511,16 @@ export class Scrim {
     updateStyles() {
         // Aplica defaults da variante antes dos overrides manuais
         this.applyVariantDefaults();
-        if (this.zIndex !== null && this.zIndex !== undefined) {
-            this.el.style.zIndex = `${this.zIndex}`;
-            this.el.style.setProperty('--z-index-layer-4', `${this.zIndex}`);
+        if (this.effectiveZIndex !== null && this.effectiveZIndex !== undefined) {
+            this.el.style.zIndex = `${this.effectiveZIndex}`;
+            this.el.style.setProperty('--z-index-layer-4', `${this.effectiveZIndex}`);
         }
         // bgColor e customOpacity sobrepõem os valores da variante
         if (this.bgColor !== null) {
             this.el.style.setProperty('--surface-overlay-scrim', this.bgColor);
         }
-        if (this.customOpacity !== null) {
-            this.el.style.setProperty('--br-scrim-opacity', `${this.customOpacity}`);
+        if (this.effectiveCustomOpacity !== null) {
+            this.el.style.setProperty('--br-scrim-opacity', `${this.effectiveCustomOpacity}`);
         }
     }
     handleVariantChange() {
@@ -452,7 +532,7 @@ export class Scrim {
                 this.cleanupSpotlight();
                 this.setupLegibility();
             }
-            else if (this.variant === 'spotlight') {
+            else if (this.effectiveVariant === 'spotlight') {
                 this.cleanupLegibility();
                 if (!this.usesNativeTopLayer)
                     this.addGlobalEventInterception();
@@ -468,7 +548,7 @@ export class Scrim {
     }
     handleLayerModeChange() {
         this.removeGlobalEventInterception();
-        if (this.isActive && this.contentLayout !== 'none' && !this.usesNativeTopLayer) {
+        if (this.isActive && this.effectiveContentLayout !== 'none' && !this.usesNativeTopLayer) {
             this.addGlobalEventInterception();
         }
     }
@@ -477,12 +557,17 @@ export class Scrim {
             this.setupSpotlight();
         }
     }
+    handleLegibilityTargetChange() {
+        if (this.isActive && this.isLegibilityVariant) {
+            this.setupLegibility();
+        }
+    }
     handleActivatorChange() {
         this.removeActivatorClickListener();
         this.setupActivator();
     }
     connectedCallback() {
-        if (this.scrollStrategy === 'close') {
+        if (this.effectiveScrollStrategy === 'close') {
             const currentScroll = window.scrollY;
             this.lastScrollTop = currentScroll;
             this.scrollOrigin = currentScroll;
@@ -500,7 +585,7 @@ export class Scrim {
             this.restoreFocusTimeoutId = null;
         }
         window.removeEventListener('scroll', this.handleScrollClose);
-        if (this.scrollStrategy === 'block' && this.isActive) {
+        if (this.effectiveScrollStrategy === 'block' && this.isActive) {
             unlockBodyScroll();
         }
         if (this.contentRef !== null) {
@@ -532,7 +617,7 @@ export class Scrim {
         }
         else if (this.isActive) {
             this.applyScrollStrategy();
-            if (this.contentLayout !== 'none' && !this.usesNativeTopLayer) {
+            if (this.effectiveContentLayout !== 'none' && !this.usesNativeTopLayer) {
                 this.addGlobalEventInterception();
                 const modalChild = this.findModalChild();
                 if (modalChild === null) {
@@ -547,6 +632,11 @@ export class Scrim {
     }
     componentDidRender() {
         syncNativeModalDialog(this.nativeDialogRef, this.isActive && this.usesNativeDialog);
+        // A referência interna do scrim é atribuída durante o render; recalcula
+        // depois dele para garantir o posicionamento inicial do alvo de legibility.
+        if (this.isLegibilityVariant) {
+            this.computeLegibilityRect();
+        }
     }
     // ======================================================================
     // MÉTODOS PÚBLICOS (API)
@@ -555,7 +645,7 @@ export class Scrim {
      * Define o limite de rolagem para o fechamento automático do scrim.
      */
     async setScrollThreshold(threshold) {
-        this.scrollThreshold = threshold;
+        this.scrollThreshold = resolveNumberPropValue(this.el, 'scrollThreshold', threshold, 0, Number.MAX_SAFE_INTEGER, 50);
     }
     /**
      * Método público para exibir o scrim
@@ -752,10 +842,10 @@ export class Scrim {
     // ESTRATÉGIAS DE ROLAGEM (SCROLL)
     // ======================================================================
     applyScrollStrategy() {
-        if (this.scrollStrategy === 'block') {
+        if (this.effectiveScrollStrategy === 'block') {
             this.enableScrollBlock();
         }
-        else if (this.scrollStrategy === 'close') {
+        else if (this.effectiveScrollStrategy === 'close') {
             this.enableScrollWatcher();
         }
     }
@@ -773,7 +863,7 @@ export class Scrim {
         window.addEventListener('scroll', this.handleScrollClose, { passive: true });
     }
     resetScrolling() {
-        if (this.scrollStrategy === 'block') {
+        if (this.effectiveScrollStrategy === 'block') {
             unlockBodyScroll();
         }
         window.removeEventListener('scroll', this.handleScrollClose);
@@ -798,7 +888,7 @@ export class Scrim {
         if (focusableElements.length > 0) {
             const firstElement = focusableElements[0];
             if (firstElement !== null && firstElement !== undefined) {
-                firstElement.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+                firstElement.scrollIntoView({ behavior: getScrollBehavior(), block: 'nearest', inline: 'nearest' });
                 firstElement.focus({ preventScroll: true });
             }
         }
@@ -955,7 +1045,7 @@ export class Scrim {
      * eventos de teclado/foco/clique e nunca bloqueia rolagem.
      */
     get isLegibilityVariant() {
-        return this.variant === 'legibility';
+        return this.effectiveVariant === 'legibility';
     }
     /**
      * Resolve o display-mode efetivo.
@@ -963,13 +1053,13 @@ export class Scrim {
      * atributo `display-mode` tenha sido explicitamente definido pelo usuário.
      */
     get effectiveDisplayMode() {
-        if (this.variant === 'legibility' && !this.displayModeExplicit) {
+        if (this.effectiveVariant === 'legibility' && !this.displayModeExplicit) {
             return 'parent';
         }
-        return this.displayMode;
+        return resolveAllowedPropValue(this.el, 'displayMode', this.displayMode, ['fullscreen', 'parent'], 'fullscreen');
     }
     get usesNativeDialog() {
-        return this.effectiveDisplayMode === 'fullscreen' && !this.isLegibilityVariant && this.contentLayout !== 'none';
+        return (this.effectiveDisplayMode === 'fullscreen' && !this.isLegibilityVariant && this.effectiveContentLayout !== 'none');
     }
     get usesNativeTopLayer() {
         return this.usesNativeDialog && supportsNativeModalDialog();
@@ -981,13 +1071,13 @@ export class Scrim {
         this.el.style.removeProperty('--surface-overlay-scrim');
         this.el.style.removeProperty('--br-scrim-opacity');
         this.el.style.removeProperty('--br-scrim-mask-size');
-        switch (this.variant) {
+        switch (this.effectiveVariant) {
             case 'focus':
             case 'spotlight':
                 if (this.bgColor === null) {
                     this.el.style.setProperty('--surface-overlay-scrim', '#000000');
                 }
-                if (this.customOpacity === null) {
+                if (this.effectiveCustomOpacity === null) {
                     this.el.style.setProperty('--br-scrim-opacity', '0.4');
                 }
                 break;
@@ -1001,7 +1091,7 @@ export class Scrim {
                 if (this.bgColor === null) {
                     this.el.style.setProperty('--surface-overlay-scrim', '#000000');
                 }
-                if (this.customOpacity === null) {
+                if (this.effectiveCustomOpacity === null) {
                     // Se bgColor for um gradiente, o usuário deve setar customOpacity=1 ou omitir
                     this.el.style.setProperty('--br-scrim-opacity', '0.64');
                 }
@@ -1019,7 +1109,7 @@ export class Scrim {
      */
     setupSpotlight() {
         this.cleanupSpotlight();
-        if (this.variant !== 'spotlight')
+        if (this.effectiveVariant !== 'spotlight')
             return;
         const target = this.resolveSpotlightTarget();
         if (target === null)
@@ -1066,10 +1156,11 @@ export class Scrim {
     /**
      * Inicializa o posicionamento da variante legibility.
      *
-     * Aplica `position: fixed` com as coordenadas exatas do elemento pai via
-     * `getBoundingClientRect`, sem exigir nenhum CSS adicional no pai.
+     * Aplica `position: fixed` com as coordenadas exatas do alvo via
+     * `getBoundingClientRect`, sem exigir CSS adicional no alvo. O alvo é
+     * resolvido por `legibilityTargetId` ou, por padrão, pelo pai direto.
      *
-     * Com `ResizeObserver`, observa o pai **e todos os seus ancestrais**: quando um
+     * Com `ResizeObserver`, observa o alvo **e todos os seus ancestrais**: quando um
      * elemento irmão muda de tamanho (ex: menu abrindo), o ancestral comum redimensiona
      * e o callback reposiciona o scrim automaticamente.
      */
@@ -1077,16 +1168,16 @@ export class Scrim {
         this.cleanupLegibility();
         if (!this.isLegibilityVariant)
             return;
-        const parent = this.el.parentElement;
-        if (parent === null)
+        const target = this.resolveLegibilityTarget();
+        if (target === null)
             return;
         this.computeLegibilityRect();
         if (typeof ResizeObserver !== 'undefined') {
             this.legibilityResizeObserver = new ResizeObserver(() => this.scheduleLegibilityRect());
-            this.legibilityResizeObserver.observe(parent);
+            this.legibilityResizeObserver.observe(target);
             // Observa ancestrais até document.body para detectar deslocamentos causados
             // por elementos irmãos que empurram o pai (ex: menu abrindo acima dele).
-            let ancestor = parent.parentElement;
+            let ancestor = target.parentElement;
             while (ancestor !== null && ancestor !== document.documentElement) {
                 this.legibilityResizeObserver.observe(ancestor);
                 ancestor = ancestor.parentElement;
@@ -1114,6 +1205,24 @@ export class Scrim {
         window.removeEventListener('load', this.scheduleLegibilityRect);
         this.resetLegibilityStyles();
     }
+    /**
+     * Resolve o alvo da variante legibility. O pai direto permanece como
+     * fallback para preservar o comportamento anterior e a compatibilidade.
+     */
+    resolveLegibilityTarget() {
+        const selector = this.legibilityTargetId ?? this.el.getAttribute('legibility-target-id');
+        if (selector !== null && selector !== '') {
+            try {
+                const target = document.querySelector(selector);
+                if (target !== null)
+                    return target;
+            }
+            catch {
+                console.warn(`br-scrim: Seletor legibilityTargetId inválido: ${selector}`);
+            }
+        }
+        return this.el.parentElement;
+    }
     /**
      * Remove os estilos inline de posicionamento aplicados pelo computeLegibilityRect.
      */
@@ -1135,47 +1244,47 @@ export class Scrim {
      * Retorna null quando não há elemento alvo resolvido.
      */
     renderSpotlightOverlay(maskId, rect, padding) {
-        const spotlightShape = this.spotlightShape === 'circle' ? (h("ellipse", { cx: rect.left + rect.width / 2, cy: rect.top + rect.height / 2, rx: rect.width / 2 + padding, ry: rect.height / 2 + padding, fill: "black" })) : (h("rect", { x: rect.left - padding, y: rect.top - padding, width: rect.width + padding * 2, height: rect.height + padding * 2, rx: this.spotlightShape === 'rounded' ? 8 : 0, ry: this.spotlightShape === 'rounded' ? 8 : 0, fill: "black" }));
+        const spotlightShape = this.effectiveSpotlightShape === 'circle' ? (h("ellipse", { cx: rect.left + rect.width / 2, cy: rect.top + rect.height / 2, rx: rect.width / 2 + padding, ry: rect.height / 2 + padding, fill: "black" })) : (h("rect", { x: rect.left - padding, y: rect.top - padding, width: rect.width + padding * 2, height: rect.height + padding * 2, rx: this.effectiveSpotlightShape === 'rounded' ? 8 : 0, ry: this.effectiveSpotlightShape === 'rounded' ? 8 : 0, fill: "black" }));
         return (h("svg", { class: "spotlight-overlay", "aria-hidden": "true", onClick: this.handleMaskClick, xmlns: "http://www.w3.org/2000/svg" }, h("defs", null, h("mask", { id: maskId }, h("rect", { width: "100%", height: "100%", fill: "white" }), spotlightShape)), h("rect", { class: "spotlight-overlay-rect", width: "100%", height: "100%", mask: `url(#${maskId})` })));
     }
     getCssClassMap() {
         return {
             'br-scrim': true,
             opened: this.isActive,
-            'scroll-block': this.scrollStrategy === 'block',
-            'position-top': this.positionContent === 'top',
-            'position-bottom': this.positionContent === 'bottom',
-            'position-left': this.positionContent === 'left',
-            'position-right': this.positionContent === 'right',
-            'position-center': this.positionContent === 'center',
+            'scroll-block': this.effectiveScrollStrategy === 'block',
+            'position-top': this.effectivePositionContent === 'top',
+            'position-bottom': this.effectivePositionContent === 'bottom',
+            'position-left': this.effectivePositionContent === 'left',
+            'position-right': this.effectivePositionContent === 'right',
+            'position-center': this.effectivePositionContent === 'center',
             'mode-fullscreen': this.effectiveDisplayMode === 'fullscreen',
             'mode-parent': this.effectiveDisplayMode === 'parent',
-            'variant-focus': this.variant === 'focus',
-            'variant-spotlight': this.variant === 'spotlight',
-            'variant-legibility': this.variant === 'legibility',
-            'legibility-anchor-top': this.variant === 'legibility' && this.legibilityAnchor === 'top',
-            'legibility-anchor-bottom': this.variant === 'legibility' && this.legibilityAnchor === 'bottom',
-            'legibility-anchor-left': this.variant === 'legibility' && this.legibilityAnchor === 'left',
-            'legibility-anchor-right': this.variant === 'legibility' && this.legibilityAnchor === 'right',
-            'legibility-anchor-center': this.variant === 'legibility' && this.legibilityAnchor === 'center',
+            'variant-focus': this.effectiveVariant === 'focus',
+            'variant-spotlight': this.effectiveVariant === 'spotlight',
+            'variant-legibility': this.effectiveVariant === 'legibility',
+            'legibility-anchor-top': this.effectiveVariant === 'legibility' && this.effectiveLegibilityAnchor === 'top',
+            'legibility-anchor-bottom': this.effectiveVariant === 'legibility' && this.effectiveLegibilityAnchor === 'bottom',
+            'legibility-anchor-left': this.effectiveVariant === 'legibility' && this.effectiveLegibilityAnchor === 'left',
+            'legibility-anchor-right': this.effectiveVariant === 'legibility' && this.effectiveLegibilityAnchor === 'right',
+            'legibility-anchor-center': this.effectiveVariant === 'legibility' && this.effectiveLegibilityAnchor === 'center',
             'has-spotlight': this.spotlightRect !== null,
-            'content-layout-none': this.contentLayout === 'none',
+            'content-layout-none': this.effectiveContentLayout === 'none',
         };
     }
     // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: render preserva as variantes pública, local e nativa sem duplicar o conteúdo.
     render() {
         const maskId = `${this.customId}-spotlight-mask`;
-        const padding = this.spotlightPadding;
+        const padding = this.effectiveSpotlightPadding;
         const rect = this.spotlightRect;
-        const isDialogContainer = !this.isLegibilityVariant && this.contentLayout !== 'none';
+        const isDialogContainer = !this.isLegibilityVariant && this.effectiveContentLayout !== 'none';
         const maskElement = this.isLegibilityVariant ? (h("div", { class: "mask" })) : (h("div", { class: "mask", role: "button", "aria-label": "Fechar sobreposi\u00E7\u00E3o", tabIndex: 0, onClick: this.handleMaskClick, onKeyDown: (event) => {
                 if (event.key === 'Enter' || event.key === ' ') {
                     event.preventDefault();
                     this.handleMaskClick(event);
                 }
             } }));
-        const contentElement = (h("div", { key: 'f5046cd6fdf7a128bed5b76fb7065fa3a7dcad24', ref: (el) => (this.contentRef = el ?? null), id: `${this.customId}-content`, class: this.contentLayout === 'none' ? 'content content-unwrapped' : 'content', tabIndex: this.contentLayout === 'none' ? undefined : -1 }, h("slot", { key: 'd341205278a651d39ebbd18e1802f14aeab1c1a4' })));
-        return (h(Host, { key: 'a9aa507c3a541fc1978acc5269954b2ffebf2f6d' }, h("slot", { key: '53eb86b0900da07d1aa4ea6dd2116ae2c02a91d0', name: "activator" }), this.usesNativeDialog ? (h("dialog", { ref: (el) => {
+        const contentElement = (h("div", { key: '3ac232885a157cd05d718cfed0c63af7a3a769ac', ref: (el) => (this.contentRef = el ?? null), id: `${this.customId}-content`, class: this.effectiveContentLayout === 'none' ? 'content content-unwrapped' : 'content', tabIndex: this.effectiveContentLayout === 'none' ? undefined : -1 }, h("slot", { key: '9d2306c1cc3296e63272e2e08fb5b216eb1bdb9d' })));
+        return (h(Host, { key: 'c7c171f3e033e7c80ba0f9ce98515331385b2bf5' }, h("slot", { key: '7b379fa99c11d5a0227abf44a7fb3dc27ffe1cf4', name: "activator" }), this.usesNativeDialog ? (h("dialog", { ref: (el) => {
                 this.nativeDialogRef = el;
                 this.scrimDivRef = el;
             }, class: this.getCssClassMap(), id: this.customId, role: this.usesNativeTopLayer ? undefined : 'dialog', "aria-modal": "true", "aria-label": this.ariaLabel || 'Conteúdo do diálogo', "data-visible": this.isActive ? 'true' : 'false', onCancel: this.handleNativeCancel, onKeyDown: this.handleKeyDown }, maskElement, rect !== null && this.renderSpotlightOverlay(maskId, rect, padding), contentElement)) : isDialogContainer ? (h("div", { ref: (el) => {
@@ -1298,7 +1407,7 @@ export class Scrim {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Define o valor de z-index do scrim"
+                    "text": "Define o valor de z-index do scrim. Deve ser um inteiro entre 0 e Number.MAX_SAFE_INTEGER; valores inv\u00E1lidos usam 0."
                 },
                 "getter": false,
                 "setter": false,
@@ -1338,7 +1447,7 @@ export class Scrim {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Define a opacidade personalizada do scrim"
+                    "text": "Define a opacidade personalizada do scrim. O valor \u00E9 limitado ao intervalo `0`\u2013`1`; entradas inv\u00E1lidas usam `0.4`."
                 },
                 "getter": false,
                 "setter": false,
@@ -1411,7 +1520,7 @@ export class Scrim {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Determina quanto de rolagem (em pixels) \u00E9 necess\u00E1rio para acionar a a\u00E7\u00E3o de fechamento autom\u00E1tico do scrim."
+                    "text": "Determina quanto de rolagem (em pixels) \u00E9 necess\u00E1rio para acionar a a\u00E7\u00E3o de fechamento autom\u00E1tico do scrim. Valores negativos usam `0`."
                 },
                 "getter": false,
                 "setter": false,
@@ -1430,7 +1539,10 @@ export class Scrim {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "example",
+                            "text": "```html\n<button id=\"abrir-ajuda\" type=\"button\">Abrir ajuda</button>\n<br-scrim activator=\"#abrir-ajuda\">Conte\u00FAdo</br-scrim>\n```"
+                        }],
                     "text": "Define o seletor para o elemento activator.\nNota: O slot 'activator' tem prioridade sobre esta propriedade."
                 },
                 "getter": false,
@@ -1524,7 +1636,10 @@ export class Scrim {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "example",
+                            "text": "```html\n<br-scrim variant=\"legibility\" legibility-anchor=\"bottom\" legibility-size=\"40%\">\n  Texto sobre a imagem\n</br-scrim>\n```"
+                        }],
                     "text": "Define o tamanho da faixa de cobertura da variante `legibility`, usado em\nconjunto com `legibilityAnchor`.\n\nAceita qualquer valor CSS de comprimento v\u00E1lido:\n- Percentual relativo ao elemento pai: `'40%'`, `'75%'`\n- Comprimento absoluto: `'120px'`, `'8rem'`, `'6em'`\n- Fun\u00E7\u00E3o CSS: `'calc(100% - 2rem)'`\n\nQuando `null` (padr\u00E3o), a m\u00E1scara ocupa **100%** da dimens\u00E3o relevante:\n- **altura** para \u00E2ncoras `top`, `bottom` e `center`\n- **largura** para \u00E2ncoras `left` e `right`\n\nS\u00F3 tem efeito quando `variant=\"legibility\"` est\u00E1 definido."
                 },
                 "getter": false,
@@ -1533,7 +1648,7 @@ export class Scrim {
                 "attribute": "legibility-size",
                 "defaultValue": "null"
             },
-            "spotlightTargetId": {
+            "legibilityTargetId": {
                 "type": "string",
                 "mutable": false,
                 "complexType": {
@@ -1545,6 +1660,29 @@ export class Scrim {
                 "optional": false,
                 "docs": {
                     "tags": [],
+                    "text": "Seletor CSS do elemento que deve receber o posicionamento da variante\n`legibility`. Quando n\u00E3o informado (padr\u00E3o), o alvo \u00E9 o elemento pai\ndireto do `<br-scrim>`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "legibility-target-id",
+                "defaultValue": "null"
+            },
+            "spotlightTargetId": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | null",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "example",
+                            "text": "```html\n<button id=\"acao-principal\" type=\"button\">Continuar</button>\n<br-scrim variant=\"spotlight\" spotlight-target-id=\"#acao-principal\"></br-scrim>\n```"
+                        }],
                     "text": "Ativa o modo de scrim vazado (variante 'spotlight'), criando uma \u00E1rea de fresta no overlay\nque destaca o elemento referenciado pelo seletor CSS fornecido."
                 },
                 "getter": false,
@@ -1565,7 +1703,7 @@ export class Scrim {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Espa\u00E7amento interno (em pixels) ao redor da \u00E1rea de fresta no scrim vazado."
+                    "text": "Espa\u00E7amento interno (em pixels) ao redor da \u00E1rea de fresta no scrim vazado. Valores negativos usam `0`."
                 },
                 "getter": false,
                 "setter": false,
@@ -1796,6 +1934,9 @@ export class Scrim {
             }, {
                 "propName": "spotlightShape",
                 "methodName": "handleSpotlightChange"
+            }, {
+                "propName": "legibilityTargetId",
+                "methodName": "handleLegibilityTargetChange"
             }, {
                 "propName": "activator",
                 "methodName": "handleActivatorChange"