# Documentação EliVue

**EliVue** é uma biblioteca de componentes Vue 3 construída sobre o **Vuetify 3**, projetada para padronizar padrões de UI como tabelas de dados (`EliTabela`) e campos de entrada (`EliEntrada*`). Ela segue a filosofia de "configuração sobre boilerplate", onde os componentes são guiados por objetos de configuração tipados em vez de propriedades de template extensas.

---

## 🤖 Diretrizes para Agentes de IA (Antigravity)

**Ao gerar código usando EliVue, siga estas regras estritas:**

1.  **Importações**: Sempre desestructure as importações do pacote raiz.
    ```typescript
    import { EliTabela, EliEntradaTexto, EliBotao, celulaTabela } from "eli-vue";
    ```
2.  **Objetos de Configuração**: Os componentes `EliTabela` e `EliEntrada` dependem fortemente de objetos de configuração (prop `tabela` para tabelas, prop `opcoes` para entradas). **Não tente** passar props individuais (como `headers` ou `items`) para o `EliTabela`.
3.  **Segurança de Tipos**: Sempre defina objetos de configuração usando os tipos TypeScript exportados (ex: `tipoEliTabelaConsulta`, `parametrosConsulta`).
4.  **Dados Assíncronos**: O `EliTabela` gerencia sua própria busca de dados via callback `consulta`. Não busque dados manualmente para passar para a tabela. Forneça a função `consulta` no lugar.
5.  **Ícones**: Use ícones do pacote `lucide-vue-next`.
6.  **Inicialização**: Prefira usar o plugin global `app.use(EliVue)` ao configurar um novo projeto, em vez de importações individuais.
7.  **Estilos**: O CSS é injetado automaticamente. Não tente importar arquivos CSS manualmente.
8.  **Idioma**: Mantenha a documentação e comentários explicativos em **Português do Brasil (pt-BR)**.

---

## Instalação

```bash
pnpm add eli-vue
# Dependências (Peer Dependencies)
pnpm add vue vuetify lucide-vue-next
```

Certifique-se de que seu projeto esteja configurado com Vuetify 3.

---

## 📦 Referência de Componentes

### 1. EliTabela (Tabela de Dados)

O componente `EliTabela` é uma tabela poderosa com paginação no servidor (server-side), busca integrada, ordenação e menus de ação.

#### API
- **Prop**: `tabela` (Obrigatório)
- **Tipo**: `tipoEliTabelaConsulta<T>`

#### Interface de Configuração (`tipoEliTabelaConsulta`)

```typescript
// De: eli-vue/src/componentes/EliTabela/types-eli-tabela.ts

export type tipoEliTabelaConsulta<T> = {
  // Identificador único para a tabela (usado para persistência local de visibilidade das colunas)
  nome: string;

  // Função para buscar dados. DEVE retornar um objeto de resposta padrão.
  consulta: (params: parametrosConsulta<T>) => Promise<tipoResposta<tipoEliConsultaPaginada<T>>>;

  // Definições das colunas
  colunas: tipoEliColuna<T>[];

  // Opções de UI
  mostrarCaixaDeBusca?: boolean;
  registros_por_consulta?: number;      // padrão: 10
  maximo_botoes_paginacao?: number;     // padrão: 7
  mensagemVazio?: string;

  // Ações
  acoesLinha?: tipoEliTabelaAcao<T>[]; // Ações para cada linha (menu de contexto)
  acoesTabela?: Array<{                 // Ações globais (superior/inferior)
  // Ações da Tabela (Botões Globais)
  acoesTabela?: Array<{
    /** 
     * Posição do botão:
     * - "superior": Ao lado da caixa de busca (canto superior direito).
     * - "inferior": No rodapé, alinhado à esquerda (canto inferior esquerdo).
     */
    posicao: "superior" | "inferior";
    
    /** Rótulo do botão */
    rotulo: string;
    
    /** Ícone (Lucide) */
    icone?: LucideIcon;
    
    /** Cor do botão (ex: "primary", "success", "error") */
    cor?: string;
    
    /** 
     * Função executada ao clicar.
     * Recebe um objeto contendo:
     * - Parâmetros atuais da consulta (offSet, limit, filtros, etc.)
     * - Helper `atualizarConsulta()`: Promise<void> para recarregar a tabela.
     */
    acao: (params: parametrosConsulta<T> & { atualizarConsulta: () => Promise<void> }) => void;
  }>;
  
  // Definição de Filtro Avançado
  filtroAvancado?: Array<{
    chave: string;
    rotulo: string;
    /** Função que gera o filtro com base no valor recebido do input */
    filtro: (valor: unknown) => tipoFiltro<T>;
    /** Definição do componente de entrada, ex: ["texto", { ... }] */
    entrada: any;
  }>;
};
```

