@govbr-ds/webcomponents 2.1.0 → 2.1.2

package/dist/collection/components/carousel/carousel.js

@@ -0,0 +1,1217 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+import { Host, h, } from "@stencil/core";
+import { isEventTargetInside } from "../../shared/utils/event";
+import { generateUniqueId } from "../../shared/utils/id";
+import { UniversalSwipe } from "../../shared/utils/swipe";
+/**
+ * ## Design System
+ *
+ * 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/carousel?tab=designer).
+ *
+ * @category Conteúdo
+ * @status stable
+ * @slot default - Slot para os slides do carrossel. Aceita exclusivamente elementos `br-carousel-page`.
+ *
+ * @part container - Elemento raiz do carrossel. Recebe `role="region"` e `aria-roledescription="carousel"`.
+ * @part stage - Área do palco que contém os slides. Recebe `aria-live` e `aria-atomic`.
+ * @part nav-prev - Wrapper do botão de navegação para o slide anterior.
+ * @part nav-next - Wrapper do botão de navegação para o próximo slide.
+ * @part indicator - Wrapper do indicador de páginas.
+ *   - Quando `indicatorType="simple"`: renderiza `br-step` em `mode="tablist"`.
+ *   - Quando `indicatorType="textual"`: renderiza um `span[aria-live]` com "X/N".
+ * @part play-button - Wrapper do botão de play/pause. Presente apenas quando `autoPlay=true`.
+ */
+export class Carousel {
+    constructor() {
+        this.activePage = 0;
+        this.isPlaying = false;
+        /**
+         * `true` somente enquanto o timer de autoPlay está ativamente disparando.
+         * Difere de `isPlaying`: ao pausar por hover/foco, `isPlaying` permanece `true`
+         * mas `isRotating` torna-se `false`, liberando o `aria-live` para anunciar
+         * mudanças manuais de slide ao leitor de tela.
+         */
+        this.isRotating = false;
+        /** Lista de slides. Declarada como @State para que a reatribuição via slotchange acione re-render automaticamente. */
+        this.pages = [];
+        /**
+         * Identificador único do componente.
+         * Quando omitido, um valor é gerado automaticamente.
+         *
+         * > **Padrão:** valor único gerado por generateUniqueId().
+         *
+         */
+        this.customId = generateUniqueId();
+        /**
+         * Posição dos botões de navegação (prev/next) em relação ao palco.
+         * - `outside`: botões ficam nas laterais externas ao palco.
+         * - `inside`: botões ficam sobrepostos dentro do palco, ocupando toda a altura.
+         */
+        this.navPosition = 'outside';
+        /**
+         * Define o tipo de indicador de páginas renderizado.
+         * - `simple`: dots usando `br-step` em modo controller.
+         * - `textual`: texto "X/N" com `aria-live`.
+         * - `none`: sem indicador.
+         */
+        this.indicatorType = 'simple';
+        /**
+         * Posição do indicador de páginas em relação ao palco.
+         * Ignorada quando `indicatorType="none"`.
+         * - `outside`: indicador fica abaixo do palco.
+         * - `inside`: indicador fica sobreposto ao conteúdo.
+         */
+        this.indicatorPosition = 'outside';
+        /**
+         * Habilita a navegação circular entre os slides.
+         * Quando true, os botões "Anterior" e "Próximo" permanecem sempre habilitados: avançar a partir do último slide retorna ao primeiro, e retroceder a partir do primeiro leva ao último.
+         * Se autoPlay estiver ativado, o comportamento circular será aplicado automaticamente, independentemente deste valor.
+         * @deprecated Use `circular`.
+         */
+        this.isCircular = false;
+        /**
+         * Habilita reprodução automática.
+         * Pausa em hover e foco (W3C). Ativa o loop circular automaticamente.
+         * Não recomendado em dispositivos móveis.
+         * @deprecated Use `autoplay`.
+         */
+        this.autoPlay = false;
+        /**
+         * Intervalo em milissegundos entre cada avanço automático.
+         * Só tem efeito quando `autoPlay=true`.
+         */
+        this.interval = 5000;
+        /**
+         * Direção de navegação automática do carrossel.
+         * - `left`: retrocede (vai para o slide anterior).
+         * - `right`: avança (vai para o próximo slide).
+         * Só tem efeito quando `autoPlay=true`.
+         */
+        this.direction = 'right';
+        /**
+         * Exibe botões de navegação em dispositivos móveis.
+         * Por padrão os botões são ocultados no breakpoint `sm`.
+         */
+        this.mobileNav = false;
+        /**
+         * Ajuste aplicado a imagens filhas diretas de `br-carousel-page`.
+         */
+        this.imageFit = 'cover';
+        this.stepRef = null;
+        this.autoPlayTimer = null;
+        this.isPausedByFocus = false;
+        /** Rastreia se o cursor está sobre o carrossel (para evitar retomar ao sair do foco enquanto hover ativo). */
+        this.isHovering = false;
+        /** Quando true, o usuário iniciou explicitamente via botão — hover e foco não pausam a rotação. */
+        this.isUserExplicitlyPlaying = false;
+        this.stageRef = null;
+        this.carouselSwipe = null;
+        this.slotEl = null;
+        this.MOBILE_MQ = '(max-width: 576px)';
+        this.mobileMediaQuery = null;
+        /**
+         * Reatualiza a lista de slides e reinicializa os atributos quando o conteúdo
+         * do slot muda (slides adicionados ou removidos dinamicamente).
+         */
+        this.onSlotChange = () => {
+            this.pages = this.slideElements;
+            if (this.activePage >= this.pages.length) {
+                this.activePage = Math.max(0, this.pages.length - 1);
+            }
+            this.initPages();
+        };
+        this.onBreakpointChange = (e) => {
+            if (e.matches) {
+                this.setupSwipeListeners();
+            }
+            else {
+                this.cleanupSwipeListeners();
+            }
+        };
+        /** Handlers de eventos do DOM — mouse, foco e interação do usuário. */
+        this.onMouseEnter = () => {
+            this.isHovering = true;
+            // W3C: se o usuário iniciou explicitamente via botão, hover não pausa
+            if (this.isUserExplicitlyPlaying)
+                return;
+            if (this.isPlaying && !this.isPausedByFocus) {
+                this.isRotating = false;
+                this.clearTimer();
+            }
+        };
+        this.onMouseLeave = () => {
+            this.isHovering = false;
+            // W3C: se o usuário iniciou explicitamente via botão, hover não retoma (já está rodando)
+            if (this.isUserExplicitlyPlaying)
+                return;
+            if (this.effectiveAutoplay && this.isPlaying && !this.isPausedByFocus) {
+                this.isRotating = true;
+                this.scheduleInterval();
+            }
+        };
+        this.onFocusIn = () => {
+            // W3C: se o usuário iniciou explicitamente via botão, foco não pausa
+            if (this.isUserExplicitlyPlaying)
+                return;
+            if (this.isPlaying) {
+                this.isPausedByFocus = true;
+                this.isRotating = false;
+                this.clearTimer();
+            }
+        };
+        this.onFocusOut = (e) => {
+            if (this.el.contains(e.relatedTarget))
+                return;
+            if (this.isUserExplicitlyPlaying)
+                return;
+            if (!this.effectiveAutoplay || !this.isPausedByFocus)
+                return;
+            this.isPausedByFocus = false;
+            // W3C: não retoma se o cursor ainda está sobre o carrossel
+            if (this.isHovering)
+                return;
+            this.isRotating = true;
+            this.scheduleInterval();
+        };
+        /** Swipe — configuração e limpeza de gestos touch/pointer em mobile. */
+        this.onSwipeLeft = () => {
+            this.nextPage();
+        };
+        this.onSwipeRight = () => {
+            this.previousPage();
+        };
+        this.onStepChange = (e) => {
+            if (e.detail.activeStep !== this.activePage) {
+                this.goTo(e.detail.activeStep);
+            }
+        };
+        this.onPrevClick = () => {
+            this.previousPage();
+        };
+        this.onNextClick = () => {
+            this.nextPage();
+        };
+        this.onPlayToggle = () => {
+            this.isPlaying ? this.pause() : this.play();
+        };
+    }
+    onActivePageChange(newVal, oldVal) {
+        this.syncStepIndicator(newVal, oldVal);
+    }
+    disconnectedCallback() {
+        this.clearTimer();
+        this.cleanupSwipeListeners();
+        this.slotEl?.removeEventListener('slotchange', this.onSlotChange);
+        this.slotEl = null;
+        this.mobileMediaQuery?.removeEventListener('change', this.onBreakpointChange);
+        this.mobileMediaQuery = null;
+    }
+    componentWillLoad() {
+        this.pages = this.slideElements;
+        const initialActive = this.pages.findIndex((p) => p.hasAttribute('active'));
+        if (initialActive >= 0) {
+            this.activePage = initialActive;
+        }
+        if (this.effectiveAutoplay) {
+            this.initAutoPlay();
+        }
+    }
+    componentDidLoad() {
+        this.initPages();
+        this.slotEl = this.el.shadowRoot.querySelector('slot');
+        this.slotEl?.addEventListener('slotchange', this.onSlotChange);
+        this.mobileMediaQuery = window.matchMedia(this.MOBILE_MQ);
+        this.mobileMediaQuery.addEventListener('change', this.onBreakpointChange);
+        if (this.mobileMediaQuery.matches) {
+            this.setupSwipeListeners();
+        }
+        if (this.effectiveAutoplay && this.isPlaying) {
+            this.scheduleInterval();
+            this.brDidAutoPlayStart.emit();
+            this.brCarouselAutoplayStart.emit();
+        }
+    }
+    /**
+     * Navegação por teclado para o modo tablist (`indicatorType="simple"`).
+     *
+     * O W3C APG Carousel Pattern especifica que, quando os controles de seleção de slide
+     * são implementados como tabs, a interação de teclado segue o
+     * {@link https://www.w3.org/WAI/ARIA/apg/patterns/tabs/ Tabs Pattern (W3C APG)}.
+     * Esse padrão define o comportamento de roving tabindex com as teclas:
+     * - `ArrowLeft` / `ArrowRight` (ou `ArrowUp` / `ArrowDown`): move o foco entre as tabs.
+     * - `Home`: move o foco para a primeira tab.
+     * - `End`: move o foco para a última tab.
+     *
+     * O handler está no `br-carousel` (e não no `br-step`) porque a lógica de
+     * `effectiveCircular` é uma responsabilidade do carrossel, mantendo uma única
+     * fonte de verdade para a navegação circular.
+     *
+     * O evento `keydown` é composto (`composed: true`), portanto borbulha através do
+     * shadow DOM do `br-step-item` até o host do `br-carousel`.
+     */
+    onTablistKeydown(e) {
+        if (this.indicatorType !== 'simple' || this.stepRef === null)
+            return;
+        if (!isEventTargetInside(e, this.stepRef))
+            return;
+        if (!Carousel.NAVIGATION_KEYS.has(e.key))
+            return;
+        e.preventDefault();
+        const next = this.resolveTablistKeyIndex(e.key);
+        if (next === this.activePage)
+            return;
+        this.goTo(next);
+        this.focusStepItem(next);
+    }
+    /** Métodos públicos  */
+    /**
+     * Avança para o próximo slide. Respeita a prop `isCircular` (ou ativo automaticamente com `autoPlay`).
+     */
+    async nextPage() {
+        const next = this.activePage + 1;
+        if (next < this.pages.length) {
+            this.goTo(next);
+        }
+        else if (this.effectiveCircular) {
+            this.goTo(0);
+        }
+    }
+    /**
+     * Retorna ao slide anterior. Respeita a prop `isCircular` (ou ativo automaticamente com `autoPlay`).
+     */
+    async previousPage() {
+        const prev = this.activePage - 1;
+        if (prev >= 0) {
+            this.goTo(prev);
+        }
+        else if (this.effectiveCircular) {
+            this.goTo(this.pages.length - 1);
+        }
+    }
+    /**
+     * Navega para o slide de número `index` (1 = primeiro slide, 2 = segundo, …).
+     * Valores fora do intervalo válido são ignorados.
+     */
+    async goToPage(index) {
+        if (index >= 1 && index <= this.pages.length) {
+            this.goTo(index - 1);
+        }
+    }
+    /**
+     * Retorna o número do slide atualmente ativo (1 = primeiro slide, 2 = segundo, …).
+     */
+    async getActivePage() {
+        return this.activePage + 1;
+    }
+    /**
+     * Inicia ou retoma a reprodução automática programaticamente.
+     */
+    async play() {
+        if (!this.effectiveAutoplay)
+            return;
+        this.isPlaying = true;
+        this.isPausedByFocus = false;
+        // W3C: ao iniciar explicitamente via botão, hover e foco não devem pausar
+        this.isUserExplicitlyPlaying = true;
+        this.isRotating = true;
+        this.scheduleInterval();
+        this.brDidAutoPlayStart.emit();
+        this.brCarouselAutoplayStart.emit();
+    }
+    /**
+     * Pausa a reprodução automática programaticamente.
+     */
+    async pause() {
+        this.isPlaying = false;
+        this.isUserExplicitlyPlaying = false;
+        this.isRotating = false;
+        this.clearTimer();
+        this.brDidAutoPlayPause.emit();
+        this.brCarouselAutoplayPause.emit();
+    }
+    /**
+     * Retorna `true` se a reprodução automática está ativa no momento.
+     */
+    async getIsPlaying() {
+        return this.isPlaying;
+    }
+    /**
+     * Retorna os slides atribuídos ao slot do carrossel.
+     *
+     * Usa `slot.assignedElements()` quando o slot já está disponível (após `componentDidLoad`):
+     * a API retorna diretamente a lista interna do browser.
+     *
+     * Recorre a `querySelectorAll` apenas em `componentWillLoad`, quando o shadow DOM
+     * ainda não foi renderizado e `slotEl` é `null`.
+     */
+    get slideElements() {
+        if (this.slotEl !== null) {
+            return this.slotEl.assignedElements();
+        }
+        return Array.from(this.el.children).filter((el) => el.tagName.toLowerCase() === 'br-carousel-page');
+    }
+    initAutoPlay() {
+        const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+        this.isPlaying = !prefersReducedMotion;
+        this.isRotating = this.isPlaying;
+    }
+    /**
+     * Retorna o ID único de um slide pelo índice (0-based).
+     * Prioriza o `customId` definido no próprio `br-carousel-page`, quando presente.
+     * Caso contrário, gera automaticamente no formato `{carousel-id}-slide-{n}`.
+     * Usado para vincular `controls-id` das tabs ao `id` do tabpanel correspondente.
+     */
+    slideId(index) {
+        return this.pages[index]?.customId ?? `${this.customId}-slide-${index + 1}`;
+    }
+    /**
+     * Circular efetivo: ativo quando `isCircular=true` OU quando `autoPlay=true`.
+     * Usar este getter em toda a lógica interna em vez de `this.isCircular` diretamente.
+     */
+    get effectiveCircular() {
+        return (this.circular ?? this.isCircular) || this.effectiveAutoplay;
+    }
+    get effectiveAutoplay() {
+        return this.autoplay ?? this.autoPlay;
+    }
+    /**
+     * Reposiciona todos os slides inativos com base no índice ativo.
+     * Slides após o ativo ficam à direita (100%), antes ficam à esquerda (-100%).
+     */
+    positionSlides(activeIndex) {
+        this.pages.forEach((page, i) => {
+            if (i !== activeIndex) {
+                page.style.left = i > activeIndex ? '100%' : '-100%';
+            }
+        });
+    }
+    initPages() {
+        this.pages.forEach((page, i) => {
+            page.id || (page.id = this.slideId(i));
+            page.setLabel(`Slide ${i + 1} de ${this.pages.length}`);
+            page.setActive(i === this.activePage);
+        });
+        this.positionSlides(this.activePage);
+        this.syncStepIndicator();
+    }
+    goTo(index) {
+        const prev = this.activePage;
+        this.activePage = index;
+        this.positionSlides(index);
+        this.pages[prev]?.setActive(false);
+        this.pages[index]?.setActive(true);
+        const detail = { activePage: this.activePage + 1 };
+        this.brDidPageChange.emit(detail);
+        this.brCarouselPageChange.emit(detail);
+    }
+    /**
+     * Mantém o atributo `active` dos `br-step-item` filhos do `br-step` em sincronia
+     * com o slide ativo. Recebe o novo e o antigo índice para otimizar a atualização (removendo o atributo apenas do item anterior, em vez de iterar por todos os itens).
+     * Se `oldVal` for `null`, atualiza todos os itens (caso de inicialização ou mudança completa de slides).
+     */
+    syncStepIndicator(newVal = this.activePage, oldVal = null) {
+        if (this.stepRef === null)
+            return;
+        const items = this.stepRef.children;
+        if (oldVal !== null) {
+            items[oldVal]?.removeAttribute('active');
+            items[newVal]?.setAttribute('active', 'true');
+        }
+        else {
+            Array.from(items).forEach((item, i) => {
+                if (i === newVal) {
+                    item.setAttribute('active', 'true');
+                }
+                else {
+                    item.removeAttribute('active');
+                }
+            });
+        }
+    }
+    getDataStage() {
+        const { navPosition, indicatorPosition } = this;
+        if (navPosition === 'inside' && indicatorPosition === 'inside')
+            return 'in';
+        if (navPosition === 'inside')
+            return 'hibw';
+        if (indicatorPosition === 'inside')
+            return 'hibh';
+        return 'out';
+    }
+    scheduleInterval() {
+        if (this.autoPlayTimer !== null) {
+            clearInterval(this.autoPlayTimer);
+            this.autoPlayTimer = null;
+        }
+        this.autoPlayTimer = setInterval(() => {
+            if (this.direction === 'left') {
+                this.previousPage();
+            }
+            else {
+                this.nextPage();
+            }
+        }, this.interval);
+    }
+    clearTimer() {
+        if (this.autoPlayTimer !== null) {
+            clearInterval(this.autoPlayTimer);
+            this.autoPlayTimer = null;
+        }
+    }
+    get isPrevDisabled() {
+        return !this.effectiveCircular && this.activePage === 0;
+    }
+    get isNextDisabled() {
+        return !this.effectiveCircular && this.activePage === this.pages.length - 1;
+    }
+    setupSwipeListeners() {
+        if (this.stageRef === null)
+            return;
+        this.carouselSwipe = new UniversalSwipe(this.stageRef, { direction: 'horizontal' });
+        this.carouselSwipe.on('SWIPE_LEFT', this.onSwipeLeft);
+        this.carouselSwipe.on('SWIPE_RIGHT', this.onSwipeRight);
+    }
+    cleanupSwipeListeners() {
+        if (this.carouselSwipe !== null) {
+            this.carouselSwipe.off('SWIPE_LEFT', this.onSwipeLeft);
+            this.carouselSwipe.off('SWIPE_RIGHT', this.onSwipeRight);
+            this.carouselSwipe.destroy();
+            this.carouselSwipe = null;
+        }
+    }
+    /**
+     * Calcula o índice alvo com base na tecla pressionada no modo tablist.
+     */
+    resolveTablistKeyIndex(key) {
+        const total = this.pages.length;
+        switch (key) {
+            case 'ArrowLeft':
+            case 'ArrowUp':
+                if (this.activePage > 0)
+                    return this.activePage - 1;
+                return this.effectiveCircular ? total - 1 : this.activePage;
+            case 'ArrowRight':
+            case 'ArrowDown':
+                if (this.activePage < total - 1)
+                    return this.activePage + 1;
+                return this.effectiveCircular ? 0 : this.activePage;
+            case 'Home':
+                return 0;
+            case 'End':
+                return total - 1;
+            default:
+                return this.activePage;
+        }
+    }
+    /**
+     * Move o foco para o `br-step-item` de índice `index`.
+     *
+     * Em modo tablist, a semântica ARIA (`role="tab"`, `tabIndex`, `aria-selected`) é
+     * aplicada diretamente no host do `br-step-item` — não no botão interno, que fica
+     * inerte. Por isso o foco vai para o próprio host, e o ring visual é controlado
+     * via `:host(.role-tab:focus-visible)` no CSS do componente.
+     */
+    focusStepItem(index) {
+        const targetItem = this.stepRef.children[index];
+        if (targetItem === null)
+            return;
+        requestAnimationFrame(() => {
+            if (typeof targetItem.focus === 'function')
+                targetItem.focus();
+        });
+    }
+    getCssClassMap() {
+        return {
+            'br-carousel': true,
+            'dark-mode': this.colorMode === 'dark',
+            inverted: this.colorMode === 'dark',
+        };
+    }
+    getHostStyle() {
+        return {
+            ...(this.minHeight !== undefined ? { '--carousel-min-height': this.minHeight } : {}),
+            '--carousel-page-image-fit': this.imageFit,
+            ...(this.height !== undefined ? { height: this.height } : {}),
+            ...(this.maxWidth !== undefined ? { marginInline: 'auto', maxWidth: this.maxWidth } : {}),
+        };
+    }
+    renderPlayButton() {
+        const label = this.isPlaying
+            ? 'Parar Apresentação Automática de Slides'
+            : 'Iniciar Apresentação Automática de Slides';
+        const icon = this.isPlaying ? 'pause' : 'play';
+        return (h("div", { part: "play-button", class: "carousel-play-button" }, h("br-button", { shape: "circle", emphasis: "tertiary", "aria-label": label, onClick: this.onPlayToggle }, h("br-icon", { iconName: `fa6-solid:${icon}`, width: "16", height: "16" }))));
+    }
+    renderNavButton(direction) {
+        const isPrev = direction === 'prev';
+        return (h("div", { part: isPrev ? 'nav-prev' : 'nav-next', class: "carousel-button" }, h("br-button", { class: isPrev ? 'carousel-btn-prev' : 'carousel-btn-next', shape: this.navPosition === 'outside' ? 'circle' : undefined, emphasis: "tertiary", "aria-label": isPrev ? 'Anterior' : 'Próximo', "aria-controls": `${this.customId}-stage`, disabled: isPrev ? this.isPrevDisabled : this.isNextDisabled, onClick: isPrev ? this.onPrevClick : this.onNextClick }, h("br-icon", { iconName: `fa6-solid:chevron-${isPrev ? 'left' : 'right'}`, width: "16", height: "16" }))));
+    }
+    renderIndicator() {
+        if (this.indicatorType === 'none')
+            return null;
+        return (h("div", { part: "indicator", class: "carousel-step" }, this.indicatorType === 'simple' && (h("br-step", { mode: "controller", "color-mode": this.colorMode, ref: (el) => (this.stepRef = el), onBrStepChange: this.onStepChange }, this.pages.map((page, i) => (h("br-step-item", { key: page.id || this.slideId(i), "aria-label": `Slide ${i + 1} de ${this.pages.length}`, "controls-id": this.slideId(i) }))))), this.indicatorType === 'textual' && (h("span", { "aria-live": this.isRotating ? 'off' : 'polite', "aria-atomic": "true", class: "carousel-page-text" }, this.activePage + 1, "/", this.pages.length))));
+    }
+    render() {
+        const dataStage = this.getDataStage();
+        return (h(Host, { key: 'f6fcc04e92f6abaa2d276dd03cb1144c1c9ccca9', style: this.getHostStyle() }, h("div", { key: '0c46599b2c345b332a3eea55eff524c66632f230', id: this.customId, part: "container", class: this.getCssClassMap(), "data-stage": dataStage, "data-mobile-nav": this.mobileNav ? '' : undefined, role: "region", "aria-label": this.ariaLabel, "aria-roledescription": "carousel", onMouseEnter: this.onMouseEnter, onMouseLeave: this.onMouseLeave, onFocusin: this.onFocusIn, onFocusout: this.onFocusOut }, this.effectiveAutoplay && this.renderPlayButton(), this.renderNavButton('prev'), h("div", { key: 'eb7e2972f7fb22c793427b687656fd3bc4ea8465', id: `${this.customId}-stage`, part: "stage", class: "carousel-stage", "aria-live": this.isRotating ? 'off' : 'polite', "aria-atomic": "false", ref: (el) => (this.stageRef = el) }, h("slot", { key: 'c096859d97085715846463c80aaf68eaa599d331' })), this.renderNavButton('next'), this.renderIndicator())));
+    }
+    static get is() { return "br-carousel"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["carousel.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["carousel.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "customId": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Identificador \u00FAnico do componente.\nQuando omitido, um valor \u00E9 gerado automaticamente.\n\n> **Padr\u00E3o:** valor \u00FAnico gerado por generateUniqueId()."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "custom-id",
+                "defaultValue": "generateUniqueId()"
+            },
+            "ariaLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "R\u00F3tulo acess\u00EDvel do carrossel.\nN\u00E3o deve conter a palavra \"carrossel\" (W3C APG).\nAtribu\u00EDdo ao `aria-label` do container raiz."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "aria-label"
+            },
+            "navPosition": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "CarouselNavPosition",
+                    "resolved": "\"inside\" | \"outside\"",
+                    "references": {
+                        "CarouselNavPosition": {
+                            "location": "import",
+                            "path": "./carousel.types",
+                            "id": "src/components/carousel/carousel.types.ts::CarouselNavPosition",
+                            "referenceLocation": "CarouselNavPosition"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Posi\u00E7\u00E3o dos bot\u00F5es de navega\u00E7\u00E3o (prev/next) em rela\u00E7\u00E3o ao palco.\n- `outside`: bot\u00F5es ficam nas laterais externas ao palco.\n- `inside`: bot\u00F5es ficam sobrepostos dentro do palco, ocupando toda a altura."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "nav-position",
+                "defaultValue": "'outside'"
+            },
+            "indicatorType": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "CarouselIndicatorType",
+                    "resolved": "\"none\" | \"simple\" | \"textual\"",
+                    "references": {
+                        "CarouselIndicatorType": {
+                            "location": "import",
+                            "path": "./carousel.types",
+                            "id": "src/components/carousel/carousel.types.ts::CarouselIndicatorType",
+                            "referenceLocation": "CarouselIndicatorType"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Define o tipo de indicador de p\u00E1ginas renderizado.\n- `simple`: dots usando `br-step` em modo controller.\n- `textual`: texto \"X/N\" com `aria-live`.\n- `none`: sem indicador."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "indicator-type",
+                "defaultValue": "'simple'"
+            },
+            "indicatorPosition": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "CarouselIndicatorPosition",
+                    "resolved": "\"inside\" | \"outside\"",
+                    "references": {
+                        "CarouselIndicatorPosition": {
+                            "location": "import",
+                            "path": "./carousel.types",
+                            "id": "src/components/carousel/carousel.types.ts::CarouselIndicatorPosition",
+                            "referenceLocation": "CarouselIndicatorPosition"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Posi\u00E7\u00E3o do indicador de p\u00E1ginas em rela\u00E7\u00E3o ao palco.\nIgnorada quando `indicatorType=\"none\"`.\n- `outside`: indicador fica abaixo do palco.\n- `inside`: indicador fica sobreposto ao conte\u00FAdo."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "indicator-position",
+                "defaultValue": "'outside'"
+            },
+            "isCircular": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `circular`."
+                        }],
+                    "text": "Habilita a navega\u00E7\u00E3o circular entre os slides.\nQuando true, os bot\u00F5es \"Anterior\" e \"Pr\u00F3ximo\" permanecem sempre habilitados: avan\u00E7ar a partir do \u00FAltimo slide retorna ao primeiro, e retroceder a partir do primeiro leva ao \u00FAltimo.\nSe autoPlay estiver ativado, o comportamento circular ser\u00E1 aplicado automaticamente, independentemente deste valor."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "is-circular",
+                "defaultValue": "false"
+            },
+            "circular": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Habilita navega\u00E7\u00E3o circular. Quando informada, tem preced\u00EAncia sobre `isCircular`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "circular"
+            },
+            "autoPlay": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `autoplay`."
+                        }],
+                    "text": "Habilita reprodu\u00E7\u00E3o autom\u00E1tica.\nPausa em hover e foco (W3C). Ativa o loop circular automaticamente.\nN\u00E3o recomendado em dispositivos m\u00F3veis."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "auto-play",
+                "defaultValue": "false"
+            },
+            "autoplay": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Habilita reprodu\u00E7\u00E3o autom\u00E1tica. Quando informada, tem preced\u00EAncia sobre `autoPlay`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "autoplay"
+            },
+            "interval": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Intervalo em milissegundos entre cada avan\u00E7o autom\u00E1tico.\nS\u00F3 tem efeito quando `autoPlay=true`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "interval",
+                "defaultValue": "5000"
+            },
+            "direction": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "CarouselDirection",
+                    "resolved": "\"left\" | \"right\"",
+                    "references": {
+                        "CarouselDirection": {
+                            "location": "import",
+                            "path": "./carousel.types",
+                            "id": "src/components/carousel/carousel.types.ts::CarouselDirection",
+                            "referenceLocation": "CarouselDirection"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Dire\u00E7\u00E3o de navega\u00E7\u00E3o autom\u00E1tica do carrossel.\n- `left`: retrocede (vai para o slide anterior).\n- `right`: avan\u00E7a (vai para o pr\u00F3ximo slide).\nS\u00F3 tem efeito quando `autoPlay=true`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "direction",
+                "defaultValue": "'right'"
+            },
+            "colorMode": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "CarouselColorMode",
+                    "resolved": "\"dark\"",
+                    "references": {
+                        "CarouselColorMode": {
+                            "location": "import",
+                            "path": "./carousel.types",
+                            "id": "src/components/carousel/carousel.types.ts::CarouselColorMode",
+                            "referenceLocation": "CarouselColorMode"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Aplica esquema de cores escuro ao componente."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "color-mode"
+            },
+            "mobileNav": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Exibe bot\u00F5es de navega\u00E7\u00E3o em dispositivos m\u00F3veis.\nPor padr\u00E3o os bot\u00F5es s\u00E3o ocultados no breakpoint `sm`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "mobile-nav",
+                "defaultValue": "false"
+            },
+            "minHeight": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Altura m\u00EDnima do palco do carrossel.\nAceita qualquer valor CSS v\u00E1lido para `min-height` (ex.: `400px`, `50vh`)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "min-height"
+            },
+            "height": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Altura do carrossel.\nAceita qualquer valor CSS v\u00E1lido para `height` (ex.: `400px`, `50vh`)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "height"
+            },
+            "maxWidth": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Largura m\u00E1xima do carrossel.\nQuando definido, o componente \u00E9 centralizado horizontalmente.\nAceita qualquer valor CSS v\u00E1lido para `max-width` (ex.: `800px`, `64rem`)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "max-width"
+            },
+            "imageFit": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "CarouselImageFit",
+                    "resolved": "\"contain\" | \"cover\" | \"fill\" | \"none\" | \"scale-down\"",
+                    "references": {
+                        "CarouselImageFit": {
+                            "location": "import",
+                            "path": "./carousel.types",
+                            "id": "src/components/carousel/carousel.types.ts::CarouselImageFit",
+                            "referenceLocation": "CarouselImageFit"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Ajuste aplicado a imagens filhas diretas de `br-carousel-page`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "image-fit",
+                "defaultValue": "'cover'"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "activePage": {},
+            "isPlaying": {},
+            "isRotating": {},
+            "pages": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "brDidPageChange",
+                "name": "brDidPageChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitido quando o slide ativo muda.\nDisparado por clique nos bot\u00F5es de navega\u00E7\u00E3o, clique no indicador de step,\ngesto swipe (apenas em mobile, breakpoint < 576px) ou avan\u00E7o autom\u00E1tico.\n`activePage` \u00E9 1-based: o primeiro slide emite `1`, o segundo `2`, e assim por diante."
+                },
+                "complexType": {
+                    "original": "CarouselPageChangeDetail",
+                    "resolved": "{ activePage: number; }",
+                    "references": {
+                        "CarouselPageChangeDetail": {
+                            "location": "import",
+                            "path": "./carousel.types",
+                            "id": "src/components/carousel/carousel.types.ts::CarouselPageChangeDetail",
+                            "referenceLocation": "CarouselPageChangeDetail"
+                        }
+                    }
+                }
+            }, {
+                "method": "brCarouselPageChange",
+                "name": "brCarouselPageChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Evento can\u00F4nico emitido quando o slide ativo muda."
+                },
+                "complexType": {
+                    "original": "CarouselPageChangeDetail",
+                    "resolved": "{ activePage: number; }",
+                    "references": {
+                        "CarouselPageChangeDetail": {
+                            "location": "import",
+                            "path": "./carousel.types",
+                            "id": "src/components/carousel/carousel.types.ts::CarouselPageChangeDetail",
+                            "referenceLocation": "CarouselPageChangeDetail"
+                        }
+                    }
+                }
+            }, {
+                "method": "brDidAutoPlayStart",
+                "name": "brDidAutoPlayStart",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitido quando a reprodu\u00E7\u00E3o autom\u00E1tica \u00E9 iniciada ou retomada."
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "brCarouselAutoplayStart",
+                "name": "brCarouselAutoplayStart",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Evento can\u00F4nico emitido quando a reprodu\u00E7\u00E3o autom\u00E1tica come\u00E7a."
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "brDidAutoPlayPause",
+                "name": "brDidAutoPlayPause",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitido quando a reprodu\u00E7\u00E3o autom\u00E1tica \u00E9 pausada."
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "brCarouselAutoplayPause",
+                "name": "brCarouselAutoplayPause",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Evento can\u00F4nico emitido quando a reprodu\u00E7\u00E3o autom\u00E1tica \u00E9 pausada."
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }];
+    }
+    static get methods() {
+        return {
+            "nextPage": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Avan\u00E7a para o pr\u00F3ximo slide. Respeita a prop `isCircular` (ou ativo automaticamente com `autoPlay`).",
+                    "tags": []
+                }
+            },
+            "previousPage": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Retorna ao slide anterior. Respeita a prop `isCircular` (ou ativo automaticamente com `autoPlay`).",
+                    "tags": []
+                }
+            },
+            "goToPage": {
+                "complexType": {
+                    "signature": "(index: number) => Promise<void>",
+                    "parameters": [{
+                            "name": "index",
+                            "type": "number",
+                            "docs": ""
+                        }],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Navega para o slide de n\u00FAmero `index` (1 = primeiro slide, 2 = segundo, \u2026).\nValores fora do intervalo v\u00E1lido s\u00E3o ignorados.",
+                    "tags": []
+                }
+            },
+            "getActivePage": {
+                "complexType": {
+                    "signature": "() => Promise<number>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<number>"
+                },
+                "docs": {
+                    "text": "Retorna o n\u00FAmero do slide atualmente ativo (1 = primeiro slide, 2 = segundo, \u2026).",
+                    "tags": []
+                }
+            },
+            "play": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Inicia ou retoma a reprodu\u00E7\u00E3o autom\u00E1tica programaticamente.",
+                    "tags": []
+                }
+            },
+            "pause": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Pausa a reprodu\u00E7\u00E3o autom\u00E1tica programaticamente.",
+                    "tags": []
+                }
+            },
+            "getIsPlaying": {
+                "complexType": {
+                    "signature": "() => Promise<boolean>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<boolean>"
+                },
+                "docs": {
+                    "text": "Retorna `true` se a reprodu\u00E7\u00E3o autom\u00E1tica est\u00E1 ativa no momento.",
+                    "tags": []
+                }
+            }
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "activePage",
+                "methodName": "onActivePageChange"
+            }];
+    }
+    static get listeners() {
+        return [{
+                "name": "keydown",
+                "method": "onTablistKeydown",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }];
+    }
+}
+Carousel.NAVIGATION_KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End']);