@veristone/nuxt-v-app 0.2.6 → 0.2.8

package/app/components/V/A/Card.vue

@@ -3,106 +3,130 @@
  * VACard - Veristone Card
  * Matches XACard API exactly.
  */
-const props = withDefaults(defineProps<{
-  title?: string
-  description?: string
-  icon?: string
-  collapsible?: boolean
-  collapsed?: boolean
-  padding?: boolean
-  divider?: boolean
-  variant?: 'default' | 'error' | 'warning' | 'success'
-}>(), {
-  title: '',
-  description: '',
-  icon: '',
-  collapsible: false,
-  collapsed: false,
-  padding: true,
-  divider: true,
-  variant: 'default'
-})
+const props = withDefaults(
+	defineProps<{
+		title?: string;
+		description?: string;
+		icon?: string;
+		collapsible?: boolean;
+		collapsed?: boolean;
+		padding?: boolean;
+		divider?: boolean;
+		variant?: "default" | "error" | "warning" | "success";
+	}>(),
+	{
+		title: "",
+		description: "",
+		icon: "",
+		collapsible: false,
+		collapsed: false,
+		padding: true,
+		divider: true,
+		variant: "default",
+	}
+);
 
-const isCollapsed = ref(props.collapsed)
-watch(() => props.collapsed, (val) => isCollapsed.value = val)
+const isCollapsed = ref(props.collapsed);
+watch(
+	() => props.collapsed,
+	(val) => (isCollapsed.value = val)
+);
 
 const toggleCollapse = () => {
-  if (props.collapsible) isCollapsed.value = !isCollapsed.value
-}
+	if (props.collapsible) isCollapsed.value = !isCollapsed.value;
+};
 
 const variantClass = computed(() => {
-  switch (props.variant) {
-    case 'error': return 'border-red-200 dark:border-red-900 bg-red-50/50 dark:bg-red-900/10'
-    case 'warning': return 'border-amber-200 dark:border-amber-900 bg-amber-50/50 dark:bg-amber-900/10'
-    case 'success': return 'border-green-200 dark:border-green-900 bg-green-50/50 dark:bg-green-900/10'
-    default: return 'border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900'
-  }
-})
+	switch (props.variant) {
+		case "error":
+			return "border-red-200 dark:border-red-900 bg-red-50/50 dark:bg-red-900/10";
+		case "warning":
+			return "border-amber-200 dark:border-amber-900 bg-amber-50/50 dark:bg-amber-900/10";
+		case "success":
+			return "border-green-200 dark:border-green-900 bg-green-50/50 dark:bg-green-900/10";
+		default:
+			return "border-gray-200 dark:border-gray-800 bg-white dark:bg-gray-900";
+	}
+});
 </script>
 
 <template>
