acai-ui 1.65.5

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

@@ -0,0 +1,410 @@
+<template>
+  <q-form
+    class="acai-ui-form"
+    @submit.prevent="onFormSubmit"
+    @validation-error="onValidationError"
+    @reset="onReset"
+    ref="formRef"
+    greedy
+  >
+    <header v-if="title">
+      <h2>{{ title }}</h2>
+    </header>
+
+    <slot />
+
+    <!-- A linha de ações aparece se houver slot #actions OU se os botões não
+         estão ocultos. `hideButtons` esconde só os botões submit/reset — NÃO o
+         slot #actions (senão consumidores com hide-buttons perdem as próprias
+         ações, ex: dropdown "Ações"). -->
+    <div v-if="!hideButtons || $slots.actions" class="acai-ui-form__actions">
+      <!--
+        AÇÕES EXTRAS DO CONSUMIDOR
+
+        No desktop ficam soltas à esquerda, como sempre.
+
+        No celular (≤600px) elas COLAPSAM num dropdown de uma linha só. O motivo
+        é aritmético: um formulário de busca costuma ter "Exportar", "Imprimir",
+        "Nova cobrança"… e cada rótulo desses come 90–120px. Somados aos dois
+        botões fixos, não cabem em 360px — a linha quebrava em três e empurrava o
+        formulário pra baixo. Recolhidas, sobra a tela inteira pra ação
+        principal, que é o que a pessoa veio fazer.
+      -->
+      <div v-if="$slots.actions" class="acai-ui-form__actions-extra">
+        <acai-ui-actions
+          :label="actionsLabel"
+          :collapse="collapseActions"
+          button-class="acai-ui-form__actions-menu"
+        >
+          <slot name="actions" />
+        </acai-ui-actions>
+      </div>
+
+      <div v-if="!hideButtons" class="acai-ui-form__actions-buttons">
+        <acai-ui-button
+          v-if="!hideSubmit"
+          outline
+          type="submit"
+          class="acai-ui-form__submit"
+          :label="submitLabel"
+          v-bind="iconRightSubmit ? { iconRight: iconRightSubmit } : {}"
+        />
+        <acai-ui-button
+          v-if="!hideReset"
+          type="reset"
+          class="acai-ui-form__reset"
+          icon="delete_outline"
+          color="negative"
+        />
+      </div>
+    </div>
+
+    <acai-ui-validation
+      v-if="!hideValidationModal"
+      v-model="modalValidacaoAberto"
+      :campos="errosParaModal"
+      @navegar="onNavegarModal"
+    />
+  </q-form>
+</template>
+
+<script setup lang="ts">
+import { ref, nextTick, computed } from 'vue'
+import type { QForm } from 'quasar'
+import type { FormProps, FormError } from './acai-ui-form-interface'
+import type { MaterialIconValues } from '../../constants/lista-icons'
+import AcaiUiActions from '../actions/acai-ui-actions.vue'
+import AcaiUiButton from '../button/acai-ui-button.vue'
+import AcaiUiValidation from '../validation/acai-ui-validation.vue'
+import type { ErroValidacao } from '../../hooks/use-validacao-visual'
+
+const props = withDefaults(defineProps<FormProps>(), {
+  submitLabel: 'Pesquisar',
+  actionsLabel: 'Ações',
+  iconSubmit: 'search',
+  hideReset: false,
+  hideSubmit: false,
+  hideButtons: false,
+  hideValidationModal: false,
+  collapseActions: true,
+})
+
+// O recolhimento das ações no celular mora no <acai-ui-actions>, compartilhado
+// com card e section — assim a regra existe uma vez só.
+
+// iconSubmit é `string | boolean` (para o Vue inferir o runtime type correto e
+// não warnar o default 'search'). Aqui reduzimos ao tipo de ícone: string vira o
+// nome do ícone; boolean (ou vazio) = sem ícone à direita.
+const iconRightSubmit = computed<MaterialIconValues | undefined>(() =>
+  typeof props.iconSubmit === 'string' ? (props.iconSubmit as MaterialIconValues) : undefined,
+)
+
+const emit = defineEmits<{
+  submit: []
+  reset: []
+  'validation-errors': [errors: FormError[]]
+}>()
+
+const formRef = ref<QForm | null>(null)
+const modalValidacaoAberto = ref(false)
+const errosColetados = ref<FormError[]>([])
+
+// Converte FormError[] para ErroValidacao[] (formato do modal).
+// O `group` vem de detectarGrupo() já no formato "Aba — Seção" quando
+// há hierarquia. Split em ' — ' separa em aba (1ª parte) e seção (2ª).
+const errosParaModal = computed<ErroValidacao[]>(() => {
+  return errosColetados.value.map((erro) => {
+    const grupo = erro.group ?? ''
+    const partes = grupo.includes(' — ') ? grupo.split(' — ') : []
+    const aba = partes[0] ?? (grupo || 'Geral')
+    const secao = partes[1] ?? (partes[0] ? grupo : grupo || 'Geral')
+    return {
+      label: erro.label,
+      aba: partes.length > 1 ? aba : 'Geral',
+      secao: partes.length > 1 ? secao : (grupo || 'Geral'),
+    }
+  })
+})
+
+// Mapa de elemento por label para navegação
+const mapaElementos = computed<Map<string, FormError>>(() => {
+  const mapa = new Map<string, FormError>()
+  for (const erro of errosColetados.value) {
+    mapa.set(`${erro.group || 'Geral'}-${erro.label}`, erro)
+  }
+  return mapa
+})
+
+function coletarErros(): FormError[] {
+  const el = formRef.value?.$el as HTMLElement | undefined
+  if (!el) return []
+
+  const camposComErro = el.querySelectorAll('.q-field--error')
+  const erros: FormError[] = []
+
+  camposComErro.forEach((campo) => {
+    const htmlCampo = campo as HTMLElement
+
+    const labelEl = campo.querySelector('.q-field__label')
+    let label = labelEl?.textContent?.trim()?.replace(/\s*\*\s*$/, '').trim() || ''
+    if (!label) {
+      const placeholder = campo.querySelector('input')?.getAttribute('placeholder')
+      label = placeholder || 'Campo sem label'
+    }
+
+    const msgEl = campo.querySelector('.q-field__messages > div')
+    const message = msgEl?.textContent?.trim() || 'Campo inválido'
+
+    const group = detectarGrupo(htmlCampo)
+
+    erros.push({ label, message, element: htmlCampo, ...(group ? { group } : {}) })
+  })
+
+  return erros
+}
+
+/**
+ * Detecta o "caminho" do campo no formulário, combinando ancestrais
+ * conhecidos em hierarquia (Tab → Section). Isso permite distinguir,
+ * por exemplo, "Dados básicos" da aba Pessoal e "Dados básicos" da
+ * aba Profissional — que sem hierarquia colidiriam.
+ *
+ * Ordem de busca:
+ *   1. Tab (AcaiUiTabs ou q-tab-panel nativo) — nível superior
+ *   2. Stepper step — nível superior alternativo
+ *   3. Section (AcaiUiSection / secao-ficha) — sub-grupo
+ *   4. Card — fallback quando nada acima existe
+ *
+ * Retorna "Tab — Section", "Tab", "Section" ou "Card" conforme
+ * o que estiver disponível.
+ */
+function detectarGrupo(campo: HTMLElement): string | undefined {
+  const partes: string[] = []
+
+  // === Nível superior: Tab ou Step ===
+  const dsTabPanel = campo.closest('.ds-tabs__panel') as HTMLElement | null
+  if (dsTabPanel) {
+    const panels = dsTabPanel.parentElement?.querySelectorAll('.ds-tabs__panel')
+    if (panels) {
+      const index = Array.from(panels).indexOf(dsTabPanel)
+      const tabsContainer = dsTabPanel.parentElement?.previousElementSibling
+      const tabs = tabsContainer?.querySelectorAll('.q-tab')
+      if (tabs && tabs[index]) {
+        const tabLabel = tabs[index]
+          .querySelector('.ds-tabs__tab-content span')
+          ?.textContent?.trim()
+        if (tabLabel) partes.push(tabLabel)
+      }
+    }
+  } else {
+    const tabPanel = campo.closest('.q-tab-panel')
+    if (tabPanel) {
+      const panelName =
+        tabPanel.getAttribute('name') || tabPanel.getAttribute('data-name')
+      if (panelName) partes.push(panelName)
+    } else {
+      const stepPanel = campo.closest('.q-stepper__step-content')
+      if (stepPanel) {
+        const stepInner = stepPanel.closest('.q-stepper__step')
+        const stepHeader = stepInner?.querySelector('.q-stepper__title')
+        const stepTitle = stepHeader?.textContent?.trim()
+        if (stepTitle) partes.push(stepTitle)
+      }
+    }
+  }
+
+  // === Sub-grupo: Section (AcaiUiSection / secao-ficha) ===
+  const secaoFicha = campo.closest('.secao-ficha')
+  if (secaoFicha) {
+    const title = secaoFicha
+      .querySelector('.secao-ficha__titulo')
+      ?.textContent?.trim()
+    if (title) partes.push(title)
+  }
+
+  if (partes.length > 0) {
+    return partes.join(' — ')
+  }
+
+  // === Fallback: Card ===
+  const card = campo.closest('.q-card')
+  if (card) {
+    const cardTitle = card.querySelector(
+      '.card-container-header h2, .card-container-header span',
+    )
+    const titulo = cardTitle?.textContent?.trim()
+    if (titulo) return titulo
+  }
+
+  return undefined
+}
+
+function ativarAbaDoErro(erro: FormError): void {
+  const dsTabPanel = erro.element.closest('.ds-tabs__panel') as HTMLElement | null
+  if (dsTabPanel) {
+    const panels = dsTabPanel.parentElement?.querySelectorAll('.ds-tabs__panel')
+    if (panels) {
+      const index = Array.from(panels).indexOf(dsTabPanel)
+      const tabsContainer = dsTabPanel.parentElement?.previousElementSibling
+      const tabEls = tabsContainer?.querySelectorAll('.q-tab') as NodeListOf<HTMLElement> | undefined
+      if (tabEls && tabEls[index]) {
+        tabEls[index].click()
+      }
+    }
+  }
+}
+
+function onNavegarModal(erroValidacao: ErroValidacao): void {
+  // O `errosParaModal` separa o group em aba + secao. Aqui reconstruímos
+  // o `group` original ("Aba — Seção" ou só "Seção") para bater com a
+  // chave registrada em `mapaElementos`.
+  const group =
+    erroValidacao.aba && erroValidacao.aba !== 'Geral'
+      ? `${erroValidacao.aba} — ${erroValidacao.secao}`
+      : erroValidacao.secao
+  const key = `${group}-${erroValidacao.label}`
+  const erroOriginal = mapaElementos.value.get(key)
+  if (!erroOriginal) return
+
+  ativarAbaDoErro(erroOriginal)
+
+  // 300ms: dá tempo da aba/painel do erro ficar visível (quando há tabs).
+  setTimeout(() => {
+    const el = erroOriginal.element
+    focarCampoErro(el)
+    rolarEDestacar(el)
+  }, 300)
+}
+
+/**
+ * Rola até o campo e só então aplica o pulso. O destaque PRECISA esperar a
+ * rolagem suave assentar: se aplicado junto com o `scrollIntoView`, a animação
+ * (curta) roda fora da viewport e o campo "não pisca" — sintoma típico do 2º
+ * erro em diante, que costuma estar mais abaixo e exige uma rolagem maior.
+ */
+function rolarEDestacar(el: HTMLElement): void {
+  el.scrollIntoView({ behavior: 'smooth', block: 'center' })
+
+  let feito = false
+  const aplicar = (): void => {
+    if (feito) return
+    feito = true
+    window.removeEventListener('scrollend', aplicar)
+    destacarCampo(el)
+  }
+
+  // `scrollend` cobre a rolagem da viewport; o timeout é fallback pra rolagem
+  // em container interno (scrollend não chega à window) e pro caso sem rolagem.
+  window.addEventListener('scrollend', aplicar, { once: true })
+  setTimeout(aplicar, 600)
+}
+
+/**
+ * Aplica o pulso de destaque forçando o restart da animação CSS (remove →
+ * reflow → add). Sem o reflow, navegar duas vezes pro MESMO campo não
+ * reinicia a animação.
+ */
+function destacarCampo(el: HTMLElement): void {
+  el.classList.remove('fvm-highlight')
+  void el.offsetWidth // força reflow → reinicia a animação
+  el.classList.add('fvm-highlight')
+  setTimeout(() => el.classList.remove('fvm-highlight'), 2000)
+}
+
+/**
+ * eMAG 6.7: ao avisar erro, foco do teclado deve voltar ao campo problemático.
+ * Procura o primeiro elemento focável dentro do wrapper `.q-field` cobrindo
+ * todos os tipos suportados (input/select/textarea + componentes ARIA do
+ * Quasar como checkbox/radio/toggle).
+ */
+function focarCampoErro(wrapper: HTMLElement): void {
+  const seletoresFocaveis = [
+    'input:not([type="hidden"]):not(.hidden)',
+    'select',
+    'textarea',
+    '[role="combobox"]',
+    '[role="checkbox"]',
+    '[role="radio"]',
+    '[role="switch"]',
+  ].join(',')
+  const focavel = wrapper.querySelector<HTMLElement>(seletoresFocaveis)
+  focavel?.focus({ preventScroll: true })
+}
+
+/** Chamado pelo q-form quando validação PASSA */
+function onFormSubmit(): void {
+  emit('submit')
+}
+
+/** Chamado pelo q-form quando validação FALHA */
+async function onValidationError(): Promise<void> {
+  if (props.hideValidationModal) return
+
+  await nextTick()
+  await new Promise((r) => setTimeout(r, 100))
+
+  errosColetados.value = coletarErros()
+  emit('validation-errors', errosColetados.value)
+
+  if (errosColetados.value.length > 0) {
+    modalValidacaoAberto.value = true
+  } else {
+    scrollParaPrimeiroErro()
+  }
+}
+
+const scrollParaPrimeiroErro = async (): Promise<void> => {
+  await nextTick()
+  const primeiroErro = formRef.value?.$el?.querySelector('.q-field--error') as HTMLElement | null
+  if (primeiroErro) {
+    primeiroErro.scrollIntoView({ behavior: 'smooth', block: 'center' })
+  }
+}
+
+const onReset = (): void => {
+  errosColetados.value = []
+  emit('reset')
+  resetValidation()
+}
+
+const validate = async (): Promise<boolean> => {
+  return (await formRef.value?.validate()) ?? false
+}
+
+const reset = (): void => {
+  formRef.value?.reset()
+  formRef.value?.resetValidation()
+  errosColetados.value = []
+}
+
+const resetValidation = (): void => {
+  formRef.value?.resetValidation()
+  errosColetados.value = []
+}
+
+defineExpose({
+  validate,
+  reset,
+  resetValidation,
+  formRef,
+  coletarErros,
+})
+</script>
+
+<style lang="scss" scoped>
+@import './acai-ui-form-styles.scss';
+</style>
+
+<style lang="scss">
+@import './acai-ui-form-grid.scss';
+
+@keyframes fvm-pulse {
+  0%, 100% { box-shadow: none; }
+  50% { box-shadow: 0 0 0 3px rgba($warning, 0.4); }
+}
+
+.fvm-highlight {
+  animation: fvm-pulse 0.6s ease 2;
+  border-radius: 8px;
+}
+</style>

package/src/components/help/acai-ui-help-interface.ts

@@ -0,0 +1,200 @@
+import type { MaterialIconValues } from '../../constants/lista-icons'
+
+/**
+ * O `| undefined` explícito em cada opcional é por causa do
+ * `exactOptionalPropertyTypes`: sem ele o consumidor não consegue escrever
+ * `:auto-start="algo || undefined"` — padrão comum quando o valor vem de estado.
+ */
+
+/** Um tópico de dúvida listado no modal "Ajuda". */
+export interface HelpTopic {
+  title: string
+  text: string
+  /** Ícone à esquerda do título. Só a lista curada (`MaterialIconsEnum`). */
+  icon?: MaterialIconValues | undefined
+}
+
+/** Lado preferido do balão em relação ao elemento iluminado. */
+export type TourPlacement = 'auto' | 'top' | 'bottom' | 'left' | 'right'
+
+/** Afunila os candidatos a alvo. Puro: recebe a lista, devolve outra. */
+export type TourFilter = (elementos: HTMLElement[]) => HTMLElement[]
+
+/** Fecha a escolha: recebe os candidatos, devolve o eleito (ou `null`). */
+export type TourPick = (elementos: HTMLElement[]) => HTMLElement | null
+
+/** Como achar um elemento na tela. Compartilhado pelo passo e pela ativação. */
+export interface TourAnchor {
+  /**
+   * Nome registrado no elemento via `v-acai-tour="'cpf'"`. É a forma preferida:
+   * sobrevive a refatoração de classe/id e funciona em qualquer componente.
+   */
+  target?: string | undefined
+  /**
+   * Alternativa por seletor CSS, para quando não dá pra pôr a diretiva — caso
+   * típico: DOM interna de um componente da lib ou do Quasar.
+   * Usado só quando `target` não resolve.
+   */
+  selector?: string | undefined
+  /**
+   * Quanto esperar (ms) o elemento aparecer no DOM antes de desistir.
+   * Cobre elemento que só existe depois de carregar dados. Default 1500.
+   */
+  waitFor?: number | undefined
+  /**
+   * Qual, quando o nome existe mais de uma vez na tela — linha de `v-for`,
+   * bloco duplicado por perfil, aba montada escondida. Monte com os
+   * combinadores: `escolher(visiveis, primeiro)`, `escolher(comTexto('Situação'))`,
+   * `escolher(dentroDe('filtros'), nEsimo(1))`.
+   *
+   * Sem `pick`, vale o padrão de sempre: o primeiro do documento que está à
+   * vista. Também filtra o resultado de `selector`, não só o de `target`.
+   */
+  pick?: TourPick | undefined
+}
+
+/**
+ * O que o tour ACIONA antes do passo, pra abrir sozinho o que vai explicar
+ * (trocar de aba, expandir um painel, abrir um menu). Sem isto, um tour que
+ * atravessa abas vira uma sequência de cliques obrigatórios no meio do
+ * caminho — e cada clique não dado apaga o bloco inteiro de passos que
+ * dependia dele.
+ */
+export interface TourActivate extends TourAnchor {
+  /**
+   * Aciona mesmo quando o alvo do passo já está à vista. Default `false`:
+   * o acionamento costuma ser um toggle (aba, expansion), e repetí-lo ao
+   * voltar pro passo fecharia justamente o que ele abriu.
+   */
+  always?: boolean | undefined
+}
+
+/**
+ * Quando um passo `interactive` avança sozinho.
+ * - `'click'` (default do passo interativo) — assim que o usuário aciona o
+ *   elemento iluminado. É o que a instrução "clique em Pesquisar" promete.
+ * - `'manual'` — só pelo botão "Próximo". Use quando a ação pedida é digitar
+ *   ou quando o clique não é o fim do passo.
+ */
+export type TourAdvanceOn = 'click' | 'manual'
+
+/** Um passo do tour: o que iluminar e o que explicar. */
+export interface TourStep extends TourAnchor {
+  title?: string | undefined
+  text: string
+  /** Default 'auto': tenta bottom → top → right → left e cai no que couber. */
+  placement?: TourPlacement | undefined
+  /**
+   * Deixa o clique CHEGAR no elemento iluminado (ex.: "agora clique em
+   * Pesquisar"). Default `false` — o tour bloqueia a tela inteira e o usuário
+   * avança só pelos botões do balão.
+   */
+  interactive?: boolean | undefined
+  /** Só faz sentido com `interactive`. Default `'click'`. */
+  advanceOn?: TourAdvanceOn | undefined
+  /**
+   * Clique que o TOUR dá antes do passo, pra deixar o alvo à vista.
+   * Preferir a `activate` sobre pedir o clique ao usuário: um passo
+   * `interactive` no meio da trilha é um ponto onde o tour se desfaz se a
+   * pessoa não obedecer.
+   */
+  activate?: TourActivate | undefined
+  /**
+   * Escape hatch pro que `activate` não cobre (abrir por store, carregar
+   * dados). Roda antes de `activate` e antes de procurar o alvo; se devolver
+   * Promise, o tour espera.
+   */
+  before?: (() => void | Promise<void>) | undefined
+  /** Folga entre o elemento e a borda do recorte, em px. Default 8. */
+  padding?: number | undefined
+}
+
+/** Por que um passo não foi mostrado. */
+export type TourSkipReason =
+  /** O alvo do passo não apareceu dentro do `waitFor`. */
+  | 'target-not-found'
+  /** O elemento da `activate` não apareceu — o passo nem teve como abrir. */
+  | 'activate-not-found'
+  /** O usuário desistiu da espera pelo botão "Pular". */
+  | 'cancelled'
+
+/** Payload de `@step-skipped` — emitido SEMPRE, inclusive em produção. */
+export interface TourSkip {
+  /** Índice 0-based do passo pulado, na lista original. */
+  index: number
+  step: TourStep
+  reason: TourSkipReason
+  /** `target` ou `selector` procurado, já resolvido pra log/telemetria. */
+  reference: string
+}
+
+/** A sequência guiada — o "Aprenda a usar". */
+export interface TourContent {
+  /**
+   * Identificador estável do tour. É a chave da persistência "já viu este
+   * tour" — mudar o id faz o tour ser oferecido de novo a todo mundo.
+   */
+  id: string
+  /** Título mostrado no botão e no cabeçalho do balão. Default "Aprenda a usar". */
+  title?: string | undefined
+  steps: TourStep[]
+}
+
+/** Conteúdo completo da ajuda de uma tela. */
+export interface HelpContent {
+  /** Título do modal. Default "Ajuda". */
+  title?: string | undefined
+  topics?: HelpTopic[] | undefined
+  tour?: TourContent | undefined
+}
+
+export interface HelpProps {
+  content: HelpContent
+  /** Ícone do botão gatilho. Default 'help'. */
+  icon?: MaterialIconValues | undefined
+  /** Rótulo acessível do gatilho. Default "Ajuda". */
+  ariaLabel?: string | undefined
+  /**
+   * Abre o tour sozinho na primeira visita do usuário a esta tela (usa a
+   * persistência por `tour.id`). Default false.
+   */
+  autoStart?: boolean | undefined
+  /** Esconde o ponto "novo" no gatilho enquanto o tour nunca foi concluído. */
+  hideNewBadge?: boolean | undefined
+  /**
+   * Esconde os botões de ouvir (leitura em voz alta) dos tópicos e do tour.
+   *
+   * Eles só aparecem quando o navegador tem síntese de voz E a preferência
+   * "Leitura em voz alta" está ligada; esta prop é o desligamento por tela,
+   * para quem não quer o recurso em nenhuma condição. Default false.
+   */
+  hideAudio?: boolean | undefined
+  /** Idioma da fala (BCP-47). Default 'pt-BR'. */
+  audioLang?: string | undefined
+}
+
+export interface TourProps {
+  tour: TourContent
+  /** Passo inicial (0-based). Default 0. */
+  startAt?: number | undefined
+  /** Esconde o botão de ouvir no balão. Default false. */
+  hideAudio?: boolean | undefined
+  /** Idioma da fala (BCP-47). Default 'pt-BR'. */
+  audioLang?: string | undefined
+}
+
+/** Retângulo do recorte, em coordenadas de viewport. */
+export interface SpotlightRect {
+  top: number
+  left: number
+  width: number
+  height: number
+}
+
+/** Onde o balão foi parar, já resolvido. */
+export interface BalloonPosition {
+  top: number
+  left: number
+  /** Lado efetivamente usado — o balão desenha a setinha a partir disto. */
+  side: Exclude<TourPlacement, 'auto'>
+}