Volcanic Super Table

A powerful, enterprise-grade data table component for Vue 3, built on AG Grid Community with full server-side support.

✨ Features

Core Functionality

• 🔄 Fully Server-Side Architecture: Built from the ground up for server-side data operations
• 📊 Dual View Modes: Seamlessly switch between Table and Card views with responsive auto-detection
• 🔍 Advanced Filtering: Column-specific filters with multiple variants (text, number, date, select, multiselect)
• 📄 Smart Pagination: Server-side pagination with customizable page sizes [25, 50, 100, 500]
• ↕️ Multi-Column Sorting: Infinite column sorting with server-side integration
• 🔎 Global Search: Debounced omni-search across all columns
• ✅ Row Selection: Single and multi-row selection with checkbox support

UI & UX

• 🎨 Flexible Filter Layout: Choose between inline floating filters or compact menu-based filters
• 📱 Responsive Design: Card view automatically activates on mobile devices
• 🌙 Dark Mode: Complete dark mode support with custom theming
• 🎯 Actions Column Helper: Built-in composable for pinned action buttons
• ⚡ Compact Headers: Optimized header design for better space utilization
• 💬 i18n Ready: Multi-language support (Italian, English) with Vue I18n

Developer Experience

• 📘 TypeScript: Fully typed with comprehensive type definitions
• 🎯 AG Grid Integration: Leverages AG Grid Community's powerful features
• 🔧 Composable API: Use useSuperTable and useActionColumn helpers
• 🎨 Tailwind CSS: Styled with Tailwind CSS v4 for easy customization

📦 Installation

npm install volcanic-super-table

## 🏗️ Component Architecture

Volcanic Super Table provides **four main components** for different usage scenarios:

### Component Hierarchy

SuperDataView (Complete UI Solution) └── SuperTableRoot (View Switching) ├── SuperGridTable (AG Grid Only) └── SuperCardGrid (Card View Only)

### When to Use Each Component

| Component | Use Case | Includes |
|-----------|----------|----------|
| **SuperDataView** | Complete data table with header, toolbar, search | ✅ Layout<br>✅ View Switching<br>✅ Grid & Card |
| **SuperTableRoot** | Responsive table with custom layout | ❌ Layout<br>✅ View Switching<br>✅ Grid & Card |
| **SuperGridTable** | AG Grid only, no mobile support | ❌ Layout<br>❌ View Switching<br>✅ Grid Only |
| **SuperCardGrid** | Card view only, mobile-first | ❌ Layout<br>❌ View Switching<br>✅ Card Only |

### Usage Examples

#### 1. Complete Solution (Recommended)

