acai-ui 1.65.5

package/src/hooks/use-filtros-na-url.ts

@@ -0,0 +1,174 @@
+// Filtros de pesquisa na query string — sair da tela e voltar sem perder a busca.
+//
+// O ganho é o de sempre em listagem: a pessoa filtra, abre um registro, volta —
+// e hoje encontra o formulário limpo. Com os filtros na URL ela volta pro que
+// estava vendo, e de brinde consegue mandar o link da pesquisa pra outra pessoa.
+//
+// 🔴 DADO PESSOAL: o que entra aqui entra no histórico do navegador, é colado em
+// conversa, e cai no LOG DE ACESSO do servidor. Filtro de CPF, RG ou nome
+// completo precisa de `excluir`. O default sincroniza tudo porque é o
+// comportamento previsível, mas ele erra pro lado inseguro — leia `excluir`
+// antes de usar em tela com dado de pessoa.
+//
+// ℹ️ Este é o hook de BAIXO NÍVEL: ele guarda e devolve os filtros, e a tela
+// continua dona de quando buscar. Se a tela é o combo `<acai-ui-form>` +
+// `<acai-ui-table>`, prefira `useListagemNaUrl`, que amarra pesquisa, paginação,
+// histórico e cache num pacote só.
+
+import { type Ref } from 'vue'
+import {
+  clonarMolde,
+  criarAdaptador,
+  criarMapa,
+  escreverNaUrl,
+  lerDaUrl,
+  type TipoFiltroUrl,
+} from './filtros-url-internos'
+
+export type { TipoFiltroUrl }
+
+export interface OpcoesFiltrosNaUrl {
+  /**
+   * Chaves que NUNCA aparecem na URL. É onde mora dado pessoal (CPF, RG, nome).
+   *
+   * Simétrico de propósito: a chave excluída também não é LIDA da URL. Se
+   * alguém colar `?cpf=...` à mão, o valor é ignorado — senão "não publicamos
+   * isso" viraria "não publicamos, mas aceitamos".
+   *
+   * Aceita a chave inteira (`'periodo'`) ou uma folha (`'periodo.from'`).
+   */
+  excluir?: readonly string[]
+  /**
+   * Tipo declarado por campo, quando o valor inicial não consegue dizer.
+   *
+   * 🔴 É o que faz o hook servir a formulário de verdade. O padrão dos apps
+   * DETRAN é derivar o modelo do request do swagger trocando `undefined` por
+   * `null` (os componentes exigem `string | number | null` e `v-model` não
+   * compila com `readonly`) — e aí `cargoId: null` não diz que é número, então
+   * a URL devolveria `'12'` em vez de `12`, calado, direto pro payload.
+   *
+   * ```ts
+   * useFiltrosNaUrl(formulario, {
+   *   tipos: { cargoId: 'number', regimeJuridicoId: 'number', progressoMinimo: 'number' },
+   * })
+   * ```
+   *
+   * Campo declarado aqui é governado mesmo que não exista no valor inicial —
+   * declarar é decisão explícita de quem escreveu a tela, diferente de aceitar
+   * chave desconhecida vinda da URL.
+   */
+  tipos?: Readonly<Record<string, TipoFiltroUrl>>
+  /**
+   * Prefixo das chaves. Só é necessário quando DUAS listagens convivem na mesma
+   * rota e as duas têm um filtro de mesmo nome, que sem prefixo se sobrescrevem.
+   */
+  prefixo?: string
+  /** Ler a URL na entrada. Default `true`. */
+  hidratar?: boolean
+}
+
+export interface FiltrosNaUrl {
+  /**
+   * Grava o estado atual dos filtros na URL. Chame no `buscar()`, não a cada
+   * tecla — senão a URL fica pulando enquanto a pessoa digita.
+   *
+   * Em tela onde o submit só reposiciona a página e deixa um `watch` buscar,
+   * chame na função que de fato dispara a requisição, não no `@submit`.
+   */
+  sincronizar: () => void
+  /** Remove os filtros da URL. Chame no `resetar()`. */
+  limpar: () => void
+  /**
+   * `true` quando a URL trouxe algum filtro na entrada.
+   *
+   * Em tela que NÃO busca no mount, é o gatilho de restaurar o resultado —
+   * senão o formulário volta preenchido com a tabela vazia:
+   * `if (hidratou) void pesquisar()`.
+   */
+  hidratou: boolean
+}
+
+/**
+ * Mantém os filtros de pesquisa na query string.
+ *
+ * Chame no `setup`, ANTES do primeiro `buscar()`: a hidratação é síncrona, então
+ * o `onMounted(buscar)` que a tela já tem sai com os filtros da URL e não há
+ * segunda requisição.
+ *
+ * ```ts
+ * const filtros = ref(filtrosVistoriaVazios())
+ * // `excluir`: CPF na URL vai pro log de acesso do servidor.
+ * // `tipos`: campo que nasce `null` não diz que é número.
+ * const { sincronizar, limpar } = useFiltrosNaUrl(filtros, {
+ *   excluir: ['cpf'],
+ *   tipos: { cargoId: 'number' },
+ * })
+ *
+ * async function buscar(): Promise<void> {
+ *   sincronizar()
+ *   await executar(limparCamposVazios(filtros.value))
+ * }
+ *
+ * function resetar(): void {
+ *   filtros.value = limparModelo(filtros.value)
+ *   limpar()
+ * }
+ *
+ * onMounted(buscar)
+ * ```
+ *
+ * **Tipos suportados:** string, number, boolean, Date, array de primitivo (chave
+ * repetida: `?sort=nome,asc&sort=idade,desc`) e **objeto de um nível** de
+ * primitivos, que vira caminho com ponto — `{ periodo: { from, to } }` sai como
+ * `?periodo.from=…&periodo.to=…`. É o formato do `<acai-ui-date-range>`, então
+ * filtro de período funciona sem o consumidor achatar nada. Dois níveis não.
+ *
+ * **O tipo sai do valor inicial** do objeto (o "molde"), e `tipos` tem
+ * precedência sobre ele.
+ *
+ * **Chave que não está no molde nem em `tipos` é ignorada** — sem isso a URL
+ * viraria vetor de injeção (`?size=99999` descendo direto pro `executar()`).
+ *
+ * ⚠️ A hidratação acontece UMA vez, no `setup`. Voltar/avançar no navegador não
+ * repõe o formulário, e a gravação usa `replace` (pesquisa não vira histórico).
+ * Quem quer a URL como fonte da verdade — com voltar funcionando e cache — usa
+ * `useListagemNaUrl`.
+ */
+export function useFiltrosNaUrl<T extends object>(
+  filtros: Ref<T>,
+  opcoes: OpcoesFiltrosNaUrl = {},
+): FiltrosNaUrl {
+  const { excluir = [], tipos = {}, prefixo = '', hidratar = true } = opcoes
+
+  const adaptador = criarAdaptador()
+  const mapa = criarMapa(clonarMolde(filtros.value), { excluir, tipos, prefixo })
+
+  function hidratarDaUrl(): boolean {
+    const alteracoes = lerDaUrl(mapa, adaptador.ler(), filtros.value as Record<string, unknown>)
+    if (Object.keys(alteracoes).length === 0) return false
+
+    // Um único assign: reatividade dispara uma vez, e a tela nunca observa um
+    // estado meio-hidratado.
+    filtros.value = { ...filtros.value, ...alteracoes } as T
+    return true
+  }
+
+  function sincronizar(): void {
+    // `replace` e não `push`: dez pesquisas não podem virar dez cliques no
+    // voltar pra sair da tela.
+    adaptador.gravar(
+      escreverNaUrl(mapa, adaptador.ler(), filtros.value as Record<string, unknown>),
+      'replace',
+    )
+  }
+
+  function limpar(): void {
+    const params = adaptador.ler()
+    for (const caminho of mapa.caminhos) params.delete(mapa.naUrl(caminho))
+    adaptador.gravar(params, 'replace')
+  }
+
+  const hidratou = hidratar ? hidratarDaUrl() : false
+
+  return { sincronizar, limpar, hidratou }
+}

package/src/hooks/use-leitura-voz.ts

@@ -0,0 +1,346 @@
+import { readonly, ref, type Ref } from 'vue'
+
+/**
+ * Leitura em voz alta pela Web Speech API do próprio navegador.
+ *
+ * Sem dependência nova e sem rede: a síntese é do sistema operacional, o que
+ * importa numa máquina de balcão do DETRAN que pode não ter saída pra internet.
+ *
+ * NUNCA fala sozinho — quem dispara é sempre um clique do usuário (WCAG 1.4.2:
+ * áudio automático precisa de controle; não ter autoplay resolve na raiz).
+ */
+
+/** Identidade do trecho lido — é o que faz cada botão saber se é ELE que fala. */
+export type IdLeitura = string
+
+export interface OpcoesFala {
+  /** Identidade do trecho. Sem id, o botão não consegue mostrar "estou lendo". */
+  id?: IdLeitura | undefined
+  /** Idioma BCP-47 da fala (ex.: `pt-BR`). @default 'pt-BR' */
+  lang?: string | undefined
+  /** Velocidade da fala, 0.1 a 10. @default 1 */
+  rate?: number | undefined
+  /**
+   * Nome da voz (`SpeechSynthesisVoice.name`), como veio de `vozes`.
+   *
+   * É por NOME e não pelo objeto porque é isso que dá pra persistir. Voz que não
+   * existe mais na máquina (perfil novo, Windows sem o pacote) cai na escolha
+   * automática em vez de emudecer.
+   */
+  voz?: string | undefined
+}
+
+interface RegistroVoz {
+  lendo: Ref<boolean>
+  idLendo: Ref<IdLeitura | null>
+  suportado: Ref<boolean>
+  vozes: Ref<SpeechSynthesisVoice[]>
+  /**
+   * Token anti-corrida. `cancel()` dispara `onerror` nas falas pendentes DEPOIS
+   * de a próxima já ter começado; sem comparar geração, o erro da fala velha
+   * zeraria o estado da nova. Mesmo padrão do `sessao` do `acai-ui-tour`.
+   */
+  geracao: number
+  ouvindoVozes: boolean
+  ouvindoVisibilidade: boolean
+}
+
+/**
+ * Estado global, e não um `let` de módulo, pelo mesmo motivo documentado no
+ * `plugin.ts`: o Vite do consumidor pode carregar a lib em DUAS instâncias (o
+ * pré-bundle do import bare e o source pela condition `vue`). Com `let`, o botão
+ * de um componente não saberia que o outro está falando — e duas falas ao mesmo
+ * tempo é sempre bug, porque `speechSynthesis` é único do documento.
+ */
+const CHAVE_GLOBAL = Symbol.for('@acai-ui:voz')
+
+/** Fatia perto disso: acima de ~15s de fala o Chrome corta no meio (ver `falar`). */
+const MAX_CARACTERES = 160
+
+function sintese(): SpeechSynthesis | null {
+  if (typeof window === 'undefined') return null
+  try {
+    return window.speechSynthesis ?? null
+  } catch {
+    // Alguns navegadores em modo restrito lançam ao tocar na API.
+    return null
+  }
+}
+
+function temSuporte(): boolean {
+  return Boolean(sintese()) && typeof window !== 'undefined' && 'SpeechSynthesisUtterance' in window
+}
+
+function criarRegistro(): RegistroVoz {
+  return {
+    lendo: ref(false),
+    idLendo: ref<IdLeitura | null>(null),
+    suportado: ref(temSuporte()),
+    vozes: ref<SpeechSynthesisVoice[]>([]),
+    geracao: 0,
+    ouvindoVozes: false,
+    ouvindoVisibilidade: false,
+  }
+}
+
+function registro(): RegistroVoz {
+  const alvo = globalThis as unknown as Record<symbol, RegistroVoz | undefined>
+  const atual = alvo[CHAVE_GLOBAL]
+  if (atual) return atual
+  const novo = criarRegistro()
+  alvo[CHAVE_GLOBAL] = novo
+  return novo
+}
+
+/**
+ * Quebra o texto em pedaços que cabem numa fala curta.
+ *
+ * O Chrome interrompe uma fala longa por volta de 15 segundos. A saída é
+ * enfileirar vários pedaços curtos de uma vez (o motor toca em sequência) em vez
+ * de uma fala só. Corta em fim de frase; se não houver, no último espaço; só
+ * parte palavra quando a "palavra" sozinha já estoura o limite (URL, token).
+ */
+export function fatiarTexto(texto: string, max = MAX_CARACTERES): string[] {
+  const limpo = texto.replace(/\s+/g, ' ').trim()
+  if (!limpo) return []
+  if (limpo.length <= max) return [limpo]
+
+  const pedacos: string[] = []
+  let resto = limpo
+
+  while (resto.length > max) {
+    const janela = resto.slice(0, max)
+    const fimDeFrase = Math.max(
+      janela.lastIndexOf('. '),
+      janela.lastIndexOf('! '),
+      janela.lastIndexOf('? '),
+      janela.lastIndexOf('; '),
+      janela.lastIndexOf(': '),
+    )
+    // +1 pra levar a pontuação junto: quem lê precisa da pausa dela.
+    const corte = fimDeFrase > max * 0.4 ? fimDeFrase + 1 : janela.lastIndexOf(' ')
+    const posicao = corte > 0 ? corte : max
+
+    pedacos.push(resto.slice(0, posicao).trim())
+    resto = resto.slice(posicao).trim()
+  }
+
+  if (resto) pedacos.push(resto)
+  return pedacos
+}
+
+/**
+ * Cacheia as vozes instaladas.
+ *
+ * `getVoices()` costuma vir vazio na primeira chamada e só popula no evento
+ * `voiceschanged`. Isso NÃO é motivo pra esperar antes de falar: no Safari/iOS o
+ * `speak()` precisa acontecer dentro do gesto do usuário, e aguardar o evento
+ * perde essa janela. Sem voz escolhida, o motor usa a do `lang` mesmo.
+ */
+function garantirVozes(): void {
+  const estado = registro()
+  const motor = sintese()
+  if (!motor) return
+
+  try {
+    estado.vozes.value = motor.getVoices() ?? []
+  } catch {
+    estado.vozes.value = []
+  }
+
+  if (estado.ouvindoVozes || typeof motor.addEventListener !== 'function') return
+  estado.ouvindoVozes = true
+  motor.addEventListener('voiceschanged', () => {
+    try {
+      registro().vozes.value = motor.getVoices() ?? []
+    } catch {
+      /* motor sumiu no meio do caminho */
+    }
+  })
+}
+
+const normalizarLang = (v: SpeechSynthesisVoice): string => v.lang.replace('_', '-').toLowerCase()
+
+/** Vozes que servem para um idioma — o que o seletor de voz oferece. */
+function vozesDoIdioma(lang: string): SpeechSynthesisVoice[] {
+  const prefixo = lang.slice(0, 2).toLowerCase()
+  return registro().vozes.value.filter((v) => normalizarLang(v).startsWith(prefixo))
+}
+
+/**
+ * Voz preferida do idioma, priorizando a LOCAL: voz de rede tem latência de
+ * segundos e simplesmente não fala em máquina sem internet.
+ *
+ * `nome` (a escolha salva do usuário) ganha de tudo — mas só se aquela voz ainda
+ * existir nesta máquina.
+ */
+function escolherVoz(lang: string, nome?: string): SpeechSynthesisVoice | undefined {
+  const vozes = registro().vozes.value
+  const alvo = lang.toLowerCase()
+  const prefixo = alvo.slice(0, 2)
+
+  const escolhida = nome ? vozes.find((v) => v.name === nome) : undefined
+  if (escolhida) return escolhida
+
+  return (
+    vozes.find((v) => normalizarLang(v) === alvo && v.localService) ??
+    vozes.find((v) => normalizarLang(v) === alvo) ??
+    vozes.find((v) => normalizarLang(v).startsWith(prefixo) && v.localService) ??
+    vozes.find((v) => normalizarLang(v).startsWith(prefixo))
+  )
+}
+
+function limparEstado(): void {
+  const estado = registro()
+  estado.lendo.value = false
+  estado.idLendo.value = null
+}
+
+function pararInterno(): void {
+  const estado = registro()
+  // Invalida o que estiver na fila ANTES do cancel: os `onerror` que ele dispara
+  // chegam com a geração velha e são ignorados.
+  estado.geracao += 1
+  const motor = sintese()
+  if (motor) {
+    try {
+      motor.cancel()
+    } catch {
+      /* já estava parado */
+    }
+  }
+  limparEstado()
+}
+
+/** Para a leitura quando o usuário troca de aba — a fala continuaria no vazio. */
+function garantirObservadorDeVisibilidade(): void {
+  const estado = registro()
+  if (estado.ouvindoVisibilidade || typeof document === 'undefined') return
+  if (typeof document.addEventListener !== 'function') return
+  estado.ouvindoVisibilidade = true
+  document.addEventListener('visibilitychange', () => {
+    if (document.hidden) pararInterno()
+  })
+}
+
+export function useLeituraVoz(): {
+  suportado: Readonly<Ref<boolean>>
+  lendo: Readonly<Ref<boolean>>
+  idLendo: Readonly<Ref<IdLeitura | null>>
+  /** Vozes instaladas na máquina. Popula sozinha no `voiceschanged`. */
+  vozes: Readonly<Ref<SpeechSynthesisVoice[]>>
+  /** Vozes que servem para um idioma (prefixo BCP-47: `pt` casa `pt-BR` e `pt-PT`). */
+  vozesPara: (lang: string) => SpeechSynthesisVoice[]
+  /**
+   * Se dá pra ler NESTE idioma nesta máquina.
+   *
+   * Otimista de propósito: com a lista ainda vazia (o `voiceschanged` costuma
+   * chegar depois) devolve `true`. Esconder o botão por uma lista que ainda não
+   * carregou seria pior que tentar e falhar — e a falha real desliga o suporte.
+   */
+  temVozPara: (lang: string) => boolean
+  falar: (texto: string, opcoes?: OpcoesFala) => void
+  alternar: (texto: string, opcoes?: OpcoesFala) => void
+  parar: () => void
+} {
+  const estado = registro()
+
+  // Carrega a lista já na primeira montagem: o painel de preferências precisa
+  // dela ANTES de qualquer fala pra desenhar o seletor.
+  if (estado.suportado.value) garantirVozes()
+
+  function falar(texto: string, opcoes: OpcoesFala = {}): void {
+    const motor = sintese()
+    if (!motor || !estado.suportado.value) return
+
+    const pedacos = fatiarTexto(texto)
+    if (!pedacos.length) return
+
+    pararInterno()
+    garantirVozes()
+    garantirObservadorDeVisibilidade()
+
+    const minhaGeracao = estado.geracao
+    const lang = opcoes.lang || 'pt-BR'
+    const voz = escolherVoz(lang, opcoes.voz)
+    const ultimo = pedacos.length - 1
+
+    estado.lendo.value = true
+    estado.idLendo.value = opcoes.id ?? null
+
+    const enfileirar = (): void => {
+      // Fila montada de uma vez só, dentro do gesto do clique. Encadear
+      // `onend → speak(próximo)` perderia o contexto de ativação no Safari.
+      pedacos.forEach((pedaco, indice) => {
+        const fala = new SpeechSynthesisUtterance(pedaco)
+        fala.lang = lang
+        if (voz) fala.voice = voz
+        if (opcoes.rate !== undefined) fala.rate = opcoes.rate
+
+        fala.onend = (): void => {
+          if (minhaGeracao !== registro().geracao) return
+          if (indice === ultimo) limparEstado()
+        }
+
+        fala.onerror = (evento: SpeechSynthesisErrorEvent): void => {
+          // `canceled`/`interrupted` são o efeito normal de um `cancel()` — não
+          // são falha, e a fala nova já assumiu.
+          if (minhaGeracao !== registro().geracao) return
+          if (evento.error === 'canceled' || evento.error === 'interrupted') return
+          // Motor existe mas não fala (kiosk, Windows sem pacote de voz): esconde
+          // o recurso em vez de deixar botão que não faz nada.
+          if (
+            evento.error === 'synthesis-unavailable' ||
+            evento.error === 'synthesis-failed' ||
+            evento.error === 'not-allowed' ||
+            evento.error === 'audio-busy'
+          ) {
+            registro().suportado.value = false
+          }
+          limparEstado()
+        }
+
+        try {
+          motor.speak(fala)
+        } catch {
+          registro().suportado.value = false
+          limparEstado()
+        }
+      })
+    }
+
+    // Chrome trava o motor quando `cancel()` e `speak()` caem no mesmo tick.
+    if (motor.speaking || motor.pending) window.setTimeout(enfileirar, 0)
+    else enfileirar()
+  }
+
+  function parar(): void {
+    pararInterno()
+  }
+
+  /** Handler do botão: se já está lendo ESTE trecho, para; senão, fala. */
+  function alternar(texto: string, opcoes: OpcoesFala = {}): void {
+    const mesmo = estado.lendo.value && estado.idLendo.value === (opcoes.id ?? null)
+    if (mesmo) parar()
+    else falar(texto, opcoes)
+  }
+
+  return {
+    suportado: readonly(estado.suportado),
+    lendo: readonly(estado.lendo),
+    idLendo: readonly(estado.idLendo),
+    vozes: readonly(estado.vozes) as Readonly<Ref<SpeechSynthesisVoice[]>>,
+    vozesPara: vozesDoIdioma,
+    temVozPara: (lang: string): boolean =>
+      estado.vozes.value.length === 0 || vozesDoIdioma(lang).length > 0,
+    falar,
+    alternar,
+    parar,
+  }
+}
+
+/** Só para testes — descarta o singleton (espelha `resetarTourVistoParaTeste`). */
+export function resetarLeituraVozParaTeste(): void {
+  const alvo = globalThis as unknown as Record<symbol, RegistroVoz | undefined>
+  delete alvo[CHAVE_GLOBAL]
+}