acai-ui 1.65.5

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

@@ -0,0 +1,56 @@
+/**
+ * Guarda do salto entre etapas.
+ *
+ * Recebe de onde a navegação sai e para onde vai; retornar `false` (ou uma
+ * Promise que resolve `false`) CANCELA a navegação — o stepper não troca de
+ * etapa e emite `salto-bloqueado`.
+ *
+ * Vale nas DUAS direções. Se a tela quiser liberar a volta, ela tem os dois
+ * nomes em mãos:
+ *
+ * ```ts
+ * const guarda = (de, para) => (Number(para) > Number(de) ? etapaValida() : true)
+ * ```
+ */
+export type AntesDeSair = (
+  de: string | number | undefined,
+  para: string | number,
+) => boolean | Promise<boolean>
+
+export interface StepperProps {
+  vertical?: boolean
+  animated?: boolean
+  headerNav?: boolean
+  contracted?: boolean
+  keepAlive?: boolean
+  /** Label do botão voltar (default: 'Voltar') */
+  backLabel?: string
+  /** Label do botão avançar (default: 'Avançar') */
+  nextLabel?: string
+  /** Label do botão no último step (default: 'Finalizar') */
+  finishLabel?: string
+  /** Cor do botão finalizar (default: 'positive') */
+  finishColor?: string
+  /** Total de steps — necessário para navegação automática saber o último step */
+  totalSteps?: number
+  /**
+   * Guarda a saída da etapa atual. Só faz sentido junto com `header-nav`, que é
+   * o que torna o cabeçalho clicável e permite pular etapas (1 → 3 direto).
+   *
+   * A guarda pega o que o STEPPER dispara: o clique no cabeçalho e o "Avançar"
+   * da navegação automática. NÃO pega `next()`, `previous()`, `goTo()` nem
+   * escrita direta no `v-model` — esses são disparados pela tela, que já decidiu
+   * navegar (guardar de novo revalidaria e abriria o modal de erro em duplicata).
+   */
+  antesDeSair?: AntesDeSair
+  /**
+   * Marca a etapa como concluída ao SAIR dela com a guarda aprovando.
+   *
+   * Existe porque o padrão `:done="step > 1"` passa a MENTIR quando há salto:
+   * pular de 1 para 5 pintaria 2, 3 e 4 de verde sem ninguém ter passado por
+   * elas. Com `auto-done`, verde quer dizer "conferida", não "ficou para trás".
+   *
+   * Um `done` explícito no `<acai-ui-step>` continua tendo precedência.
+   */
+  autoDone?: boolean
+}

package/src/components/stepper/acai-ui-stepper-styles.scss