-  <div 
-    class="va-card rounded-xl border transition-all duration-200 shadow-[0_2px_9px_rgba(0,0,0,0.08)] hover:shadow-[0_4px_12px_rgba(61,113,136,0.12)] hover:-translate-y-0.5"
-    :class="variantClass"
-  >
-    <!-- Header -->
-    <div 
-      v-if="title || $slots['header-actions'] || icon"
-      class="flex items-center justify-between"
-      :class="[
-        padding ? 'px-5 py-4' : 'px-4 py-3',
-        divider && !isCollapsed ? 'border-b border-gray-100 dark:border-gray-800' : ''
-      ]"
-    >
-      <div class="flex items-center gap-3 overflow-hidden">
-        <slot name="header">
-          <div v-if="icon" class="flex-shrink-0 p-1.5 rounded-md bg-gray-100 dark:bg-gray-800 text-gray-500">
-            <UIcon :name="icon" class="w-5 h-5" />
-          </div>
-          <div class="min-w-0">
-            <div class="flex items-center gap-2">
-              <h3 class="font-bold text-gray-900 dark:text-white truncate text-base">{{ title }}</h3>
-              
-              <button 
-                v-if="collapsible" 
-                @click="toggleCollapse"
-                class="ml-1 text-gray-400 hover:text-gray-600 dark:hover:text-gray-200 transition-colors focus:outline-none"
-              >
-                <UIcon 
-                  name="i-lucide-chevron-down" 
-                  class="w-4 h-4 transition-transform duration-300" 
-                  :class="{ '-rotate-180': !isCollapsed }"
-                />
-              </button>
-            </div>
-            <p v-if="description" class="text-xs text-gray-500 dark:text-gray-400 truncate mt-0.5 font-medium">{{ description }}</p>
-          </div>
-        </slot>
-      </div>
+	<div
+		class="va-card rounded-xl border transition-all duration-200 shadow-[0_2px_9px_rgba(0,0,0,0.08)] hover:shadow-[0_4px_12px_rgba(61,113,136,0.12)]"
+		:class="variantClass"
+	>
+		<!-- Header -->
+		<div
+			v-if="title || $slots['header-actions'] || icon"
+			class="flex items-center justify-between"
+			:class="[
+				padding ? 'px-5 py-4' : 'px-4 py-3',
+				divider && !isCollapsed
+					? 'border-b border-gray-100 dark:border-gray-800'
+					: '',
+			]"
+		>
+			<div class="flex items-center gap-3 overflow-hidden">
+				<slot name="header">
+					<div
+						v-if="icon"
+						class="flex-shrink-0 p-1.5 rounded-md bg-gray-100 dark:bg-gray-800 text-gray-500"
+					>
+						<UIcon :name="icon" class="w-5 h-5" />
+					</div>
+					<div class="min-w-0">
+						<div class="flex items-center gap-2">
+							<h3
+								class="font-bold text-gray-900 dark:text-white truncate text-base"
+							>
+								{{ title }}
+							</h3>
 
-      <!-- XACard uses 'header-actions' slot -->
-      <div v-if="$slots['header-actions']" class="flex-shrink-0 flex items-center gap-2 ml-4">
-        <slot name="header-actions" />
-      </div>
-    </div>
+							<button
+								v-if="collapsible"
+								@click="toggleCollapse"
+								class="ml-1 text-gray-400 hover:text-gray-600 dark:hover:text-gray-200 transition-colors focus:outline-none"
+							>
+								<UIcon
+									name="i-lucide-chevron-down"
+									class="w-4 h-4 transition-transform duration-300"
+									:class="{ '-rotate-180': !isCollapsed }"
+								/>
+							</button>
+						</div>
+						<p
+							v-if="description"
+							class="text-xs text-gray-500 dark:text-gray-400 truncate mt-0.5 font-medium"
+						>
+							{{ description }}
+						</p>
+					</div>
+				</slot>
+			</div>
 
-    <!-- Body -->
-    <div 
-      v-show="!isCollapsed" 
-      class="transition-all duration-300 ease-in-out"
-    >
-      <div :class="{ 'p-5': padding, 'p-0': !padding }">
-        <slot />
-      </div>
+			<!-- XACard uses 'header-actions' slot -->
+			<div
+				v-if="$slots['header-actions']"
+				class="flex-shrink-0 flex items-center gap-2 ml-4"
+			>
+				<slot name="header-actions" />
+			</div>
+		</div>
 
-      <!-- Footer -->
-      <div 
-        v-if="$slots.footer" 
-        class="bg-gray-50 dark:bg-gray-800/50 border-t border-gray-100 dark:border-gray-800"
-        :class="padding ? 'px-5 py-3' : 'px-4 py-2'"
-      >
-        <slot name="footer" />
-      </div>
-    </div>
-  </div>
+		<!-- Body -->
+		<div v-show="!isCollapsed" class="transition-all duration-300 ease-in-out">
+			<div :class="{ 'p-5': padding, 'p-0': !padding }">
+				<slot />
+			</div>
+
+			<!-- Footer -->
+			<div
+				v-if="$slots.footer"
+				class="bg-gray-50 dark:bg-gray-800/50 border-t border-gray-100 dark:border-gray-800"
+				:class="padding ? 'px-5 py-3' : 'px-4 py-2'"
+			>
+				<slot name="footer" />
+			</div>
+		</div>
+	</div>
 </template>