#### Definindo Colunas (helper `celulaTabela`)

Use o helper `celulaTabela` para criar definições de células com segurança de tipo.

```typescript
// Tipos de células disponíveis e seus dados:
// "textoSimples": { texto: string; acao?: () => void }
// "textoTruncado": { texto: string; acao?: () => void }
// "numero": { numero: number; prefixo?: string; sufixo?: string; acao?: () => void }
// "tags": { opcoes: Array<{ rotulo: string; cor?: string; icone?: LucideIcon; acao?: () => void }> }
// "data": { valor: string; formato: "data" | "data_hora" | "relativo"; acao?: () => void }
// "badge": { texto: string; cor: string }

{
  rotulo: "Nome",
  celula: (row) => celulaTabela("textoSimples", { texto: row.nome }),
  visivel: true
}
```

#### Exemplo de Uso com Filtros Avançados

```vue
<script setup lang="ts">
import { EliTabela, celulaTabela, criarFiltro26 } from "eli-vue";
import type { tipoEliTabelaConsulta } from "eli-vue"; 
import { UsuarioService } from "@/services/UsuarioService"; 
import { BadgeCheck, Pencil, Plus } from "lucide-vue-next";

type Usuario = { id: number; nome: string; email: string; ativo: boolean; created_at: string };

const tabelaConfig: tipoEliTabelaConsulta<Usuario> = {
  nome: "tabela-usuarios",
  mostrarCaixaDeBusca: true,
  registros_por_consulta: 10,
  
  colunas: [
    { 
      rotulo: "Nome", 
      celula: (usuario) => celulaTabela("textoSimples", { texto: usuario.nome }), 
      visivel: true, 
      coluna_ordem: "nome" 
    },
    {
      rotulo: "Status",
      visivel: true,
      celula: (usuario) => celulaTabela("tags", {
        opcoes: [
          usuario.ativo 
            ? { rotulo: "Ativo", cor: "success", icone: BadgeCheck }
            : { rotulo: "Inativo", cor: "error" }
        ]
      })
    },
    { 
      rotulo: "Criado em", 
      celula: (usuario) => celulaTabela("data", { valor: usuario.created_at, formato: "data_hora" }), 
      visivel: true 
    }
  ],
  
  // Configuração de filtros avançados
  filtroAvancado: [
    {
      rotulo: "Nome",
      chave: "nome",
      // Função que retorna o objeto de filtro estruturado
      filtro: (valor: unknown) => criarFiltro26({ nome: { like: valor as string } }),
      // Definição do input: ["tipo", opcoes]
      entrada: ["texto", { rotulo: "Nome do usuário" }] as any
    },
    {
      rotulo: "Ativo?",
      chave: "ativo",
      filtro: (valor: unknown) => criarFiltro26({ ativo: { "=": valor } }),
      entrada: ["selecao", { 
        rotulo: "Status",
        itens: () => [
          { chave: "true", rotulo: "Ativo" },
          { chave: "false", rotulo: "Inativo" } 
        ]
      }] as any
    }
  ],
  
  acoesTabela: [
    {
      rotulo: "Novo Usuário",
      icone: Plus,
      posicao: "superior",
      cor: "primary",
      // O callback recebe: offSet, limit, filtros, e o helper 'atualizarConsulta'
      acao: async ({ atualizarConsulta }) => {
        // Exemplo: Abrir modal de criação e depois atualizar a tabela
        await openCreateUserModal();
        await atualizarConsulta(); 
      }
    },
    {
      rotulo: "Exportar CSV",
      icone: Download,
      posicao: "inferior",
      cor: "success",
      acao: (params) => {
        // 'params' contém os filtros atuais aplicados na tabela
        UsuarioService.exportarCsv(params);
      }
    }
  ],

  consulta: async (params) => {
    // params contém: offSet, limit, texto_busca, coluna_ordem, direcao_ordem, filtros
    return await UsuarioService.listar(params);
  },

  acoesLinha: [
    {
      rotulo: "Editar",
      icone: Pencil,
      cor: "primary",
      acao: (usuario) => console.log("Editar", usuario)
    }
  ]
};
</script>

<template>
  <EliTabela :tabela="tabelaConfig" />
</template>
```

---

### 2. EliEntrada (Inputs)

Um conjunto de wrappers padronizados em torno dos campos do Vuetify.

#### Variantes
- `EliEntradaTexto`: Texto, Email, URL, CPF, CNPJ, CEP.
- `EliEntradaNumero`: Inteiros, Decimais, Moeda.
- `EliEntradaDataHora`: Data, DataHora.
- `EliEntradaSelecao`: Select/Dropdown (pode ser assíncrono).
- `EliEntradaParagrafo`: Textarea.

#### API Comum
Todas as entradas aceitam duas props principais:
1.  `value`: O binding v-model.
2.  `opcoes`: Um objeto de configuração específico para o tipo de entrada.

