winvel-ui

WinvelUI

A Vue.js UI component library built on top of PrimeVue, focusing on enhanced DataTable components with advanced filtering capabilities.

Features

• 🚀 WDataTable: Enhanced DataTable wrapper with pagination, sorting, and filtering
• 📊 WMetricCard: Beautiful metric cards for displaying statistics and KPIs
• ⚠️ WInactiveAlert: Modern alert banners for inactive/disabled items with customizable styling
• 🔍 Advanced Filters: Search, date range, boolean, select, and custom filters
• 🎯 Fluent API: Easy-to-use FilterConfigBuilder for dynamic filter configurations
• 📱 Responsive: Built with responsive design in mind
• ⚡ Performance: Optimized with debouncing and efficient rendering
• 🔗 Inertia.js Integration: Seamless integration with Laravel Inertia.js applications

Installation

npm install winvel-ui

Peer Dependencies

Make sure you have the following peer dependencies installed:

npm install vue@^3.2.0 primevue@^4.0.0 primeicons@^5.0.0

Also install Tailwind CSS and related packages:

npm install -D tailwindcss postcss autoprefixer

Tailwind CSS Configuration

Since winvel-ui uses Tailwind CSS, you must configure your consuming project's tailwind.config.js to scan the package's component files. This ensures Tailwind CSS generates all the utility classes used in winvel-ui components.

module.exports = {
  content: [
    './vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php',
    './storage/framework/views/*.php',
    './resources/views/**/*.blade.php',
    './resources/js/**/*.vue',
    // For local monorepo development
    '../packages/winvel-ui/src/**/*.{vue,js,ts,jsx,tsx}',
    // For npm package installations
    './node_modules/winvel-ui/src/**/*.{vue,js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Important: CSS is generated by your consuming project, not bundled with the package. Make sure to include the content patterns above, or Tailwind classes from winvel-ui components won't be generated.

Quick Start

<template>
  <WDataTable
    :data="users"
    :filters="filters"
    :loading="loading"
    :total="total"
    @update:filters="handleFilterUpdate"
  >
    <Column field="name" header="Name" :sortable="true" />
    <Column field="email" header="Email" />
    <Column field="created_at" header="Created" :sortable="true" />
  </WDataTable>

  <!-- Show inactive alert for disabled users -->
  <WInactiveAlert
    v-if="user.disabled"
    title="Usuário Inativo"
    description="Este usuário encontra-se atualmente inativo no sistema."
  >
    <template #cards>
      <WInactiveAlertCard
        label="Data de Desativação"
        :value="user.disabled_date"
        value-type="date"
        icon-class="CalendarTimes"
      />
      <WInactiveAlertCard
        label="Motivo"
        :value="user.disabled_reason"
        icon-class="CommentAlt"
        :multiline="true"
      />
    </template>
  </WInactiveAlert>
</template>

<script setup>
import { WDataTable, WInactiveAlert, WInactiveAlertCard } from 'winvel-ui'
import { Column } from 'primevue/column'

// Your component logic here
</script>

Components

WDataTable

Enhanced DataTable component with built-in pagination, sorting, and filtering capabilities.

WMetricCard

Beautiful metric cards for displaying statistics, KPIs, and key metrics with customizable colors, icons, and formatting.

Props:

• label (String, required): The card label/title
• value (Number|String, required): The metric value to display
• subtitle (String): Optional subtitle text
• icon (String): PrimeIcons icon class (e.g., 'pi pi-users')
• color (String): Color theme - 'blue', 'green', 'red', 'yellow', 'purple', 'indigo', 'gray'
• prefix (String): Text to prepend to the value
• suffix (String): Text to append to the value
• valueColor (String): Override value text color
• formatValue (Function): Custom formatting function for the value
• customClass (String): Additional CSS classes

Example:

<WMetricCard
  label="Current Balance"
  :value="123.5"
  icon="pi pi-wallet"
  color="blue"
  :value-color="value >= 0 ? 'green' : 'red'"
  suffix="h"
  subtitle="Bank Hours Balance"
/>

WInactiveAlert

Modern alert banner for displaying inactive/disabled items with customizable styling and color variants.

Props:

• show (Boolean): Whether to show the alert (default: true)
• title (String): The main title of the alert (default: 'Item Inativo')
• description (String): Description text below the title
• badgeText (String): Text displayed in the status badge (default: 'Inativo')
• iconClass (String): Lucide icon class for the main icon (default: 'UserTimes')
• variant (String): Color theme - 'red', 'yellow', 'orange', 'gray' (default: 'red')

Slots:

• cards: Slot for WInactiveAlertCard components

Example:

<WInactiveAlert
  title="Colaborador Inativo"
  description="Este colaborador encontra-se atualmente inativo no sistema."
  badge-text="Inativo"
  icon-class="UserTimes"
>
  <template #cards>
    <WInactiveAlertCard
      label="Data de Saída"
      :value="colaborador.data_saida"
      value-type="date"
      icon-class="CalendarTimes"
    />
    <WInactiveAlertCard
      label="Motivo da Saída"
      :value="colaborador.motivo_saida"
      icon-class="CommentAlt"
      :multiline="true"
    />
  </template>
</WInactiveAlert>

WInactiveAlertCard

Information cards designed to work within WInactiveAlert, displaying key-value pairs with icons and formatting.

Props:

• label (String, required): The label text displayed above the value
• value (String|Number|Date): The main value to display
• emptyText (String): Text to show when value is empty (default: 'Não especificado')
• iconClass (String): Lucide icon class (default: 'InfoCircle')
• multiline (Boolean): Whether this is a multiline card (affects icon alignment)
• valueType (String): Formatting type - 'text', 'date', 'datetime', 'number' (default: 'text')
• variant (String): Color theme - 'red', 'yellow', 'orange', 'gray', 'blue', 'green' (default: 'red')

Value Types:

• text: Display as-is
• date: Format as Portuguese date (e.g., "15 de janeiro de 2024")
• datetime: Format as Portuguese date and time
• number: Format with Portuguese number formatting

Example:

<!-- Date card -->
<WInactiveAlertCard
  label="Data de Saída"
  :value="new Date('2024-01-15')"
  value-type="date"
  icon-class="CalendarTimes"
/>

<!-- Text card with multiline support -->
<WInactiveAlertCard
  label="Motivo da Saída"
  value="Mudança para outra empresa devido a melhores oportunidades de carreira"
  :multiline="true"
  icon-class="CommentAlt"
/>

<!-- Number card -->
<WInactiveAlertCard
  label="Usuários Afetados"
  :value="1250"
  value-type="number"
  icon-class="Users"
/>

<!-- Empty value card -->
<WInactiveAlertCard
  label="Observações"
  :value="null"
  empty-text="Nenhuma observação"
  icon-class="StickyNote"
/>

WDataTableFilters

Dynamic filter system that works with FilterConfigBuilder for flexible filter configurations.

FilterConfigBuilder

Fluent API for building complex filter configurations:

import { FilterConfigBuilder } from 'winvel-ui'

const filterConfig = new FilterConfigBuilder()
  .search()
  .dateRange()
  .boolean('active', { label: 'Active Users' })
  .select('role', 'Role', [
    { value: 'admin', label: 'Admin' },
    { value: 'user', label: 'User' }
  ])
  .build()

Documentation

For detailed documentation and examples, visit our documentation site.

License

MIT