@datametria/vue-components

Biblioteca enterprise de componentes Vue.js 3 com 100% conformidade UX/UI DATAMETRIA

40 módulos • Variants padronizados • Design System completo • WCAG 2.1 AA • Dark Mode nativo • Sistema responsivo avançado • Micro-interações modernas • 514 testes

🏆 Features Enterprise (100% Conformidade UX/UI)

✅ 4 Sprints Implementados + Variants Padronizados

• 🎨 Sprint 1: Design System Enhancement (gradientes, bordas, dark mode, escalabilidade)
• 🧩 Sprint 2: Componentes Críticos (TimePicker, Slider, Tooltip, Menu)
• ⚡ Sprint 3: Micro-interações (shimmer, ripple, haptic feedback)
• 📱 Sprint 4: Responsividade Avançada (6 breakpoints, typography fluida, container queries)
• 🎯 Variants v1.2.0: Padronização completa de variants com primary em todos os componentes

🎯 Qualidade Enterprise

• 40 módulos (30 componentes + 10 composables)
• 514 testes com 100% success rate
• 82%+ coverage geral (100% nos componentes principais)
• Variants padronizados - Primary variant em todos os componentes
• Validação runtime - Warnings em desenvolvimento para variants inválidos
• WCAG 2.1 AA com escalabilidade controlada (0.8x-2.0x)
• Performance otimizada para produção
• TypeScript completo com inferência automática

📦 Instalação

# npm
npm install @datametria/vue-components

# yarn
yarn add @datametria/vue-components

# pnpm
pnpm add @datametria/vue-components

🚀 Uso Rápido

Importação Global

// main.ts
import { createApp } from 'vue'
import DatametriaComponents from '@datametria/vue-components'
import '@datametria/vue-components/style.css'

const app = createApp(App)
app.use(DatametriaComponents)
app.mount('#app')

Importação Individual (Recomendado)

<script setup lang="ts">
import { DatametriaButton, DatametriaInput } from '@datametria/vue-components'
import '@datametria/vue-components/style.css'
import { ref } from 'vue'

const email = ref('')
const password = ref('')

const handleLogin = () => {
  console.log('Login:', email.value, password.value)
}
</script>

<template>
  <div class="login-form">
    <DatametriaInput 
      v-model="email" 
      label="Email" 
      type="email"
      placeholder="seu@email.com" 
    />
    <DatametriaInput 
      v-model="password" 
      label="Senha" 
      type="password" 
    />
    <DatametriaButton 
      variant="primary" 
      @click="handleLogin"
    >
      Entrar
    </DatametriaButton>
  </div>
</template>

🎯 Guia Rápido de Variants

✅ Todos os Componentes Suportam primary

<!-- ✅ CORRETO - Primary variant disponível em todos -->
<DatametriaButton variant="primary">Botão Principal</DatametriaButton>
<DatametriaAlert variant="primary" message="Alerta importante" />
<DatametriaNavbar variant="primary" brand="DATAMETRIA" />
<DatametriaToast variant="primary" message="Notificação" />
<DatametriaBadge variant="primary" label="Novo" />
<DatametriaChip variant="primary" label="Tag" />

⚠️ Breaking Changes v1.2.0

<!-- ❌ ANTES (v1.1.x) -->
<DatametriaChip variant="default">Chip</DatametriaChip>
<DatametriaToast variant="info" message="Azul" />

<!-- ✅ DEPOIS (v1.2.0) -->
<DatametriaChip variant="primary">Chip</DatametriaChip>
<DatametriaToast variant="primary" message="Azul" />
<DatametriaToast variant="info" message="Cinza" />

🛡️ Validação Automática

<!-- ❌ Variant inválido -->
<DatametriaButton variant="invalid">Botão</DatametriaButton>
<!-- Console: [DatametriaButton] Invalid variant "invalid". Valid options: primary, secondary, outline, ghost -->

<!-- ✅ Variants válidos por componente -->
<DatametriaButton variant="primary | secondary | outline | ghost" />
<DatametriaAlert variant="primary | success | error | warning | info" />
<DatametriaNavbar variant="primary | light | dark | transparent" />

📚 Migração Rápida

# Script automático de migração
curl -o migrate.sh https://raw.githubusercontent.com/datametria/vue-components/main/scripts/migrate-variants.sh
chmod +x migrate.sh && ./migrate.sh

📖 Guia Completo de Migração

🎨 Componentes (30 implementados)

🌟 Novos Componentes dos Sprints