#### Objetos de Configuração (`tiposEntradas.ts`)

**EliEntradaTexto**
```typescript
opcoes: {
  rotulo: string;
  placeholder?: string;
  limiteCaracteres?: number;
  formato?: "texto" | "email" | "url" | "telefone" | "cpfCnpj" | "cep";
}
```

**EliEntradaNumero**
```typescript
opcoes: {
  rotulo: string;
  precisao?: number; // 0=inteiro (padrão se null), 0.1=1 decimal, 0.01=2 decimais. Se undefined/null, assume decimal livre.
  prefixo?: string;  // ex: "R$"
  sufixo?: string;   // ex: "kg"
}
```

**EliEntradaDataHora**
```typescript
opcoes: {
  rotulo: string;
  modo?: "data" | "dataHora"; // padrão: "dataHora"
  min?: string; // String ISO
  max?: string; // String ISO
}
```

**EliEntradaSelecao**
```typescript
opcoes: {
  rotulo: string;
  // Função que retorna itens ou promise de itens. 
  // IMPORTANTE: Itens devem ser objetos { chave: string, rotulo: string }
  itens: () => Array<{ chave: string; rotulo: string }> | Promise<Array<{ chave: string; rotulo: string }>>;
  limpavel?: boolean;
}
```

#### Exemplo de Uso

```vue
<script setup lang="ts">
import { ref } from "vue";
import { EliEntradaTexto, EliEntradaNumero, EliEntradaDataHora } from "eli-vue";

const nome = ref("");
const salario = ref<number | null>(null);
const nascimento = ref<string | null>(null); // ISO string
</script>

<template>
  <EliEntradaTexto
    :value="nome"
    @update:value="nome = $event"
    :opcoes="{ rotulo: 'Nome Completo', formato: 'texto' }"
  />

  <EliEntradaNumero
    :value="salario"
    @update:value="salario = $event"
    :opcoes="{ rotulo: 'Salário', prefixo: 'R$', precisao: 0.01 }"
  />
  
  <!-- Exibe como data local, vincula como string ISO -->
  <EliEntradaDataHora
    :value="nascimento"
    @update:value="nascimento = $event"
    :opcoes="{ rotulo: 'Data de Nascimento', modo: 'data' }"
  />
</template>
```

---

### 3. EliBotao

Wrapper simples para `v-btn`.

- **Props**: `color`, `variant` (elevated, flat, text, etc.), `size`, `loading`, `disabled`.
- **Slots**: slot padrão para o conteúdo do botão.

```vue
<EliBotao color="primary" @click="salvar">
  Salvar
</EliBotao>
```

---

### 4. EliCartao & EliBadge

**EliCartao**
Cartão padronizado para itens de domínio.
- **Props**: `titulo`, `status` (tipo `CartaoStatus`: "novo" | "rascunho" | "vendido" | "cancelado"), `variant`.
- **Slots**: `default` (conteúdo), `acoes` (ações de rodapé).

**EliBadge**
Badge aprimorado com raios.
- **Props**: `badge` (conteúdo), `color`, `radius` ("suave" | "pill").

---

## 🔧 Solução de Problemas e Dicas

### 1. "Failed to resolve component"
- Certifique-se de que `app.use(EliVue)` foi chamado no `main.ts`.
- Se importar diretamente, garanta importações padrão: `import { EliTabela } from 'eli-vue'`.

### 2. Problemas de Estilo
- **Injeção de CSS**: O `eli-vue` injeta CSS automaticamente. Verifique sua CSP (Política de Segurança de Conteúdo) se os estilos estiverem bloqueados.
- **Vuetify**: Certifique-se de que o Vuetify 3 está corretamente instalado e os estilos (`vuetify/styles`) estão importados no seu arquivo de entrada principal.

### 3. Erros de TypeScript no `celulaTabela`
- Garanta que o segundo argumento corresponda ao esquema específico do tipo de célula.
- Exemplo: `celulaTabela("textoSimples", { texto: ... })` funciona, mas `celulaTabela("textoSimples", { numero: ... })` falhará.

### 4. Ícones não aparecem
- Passe o **objeto do componente** (ex: importado de `lucide-vue-next`), não o nome em string.
- Exemplo: `icone: Pencil` (Correto) vs `icone: "pencil"` (Incorreto).

### 5. Valores do `EliEntrada`
- `EliEntradaTexto` com `formato='cpfCnpj'` emite a string **formatada** (ex: "123.456.789-00").
- `EliEntradaNumero` emite um `number` ou `null`.
- `EliEntradaDataHora` trabalha com **Strings ISO** (ex: "2023-01-01T00:00:00Z"). A exibição é localizada, mas o valor do modelo é sempre ISO.