acai-ui 1.65.5

package/src/components/help/tour-escolha.ts

@@ -0,0 +1,139 @@
+import type { TourFilter, TourPick } from './acai-ui-help-interface'
+
+/**
+ * Combinadores para escolher ENTRE alvos repetidos.
+ *
+ * O mesmo nome de `v-acai-tour` pode existir várias vezes na tela — linha de
+ * `v-for`, bloco duplicado por perfil, aba que fica montada escondida. Sem uma
+ * forma de dizer QUAL, o consumidor acaba abandonando o registro e escrevendo
+ * seletor CSS acoplado à DOM interna (`tbody tr:first-child td:last-child`),
+ * que quebra na primeira mudança de markup.
+ *
+ * Tudo aqui é função pura sobre `HTMLElement[]`: um `TourFilter` devolve outro
+ * array, um `TourPick` devolve o eleito. `escolher` costura os dois numa
+ * pipeline só, e é isso que a âncora do passo recebe em `pick`.
+ */
+
+/**
+ * Ordena por posição no documento, não por ordem de montagem.
+ *
+ * É a diferença entre "o primeiro" e "o que montou antes". Com `v-if`,
+ * `Suspense` ou chunk assíncrono a ordem de montagem não acompanha a da tela, e
+ * "primeiro" passaria a significar coisas diferentes conforme o tempo de rede.
+ */
+export function ordenarPorDocumento(elementos: HTMLElement[]): HTMLElement[] {
+  return [...elementos].sort((a, b) => {
+    if (a === b) return 0
+    const posicao = a.compareDocumentPosition(b)
+    if (posicao & Node.DOCUMENT_POSITION_FOLLOWING) return -1
+    if (posicao & Node.DOCUMENT_POSITION_PRECEDING) return 1
+    return 0
+  })
+}
+
+/** `true` quando o elemento desenha caixa — cobre `v-show`, `display:none` e pai colapsado. */
+function temCaixa(el: HTMLElement): boolean {
+  return el.getClientRects().length > 0
+}
+
+function semAcento(texto: string): string {
+  return texto
+    .normalize('NFD')
+    .replace(/\p{Diacritic}/gu, '')
+    .toLowerCase()
+    .trim()
+}
+
+/**
+ * O desempate de sempre, agora explícito: entre os vivos, o primeiro do
+ * documento que aparece na tela. É o que roda quando o passo não define `pick`.
+ */
+export const escolhaPadrao: TourPick = elementos => {
+  if (elementos.length <= 1) return elementos[0] ?? null
+  return elementos.find(temCaixa) ?? elementos[0] ?? null
+}
+
+// ---------------------------------------------------------------------------
+// Escolhas — fecham a pipeline devolvendo UM elemento.
+// ---------------------------------------------------------------------------
+
+/** O primeiro do documento entre os que sobraram. */
+export const primeiro: TourPick = elementos => elementos[0] ?? null
+
+/** O último do documento entre os que sobraram. */
+export const ultimo: TourPick = elementos => elementos[elementos.length - 1] ?? null
+
+/** Por posição, 0-based. Índice negativo conta do fim (`nEsimo(-1)` = último). */
+export function nEsimo(indice: number): TourPick {
+  return elementos => elementos.at(indice) ?? null
+}
+
+// ---------------------------------------------------------------------------
+// Filtros — afunilam os candidatos e devolvem outro array.
+// ---------------------------------------------------------------------------
+
+/**
+ * Só os que estão à vista. É o filtro certo para bloco duplicado por perfil ou
+ * aba que continua montada escondida (`v-show`) — os dois casos em que o alvo
+ * "certo" é simplesmente o único visível.
+ */
+export const visiveis: TourFilter = elementos => elementos.filter(temCaixa)
+
+/** Só os que o seletor CSS aceita. Seletor inválido derruba tudo, sem lançar. */
+export function queCasam(seletor: string): TourFilter {
+  return elementos => {
+    try {
+      return elementos.filter(el => el.matches(seletor))
+    } catch {
+      return []
+    }
+  }
+}
+
+/**
+ * Só os que contêm o texto — comparação sem acento e sem caixa, porque o texto
+ * na tela vem de dado do usuário e ninguém acerta a acentuação de cabeça.
+ */
+export function comTexto(texto: string): TourFilter {
+  const procurado = semAcento(texto)
+  return elementos => elementos.filter(el => semAcento(el.textContent ?? '').includes(procurado))
+}
+
+/** Escape hatch: qualquer predicado. Recebe também o índice na lista já filtrada. */
+export function queSatisfazem(predicado: (el: HTMLElement, indice: number) => boolean): TourFilter {
+  return elementos => elementos.filter(predicado)
+}
+
+// ---------------------------------------------------------------------------
+// Composição
+// ---------------------------------------------------------------------------
+
+/**
+ * Encadeia filtros e termina numa escolha:
+ *
+ * ```ts
+ * { target: 'linha', pick: escolher(visiveis, primeiro) }
+ * { target: 'chip', pick: escolher(comTexto('Situação')) }
+ * ```
+ *
+ * Um passo que devolve array continua a pipeline; o primeiro que devolve
+ * elemento (ou `null`) encerra. Sem escolha no fim, assume `primeiro` — é o que
+ * quase sempre se quer depois de filtrar.
+ */
+export function escolher(...passos: Array<TourFilter | TourPick>): TourPick {
+  return elementos => {
+    let atuais = elementos
+
+    for (const passo of passos) {
+      const saida = passo(atuais)
+      if (saida === null) return null
+      if (Array.isArray(saida)) {
+        atuais = saida
+        continue
+      }
+      return saida
+    }
+
+    return atuais[0] ?? null
+  }
+}

