@datametria/vue-components
Version:
DATAMETRIA Vue.js 3 Component Library with Multi-Brand Theming - 51 components + 10 composables with theming support, WCAG 2.2 AA, dark mode, responsive system
595 lines (465 loc) • 16.6 kB
Markdown
# @datametria/vue-components
<div align="center">
## Vue.js Component Library com Sistema de Theming Multi-Brand/Multi-Tenant
[](https://github.com/datametria/DATAMETRIA-common-libraries/actions)
[](https://github.com/datametria/DATAMETRIA-common-libraries)
[](LICENSE)
[](https://www.npmjs.com/package/@datametria/vue-components)
[](https://vuejs.org/)
[](https://www.typescriptlang.org/)
[](https://github.com/datametria/DATAMETRIA-common-libraries)
[](https://aws.amazon.com/q/)
[🚀 Demo](https://datametria.github.io/vue-components) • [📖 Documentação](../../docs/) • [🐛 Reportar Bug](https://github.com/datametria/DATAMETRIA-common-libraries/issues) •
[💡 Solicitar Feature](https://github.com/datametria/DATAMETRIA-common-libraries/issues/new) • [🔄 Migration Guide](../../docs/theming/migration-guide.md)
</div>
**Versão**: 2.3.0
**Data**: 27/11/2025
**Autor**: Vander Loto - CTO DATAMETRIA
---
## 📋 Índice
- [Sobre o Projeto](#sobre-o-projeto)
- [Novidades v2.0](#novidades-v20)
- [Instalação](#instalação)
- [Uso Básico](#uso-básico)
- [Sistema de Theming](#sistema-de-theming)
- [Componentes Disponíveis](#componentes-disponíveis)
- [Características](#características)
- [Documentação](#documentação)
- [Migração v1.x → v2.0](#migração-v1x--v20)
- [Desenvolvimento](#desenvolvimento)
- [Métricas](#métricas)
- [Suporte](#suporte)
- [Licença](#licença)
---
## 🎯 Sobre o Projeto
### Visão Geral
Biblioteca completa de componentes Vue.js 3 com suporte a **theming multi-brand/multi-tenant**, design system DATAMETRIA e compliance WCAG 2.1 AA. Desenvolvida com foco em reutilização, qualidade e performance.
### Objetivos
- **🎨 Theming Flexível**: Sistema multi-brand/multi-tenant com CSS Variables
- **📱 Backward Compatible**: 100% compatível com v1.x
- **⚡ Performance**: Zero overhead, bundle otimizado
- **♿ Acessibilidade**: WCAG 2.1 AA compliant
- **🧪 Qualidade**: 98.2% cobertura de testes
### Benefícios
- ✅ **51 Componentes**: Com theming integrado
- ✅ **10 Composables**: Hooks reutilizáveis
- ✅ **TypeScript**: Type safety completo
- ✅ **Responsive**: Mobile-first design
- ✅ **Dark Mode**: Suporte nativo
- ✅ **Tree Shaking**: Bundle otimizado
---
## 🌟 Novidades v2.0
### Sistema de Theming Multi-Brand/Multi-Tenant
- 🎨 **ThemeProvider**: Componente para gerenciar temas
- 🔄 **CSS Variables**: Tokens customizáveis com fallback automático
- 🎯 **useTheme**: Composable para acessar tema
- 🏢 **Multi-Tenant**: Suporte a múltiplas marcas simultaneamente
- 📱 **Backward Compatible**: 100% compatível com v1.x
### Novidades v2.3.0
- 🚀 **3 Novos Componentes de Feedback e Navegação**
- DatametriaDropdown: Menu dropdown com triggers (click/hover/contextmenu) e nested menus
- DatametriaEmpty: Estado vazio com 3 imagens SVG padrão (no-data, no-results, error)
- DatametriaTree: Árvore hierárquica com expand/collapse e checkbox selection
- 92 testes unitários (100% pass rate)
- Coverage média: 94.72% statements, 88.86% branches
- Sprint 19: 100% completo (4/4 componentes)
### Novidades v2.2.0
- 🔍 **Filtros Avançados DatametriaSortableTable**
- 4 tipos de filtro: text, date, select, multiselect
- filterOptions: 'auto' para geração automática
- Detecção automática de Date objects
- Correção: espaços no filtro de texto
### Novidades v2.1.0
- 🏗️ **Novos Componentes de Navegação**
- DatametriaSidebar: Sidebar lateral com colapso
- DatametriaFloatingBar: Barra flutuante para ações rápidas
- ⬆️ **DatametriaTabs Melhorado**
- Variantes: default, pills, underline
- Orientação: horizontal e vertical
- Ícones, badges e tabs desabilitáveis
- 🧪 **Testes**: +62 testes (100% coverage)
- 📚 **Documentação**: 3 novos guias completos
---
## 📦 Instalação
### NPM
```bash
npm install @datametria/vue-components@latest
```
### Yarn
```bash
yarn add @datametria/vue-components@latest
```
### PNPM
```bash
pnpm add @datametria/vue-components@latest
```
### Pré-requisitos
- **Vue.js**: 3.3+
- **Node.js**: 18+
- **TypeScript**: 5.3+ (opcional, mas recomendado)
---
## 🚀 Uso Básico
### Importar CSS
```typescript
// main.ts ou main.js
import '@datametria/vue-components/style.css'
```
### Sem Theming (v1.x compatível)
```vue
<template>
<div>
<DatametriaButton variant="primary">Botão Padrão</DatametriaButton>
<DatametriaCard>
<h3>Card Padrão</h3>
<p>Usando design system DATAMETRIA.</p>
</DatametriaCard>
</div>
</template>
<script setup lang="ts">
import { DatametriaButton, DatametriaCard } from '@datametria/vue-components'
import '@datametria/vue-components/style.css'
</script>
```
### Com Theming (v2.0)
```vue
<template>
<ThemeProvider :theme="meuTema">
<div>
<DatametriaButton variant="primary">Botão Customizado</DatametriaButton>
<DatametriaCard>
<h3>Card Customizado</h3>
<p>Usando tema personalizado.</p>
</DatametriaCard>
</div>
</ThemeProvider>
</template>
<script setup lang="ts">
import { ThemeProvider, DatametriaButton, DatametriaCard } from '@datametria/vue-components'
import type { Theme } from '@datametria/vue-components'
const meuTema: Theme = {
name: 'Minha Empresa',
tokens: {
colors: {
primary: '#ff6b35',
secondary: '#004e89',
success: '#22c55e',
warning: '#eab308',
error: '#ef4444',
info: '#3b82f6',
neutral: {
50: '#f8fafc',
100: '#f1f5f9',
200: '#e2e8f0',
300: '#cbd5e1',
400: '#94a3b8',
500: '#64748b',
600: '#475569',
700: '#334155',
800: '#1e293b',
900: '#0f172a'
}
},
typography: {
fontFamily: {
sans: 'Inter, sans-serif',
mono: 'JetBrains Mono, monospace'
},
fontSize: {
xs: '0.75rem',
sm: '0.875rem',
base: '1rem',
lg: '1.125rem',
xl: '1.25rem',
'2xl': '1.5rem'
},
fontWeight: {
normal: 400,
medium: 500,
semibold: 600,
bold: 700
},
lineHeight: {
tight: 1.25,
normal: 1.5,
relaxed: 1.75
}
},
spacing: {
0: '0',
1: '0.25rem',
2: '0.5rem',
3: '0.75rem',
4: '1rem',
6: '1.5rem',
8: '2rem',
12: '3rem',
16: '4rem'
},
radius: {
none: '0',
sm: '0.25rem',
md: '0.375rem',
lg: '0.5rem',
full: '9999px'
},
shadows: {
sm: '0 1px 2px 0 rgba(0, 0, 0, 0.05)',
md: '0 4px 6px -1px rgba(0, 0, 0, 0.1)',
lg: '0 10px 15px -3px rgba(0, 0, 0, 0.1)',
xl: '0 20px 25px -5px rgba(0, 0, 0, 0.1)'
},
transitions: {
fast: '150ms ease',
base: '250ms ease',
slow: '350ms ease'
}
}
}
</script>
```
---
## 🎨 Sistema de Theming
### useTheme Composable
```vue
<template>
<div>
<h1 :style="{ color: theme.tokens.colors.primary }">
Título com cor do tema
</h1>
<p>Tema atual: {{ theme.name }}</p>
</div>
</template>
<script setup lang="ts">
import { useTheme } from '@datametria/vue-components'
const theme = useTheme()
</script>
```
### Temas Pré-definidos
```vue
<script setup lang="ts">
import {
ThemeProvider,
datametriaTheme,
defaultTheme
} from '@datametria/vue-components'
// Usar tema DATAMETRIA (padrão)
const tema = datametriaTheme
// Ou tema genérico
const tema = defaultTheme
</script>
```
### Multi-Tenant
```vue
<template>
<div>
<select v-model="tenantAtual">
<option value="datametria">DATAMETRIA</option>
<option value="clienteA">Cliente A</option>
<option value="clienteB">Cliente B</option>
</select>
<ThemeProvider :theme="temas[tenantAtual]">
<MeuApp />
</ThemeProvider>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue'
import { datametriaTheme } from '@datametria/vue-components'
const tenantAtual = ref('datametria')
const temas = {
datametria: datametriaTheme,
clienteA: clienteATheme,
clienteB: clienteBTheme
}
</script>
```
---
## 📚 Componentes Disponíveis
### Forms & Inputs (13 componentes)
- `DatametriaButton` - Botão com múltiplas variações + theming
- `DatametriaInput` - Input com validação + theming
- `DatametriaPasswordInput` - Input de senha com força + theming
- `DatametriaSelect` - Select customizável + theming
- `DatametriaCheckbox` - Checkbox estilizado + theming
- `DatametriaRadio` - Radio button + theming
- `DatametriaSwitch` - Toggle switch + theming
- `DatametriaTextarea` - Textarea redimensionável + theming
- `DatametriaDatePicker` - Seletor de data + theming
- `DatametriaTimePicker` - Seletor de hora + theming
- `DatametriaSlider` - Slider de valores + theming
- `DatametriaFileUpload` - Upload de arquivos + theming
- `DatametriaAutocomplete` - Busca com autocomplete + theming
### Layout & Navigation (5 componentes)
- `DatametriaCard` - Card container + theming
- `DatametriaModal` - Modal dialog + theming
- `DatametriaContainer` - Container responsivo + theming
- `DatametriaGrid` - Sistema de grid + theming
- `DatametriaDivider` - Divisor visual + theming
### Feedback (6 componentes)
- `DatametriaAlert` - Alertas contextuais + theming
- `DatametriaToast` - Notificações toast + theming
- `DatametriaTooltip` - Tooltip informativo + theming
- `DatametriaSkeleton` - Loading skeleton + theming
- `DatametriaProgress` - Barra de progresso + theming
- `DatametriaSpinner` - Loading spinner + theming
### Data Display (6 componentes)
- `DatametriaTable` - Tabela básica + theming
- `DatametriaSortableTable` - Tabela com ordenação e filtros avançados + theming ✨ **MELHORADO v2.2**
- `DatametriaAvatar` - Avatar de usuário + theming
- `DatametriaBadge` - Badge de status + theming
- `DatametriaChip` - Chip removível + theming
- `DatametriaTree` - Árvore hierárquica + theming ✨ **NOVO v2.3**
### Feedback & Empty States (2 componentes)
- `DatametriaEmpty` - Estado vazio com imagens padrão + theming ✨ **NOVO v2.3**
- `DatametriaResult` - Resultado de operações + theming
### Navigation (7 componentes)
- `DatametriaNavbar` - Barra de navegação + theming
- `DatametriaSidebar` - Sidebar lateral com colapso + theming ✨ **NOVO v2.1**
- `DatametriaFloatingBar` - Barra flutuante para ações + theming ✨ **NOVO v2.1**
- `DatametriaMenu` - Menu dropdown + theming
- `DatametriaBreadcrumb` - Navegação breadcrumb + theming
- `DatametriaTabs` - Abas navegáveis (melhorado v2.1) + theming
- `DatametriaDropdown` - Menu dropdown com triggers + theming ✨ **NOVO v2.3**
### Theming System (3 componentes)
- `ThemeProvider` - Provider de tema
- `useTheme` - Composable para acessar tema
- Presets: `datametriaTheme`, `defaultTheme`
**Total: 51 componentes + 10 composables**
---
## 🎯 Características
### ✅ Theming v2.0
- **Multi-Brand**: Suporte a múltiplas marcas
- **Multi-Tenant**: Múltiplos tenants simultaneamente
- **CSS Variables**: Tokens customizáveis
- **Fallback Values**: Funciona sem ThemeProvider
- **Performance**: Zero overhead
### ✅ Qualidade
- **TypeScript**: Type safety completo
- **WCAG 2.1 AA**: Compliance de acessibilidade
- **Responsive**: Mobile-first design
- **Dark Mode**: Suporte nativo
- **98.2% Coverage**: Testes automatizados
### ✅ Developer Experience
- **Composition API**: Vue 3 nativo
- **Tree Shaking**: Bundle otimizado
- **Hot Reload**: Desenvolvimento rápido
- **Storybook**: Documentação interativa
---
## 📖 Documentação
### Guias de Theming
- **[Getting Started](../../docs/theming/getting-started.md)** - Introdução ao sistema
- **[Creating Themes](../../docs/theming/creating-themes.md)** - Criar temas customizados
- **[Multi-Tenant](../../docs/theming/multi-tenant.md)** - Sistema multi-tenant
- **[Migration Guide](../../docs/theming/migration-guide.md)** - Migração v1 → v2
### Exemplos
- **[Multi-Tenant App](../../examples/multi-tenant/)** - Aplicação demo
- **[Storybook Setup](../../docs/tools/storybook-setup.md)** - Configuração Storybook
### API Reference
- **[Components API](../../docs/api/)** - Referência completa de componentes
- **[Theming API](../../docs/api/theming.md)** - API do sistema de theming
- **[Types](../../docs/api/types.md)** - Interfaces TypeScript
---
## 🔄 Migração v1.x → v2.0
### Compatibilidade
- ✅ **100% Backward Compatible**: Código v1.x funciona sem mudanças
- ✅ **Opt-in Theming**: ThemeProvider é opcional
- ✅ **Zero Breaking Changes**: Sem quebras de API
### Migração Gradual
```vue
<!-- v1.x - Continua funcionando -->
<DatametriaButton variant="primary">Botão</DatametriaButton>
<!-- v2.0 - Com theming (opcional) -->
<ThemeProvider :theme="meuTema">
<DatametriaButton variant="primary">Botão</DatametriaButton>
</ThemeProvider>
```
Consulte o **[Migration Guide](../../docs/theming/migration-guide.md)** para instruções detalhadas.
---
## 🛠️ Desenvolvimento
### Scripts
```bash
# Desenvolvimento
npm run dev
# Build
npm run build
# Testes
npm run test
npm run test:coverage
# Linting
npm run lint
npm run type-check
```
### Estrutura
```
src/
├── components/ # 32 componentes
├── composables/ # 10 composables
├── theme/ # Sistema de theming (novo!)
│ ├── ThemeProvider.vue
│ ├── useTheme.ts
│ ├── types.ts
│ ├── presets/
│ └── tokens/
├── types/ # Tipos TypeScript
└── index.ts # Exports principais
```
### Contribuindo
1. Fork o projeto
2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
4. Push para a branch (`git push origin feature/AmazingFeature`)
5. Abra um Pull Request
---
## 📊 Métricas
### Performance
- **Bundle Size**: ~45KB (gzipped)
- **Render Time**: < 100ms
- **Theme Switch**: < 50ms
- **Tree Shaking**: Suporte completo
### Qualidade
- **Componentes**: 51 com theming
- **Composables**: 10 hooks reutilizáveis
- **Cobertura**: 98.2% testes
- **TypeScript**: 100% tipado com arquivos .d.ts
- **Acessibilidade**: WCAG 2.1 AA
### Compatibilidade
- **Vue.js**: 3.3+
- **Browsers**: Chrome 90+, Firefox 88+, Safari 14+
- **Node.js**: 18+
- **TypeScript**: 5.3+
---
## 📞 Suporte
### Canais de Suporte
- **📧 Email**: suporte@datametria.io
- **💬 Discord**: [discord.gg/kKYGmCC3](https://discord.gg/kKYGmCC3)
- **🐛 Issues**: [GitHub Issues](https://github.com/datametria/DATAMETRIA-common-libraries/issues)
- **📖 Docs**: [Documentação Completa](../../docs/)
### Recursos Úteis
- **[Theming Documentation](../../docs/theming/getting-started.md)** - Documentação completa
- **[Migration Guide](../../docs/theming/migration-guide.md)** - Guia de migração
- **[Multi-Tenant Example](../../examples/multi-tenant/)** - Exemplo prático
- **[Storybook Setup](../../docs/tools/storybook-setup.md)** - Configuração Storybook
---
## 📄 Licença
Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.
### Resumo da Licença
- ✅ **Uso Comercial**: Permitido
- ✅ **Modificação**: Permitida
- ✅ **Distribuição**: Permitida
- ✅ **Uso Privado**: Permitido
---
## 🙏 Agradecimentos
### Equipe DATAMETRIA
- **Vander Loto** - CTO, Arquitetura e Implementação
- **Marcelo Cunha** - CEO, Visão Estratégica
- **Dalila Rodrigues** - Tech Lead, Qualidade e Supervisão
### Tecnologias
- **Vue.js Team** - Framework incrível
- **TypeScript Team** - Type safety excepcional
- **Amazon Q Developer** - 90% da implementação automatizada
---
<div align="center">
**Desenvolvido com ❤️ pela equipe DATAMETRIA**
⭐ **Se este projeto te ajudou, considere dar uma estrela!** ⭐
</div>