valk-ui/blade

Valk UI - Modern Blade Components Library for Laravel with Tailwind CSS

1.0.0 2025-11-24 15:35 UTC

Requires

• php: ^8.1
• illuminate/support: ^10.0|^11.0

MIT

• Fernando Forastieri

• ui
• components
• laravel
• blade
• design-system
• tailwindcss
• valk-ui

README

Biblioteca moderna de componentes UI para React e Blade (Laravel)

Documentação • Instalação • Componentes • Contribuir

✨ Características

• 🎨 Design Moderno: Componentes bonitos e consistentes com Tailwind CSS
• ⚛️ React/TypeScript: Totalmente tipado e pronto para produção
• 🔷 Blade/Laravel: Integração perfeita com Laravel e Alpine.js
• 🌙 Dark Mode: Suporte nativo a modo escuro
• 📦 CLI Interativo: Instale apenas os componentes que você precisa
• 🎯 Zero Dependências: Componentes leves e performáticos
• ♿ Acessível: Construído com acessibilidade em mente
• 🔧 Customizável: Fácil de personalizar e estender

🚀 Instalação Rápida

Usando o CLI (Recomendado)

# Instalar globalmente
npm install -g valk-ui

# Ou usar diretamente com npx
npx valk-ui

O CLI interativo permite:

• ✅ Escolher idioma (PT, EN, ES)
• ✅ Selecionar tecnologia (React ou Blade)
• ✅ Instalar por categoria ou individualmente
• ✅ Definir diretório de instalação

Instalação Manual

React/TypeScript

# Copie os componentes de packages/react/src/components
# para o seu projeto em ./src/components/ui

Blade/Laravel

# Copie os componentes de packages/blade/resources/views/components
# para o seu projeto em ./resources/views/components

📖 Documentação

Acesse a documentação completa em: https://valk-ui.dev

Ou execute localmente:

cd packages/docs
npm install
npm run dev

🎨 Componentes Disponíveis

📝 Formulários

• Button - Botões com múltiplas variantes e tamanhos
• Input - Campos de entrada com suporte a ícones e validação
• Select - Seletor customizado com busca e modo múltiplo
• Checkbox - Checkbox customizado com label e descrição
• Toggle - Switch toggle com diferentes tamanhos
• DatePicker - Seletor de data com calendário interativo

💬 Feedback

• Modal - Modal responsivo com diferentes tamanhos
• StatusBadge - Badges para indicar status
• ProgressBar - Barra de progresso com diferentes cores

📐 Layout

• Avatar - Avatar com fallback para iniciais
• MetricCard - Card para exibir métricas e KPIs
• PaginatedTable - Tabela paginada com busca e ordenação

📊 Gráficos

• BarChart - Gráfico de barras comparativo
• DonutChart - Gráfico de rosca (donut)
• LineChart - Gráfico de linha temporal

🏗️ Estrutura do Projeto

valk-ui/
├── packages/
│   ├── react/              # Componentes React/TypeScript
│   │   ├── src/
│   │   │   ├── components/  # Componentes organizados por categoria
│   │   │   │   ├── forms/
│   │   │   │   ├── feedback/
│   │   │   │   ├── layout/
│   │   │   │   └── charts/
│   │   │   └── lib/         # Utilitários (cn, etc)
│   │   └── package.json
│   ├── blade/               # Componentes Blade/Laravel
│   │   ├── resources/
│   │   │   └── views/
│   │   │       └── components/  # Componentes Blade
│   │   └── src/
│   │       └── ValkUIBladeServiceProvider.php
│   └── docs/                # Site de documentação
│       ├── src/
│       │   ├── pages/       # Páginas do site
│       │   └── components/  # Componentes do site
│       └── package.json
├── cli/                     # CLI interativo
│   ├── index.js
│   └── translations.js
└── package.json             # Workspace root

🎯 Uso Básico

React/TypeScript

import { Button, Input, Modal } from '@/components/ui'

function App() {
  return (
    <div>
      <Button variant="primary" size="lg">
        Clique aqui
      </Button>
      <Input label="Email" placeholder="[e-mail]" />
      <Modal isOpen={true} onClose={() => {}} title="Título">
        Conteúdo do modal
      </Modal>
    </div>
  )
}

Blade/Laravel

<x-forms.button variant="primary" size="lg">
    Clique aqui
</x-forms.button>

<x-forms.input label="Email" placeholder="[e-mail]" />

<x-feedback.modal isOpen="true" title="Título">
    Conteúdo do modal
</x-feedback.modal>

🛠️ Requisitos

• React: ^18.0.0
• TypeScript: ^5.0.0 (para projetos React)
• Laravel: ^9.0 (para projetos Blade)
• Tailwind CSS: ^3.0.0
• Node.js: ^18.0.0

📦 Dependências dos Componentes

React

• react ^18.0.0
• react-dom ^18.0.0
• @heroicons/react ^2.0.0 (para ícones)
• chart.js ^4.0.0 e react-chartjs-2 ^5.0.0 (para gráficos)
• clsx e tailwind-merge (para utilitários)

Blade

• laravel/framework ^9.0
• alpinejs (recomendado para interatividade)
• chart.js (para componentes de gráficos)

🤝 Contribuindo

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

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

📝 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

• Tailwind CSS - Framework CSS utilitário
• Heroicons - Ícones SVG
• Chart.js - Biblioteca de gráficos
• shadcn/ui - Inspiração para a estrutura

📧 Contato

• Website: https://valk-ui.dev
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Feito com ❤️ por Fernando Forastieri

⭐ Se este projeto foi útil para você, considere dar uma estrela!