acai-ui 1.65.5

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

@@ -0,0 +1,614 @@
+// Listagem cuja FONTE DA VERDADE é a URL.
+//
+// Feito para o combo `<acai-ui-form>` + `<acai-ui-table>`, que é o desenho de
+// toda listagem dos apps DETRAN. A diferença para o `useFiltrosNaUrl` é de quem
+// manda: lá a tela busca e a URL apenas anota o que foi buscado; aqui a URL é o
+// estado, e a tela é um reflexo dela.
+//
+// O que isso resolve, na ordem em que dói:
+//
+// 1. **Voltar funciona.** Trocar filtro é `push`, então o Voltar do navegador
+//    desfaz a pesquisa em vez de sair da tela. Paginar é `replace`, senão sair
+//    de uma listagem depois de folhear 8 páginas custaria 8 cliques no Voltar.
+// 2. **Voltar do detalhe não refaz a requisição.** A última pesquisa fica em
+//    cache, chaveada pela própria query string. Mesma query = mesma resposta.
+// 3. **A busca não espera a navegação.** A requisição sai na hora, e a URL é
+//    escrita em paralelo. Em app com `beforeEach` assíncrono (é o caso do
+//    gestao-pessoas, que revalida sessão a cada navegação), amarrar a busca ao
+//    router colocaria um round trip de rede na frente de toda pesquisa.
+//
+// 🔴 DADO PESSOAL: o que entra na URL entra no histórico do navegador, é colado
+// em conversa e cai no LOG DE ACESSO do servidor. CPF, RG e afins vão em
+// `excluir`. Vale o mesmo aviso do `useFiltrosNaUrl` — e aqui é mais grave,
+// porque `push` deixa rastro no histórico.
+
+import { computed, onScopeDispose, ref, shallowRef, type ComputedRef, type Ref } from 'vue'
+import {
+  assinatura,
+  clonarMolde,
+  criarAdaptador,
+  criarMapa,
+  escreverNaUrl,
+  lerDaUrl,
+  type TipoFiltroUrl,
+} from './filtros-url-internos'
+
+/** O que a tela precisa devolver para a tabela se pintar. */
+export interface ResultadoListagem<Linha> {
+  linhas: Linha[]
+  /** Total de registros no servidor. Sem ele, cai na contagem das linhas da página. */
+  totalItens?: number
+  /** Total de páginas. Sem ele, assume 1. */
+  totalPaginas?: number
+}
+
+/** O que o hook entrega para a função de busca. Vem da URL, não do formulário. */
+export interface ParametrosListagem<Filtros> {
+  /** Filtros já convertidos pelos `tipos` — o que a URL de fato carrega. */
+  filtros: Filtros
+  /**
+   * Página **1-based**, igual ao `v-model` do `<acai-ui-table>`.
+   *
+   * 🔴 **Com `paginacao: 'cliente'`, IGNORE.** Lá quem fatia é o hook, e a chave
+   * do cache não inclui a página de propósito — é isso que faz folhear não
+   * chamar `buscar`. Se a busca usar esta página nesse modo, a primeira fatia
+   * pedida fica em cache e passa a ser devolvida para TODAS as páginas: dado
+   * errado, sem erro nenhum. Nesse modo escreva `({ filtros }) => …`.
+   */
+  pagina: number
+}
+
+export interface OpcoesListagemNaUrl<Filtros extends object, Linha> {
+  /**
+   * Fábrica do estado inicial dos filtros. **Função, não objeto**: ela é chamada
+   * de novo no `limpar()`, e um objeto compartilhado voltaria já sujo da última
+   * pesquisa.
+   */
+  molde: () => Filtros
+  /**
+   * A requisição. Recebe o que está na URL e devolve o que a tabela mostra.
+   *
+   * Erro aqui NÃO é engolido nem quebra a tela: as linhas atuais ficam onde
+   * estão, `erro` recebe o que foi lançado e o resultado não vai pro cache.
+   * Quem trata (notificação, retry) é a tela — o hook não sabe o que é um erro
+   * aceitável no domínio dela.
+   */
+  buscar: (parametros: ParametrosListagem<Filtros>) => Promise<ResultadoListagem<Linha>>
+  /** Tipo declarado por campo. Ver `useFiltrosNaUrl` — mesma regra e mesmo motivo. */
+  tipos?: Readonly<Record<string, TipoFiltroUrl>>
+  /** Chaves que NUNCA entram na URL (dado pessoal). Simétrico: também não são lidas. */
+  excluir?: readonly string[]
+  /** Prefixo das chaves. Só necessário com DUAS listagens na mesma rota. */
+  prefixo?: string
+  /** Nome da chave de página na URL. Default `'pagina'`. */
+  chavePagina?: string
+  /**
+   * Quem fatia as páginas. Default `'servidor'`.
+   *
+   * - **`'servidor'`** — `buscar` recebe a página e devolve só ela. É o desenho
+   *   de API paginada (Spring e afins), e cada troca de página é uma requisição.
+   * - **`'cliente'`** — `buscar` devolve o conjunto INTEIRO e o hook fatia. Uma
+   *   requisição por conjunto de filtros; folhear não chama `buscar` nenhuma vez.
+   *
+   * 🔴 `'cliente'` existe para fonte que **não pagina** — SOAP, arquivo, endpoint
+   * legado que só sabe devolver tudo. Nesses casos paginar no servidor não é uma
+   * escolha de desenho: refazer a chamada a cada clique de página é o custo
+   * inteiro da consulta de novo (medido de 9 a 15s no SOAP do DETRAN).
+   *
+   * Não é atalho para fonte que pagina de verdade: com resultado grande, trazer
+   * tudo para fatiar no navegador troca uma requisição pequena por uma enorme.
+   */
+  paginacao?: 'servidor' | 'cliente'
+  /**
+   * Quantas linhas por página. Default `10`.
+   *
+   * ⚠️ **Só vale com `paginacao: 'cliente'`** — quem fatia no modo servidor é o
+   * servidor, e o hook não tem como impor tamanho de página a ele. Declarar aqui
+   * junto de `'servidor'` avisa em DEV e não faz nada.
+   */
+  itensPorPagina?: number
+  /**
+   * Buscar ao montar quando a URL está vazia? Default `true` — é o que toda
+   * listagem dos apps faz hoje (`onMounted(buscar)`). Passe `false` na tela que
+   * só deve buscar depois que a pessoa pesquisar.
+   *
+   * Com filtro na URL o hook busca de qualquer jeito: foi pedido explicitamente.
+   */
+  buscarAoMontar?: boolean
+}
+
+export interface ListagemNaUrl<Filtros extends object, Linha> {
+  /**
+   * Rascunho do formulário — é aqui que os campos dão `v-model`.
+   *
+   * É rascunho de propósito: digitar não pesquisa e não mexe na URL. O que está
+   * na URL é a pesquisa APLICADA, e as duas só se encontram no `pesquisar()`.
+   */
+  filtros: Ref<Filtros>
+  /**
+   * Os filtros que produziram as LINHAS que estão na tela — não o rascunho.
+   *
+   * Serve pra tudo que precisa acompanhar o resultado exibido em vez do que a
+   * pessoa está digitando. O caso real: listagem cujas COLUNAS dependem do
+   * filtro (situação `Ativo`/`Desligado` mostra ou não "Motivo de saída"). Com
+   * `filtros` o cabeçalho mudaria no meio da digitação, antes das linhas
+   * correspondentes chegarem.
+   *
+   * Só avança quando o resultado é aplicado — inclusive vindo do cache. Se a
+   * busca falha, continua descrevendo as linhas que ficaram na tela.
+   */
+  aplicados: Ref<Filtros>
+  /** `v-model` do `<acai-ui-table>`. Mudar aqui já pagina (e escreve na URL). */
+  pagina: Ref<number>
+  linhas: Ref<Linha[]>
+  totalItens: Ref<number>
+  totalPaginas: Ref<number>
+  carregando: Ref<boolean>
+  /** O que a última busca lançou, ou `null`. */
+  erro: Ref<unknown>
+  /** Props prontas do `<acai-ui-table>`: `v-bind="listagem.tabela"`. */
+  tabela: ComputedRef<{
+    rows: Linha[]
+    totalItems: number
+    totalPages: number
+    skeleton: boolean
+  }>
+  /** `@submit` do `<acai-ui-form>`. Aplica o rascunho, volta pra página 1. */
+  pesquisar: () => void
+  /** `@reset` do `<acai-ui-form>`. Devolve o molde e limpa a URL. */
+  limpar: () => void
+  /**
+   * Refaz a requisição da pesquisa atual, ignorando o cache.
+   *
+   * É o que chamar depois de excluir uma linha na própria tela.
+   */
+  recarregar: () => Promise<void>
+  /** Descarta o cache desta listagem sem refazer a busca agora. */
+  invalidar: () => void
+  /** `true` quando a tela abriu já com filtro na URL. */
+  hidratou: boolean
+}
+
+/**
+ * Cache da ÚLTIMA pesquisa de cada listagem.
+ *
+ * Fora do componente de propósito: o caso que ele existe pra resolver é
+ * justamente ir no detalhe e voltar, e nesse caminho a tela DESMONTA. Cache
+ * guardado no `setup` morreria exatamente quando seria útil.
+ *
+ * Uma entrada por listagem (rota + prefixo), e só a última pesquisa — foi a
+ * decisão tomada: cobre ir-e-voltar, que é o caso real, sem virar um cache de
+ * verdade com invalidação por chave, TTL e todo o custo de manter isso correto.
+ */
+interface EntradaCache {
+  chave: string
+  resultado: ResultadoListagem<unknown>
+  /** Qual instância do hook gravou. Serve pro aviso de dado velho em DEV. */
+  instancia: number
+}
+
+const cache = new Map<string, EntradaCache>()
+let proximaInstancia = 0
+
+/**
+ * Estamos renderizando no SERVIDOR?
+ *
+ * 🔴 Isto existe porque o `cache` acima é um `Map` de MÓDULO. No navegador ele é
+ * por aba e está correto. No Node do SSR ele é do PROCESSO: um objeto só para
+ * todas as requisições de todas as pessoas. Chaveado por rota + assinatura dos
+ * filtros, dois usuários com a mesma pesquisa passariam a compartilhar entrada —
+ * e em app que restringe resultado por perfil, a resposta de um alimentaria a
+ * tela do outro.
+ *
+ * Somado a isso, o `executar` é disparado sem espera (`void executar(...)`): no
+ * servidor a requisição SAI, não chega a tempo do HTML, e o resultado cai no
+ * cache compartilhado depois que a resposta já foi embora. Custo puro.
+ *
+ * As duas condições porque nenhuma sozinha cobre tudo: `import.meta.env.SSR` é
+ * do Vite (pode não existir em outro empacotador) e `window` é o teste de
+ * runtime que vale em qualquer lugar.
+ */
+const noServidor = (): boolean => import.meta.env.SSR === true || typeof window === 'undefined'
+
+/**
+ * Descarta o cache de listagem.
+ *
+ * 🔴 **Chame depois de gravar.** O cache não tem como saber que outra tela
+ * cadastrou, editou ou excluiu um registro que a listagem mostra — e sem isso a
+ * pessoa salva, volta pra lista e vê o dado velho.
+ *
+ * ```ts
+ * // na tela de cadastro, depois de salvar
+ * await salvar()
+ * invalidarListagens('/servidores')   // ou sem argumento, pra derrubar todas
+ * void router.push({ name: 'servidores' })
+ * ```
+ *
+ * Sem argumento derruba tudo. É grosso, mas é o padrão seguro: o custo de
+ * invalidar demais é uma requisição, e o de invalidar de menos é dado errado
+ * na tela.
+ */
+export function invalidarListagens(rota?: string): void {
+  if (rota === undefined) {
+    cache.clear()
+    return
+  }
+  for (const chave of [...cache.keys()]) {
+    if (chave === rota || chave.startsWith(`${rota}::`)) cache.delete(chave)
+  }
+}
+
+const avisouCacheVelho = new Set<string>()
+
+/**
+ * Listagem com a URL como fonte da verdade.
+ *
+ * ```ts
+ * const listagem = useListagemNaUrl({
+ *   molde: filtrosServidoresIniciais,
+ *   excluir: ['pessoalCpf'],
+ *   tipos: { cargoId: 'number', progressoMinimo: 'number' },
+ *   buscar: async ({ filtros, pagina }) => {
+ *     const dados = await listarServidores(montarParametros(filtros, pagina))
+ *     return {
+ *       linhas: dados.content ?? [],
+ *       totalItens: dados.page?.totalElements,
+ *       totalPaginas: dados.page?.totalPages,
+ *     }
+ *   },
+ * })
+ * ```
+ *
+ * ```html
+ * <acai-ui-form @submit="listagem.pesquisar()" @reset="listagem.limpar()">
+ *   <acai-ui-input v-model="listagem.filtros.value.pessoalNome" label="Nome" />
+ * </acai-ui-form>
+ *
+ * <acai-ui-table v-model="listagem.pagina.value" :columns="colunas" v-bind="listagem.tabela.value" />
+ * ```
+ *
+ * Com `<script setup>`, desestruture — todos os campos são ref/computed e
+ * continuam reativos: `const { filtros, pagina, tabela, pesquisar } = listagem`.
+ */
+export function useListagemNaUrl<Filtros extends object, Linha>(
+  opcoes: OpcoesListagemNaUrl<Filtros, Linha>,
+): ListagemNaUrl<Filtros, Linha> {
+  const {
+    molde: fabricaMolde,
+    buscar,
+    tipos = {},
+    excluir = [],
+    prefixo = '',
+    chavePagina = 'pagina',
+    paginacao = 'servidor',
+    itensPorPagina = 10,
+    buscarAoMontar = true,
+  } = opcoes
+
+  const fatiaNoCliente = paginacao === 'cliente'
+  // Guarda de divisão: `itensPorPagina: 0` faria `ceil(n/0)` virar Infinity e a
+  // tabela anunciar infinitas páginas.
+  const porPagina = Math.max(1, Math.trunc(itensPorPagina))
+
+  if (import.meta.env.DEV && !fatiaNoCliente && opcoes.itensPorPagina !== undefined) {
+    console.warn(
+      "[acai-ui] useListagemNaUrl: `itensPorPagina` só vale com `paginacao: 'cliente'`. " +
+        "No modo servidor quem decide o tamanho da página é o servidor — esta opção não faz nada.",
+    )
+  }
+
+  const adaptador = criarAdaptador()
+  const mapa = criarMapa(clonarMolde(fabricaMolde()), { excluir, tipos, prefixo })
+  /**
+   * Mapa SEM `excluir`, usado só pra chavear o cache.
+   *
+   * 🔴 Sem isso o cache mente. Filtro excluído muda a BUSCA mas não a URL, então
+   * chavear pela URL faz "pesquisar por CPF" bater na entrada da pesquisa
+   * anterior e devolver a lista inteira — resultado errado, sem erro nenhum.
+   * A chave sai do ESTADO; a URL continua sem o dado pessoal.
+   */
+  const mapaChave = criarMapa(clonarMolde(fabricaMolde()), { tipos, prefixo })
+  const chavePaginaUrl = `${prefixo}${chavePagina}`
+  const chaveCache = `${adaptador.rota()}::${prefixo}`
+  /**
+   * A rota em que este hook nasceu.
+   *
+   * 🔴 Sem isto o hook age na rota que estiver ATIVA, não na dele. Ao sair da
+   * listagem para o detalhe, o watcher da query dispara com a query do DESTINO,
+   * e uma escrita atrasada (a tabela reposicionando a página quando o total
+   * chega, por exemplo) grava os filtros e o `pagina` na URL do detalhe.
+   *
+   * Medido: sair de `/servidores?nome=ana&pagina=3` para
+   * `/servidores/7?origem=servidores&origemLabel=Servidores` terminava em
+   * `/servidores/7?origem=servidores&origemLabel=Servidores&pagina=2`. Isso suja
+   * justamente a query de onde a trilha de breadcrumb do app lê a cadeia de
+   * origem — e um `push` desses ainda cria entrada de histórico no detalhe,
+   * quebrando o Voltar.
+   */
+  const rotaDona = adaptador.rota()
+  const instancia = ++proximaInstancia
+
+  const filtros = ref(fabricaMolde()) as Ref<Filtros>
+  const aplicados = ref(fabricaMolde()) as Ref<Filtros>
+  const pagina = ref(1)
+  const linhas = shallowRef<Linha[]>([]) as Ref<Linha[]>
+  const totalItens = ref(0)
+  const totalPaginas = ref(1)
+  const carregando = ref(false)
+  const erro = ref<unknown>(null)
+
+  /**
+   * Assinatura da pesquisa que está NA TELA. É a chave do cache e o critério de
+   * "a URL mudou por fora": se o que chegou na URL bate com isto, o hook mesmo
+   * escreveu, e não há o que reagir.
+   */
+  let chaveAtual = ''
+  /** Corrida: só a resposta da última busca disparada pode pintar a tabela. */
+  let requisicaoAtual = 0
+  /** Uma vez por listagem — o aviso é de código, não de dado. */
+  let avisouTotais = false
+
+  /** Estado (filtros + página) → os params da URL. */
+  function paramsDe(valores: Filtros, numeroPagina: number): URLSearchParams {
+    const base = adaptador.ler()
+    base.delete(chavePaginaUrl)
+    // Dado pessoal colado à mão na barra não sobrevive à primeira pesquisa —
+    // com `push`, ele entraria em toda entrada seguinte do histórico.
+    mapa.removerExcluidas(base)
+    const params = escreverNaUrl(mapa, base, valores as Record<string, unknown>)
+    // Página 1 fica FORA da URL, mesma regra do filtro no default: `?pagina=1`
+    // seria ruído em toda listagem recém-aberta.
+    if (numeroPagina > 1) params.set(chavePaginaUrl, String(numeroPagina))
+    return params
+  }
+
+  /** Assinatura da URL — serve pra saber se a mudança veio de fora do hook. */
+  function chaveDe(params: URLSearchParams): string {
+    const dosFiltros = assinatura(mapa, params)
+    const daPagina = params.get(chavePaginaUrl) ?? '1'
+    return `${dosFiltros}|${chavePaginaUrl}=${daPagina}`
+  }
+
+  /**
+   * Assinatura da BUSCA — inclui os filtros excluídos da URL. Chave do cache.
+   *
+   * 🔴 No modo cliente a PÁGINA fica de fora, e é essa ausência que faz o recurso
+   * existir: a entrada do cache passa a valer para o conjunto inteiro, então
+   * folhear cai no cache em vez de chamar `buscar`. No modo servidor a página
+   * continua na chave — lá cada página é uma resposta diferente.
+   */
+  function chaveDaBusca(valores: Filtros, numeroPagina: number): string {
+    const params = escreverNaUrl(mapaChave, new URLSearchParams(), valores as Record<string, unknown>)
+    const dosFiltros = assinatura(mapaChave, params)
+    if (fatiaNoCliente) return dosFiltros
+    return `${dosFiltros}|${chavePaginaUrl}=${numeroPagina}`
+  }
+
+  function paginaDe(params: URLSearchParams): number {
+    const bruto = Number(params.get(chavePaginaUrl))
+    return Number.isFinite(bruto) && bruto >= 1 ? Math.trunc(bruto) : 1
+  }
+
+  /**
+   * Recebe a página em vez de ler `pagina.value`.
+   *
+   * O `aplicar` grava o ref antes de chamar o `executar`, então ler de lá daria
+   * o mesmo número hoje — mas amarraria o fatiamento à ordem de duas atribuições
+   * distantes. Explícito não tem como sair de sincronia.
+   */
+  function aplicarResultado(
+    resultado: ResultadoListagem<Linha>,
+    valores: Filtros,
+    numeroPagina: number,
+  ): void {
+    if (fatiaNoCliente) {
+      const todas = resultado.linhas
+      totalItens.value = todas.length
+      // `max(1, …)` mantém "1 página" no resultado vazio, igual ao modo servidor
+      // — tabela com 0 páginas não tem o que mostrar na paginação.
+      totalPaginas.value = Math.max(1, Math.ceil(todas.length / porPagina))
+      const inicio = (numeroPagina - 1) * porPagina
+      // Página fora do intervalo (`?pagina=99` com 3 páginas) devolve lista
+      // vazia. Não reposiciono pra última: isso exigiria escrever na URL durante
+      // a aplicação do resultado, que é a classe de escrita atrasada que sujou a
+      // URL da tela de destino na 1.63.2.
+      linhas.value = todas.slice(inicio, inicio + porPagina)
+    } else {
+      linhas.value = resultado.linhas
+      totalItens.value = resultado.totalItens ?? resultado.linhas.length
+      totalPaginas.value = resultado.totalPaginas ?? 1
+    }
+    // Só aqui, junto das linhas: `aplicados` descreve o que está na tela. Mover
+    // isto pro início da requisição faria o cabeçalho da tabela mudar enquanto
+    // as linhas antigas ainda estão sendo exibidas.
+    aplicados.value = clonarMolde(valores)
+  }
+
+  /**
+   * No modo cliente os totais saem do tamanho do resultado, então `totalItens` e
+   * `totalPaginas` devolvidos pela busca são ignorados. Avisa porque o erro
+   * provável é copiar uma listagem de servidor e trocar só o `paginacao` — e o
+   * sintoma seria uma contagem que não confere, sem erro nenhum.
+   */
+  function avisarTotaisIgnorados(resultado: ResultadoListagem<Linha>): void {
+    if (!import.meta.env.DEV || !fatiaNoCliente) return
+    if (resultado.totalItens === undefined && resultado.totalPaginas === undefined) return
+    if (avisouTotais) return
+    avisouTotais = true
+    console.warn(
+      "[acai-ui] useListagemNaUrl: com `paginacao: 'cliente'` o hook conta as linhas que a " +
+        "busca devolveu — `totalItens` e `totalPaginas` do resultado são ignorados. Devolva só `linhas`.",
+    )
+  }
+
+  async function executar(valores: Filtros, numeroPagina: number): Promise<void> {
+    // 🔴 No servidor o hook para aqui: nem busca, nem lê, nem escreve o cache.
+    // Os filtros JÁ foram hidratados da URL pelo `aplicar`, então o formulário
+    // renderiza preenchido e a tabela renderiza vazia — que é exatamente o que o
+    // cliente vai renderizar no primeiro quadro, antes de a busca dele voltar.
+    // É isso que mantém a hidratação casando; buscar aqui produziria HTML com
+    // linhas que o cliente não teria, e aí sim daria divergência.
+    if (noServidor()) return
+
+    const chave = chaveDaBusca(valores, numeroPagina)
+    const entrada = cache.get(chaveCache)
+    if (entrada && entrada.chave === chave) {
+      // Servido do cache: nenhuma requisição.
+      if (import.meta.env.DEV && entrada.instancia !== instancia && !avisouCacheVelho.has(chave)) {
+        avisouCacheVelho.add(chave)
+        console.info(
+          `[acai-ui] useListagemNaUrl: "${chaveCache}" foi servida do cache da visita anterior. ` +
+            'Se alguma tela gravou dados desde então, chame invalidarListagens() depois de salvar.',
+        )
+      }
+      aplicarResultado(entrada.resultado as ResultadoListagem<Linha>, valores, numeroPagina)
+      erro.value = null
+      return
+    }
+
+    const meuTicket = ++requisicaoAtual
+    carregando.value = true
+    erro.value = null
+    try {
+      const resultado = await buscar({ filtros: clonarMolde(valores), pagina: numeroPagina })
+      // Resposta velha de uma pesquisa que o usuário já trocou: descarta.
+      if (meuTicket !== requisicaoAtual) return
+      avisarTotaisIgnorados(resultado)
+      aplicarResultado(resultado, valores, numeroPagina)
+      cache.set(chaveCache, { chave, resultado: resultado as ResultadoListagem<unknown>, instancia })
+    } catch (falha) {
+      if (meuTicket !== requisicaoAtual) return
+      // Linhas ficam como estão: apagar a tabela por causa de um 500 tira da
+      // pessoa o resultado que ela tinha, sem ganho nenhum.
+      erro.value = falha
+    } finally {
+      if (meuTicket === requisicaoAtual) carregando.value = false
+    }
+  }
+
+  /**
+   * Aplica um estado: escreve a URL e dispara a busca.
+   *
+   * As duas coisas em paralelo, e a busca NÃO espera a navegação — ver o
+   * cabeçalho do arquivo.
+   */
+  /** A tela ainda está no ar? Fora da rota dona o hook não escreve nem busca. */
+  function naRotaDona(): boolean {
+    return adaptador.rota() === rotaDona
+  }
+
+  function aplicar(
+    valores: Filtros,
+    numeroPagina: number,
+    modo: 'push' | 'replace' | 'nenhum',
+  ): void {
+    // A navegação já saiu daqui: escrever agora grava os filtros desta listagem
+    // na URL de OUTRA tela, e buscar seria requisição para uma tabela que
+    // ninguém está vendo. Acontece de verdade — o `v-model` da tabela ainda
+    // reposiciona a página enquanto o componente é desmontado.
+    if (!naRotaDona()) return
+
+    const params = paramsDe(valores, numeroPagina)
+    const chave = chaveDe(params)
+
+    filtros.value = valores
+    pagina.value = numeroPagina
+    chaveAtual = chave
+
+    if (modo !== 'nenhum') adaptador.gravar(params, modo)
+    void executar(valores, numeroPagina)
+  }
+
+  function pesquisar(): void {
+    // Sempre volta pra página 1: manter a pessoa na página 7 de um resultado que
+    // acabou de mudar é mostrar "nenhum registro" numa busca que tem resultado.
+    aplicar(clonarMolde(filtros.value), 1, 'push')
+  }
+
+  function limpar(): void {
+    aplicar(fabricaMolde(), 1, 'push')
+  }
+
+  async function recarregar(): Promise<void> {
+    cache.delete(chaveCache)
+    await executar(filtros.value, pagina.value)
+  }
+
+  function invalidar(): void {
+    cache.delete(chaveCache)
+  }
+
+  // ── Entrada: a URL manda ────────────────────────────────────────────────────
+  const paramsIniciais = adaptador.ler()
+  const doUrl = lerDaUrl(mapa, paramsIniciais, filtros.value as Record<string, unknown>)
+  const hidratou = Object.keys(doUrl).length > 0 || paramsIniciais.has(chavePaginaUrl)
+
+  if (hidratou) {
+    // `nenhum`: a URL já está do jeito certo — reescrevê-la no mount criaria uma
+    // entrada de histórico duplicada e, num app com guard assíncrono, uma
+    // navegação inútil a cada visita.
+    aplicar({ ...filtros.value, ...doUrl } as Filtros, paginaDe(paramsIniciais), 'nenhum')
+  } else if (buscarAoMontar) {
+    aplicar(filtros.value, 1, 'nenhum')
+  } else {
+    chaveAtual = chaveDe(paramsDe(filtros.value, 1))
+  }
+
+  // ── URL mudando por fora: voltar/avançar, link, barra de endereço ───────────
+  const parar = adaptador.observar?.(() => {
+    // 🔴 A query mudou porque a navegação saiu daqui, não porque alguém mexeu
+    // NESTA listagem. Sem esta linha o hook se re-hidrata a partir da query da
+    // outra tela: o estado é zerado e uma requisição sai para uma tabela que
+    // ninguém está vendo. O `aplicar` também se protege, mas parar aqui evita o
+    // trabalho inteiro.
+    if (!naRotaDona()) return
+
+    const params = adaptador.ler()
+    const chave = chaveDe(params)
+    // Foi o próprio hook que escreveu — nada a fazer.
+    if (chave === chaveAtual) return
+
+    const alteracoes = lerDaUrl(mapa, params, fabricaMolde() as Record<string, unknown>)
+    // Parte do MOLDE, não do estado atual: voltar pra uma URL sem `nome` tem que
+    // limpar o campo nome, e não manter o que a pesquisa anterior tinha nele.
+    aplicar({ ...fabricaMolde(), ...alteracoes } as Filtros, paginaDe(params), 'nenhum')
+  })
+
+  if (parar) onScopeDispose(parar)
+
+  // ── Paginação: o `v-model` do table escreve aqui ────────────────────────────
+  // Não é `watch(pagina)`: o próprio `aplicar` mexe em `pagina.value`, e o watch
+  // reentraria a cada busca. A tabela chama isto por `v-model`, e só ela.
+  const paginaModel = computed<number>({
+    get: () => pagina.value,
+    set: (nova) => {
+      if (nova === pagina.value) return
+      // `replace`: folhear 8 páginas não pode custar 8 cliques no Voltar.
+      aplicar(clonarMolde(filtros.value), nova, 'replace')
+    },
+  })
+
+  const tabela = computed(() => ({
+    rows: linhas.value,
+    totalItems: totalItens.value,
+    totalPages: totalPaginas.value,
+    skeleton: carregando.value,
+  }))
+
+  return {
+    filtros,
+    aplicados,
+    pagina: paginaModel,
+    linhas,
+    totalItens,
+    totalPaginas,
+    carregando,
+    erro,
+    tabela,
+    pesquisar,
+    limpar,
+    recarregar,
+    invalidar,
+    hidratou,
+  }
+}