@htlkg/components 0.0.2 → 0.0.4

package/src/composables/useStats.ts

@@ -0,0 +1,361 @@
+/**
+ * Stats Composable
+ *
+ * Derives statistics from reactive data with staggered loading animation.
+ * Integrates with uiStats component from @hotelinking/ui.
+ */
+
+import { ref, computed, watch, type Ref, type ComputedRef, type Component } from 'vue';
+
+/**
+ * Color options matching @hotelinking/ui
+ */
+export type StatColor = 'green' | 'red' | 'yellow' | 'blue' | 'gray' | 'purple' | 'orange' | 'pink';
+
+/**
+ * Change type for stat trends
+ */
+export type ChangeType = 'increase' | 'decrease' | 'neutral';
+
+/**
+ * Definition for a single stat
+ */
+export interface StatDefinition<T> {
+	/** Unique identifier */
+	id: string;
+	/** Display name */
+	name: string;
+	/** Icon component (Heroicons) */
+	icon: Component;
+	/** Color theme */
+	color?: StatColor;
+	/** Function to compute stat value from data */
+	compute: (items: T[]) => string | number;
+	/** Optional: Compute change percentage/value */
+	computeChange?: (items: T[], previousItems?: T[]) => string;
+	/** Optional: Compute change type (increase/decrease/neutral) */
+	computeChangeType?: (items: T[], previousItems?: T[]) => ChangeType;
+	/** Show footer with action text */
+	showFooter?: boolean;
+	/** Action text for footer */
+	actionText?: string;
+}
+
+/**
+ * Stat item formatted for uiStats component
+ */
+export interface StatItem {
+	id: string;
+	name: string;
+	stat: string | number;
+	icon: Component;
+	color: StatColor;
+	change?: string;
+	changeType?: ChangeType;
+	showFooter?: boolean;
+	actionText?: string;
+}
+
+/**
+ * Options for useStats
+ */
+export interface UseStatsOptions<T> {
+	/** Reactive data source */
+	data: Ref<T[]> | ComputedRef<T[]>;
+	/** Loading state of the data source */
+	loading: Ref<boolean> | ComputedRef<boolean>;
+	/** Stat definitions */
+	definitions: StatDefinition<T>[];
+	/** Delay between each stat reveal (ms) */
+	staggerDelay?: number;
+	/** Initial delay before first stat reveals (ms) */
+	initialDelay?: number;
+	/** Previous data for computing changes (optional) */
+	previousData?: Ref<T[]> | ComputedRef<T[]>;
+}
+
+/**
+ * Return type for useStats
+ */
+export interface UseStatsReturn<T> {
+	/** Computed stats array for uiStats */
+	stats: ComputedRef<StatItem[]>;
+	/** Individual loading states for each stat */
+	loadingStates: Ref<boolean[]>;
+	/** Combined stats with loading property */
+	statsWithLoading: ComputedRef<Array<StatItem & { loading: boolean }>>;
+	/** Whether all stats are loaded */
+	allLoaded: ComputedRef<boolean>;
+	/** Force refresh loading animation */
+	refreshAnimation: () => void;
+	/** Get a single stat by ID */
+	getStat: (id: string) => StatItem | undefined;
+}
+
+/**
+ * Creates a stats composable for deriving statistics from reactive data
+ *
+ * @example
+ * ```typescript
+ * import { CheckCircleIcon, ClockIcon, XCircleIcon } from '@heroicons/vue/24/outline';
+ *
+ * const { statsWithLoading } = useStats({
+ *   data: campaigns,
+ *   loading: campaignsLoading,
+ *   definitions: [
+ *     {
+ *       id: 'active',
+ *       name: 'Active Campaigns',
+ *       icon: CheckCircleIcon,
+ *       color: 'green',
+ *       compute: (items) => items.filter(c => c.status === 'active').length,
+ *     },
+ *     {
+ *       id: 'pending',
+ *       name: 'Pending',
+ *       icon: ClockIcon,
+ *       color: 'yellow',
+ *       compute: (items) => items.filter(c => c.status === 'pending').length,
+ *     },
+ *     {
+ *       id: 'total-sent',
+ *       name: 'Total Sent',
+ *       icon: PaperAirplaneIcon,
+ *       color: 'blue',
+ *       compute: (items) => items.reduce((sum, c) => sum + c.sentCount, 0).toLocaleString(),
+ *       computeChange: (items) => '+12%',
+ *       computeChangeType: () => 'increase',
+ *     },
+ *   ],
+ *   staggerDelay: 100,
+ * });
+ *
+ * // In template
+ * <div class="grid grid-cols-4 gap-4">
+ *   <uiStats
+ *     v-for="stat in statsWithLoading"
+ *     :key="stat.id"
+ *     :item="stat"
+ *     :loading="stat.loading"
+ *     @statClick="handleStatClick"
+ *   />
+ * </div>
+ * ```
+ */
+export function useStats<T>(options: UseStatsOptions<T>): UseStatsReturn<T> {
+	const {
+		data,
+		loading,
+		definitions,
+		staggerDelay = 100,
+		initialDelay = 0,
+		previousData,
+	} = options;
+
+	// Individual loading states for staggered animation
+	const loadingStates = ref<boolean[]>(definitions.map(() => true));
+
+	// Timers for cleanup
+	let timers: ReturnType<typeof setTimeout>[] = [];
+
+	// Clear all pending timers
+	function clearTimers(): void {
+		timers.forEach(timer => clearTimeout(timer));
+		timers = [];
+	}
+
+	// Trigger staggered loading animation
+	function triggerStaggeredReveal(): void {
+		clearTimers();
+
+		// Reset all to loading
+		loadingStates.value = definitions.map(() => true);
+
+		// Staggered reveal
+		definitions.forEach((_, index) => {
+			const timer = setTimeout(() => {
+				loadingStates.value[index] = false;
+			}, initialDelay + staggerDelay * (index + 1));
+			timers.push(timer);
+		});
+	}
+
+	// Watch for loading state changes
+	watch(
+		() => loading.value,
+		(isLoading, wasLoading) => {
+			if (wasLoading && !isLoading) {
+				// Data just finished loading, trigger reveal
+				triggerStaggeredReveal();
+			} else if (isLoading && !wasLoading) {
+				// Started loading, reset states
+				clearTimers();
+				loadingStates.value = definitions.map(() => true);
+			}
+		},
+		{ immediate: true }
+	);
+
+	// If data is already loaded on mount, trigger reveal
+	if (!loading.value) {
+		triggerStaggeredReveal();
+	}
+
+	// Computed: Stats derived from data
+	const stats = computed<StatItem[]>(() => {
+		const items = data.value;
+		const prevItems = previousData?.value;
+
+		return definitions.map(def => {
+			const stat: StatItem = {
+				id: def.id,
+				name: def.name,
+				stat: def.compute(items),
+				icon: def.icon,
+				color: def.color ?? 'gray',
+			};
+
+			// Add change information if provided
+			if (def.computeChange) {
+				stat.change = def.computeChange(items, prevItems);
+			}
+
+			if (def.computeChangeType) {
+				stat.changeType = def.computeChangeType(items, prevItems);
+			}
+
+			// Footer options
+			if (def.showFooter !== undefined) {
+				stat.showFooter = def.showFooter;
+			}
+
+			if (def.actionText) {
+				stat.actionText = def.actionText;
+			}
+
+			return stat;
+		});
+	});
+
+	// Computed: Stats with loading property included
+	const statsWithLoading = computed(() =>
+		stats.value.map((stat, index) => ({
+			...stat,
+			loading: loading.value || loadingStates.value[index],
+		}))
+	);
+
+	// Computed: All stats loaded
+	const allLoaded = computed(() =>
+		!loading.value && loadingStates.value.every(s => !s)
+	);
+
+	// Get a single stat by ID
+	function getStat(id: string): StatItem | undefined {
+		return stats.value.find(s => s.id === id);
+	}
+
+	// Manually refresh animation
+	function refreshAnimation(): void {
+		triggerStaggeredReveal();
+	}
+
+	return {
+		stats,
+		loadingStates,
+		statsWithLoading,
+		allLoaded,
+		refreshAnimation,
+		getStat,
+	};
+}
+
+/**
+ * Helper: Create a simple count stat definition
+ */
+export function countStat<T>(
+	id: string,
+	name: string,
+	icon: Component,
+	filter: (item: T) => boolean,
+	options?: { color?: StatColor }
+): StatDefinition<T> {
+	return {
+		id,
+		name,
+		icon,
+		color: options?.color ?? 'gray',
+		compute: (items) => items.filter(filter).length,
+	};
+}
+
+/**
+ * Helper: Create a sum stat definition
+ */
+export function sumStat<T>(
+	id: string,
+	name: string,
+	icon: Component,
+	getValue: (item: T) => number,
+	options?: { color?: StatColor; format?: (value: number) => string }
+): StatDefinition<T> {
+	return {
+		id,
+		name,
+		icon,
+		color: options?.color ?? 'gray',
+		compute: (items) => {
+			const sum = items.reduce((total, item) => total + getValue(item), 0);
+			return options?.format ? options.format(sum) : sum.toLocaleString();
+		},
+	};
+}
+
+/**
+ * Helper: Create an average stat definition
+ */
+export function averageStat<T>(
+	id: string,
+	name: string,
+	icon: Component,
+	getValue: (item: T) => number,
+	options?: { color?: StatColor; decimals?: number; suffix?: string }
+): StatDefinition<T> {
+	return {
+		id,
+		name,
+		icon,
+		color: options?.color ?? 'gray',
+		compute: (items) => {
+			if (items.length === 0) return '0';
+			const sum = items.reduce((total, item) => total + getValue(item), 0);
+			const avg = sum / items.length;
+			const formatted = avg.toFixed(options?.decimals ?? 1);
+			return options?.suffix ? `${formatted}${options.suffix}` : formatted;
+		},
+	};
+}
+
+/**
+ * Helper: Create a percentage stat definition
+ */
+export function percentageStat<T>(
+	id: string,
+	name: string,
+	icon: Component,
+	filter: (item: T) => boolean,
+	options?: { color?: StatColor; decimals?: number }
+): StatDefinition<T> {
+	return {
+		id,
+		name,
+		icon,
+		color: options?.color ?? 'gray',
+		compute: (items) => {
+			if (items.length === 0) return '0%';
+			const count = items.filter(filter).length;
+			const percentage = (count / items.length) * 100;
+			return `${percentage.toFixed(options?.decimals ?? 1)}%`;
+		},
+	};
+}

package/src/composables/useTable.ts

@@ -122,11 +122,13 @@ export function useTable<T extends Record<string, any>>(
 
   // Computed - Filtering
   const filteredItems = computed(() => {
-    if (activeFilters.value.length === 0) return items.value;
+    // Ensure activeFilters is always an array
+    const filters = Array.isArray(activeFilters.value) ? activeFilters.value : [];
+    if (filters.length === 0) return items.value;
 
     return items.value.filter(item => {
       // All filters must pass (AND logic by default)
-      return activeFilters.value.every(filter => {
+      return filters.every(filter => {
         const { category, operator, value } = filter;
         
         if (value === undefined || value === null || value === '') return true;
@@ -297,8 +299,27 @@ export function useTable<T extends Record<string, any>>(
   }
 
   // Methods - Filtering
-  function applyFilters(filters: SmartFilter[]) {
-    activeFilters.value = filters;
+  function applyFilters(filters: SmartFilter[] | Record<string, any>) {
+    // Handle various filter formats from UI components
+    if (Array.isArray(filters)) {
+      activeFilters.value = filters;
+    } else if (filters && typeof filters === 'object') {
+      // Handle object format like { filters: [...] } or extract values
+      if ('filters' in filters && Array.isArray(filters.filters)) {
+        activeFilters.value = filters.filters;
+      } else {
+        // Convert object to SmartFilter array
+        activeFilters.value = Object.entries(filters)
+          .filter(([_, value]) => value !== undefined && value !== null && value !== '')
+          .map(([key, value]) => ({
+            category: key,
+            operator: 'contains',
+            value,
+          }));
+      }
+    } else {
+      activeFilters.value = [];
+    }
     currentPage.value = 1; // Reset to first page when filters change
   }
 
@@ -314,7 +335,7 @@ export function useTable<T extends Record<string, any>>(
     }
   }
 
-  function handleSmartFiltersApplied(filters: SmartFilter[]) {
+  function handleSmartFiltersApplied(filters: SmartFilter[] | Record<string, any>) {
     applyFilters(filters);
   }