package/src/components/help/tour-posicionar.ts

@@ -0,0 +1,148 @@
+import type { BalloonPosition, SpotlightRect, TourPlacement } from './acai-ui-help-interface'
+
+/**
+ * Geometria do tour, isolada do DOM de propósito.
+ *
+ * Tudo aqui é função pura sobre números: o componente lê os retângulos com
+ * `getBoundingClientRect()` e passa pra cá. Isso deixa o miolo difícil
+ * (flip/clamp do balão) testável sem montar nada.
+ */
+
+export interface Viewport {
+  width: number
+  height: number
+}
+
+export interface Tamanho {
+  width: number
+  height: number
+}
+
+/** Distância entre o recorte e o balão, em px. */
+export const ESPACO_BALAO = 12
+
+/** Respiro mínimo entre o balão e a borda da janela, em px. */
+export const MARGEM_JANELA = 8
+
+/** Ordem de tentativa quando o passo não escolhe um lado. */
+const ORDEM_AUTO: Exclude<TourPlacement, 'auto'>[] = ['bottom', 'top', 'right', 'left']
+
+function limitar(valor: number, minimo: number, maximo: number): number {
+  // `maximo < minimo` acontece quando o balão é maior que a janela; nesse caso
+  // vale mais grudar no topo/esquerda do que devolver um número invertido.
+  if (maximo < minimo) return minimo
+  return Math.min(Math.max(valor, minimo), maximo)
+}
+
+/**
+ * Cresce o retângulo do elemento pela folga do recorte e o mantém dentro da
+ * janela — sem isso, um alvo colado na borda gera um buraco com pedaço fora
+ * da tela e a máscara fica torta.
+ */
+export function expandirRecorte(
+  alvo: SpotlightRect,
+  padding: number,
+  viewport: Viewport,
+): SpotlightRect {
+  const esquerda = Math.max(0, alvo.left - padding)
+  const topo = Math.max(0, alvo.top - padding)
+  const direita = Math.min(viewport.width, alvo.left + alvo.width + padding)
+  const base = Math.min(viewport.height, alvo.top + alvo.height + padding)
+
+  return {
+    left: esquerda,
+    top: topo,
+    width: Math.max(0, direita - esquerda),
+    height: Math.max(0, base - topo),
+  }
+}
+
+/** `true` quando o alvo saiu inteiro da área visível (usuário rolou demais). */
+export function estaForaDaJanela(alvo: SpotlightRect, viewport: Viewport): boolean {
+  return (
+    alvo.top + alvo.height <= 0 ||
+    alvo.top >= viewport.height ||
+    alvo.left + alvo.width <= 0 ||
+    alvo.left >= viewport.width
+  )
+}
+
+function posicionarNoLado(
+  lado: Exclude<TourPlacement, 'auto'>,
+  alvo: SpotlightRect,
+  balao: Tamanho,
+): { top: number; left: number } {
+  const centroX = alvo.left + alvo.width / 2 - balao.width / 2
+  const centroY = alvo.top + alvo.height / 2 - balao.height / 2
+
+  switch (lado) {
+    case 'bottom':
+      return { top: alvo.top + alvo.height + ESPACO_BALAO, left: centroX }
+    case 'top':
+      return { top: alvo.top - balao.height - ESPACO_BALAO, left: centroX }
+    case 'right':
+      return { top: centroY, left: alvo.left + alvo.width + ESPACO_BALAO }
+    case 'left':
+      return { top: centroY, left: alvo.left - balao.width - ESPACO_BALAO }
+  }
+}
+
+function cabe(pos: { top: number; left: number }, balao: Tamanho, viewport: Viewport): boolean {
+  return (
+    pos.top >= MARGEM_JANELA &&
+    pos.left >= MARGEM_JANELA &&
+    pos.top + balao.height <= viewport.height - MARGEM_JANELA &&
+    pos.left + balao.width <= viewport.width - MARGEM_JANELA
+  )
+}
+
+/**
+ * Escolhe onde o balão fica: tenta o lado pedido, vira pro lado oposto/livre
+ * se não couber (*flip*) e, em último caso, gruda dentro da janela (*clamp*).
+ *
+ * O `side` devolvido é o lado REAL usado — é ele que orienta a setinha, senão
+ * a seta aponta pro nada quando houve flip.
+ */
+export function posicionarBalao(
+  alvo: SpotlightRect,
+  balao: Tamanho,
+  viewport: Viewport,
+  placement: TourPlacement = 'auto',
+): BalloonPosition {
+  const candidatos: Exclude<TourPlacement, 'auto'>[] =
+    placement === 'auto'
+      ? ORDEM_AUTO
+      : [placement, ...ORDEM_AUTO.filter(lado => lado !== placement)]
+
+  for (const lado of candidatos) {
+    const pos = posicionarNoLado(lado, alvo, balao)
+    if (cabe(pos, balao, viewport)) return { ...pos, side: lado }
+  }
+
+  // Nenhum lado coube inteiro — mantém o lado preferido e encaixa na força.
+  const ladoFinal = candidatos[0]!
+  const bruto = posicionarNoLado(ladoFinal, alvo, balao)
+
+  return {
+    top: limitar(bruto.top, MARGEM_JANELA, viewport.height - balao.height - MARGEM_JANELA),
+    left: limitar(bruto.left, MARGEM_JANELA, viewport.width - balao.width - MARGEM_JANELA),
+    side: ladoFinal,
+  }
+}
+
+/** Passo sem âncora (ex.: boas-vindas): balão no meio da tela, sem recorte. */
+export function centralizarBalao(balao: Tamanho, viewport: Viewport): BalloonPosition {
+  return {
+    top: limitar(
+      viewport.height / 2 - balao.height / 2,
+      MARGEM_JANELA,
+      viewport.height - balao.height - MARGEM_JANELA,
+    ),
+    left: limitar(
+      viewport.width / 2 - balao.width / 2,
+      MARGEM_JANELA,
+      viewport.width - balao.width - MARGEM_JANELA,
+    ),
+    side: 'bottom',
+  }
+}

package/src/components/help/tour-registry.ts

@@ -0,0 +1,177 @@
+import type { Directive } from 'vue'
+import { escolhaPadrao, ordenarPorDocumento } from './tour-escolha'
+import type { TourAnchor, TourFilter, TourStep } from './acai-ui-help-interface'
+
+/**
+ * Registro dos alvos do tour.
+ *
+ * A diretiva `v-acai-tour="'cpf'"` guarda o elemento aqui e o passo referencia
+ * pelo nome. É preferível ao seletor CSS porque sobrevive a renomeação de
+ * classe/id e não depende da DOM interna de nenhum componente.
+ *
+ * O valor é um `Set` (e não um elemento só) porque `v-for`, `keep-alive` e
+ * remount podem registrar o mesmo nome mais de uma vez — inclusive com o
+ * `mounted` do novo elemento rodando ANTES do `unmounted` do antigo.
+ */
+const registro = new Map<string, Set<HTMLElement>>()
+
+/** Espera padrão pelo alvo aparecer no DOM, em ms. */
+export const ESPERA_PADRAO = 1500
+
+export function registrarAlvo(nome: string, el: HTMLElement): void {
+  const atuais = registro.get(nome)
+  if (atuais) atuais.add(el)
+  else registro.set(nome, new Set([el]))
+}
+
+export function removerAlvo(nome: string, el: HTMLElement): void {
+  const atuais = registro.get(nome)
+  if (!atuais) return
+  atuais.delete(el)
+  if (atuais.size === 0) registro.delete(nome)
+}
+
+/** Só para testes — o app nunca precisa chamar. */
+export function limparRegistro(): void {
+  registro.clear()
+}
+
+/**
+ * Todos os elementos vivos sob este nome, **em ordem de documento**.
+ *
+ * A ordem importa: o `Set` guarda por ordem de MONTAGEM, que com `v-if`,
+ * `Suspense` ou chunk assíncrono não acompanha a ordem da tela. "O primeiro"
+ * precisa significar o de cima, sempre.
+ */
+export function obterAlvos(nome: string): HTMLElement[] {
+  const elementos = registro.get(nome)
+  if (!elementos) return []
+  return ordenarPorDocumento([...elementos].filter(el => el.isConnected))
+}
+
+/** Elemento registrado sob este nome, ou `null` se nenhum está no documento. */
+export function obterAlvo(nome: string): HTMLElement | null {
+  return escolhaPadrao(obterAlvos(nome))
+}
+
+/**
+ * Só os candidatos que estão DENTRO de um alvo registrado (ou de um elemento
+ * que casa com o seletor CSS). É o escopo sem inventar conceito de escopo:
+ * `escolher(dentroDe('aba-servidores'))` desempata o mesmo nome usado em duas
+ * abas que ficam montadas ao mesmo tempo.
+ *
+ * O próprio contêiner conta como "dentro" — apontar pro bloco e pro que está
+ * nele com o mesmo filtro não deve dar em nada.
+ */
+export function dentroDe(nomeOuSeletor: string): TourFilter {
+  return elementos => {
+    const containers = obterAlvos(nomeOuSeletor)
+
+    if (containers.length > 0) {
+      return elementos.filter(el => containers.some(pai => pai.contains(el)))
+    }
+
+    try {
+      return elementos.filter(el => el.closest(nomeOuSeletor) !== null)
+    } catch {
+      // Nome que não está registrado e também não é seletor válido.
+      return []
+    }
+  }
+}
+
+/** `true` quando o passo não aponta pra lugar nenhum — balão centralizado, sem recorte. */
+export function passoSemAncora(passo: TourStep): boolean {
+  return !passo.target && !passo.selector
+}
+
+/** Texto do que se procurou — pro warn de DEV e pro payload de `step-skipped`. */
+export function descreverAncora(ancora: TourAnchor): string {
+  return ancora.target ?? ancora.selector ?? '(sem alvo)'
+}
+
+/**
+ * Uma tentativa, sem espera: registro primeiro, seletor CSS como reserva.
+ * O `pick` da âncora arbitra os dois — inclusive o `selector`, que também pode
+ * casar com vários elementos.
+ */
+export function resolverAlvo(ancora: TourAnchor): HTMLElement | null {
+  const escolher = ancora.pick ?? escolhaPadrao
+
+  if (ancora.target) {
+    const candidatos = obterAlvos(ancora.target)
+    if (candidatos.length > 0) {
+      const escolhido = escolher(candidatos)
+      if (escolhido) return escolhido
+    }
+  }
+
+  if (ancora.selector) {
+    try {
+      // `querySelectorAll` já devolve em ordem de documento.
+      const candidatos = [...document.querySelectorAll<HTMLElement>(ancora.selector)].filter(
+        el => el.isConnected,
+      )
+      const escolhido = escolher(candidatos)
+      if (escolhido?.isConnected) return escolhido
+    } catch {
+      // Seletor inválido vindo do consumidor — tratado como "não achou".
+    }
+  }
+
+  return null
+}
+
+/**
+ * Tenta resolver o alvo até `timeout`, olhando de novo a cada frame. Cobre o
+ * caso comum de um passo apontar pra algo que só existe depois do carregamento
+ * dos dados (linha de tabela, botão que aparece com resultado).
+ *
+ * `sinal` permite desistir antes do teto — é o que o botão "Pular" do balão
+ * usa: sem ele, a espera de um alvo que nunca vem prende o tour em silêncio.
+ */
+export function aguardarAlvo(
+  ancora: TourAnchor,
+  timeout: number = ancora.waitFor ?? ESPERA_PADRAO,
+  sinal?: AbortSignal,
+): Promise<HTMLElement | null> {
+  const imediato = resolverAlvo(ancora)
+  if (imediato) return Promise.resolve(imediato)
+  if (sinal?.aborted) return Promise.resolve(null)
+
+  return new Promise(resolve => {
+    const limite = Date.now() + timeout
+
+    const tentar = (): void => {
+      if (sinal?.aborted) return resolve(null)
+
+      const el = resolverAlvo(ancora)
+      if (el) return resolve(el)
+      if (Date.now() >= limite) return resolve(null)
+
+      if (typeof requestAnimationFrame === 'function') requestAnimationFrame(tentar)
+      else setTimeout(tentar, 16)
+    }
+
+    tentar()
+  })
+}
+
+/**
+ * Diretiva `v-acai-tour`. Aplicada num componente, o Vue a repassa pro elemento
+ * raiz dele — por isso não funciona em componente de múltiplas raízes
+ * (fragmento); nesse caso use `selector` no passo.
+ */
+export const vAcaiTour: Directive<HTMLElement, string | undefined> = {
+  mounted(el, binding) {
+    if (binding.value) registrarAlvo(binding.value, el)
+  },
+  updated(el, binding) {
+    if (binding.value === binding.oldValue) return
+    if (binding.oldValue) removerAlvo(binding.oldValue, el)
+    if (binding.value) registrarAlvo(binding.value, el)
+  },
+  unmounted(el, binding) {
+    if (binding.value) removerAlvo(binding.value, el)
+  },
+}

