# Design System Vue 3 (TypeScript) — Regras do Agente

## Objetivo do projeto
Construir um Design System de componentes em **Vue 3** para reutilização em múltiplos projetos, com foco em:
- **Consistência visual e de comportamento**
- **Componentes bem tipados (TypeScript forte)**
- **Documentação em português** (para devs e para outras IAs)
- **Exemplos executáveis (playground)**
- **Facilidade de manutenção e evolução**

---

## O que NÃO entra no contexto do agente

- `node_modules/`: dependências da arquitetura (não versionar / não usar como “fonte da verdade”).
- `dist/`: pasta **gerada** pelo build (não versionar). Use para validar o build localmente.

---

## Stack e padrões obrigatórios
- Vue 3
- TypeScript (modo estrito e tipagem forte)
- **defineComponent** (obrigatório)
- Sem TSX (padrão: `<template>` + `<script lang="ts">`)
- Estilo: **NÃO usar CSS scoped**. Usar namespacing estático (BEM) com prefixo `eli-` (ex: `.eli-botao__texto`).
- Ícones: caso seja necessário o uso de ícones, usar **lucide** (biblioteca `lucide-vue-next`) como padrão do repositório.

---

## Regras de Estilização (CSS) - IMPORTANTE

Para garantir compatibilidade e evitar problemas de hidratação/build em projetos consumidores:

1.  **NUNCA usar `<style scoped>`**.
    *   O atributo `scoped` gera hashes dinâmicos (`data-v-xyz`) que mudam a cada build.
    *   Isso quebra o estilo se o projeto consumidor não atualizar o CSS instantaneamente.

2.  **Use Namespacing Estático (Padrão BEM)**.
    *   Todas as classes devem começar com o prefixo do componente (ex: `.eli-tabela`).
    *   Elementos internos devem seguir o padrão BEM ou similar (ex: `.eli-tabela__cabecalho`, `.eli-tabela--carregando`).
    *   **Exemplo Correto:**
        ```css
        .eli-modal { ... }
        .eli-modal__titulo { ... }
        ```
    *   **Exemplo INCORRETO:**
        ```css
        .container { ... } /* Muito genérico */
        .titulo { ... }    /* Conflita com outros estilos */
        ```

3.  **Evite seletores de tag soltos**.
    *   Não estilize tags HTML diretamente (ex: `div`, `input`, `button`) a menos que estejam estritamente aninhadas em uma classe namespaced.
    *   Melhor ainda: coloque classes em todos os elementos que precisam de estilo.
    *   **Válido:** `.eli-form input { ... }` (aceitável, mas prefira `.eli-form__input`)
    *   **Proibido:** `input { ... }` (afeta a aplicação inteira do consumidor)

---

## Regras de idioma e nomenclatura
- **Variáveis, nomes de arquivos e nomes de pastas em português sempre que possível**
  - Ex.: `botao`, `cartao`, `campo_texto`, `seletor_opcoes`
  - Evitar abreviações confusas
- Nomes de componentes (PascalCase) podem seguir padrão técnico:
  - **Padrão do repositório:** componentes com prefixo `Eli` (ex.: `EliBotao`, `EliInput`).
  - Pastas preferem português (ex.: `src/componentes/botao/`, `src/componentes/campo/`).
- Props e eventos: preferir português e sem ambiguidades:
  - Props: `rotulo`, `desabilitado`, `carregando`, `modeloValor`
  - Eventos: `update:modelValue`, `confirmar`, `cancelar`, `clicar`

---

## Convenção atual de entradas (IMPORTANTE)

O componente **`EliInput` foi removido**. O padrão atual é a família **`EliEntrada*`**:

- `EliEntradaTexto`
- `EliEntradaNumero`
- `EliEntradaDataHora`

E o contrato padrão para entradas é:
- prop `value`
- evento `update:value`
- prop obrigatória `opcoes` (contém `rotulo` e outras opções)

Exemplo:

```vue
<EliEntradaTexto v-model:value="nome" :opcoes="{ rotulo: 'Nome' }" />
```

---

## Estrutura obrigatória do repositório
- Cada componente deve possuir **sua própria pasta** em `src/componentes/`
- Dentro de cada pasta do componente:
  - `README.md` (detalhado e em português)
  - `index.ts` (re-export)
  - Arquivo do componente `.vue`
  - (opcional) `tipos.ts` se necessário para manter tipagem limpa

Estrutura sugerida:

src/
  componentes/
    botao/
      EliBotao.vue
      index.ts
      README.md
    cartao/
      EliCartao.vue
      index.ts
      README.md
  playground/
    botao.playground.vue
    cartao.playground.vue
  index.ts

Raiz do projeto:
- `README.md` geral (guia do design system em português)

Pastas geradas/ignoradas:
- `dist/` (build)
- `node_modules/` (dependências)

---

## Documentação obrigatória (README.md)
### 1) README.md na raiz (obrigatório)
Deve servir como guia para desenvolvedores e outras IAs, contendo:
- Visão geral do design system
- Como instalar e usar (ex.: importações, registro)
- Convenções do projeto (tipagem, pastas, playground)
- Como criar um novo componente (checklist)
- Como rodar o playground
- Padrões de versionamento (se aplicável)

### 2) README.md por componente (obrigatório)
Cada componente precisa ter um README.md com **mais detalhamento**:
- O que o componente resolve (objetivo)
- API completa:
  - Props (nome, tipo, padrão, descrição)
  - Emits (nome, payload, quando dispara)
  - Slots (nome, objetivo, exemplo)
- Exemplos de uso (mínimo 2)
- Casos de borda / comportamento esperado
- Acessibilidade (quando aplicável)
- Decisões de implementação relevantes (por que foi feito assim)

