@kikiloaw/simple-table 1.0.2 → 1.0.4

package/README.md

@@ -87,6 +87,307 @@ public function getData(Request $request)
 
 ---
 
+## 📦 Using Predefined/Static Data
+
+**Want to use static data instead of an API?** SimpleTable handles this perfectly in client-side mode!
+
+### Basic Setup
+
+```vue
+<script setup lang="ts">
+import SimpleTable from '@kikiloaw/simple-table'
+
+// Define your static data
+const data = [
+  { id: 1, name: 'John Doe', email: 'john@example.com', status: 'active' },
+  { id: 2, name: 'Jane Smith', email: 'jane@example.com', status: 'active' },
+  { id: 3, name: 'Bob Johnson', email: 'bob@example.com', status: 'inactive' },
+  // ... more rows
+]
+
+const columns = [
+  { key: 'id', label: '#', sortable: true, width: '80px' },
+  { key: 'name', label: 'Name', sortable: true },
+  { key: 'email', label: 'Email', sortable: true },
+  { key: 'status', label: 'Status', width: '120px' }
+]
+
+const pageSizes = [
+  { label: '50 Rows', value: 50 },
+  { label: '100 Rows', value: 100 },
+]
+</script>
+
+<template>
+  <SimpleTable 
+    :data="data"
+    :columns="columns" 
+    :page-sizes="pageSizes"
+    :per-page="50"
+    mode="client"
+    searchable
+  />
+</template>
+```
+
+### Key Props for Static Data
+
+| Prop | Required | Default | Description |
+|------|----------|---------|-------------|
+| `:data` | **Yes** | `[]` | Your static array of objects |
+| `mode` | **Yes** | `'auto'` | Set to `"client"` for static data |
+| `:per-page` | Recommended | `10` | Initial page size (should match first option in pageSizes) |
+| `:page-sizes` | Optional | `[10,20,30,50,100]` | Available page size options |
+
+### ⚠️ Common Pitfalls
+
+#### 1. **Don't Mix Static Data with `fetch-url`**
+
+❌ **Wrong:**
+```vue
+<!-- This will ignore your static data! -->
+<SimpleTable 
+  :data="myData"
+  fetch-url="/api/users"  <!-- ❌ Conflicts with :data -->
+/>
+```
+
+✅ **Correct:**
+```vue
+<!-- Remove fetch-url when using static data -->
+<SimpleTable 
+  :data="myData"
+  mode="client"
+/>
+```
+
+#### 2. **Set Initial Page Size to Match Your Options**
+
+❌ **Wrong:**
+```vue
+<!-- Component defaults to 10, but you only have 50/100 options -->
+<SimpleTable 
+  :data="data"
+  :page-sizes="[{ label: '50 Rows', value: 50 }, { label: '100 Rows', value: 100 }]"
+  <!-- ❌ Will show "10 Rows" which doesn't exist in dropdown -->
+/>
+```
+
+✅ **Correct:**
+```vue
+<SimpleTable 
+  :data="data"
+  :page-sizes="[50, 100]"
+  :per-page="50"  <!-- ✅ Matches first option -->
+/>
+```
+
+#### 3. **Columns Must Match Your Data Structure**
+
+❌ **Wrong:**
+```vue
+<script setup>
+const data = [
+  { CourseCode: 'CS101', Description: 'Intro to CS', Units: 3 }
+]
+
+const columns = [
+  { key: 'course_code', label: 'Code' },  // ❌ Wrong key!
+  { key: 'description', label: 'Name' },  // ❌ Wrong key!
+]
+</script>
+```
+
+✅ **Correct:**
+```vue
+<script setup>
+const data = [
+  { CourseCode: 'CS101', Description: 'Intro to CS', Units: 3 }
+]
+
+const columns = [
+  { key: 'CourseCode', label: 'Code' },    // ✅ Matches data
+  { key: 'Description', label: 'Name' },   // ✅ Matches data
+  { key: 'Units', label: 'Units' },
+]
+</script>
+```
+
+### Features Available in Client-Side Mode
+
+✅ **Works:**
+- Client-side searching (filters through your data array)
+- Client-side sorting (by sortable columns)
+- Client-side pagination (chunks your data into pages)
+- Data transformation via `beforeRender`
+- Custom cell rendering
+- Group headers
+- Auto-numbering
+
+❌ **Not Available:**
+- Server-side sorting (data is sorted locally)
+- API caching (no API calls)
+- Query parameters (no server to send them to)
+
+### Complete Example with Group Headers
+
+```vue
+<script setup lang="ts">
+import SimpleTable from '@kikiloaw/simple-table'
+
+// Static course data
+const data = [
+  { 
+    CourseCode: 'CS101', 
+    Description: 'Intro to Computer Science', 
+    Units: 3,
+    Grade: 'A',
+    semester: '1st Semester, 2023-2024'
+  },
+  { 
+    CourseCode: 'MATH101', 
+    Description: 'Calculus I', 
+    Units: 4,
+    Grade: 'B+',
+    semester: '1st Semester, 2023-2024'
+  },
+  { 
+    CourseCode: 'CS102', 
+    Description: 'Data Structures', 
+    Units: 3,
+    Grade: 'A-',
+    semester: '2nd Semester, 2023-2024'
+  },
+]
+
+const columns = [
+  { key: 'CourseCode', label: 'Course Code', sortable: true, width: '150px' },
+  { key: 'Description', label: 'Description', sortable: true, width: '300px' },
+  { key: 'Units', label: 'Units', width: '80px' },
+  { key: 'Grade', label: 'Grade', sortable: true, width: '80px' },
+]
+
+// Add group headers by semester
+const addGroupHeaders = (rows) => {
+  // DON'T sort here if your data is already in the correct order!
+  // Sorting will override your predefined order
+  
+  const result = []
+  let currentSemester = null
+  
+  rows.forEach(row => {
+    const semester = row.semester || 'No Semester'
+    
+    // When semester changes, add a header row
+    if (semester !== currentSemester) {
+      result.push({
+        _isGroupHeader: true,
+        _groupTitle: semester,
+        // Empty values for all columns
+        CourseCode: '',
+        Description: semester,
+        Units: '',
+        Grade: '',
+      })
+      currentSemester = semester
+    }
+    
+    result.push(row)
+  })
+  
+  return result
+}
+</script>
+
+<template>
+  <SimpleTable 
+    :data="data"
+    :columns="columns" 
+    :page-sizes="[50, 100]"
+    :per-page="50"
+    :before-render="addGroupHeaders"
+    mode="client"
+    searchable
+    odd-row-color="bg-gray-50"
+    even-row-color="bg-white"
+    hover-color="hover:bg-green-100"
+  />
+</template>
+
+### 📏 Row Height Control
+
+Control the exact height of your table rows with the `rowHeight` prop:
+
+```vue
+<template>
+  <SimpleTable 
+    :data="data"
+    :columns="columns"
+    :row-height="38"  <!-- Rows will be exactly 38px tall -->
+  />
+</template>
+```
+
+**How it works:**
+- Sets the `height` style on both header and data rows
+- Automatically adjusts cell padding based on the height
+- Default: `38px` (compact and readable)
+
+**Recommended Values:**
+
+| Height | Padding | Use Case |
+|--------|---------|----------|
+| `30-36px` | `p-2` (8px) | **Extra compact** - Maximum rows visible, dense data |
+| `38-42px` | `p-2` (8px) | **Standard** - Good balance (default: 38px) |
+| `44-55px` | `p-3` (12px) | **Comfortable** - Easy to read, spacious |
+| `56px+` | `p-4` (16px) | **Very spacious** - Accessibility-friendly, large text |
+
+**Examples:**
+
+```vue
+<!-- Ultra compact for dashboards -->
+<SimpleTable :row-height="32" />
+
+<!-- Default - balanced -->
+<SimpleTable :row-height="38" />  <!-- or omit for default -->
+
+<!-- Comfortable reading -->
+<SimpleTable :row-height="48" />
+
+<!-- Accessibility-friendly -->
+<SimpleTable :row-height="60" />
+
+<!-- No prop = uses default 38px -->
+<SimpleTable :data="data" :columns="columns" />
+```
+
+**Padding Auto-Adjustment:**
+
+The component automatically adjusts internal padding:
+- **< 44px**: Uses `p-2` (8px) - Compact
+- **44-55px**: Uses `p-3` (12px) - Normal  
+- **56px+**: Uses `p-4` (16px) - Comfortable
+
+### 💡 Best Practices
+
+1. **Data Order Preservation**
+   - If your data is already sorted correctly, **don't sort it again** in `beforeRender`
+   - Let users sort by clicking column headers if needed
+
+2. **Performance**
+   - Client-side mode works great for **< 1,000 rows**
+   - For larger datasets, consider server-side mode with `fetch-url`
+
+3. **Reactivity**
+   - Use `ref()` or `reactive()` if your data changes
+   - The table will automatically update when data changes
+
+4. **Page Size Options**
+   - Keep options reasonable: `[10, 25, 50, 100]`
+   - Set `:per-page` to match your first option
+
+---
+
 ## 📖 Table of Contents
 
 - [Core Concepts](#-core-concepts)
@@ -754,28 +1055,73 @@ const beforeRender = (rows) => {
 
 ### Custom Cell Rendering
 
-**Customize how data is displayed in specific columns:**
+**Customize how data is displayed in any column using named slots.**
+
+**Slot Syntax:** `#cell-{columnKey}="{ row }"`
+
+#### 1. Conditional Styling & Badges
 
 ```vue
-<SimpleTable :columns="columns" fetch-url="/api/users">
-  <!-- Custom status badge -->
-  <template #cell-status="{ row }">
+<SimpleTable :columns="columns" :data="data">
+  <!-- Status Badge with Conditional Color -->
+  <template #cell-is_active="{ row }">
     <span 
-      :class="row.status === 'active' ? 'badge-success' : 'badge-danger'"
+      v-if="!row._isGroupHeader"
+      :class="row.is_active ? 'text-green-600 font-bold' : 'text-red-600'"
     >
-      {{ row.status }}
+      {{ row.is_active ? 'Active' : 'Inactive' }}
     </span>
   </template>
-  
-  <!-- Custom actions column -->
+</SimpleTable>
+```
+
+#### 2. Rendering Lists/Tags
+
+```vue
+<SimpleTable :columns="columns" :data="data">
+  <!-- Loop through array data in a cell -->
+  <template #cell-tags="{ row }">
+    <div v-if="!row._isGroupHeader" class="flex gap-1 flex-wrap">
+      <span 
+        v-for="tag in row.tags" 
+        :key="tag.id"
+        class="bg-blue-100 text-blue-800 text-xs px-2 py-0.5 rounded"
+      >
+        {{ tag.name }}
+      </span>
+    </div>
+  </template>
+</SimpleTable>
+```
+
+#### 3. Action Buttons
+
+```vue
+<SimpleTable :columns="columns" :data="data">
   <template #cell-actions="{ row }">
-    <button @click="edit(row)" class="btn-sm">Edit</button>
-    <button @click="delete(row)" class="btn-sm btn-danger">Delete</button>
+    <div v-if="!row._isGroupHeader" class="flex gap-2">
+      <Button variant="outline" size="sm" @click="edit(row)">Edit</Button>
+      <Button variant="destructive" size="sm" @click="remove(row)">Delete</Button>
+    </div>
   </template>
 </SimpleTable>
 ```
 