package/src/components/help/use-tour-visto.ts

@@ -0,0 +1,81 @@
+import { ref, type Ref } from 'vue'
+
+/**
+ * Memória de "este usuário já fez este tour".
+ *
+ * Mesmo formato de persistência do `use-preferencias.ts`: singleton reativo +
+ * `localStorage` com try/catch, porque em navegador com cookies/armazenamento
+ * bloqueado o acesso lança e não pode derrubar a tela.
+ */
+const CHAVE = 'acai-ui:tours-vistos'
+
+/** Singleton: todos os `<acai-ui-help>` da app compartilham o mesmo estado. */
+let vistos: Ref<string[]> | null = null
+
+function carregar(): string[] {
+  if (typeof window === 'undefined') return []
+  try {
+    const bruto = window.localStorage.getItem(CHAVE)
+    if (!bruto) return []
+    const salvo: unknown = JSON.parse(bruto)
+    if (!Array.isArray(salvo)) return []
+    return salvo.filter((id): id is string => typeof id === 'string')
+  } catch {
+    // localStorage indisponível ou JSON inválido — começa do zero.
+    return []
+  }
+}
+
+function salvar(lista: string[]): void {
+  if (typeof window === 'undefined') return
+  try {
+    window.localStorage.setItem(CHAVE, JSON.stringify(lista))
+  } catch {
+    // Cota estourada ou modo restrito: a memória em RAM continua valendo
+    // nesta sessão, só não sobrevive ao reload.
+  }
+}
+
+function estado(): Ref<string[]> {
+  if (!vistos) vistos = ref<string[]>(carregar())
+  return vistos
+}
+
+export function useTourVisto() {
+  const lista = estado()
+
+  function jaViu(id: string): boolean {
+    return lista.value.includes(id)
+  }
+
+  function marcarVisto(id: string): void {
+    if (lista.value.includes(id)) return
+    lista.value = [...lista.value, id]
+    salvar(lista.value)
+  }
+
+  /** Faz este tour voltar a ser oferecido (útil no botão "ver de novo"). */
+  function esquecerTour(id: string): void {
+    if (!lista.value.includes(id)) return
+    lista.value = lista.value.filter(item => item !== id)
+    salvar(lista.value)
+  }
+
+  function limparVistos(): void {
+    lista.value = []
+    salvar(lista.value)
+  }
+
+  return { vistos: lista, jaViu, marcarVisto, esquecerTour, limparVistos }
+}
+
+/** Só para testes — descarta o singleton e o que está gravado. */
+export function resetarTourVistoParaTeste(): void {
+  vistos = null
+  if (typeof window === 'undefined') return
+  try {
+    window.localStorage.removeItem(CHAVE)
+  } catch {
+    /* nada a fazer */
+  }
+}

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