package/app/components/V/A/Table/README.md

@@ -34,12 +34,13 @@ The primary table component. Wraps Nuxt UI's `<UTable>` with a toolbar, filter c
 | `loading` | `boolean` | `false` | Shows loading skeleton on initial load |
 | `initialPageLimit` | `number` | `10` | Rows per page (client-side mode) |
 | `selectable` | `boolean` | `false` | Enable row selection checkboxes |
+| `showSearch` | `boolean` | `false` | Show the built-in search input in the toolbar |
 | `filters` | `FilterDefinition[]` | — | Filter dropdown definitions |
 | `onRefresh` | `() => void \| Promise<void>` | — | Shows refresh button; called on click |
 | `onRowClick` | `(row: unknown) => void` | — | Called when a row is clicked |
 | `defaultSort` | `string` | — | Column accessorKey to sort by on mount |
 | `defaultSortDesc` | `boolean` | `false` | Sort descending by default |
-| `manualPagination` | `boolean` | `false` | Enable server-side pagination mode |
+| `manualPagination` | `boolean` | `false` | Enable server-side pagination mode (disables client-side sorting and filtering) |
 | `total` | `number` | — | Total row count from server (required for manualPagination) |
 
 #### v-model Bindings
@@ -47,8 +48,8 @@ The primary table component. Wraps Nuxt UI's `<UTable>` with a toolbar, filter c
 | Model | Type | Description |
 |-------|------|-------------|
 | `sorting` | `SortingState` | TanStack sorting state |
-| `filterValues` | `Record<string, unknown>` | Active filter values |
-| `globalFilter` | `string` | Search/query filter |
+| `filterValues` | `Record<string, unknown>` | Active filter values (for built-in filters) |
+| `globalFilter` | `string` | Search/query filter (for built-in search) |
 | `page` | `number` | Current page (1-based, server-side mode) |
 | `itemsPerPage` | `number` | Page size (server-side mode) |
 