-**Slot Naming:** `#cell-{columnKey}`
+#### ⚠️ Important: Handling Group Headers
+
+If you use **Group Headers**, your custom slots will technically be available for the header row too (though hidden by the colspan). To avoid errors accessing properties that don't exist on the header row, **always check `!row._isGroupHeader`**.
+
+```vue
+<template #cell-price="{ row }">
+  <!-- ❌ Bad: Might crash on header row where row.price is undefined -->
+  ${{ row.price.toFixed(2) }}
+  
+  <!-- ✅ Good: Safe check -->
+  <span v-if="!row._isGroupHeader">
+    ${{ row.price?.toFixed(2) }}
+  </span>
+</template>
+```
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kikiloaw/simple-table",
-    "version": "1.0.2",
+    "version": "1.0.4",
     "description": "A lightweight, dependency-light DataTable component for Vue 3 with Tailwind CSS",
     "main": "src/index.js",
     "module": "src/index.js",

package/src/SimpleTable.vue

@@ -45,6 +45,7 @@ interface Props {
   queryParams?: Record<string, any> // Additional parameters to send with every request (e.g., filters, user context)
   
   // Style Props
+  rowHeight?: number // Table row height in pixels (default: 38)
   oddRowColor?: string  // Tailwind color class, e.g. 'bg-white'
   evenRowColor?: string // Tailwind color class, e.g. 'bg-gray-50'
   hoverColor?: string   // Tailwind color class for hover, e.g. 'hover:bg-gray-100'. If passed, we'll try to apply group-hover for fixed cols.
@@ -60,6 +61,7 @@ const props = withDefaults(defineProps<Props>(), {
   queryParams: () => ({}),
   perPage: 10,
   pageSizes: () => [10, 20, 30, 50, 100],
+  rowHeight: 38,
   oddRowColor: 'bg-background',
   evenRowColor: 'bg-background',
   hoverColor: 'hover:bg-muted/50'
@@ -88,6 +90,37 @@ const normalizedPageSizes = computed(() => {
     return []
 })
 
+// -- Computed: Row height-based sizing --
+const densityConfig = computed(() => {
+  const height = props.rowHeight || 38
+  
+  // Calculate padding based on height
+  // For 38px height: use p-2 (8px)
+  // For 48px height: use p-3 (12px)  
+  // For 56px+ height: use p-4 (16px)
+  let cellPadding = 'p-2'
+  let headerPadding = 'px-2'
+  let groupHeaderPadding = 'py-1'
+  
+  if (height >= 56) {
+    cellPadding = 'p-4'
+    headerPadding = 'px-4'
+    groupHeaderPadding = 'py-2'
+  } else if (height >= 44) {
+    cellPadding = 'p-3'
+    headerPadding = 'px-3'
+    groupHeaderPadding = 'py-1.5'
+  }
+  
+  return {
+    cellPadding,
+    cellHeight: `${height}px`,
+    headerHeight: `h-[${height}px]`,
+    headerPadding,
+    groupHeaderPadding
+  }
+})
+
 
 
 // <template>
@@ -722,12 +755,14 @@ function getCellStyle(col: any) {
       <!-- We add min-w-full to Table to ensure it stretches -->
       <Table class="min-w-full table-fixed"> 
         <TableHeader>
-          <TableRow>
+          <TableRow :style="{ height: densityConfig.cellHeight }">
             <TableHead
               v-for="(col, idx) in columns"
               :key="col.key"
               :class="getCellClass(col, idx, columns.length)"
               :style="getCellStyle(col)"
+              :height="densityConfig.headerHeight"
+              :padding="densityConfig.headerPadding"
             >
               <div
                 v-if="col.sortable"
@@ -757,11 +792,12 @@ function getCellStyle(col: any) {
                 :key="idx"
                 class="group"
                 :class="getRowClass(row, idx)"
+                :style="{ height: densityConfig.cellHeight }"
             >
               <!-- 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">
+                  <div :class="['px-2', densityConfig.groupHeaderPadding, 'font-semibold text-gray-700 text-sm uppercase tracking-wide']">
                     {{ row._groupTitle }}
                   </div>
                 </TableCell>
@@ -774,6 +810,8 @@ function getCellStyle(col: any) {
                   :key="col.key"
                   :class="getCellClass(col, cIdx, columns.length, idx)"
                   :style="getCellStyle(col)"
+                  :padding="densityConfig.cellPadding"
+                  :height="densityConfig.cellHeight"
                 >
                   <!-- Auto-numbering or custom cell rendering -->
                    <div>
@@ -790,7 +828,7 @@ function getCellStyle(col: any) {
               </template>
             </TableRow>
           </template>
-          <TableRow v-else>
+          <TableRow v-else :style="{ height: densityConfig.cellHeight }">
             <TableCell :colspan="columns.length" class="h-24 text-center">
               No results.
             </TableCell>

package/src/components/table/TableCell.vue

@@ -4,18 +4,29 @@ import { cn } from '@/lib/utils'
 
 const props = defineProps<{
   class?: HTMLAttributes['class']
+  style?: any
+  padding?: string
+  height?: string
 }>()
 
 const delegatedProps = computed(() => {
-  const { class: _, ...delegated } = props
+  const { class: _, padding: __, height: ___, style: ____, ...delegated } = props
 
   return delegated
 })
+
+const cellStyle = computed(() => {
+  const baseStyle = (props as any).style || {}
+  const heightStyle = props.height ? { minHeight: props.height } : {}
+  
+  return { ...baseStyle, ...heightStyle }
+})
 </script>
 
 <template>
   <td
-    :class="cn('p-4 align-middle [&:has([role=checkbox])]:pr-0', props.class)"
+    :class="cn(props.padding || 'p-2', 'align-middle [&:has([role=checkbox])]:pr-0', props.class)"
+    :style="cellStyle"
     v-bind="delegatedProps"
   >
     <slot />

package/src/components/table/TableHead.vue

@@ -4,10 +4,12 @@ import { cn } from '@/lib/utils'
 
 const props = defineProps<{
   class?: HTMLAttributes['class']
+  height?: string
+  padding?: string
 }>()
 
 const delegatedProps = computed(() => {
-  const { class: _, ...delegated } = props
+  const { class: _, height: __, padding: ___, ...delegated } = props
 
   return delegated
 })
@@ -17,7 +19,9 @@ const delegatedProps = computed(() => {
   <th
     :class="
       cn(
-        'h-12 px-4 text-left align-middle font-medium text-muted-foreground [&:has([role=checkbox])]:pr-0',
+        props.height || 'h-[38px]',
+        props.padding || 'px-2',
+        'text-left align-middle font-medium text-muted-foreground [&:has([role=checkbox])]:pr-0',
         props.class,
       )
     "