```vue
<script setup>
import { SuperDataView } from 'volcanic-super-table'
</script>

<template>
  <SuperDataView
    :data="data"
    :columns="columns"
    title="User Management"
    :enable-sorting="true"
    :enable-pagination="true"
  >
    <template #header-actions>
      <button>Add User</button>
    </template>
  </SuperDataView>
</template>

2. Custom Layout with View Switching

<script setup>
import { SuperTableRoot } from 'volcanic-super-table'
</script>

<template>
  <div class="my-custom-layout">
    <header>My Custom Header</header>
    <SuperTableRoot
      :data="data"
      :columns="columns"
      :enable-sorting="true"
    />
  </div>
</template>

3. Grid Only (No Mobile Support)

<script setup>
import { SuperGridTable } from 'volcanic-super-table'
</script>

<template>
  <div class="h-screen">
    <SuperGridTable
      :data="data"
      :columns="columns"
      :enable-sorting="true"
      :enable-pagination="true"
    />
  </div>
</template>

4. Card View Only (Mobile-First)

<script setup>
import { SuperCardGrid } from 'volcanic-super-table'
</script>

<template>
  <SuperCardGrid
    :data="data"
    :columns="columns"
    :sorting="sorting"
    @update:sorting="handleSort"
  />
</template>
</template>

🚀 Quick Start

Basic Client-Side Table

<script setup lang="ts">
import { ref } from 'vue'
import { SuperDataView } from 'volcanic-super-table'
import type { SuperTableColumn } from 'volcanic-super-table'

interface User {
  id: number
  name: string
  email: string
  role: string
  status: string
}

const data = ref<User[]>([
  { id: 1, name: 'John Doe', email: '[email protected]', role: 'Admin', status: 'Active' },
  { id: 2, name: 'Jane Smith', email: '[email protected]', role: 'User', status: 'Active' },
])

const columns: SuperTableColumn<User>[] = [
  {
    accessorKey: 'name',
    header: 'Name',
    pinned: 'left',
  },
  {
    accessorKey: 'email',
    header: 'Email',
  },
  {
    accessorKey: 'role',
    header: 'Role',
    meta: {
      filterVariant: 'select',
      filterOptions: [
        { value: 'Admin', label: 'Admin' },
        { value: 'User', label: 'User' },
      ],
    },
  },
  {
    accessorKey: 'status',
    header: 'Status',
  },
]
</script>

<template>
  <SuperDataView
    :data="data"
    :columns="columns"
    :enable-sorting="true"
    :enable-column-filters="true"
    :enable-pagination="true"
    title="User Management"
    subtitle="Manage your users"
  />
</template>

Server-Side Table with Full Control

<script setup lang="ts">
import { ref } from 'vue'
import { SuperDataView, useActionColumn } from 'volcanic-super-table'
import type { SuperTableColumn } from 'volcanic-super-table'
import IconEdit from './icons/IconEdit.vue'
import IconTrash from './icons/IconTrash.vue'

// Server-side state
const serverState = ref({
  pageIndex: 0,
  pageSize: 50,
  sorting: [] as { id: string; desc: boolean }[],
  globalFilter: '',
})

const data = ref([])
const rowCount = ref(0)
const loading = ref(false)

// Fetch data from server
const fetchData = async () => {
  loading.value = true
  try {
    const response = await fetch('/api/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(serverState.value),
    })
    const result = await response.json()
    data.value = result.data
    rowCount.value = result.total
  } finally {
    loading.value = false
  }
}

// Event handlers
const onUpdateSorting = (sorting: any) => {
  serverState.value.sorting = sorting
  serverState.value.pageIndex = 0 // Reset to first page
  fetchData()
}

const onUpdatePageIndex = (pageIndex: number) => {
  serverState.value.pageIndex = pageIndex
  fetchData()
}

const onUpdatePageSize = (pageSize: number) => {
  serverState.value.pageSize = pageSize
  serverState.value.pageIndex = 0
  fetchData()
}

const onUpdateGlobalFilter = (filter: string) => {
  serverState.value.globalFilter = filter
  serverState.value.pageIndex = 0
  fetchData()
}

// Define columns with Actions column
const columns: SuperTableColumn[] = [
  { accessorKey: 'name', header: 'Name', pinned: 'left' },
  { accessorKey: 'email', header: 'Email' },
  { accessorKey: 'role', header: 'Role' },

  // Actions column helper
  useActionColumn([
    {
      label: 'Edit',
      icon: IconEdit,
      onClick: (row: any) => editUser(row.id),
      class: 'text-blue-600 hover:bg-blue-50',
    },
    {
      label: 'Delete',
      icon: IconTrash,
      onClick: (row: any) => deleteUser(row.id),
      class: 'text-red-600 hover:bg-red-50',
    },
  ]),
]

// Initialize
onMounted(() => fetchData())
</script>

<template>
  <SuperDataView
    :data="data"
    :columns="columns"
    :row-count="rowCount"
    :page-index="serverState.pageIndex"
    :page-size="serverState.pageSize"
    :sorting="serverState.sorting"
    :global-filter="serverState.globalFilter"
    :is-loading="loading"
    :enable-sorting="true"
    :enable-pagination="true"
    :enable-column-filters="true"
    :enable-global-filter="true"
    title="Users"
    @update:sorting="onUpdateSorting"
    @update:page-index="onUpdatePageIndex"
    @update:page-size="onUpdatePageSize"
    @update:global-filter="onUpdateGlobalFilter"
  />
</template>

🎯 Key Concepts

Server-Side Architecture

Volcanic Super Table is designed for server-side data operations:

• No Client-Side State: All data operations (pagination, sorting, filtering) are controlled by props
• Event-Driven Updates: Emit events when user interacts, you fetch new data
• Total Control: You decide how to fetch, transform, and cache data
• Scalable: Handle millions of rows without performance degradation

View Modes

Three view modes available via initialViewMode prop:

• table: Always show table view (AG Grid)
• card: Always show card view (responsive grid)
• auto (default): Automatically switches based on screen size (< 768px = card)

Switch programmatically using SuperViewSwitcher component or exposed toggleViewMode() method.

Filter Layouts

Control filter UI via enableFloatingFilters prop:

• false (default): Compact headers, filters in column menu (⋮) - recommended for most use cases
• true: Floating filter row below headers (AG Grid standard)

Both options provide the same filtering functionality, only UI differs.

📚 Documentation

• Configuration Guide: Complete props and options reference
• Usage Guide: Patterns, examples, and best practices
• Component Reference: Detailed component documentation
• API Reference: Components, composables, and types
• Architecture: Technical design and internals

🛠 Development

# Install dependencies
npm install

# Run playground with live examples
npm run dev

# Type check
npm run type-check

# Lint
npm run lint

# Build library
npm run build

🔧 Technology Stack

| Technology | Purpose | | ------------------- | -------------------------------- | | AG Grid Vue 3 | Enterprise-grade table engine | | Vue 3 | Progressive JavaScript framework | | TypeScript | Type-safe development | | Tailwind CSS v4 | Utility-first styling | | Vue I18n | Internationalization | | @vueuse/core | Composition utilities |

📄 License

MIT © Volcanic Minds

🤝 Contributing

Contributions are welcome! Please see our contributing guidelines.

🆘 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions