acai-ui 1.65.5

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

@@ -0,0 +1,802 @@
+<template>
+  <!--
+    A MOLDURA é trocável; o conteúdo é escrito uma vez só.
+
+    - `q-drawer`: trilho fixo no desktop, gaveta lateral no tablet/celular
+      largo. É o comportamento de sempre.
+    - `q-dialog maximized` + slide-up: abaixo de `sheetBreakpoint` (600px) o
+      menu deixa de ser gaveta e vira FOLHA — sobe de baixo e ocupa a tela
+      inteira. Numa tela de 360px uma gaveta lateral nunca foi um bom negócio:
+      ou come a tela toda mesmo assim, ou sobra uma faixa inútil de backdrop.
+
+    Trocar só a moldura (e não duplicar o template em v-if/v-else) importa: a
+    árvore de navegação abaixo tem ~120 linhas com grupos, sub-grupos e badges.
+    Duas cópias divergiriam no primeiro ajuste.
+  -->
+  <!-- `ref` fica AQUI e não no `atributosRaiz`: em <script setup> um ref de
+       template é uma variável, e `ref: 'drawerRef'` dentro de um v-bind seria
+       tratado como string ref — que não existe mais. Na folha ele aponta pro
+       QDialog, e o `medirAncora` já se protege com `instanceof HTMLElement`. -->
+  <component :is="raiz" ref="drawerRef" v-bind="atributosRaiz">
+    <div ref="conteudoRef" class="drawer-container" :class="classesConteudo">
+      <!--
+        FOLHA — cabeçalho fixo, o único da tela.
+
+        Ele não some ao trocar de vista: é a mesma barra que muda de título e de
+        ícone. Trocar o CONTEÚDO embaixo de um cabeçalho estável é o que faz
+        parecer uma tela só com duas abas, em vez de dois painéis empilhados um
+        sobre o outro.
+      -->
+      <!--
+        Ações da folha — AO LADO da marca, na mesma linha da logo.
+
+        Posicionadas em absoluto sobre a linha da marca (mesma âncora do handle
+        e do botão de fechar da gaveta) em vez de numa barra própria acima. Uma
+        barra separada empurrava a logo pra baixo e deixava uma faixa vazia no
+        topo; aqui elas ocupam a quina que a marca cede via `padding-right`.
+
+        Fora da `<transition>` de propósito: são a parte FIXA da tela. Só o
+        conteúdo abaixo troca.
+      -->
+      <div v-if="ehFolhaMobile" class="drawer-folha__acoes" :style="estiloAcoes">
+        <button
+          v-if="preferences"
+          type="button"
+          class="acai-drawer-acao"
+          :aria-label="vista === 'menu' ? tituloPreferencias : 'Voltar ao menu'"
+          :aria-pressed="vista === 'preferencias'"
+          @click="vista = vista === 'menu' ? 'preferencias' : 'menu'"
+        >
+          <acai-ui-icon :name="vista === 'menu' ? 'tune' : 'menu'" size="20px" decorative />
+        </button>
+
+        <button
+          type="button"
+          class="acai-drawer-acao"
+          aria-label="Fechar menu"
+          @click="aberto = false"
+        >
+          <acai-ui-icon name="close" size="20px" decorative />
+        </button>
+      </div>
+
+      <!--
+      Fechar — só no modo mobile, e só com a gaveta aberta.
+
+      DENTRO do drawer, ao contrário do handle logo abaixo. O handle precisa ser
+      irmão porque desliza pra FORA ao recolher, e o `.q-drawer__content` é
+      `overflow: hidden`. Este nunca sai: fica encostado na borda interna
+      direita, então não há o que recortar.
+
+      E precisa ser dentro: como irmão `position: fixed`, ele exigia um z-index
+      acima do drawer sobreposto (3000) — e aí passava por cima de QUALQUER
+      outro overlay de mesma camada. Na prática o <acai-ui-preferences>, que é
+      um QDrawer à direita também em 3000: abrir as preferências deixava dois
+      "X" empilhados na tela, o nosso por cima do painel. Morando dentro, ele
+      herda o contexto de empilhamento da própria gaveta e some junto quando
+      algo cobre o drawer, sem z-index nenhum.
+
+      Tocar no backdrop já fecha, mas isso é alvo invisível: quem navega por
+      teclado ou leitor de tela não tem como descobrir. Este é o controle
+      explícito e rotulado.
+
+      Não vale na folha: lá o fechar mora no cabeçalho, junto com a troca de
+      vista, e dois "fechar" na mesma tela seria ruído.
+      -->
+      <button
+        v-if="comportamento === 'mobile' && !ehFolhaMobile"
+        type="button"
+        class="acai-drawer-fechar"
+        :style="estiloFechar"
+        aria-label="Fechar menu"
+        @click="aberto = false"
+      >
+        <acai-ui-icon name="close" size="18px" decorative />
+      </button>
+
+      <!--
+        Topo — MONTADO UMA VEZ, nunca trocado.
+
+        A moldura roxa, esta faixa da marca, os botões e o rodapé são os mesmos
+        nas duas vistas. Desmontar e remontar qualquer um deles pra "trocar de
+        tela" produz o pisca que não deveria existir: o usuário vê a logo sumir
+        e voltar, sendo que ela nunca mudou.
+
+        Só o MIOLO troca (a `<transition>` mais abaixo).
+
+        Por isso o slot recebe `vista`: o que muda aqui dentro é decisão do
+        consumidor, não da lib. Na documentação, por exemplo, a logo fica parada
+        e só o texto ao lado dela vira "Preferências"; o campo de busca, que só
+        faz sentido sobre a lista, sai de cena. A lib não tem como fazer esse
+        recorte sozinha — logo, título e busca chegam juntos, num slot só.
+      -->
+      <div v-if="$slots.brand" class="drawer-brand">
+        <slot name="brand" :mini="miniAtivo" :vista="vista" />
+      </div>
+
+      <!-- Corpo — a ÚNICA parte que troca. `mode="out-in"`: o que sai termina
+           antes do que entra, senão os dois se sobrepõem durante a troca e a
+           altura salta. -->
+      <transition :name="nomeTransicao" mode="out-in">
+        <!-- Vista PREFERÊNCIAS: o mesmo painel de sempre, sem moldura própria. -->
+        <div
+          v-if="ehFolhaMobile && vista === 'preferencias'"
+          key="corpo-pref"
+          class="drawer-folha__painel"
+        >
+          <acai-ui-preferences embutido />
+        </div>
+
+        <q-scroll-area v-else key="corpo-menu" class="drawer-scroll">
+      <!-- MINI: trilho só de ícones. Lista própria (e não a de baixo escondida
+           por CSS) porque a estrutura é outra — sem expansões, sem badges de
+           filho, rótulo em tooltip. Esconder a árvore inteira por CSS deixaria
+           itens focáveis invisíveis, que é armadilha de acessibilidade. -->
+      <q-list v-if="miniAtivo" class="drawer-mini-list">
+        <q-item
+          v-for="no in itensVisiveis"
+          :key="chaveGrupo(no)"
+          :active="ehFolha(no) && ativo(no.name)"
+          active-class="item-ativo"
+          clickable
+          class="drawer-item drawer-mini-item"
+          :aria-label="rotuloDe(no)"
+          @click="aoClicarMini(no)"
+        >
+          <acai-ui-icon :name="iconeDe(no)" />
+          <acai-ui-tooltip position="right">{{ rotuloDe(no) }}</acai-ui-tooltip>
+        </q-item>
+      </q-list>
+
+      <q-list v-else>
+        <template v-for="group in itensVisiveis" :key="chaveGrupo(group)">
+          <q-expansion-item
+            v-if="ehGrupo(group)"
+            :header-class="[
+              'header-expansao',
+              temAtivo(group) ? 'expansion-ativo' : '',
+            ]"
+            expand-icon="chevron_right"
+            expand-icon-class="text-white"
+            :model-value="expansaoAberta[group.expansionName] ?? false"
+            @update:model-value="
+              (val: boolean) => (expansaoAberta[group.expansionName] = val)
+            "
+          >
+            <template #header>
+              <q-item-section class="content-header-itens">
+                <acai-ui-icon
+                  v-if="group.iconExpansion"
+                  :name="group.iconExpansion"
+                />
+                <span>{{ group.expansionName }}</span>
+              </q-item-section>
+            </template>
+
+            <template v-for="item in group.children" :key="chaveFilho(item)">
+              <q-expansion-item
+                v-if="ehGrupo(item)"
+                :label="item.expansionName"
+                :header-class="[
+                  'header-expansao',
+                  'content-sub-grupo',
+                  temAtivo(item) ? 'expansion-ativo' : '',
+                ]"
+                expand-icon="chevron_right"
+            expand-icon-class="text-white"
+                :model-value="expansaoAberta[item.expansionName] ?? false"
+                @update:model-value="
+                  (val: boolean) => (expansaoAberta[item.expansionName] = val)
+                "
+              >
+                <template v-for="sub in item.children" :key="chaveFilho(sub)">
+                  <q-item
+                    v-if="ehFolha(sub)"
+                    :active="ativo(sub.name)"
+                    active-class="item-ativo"
+                    clickable
+                    class="drawer-item content-item sub-grupo"
+                    @click="aoClicarItem(sub)"
+                  >
+                    <q-item-section>
+                      <q-item-label style="font-size: 0.875rem">{{
+                        sub.label
+                      }}</q-item-label>
+                      <q-item-label v-if="sub.caption" caption>{{
+                        sub.caption
+                      }}</q-item-label>
+                    </q-item-section>
+                    <q-item-section v-if="sub.badge !== undefined" side>
+                      <q-badge
+                        class="badge-lazy"
+                        :label="sub.badge"
+                        color="warning" text-color="dark"
+                        role="status"
+                        :aria-label="`${sub.badge} notificações em ${sub.label}`"
+                      />
+                    </q-item-section>
+                  </q-item>
+                </template>
+              </q-expansion-item>
+
+              <q-item
+                v-else-if="ehFolha(item)"
+                :active="ativo(item.name)"
+                active-class="item-ativo"
+                clickable
+                class="drawer-item content-item"
+                @click="aoClicarItem(item)"
+              >
+                <q-item-section>
+                  <q-item-label>{{ item.label }}</q-item-label>
+                  <q-item-label v-if="item.caption" caption>{{
+                    item.caption
+                  }}</q-item-label>
+                </q-item-section>
+                <q-item-section v-if="item.badge !== undefined" side>
+                  <q-badge
+                    class="badge-lazy"
+                    :label="item.badge"
+                    color="warning" text-color="dark"
+                    role="status"
+                    :aria-label="`${item.badge} notificações em ${item.label}`"
+                  />
+                </q-item-section>
+              </q-item>
+            </template>
+          </q-expansion-item>
+
+          <q-item
+            v-else-if="ehFolha(group)"
+            :active="ativo(group.name)"
+            active-class="item-ativo"
+            clickable
+            class="drawer-item"
+            @click="aoClicarItem(group)"
+          >
+            <q-item-section class="content-header-itens">
+              <acai-ui-icon v-if="group.icon" :name="group.icon" />
+              <span>{{ group.label }}</span>
+            </q-item-section>
+            <q-item-section v-if="group.badge !== undefined" side>
+              <q-badge
+                :label="group.badge"
+                color="warning" text-color="dark"
+                role="status"
+                :aria-label="`${group.badge} notificações em ${group.label}`"
+              />
+            </q-item-section>
+          </q-item>
+        </template>
+      </q-list>
+        </q-scroll-area>
+      </transition>
+
+      <!-- Rodapé — também MONTADO UMA VEZ, igual ao topo. Chegou a sair na vista
+           de preferências; era o mesmo pisca do topo, só que embaixo.
+           Sem versão e sem slot ele não renderiza: um `border-top` sozinho
+           desenharia uma linha solta no pé do drawer. -->
+      <div v-if="version || $slots.footer" class="footer">
+        <!-- Slot `footer` deixa o consumidor (ex: template do CLI) prover o
+             próprio rodapé. Recebe `mini` pra encolher o conteúdo no trilho —
+             72px não comportam o rodapé expandido. E `vista`, pela mesma razão
+             do `#brand`: quem decide o que muda aqui dentro é o consumidor. -->
+        <slot name="footer" :mini="miniAtivo" :vista="vista">
+          <div v-if="version" class="footer__versao">
+            <!-- No trilho sobra só o número: a assinatura não caberia em 72px, e
+                 o número sozinho já é o que se procura ao conferir versão. -->
+            <span v-if="!miniAtivo" class="footer__versao-rotulo">
+              &copy; {{ anoAtual }} Açaí UI
+            </span>
+            <span class="footer__versao-numero">v{{ version }}</span>
+          </div>
+        </slot>
+      </div>
+    </div>
+  </component>
+
+  <!--
+    Handle de recolher/expandir — IRMÃO do q-drawer, não filho.
+    O `.q-drawer__content` é `overflow: hidden`, então qualquer elemento dentro
+    dele seria cortado na borda (nem `position: fixed` escapa: o `aside` tem
+    `transform`, e transform cria bloco de contenção pra descendentes fixos).
+    Como irmão, ele desliza livremente pra fora do drawer ao recolher.
+    O `left` é interpolado por CSS transition; o `top` acompanha o topo real do
+    drawer (que muda se o app tiver header).
+  -->
+  <button
+    v-if="collapsible && comportamento === 'desktop' && aberto"
+    type="button"
+    class="acai-drawer-handle"
+    :class="{ 'acai-drawer-handle--solto': miniAtivo }"
+    :style="estiloHandle"
+    :aria-label="miniAtivo ? 'Expandir menu' : 'Recolher menu'"
+    :aria-expanded="miniAtivo ? 'false' : 'true'"
+    @click="miniAtivo = !miniAtivo"
+  >
+    <acai-ui-icon :name="miniAtivo ? 'arrow_forward' : 'arrow_back'" size="18px" decorative />
+    <acai-ui-tooltip position="right">
+      {{ miniAtivo ? 'Expandir menu' : 'Recolher menu' }}
+    </acai-ui-tooltip>
+  </button>
+
+</template>
+
+<script setup lang="ts">
+import {
+  computed,
+  nextTick,
+  onBeforeUnmount,
+  onMounted,
+  reactive,
+  ref,
+  useAttrs,
+  watch,
+} from 'vue'
+import { QDialog, QDrawer } from 'quasar'
+import { useTela } from '../../hooks/use-tela'
+import AcaiUiIcon from '../icon/acai-ui-icon.vue'
+import AcaiUiPreferences from '../preferences/acai-ui-preferences.vue'
+import AcaiUiTooltip from '../tooltip/acai-ui-tooltip.vue'
+import type { MaterialIconValues } from '../../constants/lista-icons'
+import type {
+  DrawerProps,
+  SidebarGroup,
+  SidebarLeaf,
+  SidebarRouteConfig,
+} from './acai-ui-drawer-interface'
+import { processarSidebar } from './drawer-sidebar-helper'
+
+// O componente tem DOIS nós raiz (drawer + handle). Sem isto o Vue avisa que
+// não sabe em qual deles aplicar os atributos herdados — repassamos ao drawer.
+defineOptions({ inheritAttrs: false })
+
+const attrs = useAttrs()
+
+const props = withDefaults(defineProps<DrawerProps>(), {
+  version: '',
+  activeKey: '',
+  width: 320,
+  // 1024 = `$bp-md` de scss/_breakpoints.scss. Ver o porquê da troca (era 1080)
+  // no JSDoc da prop, em acai-ui-drawer-interface.ts.
+  breakpoint: 1024,
+  // 600 = `$bp-sm` de scss/_breakpoints.scss, o mesmo ponto do mixin
+  // `ate-mobile` e da classe `lt-sm` do Quasar. Assim um `@media` do app e a
+  // folha do menu viram na MESMA largura.
+  sheetBreakpoint: 600,
+  preferences: true,
+  miniWidth: 72,
+  collapsible: false,
+})
+
+const emit = defineEmits<{
+  /** Disparado quando o usuário clica em um item-folha do drawer.
+   *  Itens com `href` são abertos em nova aba e NÃO disparam este evento. */
+  'item-click': [item: SidebarLeaf]
+}>()
+
+const aberto = defineModel<boolean>({ default: false })
+/**
+ * Trilho recolhido (`v-model:mini`). Não vale no mobile: lá o drawer é overlay
+ * sobre o conteúdo, e um trilho fixo de 72px comeria a tela.
+ */
+const mini = defineModel<boolean>('mini', { default: false })
+
+const { largura: larguraTela, medido, abaixoDe } = useTela()
+
+/**
+ * Desktop (trilho fixo que empurra o conteúdo) ou mobile (gaveta sobreposta com
+ * backdrop)?
+ *
+ * 🔴 Isto era um `ref('desktop')` que NUNCA recebia atribuição — em nenhum
+ * commit da história do arquivo. Como o valor ia direto pro `:behavior` do
+ * QDrawer, e o Quasar faz
+ *
+ *     behavior === 'mobile' || (behavior !== 'desktop' && totalWidth <= breakpoint)
+ *
+ * o `'desktop'` fixo curto-circuitava a comparação: o `:breakpoint` nunca era
+ * consultado, o drawer nunca virava overlay e num celular de 360px ele seguia
+ * como painel fixo de 320px empurrando o conteúdo — sobravam ~40px de página.
+ * Era a causa de "o layout quebra no celular" em todos os apps que consomem a
+ * lib, e nenhuma regra de CSS resolveria, porque o problema era o valor da prop.
+ *
+ * A decisão sai do `useTela` e não de `$q.screen` cru porque em SSR a largura é
+ * 0 até a hidratação terminar — ver o hook pro porquê e pro que se usa no lugar.
+ */
+const estreito = abaixoDe(() => props.breakpoint)
+
+const comportamento = computed<'desktop' | 'mobile'>(() =>
+  estreito.value ? 'mobile' : 'desktop',
+)
+
+/**
+ * Folha de tela cheia (sobe de baixo) em vez de gaveta lateral.
+ *
+ * Cuidado com o nome: `ehFolha` (sem o sufixo) é o type guard de item-folha da
+ * árvore do menu, coisa completamente diferente.
+ */
+const ehFolhaMobile = abaixoDe(() => props.sheetBreakpoint)
+
+/** Qual conteúdo a folha mostra. Só existe na folha. */
+const vista = ref<'menu' | 'preferencias'>('menu')
+
+/** Rótulo do atalho. Não é mais desenhado como título — o topo é fixo, e quem
+ *  escreve "Preferências" ali é o slot `#brand`. Aqui serve ao `aria-label`. */
+const tituloPreferencias = 'Preferências'
+
+/**
+ * Direção da animação de troca: entrando nas preferências o conteúdo AVANÇA
+ * (novo entra pela direita), voltando pro menu ele VOLTA (novo entra pela
+ * esquerda). Sem a direção, ir e voltar dariam a mesma animação e o gesto
+ * perderia a noção de "estou entrando" vs "estou saindo".
+ */
+const nomeTransicao = computed(() =>
+  vista.value === 'preferencias' ? 'acai-vista-avanca' : 'acai-vista-volta',
+)
+
+/**
+ * Ações da folha, alinhadas ao CENTRO da linha da marca — a mesma âncora medida
+ * que o handle e o botão de fechar usam. Ver `estiloFechar` pro porquê de medir
+ * (a altura dessa linha é conteúdo do consumidor) e por que isso não faz o
+ * botão saltar.
+ */
+const ALTURA_ACAO = 44
+
+const estiloAcoes = computed(() => ({
+  top: `${centroAncora.value - topoDrawer.value - ALTURA_ACAO / 2}px`,
+}))
+
+// Sair da folha (girar a tela, redimensionar) tem que voltar pro menu: a gaveta
+// lateral não tem cabeçalho pra trocar de vista, então o usuário ficaria preso
+// nas preferências sem botão de volta.
+watch(ehFolhaMobile, (folha) => {
+  if (!folha) vista.value = 'menu'
+})
+
+// Fechar e reabrir sempre começa no menu — é o que se espera de um botão de
+// menu. Sem isto, quem saísse com as preferências abertas reabriria nelas.
+watch(aberto, (estaAberto) => {
+  if (!estaAberto) vista.value = 'menu'
+})
+
+/**
+ * A moldura. Ver o comentário no topo do template pro porquê de trocar só ela.
+ *
+ * `maximized` + `slide-up`/`slide-down` é o jeito documentado do Quasar de
+ * fazer folha de tela cheia vinda de baixo. O QDialog ainda entrega Esc pra
+ * fechar, trava de foco e bloqueio de scroll do fundo — tudo que teríamos de
+ * refazer à mão num `<div fixed>`.
+ */
+const raiz = computed(() => (ehFolhaMobile.value ? QDialog : QDrawer))
+
+const atributosRaiz = computed<Record<string, unknown>>(() => {
+  const modelo = {
+    modelValue: aberto.value,
+    'onUpdate:modelValue': (v: boolean) => {
+      aberto.value = v
+    },
+  }
+
+  if (ehFolhaMobile.value) {
+    return {
+      ...modelo,
+      maximized: true,
+      transitionShow: 'slide-up',
+      transitionHide: 'slide-down',
+      class: 'acai-drawer-folha',
+    }
+  }
+
+  return {
+    ...modelo,
+    ...attrs,
+    showIfAbove: true,
+    bordered: true,
+    breakpoint: props.breakpoint,
+    width: larguraEfetiva.value,
+    mini: miniAtivo.value,
+    miniWidth: props.miniWidth,
+    behavior: comportamento.value,
+    overlay: comportamento.value === 'mobile',
+  }
+})
+
+const classesConteudo = computed(() => ({
+  'drawer-container--mini': miniAtivo.value,
+  'drawer-container--collapsible': props.collapsible,
+  'drawer-container--mobile': comportamento.value === 'mobile' && !ehFolhaMobile.value,
+  'drawer-container--folha': ehFolhaMobile.value,
+  // Sem o atalho de preferências sobra um botão só, e a quina reservada na
+  // marca encolhe junto.
+  'drawer-container--folha-uma-acao': ehFolhaMobile.value && !props.preferences,
+}))
+
+/**
+ * No desktop vale a `width` que o consumidor pediu, sem discussão.
+ *
+ * No celular ela vira um TETO: o default de 320px numa tela de 360px deixaria
+ * 40px de backdrop — faixa fina demais pra acertar com o polegar, e a gaveta
+ * aberta viraria uma armadilha (só o botão de menu fecharia). Reservando 56px
+ * sobra alvo de toque confortável pra fechar tocando fora. O piso de 240px
+ * impede que numa tela muito estreita a gaveta encolha até ficar ilegível —
+ * aí é melhor o backdrop encolher do que o menu.
+ *
+ * Sem medição (SSR até hidratar) não há de onde tirar o teto: `larguraTela` é 0
+ * e a conta daria o piso de 240px pra QUALQUER aparelho. Aí vale a `width`
+ * pedida, e o teto entra junto com a primeira medição.
+ */
+const larguraEfetiva = computed<number>(() =>
+  comportamento.value === 'mobile' && medido.value
+    ? Math.min(props.width, Math.max(larguraTela.value - 56, 240))
+    : props.width,
+)
+
+const miniAtivo = computed<boolean>({
+  get: () => mini.value && comportamento.value === 'desktop',
+  set: (v) => {
+    mini.value = v
+  },
+})
+
+
+const anoAtual = new Date().getFullYear()
+
+const ehGrupo = (n: SidebarRouteConfig): n is SidebarGroup => 'children' in n
+const ehFolha = (n: SidebarRouteConfig): n is SidebarLeaf => 'name' in n
+
+function temHref(
+  no: SidebarRouteConfig,
+): no is SidebarRouteConfig & { href: string } {
+  return (
+    'href' in no &&
+    typeof (no as { href?: unknown }).href === 'string' &&
+    (no as { href: string }).href.length > 0
+  )
+}
+
+const itensVisiveis = computed<SidebarRouteConfig[]>(() =>
+  processarSidebar(props.items),
+)
+
+/**
+ * Item está ativo? — comparado com a prop `activeKey` que o consumidor
+ * controla (geralmente `String(route.name)` no vue-router).
+ */
+const ativo = (nome?: string): boolean =>
+  typeof nome === 'string' && nome.length > 0 && nome === props.activeKey
+
+function temAtivo(no: SidebarRouteConfig): boolean {
+  if (temHref(no)) return false
+  if (ehFolha(no)) return ativo(no.name)
+  if (ehGrupo(no)) return no.children.some((child) => temAtivo(child))
+  return false
+}
+
+// Estado reativo das expansões
+const expansaoAberta = reactive<Record<string, boolean>>({})
+
+function abrirExpansoesDaRotaAtiva(): void {
+  for (const group of itensVisiveis.value) {
+    if (ehGrupo(group)) {
+      if (temAtivo(group)) {
+        expansaoAberta[group.expansionName] = true
+        for (const child of group.children) {
+          if (ehGrupo(child) && temAtivo(child)) {
+            expansaoAberta[child.expansionName] = true
+          }
+        }
+      }
+    }
+  }
+}
+
+// Abre expansões quando a rota ativa muda
+watch(
+  () => props.activeKey,
+  () => {
+    abrirExpansoesDaRotaAtiva()
+  },
+  { immediate: true },
+)
+
+// =============================================================
+// Handle de recolher/expandir
+// =============================================================
+
+const drawerRef = ref<{ $el?: unknown } | null>(null)
+
+/**
+ * A coluna de conteúdo (`.drawer-container`), que existe igual nas duas
+ * molduras. É a referência de medida — ver `medirAncora`.
+ */
+const conteudoRef = ref<HTMLElement | null>(null)
+
+/** Altura do handle — usada pra converter "centro desejado" em `top`. */
+const ALTURA_HANDLE = 32
+/** Metade do handle + respiro até a borda interna do drawer. */
+const RECUO_INTERNO = 46
+const FOLGA_EXTERNA = 10
+/** Fallback quando não há slot #brand: alinha com o primeiro item da lista. */
+const CENTRO_PADRAO = 35
+
+// O fechar usa EXATAMENTE a mesma geometria do handle (32px, mesmo recuo): os
+// dois nunca aparecem juntos e pousam na mesma âncora, então compartilhar a
+// medida é o que faz a troca parecer o mesmo botão mudando de função. O alvo de
+// toque de 44px vem de uma camada invisível no CSS, sem inchar o desenho.
+
+/**
+ * Centro vertical (na viewport) da linha em que o handle deve pousar.
+ * MEDIDO, não constante: o topo do drawer muda se o app tiver header, e a
+ * altura da marca depende inteiramente do que o consumidor põe no slot #brand.
+ */
+const centroAncora = ref(CENTRO_PADRAO)
+
+/**
+ * Topo do drawer na viewport. O handle é `position: fixed` e usa `centroAncora`
+ * cru; o botão de fechar é `absolute` DENTRO do drawer e precisa da mesma
+ * âncora convertida pra coordenada local — daí guardar o topo.
+ */
+const topoDrawer = ref(0)
+
+function medirAncora(): void {
+  // Mede a partir do CONTEÚDO, não da moldura.
+  //
+  // 🔴 Na folha a moldura é um QDialog, que teleporta o conteúdo pro body: o
+  // `$el` dele não contém `.drawer-brand`, então o `querySelector` abaixo dava
+  // vazio e a âncora caía no CENTRO_PADRAO. Isso passou despercebido porque no
+  // menu o padrão de 35px bate por coincidência com o centro da linha da logo;
+  // só ao trocar pro título "Preferências" (24px de altura, centro em 30) o
+  // erro apareceu — 5px de desvio, medidos no navegador.
+  //
+  // O `.drawer-container` preenche a moldura nos dois modos, então usar o topo
+  // dele em vez do topo do drawer não muda nada pro handle do desktop.
+  const el = conteudoRef.value
+  if (!(el instanceof HTMLElement)) return
+
+  const topo = el.getBoundingClientRect().top
+  topoDrawer.value = topo
+  const marca = el.querySelector('.drawer-brand')
+
+  if (!(marca instanceof HTMLElement)) {
+    centroAncora.value = topo + CENTRO_PADRAO
+    return
+  }
+
+  // Ancora na PRIMEIRA LINHA do slot #brand — a mesma que cede espaço à direita
+  // pro handle. Usar o centro do `.drawer-brand` inteiro só funciona enquanto o
+  // slot tem uma linha só: assim que o consumidor empilha algo embaixo (um campo
+  // de busca, por exemplo), o centro desce e o botão descola da logo.
+  const primeiraLinha = marca.firstElementChild
+  if (primeiraLinha instanceof HTMLElement) {
+    const r = primeiraLinha.getBoundingClientRect()
+    centroAncora.value = r.top + r.height / 2
+    return
+  }
+
+  // Slot vazio: cai no centro da caixa de conteúdo da marca (descontando o
+  // padding, que raramente é simétrico).
+  const r = marca.getBoundingClientRect()
+  const cs = getComputedStyle(marca)
+  const padTopo = Number.parseFloat(cs.paddingTop) || 0
+  const padBase = Number.parseFloat(cs.paddingBottom) || 0
+  centroAncora.value = r.top + padTopo + (r.height - padTopo - padBase) / 2
+}
+
+const estiloHandle = computed(() => ({
+  // `top` posiciona a BORDA, então desconta metade da altura pra o CENTRO do
+  // handle bater com o centro da marca.
+  top: `${centroAncora.value - ALTURA_HANDLE / 2}px`,
+  // Recolhido: para FORA do trilho. Expandido: encostado na borda interna, na
+  // mesma linha da marca (ao lado do que o consumidor puser no slot #brand).
+  left: miniAtivo.value
+    ? `${props.miniWidth + FOLGA_EXTERNA}px`
+    : `${props.width - RECUO_INTERNO}px`,
+}))
+
+/**
+ * `top` do botão de fechar, RELATIVO ao drawer (ele é filho absoluto de dentro).
+ *
+ * Por que medir, se ele mora dentro: a altura da primeira linha da marca é
+ * conteúdo do consumidor — logo + duas linhas de texto dão 42px aqui, mas outro
+ * app pode pôr só um ícone. Um `top` cravado no CSS acerta um caso e erra os
+ * outros; medido, o X sempre nasce no centro exato da linha da marca, alinhado
+ * com o que o consumidor puser ali ao lado.
+ *
+ * E medir aqui NÃO reintroduz o "teletransporte" que você viu: aquilo era
+ * consequência de ele ser irmão `position: fixed`, que aparecia pronto no
+ * destino enquanto a gaveta ainda estava deslizando. Agora ele é parte da
+ * gaveta — entra junto com ela — e qualquer ajuste de medida acontece com o
+ * drawer ainda fora da tela.
+ *
+ * `right` fica no CSS: 18px, o mesmo padding lateral da marca, pra a borda
+ * direita do botão bater com a do conteúdo (campo de busca, itens da lista).
+ */
+const estiloFechar = computed(() => ({
+  top: `${centroAncora.value - topoDrawer.value - ALTURA_HANDLE / 2}px`,
+}))
+
+onMounted(() => {
+  medirAncora()
+  window.addEventListener('resize', medirAncora)
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', medirAncora)
+})
+
+// `vista` volta pra cá: o topo não é mais trocado por uma `<transition>`, mas o
+// CONTEÚDO dele pode mudar de altura (na docs, duas linhas de marca viram uma de
+// "Preferências"). Sem remedir, as ações ficariam ancoradas na altura anterior.
+// Um tick basta agora — sem `mode="out-in"` no caminho, o DOM já está no lugar.
+watch([miniAtivo, aberto, vista], () => {
+  void nextTick(medirAncora)
+})
+
+// =============================================================
+// Trilho mini
+// =============================================================
+
+/** Ícone do nó no trilho. Folha usa `icon`; grupo usa `iconExpansion`. */
+function iconeDe(no: SidebarRouteConfig): MaterialIconValues {
+  const icone = ehGrupo(no) ? no.iconExpansion : no.icon
+  // Sem ícone o item viraria um quadrado vazio e não-clicável aos olhos —
+  // melhor um marcador genérico do que um buraco no trilho.
+  return icone ?? 'label'
+}
+
+function rotuloDe(no: SidebarRouteConfig): string {
+  return ehGrupo(no) ? (no.label ?? no.expansionName) : no.label
+}
+
+/**
+ * Clique no trilho: folha navega direto; grupo não tem como abrir dentro de
+ * 72px, então reexpande o drawer já com aquele grupo aberto.
+ */
+function aoClicarMini(no: SidebarRouteConfig): void {
+  if (ehGrupo(no)) {
+    expansaoAberta[no.expansionName] = true
+    miniAtivo.value = false
+    return
+  }
+  aoClicarItem(no)
+}
+
+function ehUrlAbsoluta(url: string): boolean {
+  return /^https?:\/\//i.test(url)
+}
+
+function construirUrl(no: { href: string }): string {
+  return ehUrlAbsoluta(no.href)
+    ? no.href
+    : no.href.startsWith('/')
+      ? no.href
+      : `/${no.href}`
+}
+
+function aoClicarItem(no: SidebarRouteConfig): void {
+  // href tem precedência: lib lida sozinha (abre em nova aba)
+  if (temHref(no)) {
+    const url = construirUrl(no)
+    window.open(url, '_blank', 'noopener')
+    return
+  }
+  // folha sem href: delega a navegação pro consumidor
+  if (ehFolha(no)) {
+    emit('item-click', no)
+  }
+}
+
+function chaveGrupo(n: SidebarRouteConfig): string {
+  return ehGrupo(n)
+    ? `g:${n.expansionName}`
+    : `f:${(n as SidebarLeaf).name ?? n.label}`
+}
+
+function chaveFilho(n: SidebarRouteConfig): string {
+  return ehGrupo(n)
+    ? `g:${n.expansionName}`
+    : `f:${(n as SidebarLeaf).name ?? n.label}`
+}
+</script>
+
+<style lang="scss" src="./acai-ui-drawer-styles.scss" />