@be-enlighten/beni-avatar

@be-enlighten/beni-avatar

Avatar Vue 3 animado, pequeno e simpático. Um squircle que olha pra você, pisca, pula e comemora. Solte-o em qualquer app Vue pra dar personalidade a estados de carregamento, páginas vazias, fluxos de onboarding, ou só por diversão.

• 🎭 8 estados: idle, working, error, speaking, loading, sleep, branding, celebrate
• 💬 4 humores: happy, sad, angry, surprised (sobrepostos a qualquer estado)
• 🎩 6 acessórios de cabeça: beanie, coroa, capacete, chapéu de festa, gorro de papai noel, gorro stan
• 🖱️ Olhos que seguem o mouse, opcional
• 🎉 Easter eggs por clique: duplo, triplo, quíntuplo
• 🎨 Tema via props: cores do corpo e dos olhos controladas pelo componente pai
• ⚡ ~14 KB gzipped, sem dependências de runtime além de gsap e vue

Animações a 60fps com GSAP.

Demo

A playground em examples/beni-avatar é um estúdio interativo: à esquerda, os 8 estados como cards clicáveis; no centro, o Beni grande controlado pela seleção; à direita, os 4 humores. Logo abaixo, um painel de configuração com acessório, tema (5 presets), toggle "seguir mouse" e slider de intervalo de piscada. Os cards reagem ao tema e ao acessório ativos, com borda gradiente destacada no item selecionado. É também a página hospedada na Vercel.

Instalação

pnpm add @be-enlighten/beni-avatar gsap
# ou
npm install @be-enlighten/beni-avatar gsap
# ou
yarn add @be-enlighten/beni-avatar gsap

Peer dependency: vue ≥ 3.5. O gsap (≥ 3.15) é dependency do pacote — instalado automaticamente; declare-o também no app se quiser pinar a mesma cópia.

Início rápido

O avatar é distribuído como um SFC Vue acompanhado de um arquivo CSS. Importe o stylesheet uma vez no app, em main.ts, para que as variáveis CSS dos acessórios fiquem disponíveis:

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import '@be-enlighten/beni-avatar/style.css'

createApp(App).mount('#app')

<!-- App.vue -->
<script setup lang="ts">
import { ref } from 'vue'
import { Beni, type BeniState, type MoodName } from '@be-enlighten/beni-avatar'

const state = ref<BeniState>('idle')
const mood = ref<MoodName | null>(null)
</script>

<template>
  <Beni
    v-model:state="state"
    v-model:mood="mood"
  />
</template>

Pronto. Você tem um squircle de ~160×160 que pisca, respira e segue o cursor.

Props

* bind bidirecional via v-model.

Eventos

Estados

<Beni :state="currentState" />

const currentState = ref<BeniState>('working')

watch(someTask, (task) => {
  currentState.value = task.status === 'loading' ? 'working' : 'celebrate'
})

Humores

Os humores se sobrepõem a um estado. Mudam olhos, boca e geram pequenos elementos SVG (lágrima, veia de raiva).

<Beni v-model:state="state" v-model:mood="mood" />

Você pode derivar o humor a partir do estado. O avatar já dispara happy no clique duplo em idle (veja "Interações internas").

Acessórios de cabeça

Seis itens prontos. Cada um acompanha o pulo/escala/rotação do corpo, mas se mantém firme em cima da cabeça — não inclina com a inclinação do corpo, na prática parecia instável demais.

<Beni :head-item="accessory" />

import { type HeadItemKey, headItemNames, headItemLabels } from '@be-enlighten/beni-avatar'
import { ref } from 'vue'

const accessory = ref<HeadItemKey | null>('crown')

Em working, loading e error o acessório é escondido automaticamente. Esses estados giram tanto o corpo que o chapéu voaria.

Tematizando os acessórios: as cores vêm de variáveis CSS. Sobrescreva-as no seu stylesheet:

:root {
  --beni-items-head-crown: #ffd700;
  --beni-items-head-crown-shade: #b8860b;
  --beni-items-head-beanie: #8b5cf6;
  /* ... */
}

Importe @be-enlighten/beni-avatar/style.css antes e sobrescreva as variáveis depois.

Interações internas por clique

Clique rápido pra disparar easter eggs. Já vêm de fábrica, sem flag.

Cada interação é anunciada pelo evento interaction.

Eventos de clique

<Beni @click="onClick" @interaction="onInteraction" />