• DatametriaTimePicker ⭐ Sprint 2 - Seletor de hora com WCAG 2.1 AA
• DatametriaSlider ⭐ Sprint 2 - Range slider com visual progress
• DatametriaTooltip ⭐ Sprint 2 - Tooltip com posicionamento dinâmico
• DatametriaMenu ⭐ Sprint 2 - Menu dropdown com keyboard navigation
• DatametriaSkeleton ⭐ Sprint 3 - Loading skeleton com shimmer animation

🔘 Form Components (10)

<!-- Button com 4 variants padronizados -->
<DatametriaButton variant="primary" size="md" :loading="false">
  Primary Button
</DatametriaButton>
<DatametriaButton variant="secondary">Secondary</DatametriaButton>
<DatametriaButton variant="outline">Outline</DatametriaButton>
<DatametriaButton variant="ghost">Ghost</DatametriaButton>

<!-- Input com validação -->
<DatametriaInput 
  v-model="value" 
  label="Nome" 
  :error="errorMessage"
  required 
/>

<!-- Select com options -->
<DatametriaSelect 
  v-model="selected" 
  :options="options" 
  placeholder="Selecione..."
/>

<!-- Checkbox -->
<DatametriaCheckbox v-model="checked" label="Aceito os termos" />

<!-- Radio -->
<DatametriaRadio v-model="selected" value="option1" label="Opção 1" />

<!-- Switch -->
<DatametriaSwitch v-model="enabled" label="Ativar notificações" />

<!-- Textarea -->
<DatametriaTextarea v-model="text" label="Mensagem" :maxlength="500" />

<!-- DatePicker -->
<DatametriaDatePicker v-model="date" label="Data" />

<!-- FileUpload -->
<DatametriaFileUpload v-model="files" :multiple="true" />

<!-- Autocomplete -->
<DatametriaAutocomplete 
  v-model="selected" 
  :options="options" 
  placeholder="Buscar..."
/>

📦 Layout Components (5)

<!-- Card com slots -->
<DatametriaCard title="Título" subtitle="Subtítulo">
  <template #header>Header customizado</template>
  Conteúdo do card
  <template #footer>Footer customizado</template>
</DatametriaCard>

<!-- Modal com teleport -->
<DatametriaModal v-model="isOpen" title="Modal" size="md">
  Conteúdo do modal
</DatametriaModal>

<!-- Container responsivo -->
<DatametriaContainer size="lg" :fluid="false">
  Conteúdo
</DatametriaContainer>

<!-- Grid responsivo -->
<DatametriaGrid :cols="3" :gap="4">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</DatametriaGrid>

<!-- Divider -->
<DatametriaDivider orientation="horizontal" :dashed="false" />

🔔 Feedback Components (4)

<!-- Alert com variant primary -->
<DatametriaAlert variant="primary" :closable="true">
  Informação importante!
</DatametriaAlert>
<DatametriaAlert variant="success" :closable="true">
  Operação realizada com sucesso!
</DatametriaAlert>

<!-- Toast com variant primary -->
<DatametriaToast 
  v-model="showToast" 
  variant="primary" 
  :duration="3000"
>
  Notificação importante
</DatametriaToast>
<DatametriaToast variant="info">Informação</DatametriaToast>

<!-- Progress -->
<DatametriaProgress :value="75" variant="primary" />

<!-- Spinner -->
<DatametriaSpinner size="md" variant="primary" />

📊 Data Display (4)

<!-- Table -->
<DatametriaTable :columns="columns" :data="data" />

<!-- Avatar -->
<DatametriaAvatar 
  src="/avatar.jpg" 
  alt="User" 
  size="md" 
  :rounded="true"
/>

<!-- Badge -->
<DatametriaBadge variant="success" size="md">
  Novo
</DatametriaBadge>

<!-- Chip -->
<DatametriaChip 
  variant="primary" 
  :closable="true" 
  @close="handleClose"
>
  Tag
</DatametriaChip>

🧭 Navigation (3)

<!-- Navbar -->
<DatametriaNavbar variant="primary" :sticky="true">
  <template #brand>Logo</template>
  <template #menu>Menu</template>
  <template #actions>Actions</template>
</DatametriaNavbar>

<!-- Breadcrumb -->
<DatametriaBreadcrumb :items="breadcrumbs" separator="/" />

<!-- Tabs -->
<DatametriaTabs v-model="activeTab" :tabs="tabs" />

🧩 Composables (10 implementados)

🌟 Novos Composables dos Sprints

• useAccessibilityScale ⭐ Sprint 1 - Escalabilidade controlada 0.8x-2.0x
• useRipple ⭐ Sprint 3 - Efeitos ripple Material Design
• useHapticFeedback ⭐ Sprint 3 - Feedback háptico com fallback visual
• useBreakpoints ⭐ Sprint 4 - Detecção responsiva com 6 breakpoints

