acai-ui 1.65.5

package/src/components/help/acai-ui-tour.vue

@@ -0,0 +1,766 @@
+<template>
+  <teleport to="body">
+    <div v-if="aberto" class="acaitour" :class="{ 'acaitour--estatico': semAnimacao }">
+      <!-- CAMADA 1 — visual. `pointer-events: none`: quem bloqueia clique são as
+           divs da camada 2, porque SVG com máscara não recorta área de clique. -->
+      <svg class="acaitour__overlay" aria-hidden="true" focusable="false">
+        <defs>
+          <mask :id="idMascara">
+            <rect x="0" y="0" width="100%" height="100%" fill="white" />
+            <rect
+              v-if="recorte"
+              :x="recorte.left"
+              :y="recorte.top"
+              :width="recorte.width"
+              :height="recorte.height"
+              :rx="RAIO_RECORTE"
+              fill="black"
+            />
+          </mask>
+        </defs>
+        <rect
+          class="acaitour__tinta"
+          x="0"
+          y="0"
+          width="100%"
+          height="100%"
+          :mask="`url(#${idMascara})`"
+        />
+        <!-- Aro do recorte: em alto contraste o escurecimento sozinho não
+             comunica "é aqui" (eMAG 4.1). -->
+        <rect
+          v-if="recorte"
+          class="acaitour__aro"
+          :x="recorte.left"
+          :y="recorte.top"
+          :width="recorte.width"
+          :height="recorte.height"
+          :rx="RAIO_RECORTE"
+          fill="none"
+        />
+      </svg>
+
+      <!-- CAMADA 2 — bloqueio de clique. Cerca o recorte por fora; a peça
+           `centro` só entra quando o passo NÃO é interativo. -->
+      <div
+        v-for="bloqueio in bloqueios"
+        :key="bloqueio.nome"
+        class="acaitour__bloqueio"
+        :style="bloqueio.estilo"
+      />
+
+      <!-- CAMADA 3 — o coach mark. -->
+      <div
+        ref="balaoRef"
+        class="acaitour__balao"
+        :class="[`acaitour__balao--${posicao.side}`, { 'acaitour__balao--solto': !recorte }]"
+        :style="{ top: `${posicao.top}px`, left: `${posicao.left}px`, opacity: pronto ? 1 : 0 }"
+        role="dialog"
+        aria-modal="true"
+        :aria-labelledby="idTitulo"
+        :aria-describedby="idTexto"
+        :aria-busy="buscando ? 'true' : undefined"
+        tabindex="-1"
+      >
+        <span v-if="recorte" class="acaitour__seta" :style="estiloSeta" aria-hidden="true" />
+
+        <header class="acaitour__cab">
+          <h2 :id="idTitulo" class="acaitour__titulo">
+            {{ passoAtual?.title || tituloTour }}
+          </h2>
+          <button
+            v-if="mostrarAudio"
+            type="button"
+            class="acaitour__ouvir"
+            :aria-pressed="lendoPasso"
+            aria-label="Ouvir este passo"
+            @click="alternarPasso"
+          >
+            <acai-ui-icon :name="lendoPasso ? 'stop' : 'volume_up'" size="md" decorative />
+          </button>
+          <button
+            type="button"
+            class="acaitour__fechar"
+            :aria-label="`Sair de ${tituloTour}`"
+            @click="sair"
+          >
+            <!-- md=16px (escala de espaços): sm=8px sumia no botão de 28px. -->
+            <acai-ui-icon name="close" size="md" />
+          </button>
+        </header>
+
+        <p :id="idTexto" class="acaitour__texto">{{ passoAtual?.text }}</p>
+
+        <footer class="acaitour__rodape">
+          <div class="acaitour__pontos" aria-hidden="true">
+            <span
+              v-for="(_, indice) in passos"
+              :key="indice"
+              class="acaitour__ponto"
+              :class="{ 'acaitour__ponto--ativo': indice === indiceAtual }"
+            />
+          </div>
+
+          <span class="acaitour__contador">Passo {{ indiceAtual + 1 }} de {{ passos.length }}</span>
+
+          <!-- Enquanto procura o alvo, o balão DIZ que está procurando e dá
+               saída — antes disso "esperando" e "travado" eram a mesma tela. -->
+          <div v-if="buscando" class="acaitour__acoes acaitour__busca">
+            <span class="acaitour__busca-giro" aria-hidden="true" />
+            <span class="acaitour__busca-texto">Procurando…</span>
+            <acai-ui-button flat dense color="primary" label="Pular" @click="pularBusca" />
+          </div>
+
+          <div v-else class="acaitour__acoes">
+            <acai-ui-button
+              v-if="indiceAtual > 0"
+              flat
+              dense
+              color="primary"
+              label="Anterior"
+              @click="anterior"
+            />
+            <acai-ui-button
+              dense
+              color="primary"
+              :label="ehUltimo ? 'Concluir' : 'Próximo'"
+              @click="proximo"
+            />
+          </div>
+        </footer>
+      </div>
+
+      <!-- eMAG: leitor de tela anuncia a troca de passo sem roubar o foco. -->
+      <div class="acaitour__anuncio" role="status" aria-live="polite">{{ anuncio }}</div>
+    </div>
+  </teleport>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue'
+import AcaiUiButton from '../button/acai-ui-button.vue'
+import AcaiUiIcon from '../icon/acai-ui-icon.vue'
+import { usePreferencias } from '../../hooks/use-preferencias'
+import { useLeituraVoz } from '../../hooks/use-leitura-voz'
+import { scrollParaElemento } from '../../utils/scroll-elemento'
+import {
+  ESPERA_PADRAO,
+  aguardarAlvo,
+  descreverAncora,
+  passoSemAncora,
+  resolverAlvo,
+} from './tour-registry'
+import {
+  centralizarBalao,
+  expandirRecorte,
+  posicionarBalao,
+  type Viewport,
+} from './tour-posicionar'
+import type {
+  BalloonPosition,
+  SpotlightRect,
+  TourProps,
+  TourSkip,
+  TourSkipReason,
+  TourStep,
+} from './acai-ui-help-interface'
+
+const props = withDefaults(defineProps<TourProps>(), { startAt: 0 })
+
+const emits = defineEmits<{
+  /** Chegou ao fim pelo botão "Concluir". */
+  (e: 'finish'): void
+  /** Saiu antes do fim (Esc, X ou fora de passos). */
+  (e: 'exit'): void
+  /** Trocou de passo — índice 0-based. */
+  (e: 'step', indice: number): void
+  /**
+   * Um passo não pôde ser mostrado. Emitido SEMPRE (o `console.warn` fica só
+   * em DEV): é por aqui que o consumidor instrumenta o tour em produção e
+   * descobre que metade dele desapareceu.
+   */
+  (e: 'step-skipped', info: TourSkip): void
+}>()
+
+const aberto = defineModel<boolean>({ default: false })
+
+/** Folga padrão do recorte, em px. */
+const PADDING_PADRAO = 8
+/** Cantos do buraco — casa com o `$radius-lg` dos cards. */
+const RAIO_RECORTE = 8
+
+// `Math.random` aqui é só pra evitar colisão de id de máscara SVG quando dois
+// tours coexistem (docs com dois exemplos na mesma página).
+const sufixo = Math.random().toString(36).slice(2, 8)
+const idMascara = `acaitour-mask-${sufixo}`
+const idTitulo = `acaitour-titulo-${sufixo}`
+const idTexto = `acaitour-texto-${sufixo}`
+
+const { preferencias } = usePreferencias()
+
+// ===================== Leitura em voz alta =====================
+const {
+  suportado: vozSuportada,
+  temVozPara,
+  vozes,
+  idLendo,
+  alternar: alternarFala,
+  parar: pararFala,
+} = useLeituraVoz()
+
+const idFalaPasso = `acaitour-voz-${sufixo}`
+const idiomaFala = computed(() => props.audioLang || 'pt-BR')
+
+/** Precedência: prop da tela > preferência do usuário > suporte > voz do idioma. */
+const mostrarAudio = computed(() => {
+  void vozes.value
+  return (
+    vozSuportada.value &&
+    !props.hideAudio &&
+    preferencias.leituraVoz &&
+    temVozPara(idiomaFala.value)
+  )
+})
+
+const lendoPasso = computed(() => idLendo.value === idFalaPasso)
+
+function alternarPasso(): void {
+  const passo = passos.value[indiceAtual.value]
+  if (!passo) return
+  // Sem "Passo N de M": o contador está na tela e o leitor de tela já anuncia —
+  // repetir em voz vira ruído a cada passo.
+  const texto = [passo.title, passo.text].filter(Boolean).join('. ')
+  alternarFala(texto, {
+    id: idFalaPasso,
+    lang: idiomaFala.value,
+    voz: preferencias.vozNome,
+    rate: preferencias.vozVelocidade,
+  })
+}
+
+/**
+ * Quanto o tour espera antes de ADMITIR que está procurando. Abaixo disso a
+ * troca de passo é percebida como instantânea e o aviso só piscaria.
+ */
+const ESPERA_ATE_AVISAR = 350
+
+const indiceAtual = ref(0)
+const alvoEl = ref<HTMLElement | null>(null)
+const recorte = ref<SpotlightRect | null>(null)
+const posicao = ref<BalloonPosition>({ top: 0, left: 0, side: 'bottom' })
+const pronto = ref(false)
+const anuncio = ref('')
+const balaoRef = ref<HTMLElement | null>(null)
+/** Está esperando um alvo aparecer — o balão para de fingir que nada acontece. */
+const buscando = ref(false)
+
+/** Quem tinha o foco antes do tour — devolvemos no fim (eMAG 4.3). */
+let focoAnterior: HTMLElement | null = null
+/** Direção da navegação: define pra que lado pular um passo sem alvo. */
+let direcao: 1 | -1 = 1
+let frameAgendado = 0
+let observador: ResizeObserver | null = null
+/**
+ * Cada abertura é uma sessão. Uma busca que termina depois do tour fechar (ou
+ * depois de um `irPara` mais novo) não pode voltar e aplicar um passo velho.
+ */
+let sessao = 0
+let controleBusca: AbortController | null = null
+let temporizadorAviso = 0
+let buscaCancelada = false
+/** Desfaz a escuta do passo interativo da vez. */
+let desescutarAlvo: (() => void) | null = null
+
+const passos = computed<TourStep[]>(() => props.tour.steps ?? [])
+const passoAtual = computed<TourStep | undefined>(() => passos.value[indiceAtual.value])
+const ehUltimo = computed(() => indiceAtual.value >= passos.value.length - 1)
+const tituloTour = computed(() => props.tour.title || 'Aprenda a usar')
+
+const semAnimacao = computed(() => {
+  if (preferencias.reduzirAnimacoes) return true
+  if (typeof window === 'undefined' || !window.matchMedia) return false
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches
+})
+
+function janela(): Viewport {
+  return { width: window.innerWidth, height: window.innerHeight }
+}
+
+/**
+ * As divs que impedem o clique fora do recorte. São 4 faixas cercando o buraco
+ * (e não um retângulo furado) porque CSS não recorta área de clique; com
+ * `interactive` a peça do centro simplesmente não é renderizada e o clique
+ * chega ao elemento.
+ */
+const bloqueios = computed(() => {
+  const r = recorte.value
+  if (!r) return [{ nome: 'tudo', estilo: { inset: '0' } }]
+
+  const faixas = [
+    { nome: 'topo', estilo: { top: '0', left: '0', right: '0', height: `${r.top}px` } },
+    {
+      nome: 'base',
+      estilo: { top: `${r.top + r.height}px`, left: '0', right: '0', bottom: '0' },
+    },
+    {
+      nome: 'esquerda',
+      estilo: { top: `${r.top}px`, left: '0', width: `${r.left}px`, height: `${r.height}px` },
+    },
+    {
+      nome: 'direita',
+      estilo: {
+        top: `${r.top}px`,
+        left: `${r.left + r.width}px`,
+        right: '0',
+        height: `${r.height}px`,
+      },
+    },
+  ]
+
+  if (passoAtual.value?.interactive) return faixas
+
+  return [
+    ...faixas,
+    {
+      nome: 'centro',
+      estilo: {
+        top: `${r.top}px`,
+        left: `${r.left}px`,
+        width: `${r.width}px`,
+        height: `${r.height}px`,
+      },
+    },
+  ]
+})
+
+/** Deslocamento da setinha pro centro do recorte, mesmo com o balão deslocado. */
+const estiloSeta = computed(() => {
+  const r = recorte.value
+  if (!r) return {}
+  const lado = posicao.value.side
+
+  if (lado === 'top' || lado === 'bottom') {
+    const centro = r.left + r.width / 2 - posicao.value.left
+    return { left: `${centro}px` }
+  }
+
+  const centro = r.top + r.height / 2 - posicao.value.top
+  return { top: `${centro}px` }
+})
+
+/**
+ * Recalcula recorte e balão. Roda a cada frame em que algo pode ter mexido:
+ * scroll (inclusive o do `.q-page.container-page`), resize e mudança de
+ * tamanho do alvo. Sem isso o buraco descola do elemento ao rolar a página.
+ */
+function medir(): void {
+  const vp = janela()
+  const balao = balaoRef.value?.getBoundingClientRect()
+  const tamanhoBalao = { width: balao?.width || 320, height: balao?.height || 160 }
+
+  if (!alvoEl.value) {
+    recorte.value = null
+    posicao.value = centralizarBalao(tamanhoBalao, vp)
+    pronto.value = true
+    return
+  }
+
+  const r = alvoEl.value.getBoundingClientRect()
+  const bruto: SpotlightRect = { top: r.top, left: r.left, width: r.width, height: r.height }
+  const padding = passoAtual.value?.padding ?? PADDING_PADRAO
+
+  recorte.value = expandirRecorte(bruto, padding, vp)
+  posicao.value = posicionarBalao(
+    recorte.value,
+    tamanhoBalao,
+    vp,
+    passoAtual.value?.placement ?? 'auto',
+  )
+  pronto.value = true
+}
+
+function agendarMedicao(): void {
+  if (frameAgendado) return
+  frameAgendado = requestAnimationFrame(() => {
+    frameAgendado = 0
+    medir()
+  })
+}
+
+/**
+ * Scroll manual TRAVADO durante o tour, de propósito: o usuário fica com o
+ * foco exatamente no que o passo ilumina e é o TOUR quem rola a página (o
+ * `scrollParaElemento` de cada passo). Sem isso, uma rolada de dedo tira o
+ * elemento do recorte e a explicação fica apontando pro nada.
+ * `preventDefault` exige listener não-passivo.
+ */
+function bloquearScrollManual(evento: Event): void {
+  // Rolagem DENTRO do balão (texto longo em tela baixa) continua permitida.
+  if (evento.target instanceof Node && balaoRef.value?.contains(evento.target)) return
+  evento.preventDefault()
+}
+
+function ligarObservadores(): void {
+  window.addEventListener('resize', agendarMedicao)
+  // `capture: true` é o que faz o scroll do `.q-page.container-page` chegar
+  // aqui — evento de scroll não borbulha, só desce na captura. (Programático
+  // dispara `scroll` do mesmo jeito, então a medição acompanha o auto-scroll.)
+  window.addEventListener('scroll', agendarMedicao, { capture: true, passive: true })
+  document.addEventListener('keydown', aoTeclar, true)
+  document.addEventListener('wheel', bloquearScrollManual, { capture: true, passive: false })
+  document.addEventListener('touchmove', bloquearScrollManual, { capture: true, passive: false })
+
+  if (typeof ResizeObserver !== 'undefined') {
+    observador = new ResizeObserver(agendarMedicao)
+    observador.observe(document.body)
+  }
+}
+
+function desligarObservadores(): void {
+  window.removeEventListener('resize', agendarMedicao)
+  window.removeEventListener('scroll', agendarMedicao, { capture: true })
+  document.removeEventListener('keydown', aoTeclar, true)
+  document.removeEventListener('wheel', bloquearScrollManual, { capture: true })
+  document.removeEventListener('touchmove', bloquearScrollManual, { capture: true })
+  observador?.disconnect()
+  observador = null
+  if (frameAgendado) cancelAnimationFrame(frameAgendado)
+  frameAgendado = 0
+}
+
+const SELETOR_FOCAVEL =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+function focaveis(): HTMLElement[] {
+  const doBalao = balaoRef.value
+    ? [...balaoRef.value.querySelectorAll<HTMLElement>(SELETOR_FOCAVEL)]
+    : []
+
+  // Num passo interativo o alvo entra no ciclo do Tab — senão o usuário não
+  // consegue fazer, só teclado, o que o passo está mandando fazer (eMAG 2.1).
+  if (!passoAtual.value?.interactive || !alvoEl.value) return doBalao
+
+  const doAlvo = alvoEl.value.matches(SELETOR_FOCAVEL)
+    ? [alvoEl.value]
+    : [...alvoEl.value.querySelectorAll<HTMLElement>(SELETOR_FOCAVEL)]
+
+  return [...doAlvo, ...doBalao]
+}
+
+function ehCampoDeTexto(el: EventTarget | null): boolean {
+  if (!(el instanceof HTMLElement)) return false
+  if (el.isContentEditable) return true
+  return ['INPUT', 'TEXTAREA', 'SELECT'].includes(el.tagName)
+}
+
+function aoTeclar(evento: KeyboardEvent): void {
+  if (!aberto.value) return
+
+  if (evento.key === 'Escape') {
+    evento.preventDefault()
+    sair()
+    return
+  }
+
+  if (evento.key === 'Tab') {
+    const lista = focaveis()
+    if (lista.length === 0) return
+    evento.preventDefault()
+    const atual = lista.indexOf(document.activeElement as HTMLElement)
+    const passo = evento.shiftKey ? -1 : 1
+    const proximoIndice = (atual + passo + lista.length) % lista.length
+    lista[proximoIndice]?.focus()
+    return
+  }
+
+  // Setas e Enter não podem atropelar quem está digitando num passo interativo.
+  if (ehCampoDeTexto(evento.target)) return
+
+  if (evento.key === 'ArrowRight') {
+    evento.preventDefault()
+    proximo()
+    return
+  }
+
+  if (evento.key === 'ArrowLeft') {
+    evento.preventDefault()
+    anterior()
+    return
+  }
+
+  // Enter só avança quando o foco está no balão em si — num botão, ele já é
+  // o "clique" nativo e avançar de novo pularia um passo.
+  if (evento.key === 'Enter' && evento.target === balaoRef.value) {
+    evento.preventDefault()
+    proximo()
+    return
+  }
+
+  // Teclas de rolagem — mesmo travamento do wheel/touch: quem rola é o tour.
+  // Exceção: Space com foco num botão é o "clique" do teclado (eMAG 2.1) —
+  // bloquear mataria o Tab+Space no "Próximo".
+  const ehBotao =
+    evento.target instanceof HTMLElement && evento.target.closest('button, [role="button"]')
+  if (evento.key === ' ' && ehBotao) return
+
+  if (['ArrowUp', 'ArrowDown', 'PageUp', 'PageDown', 'Home', 'End', ' '].includes(evento.key)) {
+    evento.preventDefault()
+  }
+}
+
+function pularPasso(passo: TourStep, indice: number, motivo: TourSkipReason): void {
+  const referencia = descreverAncora(motivo === 'activate-not-found' ? passo.activate! : passo)
+
+  emits('step-skipped', { index: indice, step: passo, reason: motivo, reference: referencia })
+
+  if (!import.meta.env.DEV) return
+  console.warn(
+    `[acai-ui-tour] Passo ${indice + 1} de "${props.tour.id}" foi pulado (${motivo}): ` +
+      `"${referencia}" não apareceu no DOM.`,
+  )
+}
+
+/** O usuário desistiu de esperar — a busca da vez devolve `null` na hora. */
+function pularBusca(): void {
+  buscaCancelada = true
+  controleBusca?.abort()
+}
+
+function encerrarAviso(): void {
+  if (temporizadorAviso) window.clearTimeout(temporizadorAviso)
+  temporizadorAviso = 0
+  buscando.value = false
+  controleBusca = null
+}
+
+/**
+ * Espera um alvo COM feedback: passado o limiar, o balão troca as ações por
+ * "Procurando…" + "Pular". Antes disso o tour ficava parado e indistinguível
+ * de travado — e o `waitFor` de cada passo somava em silêncio.
+ */
+async function procurarComAviso(
+  ancora: Parameters<typeof aguardarAlvo>[0],
+  timeout: number,
+): Promise<HTMLElement | null> {
+  const imediato = resolverAlvo(ancora)
+  if (imediato) return imediato
+
+  buscaCancelada = false
+  controleBusca = new AbortController()
+  temporizadorAviso = window.setTimeout(() => {
+    buscando.value = true
+    anuncio.value = 'Procurando o próximo passo.'
+  }, ESPERA_ATE_AVISAR)
+
+  try {
+    return await aguardarAlvo(ancora, timeout, controleBusca.signal)
+  } finally {
+    encerrarAviso()
+  }
+}
+
+/**
+ * Abre o que o passo vai explicar, ANTES de procurar o alvo: `before` (código
+ * do consumidor) e `activate` (um clique que o próprio tour dá). É o que evita
+ * transformar um tour que atravessa abas numa corrida de cliques obrigatórios.
+ *
+ * Devolve `false` quando havia `activate` e o gatilho não apareceu — o passo
+ * ainda é tentado, mas o motivo do skip fica correto se ele falhar.
+ */
+async function prepararPasso(passo: TourStep): Promise<boolean> {
+  if (passo.before) {
+    try {
+      await passo.before()
+    } catch (erro) {
+      if (import.meta.env.DEV) console.warn(`[acai-ui-tour] "before" do passo falhou:`, erro)
+    }
+  }
+
+  const ativar = passo.activate
+  if (!ativar) return true
+
+  // Alvo já à vista: acionar de novo FECHARIA o que está aberto (aba e
+  // expansion são toggle). Por isso a ativação é condicional por padrão.
+  if (!ativar.always && !passoSemAncora(passo) && resolverAlvo(passo)) return true
+
+  const gatilho = await procurarComAviso(ativar, ativar.waitFor ?? passo.waitFor ?? ESPERA_PADRAO)
+  if (!gatilho) return false
+
+  gatilho.click()
+  await nextTick()
+  return true
+}
+
+async function irPara(indice: number): Promise<void> {
+  if (indice < 0) return
+  if (indice >= passos.value.length) return concluir()
+
+  const passo = passos.value[indice]!
+  // Toda navegação nova invalida a anterior: a última ganha, e uma busca ainda
+  // pendente não volta depois pra aplicar um passo que já não é o da vez.
+  const minhaSessao = ++sessao
+  controleBusca?.abort()
+
+  const ativou = await prepararPasso(passo)
+  // O tour fechou (ou outro `irPara` assumiu) enquanto isto acontecia.
+  if (minhaSessao !== sessao) return
+
+  if (passoSemAncora(passo)) {
+    alvoEl.value = null
+    aplicarPasso(indice)
+    return
+  }
+
+  const el = await procurarComAviso(passo, passo.waitFor ?? ESPERA_PADRAO)
+  if (minhaSessao !== sessao) return
+
+  if (!el) {
+    const motivo: TourSkipReason = buscaCancelada
+      ? 'cancelled'
+      : ativou
+        ? 'target-not-found'
+        : 'activate-not-found'
+    pularPasso(passo, indice, motivo)
+
+    const seguinte = indice + direcao
+    // Pulou o primeiro andando pra trás: não há pra onde ir, fica onde está.
+    if (seguinte < 0) return
+    return irPara(seguinte)
+  }
+
+  scrollParaElemento(el, undefined, semAnimacao.value ? 'auto' : 'smooth')
+  alvoEl.value = el
+  aplicarPasso(indice)
+}
+
+/**
+ * Passo interativo avança na AÇÃO, não no botão. A instrução "clique em
+ * Pesquisar" prometia isso desde sempre: liberar o clique e deixar o índice
+ * parado significa que quem obedece o passo vê o tour congelado.
+ * Escuta na fase de bolha — o handler do app roda primeiro.
+ */
+function escutarAlvoInterativo(): void {
+  desescutarAlvo?.()
+  desescutarAlvo = null
+
+  const passo = passoAtual.value
+  const el = alvoEl.value
+  if (!el || !passo?.interactive || passo.advanceOn === 'manual') return
+
+  const aoAgir = (): void => {
+    // Solta a escuta na hora: dois cliques seguidos no mesmo elemento não
+    // podem virar dois avanços.
+    desescutarAlvo?.()
+    desescutarAlvo = null
+    // Cede um tick pro efeito do clique acontecer (trocar de aba, buscar)
+    // antes de procurar o alvo do passo seguinte.
+    window.setTimeout(() => {
+      if (aberto.value) proximo()
+    }, 0)
+  }
+
+  el.addEventListener('click', aoAgir)
+  desescutarAlvo = (): void => el.removeEventListener('click', aoAgir)
+}
+
+function aplicarPasso(indice: number): void {
+  // Cala ANTES de reescrever o anúncio: a fala é do passo velho, e o `aria-live`
+  // abaixo vai anunciar o passo novo. Nessa ordem os dois nunca se atropelam.
+  pararFala()
+
+  indiceAtual.value = indice
+  pronto.value = false
+  emits('step', indice)
+
+  const passo = passos.value[indice]
+  anuncio.value = `Passo ${indice + 1} de ${passos.value.length}. ${passo?.title ?? ''} ${passo?.text ?? ''}`.trim()
+
+  escutarAlvoInterativo()
+
+  void nextTick(() => {
+    medir()
+    // Segunda medição no frame seguinte: na primeira o balão ainda não tem o
+    // tamanho final (texto do passo novo), e o flip sairia com a altura velha.
+    agendarMedicao()
+    if (!passo?.interactive) balaoRef.value?.focus({ preventScroll: true })
+  })
+}
+
+function proximo(): void {
+  direcao = 1
+  void irPara(indiceAtual.value + 1)
+}
+
+function anterior(): void {
+  direcao = -1
+  void irPara(indiceAtual.value - 1)
+}
+
+function encerrar(): void {
+  pararFala()
+  aberto.value = false
+  // Invalida qualquer busca em voo — sem isto um alvo que aparece depois do
+  // fim reabriria o passo em cima de uma tela que já seguiu adiante.
+  sessao++
+  controleBusca?.abort()
+  encerrarAviso()
+  desescutarAlvo?.()
+  desescutarAlvo = null
+  desligarObservadores()
+  alvoEl.value = null
+  recorte.value = null
+  pronto.value = false
+  focoAnterior?.focus({ preventScroll: true })
+  focoAnterior = null
+}
+
+function concluir(): void {
+  encerrar()
+  emits('finish')
+}
+
+function sair(): void {
+  encerrar()
+  emits('exit')
+}
+
+function iniciar(): void {
+  focoAnterior = document.activeElement instanceof HTMLElement ? document.activeElement : null
+  direcao = 1
+  ligarObservadores()
+  void irPara(Math.min(Math.max(props.startAt, 0), Math.max(passos.value.length - 1, 0)))
+}
+
+// `immediate` porque o caso normal é o pai montar o componente já com o
+// v-model em `true` — sem ele o watcher nunca dispara e o tour não começa.
+watch(
+  aberto,
+  ativo => {
+    if (ativo) {
+      if (passos.value.length === 0) {
+        aberto.value = false
+        emits('exit')
+        return
+      }
+      void nextTick(iniciar)
+    } else {
+      desligarObservadores()
+    }
+  },
+  { immediate: true },
+)
+
+onBeforeUnmount(() => {
+  pararFala()
+  sessao++
+  controleBusca?.abort()
+  encerrarAviso()
+  desescutarAlvo?.()
+  desescutarAlvo = null
+  desligarObservadores()
+})
+
+defineExpose({ proximo, anterior, sair, irPara, pularBusca })
+</script>
+
+<style lang="scss" src="./acai-ui-tour-styles.scss" />