@@ -378,6 +379,8 @@ const columns = [
 
 ### Server-side pagination
 
+When `manualPagination` is enabled, the table disables client-side sorting and filtering. The parent component owns all query logic — it watches the table's `sorting`, `page`, and `itemsPerPage` models, builds API params, and fetches data.
+
 ```vue
 <script setup>
 const columns = [
@@ -386,23 +389,34 @@ const columns = [
   { accessorKey: 'status', header: 'Status' },
 ]
 
-// Server-side pagination state
+const sorting = ref([])
 const page = ref(1)
 const itemsPerPage = ref(20)
 const total = ref(0)
 const users = ref([])
 const loading = ref(false)
 
-// Fetch data from API with pagination params
+// Parent-owned search (not built into the table)
+const search = ref('')
+
+// Build API params from table state + parent state
+const apiParams = computed(() => {
+  const params = { page: page.value, limit: itemsPerPage.value }
+  const sort = sorting.value[0]
+  if (sort?.id) {
+    params.sort_by = sort.id
+    params.sort_order = sort.desc ? 'desc' : 'asc'
+  }
+  if (search.value.trim()) {
+    params.search = search.value.trim()
+  }
+  return params
+})
+
 async function fetchUsers() {
   loading.value = true
   try {
-    const response = await $fetch('/api/users', {
-      query: {
-        page: page.value,
-        limit: itemsPerPage.value,
-      }
-    })
+    const response = await $fetch('/api/users', { query: apiParams.value })
     users.value = response.data
     total.value = response.total
   } finally {
@@ -410,11 +424,13 @@ async function fetchUsers() {
   }
 }
 
-// React to pagination changes
-watch([page, itemsPerPage], fetchUsers, { immediate: true })
+watch(apiParams, fetchUsers, { immediate: true, deep: true })
 </script>
 
 <template>
+  <!-- Parent-owned search input -->
+  <UInput v-model="search" placeholder="Search..." icon="i-lucide-search" class="mb-4 max-w-xs" />
+
   <VATable
     name="Users"
     :data="users"
@@ -422,8 +438,10 @@ watch([page, itemsPerPage], fetchUsers, { immediate: true })
     :loading="loading"
     :manual-pagination="true"
     :total="total"
+    v-model:sorting="sorting"
     v-model:page="page"
     v-model:items-per-page="itemsPerPage"
+    :on-refresh="fetchUsers"
   />
 </template>
 ```

package/app/components/V/A/Table/index.vue

@@ -40,6 +40,7 @@
 				<!-- Normal Toolbar (shown when no items selected) -->
 				<div v-else class="flex items-center gap-2">
 					<UInput
+						v-if="showSearch"
 						v-model="globalFilter"
 						placeholder="Search..."
 						icon="i-lucide-search"
@@ -58,6 +59,8 @@
 							class="w-40"
 						/>
 					</template>
+
+					<slot name="toolbar-left" />
 				</div>
 
 				<div class="flex items-center gap-2">
@@ -97,7 +100,7 @@
 			<UTable
 				ref="table"
 				v-model:sorting="sorting"
-				v-model:global-filter="globalFilter"
+				v-model:global-filter="tableGlobalFilter"
 				v-model:pagination="pagination"
 				v-model:column-visibility="columnVisibility"
 				v-model:row-selection="rowSelection"
@@ -105,7 +108,7 @@
 				:columns="tableColumns"
 				:loading="loading"
 				:row-selection-options="{ enableRowSelection: props.selectable }"
-				:sorting-options="{ getSortedRowModel: getSortedRowModel() }"
+				:sorting-options="sortingOptions"
 				:pagination-options="{
 					getPaginationRowModel: getPaginationRowModel(),
 					manualPagination: props.manualPagination,
@@ -119,7 +122,7 @@
 				}"
 				empty="Nothing to show."
 				v-bind="$attrs"
-				@row-click="handleRowClick"
+				:on-select="props.onRowClick ? (_e: any, row: any) => handleRowClick(row) : undefined"
 			>
 				<template v-for="slotEntry in forwardedSlots" :key="slotEntry.target" #[slotEntry.target]="slotProps">
 					<slot :name="slotEntry.source" v-bind="slotProps" />
@@ -162,42 +165,50 @@
 	</UCard>
 </template>
 
