# IA.md — Guia para IAs (consumidoras) do pacote `eli-vue`

Este arquivo existe para **IAs e automações** que precisam **importar e usar** o pacote `eli-vue` em projetos Vue 3.

> Fonte da verdade das regras internas do repositório: **`.agent`**.
> Este `IA.md` é focado no **uso do pacote como dependência** (projeto consumidor).

---

## O que é o `eli-vue`

Biblioteca (Design System) de componentes para **Vue 3** com **TypeScript** e integração com **Vuetify 3**.

### Premissas importantes

- O `eli-vue` **não cria** nem configura Vuetify no seu projeto.
- `vue` e `vuetify` são **peerDependencies**: o projeto consumidor precisa ter ambos instalados.

---

## Instalação (projeto consumidor)

> Preferência do repo: `pnpm`.

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

Se o projeto ainda não tiver as peer dependencies, instale também:

```bash
pnpm add vue vuetify
```

---

## Uso recomendado

### 1) Registro global via plugin (recomendado)

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

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

// eli-vue
import EliVue from "eli-vue";
import "eli-vue/dist/eli-vue.css";

const vuetify = createVuetify({});

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

### 2) Importação direta (quando não quiser plugin)

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

> Observação: ainda pode ser necessário importar o CSS do pacote:

```ts
import "eli-vue/dist/eli-vue.css";
```

---

## Exemplos mínimos

### Botão

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

### Input com 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("");
    function salvar() {
      // ...
    }

    return { nome, salvar };
  },
});
</script>
```

### Input de porcentagem

Quando precisar de um campo numérico com sufixo `%`, use `type="porcentagem"`.

```vue
<template>
  <EliInput v-model="taxa" type="porcentagem" label="Taxa" placeholder="0,00" />
</template>

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

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

### Data e hora (entrada) com suporte a UTC/Z

```vue
<template>
  <!-- Valor chega do backend em ISO 8601 (UTC/offset), e o componente exibe em horário local -->
  <EliDataHora v-model="dataHora" rotulo="Agendamento" />

  <!-- Somente data -->
  <EliDataHora v-model="data" modo="data" rotulo="Nascimento" />
</template>

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

export default defineComponent({
  setup() {
    const dataHora = ref<string | null>("2026-01-09T16:15:00Z");
    const data = ref<string | null>("2026-01-09T00:00:00-03:00");
    return { dataHora, data };
  },
});
</script>
```

---

## Troubleshooting (para IAs)

### 1) “Failed to resolve component”

Provável causa: componente não foi registrado.

- Se estiver usando plugin: confirme `app.use(EliVue)`
- Se estiver importando direto: registre localmente no componente

### 2) Estilos não aplicam

Confirme que o projeto importou:

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

### 3) Ícones não aparecem

Alguns exemplos usam `<v-icon>` (MDI). O `eli-vue` **não instala** ícones automaticamente no projeto consumidor.

---

## Como a IA deve agir ao modificar um projeto consumidor

Quando for integrar `eli-vue` num projeto existente:

1) Verifique se **Vue 3** e **Vuetify 3** já estão configurados.
2) Prefira usar o **plugin** do `eli-vue` (simplifica registro).
3) Garanta o import do CSS do pacote (`eli-vue/dist/eli-vue.css`).
4) Ao ver erros de tipos, valide se o projeto está usando TypeScript e se o build está resolvendo `types` corretamente.

---

## Quando este arquivo deve ser atualizado

Atualize este `IA.md` quando houver mudanças em qualquer um destes pontos:

- caminho/nome do CSS em `dist/`
- forma de instalação e/ou peerDependencies
- forma de uso do plugin/export principal
- lista de exports públicos (novos componentes, renomes, remoções)
- mudanças de comportamento relevantes para consumo