acai-ui 1.65.5

package/src/components/help/acai-ui-help-styles.scss

@@ -0,0 +1,209 @@
+// Compilado isolado (via <style src>), sem o additionalData do vite.config —
+// importar explicitamente o que usa. Ver CLAUDE.md §6.
+@import '../../scss/variables';
+@import '../../scss/spacing';
+@import '../../scss/radius';
+
+// Coluna do ícone dos tópicos — o mesmo número serve de recuo pro texto aberto.
+$topico-icone-largura: 20px;
+
+.acaihelp {
+  &__gatilho {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 38px;
+    height: 38px;
+    padding: 0;
+    border: 0;
+    border-radius: $radius-full;
+    background: transparent;
+    color: var(--acai-control-on, #{$primary});
+    cursor: pointer;
+    transition: background 0.16s ease;
+
+    &:hover {
+      background: var(--acai-surface-hover, #{$color-gray-100});
+    }
+
+    // eMAG 4.3 — foco visível sem depender de cor sozinha.
+    &:focus-visible {
+      outline: 2px solid var(--acai-control-on, #{$primary});
+      outline-offset: 2px;
+    }
+  }
+
+  // Ponto de "tem novidade aqui": some quando o tour é concluído.
+  &__novo {
+    position: absolute;
+    top: 4px;
+    right: 4px;
+    width: 7px;
+    height: 7px;
+    border-radius: $radius-full;
+    background: var(--acai-negative, #{$negative});
+    border: 1.5px solid var(--acai-surface, #{$color-white-100});
+  }
+
+  &__vazio {
+    margin: 0;
+    color: var(--acai-text-muted, #{$color-gray-600});
+    font-size: 0.9375rem;
+  }
+
+  // Cartão de entrada do tour — a ação principal do modal.
+  &__tour {
+    display: flex;
+    align-items: center;
+    gap: $spacing-sm + $spacing-xs; // 12px — mesmo respiro dos tópicos
+    width: 100%;
+    padding: $spacing-sm $spacing-md;
+    margin-bottom: $spacing-md;
+    text-align: left;
+    border: 1px solid var(--acai-border, #{$color-gray-300});
+    border-radius: $radius-lg;
+    background: var(--acai-surface-2, #{$color-gray-100});
+    color: var(--acai-text, #{$color-gray-800});
+    cursor: pointer;
+    transition:
+      border-color 0.16s ease,
+      background 0.16s ease;
+
+    &:hover {
+      border-color: var(--acai-control-on, #{$primary});
+      background: var(--acai-surface-hover, #{$color-gray-100});
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--acai-control-on, #{$primary});
+      outline-offset: 2px;
+    }
+  }
+
+  &__tour-icone {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 36px;
+    height: 36px;
+    flex: 0 0 36px;
+    border-radius: $radius-full;
+    background: var(--acai-surface, #{$color-white-100});
+    color: var(--acai-control-on, #{$primary});
+  }
+
+  &__tour-texto {
+    display: flex;
+    flex-direction: column;
+    flex: 1;
+    gap: 2px;
+
+    strong {
+      font-size: 0.9375rem;
+      color: var(--acai-heading, #{$primary});
+    }
+
+    small {
+      font-size: 0.8125rem;
+      color: var(--acai-text-muted, #{$color-gray-600});
+    }
+  }
+
+  &__topicos {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  &__topico {
+    border-bottom: 1px solid var(--acai-border-subtle, #{$color-gray-100});
+
+    &:last-child {
+      border-bottom: 0;
+    }
+  }
+
+  // <details>/<summary> nativos de propósito: acordeão acessível de graça
+  // (teclado, leitor de tela, estado expandido) sem ARIA inventado.
+  &__topico-titulo {
+    display: flex;
+    align-items: center;
+    gap: $spacing-sm + $spacing-xs; // 12px
+    padding: $spacing-sm 0;
+    font-size: 0.9375rem;
+    font-weight: 600;
+    color: var(--acai-heading, #{$primary});
+    cursor: pointer;
+
+    &:focus-visible {
+      outline: 2px solid var(--acai-control-on, #{$primary});
+      outline-offset: 2px;
+      border-radius: $radius-sm;
+    }
+  }
+
+  // Coluna própria pro ícone: colado no texto e do mesmo navy/negrito do título,
+  // ele era lido como se fosse um caractere da frase. Largura fixa alinha os
+  // títulos entre si, e o tom mais suave separa símbolo de texto.
+  &__topico-icone {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex: 0 0 $topico-icone-largura;
+    color: var(--acai-control-on, #{$primary});
+    opacity: 0.75;
+  }
+
+  // Texto e botão de ouvir lado a lado: o botão fica no fim do parágrafo, onde a
+  // leitura termina, em vez de competir com o título.
+  &__topico-corpo {
+    display: flex;
+    align-items: flex-start;
+    gap: $spacing-sm;
+  }
+
+  // Alinhado com o TÍTULO (ícone + gap), não com a borda do modal: o texto
+  // aberto vira continuação visual do tópico.
+  &__topico-texto {
+    flex: 1 1 auto;
+    min-width: 0;
+    margin: 0 0 $spacing-sm;
+    padding-left: $topico-icone-largura + $spacing-sm + $spacing-xs;
+    font-size: 0.9375rem;
+    line-height: 1.6;
+    color: var(--acai-text, #{$color-gray-700});
+  }
+
+  // Alvo de 32px: menor que isso vira mira difícil no toque (eMAG 2.1).
+  &__ouvir {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex: 0 0 32px;
+    width: 32px;
+    height: 32px;
+    padding: 0;
+    border: 0;
+    border-radius: $radius-full;
+    background: transparent;
+    color: var(--acai-control-on, #{$primary});
+    cursor: pointer;
+    transition: background 0.16s ease;
+
+    &:hover {
+      background: var(--acai-surface-hover, #{$color-gray-100});
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--acai-control-on, #{$primary});
+      outline-offset: 2px;
+    }
+
+    // Estado "lendo" NÃO é comunicado só por cor (eMAG 4.2): o ícone vira o de
+    // parar. O fundo aqui é reforço, não a informação.
+    &[aria-pressed='true'] {
+      background: var(--acai-surface-hover, #{$color-gray-100});
+    }
+  }
+}

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

@@ -0,0 +1,259 @@
+<template>
+  <button
+    ref="gatilhoRef"
+    type="button"
+    class="acaihelp__gatilho"
+    :class="{ 'acaihelp__gatilho--novo': mostrarPontoNovo }"
+    :aria-label="rotuloGatilho"
+    :title="rotuloGatilho"
+    @click="abrirModal"
+  >
+    <acai-ui-icon :name="iconeGatilho" size="md" />
+    <span v-if="mostrarPontoNovo" class="acaihelp__novo" aria-hidden="true" />
+  </button>
+
+  <acai-ui-modal
+    v-model="modalAberto"
+    :title="tituloModal"
+    hide-actions
+    modal-class="acaihelp__modal"
+  >
+    <p v-if="!temTopicos && !temTour" class="acaihelp__vazio">
+      Ainda não há conteúdo de ajuda para esta tela.
+    </p>
+
+    <!-- O tour vem PRIMEIRO: é a ação mais útil pra quem chegou perdido. -->
+    <!-- Tamanhos: `size` do AcaiUiIcon usa a escala de ESPAÇOS (MedidasKeys),
+         não camiseta — sm=8px some ao lado de texto; md=16px é o ponto certo. -->
+    <button v-if="temTour" type="button" class="acaihelp__tour" @click="iniciarTour">
+      <span class="acaihelp__tour-icone">
+        <acai-ui-icon name="auto_stories" size="md" />
+      </span>
+      <span class="acaihelp__tour-texto">
+        <strong>{{ tituloTour }}</strong>
+        <small>
+          Passo a passo guiado pela tela — {{ totalPassos }}
+          {{ totalPassos === 1 ? 'passo' : 'passos' }}.
+        </small>
+      </span>
+      <acai-ui-icon name="arrow_forward" size="md" />
+    </button>
+
+    <ul v-if="temTopicos" class="acaihelp__topicos">
+      <li v-for="(topico, indice) in content.topics" :key="indice" class="acaihelp__topico">
+        <details>
+          <summary class="acaihelp__topico-titulo">
+            <span v-if="topico.icon" class="acaihelp__topico-icone">
+              <acai-ui-icon :name="topico.icon" size="md" decorative />
+            </span>
+            <span>{{ topico.title }}</span>
+          </summary>
+          <!-- O botão fica no CORPO, nunca no <summary>: clique lá dentro
+               alterna o <details>, e o Space ficaria ambíguo entre abrir o
+               tópico e acionar o botão. -->
+          <div class="acaihelp__topico-corpo">
+            <p class="acaihelp__topico-texto">{{ topico.text }}</p>
+            <button
+              v-if="mostrarAudio"
+              type="button"
+              class="acaihelp__ouvir"
+              :aria-pressed="lendoTopico(indice)"
+              :aria-label="`Ouvir: ${topico.title}`"
+              @click="alternarTopico(indice, topico)"
+            >
+              <acai-ui-icon
+                :name="lendoTopico(indice) ? 'stop' : 'volume_up'"
+                size="16px"
+                decorative
+              />
+            </button>
+          </div>
+        </details>
+      </li>
+    </ul>
+  </acai-ui-modal>
+
+  <acai-ui-tour
+    v-if="temTour && tourAtivo"
+    ref="tourRef"
+    v-model="tourAtivo"
+    :tour="content.tour!"
+    :hide-audio="hideAudio"
+    :audio-lang="audioLang"
+    @finish="aoConcluirTour"
+    @exit="emits('tour-exit')"
+    @step="indice => emits('tour-step', indice)"
+    @step-skipped="info => emits('tour-step-skipped', info)"
+  />
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import AcaiUiIcon from '../icon/acai-ui-icon.vue'
+import AcaiUiModal from '../modal/acai-ui-modal.vue'
+import AcaiUiTour from './acai-ui-tour.vue'
+import { useTourVisto } from './use-tour-visto'
+import { useLeituraVoz } from '../../hooks/use-leitura-voz'
+import { usePreferencias } from '../../hooks/use-preferencias'
+import { gerarId } from '../../utils/gerador-id'
+import type { MaterialIconValues } from '../../constants/lista-icons'
+import type { HelpProps, HelpTopic, TourSkip } from './acai-ui-help-interface'
+
+const props = withDefaults(defineProps<HelpProps>(), {
+  icon: 'help',
+  ariaLabel: 'Ajuda',
+  autoStart: false,
+  hideNewBadge: false,
+})
+
+const emits = defineEmits<{
+  (e: 'open'): void
+  (e: 'tour-start'): void
+  (e: 'tour-finish'): void
+  /** Saiu antes do fim (Esc ou X). */
+  (e: 'tour-exit'): void
+  /** Trocou de passo — índice 0-based. */
+  (e: 'tour-step', indice: number): void
+  /** Um passo não pôde ser mostrado. Repassa o `step-skipped` do tour. */
+  (e: 'tour-step-skipped', info: TourSkip): void
+}>()
+
+const { jaViu, marcarVisto } = useTourVisto()
+
+const modalAberto = ref(false)
+const tourAtivo = ref(false)
+const gatilhoRef = ref<HTMLElement | null>(null)
+const tourRef = ref<InstanceType<typeof AcaiUiTour> | null>(null)
+
+// O `?? ` em vez de confiar só no withDefaults: o tipo da prop declara
+// `| undefined` explícito (exigência do exactOptionalPropertyTypes) e o
+// default não apaga esse `undefined` aos olhos do compilador.
+const iconeGatilho = computed<MaterialIconValues>(() => props.icon ?? 'help')
+
+const tituloModal = computed(() => props.content.title || 'Ajuda')
+const tituloTour = computed(() => props.content.tour?.title || 'Aprenda a usar')
+const rotuloGatilho = computed(() => props.ariaLabel || 'Ajuda')
+
+const temTopicos = computed(() => (props.content.topics?.length ?? 0) > 0)
+const temTour = computed(() => (props.content.tour?.steps.length ?? 0) > 0)
+const totalPassos = computed(() => props.content.tour?.steps.length ?? 0)
+
+// ===================== Leitura em voz alta =====================
+const { preferencias } = usePreferencias()
+const {
+  suportado: vozSuportada,
+  temVozPara,
+  vozes,
+  idLendo,
+  alternar: alternarFala,
+  parar: pararFala,
+} = useLeituraVoz()
+
+const idiomaFala = computed(() => props.audioLang || 'pt-BR')
+
+/**
+ * Precedência: prop da tela > preferência do usuário > suporte do navegador >
+ * existir voz do idioma. Sem voz do idioma, o motor leria português com fonemas
+ * de outra língua — pior que não oferecer.
+ */
+const mostrarAudio = computed(() => {
+  void vozes.value // recalcula quando a lista de vozes chega
+  return (
+    vozSuportada.value &&
+    !props.hideAudio &&
+    preferencias.leituraVoz &&
+    temVozPara(idiomaFala.value)
+  )
+})
+
+// Id por INSTÂNCIA: duas ajudas na mesma tela não podem disputar o "quem está
+// lendo" só porque os dois têm um tópico 0.
+const idBase = gerarId('acai-voz', 'help')
+
+const idDoTopico = (indice: number): string => `${idBase}:topico:${indice}`
+
+const lendoTopico = (indice: number): boolean => idLendo.value === idDoTopico(indice)
+
+function alternarTopico(indice: number, topico: HelpTopic): void {
+  // Título junto do texto: ouvindo sem olhar, a pergunta dá o contexto da resposta.
+  // Voz e velocidade vêm das preferências — a escolha é do usuário, não da tela.
+  alternarFala(`${topico.title}. ${topico.text}`, {
+    id: idDoTopico(indice),
+    lang: idiomaFala.value,
+    voz: preferencias.vozNome,
+    rate: preferencias.vozVelocidade,
+  })
+}
+
+// Fechou o modal ou saiu do componente, a voz para: continuar falando um texto
+// que não está mais na tela é desorientador.
+watch(modalAberto, (aberto) => {
+  if (!aberto) pararFala()
+})
+
+onBeforeUnmount(pararFala)
+
+/** Ponto discreto no "?" enquanto o usuário nunca concluiu o tour desta tela. */
+const mostrarPontoNovo = computed(() => {
+  if (props.hideNewBadge || !temTour.value) return false
+  return !jaViu(props.content.tour!.id)
+})
+
+function abrirModal(): void {
+  modalAberto.value = true
+  emits('open')
+}
+
+function iniciarTour(): void {
+  // O tour tem o botão de ouvir dele; a fala do tópico não pode atravessar.
+  pararFala()
+  modalAberto.value = false
+  // Espera o q-dialog fechar: com o modal ainda montado, o backdrop dele fica
+  // por cima do recorte e o primeiro passo aparece apagado.
+  void nextTick(() => {
+    window.setTimeout(() => {
+      // Foco explícito no "?" antes de abrir: é dele que o tour tira o
+      // `focoAnterior` pra devolver no fim (eMAG 4.3). Deixar por conta do
+      // q-dialog daria `<body>` conforme o timing.
+      gatilhoRef.value?.focus({ preventScroll: true })
+      tourAtivo.value = true
+      emits('tour-start')
+    }, 180)
+  })
+}
+
+function aoConcluirTour(): void {
+  marcarVisto(props.content.tour!.id)
+  emits('tour-finish')
+}
+
+onMounted(() => {
+  if (!props.autoStart || !temTour.value) return
+  if (jaViu(props.content.tour!.id)) return
+  // Só depois da tela pintar — senão os alvos ainda não estão no DOM.
+  void nextTick(() => {
+    tourAtivo.value = true
+    emits('tour-start')
+  })
+})
+
+// O controle do tour é repassado aqui porque é o `<acai-ui-help>` (e o `help`
+// do `<acai-ui-container>`) que instancia o `<acai-ui-tour>` — sem isto o
+// consumidor não tem como dirigir o tour que ele mesmo mandou abrir.
+// Todos são no-op quando não há tour em andamento.
+defineExpose({
+  abrirModal,
+  iniciarTour,
+  /** Fecha modal e tour de uma vez — útil ao trocar de rota. */
+  fechar: (): void => {
+    modalAberto.value = false
+    tourAtivo.value = false
+  },
+  proximo: (): void => tourRef.value?.proximo(),
+  anterior: (): void => tourRef.value?.anterior(),
+  irPara: (indice: number): void => void tourRef.value?.irPara(indice),
+  sairTour: (): void => tourRef.value?.sair(),
+})
+</script>
+
+<style lang="scss" src="./acai-ui-help-styles.scss" />