useTheme - Dark Mode

import { useTheme } from '@datametria/vue-components'

const { isDark, toggle, setDark, setLight } = useTheme()

// Toggle dark mode
toggle()

// Set específico
setDark()
setLight()

// Verifica estado
console.log(isDark.value) // true/false

useValidation - Validators

import { useValidation } from '@datametria/vue-components'

const { required, email, minLength, maxLength, pattern, custom } = useValidation()

// Validar campo
const isValid = required(value) // boolean
const isEmail = email('test@example.com') // boolean
const isMin = minLength(5)('texto') // boolean

useAPI - HTTP Client

import { useAPI } from '@datametria/vue-components'

const { get, post, put, delete: del, loading, error, data } = useAPI()

// GET request
await get('/api/users')
console.log(data.value) // Response data

// POST request
await post('/api/users', { name: 'John' })

// Loading state
console.log(loading.value) // true/false

// Error handling
if (error.value) {
  console.error(error.value)
}

useLocalStorage - Sync Storage

import { useLocalStorage } from '@datametria/vue-components'

const user = useLocalStorage('user', { name: 'Default' })

// Auto-sync com localStorage
user.value = { name: 'John' }
// localStorage.setItem('user', '{"name":"John"}')

console.log(user.value) // { name: 'John' }

useDebounce - Delay Input

import { useDebounce } from '@datametria/vue-components'
import { ref } from 'vue'

const search = ref('')
const debouncedSearch = useDebounce(search, 300)

// search muda imediatamente
// debouncedSearch muda após 300ms
watch(debouncedSearch, (value) => {
  console.log('Buscar:', value)
})

useClipboard - Copy/Paste

import { useClipboard } from '@datametria/vue-components'

const { copy, read, copied, error } = useClipboard()

// Copiar texto
await copy('Texto para copiar')
console.log(copied.value) // true (auto-reset após 2s)

// Ler clipboard
const text = await read()
console.log(text)

🎨 Design System Completo ⭐ Sprint 1

🌈 Cores + Gradientes Corporativos

/* Cores principais */
--dm-primary: #0072CE; /* Azul DATAMETRIA */
--dm-secondary: #4B0078; /* Roxo DATAMETRIA */
--dm-success: #10b981;
--dm-warning: #f59e0b;
--dm-error: #ef4444;
--dm-info: #3b82f6;