-<script setup lang="ts">
-import { getCoreRowModel, getPaginationRowModel, getSortedRowModel } from "@tanstack/vue-table";
-import type { TableColumn, DropdownMenuItem } from "@nuxt/ui";
-import type { SortingState } from "@tanstack/vue-table";
-import { h, resolveComponent, useSlots } from 'vue';
-import CellRenderer from './CellRenderer.vue';
-import FilterChips from './FilterChips.vue';
-
-type FilterDefinition = {
-	label: string;
-	key: string;
-	options: { label: string; value: string }[];
-};
-
-const props = withDefaults(defineProps<{
-	name?: string;
-	data: unknown[];
-	columns: TableColumn<unknown>[];
-	loading?: boolean;
-	initialPageLimit?: number;
-	selectable?: boolean;
-	filters?: FilterDefinition[];
-	onRefresh?: () => void | Promise<void>;
-	onRowClick?: (row: unknown) => void;
-	/** Default column to sort by */
-	defaultSort?: string;
-	/** Default sort direction */
-	defaultSortDesc?: boolean;
-	/** Enable server-side pagination mode */
-	manualPagination?: boolean;
-	/** Total row count from server (required for manualPagination) */
-	total?: number;
-}>(), {
-	selectable: false,
-	manualPagination: false,
-});
+/**
+ * VATable - Veristone data table component built on Nuxt UI's UTable + TanStack Table.
+ *
+ * @props
+ *   name             - Optional card header title
+ *   data             - Row data array
+ *   columns          - TanStack TableColumn definitions; supports `meta.preset` for cell rendering
+ *   loading          - Shows skeleton on initial load; shows inline spinner on subsequent refreshes
+ *   initialPageLimit - Default page size (default: 10)
+ *   selectable       - Enables row checkboxes; exposes `selectedRows` via template ref
+ *   showSearch       - Renders a global search input in the toolbar
+ *   filters          - Array of { key, label, options } for toolbar USelect dropdowns
+ *   onRefresh        - Async callback; shows a refresh spinner button in the toolbar
+ *   onRowClick       - Called with the row's original data when a row is clicked
+ *   defaultSort      - Column key to sort by on mount
+ *   defaultSortDesc  - Sort descending when defaultSort is set (default: false)
+ *   manualPagination - Enables server-side pagination mode
+ *   total            - Total row count for server-side pagination
+ *
+ * @models (v-model)
+ *   sorting          - SortingState — sync sort state with parent
+ *   filterValues     - Record<string, unknown> — sync active filter values with parent
+ *   globalFilter     - string — sync search input value with parent
+ *   page             - number (1-based) — current page in manual pagination mode
+ *   itemsPerPage     - number — page size in manual pagination mode
+ *
+ * @slots
+ *   header-right     - Content rendered on the right side of the card header
+ *   toolbar-left     - Custom controls (e.g. filter selects) injected into the toolbar
+ *                      next to the search input and built-in filter dropdowns
+ *                      Example:
+ *                        <template #toolbar-left>
+ *                          <USelect v-model="status" :items="opts" placeholder="Status" size="sm" />
+ *                        </template>
+ *   bulk-actions     - Shown in the toolbar when rows are selected; receives
+ *                      { selected, count, clear }
+ *   actions-cell     - Renders an "Actions" column; receives { row }
+ *   [column]-cell    - Override cell rendering for a specific column by accessor key
+ *
+ * @exposes
+ *   selectedRows     - Array of selected row originals
+ *   rowSelection     - Raw TanStack row selection state
+ *   clearSelection   - Clears the current row selection
+ */
 
 // Sorting state - v-model support
 const sorting = defineModel<SortingState>("sorting", {
@@ -285,14 +296,6 @@ function clearSelection() {
 	rowSelection.value = {};
 }
 
-watch(
-	() => filterValues.value,
-	() => {
-		clearSelection();
-	},
-	{ deep: true }
-);
-
 // Table ref for accessing TanStack API
 const table = ref<{ tableApi?: any } | null>(null);
 
@@ -328,6 +331,30 @@ watch(
 // Global filter - v-model support
 const globalFilter = defineModel<string>("globalFilter", { default: "" });
 
+// In manual mode, prevent TanStack from filtering client-side
+const tableGlobalFilter = computed({
+	get: () => props.manualPagination ? undefined : globalFilter.value,
+	set: (v: string) => { globalFilter.value = v ?? '' },
+});
+
+// Reset page when sorting changes
+watch(
+	sorting,
+	() => {
+		clearSelection();
+		if (props.manualPagination) {
+			page.value = 1;
+		} else {
+			pagination.value = { ...pagination.value, pageIndex: 0 };
+		}
+	},
+	{ deep: true, flush: 'sync' }
+);
+
+const sortingOptions = computed(() =>
+	props.manualPagination ? { manualSorting: true } : undefined
+);
+
 // Initialize default sorting if provided
 onMounted(() => {
 	if (props.defaultSort && sorting.value.length === 0) {
@@ -457,7 +484,7 @@ const tableColumns = computed(() => {
 
 const forwardedSlots = computed(() => {
 	const passthrough = Object.keys(slots).filter((name) => {
-		return !['default', 'header-right', 'bulk-actions'].includes(name);
+		return !['default', 'header-right', 'bulk-actions', 'toolbar-left'].includes(name);
 	});
 
 	return passthrough.map((source) => {