@@ -0,0 +1,12 @@
+import type { QIconProps } from 'quasar'
+import type { MaterialIconValues } from '../../constants/lista-icons'
+import type { MedidasKeys } from '../../constants/medidas-espacos'
+
+export interface IconProps {
+  name: MaterialIconValues
+  size?: MedidasKeys | (string & {})
+  color?: QIconProps['color']
+  outlined?: boolean
+  /** Marca o ícone como decorativo (aria-hidden="true"). Use quando o ícone acompanhar texto que já transmite o significado (eMAG 1.2). */
+  decorative?: boolean
+}

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

@@ -0,0 +1,33 @@
+<template>
+  <q-icon
+    :name="nomeResolvido"
+    :size="tamanhoResolvido"
+    :color="color"
+    :aria-hidden="props.decorative ? 'true' : undefined"
+    class="acai-ui-icon"
+  >
+    <slot />
+  </q-icon>
+</template>
+
+<script setup lang="ts">
+import { computed } from "vue";
+import type { IconProps } from "./acai-ui-icon-interface";
+import { Medidas } from "../../constants/medidas-espacos";
+import type { MedidasKeys } from "../../constants/medidas-espacos";
+
+const props = withDefaults(defineProps<IconProps>(), {
+  outlined: false,
+  size: "lg",
+});
+
+const nomeResolvido = computed(() =>
+  props.outlined ? `o_${props.name}` : props.name,
+);
+
+const tamanhoResolvido = computed(() => {
+  if (!props.size) return undefined;
+  if (props.size in Medidas) return Medidas[props.size as MedidasKeys];
+  return props.size;
+});
+</script>