@@ -0,0 +1,222 @@
+// Import explícito (CLAUDE.md §6): consumidores via condition `vue` compilam
+// este source sem o `additionalData` do vite.config da lib.
+@import '../../scss/breakpoints';
+
+.ds-stepper {
+  // Sem borda/fundo/radius próprios: o stepper SEMPRE é usado dentro de
+  // <acai-ui-container> > <acai-ui-card>, que já entrega o visual de card.
+  border: none;
+  background: transparent;
+  box-shadow: none;
+
+  // ============================
+  // DOT — tamanho e shape
+  // ============================
+  .q-stepper__dot {
+    width: 28px;
+    min-width: 28px;
+    height: 28px;
+    border-radius: $radius-full;
+    font-size: 0.8125rem;
+    font-weight: 600;
+    margin-right: 12px;
+  }
+
+  // ============================
+  // ESTADOS — cor via currentColor
+  // ============================
+
+  .q-stepper__tab {
+    color: $color-gray-200;
+  }
+
+  .q-stepper__tab--active {
+    // Navy ($primary) some sobre o card escuro. control-on = navy no claro
+    // (idêntico) e azul legível (#3a80d0) no escuro.
+    color: var(--acai-control-on, #{$primary});
+  }
+
+  // A bolinha (dot) ativa: o Quasar pinta via `background: currentColor` HERDADO
+  // do tab. Mas o dot ativo carrega ícone + `text-shadow: 0 0 0 currentColor`, e o
+  // currentColor herdado nem sempre reflete o control-on → o dot não recoloria no
+  // daltônico. Seta o background EXPLÍCITO com control-on (navy claro / azul dark /
+  // cor CVD no daltônico). done/error já usam --q-positive/--q-negative (recoloram).
+  .q-stepper__tab--active .q-stepper__dot {
+    background: var(--acai-control-on, #{$primary});
+  }
+
+  // Tinta sobre a superfície (não fundo sólido) → `--acai-positive`, que clareia
+  // no escuro. Com `--q-positive` o passo concluído ficava em 4,35:1.
+  .q-stepper__tab--done {
+    color: var(--acai-positive, #{$positive});
+  }
+
+  .q-stepper__tab--error {
+    color: var(--acai-negative, #{$negative});
+  }
+
+  // ============================
+  // TÍTULO
+  // ============================
+  .q-stepper__title {
+    font-size: 0.875rem;
+    font-weight: 500;
+    color: var(--acai-text, #{$color-gray-700});
+    letter-spacing: 0;
+  }
+
+  .q-stepper__tab--active .q-stepper__title {
+    font-weight: 600;
+    color: var(--acai-control-on, #{$primary});
+  }
+
+  .q-stepper__tab--done .q-stepper__title {
+    color: var(--acai-positive, #{$positive});
+    font-weight: 500;
+  }
+
+  .q-stepper__tab--error .q-stepper__title {
+    color: var(--acai-negative, #{$negative});
+  }
+
+  // ============================
+  // CAPTION
+  // ============================
+  .q-stepper__caption {
+    font-size: 0.75rem;
+    color: var(--acai-text-muted, #{$color-gray-600});
+    font-weight: 400;
+  }
+
+  // ============================
+  // LINHA conectora (horizontal)
+  // ============================
+  .q-stepper__line::before,
+  .q-stepper__line::after {
+    background: var(--acai-border, #{$color-gray-300});
+  }
+
+  // ============================
+  // LINHA conectora (vertical — pseudo-elements no dot)
+  // ============================
+  .q-stepper__dot::before,
+  .q-stepper__dot::after {
+    background: var(--acai-border, #{$color-gray-300});
+  }
+
+  // ============================
+  // HEADER — borda inferior (horizontal)
+  // ============================
+  .q-stepper__header--border {
+    border-bottom-color: var(--acai-border, #{$color-gray-300});
+  }
+
+  // ============================
+  // NAV automático — botão de avançar/finalizar ancorado à direita.
+  // O "Voltar" some no passo 1 (v-if no template); sem esta âncora, o "Avançar"
+  // pularia pra esquerda no `justify-content: space-between`. Vale horizontal e
+  // vertical. Consumidores que passam step por NOME (string) mantêm o "Voltar"
+  // sempre visível (ehPrimeiro só é true em step numérico) — nada muda pra eles.
+  // ============================
+  .ds-stepper__nav-next {
+    margin-left: auto;
+  }
+
+  // ============================
+  // HORIZONTAL
+  // ============================
+  &.q-stepper--horizontal {
+    .q-stepper__step-inner {
+      padding: $spacing-lg $spacing-xl;
+    }
+
+    .q-stepper__nav {
+      padding: 0 $spacing-xl $spacing-lg;
+      display: flex;
+      // "Voltar" e "Continuar/Finalizar" nas pontas. Rótulos customizados num
+      // celular não cabem lado a lado, e sem wrap o da direita vaza.
+      flex-wrap: wrap;
+      gap: $spacing-sm;
+      justify-content: space-between;
+    }
+  }
+
+  // ============================
+  // VERTICAL
+  // ============================
+  &.q-stepper--vertical {
+    padding: 0;
+
+    .q-stepper__tab {
+      padding: $spacing-sm $spacing-md;
+    }
+
+    .q-stepper__step-inner {
+      padding: 0 $spacing-md $spacing-lg calc(28px + 12px + $spacing-md);
+    }
+
+    .q-stepper__step:last-child .q-stepper__step-inner {
+      padding-bottom: $spacing-md;
+    }
+
+    // ----------------------------------------------------------------
+    // CELULAR — sem a linha conectora e sem a coluna vazia à esquerda.
+    //
+    // No vertical o conteúdo é indentado em `28px (dot) + 12px + 16px` = 56px
+    // só pra abrir espaço à esquerda da linha que liga um passo ao outro. Em
+    // 360px isso é ~16% da largura gasta em decoração, e o conteúdo — que é o
+    // que a pessoa veio ler — fica espremido num corredor.
+    //
+    // A linha some junto porque sem a indentação ela não liga mais nada: ficaria
+    // um traço vertical cortando o texto.
+    //
+    // 🔒 Por que é seguro remover: as duas linhas são `::before`/`::after` do
+    // dot, e o Quasar as declara `position: absolute` (`height: 99999px`,
+    // recortada pelo passo). Elemento absoluto não ocupa espaço no fluxo, então
+    // escondê-lo NÃO desloca, encolhe nem reposiciona nada — só apaga o traço.
+    // Não há semântica junto: é pseudo-elemento, sem texto, sem ARIA, invisível
+    // pro leitor de tela nos dois casos. O dot e o título do passo continuam,
+    // que é o que informa em que etapa a pessoa está.
+    // ----------------------------------------------------------------
+    @include ate-mobile {
+      .q-stepper__dot::before,
+      .q-stepper__dot::after {
+        display: none;
+      }
+
+      // Conteúdo alinhado com o título do passo (o tab usa o mesmo $spacing-md),
+      // em vez de recuado atrás da linha que não existe mais.
+      .q-stepper__step-inner {
+        padding-left: $spacing-md;
+      }
+    }
+
+    .q-stepper__nav {
+      padding: $spacing-sm $spacing-md $spacing-md;
+      display: flex;
+      flex-wrap: wrap;
+      justify-content: space-between;
+      gap: $spacing-sm;
+    }
+  }
+}
+
+// ============================
+// TEMA ESCURO — passo PENDENTE
+// ============================
+// A cor fixa $color-gray-200 (#c7c7c7) do dot inativo fica muito clara/brilhante
+// sobre o card escuro (~10:1). Sobre um tom mutado (text-muted) só no escuro —
+// o :not() preserva active/done/error (que têm regras menos específicas). O tema
+// CLARO fica intacto (a regra base continua valendo).
+.body--dark
+  .ds-stepper
+  .q-stepper__tab:not(.q-stepper__tab--active):not(.q-stepper__tab--done):not(.q-stepper__tab--error) {
+  color: var(--acai-text-muted, #{$color-gray-200});
+}
+
+// O Quasar força o número do dot pra #000 no dark (`.q-stepper--dark .q-stepper__dot
+// span`, assumindo dot claro). Nossos dots são COLORIDOS (control-on azul / positive
+// verde) — número branco lê melhor. O dot ATIVO já usa currentColor = --acai-control-on.
+.body--dark .ds-stepper .q-stepper__dot span {
+  color: #fff;
+}

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

@@ -0,0 +1,231 @@
+<template>
+  <q-stepper
+    ref="stepperRef"
+    class="ds-stepper"
+    flat
+    v-bind="$attrs"
+    :vertical="vertical"
+    :animated="animated"
+    :header-nav="headerNav"
+    :contracted="contracted"
+    :keep-alive="keepAlive"
+    :model-value="modelValue"
+    @update:model-value="onNavegar"
+  >
+    <!-- As etapas NÃO passam por `<slot />` cru: quando `auto-done` está ligado
+         elas são reemitidas com `done` marcado. O motivo está em `etapas` abaixo.
+         `<component :is="vnode">` devolve um clone do MESMO vnode, sem inserir
+         componente nenhum no meio — se inserisse, o q-stepper deixaria de
+         reconhecer as etapas (ele varre os filhos diretos do slot). -->
+    <component :is="vn" v-for="(vn, i) in etapas" :key="chaveEtapa(vn, i)" />
+
+    <template #navigation>
+      <slot v-if="$slots.navigation" name="navigation" />
+
+      <q-stepper-navigation v-else class="ds-stepper__nav-auto">
+        <!-- "Voltar" só a partir do passo 2 — no passo 1 não há pra onde voltar.
+             Some (v-if) em vez de ficar desabilitado. O botão de avançar/finalizar
+             é ancorado à direita via CSS (margin-left:auto), então não pula quando
+             o "Voltar" não está presente. -->
+        <acai-ui-button
+          v-if="!ehPrimeiro"
+          outline
+          :label="backLabel ?? 'Voltar'"
+          @click="voltarPelaNav()"
+        />
+        <acai-ui-button
+          v-if="!ehUltimo"
+          class="ds-stepper__nav-next"
+          :label="nextLabel ?? 'Avançar'"
+          @click="avancarPelaNav()"
+        />
+        <acai-ui-button
+          v-else
+          class="ds-stepper__nav-next"
+          :label="finishLabel ?? 'Finalizar'"
+          :color="finishColor ?? 'positive'"
+          @click="emit('finalizar')"
+        />
+      </q-stepper-navigation>
+    </template>
+  </q-stepper>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, cloneVNode, useSlots, type VNode } from 'vue'
+import type { QStepper } from 'quasar'
+import type { StepperProps } from './acai-ui-stepper-interface'
+import { achatarSlot, normalizarProps } from '../../utils/vnode-slot'
+import AcaiUiButton from '../button/acai-ui-button.vue'
+
+defineOptions({ inheritAttrs: false })
+
+const modelValue = defineModel<string | number>()
+
+const props = withDefaults(defineProps<StepperProps>(), {
+  animated: true,
+  vertical: false,
+  headerNav: false,
+  contracted: false,
+  keepAlive: false,
+  autoDone: false,
+})
+
+const emit = defineEmits<{
+  finalizar: []
+  'salto-bloqueado': [salto: { de: string | number | undefined; para: string | number }]
+}>()
+
+const stepperRef = ref<InstanceType<typeof QStepper> | null>(null)
+
+const ehPrimeiro = computed(() => {
+  if (typeof modelValue.value === 'number') return modelValue.value <= 1
+  return false
+})
+
+const ehUltimo = computed(() => {
+  if (props.totalSteps && typeof modelValue.value === 'number') {
+    return modelValue.value >= props.totalSteps
+  }
+  return false
+})
+
+// Anotação explícita, não estilo: o template usa `etapas`, `etapas` lê `slots` e
+// `useSlots()` se infere a partir do próprio componente — circularidade que o
+// vue-tsc do build de .d.ts rejeita com TS7022 (o `typecheck` não pega, é outra
+// config). Fixar o tipo aqui corta o ciclo.
+const slots = useSlots() as { default?: () => VNode[] }
+
+// Etapas já concluídas. Set dentro de ref é reativo no Vue 3 (add/has são
+// rastreados), então marcar uma etapa reprocessa `etapas` sozinho.
+const concluidos = ref<Set<string | number>>(new Set())
+
+/**
+ * As etapas do slot, com o que o cabeçalho precisa ler acrescentado no VNODE.
+ *
+ * 🔴 Existe porque quem desenha o cabeçalho MUDA com a orientação. No
+ * **vertical** é o `QStep`, que lê as próprias props — ali o `<acai-ui-step>` é
+ * transparente e tudo funciona. No **horizontal** é o `QStepper`, e ele lê
+ * `panel.props`: o vnode CRU escrito no template (`camelizeProps(panel.props)`
+ * no QStepper.js). Ou seja, o que o `<acai-ui-step>` calcula ou renomeia por
+ * dentro chega ao PAINEL e nunca chega ao CABEÇALHO — some sem erro nenhum, só
+ * no horizontal. Escrevendo no vnode, os dois modos leem a mesma coisa.
+ *
+ * Só clona quando há o que acrescentar: vnode intocado é vnode que o Vue
+ * reconcilia sem trabalho extra.
+ */
+const etapas = computed<VNode[]>(() =>
+  achatarSlot(slots.default?.()).map((vn) => {
+    const p = normalizarProps(vn.props)
+    const acrescimo: Record<string, unknown> = {}
+
+    // Os renomes da lib. `subtitle` e `prefixo` são o vocabulário do
+    // <acai-ui-step>; o cabeçalho do Quasar procura `caption` e `prefix` e não
+    // faz ideia dos nossos nomes. No vertical o wrapper já traduz na hora de
+    // montar o <q-step> — no horizontal ninguém traduzia, e as duas props
+    // simplesmente não apareciam.
+    if (p.subtitle !== undefined && p.caption === undefined) acrescimo.caption = p.subtitle
+    if (p.prefixo !== undefined && p.prefix === undefined) acrescimo.prefix = p.prefixo
+
+    // `done` explícito no template vence: quem passou a prop decidiu o que a
+    // etapa é, e a lib não sobrescreve escolha do consumidor.
+    if (props.autoDone && p.done === undefined) {
+      const nome = p.name as string | number | undefined
+      if (nome !== undefined && concluidos.value.has(nome)) acrescimo.done = true
+    }
+
+    return Object.keys(acrescimo).length > 0 ? cloneVNode(vn, acrescimo) : vn
+  }),
+)
+
+/**
+ * Preserva a key do consumidor, caindo no nome da etapa e depois no índice (a
+ * ordem das etapas é estável). `vn.key` é `PropertyKey` e pode ser symbol, que
+ * não serve de key de template — daí o filtro por tipo.
+ */
+function chaveEtapa(vn: VNode, indice: number): string | number {
+  if (typeof vn.key === 'string' || typeof vn.key === 'number') return vn.key
+
+  const nome = normalizarProps(vn.props).name
+  if (typeof nome === 'string' || typeof nome === 'number') return nome
+
+  return indice
+}
+
+/**
+ * Quando ligada, a próxima navegação NÃO passa pela guarda.
+ *
+ * É o que separa o que a LIB dispara (clique no cabeçalho, "Avançar" automático
+ * — guardados) do que a TELA dispara (`next`/`previous`/`goTo` — livres). Sem
+ * isso, uma tela que já valida antes de chamar `next()` validaria de novo aqui e
+ * abriria o modal de erro duas vezes.
+ */
+let ignorarGuarda = false
+
+function semGuarda(navegar: () => void): void {
+  ignorarGuarda = true
+  try {
+    navegar()
+  } finally {
+    ignorarGuarda = false
+  }
+}
+
+/**
+ * Intercepta a troca de etapa pedida pelo q-stepper.
+ *
+ * O q-stepper é totalmente controlado por `:model-value`, então basta NÃO
+ * escrever no model para o salto ficar cancelado — não há estado interno dele
+ * para desfazer.
+ */
+async function onNavegar(para: string | number): Promise<void> {
+  const de = modelValue.value
+  if (para === de) return
+
+  if (ignorarGuarda || !props.antesDeSair) {
+    aplicarNavegacao(de, para)
+    return
+  }
+
+  const liberado = await props.antesDeSair(de, para)
+  if (!liberado) {
+    emit('salto-bloqueado', { de, para })
+    return
+  }
+
+  aplicarNavegacao(de, para)
+}
+
+function aplicarNavegacao(de: string | number | undefined, para: string | number): void {
+  if (props.autoDone && de !== undefined) concluidos.value.add(de)
+  modelValue.value = para
+}
+
+/** Botão "Avançar" da navegação automática — passa pela guarda. */
+function avancarPelaNav(): void {
+  stepperRef.value?.next()
+}
+
+/** Botão "Voltar" da navegação automática — passa pela guarda. */
+function voltarPelaNav(): void {
+  stepperRef.value?.previous()
+}
+
+function next() {
+  semGuarda(() => stepperRef.value?.next())
+}
+
+function previous() {
+  semGuarda(() => stepperRef.value?.previous())
+}
+
+function goTo(name: string | number) {
+  semGuarda(() => stepperRef.value?.goTo(name))
+}
+
+defineExpose({ next, previous, goTo })
+</script>
+
+<style lang="scss">
+@import './acai-ui-stepper-styles.scss';
+</style>

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

@@ -0,0 +1,54 @@
+import type { DocumentoOpenApi, OperacaoNormalizada } from './openapi-tipos'
+
+/**
+ * O `| undefined` explícito em cada opcional é por causa do
+ * `exactOptionalPropertyTypes`: sem ele, o consumidor não consegue escrever
+ * `:url="algumaCoisa || undefined"` — padrão comum quando a URL vem de estado.
+ */
+export interface SwaggerProps {
+  /**
+   * URL do documento OpenAPI. Em Spring Boot é `${BASE_URL}/v3/api-docs`.
+   * Ignorada quando `spec` é passada.
+   */
+  url?: string | undefined
+  /**
+   * Documento já em memória. Ganha da `url` — é a saída para quem precisa
+   * buscar a spec por um caminho próprio (proxy do dev server, endpoint
+   * autenticado, arquivo importado).
+   */
+  spec?: DocumentoOpenApi | null | undefined
+  /**
+   * Base das requisições do "Executar". Default: primeiro `servers[]` da spec
+   * e, se a spec não declarar nenhum (Spring Boot costuma declarar `/`), a
+   * origem da própria `url`.
+   */
+  baseUrl?: string | undefined
+  /**
+   * Cabeçalhos enviados em toda requisição do "Executar" — é por aqui que o
+   * app injeta o token da sessão. A lib não conhece store nem interceptor.
+   */
+  headers?: Record<string, string> | undefined
+  /** Manda cookie/credencial junto (`fetch` com `credentials: 'include'`). */
+  withCredentials?: boolean | undefined
+  /** Esconde o "Executar": a tela vira explorador só-leitura. */
+  hideExecute?: boolean | undefined
+  /** Título do cabeçalho. Default: `info.title` da spec. */
+  title?: string | undefined
+}
+
+/**
+ * Props internas do detalhe de uma operação.
+ *
+ * O `| undefined` explícito é exigência do `exactOptionalPropertyTypes`: a casca
+ * repassa `:headers="headers"` e, sem ele, "prop ausente" e "prop com undefined"
+ * deixam de ser a mesma coisa e o template não compila.
+ */
+export interface SwaggerOperacaoProps {
+  operacao: OperacaoNormalizada
+  /** Documento cru — o detalhe resolve `$ref` de schema por conta própria. */
+  doc: DocumentoOpenApi
+  baseUrl: string
+  headers?: Record<string, string> | undefined
+  withCredentials?: boolean | undefined
+  hideExecute?: boolean | undefined
+}