vue-componentes/README.md

# eli-vue — Design System (Vue 3 + TypeScript)

Biblioteca de componentes Vue 3 (Design System) para reutilização em múltiplos projetos.

Este README foi escrito para **humanos e IAs**: ele descreve o objetivo do repositório, regras, estrutura, fluxo de contribuição, comandos e um roadmap de melhorias.

## Fonte da verdade (regras)

As regras oficiais do repositório estão no arquivo **`.agent`**.

Antes de propor mudanças:

- leia o `.agent`
- procure padrões já existentes no código
- atualize a documentação correspondente (README raiz e/ou README do componente)

## Objetivos

- consistência visual e comportamental
- tipagem forte (TypeScript `strict`)
- documentação em português
- exemplos executáveis via playground

## O que NÃO entra no contexto

- `node_modules/`: dependências (não versionar; não usar como fonte da verdade)
- `dist/`: gerado no build (não versionar)

## Arquitetura do repositório

```
src/
  componentes/
    botao/
      EliBotao.vue
      index.ts
      README.md
    campo/
      EliInput.vue
      index.ts
      README.md
    indicador/
      EliBadge.vue
      index.ts
      README.md
  tipos/
    botao.ts
    campo.ts
    indicador.ts
    index.ts
  playground/
    App.vue
    *.playground.vue
  index.ts
```

### Convenções (nomenclatura)

- Componentes usam **prefixo `Eli`** (ex.: `EliBotao`, `EliInput`).
- Pastas preferem **português** (ex.: `src/componentes/botao`, `src/componentes/campo`).
- Tipos compartilhados ficam em `src/tipos/`.
- Sem TSX; padrão SFC: `<template>` + `<script lang="ts">` + `defineComponent`.
- `any` é proibido.

## Instalação

```bash
pnpm add eli-vue
```

> Observação: `vue` e `vuetify` são **peerDependencies**.

### Instalação (projeto consumidor já usa Vuetify)

Se o seu projeto já está configurado com Vuetify 3, basta instalar este pacote:

```bash
pnpm add eli-vue
```

> Dica: mantenha `vue` e `vuetify` atualizados dentro das faixas suportadas.

## Uso

### 1) Registro global (plugin)

```ts
import { createApp } from "vue";
import EliVue from "eli-vue";

import App from "./App.vue";

createApp(App).use(EliVue).mount("#app");
```

#### Exemplo completo (main.ts) — com Vuetify 3

Este é o modelo recomendado para projetos consumidores (Vite + Vue 3) **que já usam Vuetify 3**:

```ts
import { createApp } from "vue";
import App from "./App.vue";

// Vuetify
import "vuetify/styles";
import { createVuetify } from "vuetify";

// eli-vue (Design System)
import EliVue from "eli-vue";
import "eli-vue/dist/eli-vue.css";

const vuetify = createVuetify({
  // opcional: componentes/directives/tema do seu projeto
});

createApp(App)
  .use(vuetify)
  .use(EliVue)
  .mount("#app");
```

> Nota: o `eli-vue` **não cria** nem configura Vuetify; ele assume que o consumidor já tem Vuetify.

### 2) Importação direta de componentes

```ts
import { EliBotao, EliInput, EliBadge } from "eli-vue";
```

## Exemplos rápidos de uso

### EliBotao

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

### EliInput (v-model)

```vue
<template>
  <EliInput v-model="nome" label="Nome" placeholder="Digite seu nome" />
</template>

<script lang="ts">
import { defineComponent, ref } from "vue";

export default defineComponent({
  setup() {
    const nome = ref("");
    return { nome };
  },
});
</script>
```

### EliBadge

```vue
<template>
  <EliBadge badge="3">
    <v-icon>mdi-bell</v-icon>
  </EliBadge>
</template>
```

## Troubleshooting (problemas comuns)

### 1) "Failed to resolve component" / componente não registrado

Você provavelmente esqueceu de:

- usar o plugin: `app.use(EliVue)`
- ou importar e registrar o componente localmente

### 2) Estilos não aplicam / layout estranho

Confirme que o consumidor importou:

- `vuetify/styles`
- `eli-vue/dist/eli-vue.css`

### 3) Ícones não aparecem

Alguns exemplos usam `<v-icon>` com Material Design Icons. O `eli-vue` **não instala ícones** no seu projeto.

- garanta que o seu projeto consumidor está configurado com o pacote de ícones desejado (ex.: MDI)
- ou substitua o conteúdo do slot por outro elemento

## Como rodar localmente

### Playground

```bash
pnpm dev
```

O playground (`src/playground`) valida visualmente variações e interações.

### Build da lib + geração de tipos

```bash
pnpm run build
```

Gera `dist/` (artefatos de build) e `dist/types` (declarações `.d.ts`).

## Guia rápido para IAs (antes de codar)

1) **Leia** `.agent` e este README.
2) **Busque padrões** antes de criar API nova (props/emits/slots).
3) **Não use `any`**.
4) **Centralize tipos** em `src/tipos/`.
5) Ao mudar API/comportamento:
   - atualize o `README.md` do componente
   - atualize ou crie um `*.playground.vue`
6) Rode `pnpm run build` antes de finalizar.

## Como criar/alterar um componente (checklist)

1. Criar pasta em `src/componentes/<nome_em_portugues>/`
2. Criar `EliNomeDoComponente.vue` com `defineComponent` + comentários úteis
3. Criar `index.ts` com re-export (ex.: `export { default as EliX } from './EliX.vue'`)
4. Criar `README.md` do componente (API, exemplos, casos de borda, A11y)
5. Criar playground em `src/playground/<nome>.playground.vue` (mín. 3 variações)
6. Exportar no `src/index.ts`

### Critérios de aceite (qualidade)

- `pnpm run build` passa (inclui `vue-tsc`)
- zero `any`
- `defineComponent` em todos os componentes
- README do componente atualizado quando API mudar
- playground demonstrando variações + interação

## Roadmap de melhorias (a aplicar)

### Curto prazo (qualidade / consistência)
- [ ] Padronizar comentários úteis em todos os componentes (explicar decisões e estados)
- [ ] Tipar `emits` com validação de payload (quando houver)
- [ ] Consolidar nomenclatura de props/eventos em português (avaliar breaking changes)

### Médio prazo (DX + segurança)
- [ ] Adicionar ESLint + Prettier e regras (incluindo proibição de `any`)
- [ ] Adicionar testes unitários com Vitest + @vue/test-utils
- [ ] Criar pipeline de CI rodando `pnpm run build`

### Longo prazo (docs e maturidade)
- [ ] Documentação visual (Storybook ou VitePress)
- [ ] Tokens de design (cores/spacing) e guideline de acessibilidade