@kikiloaw/simple-table 1.0.0 → 1.0.2

package/README.md

@@ -212,6 +212,14 @@ const columns = [
     label: 'Email' 
   },
   
+  // Auto-numbering (row numbers instead of data)
+  {
+    key: 'id',
+    label: '#',
+    autonumber: true,
+    width: '80px'
+  },
+  
   // Sticky actions column (always visible)
   { 
     key: 'actions', 
@@ -233,6 +241,50 @@ Use custom sort keys when:
 
 ## 🎨 Features
 
+### Auto-Numbering
+
+**Display sequential row numbers instead of actual data:**
+
+```vue
+const columns = [
+  { 
+    key: 'id', 
+    label: '#', 
+    autonumber: true,
+    width: '80px'
+  },
+  // ... other columns
+]
+```
+
+**Features:**
+- ✅ Displays 1, 2, 3, 4... for each data row
+- ✅ Skips group headers (only counts data rows)
+- ✅ Pagination-aware: Page 2 shows 11, 12, 13... (with 10 per page)
+- ✅ Overrides actual column data
+- ✅ Works with both server-side and client-side modes
+
+**Example:**
+```
+┌────┬──────────────────┬─────────┐
+│ #  │ Name             │ Status  │
+├────┼──────────────────┼─────────┤
+│ ACTIVE USERS                    │ ← Header (not counted)
+│ 1  │ John Doe         │ Active  │
+│ 2  │ Jane Smith       │ Active  │
+├────┴──────────────────┴─────────┤
+│ INACTIVE USERS                  │ ← Header (not counted)
+│ 3  │ Bob Johnson      │ Inactive│
+```
+
+**Perfect for:**
+- Sequential numbering regardless of actual IDs
+- User-friendly row references
+- Tables with group headers
+- Paginated lists with continuous numbering
+
+---
+
 ### Custom Sort Keys
 
 **Problem:** You want to display `department.name` but sort by `department_id`.
@@ -263,19 +315,22 @@ const columns = [
 
 **Use Case:** Add filters like status, department, date range, etc.
 
+**Performance:** Query parameters are sent with every request but **do NOT auto-refetch**. This prevents unnecessary API calls when you have multiple filters. Call `refresh()` manually when ready.
+
 ```vue
 <script setup>
 import { ref } from 'vue'
 
+const tableRef = ref()
 const filters = ref({
   status: 'active',
   department_id: 5,
   year: 2025
 })
 
-function updateStatus(newStatus) {
-  filters.value.status = newStatus
-  // Table automatically refetches!
+function applyFilters() {
+  // After setting all filters, manually refresh
+  tableRef.value?.refresh()
 }
 </script>
 
@@ -291,10 +346,13 @@ function updateStatus(newStatus) {
       <option :value="1">IT</option>
       <option :value="5">HR</option>
     </select>
+    
+    <button @click="applyFilters" class="btn">Apply Filters</button>
   </div>
 
   <!-- Table with filters -->
   <SimpleTable 
+    ref="tableRef"
     fetch-url="/api/users"
     :columns="columns"
     :query-params="filters"
@@ -302,6 +360,8 @@ function updateStatus(newStatus) {
 </template>
 ```
 
+**Important:** Query parameters are **NOT automatically watched**. This prevents multiple API calls when you have many filters. Call `tableRef.value?.refresh()` manually when you want to refetch.
+
 **API Request:**
 ```
 GET /api/users?page=1&per_page=10&status=active&department_id=5&year=2025
@@ -379,24 +439,316 @@ function handleCreate() {
 
 ### Custom Actions and Slots
 
-**Add custom buttons to the toolbar:**
+**Add custom buttons to the toolbar with access to table data:**
 
 ```vue
-<SimpleTable :columns="columns" fetch-url="/api/users">
-  <template #actions="{ rows }">
-    <button @click="exportCustom(rows)" class="btn">
-      Custom Export
-    </button>
-    <button @click="bulkDelete(rows)" class="btn btn-danger">
-      Bulk Delete
-    </button>
-  </template>
-</SimpleTable>
+<script setup>
+import { Download, Printer, Trash } from 'lucide-vue-next'
+
+const handleExport = (type, rows) => {
+  console.log(`Exporting ${rows.length} rows as ${type}`)
+  
+  if (type === 'csv') {
+    const csv = rows.map(row => 
+      `${row.id},${row.name},${row.email}`
+    ).join('\n')
+    
+    downloadCSV(csv, 'export.csv')
+  }
+}
+
+const handleBulkDelete = (rows) => {
+  const ids = rows.map(r => r.id)
+  if (confirm(`Delete ${ids.length} items?`)) {
+    axios.delete('/api/bulk-delete', { data: { ids } })
+  }
+}
+
+const downloadCSV = (content, filename) => {
+  const blob = new Blob([content], { type: 'text/csv' })
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement('a')
+  a.href = url
+  a.download = filename
+  a.click()
+}
+</script>
+
+<template>
+  <SimpleTable :columns="columns" fetch-url="/api/users">
+    <template #actions="{ rows, columns }">
+      <Button @click="handleExport('csv', rows)">
+        <Download class="mr-2 h-4 w-4" />
+        Export ({{ rows.length }})
+      </Button>
+      
+      <Button @click="handleExport('excel', rows)">
+        <Download class="mr-2 h-4 w-4" />
+        Excel
+      </Button>
+      
+      <Button @click="handleBulkDelete(rows)" variant="destructive">
+        <Trash class="mr-2 h-4 w-4" />
+        Bulk Delete
+      </Button>
+    </template>
+  </SimpleTable>
+</template>
+```
+
+**Slot Props:**
+- **`rows`**: Currently visible table data (array of objects)
+- **`columns`**: Column definitions (array of column config)
+
+**Use Cases:**
+- ✅ Custom export buttons (CSV, Excel, PDF)
+- ✅ Bulk actions (delete, update, approve)
+- ✅ Print functionality
+- ✅ Custom filters or search
+- ✅ Integration with third-party libraries
+
+
+---
+
+### Group Headers
+
+**Organize your table data with full-width group headers:**
+
+```vue
+<script setup>
+const addGroupHeaders = (rows) => {
+  // Sort by category first
+  const sorted = [...rows].sort((a, b) => 
+    (a.category || '').localeCompare(b.category || '')
+  )
+  
+  const result = []
+  let currentCategory = null
+  
+  sorted.forEach(row => {
+    const category = row.category || 'Uncategorized'
+    
+    // When category changes, add a header row
+    if (category !== currentCategory) {
+      result.push({
+        _isGroupHeader: true,      // Special flag
+        _groupTitle: category,      // Header text
+        // Add empty values for all columns
+        ...Object.fromEntries(
+          Object.keys(row).map(key => [key, ''])
+        )
+      })
+      currentCategory = category
+    }
+    
+    result.push(row)
+  })
+  
+  return result
+}
+</script>
+
+<template>
+  <SimpleTable 
+    :columns="columns"
+    :before-render="addGroupHeaders"
+    odd-row-color="bg-gray-50"
+    even-row-color="bg-white"
+    fetch-url="/api/data"
+  />
+</template>
+```
+
+**Result:**
+```
+┌────────────────────────────────────────┐
+│ CATEGORY A                             │  ← Full-width header
+├─────┬──────────┬──────────┬────────────┤
+│ 1   │ Item 1   │ $100     │ Active     │
+│ 2   │ Item 2   │ $200     │ Active     │
+├─────┴──────────┴──────────┴────────────┤
+│ CATEGORY B                             │  ← Full-width header
+├─────┬──────────┬──────────┬────────────┤
+│ 3   │ Item 3   │ $150     │ Inactive   │
+```
+
+**How It Works:**
+1. Use `beforeRender` callback to transform data
+2. Insert rows with `_isGroupHeader: true` flag
+3. Component renders these as full-width cells with `colspan`
+4. Striping continues correctly across all rows
+
+**Grouping Examples:**
+
+```vue
+// Group by first letter
+const groupByLetter = (rows) => {
+  const sorted = [...rows].sort((a, b) => 
+    a.name.localeCompare(b.name)
+  )
+  
+  const result = []
+  let currentLetter = null
+  
+  sorted.forEach(row => {
+    const letter = row.name.charAt(0).toUpperCase()
+    
+    if (letter !== currentLetter) {
+      result.push({
+        _isGroupHeader: true,
+        _groupTitle: letter,
+      })
+      currentLetter = letter
+    }
+    
+    result.push(row)
+  })
+  
+  return result
+}
+
+// Group by date range
+const groupByDate = (rows) => {
+  const sorted = [...rows].sort((a, b) => 
+    new Date(b.created_at) - new Date(a.created_at)
+  )
+  
+  const result = []
+  let currentMonth = null
+  
+  sorted.forEach(row => {
+    const month = new Date(row.created_at).toLocaleDateString('en', { 
+      year: 'numeric', 
+      month: 'long' 
+    })
+    
+    if (month !== currentMonth) {
+      result.push({
+        _isGroupHeader: true,
+        _groupTitle: month,
+      })
+      currentMonth = month
+    }
+    
+    result.push(row)
+  })
+  
+  return result
+}
+
+// Group by status
+const groupByStatus = (rows) => {
+  const active = rows.filter(r => r.is_active)
+  const inactive = rows.filter(r => !r.is_active)
+  
+  return [
+    { _isGroupHeader: true, _groupTitle: 'Active Items' },
+    ...active,
+    { _isGroupHeader: true, _groupTitle: 'Inactive Items' },
+    ...inactive
+  ]
+}
+```
+
+**Styling Group Headers:**
+
+The component applies these classes to group header rows:
+- `border-b border-gray-200` - Bottom border
+- Font styling via the inner div
+- Row striping colors (odd-row-color / even-row-color)
+
+You can customize by overriding row colors:
+```vue
+<SimpleTable 
+  :before-render="addGroupHeaders"
+  odd-row-color="bg-blue-50"
+  even-row-color="bg-white"
+/>
+```
+
+---
+
+### Data Transformation (beforeRender)
+
+**Transform data before it's rendered in the table:**
+
+```vue
+<script setup>
+import dayjs from 'dayjs'
+
+const transformData = (rows) => {
+  return rows.map(row => ({
+    ...row,
+    // Add computed properties
+    full_name: `${row.first_name} ${row.last_name}`,
+    
+    // Format dates
+    created_at_formatted: dayjs(row.created_at).format('MMM D, YYYY'),
+    
+    // Add status badge classes
+    status_class: row.status === 'active' ? 'text-green-600' : 'text-red-600',
+    
+    // Transform arrays
+    tags_joined: row.tags?.join(', ') || 'No tags',
+    
+    // Add custom logic
+    is_urgent: row.priority > 8,
+    days_since_created: dayjs().diff(dayjs(row.created_at), 'days')
+  }))
+}
+</script>
+
+<template>
+  <SimpleTable 
+    :columns="columns" 
+    fetch-url="/api/users"
+    :before-render="transformData"
+  />
+</template>
+```
+
+**When to Use:**
+- ✅ Format dates, numbers, or currencies
+- ✅ Combine multiple fields into one
+- ✅ Add computed properties
+- ✅ Transform nested objects to flat properties
+- ✅ Add CSS classes based on data
+- ✅ Filter unwanted rows (return modified array)
+
+**Example - Adding Full Names:**
+```vue
+<script setup>
+const columns = [
+  { key: 'full_name', label: 'Name' },  // Not in API response
+  { key: 'email', label: 'Email' },
+  { key: 'created_at_formatted', label: 'Joined' }
+]
+
+const beforeRender = (rows) => {
+  return rows.map(row => ({
+    ...row,
+    full_name: `${row.first_name} ${row.last_name}`,
+    created_at_formatted: new Date(row.created_at).toLocaleDateString()
+  }))
+}
+</script>
+
+<template>
+  <SimpleTable 
+    :columns="columns" 
+    :before-render="beforeRender"
+    fetch-url="/api/users" 
+  />
+</template>
 ```
 
-**Access to:**
-- `rows`: Currently visible data
-- `columns`: Column definitions
+**Execution Order:**
+1. Data fetched from API
+2. Filtering & Searching (client-side only)
+3. Sorting (client-side only)
+4. Pagination (client-side only)
+5. **`beforeRender` called** ← Your transformation here
+6. Rows rendered in table
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kikiloaw/simple-table",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "description": "A lightweight, dependency-light DataTable component for Vue 3 with Tailwind CSS",
     "main": "src/index.js",
     "module": "src/index.js",
@@ -29,4 +29,4 @@
         "type": "git",
         "url": "git+https://github.com/kikiloaw/simple-table.git"
     }
-}
+}

package/src/SimpleTable.vue

@@ -26,6 +26,7 @@ interface Props {
     class?: string
     fixed?: boolean // 'left' or 'right' could be added later, assuming 'right' for actions usually
     width?: string
+    autonumber?: boolean // If true, display auto-incremented row numbers instead of data
   }[]
   mode?: 'auto' | 'server' | 'client'
   protocol?: 'laravel' | 'datatables' // API request/response format
@@ -34,6 +35,9 @@ interface Props {
   pageSizes?: any[] // number[] or { label: string, value: number }[]
   fetchUrl?: string
   
+  // Callbacks
+  beforeRender?: (rows: any[]) => any[] // Transform data before rendering
+  
   // Cache Props
   enableCache?: boolean // If true, cache responses by page/search/sort to avoid redundant requests
   
@@ -48,6 +52,7 @@ interface Props {
 
 const props = withDefaults(defineProps<Props>(), {
   data: () => [],
+  columns: () => [],
   mode: 'auto',
   protocol: 'laravel',
   searchable: true,
@@ -164,14 +169,6 @@ watch(() => props.data, (newVal) => {
     internalData.value = newVal
 }, { deep: true })
 
-// Watch queryParams and refetch when they change
-watch(() => props.queryParams, () => {
-    if (isServerSide.value) {
-        currentPage.value = 1 // Reset to first page when filters change
-        fetchData()
-    }
-}, { deep: true })
-
 // -- Computed: Mode Detection --
 const isServerSide = computed(() => {
   if (props.mode === 'server') return true
@@ -196,6 +193,7 @@ const serverMeta = computed(() => {
     return {
         current_page: meta.current_page ?? 1,
         last_page: meta.last_page ?? 1,
+        per_page: meta.per_page ?? currentPerPage.value,
         from: meta.from ?? 0,
         to: meta.to ?? 0,
         total: meta.total ?? 0,
@@ -205,39 +203,52 @@ const serverMeta = computed(() => {
 
 // -- Computed: Data Normalization --
 const tableData = computed(() => {
+  let result: any[] = []
+  
   if (isServerSide.value) {
     const d = internalData.value as any
-    return d.data || []
-  }
-  
-  // Client Side Processing
-  let items = [...(internalData.value as any[])]
+    result = d.data || []
+  } else {
+    // Client Side Processing
+    let items = [...(internalData.value as any[])]
 
-  // 1. Filter
-  if (searchQuery.value) {
-    const lowerQuery = searchQuery.value.toLowerCase()
-    items = items.filter((item) =>
-      Object.values(item).some((val) =>
-        String(val).toLowerCase().includes(lowerQuery)
+    // 1. Filter
+    if (searchQuery.value) {
+      const lowerQuery = searchQuery.value.toLowerCase()
+      items = items.filter((item) =>
+        Object.values(item).some((val) =>
+          String(val).toLowerCase().includes(lowerQuery)
+        )
       )
-    )
-  }
+    }
 
-  // 2. Sort
-  if (sortColumn.value) {
-    items.sort((a, b) => {
-      const valA = a[sortColumn.value]
-      const valB = b[sortColumn.value]
-      if (valA === valB) return 0
-      const comparison = valA > valB ? 1 : -1
-      return sortDirection.value === 'asc' ? comparison : -comparison
-    })
-  }
+    // 2. Sort
+    if (sortColumn.value) {
+      items.sort((a, b) => {
+        const valA = a[sortColumn.value]
+        const valB = b[sortColumn.value]
+        if (valA === valB) return 0
+        const comparison = valA > valB ? 1 : -1
+        return sortDirection.value === 'asc' ? comparison : -comparison
+      })
+    }
 
-  // 3. Paginate
-  const start = (currentPage.value - 1) * currentPerPage.value
-  const end = start + currentPerPage.value
-  return items.slice(start, end)
+    // 3. Paginate
+    const start = (currentPage.value - 1) * currentPerPage.value
+    const end = start + currentPerPage.value
+    result = items.slice(start, end)
+  }
+  
+  // Apply beforeRender callback if provided
+  if (props.beforeRender && typeof props.beforeRender === 'function') {
+    const transformed = props.beforeRender(result)
+    // Ensure callback returns an array
+    if (Array.isArray(transformed)) {
+      result = transformed
+    }
+  }
+  
+  return result
 })
 
 const totalPages = computed(() => {
@@ -539,6 +550,38 @@ function handlePageSizeChange(size: any) {
     fetchData()
 }
 
+// Get row class with simple alternating stripes (all rows)
+function getRowClass(row: any, idx: number) {
+  // Alternate: index 0 = white, index 1 = gray, index 2 = white, etc.
+  const isOdd = idx % 2 === 0  // Changed: even index = odd color (white)
+  return [
+    { [props.oddRowColor]: isOdd, [props.evenRowColor]: !isOdd },
+    row._isGroupHeader ? '' : props.hoverColor  // No hover on headers
+  ]
+}
+
+// Get row number for auto-numbering (excluding group headers)
+function getRowNumber(idx: number): number {
+  // Count only data rows before this index
+  let dataRowCount = 0
+  for (let i = 0; i <= idx; i++) {
+    if (!tableData.value[i]?._isGroupHeader) {
+      dataRowCount++
+    }
+  }
+  
+  // Add offset for pagination
+  if (isServerSide.value) {
+    const currentPage = serverMeta.value?.current_page || 1
+    const perPage = serverMeta.value?.per_page || currentPerPage.value
+    const offset = (currentPage - 1) * perPage
+    return offset + dataRowCount
+  }
+  
+  // Client-side: just return the count
+  return dataRowCount
+}
+
 function handlePageChange(page: number) {
   if (page < 1 || page > totalPages.value) return
   
@@ -713,21 +756,38 @@ function getCellStyle(col: any) {
                 v-for="(row, idx) in tableData" 
                 :key="idx"
                 class="group"
-                :class="[{ [evenRowColor]: Number(idx) % 2 === 0, [oddRowColor]: Number(idx) % 2 !== 0 }, hoverColor]"
+                :class="getRowClass(row, idx)"
             >
-              <TableCell
-                v-for="(col, cIdx) in columns"
-                :key="col.key"
-                :class="getCellClass(col, cIdx, columns.length, Number(idx))"
-                :style="getCellStyle(col)"
-              >
-                <!-- Scoped Slot for custom cell rendering -->
-                 <div>
-                    <slot :name="`cell-${col.key}`" :row="row">
-                    {{ row[col.key] }}
-                    </slot>
-                 </div>
-              </TableCell>
+              <!-- Group Header Row: Single cell spanning all columns -->
+              <template v-if="row._isGroupHeader">
+                <TableCell :colspan="columns.length" class="border-b border-gray-200">
+                  <div class="px-2 py-2 font-semibold text-gray-700 text-sm uppercase tracking-wide">
+                    {{ row._groupTitle }}
+                  </div>
+                </TableCell>
+              </template>
+              
+              <!-- Regular Data Row: Individual cells -->
+              <template v-else>
+                <TableCell
+                  v-for="(col, cIdx) in columns"
+                  :key="col.key"
+                  :class="getCellClass(col, cIdx, columns.length, idx)"
+                  :style="getCellStyle(col)"
+                >
+                  <!-- Auto-numbering or custom cell rendering -->
+                   <div>
+                      <template v-if="col.autonumber">
+                        {{ getRowNumber(idx) }}
+                      </template>
+                      <template v-else>
+                        <slot :name="`cell-${col.key}`" :row="row">
+                        {{ row[col.key] }}
+                        </slot>
+                      </template>
+                   </div>
+                </TableCell>
+              </template>
             </TableRow>
           </template>
           <TableRow v-else>