acai-ui 1.65.5

package/src/hooks/filtros-url-internos.ts

@@ -0,0 +1,497 @@
+// Núcleo compartilhado de filtros na query string.
+//
+// Interno: NÃO é exportado no index da lib. Existe porque `useFiltrosNaUrl` e
+// `useListagemNaUrl` precisam da MESMA regra de serialização — se cada um
+// tivesse a sua, o link gerado por uma tela não abriria na outra, e a diferença
+// só apareceria em produção.
+//
+// O que mora aqui é a parte PURA (molde → caminhos → texto → volta) mais o
+// adaptador de URL. Política (quando gravar, o que disparar) fica em cada hook.
+
+import { getCurrentInstance, watch } from 'vue'
+
+/** Tipos que sobrevivem a uma query string. Sufixo `[]` = chave repetida. */
+export type TipoFiltroUrl =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'string[]'
+  | 'number[]'
+  | 'boolean[]'
+  | 'date[]'
+
+/**
+ * Separador do caminho aninhado: `?periodo.from=2026-01-01`.
+ *
+ * Ponto, e não junção camelCase (`periodoFrom`), por dois motivos: é legal em
+ * query string sem escapar, e não corre o risco de colidir com um campo que se
+ * chame de verdade `periodoFrom`. Ler a URL também mostra a estrutura.
+ */
+export const SEPARADOR = '.'
+
+type TipoEscalar = 'string' | 'number' | 'boolean' | 'date'
+
+interface Descritor {
+  escalar: TipoEscalar
+  ehArray: boolean
+}
+
+/** Marcador de "não deu pra converter" — distinto de `null`, que é valor válido. */
+const INVALIDO = Symbol('invalido')
+
+export function ehObjetoSimples(valor: unknown): valor is Record<string, unknown> {
+  return (
+    valor !== null && typeof valor === 'object' && !Array.isArray(valor) && !(valor instanceof Date)
+  )
+}
+
+function descritorDeclarado(tipo: TipoFiltroUrl): Descritor {
+  const ehArray = tipo.endsWith('[]')
+  return { escalar: (ehArray ? tipo.slice(0, -2) : tipo) as TipoEscalar, ehArray }
+}
+
+function escalarDoValor(valor: unknown): TipoEscalar {
+  if (typeof valor === 'number') return 'number'
+  if (typeof valor === 'boolean') return 'boolean'
+  if (valor instanceof Date) return 'date'
+  // Também o caso de `null`/`undefined`: não há tipo a inferir, e string é o que
+  // menos estraga. Quem precisa do tipo certo declara em `tipos`.
+  return 'string'
+}
+
+function descritorDoValor(valor: unknown): Descritor {
+  if (Array.isArray(valor)) {
+    // Array vazio não tem elemento pra amostrar — os itens ficam string. A
+    // requisição sai igual (`ids=1&ids=2`, o backend converte); só o tipo em TS
+    // fica otimista. `tipos: { ids: 'number[]' }` resolve.
+    return { escalar: valor.length > 0 ? escalarDoValor(valor[0]) : 'string', ehArray: true }
+  }
+  return { escalar: escalarDoValor(valor), ehArray: false }
+}
+
+/**
+ * Converte o texto da URL para o tipo resolvido.
+ *
+ * ⚠️ Nunca "converter se parecer número": matrícula, CEP e protocolo têm zero à
+ * esquerda, e `'00123'` viraria `123`. A conversão só acontece quando o tipo diz
+ * que aquele campo é número.
+ */
+function coagirEscalar(texto: string, escalar: TipoEscalar): unknown {
+  if (escalar === 'number') {
+    const numero = Number(texto)
+    return texto.trim() !== '' && Number.isFinite(numero) ? numero : INVALIDO
+  }
+  if (escalar === 'boolean') {
+    if (texto === 'true') return true
+    if (texto === 'false') return false
+    return INVALIDO
+  }
+  if (escalar === 'date') {
+    const data = new Date(texto)
+    return Number.isNaN(data.getTime()) ? INVALIDO : data
+  }
+  return texto
+}
+
+export function coagir(brutos: string[], descritor: Descritor): unknown {
+  if (descritor.ehArray) {
+    const itens = brutos
+      .map((bruto) => coagirEscalar(bruto, descritor.escalar))
+      .filter((item) => item !== INVALIDO)
+    return itens.length > 0 ? itens : INVALIDO
+  }
+  const primeiro = brutos[0]
+  return primeiro === undefined ? INVALIDO : coagirEscalar(primeiro, descritor.escalar)
+}
+
+export function ehInvalido(valor: unknown): boolean {
+  return valor === INVALIDO
+}
+
+/** Valor do filtro → texto da URL. `null` significa "não vai pra URL". */
+export function paraTexto(valor: unknown): string | null {
+  if (valor === null || valor === undefined || valor === '') return null
+  if (valor instanceof Date) return Number.isNaN(valor.getTime()) ? null : valor.toISOString()
+  if (typeof valor === 'string') return valor
+  if (typeof valor === 'number') return Number.isFinite(valor) ? String(valor) : null
+  if (typeof valor === 'boolean') return String(valor)
+  return null
+}
+
+/**
+ * Mesma regra de "vazio" do `limparCamposVazios`: `''`, `null`, `undefined` e
+ * array sem item aproveitável ficam fora. `false` e `0` são valores de verdade e
+ * entram.
+ *
+ * ⚠️ Escrito à mão em vez de chamar o `limparCamposVazios`, que era o óbvio: ele
+ * trata `Date` como objeto aninhado, e como `Date` não tem chave própria
+ * enumerável, o `Object.keys({}).length === 0` DERRUBA o campo. Um filtro de data
+ * desaparecia da URL sem aviso. Aqui `Date` é valor escalar.
+ */
+export function estaVazio(valor: unknown): boolean {
+  if (valor === null || valor === undefined || valor === '') return true
+  if (Array.isArray(valor)) {
+    return valor.every((item) => item === null || item === undefined || item === '')
+  }
+  return false
+}
+
+/**
+ * O valor está no default do molde?
+ *
+ * Vale como "vazio" pra efeito de URL: se o campo está do jeito que nasceu, não
+ * há nada a lembrar. Sem isso, uma listagem recém-aberta já escreve
+ * `?page=0&size=10&somenteAtivos=false` — a URL vira ruído antes de a pessoa
+ * pesquisar.
+ *
+ * Não se perde informação: chave ausente na URL cai no molde na hidratação, que
+ * é exatamente o mesmo valor.
+ */
+export function igualAoMolde(valor: unknown, molde: unknown): boolean {
+  if (valor instanceof Date && molde instanceof Date) return valor.getTime() === molde.getTime()
+  if (Array.isArray(valor) && Array.isArray(molde)) {
+    return valor.length === molde.length && valor.every((item, i) => item === molde[i])
+  }
+  return valor === molde
+}
+
+const avisados = new Set<string>()
+
+/** Só um nível de aninhamento tem serialização honesta em query string. */
+export function avisarNaoSuportado(caminho: string, motivo: string): void {
+  if (!import.meta.env.DEV || avisados.has(caminho)) return
+  avisados.add(caminho)
+  console.warn(
+    `[acai-ui] filtros na URL: o filtro "${caminho}" ${motivo} e não vai pra URL. ` +
+      'Achate o campo, declare em `tipos`, ou use `excluir` pra silenciar este aviso.',
+  )
+}
+
+/**
+ * Cópia que preserva o TIPO de cada campo, um nível adentro.
+ *
+ * Existe porque o molde é lido no `setup` e consultado depois: guardar a
+ * referência viva faria o molde mudar junto com o filtro, e a conversão passaria
+ * a se basear no que o usuário digitou em vez do valor inicial.
+ */
+export function clonarMolde<T extends object>(origem: T): T {
+  const saida: Record<string, unknown> = {}
+  for (const [chave, valor] of Object.entries(origem)) {
+    if (Array.isArray(valor)) saida[chave] = [...valor]
+    else if (valor instanceof Date) saida[chave] = new Date(valor.getTime())
+    else if (ehObjetoSimples(valor)) saida[chave] = { ...valor }
+    else saida[chave] = valor
+  }
+  return saida as T
+}
+
+/** Lê `periodo.from` (ou `nome`) de um objeto. Um nível só. */
+export function lerEm(alvo: Record<string, unknown> | undefined, caminho: string): unknown {
+  if (!alvo) return undefined
+  const partes = caminho.split(SEPARADOR)
+  const raiz = alvo[partes[0] as string]
+  if (partes.length === 1) return raiz
+  return ehObjetoSimples(raiz) ? raiz[partes[1] as string] : undefined
+}
+
+/** Contrato mínimo de leitura/escrita de URL. Duas implementações abaixo. */
+export interface AdaptadorUrl {
+  ler: () => URLSearchParams
+  /** `push` cria entrada no histórico; `replace` substitui a atual. */
+  gravar: (params: URLSearchParams, modo: 'push' | 'replace') => void
+  /** Caminho da rota, sem query. É a chave do cache por tela. */
+  rota: () => string
+  /**
+   * Avisa quando a URL muda POR FORA (voltar/avançar, link, edição na barra).
+   * Devolve o desinscrito. Ausente onde não há como observar.
+   */
+  observar?: (aoMudar: () => void) => () => void
+}
+
+/**
+ * Shape do `$router` do vue-router que a gente usa. Declarado à mão porque a lib
+ * **não depende de vue-router** — ela apenas o aproveita quando ele existe.
+ */
+interface RouterCompativel {
+  /** Opcional de propósito — ver `ehRouterCompativel`. */
+  push?: (destino: { query: Record<string, string | string[]> }) => Promise<unknown> | unknown
+  replace: (destino: { query: Record<string, string | string[]> }) => Promise<unknown> | unknown
+  currentRoute: { value: { query: Record<string, unknown>; path?: string } }
+}
+
+/**
+ * `replace` + `currentRoute` bastam. `push` NÃO entra no teste: exigi-lo aqui
+ * derrubaria pro History qualquer shim de router que só implemente o que a lib
+ * usava até então — e cair no History por trás de um router deixa o
+ * `route.query` desatualizado, que é o pior desfecho possível. Sem `push`, o
+ * `gravar` degrada pra `replace` (perde histórico, mantém a URL correta).
+ */
+function ehRouterCompativel(alvo: unknown): alvo is RouterCompativel {
+  if (!alvo || typeof alvo !== 'object') return false
+  const candidato = alvo as Partial<RouterCompativel>
+  return typeof candidato.replace === 'function' && !!candidato.currentRoute
+}
+
+/** `URLSearchParams` → o formato de query do vue-router (repetida vira array). */
+function paramsParaQuery(params: URLSearchParams): Record<string, string | string[]> {
+  const query: Record<string, string | string[]> = {}
+  for (const chave of new Set(params.keys())) {
+    const valores = params.getAll(chave)
+    query[chave] = valores.length > 1 ? valores : (valores[0] as string)
+  }
+  return query
+}
+
+/**
+ * Descobre como mexer na URL.
+ *
+ * 🔴 Por que NÃO importar vue-router: a lib é agnóstica dele de propósito (quem
+ * usa só chip e input não pode ganhar peer dep). E por que não mexer direto no
+ * History quando ele existe: `history.replaceState` por trás do router deixa o
+ * `route.query` DESATUALIZADO — a URL diz uma coisa e a rota reativa diz outra,
+ * sem erro nenhum. Então: se o app instalou vue-router, `$router` está em
+ * `globalProperties` e a gente usa o dele. Se não, cai no History, onde não há
+ * router pra desincronizar.
+ */
+export function criarAdaptador(): AdaptadorUrl {
+  const router = getCurrentInstance()?.appContext.config.globalProperties.$router
+
+  if (ehRouterCompativel(router)) {
+    return {
+      ler: () => {
+        const params = new URLSearchParams()
+        for (const [chave, valor] of Object.entries(router.currentRoute.value.query)) {
+          if (Array.isArray(valor)) {
+            for (const item of valor) if (item != null) params.append(chave, String(item))
+          } else if (valor != null) {
+            params.append(chave, String(valor))
+          }
+        }
+        return params
+      },
+      gravar: (params, modo) => {
+        const navegar = modo === 'push' && router.push ? router.push : router.replace
+        void Promise.resolve(navegar.call(router, { query: paramsParaQuery(params) })).catch(() => {
+          // Navegação redundante (mesma query) não é erro — só não fazer nada.
+        })
+      },
+      rota: () => router.currentRoute.value.path ?? '',
+      // `currentRoute` é um ref do vue-router: dá pra observar sem importar a
+      // biblioteca. Cobre voltar/avançar, link colado e edição na barra — tudo
+      // que muda a URL sem passar pelo hook.
+      observar: (aoMudar) => watch(() => router.currentRoute.value.query, aoMudar, { deep: true }),
+    }
+  }
+
+  // ⚠️ Este ramo NÃO é o caminho do SSR de app real. A checagem do router vem
+  // antes, e no servidor o router existe — então app com vue-router (que é o
+  // caso de todos os consumidores) cai lá em cima, e cai certo: `ler()` e
+  // `rota()` do router funcionam no servidor e são o que permite o formulário
+  // renderizar já preenchido com os filtros da URL.
+  //
+  // O que NÃO pode acontecer no servidor é buscar e mexer em cache de módulo —
+  // e isso é barrado no `useListagemNaUrl`, não aqui. Ver `noServidor()` lá.
+  //
+  // Aqui é o fallback de ambiente sem window NEM router: teste de nó puro, ou
+  // consumidor que usa o hook sem router instalado.
+  if (typeof window === 'undefined') {
+    return { ler: () => new URLSearchParams(), gravar: () => undefined, rota: () => '' }
+  }
+
+  return {
+    ler: () => new URLSearchParams(window.location.search),
+    gravar: (params, modo) => {
+      const busca = params.toString()
+      const destino = `${window.location.pathname}${busca ? `?${busca}` : ''}${window.location.hash}`
+      if (modo === 'push') window.history.pushState(window.history.state, '', destino)
+      else window.history.replaceState(window.history.state, '', destino)
+    },
+    rota: () => window.location.pathname,
+    observar: (aoMudar) => {
+      window.addEventListener('popstate', aoMudar)
+      return () => window.removeEventListener('popstate', aoMudar)
+    },
+  }
+}
+
+export interface OpcoesMapa {
+  excluir?: readonly string[]
+  tipos?: Readonly<Record<string, TipoFiltroUrl>>
+  prefixo?: string
+}
+
+/**
+ * Mapa de um molde: quais caminhos este hook governa e como converter cada um.
+ *
+ * Governar é tudo: caminho fora daqui não é lido nem escrito — sem isso a URL
+ * viraria vetor de injeção (`?size=99999` descendo direto pro `executar()`).
+ */
+export interface MapaFiltros<T extends object> {
+  caminhos: string[]
+  molde: T
+  naUrl: (caminho: string) => string
+  descritorDe: (caminho: string) => Descritor
+  /**
+   * Remove da query as chaves marcadas em `excluir`.
+   *
+   * Não é o mesmo que "não escrever": aqui a chave é APAGADA mesmo que tenha
+   * chegado de fora. `excluir` marca dado pessoal, e uma chave dessas colada à
+   * mão na barra de endereço não pode sobreviver à primeira pesquisa — com
+   * `push`, ela seria copiada pra toda entrada seguinte do histórico.
+   */
+  removerExcluidas: (params: URLSearchParams) => void
+}
+
+export function criarMapa<T extends object>(molde: T, opcoes: OpcoesMapa = {}): MapaFiltros<T> {
+  const { excluir = [], tipos = {}, prefixo = '' } = opcoes
+  const excluidas = new Set(excluir)
+  const moldeBruto = molde as Record<string, unknown>
+
+  const estaExcluido = (caminho: string): boolean =>
+    excluidas.has(caminho) || excluidas.has(caminho.split(SEPARADOR)[0] as string)
+
+  const caminhos = (() => {
+    const encontrados: string[] = []
+
+    for (const [chave, valor] of Object.entries(molde)) {
+      if (!ehObjetoSimples(valor)) {
+        encontrados.push(chave)
+        continue
+      }
+      for (const [sub, subValor] of Object.entries(valor)) {
+        if (ehObjetoSimples(subValor)) {
+          avisarNaoSuportado(`${chave}${SEPARADOR}${sub}`, 'tem dois níveis de aninhamento')
+          continue
+        }
+        encontrados.push(`${chave}${SEPARADOR}${sub}`)
+      }
+    }
+
+    // Declarado em `tipos` mas ausente do molde: entra. É o caso do campo que
+    // nasce `null` sem forma (um `periodo: null` de date-range, por exemplo).
+    for (const declarado of Object.keys(tipos)) {
+      if (!encontrados.includes(declarado)) encontrados.push(declarado)
+    }
+
+    return encontrados.filter((caminho) => !estaExcluido(caminho))
+  })()
+
+  return {
+    caminhos,
+    molde,
+    naUrl: (caminho) => `${prefixo}${caminho}`,
+    removerExcluidas: (params) => {
+      for (const excluida of excluidas) {
+        // A chave excluída pode ser a raiz (`periodo`) de folhas que estão na
+        // URL como `periodo.from` — daí varrer por prefixo, e não só igualdade.
+        const alvo = `${prefixo}${excluida}`
+        for (const chave of [...new Set(params.keys())]) {
+          if (chave === alvo || chave.startsWith(`${alvo}${SEPARADOR}`)) params.delete(chave)
+        }
+      }
+    },
+    descritorDe: (caminho) => {
+      const declarado = tipos[caminho]
+      return declarado ? descritorDeclarado(declarado) : descritorDoValor(lerEm(moldeBruto, caminho))
+    },
+  }
+}
+
+/**
+ * Lê os caminhos governados de uma query. Devolve só o que a URL trouxe — chave
+ * ausente NÃO vira `undefined` no patch, senão hidratar apagaria o que já estava.
+ */
+export function lerDaUrl<T extends object>(
+  mapa: MapaFiltros<T>,
+  params: URLSearchParams,
+  atual: Record<string, unknown>,
+): Record<string, unknown> {
+  const alteracoes: Record<string, unknown> = {}
+  // Patches por chave-raiz: hidratar `periodo.from` não pode apagar o `to` que
+  // já estava no filtro.
+  const aninhados = new Map<string, Record<string, unknown>>()
+
+  for (const caminho of mapa.caminhos) {
+    const brutos = params.getAll(mapa.naUrl(caminho))
+    if (brutos.length === 0) continue
+
+    const valor = coagir(brutos, mapa.descritorDe(caminho))
+    if (ehInvalido(valor)) continue
+
+    const partes = caminho.split(SEPARADOR)
+    if (partes.length === 1) {
+      alteracoes[partes[0] as string] = valor
+      continue
+    }
+
+    const raiz = partes[0] as string
+    let patch = aninhados.get(raiz)
+    if (!patch) {
+      const valorAtual = atual[raiz]
+      patch = ehObjetoSimples(valorAtual) ? { ...valorAtual } : {}
+      aninhados.set(raiz, patch)
+    }
+    patch[partes[1] as string] = valor
+  }
+
+  for (const [raiz, patch] of aninhados) alteracoes[raiz] = patch
+  return alteracoes
+}
+
+/**
+ * Estado dos filtros → `URLSearchParams`, partindo da query ATUAL para não
+ * apagar chave alheia (`?aba=2` de outro componente na mesma rota).
+ */
+export function escreverNaUrl<T extends object>(
+  mapa: MapaFiltros<T>,
+  base: URLSearchParams,
+  estado: Record<string, unknown>,
+): URLSearchParams {
+  const params = new URLSearchParams(base)
+  for (const caminho of mapa.caminhos) params.delete(mapa.naUrl(caminho))
+
+  const moldeBruto = mapa.molde as Record<string, unknown>
+
+  for (const caminho of mapa.caminhos) {
+    const valor = lerEm(estado, caminho)
+    // Mesma regra do payload: campo vazio não viaja.
+    if (estaVazio(valor)) continue
+    // Nem campo intocado: só o que a pessoa mudou merece estar na URL.
+    if (igualAoMolde(valor, lerEm(moldeBruto, caminho))) continue
+
+    if (Array.isArray(valor)) {
+      // Chave REPETIDA, não junção por vírgula: o `sort` do Spring é
+      // `['dataHoraCadastro,desc']` — o próprio valor tem vírgula, e juntar
+      // corromperia o par na volta.
+      for (const item of valor) {
+        const texto = paraTexto(item)
+        if (texto !== null) params.append(mapa.naUrl(caminho), texto)
+      }
+      continue
+    }
+
+    if (ehObjetoSimples(valor)) {
+      avisarNaoSuportado(caminho, 'virou objeto depois da inicialização')
+      continue
+    }
+
+    const texto = paraTexto(valor)
+    if (texto !== null) params.append(mapa.naUrl(caminho), texto)
+  }
+
+  return params
+}
+
+/** Só os caminhos governados, ordenados — serve de chave de cache e de comparação. */
+export function assinatura<T extends object>(
+  mapa: MapaFiltros<T>,
+  params: URLSearchParams,
+): string {
+  const pares: string[] = []
+  for (const caminho of mapa.caminhos) {
+    const chave = mapa.naUrl(caminho)
+    for (const valor of params.getAll(chave)) pares.push(`${chave}=${valor}`)
+  }
+  return pares.sort().join('&')
+}

package/src/hooks/index.ts

@@ -0,0 +1,22 @@
+export { notificacao } from './notify'
+export { useValidacaoVisual } from './use-validacao-visual'
+export type { ErroValidacao, OpcoesValidacaoVisual, SeletoresValidacao } from './use-validacao-visual'
+export { useContadorSessao } from './use-contador-sessao'
+export type { OpcoesContadorSessao } from './use-contador-sessao'
+export { usePreferencias } from './use-preferencias'
+export type { PreferenciasAcaiUi, TemaAcaiUi, DaltonismoAcaiUi } from './use-preferencias'
+export { useLeituraVoz } from './use-leitura-voz'
+export type { IdLeitura, OpcoesFala } from './use-leitura-voz'
+export { useTamanhoElemento } from './use-tamanho-elemento'
+export type { TamanhoElemento, PadraoTamanho } from './use-tamanho-elemento'
+export { useTela, BREAKPOINTS } from './use-tela'
+export type { TelaAcaiUi } from './use-tela'
+export { useFiltrosNaUrl } from './use-filtros-na-url'
+export type { FiltrosNaUrl, OpcoesFiltrosNaUrl, TipoFiltroUrl } from './use-filtros-na-url'
+export { useListagemNaUrl, invalidarListagens } from './use-listagem-na-url'
+export type {
+  ListagemNaUrl,
+  OpcoesListagemNaUrl,
+  ParametrosListagem,
+  ResultadoListagem,
+} from './use-listagem-na-url'

package/src/hooks/notify.ts

@@ -0,0 +1,18 @@
+import { Notify } from 'quasar'
+
+interface NotificationModel {
+  message: string
+  color: 'positive' | 'negative' | 'warning'
+  timeout?: number
+}
+
+export const notificacao = ({ message, color, timeout = 5000 }: NotificationModel): void => {
+  Notify.create({
+    message: message,
+    color: color,
+    position: 'center',
+    timeout,
+    textColor: color === 'warning' ? 'black' : 'white',
+    actions: [{ label: 'Fechar', color: color === 'warning' ? 'black' : 'white' }],
+  })
+}

package/src/hooks/use-contador-sessao.ts

@@ -0,0 +1,95 @@
+import { computed, onBeforeUnmount, ref, toValue, watch, type MaybeRefOrGetter } from 'vue'
+
+export interface OpcoesContadorSessao {
+  /** Minutos restantes a partir dos quais `emAlerta` fica true. Default 5. */
+  minutosAlerta?: number
+  /** Chamado UMA vez quando o tempo zera. */
+  aoExpirar?: () => void
+}
+
+/**
+ * Contagem regressiva de sessão a partir de um instante de expiração.
+ * Aceita epoch em MILISSEGUNDOS ou `Date` (de um JWT: `exp * 1000`).
+ * Reativo — reinicia sozinho quando `expiraEm` muda; limpa o intervalo no unmount.
+ *
+ * @example
+ * const { horasMinutos, emAlerta } = useContadorSessao(() => usuario.value?.exp ? usuario.value.exp * 1000 : null)
+ */
+export function useContadorSessao(
+  expiraEm: MaybeRefOrGetter<number | Date | null | undefined>,
+  opcoes: OpcoesContadorSessao = {},
+) {
+  const minutosAlerta = opcoes.minutosAlerta ?? 5
+
+  const expiracaoMs = computed<number | null>(() => {
+    const v = toValue(expiraEm)
+    if (v instanceof Date) return v.getTime()
+    if (typeof v === 'number' && Number.isFinite(v)) return v
+    return null
+  })
+
+  const restanteMs = ref<number | null>(null)
+  let intervalo: number | null = null
+  let expirouEmitido = false
+
+  function parar(): void {
+    if (intervalo === null) return
+    window.clearInterval(intervalo)
+    intervalo = null
+  }
+
+  function tick(): void {
+    if (expiracaoMs.value === null) {
+      restanteMs.value = null
+      return
+    }
+    const restante = expiracaoMs.value - Date.now()
+    restanteMs.value = Math.max(0, restante)
+    if (restante <= 0) {
+      parar()
+      if (!expirouEmitido) {
+        expirouEmitido = true
+        opcoes.aoExpirar?.()
+      }
+    }
+  }
+
+  watch(
+    expiracaoMs,
+    (novo) => {
+      parar()
+      expirouEmitido = false
+      if (novo === null) {
+        restanteMs.value = null
+        return
+      }
+      tick()
+      intervalo = window.setInterval(tick, 1000)
+    },
+    { immediate: true },
+  )
+
+  onBeforeUnmount(parar)
+
+  const doisDigitos = (n: number): string => String(n).padStart(2, '0')
+
+  /** Tempo restante em HH:MM (ex.: "03:42"). "--" quando não há expiração. */
+  const horasMinutos = computed(() => {
+    if (restanteMs.value === null) return '--'
+    const totalSegundos = Math.floor(restanteMs.value / 1000)
+    return `${doisDigitos(Math.floor(totalSegundos / 3600))}:${doisDigitos(Math.floor((totalSegundos % 3600) / 60))}`
+  })
+
+  /** Tempo restante em HH:MM:SS (ex.: "03:42:07"). */
+  const horasMinutosSegundos = computed(() => {
+    if (restanteMs.value === null) return '--'
+    const s = Math.floor(restanteMs.value / 1000)
+    return `${doisDigitos(Math.floor(s / 3600))}:${doisDigitos(Math.floor((s % 3600) / 60))}:${doisDigitos(s % 60)}`
+  })
+
+  const emAlerta = computed(
+    () => restanteMs.value !== null && restanteMs.value <= minutosAlerta * 60_000,
+  )
+
+  return { restanteMs, horasMinutos, horasMinutosSegundos, emAlerta }
+}