import type { BeniClickPayload, BeniInteractionPayload } from '@be-enlighten/beni-avatar'

function onClick(p: BeniClickPayload) {
  console.log(p.target)       // 'body' | 'eye-left' | 'eye-right'
  console.log(p.clickIndex)   // 1 no primeiro clique, 2 no segundo dentro de 800ms, ...
  console.log(p.state)        // estado atual
  console.log(p.mood)         // humor atual (ou null)
}

function onInteraction(p: BeniInteractionPayload) {
  console.log(p.id)              // ex.: 'happy-on-double-click'
  console.log(p.label)           // legível por humanos
  console.log(p.triggerClickCount)
}

Tematizando o avatar

<script setup lang="ts">
const theme = {
  body: '#f59e0b',
  bodyTo: '#ef4444',
  eye: '#fef3c7',
}
</script>

<template>
  <Beni
    :body-base-color="theme.body"
    :body-base-color-to="theme.bodyTo"
    :eye-base-color="theme.eye"
  />
</template>

Para um seletor de temas completo, use computed:

import { computed } from 'vue'
import type { BeniState, MoodName } from '@be-enlighten/beni-avatar'

const theme = computed(() => themes[currentTheme.value])
const state = ref<BeniState>('idle')
const mood = ref<MoodName | null>(null)

O avatar é totalmente reativo: cada mudança de prop entra com tween (sem piscar), e estados/humores fazem crossfade suave.

Exemplo: estado de carregamento de um assistente de IA

<script setup lang="ts">
import { ref, watch } from 'vue'
import { Beni, type BeniState, type MoodName } from '@be-enlighten/beni-avatar'

const status = ref<'idle' | 'thinking' | 'done'>('idle')
const state = ref<BeniState>('idle')
const mood = ref<MoodName | null>(null)

watch(status, (s) => {
  if (s === 'thinking') {
    state.value = 'working'
    mood.value = null
  } else if (s === 'done') {
    state.value = 'celebrate'
    mood.value = 'happy'
  } else {
    state.value = 'idle'
    mood.value = null
  }
})
</script>

<template>
  <div class="assistant">
    <Beni
      v-model:state="state"
      v-model:mood="mood"
      :head-item="status === 'done' ? 'partyhat' : null"
      body-base-color="#fbbf24"
      body-base-color-to="#ec4899"
      eye-base-color="#fef3c7"
    />
    <p v-if="status === 'thinking'">Pensando…</p>
    <p v-else-if="status === 'done'">Pronto!</p>
  </div>
</template>

TypeScript

Pacote totalmente tipado. Exports mais úteis:

import type {
  BeniState,
  MoodName,
  HeadItemKey,
  BodyModelName,
  EyeModelName,
  BeniClickPayload,
  BeniInteractionPayload,
} from '@be-enlighten/beni-avatar'

// Constantes
import {
  beniStateNames, // ['idle', 'working', ...]
  beniMoods,
  headItemNames,
  headItemLabels,
} from '@be-enlighten/beni-avatar'

Suporte a navegadores

Qualquer navegador com suporte a CSS moderno (custom properties, filter) e SVG, ou seja, todos os navegadores evergreen. O GSAP exige requestAnimationFrame, que é universal.

O pacote respeita prefers-reduced-motion: reduce: as animações pausam no frame final quando o usuário tem essa preferência ativa.

Desenvolvimento

Este pacote vive no monorepo en-sdk (packages/beni-avatar). A demo/playground fica em examples/beni-avatar e consome o dist/ deste pacote via workspace — rode o build antes (e após cada mudança no src/).

pnpm install
pnpm --filter @be-enlighten/beni-avatar build             # gera dist/ (pacote)
pnpm --filter @be-enlighten/beni-avatar typecheck         # só type-check
pnpm --filter @be-enlighten/enspace-sdk-example-beni dev  # playground em http://localhost:5173

Publicando

Versão própria — este pacote não entra no lockstep dos 4 packages enspace-sdk-*. O versionamento é gerenciado por changesets (.changeset/ no root do monorepo): adicione um changeset com pnpm changeset a cada mudança user-facing e publique pelo fluxo unificado do monorepo:

pnpm version-packages   # bumpa versão + gera CHANGELOG a partir dos changesets
pnpm release            # valida, builda e publica o que estiver pendente

Detalhes na seção Publicação do AGENTS.md do monorepo. Sobe no npm público (access: public). Precisa de login npm local (npm login) com acesso ao escopo @be-enlighten.

Licença

MIT.