**Idioma:** sempre em português claro.

---

## Comentários obrigatórios nos componentes
Todos os componentes `.vue` devem conter comentários úteis, principalmente:
- Explicando a intenção de blocos importantes (watchers, computed, validações)
- Explicando decisões de tipagem
- Explicando regras de negócio / estados (carregando, erro, desabilitado)
Evitar comentários óbvios (“isso é um botão”).

---

## Tipagem forte (TypeScript) — regras
- Usar `strict: true`
- Evitar `any` (proibido), exceto se for inevitável e justificado no README do componente
- Preferir tipos explícitos para:
  - props complexas
  - retornos de funções
  - emits com payload tipado
- Para props complexas, usar `PropType<T>` quando necessário
- Padronizar nomes de tipos em português:
  - `tipoOpcao`, `tipoTamanho`, `tipoEstado`, `tipoTema`

### Centralização de tipos (padrão do repositório)

- Tipos compartilhados (uniões, enums, aliases) devem ficar em `src/tipos/`.
- Cada domínio pode ter seu arquivo:
  - `src/tipos/botao.ts`
  - `src/tipos/campo.ts`
  - `src/tipos/indicador.ts`
- Re-export central em `src/tipos/index.ts`.
- Componentes importam tipagens de `src/tipos`.

---

## Padrão defineComponent (obrigatório)
- Sempre usar:
  - `<script lang="ts">`
  - `export default defineComponent({ ... })`
- Props com tipos explícitos
- Emits declarados e tipados
- Preferir `computed`, `ref` e `watch` com tipos claros

---

## Playground obrigatório para cada componente
- Todo componente criado deve ter **um teste demonstrativo** em `src/playground`
- O playground deve:
  - Exibir variações do componente (mínimo 3 variações)
  - Demonstrar interação (v-model, click, estados)
  - Validar visualmente comportamentos e casos de borda
- Nome do arquivo do playground:
  - `nome_do_componente.playground.vue`
  - Ex.: `botao.playground.vue`, `campo_texto.playground.vue`

---

## Regras de exportação e reuso
- Cada pasta do componente deve ter `index.ts` exportando o componente:
  - `export { default as EliBotao } from "./EliBotao.vue"`
- `src/index.ts` deve exportar todos os componentes publicamente
- Não exportar itens internos não documentados

---

## Convenção atual de EliTabela (IMPORTANTE)

### Filtro avançado

O filtro avançado da `EliTabela` é configurado via `tabela.filtroAvancado`.

Regras:
- O **operador é travado na definição** (o usuário não escolhe operador)
- Cada filtro pode ser usado **no máximo 1 vez**
- UI: modal mostra **apenas os componentes de entrada** definidos no filtro
- Persistência: salva em `localStorage` apenas `{ coluna, valor }[]` por `tabela.nome`

Se você for evoluir isso para backend:
- usar `parametrosConsulta.filtros` (`tipoFiltro[]`) no `tabela.consulta`
- manter compatibilidade com simulação local (quando necessário)

---

## Publicação do pacote (npm)

### Regra de publicação (sem usar `package.json.files`)

Este repositório **não usa** o campo `package.json.files`.
O controle do que vai para o tarball publicado é feito via **`.npmignore`**.

**Ação obrigatória:** sempre que adicionar/renomear/remover arquivos importantes para consumo (ex.: `IA.md`, mudanças de CSS em `dist/`, novas tipagens geradas), revisar e atualizar o `.npmignore`.

**Validação obrigatória:** após alterar `.npmignore`, rodar:

```bash
npm pack --dry-run
```

E confirmar que o tarball inclui o que deve estar disponível para consumidores.

---

## Qualidade e consistência
- Antes de finalizar um componente:
  - Conferir documentação (README raiz + README do componente)
  - Conferir comentários no `.vue`
  - Conferir playground criado e funcionando
  - Conferir tipagem (sem any; sem tipos implícitos perigosos)

---

## Checklist por componente (obrigatório)
Ao criar/alterar componente, garantir:
- [ ] Pasta do componente criada em `src/componentes/<nome_em_portugues>/`
- [ ] `.vue` com defineComponent + comentários úteis
- [ ] `index.ts` com export do componente
- [ ] README.md do componente completo (em português)
- [ ] Playground criado em `src/playground/`
- [ ] Export adicionado em `src/index.ts`
- [ ] Tipos fortes (sem any; PropType<T> quando necessário)

---

## Regra de mudança importante
Sempre que uma mudança for relevante para desenvolvedores/usuários/IA, **atualizar o README.md correspondente**:
- README da raiz (se impactar o projeto)
- README do componente (se impactar API/uso/comportamento)

### Documentação para IAs consumidoras (IA.md)

O arquivo **`IA.md`** (na raiz) é um guia para **IAs que vão consumir/importar** o pacote `eli-vue`.

Sempre que houver mudanças relevantes de consumo, **`IA.md` deve ser atualizado** — por exemplo:

- instalação / comandos recomendados (pnpm/npm/yarn)
- peerDependencies (Vue/Vuetify) e requisitos mínimos
- forma de uso do plugin (`import EliVue from "eli-vue"`) e registro
- caminho/nome do CSS publicado em `dist/` (ex.: `eli-vue/dist/eli-vue.css`)
- exports públicos (componentes adicionados/removidos/renomeados)

---

## Postura do agente ao gerar código
- Gerar código enxuto, legível e consistente
- Priorizar clareza e tipagem forte
- Nunca “inventar” API sem documentar
- Se houver dúvida de padrão visual, criar uma implementação neutra, documentar e manter extensível