/* Gradientes corporativos ⭐ Sprint 1 */
--gradient-primary: linear-gradient(135deg, #0072CE 0%, #005ba3 100%);
--gradient-secondary: linear-gradient(135deg, #4B0078 0%, #3a005c 100%);
--gradient-success: linear-gradient(135deg, #10b981 0%, #059669 100%);
--gradient-warning: linear-gradient(135deg, #f59e0b 0%, #d97706 100%);

/* Bordas temáticas ⭐ Sprint 1 */
--border-success: #10b981;
--border-warning: #f59e0b;
--border-info: #06b6d4;
--border-feature: #8b5cf6;
--border-error: #ef4444;

🌙 Dark Mode Nativo ⭐ Sprint 1

[data-theme="dark"] {
  --dm-primary: #3b82f6;
  --dm-secondary: #8b5cf6;
  --dm-bg-primary: #111827;
  --dm-text-primary: #f9fafb;
  /* + 20 variáveis adicionais */
}

📱 Sistema Responsivo Avançado ⭐ Sprint 4

/* 6 breakpoints */
--breakpoint-xs: 475px;
--breakpoint-sm: 640px;
--breakpoint-md: 768px;
--breakpoint-lg: 1024px;
--breakpoint-xl: 1280px;
--breakpoint-2xl: 1536px;

/* Typography fluida */
--dm-text-base-fluid: clamp(1rem, 0.9rem + 0.5vw, 1.125rem);
--dm-text-lg-fluid: clamp(1.125rem, 1rem + 0.625vw, 1.25rem);

/* Spacing fluido */
--space-md-fluid: clamp(1rem, 0.8rem + 1vw, 1.5rem);
--space-lg-fluid: clamp(1.5rem, 1.2rem + 1.5vw, 2.25rem);

/* Container queries */
@container (min-width: 320px) {
  .cq-xs\:block { display: block; }
}

/* Aspect ratio utilities */
.aspect-square { aspect-ratio: 1 / 1; }
.aspect-video { aspect-ratio: 16 / 9; }
.aspect-photo { aspect-ratio: 4 / 3; }

Spacing System

--dm-space-1: 0.25rem;  /* 4px */
--dm-space-2: 0.5rem;   /* 8px */
--dm-space-3: 0.75rem;  /* 12px */
--dm-space-4: 1rem;     /* 16px */
--dm-space-6: 1.5rem;   /* 24px */
--dm-space-8: 2rem;     /* 32px */

Typography

--dm-text-xs: 0.75rem;   /* 12px */
--dm-text-sm: 0.875rem;  /* 14px */
--dm-text-base: 1rem;    /* 16px */
--dm-text-lg: 1.125rem;  /* 18px */
--dm-text-xl: 1.25rem;   /* 20px */
--dm-text-2xl: 1.5rem;   /* 24px */

🎭 Micro-interações ⭐ Sprint 3

/* Shimmer loading states */
@keyframes shimmer {
  0% { background-position: -200% 0; }
  100% { background-position: 200% 0; }
}

.shimmer {
  background-image: var(--shimmer-bg);
  animation: shimmer 1.5s ease-in-out infinite;
}

/* Enhanced transitions */
--transition-fast: 150ms ease-out;
--transition-bounce: 400ms cubic-bezier(0.68, -0.55, 0.265, 1.55);
--transition-smooth: 250ms cubic-bezier(0.4, 0, 0.2, 1);

♿ Acessibilidade WCAG 2.1 AA ⭐ Sprint 1

// Escalabilidade controlada 0.8x - 2.0x
import { useAccessibilityScale } from '@datametria/vue-components'

const { scale, setScale } = useAccessibilityScale()
setScale(1.5) // 150% zoom

🚀 Features Completas

• ✅ Design System completo - Gradientes, bordas, dark mode
• ✅ Sistema responsivo avançado - 6 breakpoints, typography fluida
• ✅ Micro-interações modernas - Shimmer, ripple, haptic feedback
• ✅ Acessibilidade WCAG 2.1 AA - Escalabilidade controlada
• ✅ Performance otimizada - Tree-shaking, lazy loading
• ✅ TypeScript completo - 100% tipado com inferência

📊 Status Final - 100% Conformidade UX/UI ✅

🏆 4 Sprints Completos

📈 Métricas Finais

🎯 Conquistas

• ✅ 40 módulos implementados e funcionais
• ✅ 514 testes com 100% success rate
• ✅ Variants padronizados - Primary variant em todos os componentes
• ✅ Validação runtime - Warnings automáticos para variants inválidos
• ✅ Design System completo com brand colors oficiais
• ✅ Sistema responsivo avançado com 6 breakpoints
• ✅ Micro-interações modernas (shimmer, ripple, haptic)
• ✅ Acessibilidade WCAG 2.1 AA com escalabilidade controlada
• ✅ Dark mode nativo com 25+ variáveis CSS
• ✅ Performance otimizada para produção enterprise

Status: 🚀 PRONTO PARA PRODUÇÃO

📚 Documentação Completa

• 📖 README.md - Este arquivo
• 📋 CHANGELOG.md - Histórico de mudanças
• ♿ ACCESSIBILITY.md - Guia WCAG 2.1 AA
• 🎨 DESIGN-SYSTEM.md - Design tokens e uso
• 📊 PROGRESS.md - Status de implementação
• 🎓 LESSONS-LEARNED.md - Lições aprendidas
• 📦 PUBLISHING.md - Guia de publicação NPM
• 🔮 FUTURE_IMPROVEMENTS.md - Melhorias futuras

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

1. Fork o repositório
2. Crie uma branch: git checkout -b feature/nova-feature
3. Commit suas mudanças: git commit -m 'feat: adiciona nova feature'
4. Push para a branch: git push origin feature/nova-feature
5. Abra um Pull Request

Desenvolvimento Local

# Clone o repositório
git clone https://github.com/datametria/DATAMETRIA-common-libraries.git
cd DATAMETRIA-common-libraries/packages/vue-components

# Instale dependências
npm install

# Rode testes
npm test

# Build
npm run build

📄 Licença

MIT © 2025 DATAMETRIA - Vander Loto (CTO)

Versão: 1.2.0 Última Atualização: 05/11/2025 Autor: Vander Loto - CTO DATAMETRIA

👥 Equipe

• Vander Loto - CTO DATAMETRIA
• Dalila Rodrigues - Tech Lead DATAMETRIA
• Amazon Q Developer - AI-First Development (90%)
• Supervisão Humana - Validação e qualidade (10%)

🤖 AI-First Development

90% Amazon Q Developer + 10% Supervisão Humana = 100% Qualidade Enterprise

🔗 Links

• 📦 NPM Package
• 🐙 GitHub Repository
• 🌐 DATAMETRIA Website
• 💬 Discord Community

Desenvolvido com ❤️ pela equipe DATAMETRIA