@htlkg/components 0.0.3 → 0.0.4

package/src/composables/useConfirmation.ts

@@ -0,0 +1,358 @@
+/**
+ * Confirmation Composable
+ *
+ * Manages confirmation dialog state for destructive actions.
+ * Works with uiModal from @hotelinking/ui.
+ */
+
+import { ref, computed, type Ref, type ComputedRef, type Component } from 'vue';
+
+/**
+ * Confirmation dialog variant
+ */
+export type ConfirmationVariant = 'danger' | 'warning' | 'info' | 'default';
+
+/**
+ * Configuration for a confirmation dialog
+ */
+export interface ConfirmationConfig {
+	/** Dialog title */
+	title: string;
+	/** Dialog message/description */
+	message: string;
+	/** Text for confirm button */
+	confirmText?: string;
+	/** Text for cancel button */
+	cancelText?: string;
+	/** Visual variant */
+	variant?: ConfirmationVariant;
+	/** Icon component to display */
+	icon?: Component;
+	/** Whether action is in progress */
+	loading?: boolean;
+}
+
+/**
+ * Internal state for pending confirmation
+ */
+interface PendingConfirmation {
+	resolve: (value: boolean) => void;
+	reject: (reason?: unknown) => void;
+}
+
+/**
+ * Options for useConfirmation
+ */
+export interface UseConfirmationOptions {
+	/** Default confirm button text */
+	defaultConfirmText?: string;
+	/** Default cancel button text */
+	defaultCancelText?: string;
+	/** Default variant */
+	defaultVariant?: ConfirmationVariant;
+}
+
+/**
+ * Return type for useConfirmation
+ */
+export interface UseConfirmationReturn {
+	/** Whether dialog is open */
+	isOpen: Ref<boolean>;
+	/** Current dialog configuration */
+	config: Ref<ConfirmationConfig>;
+	/** Whether action is in progress */
+	isLoading: Ref<boolean>;
+
+	/** Open confirmation dialog and wait for response */
+	confirm: (options: ConfirmationConfig) => Promise<boolean>;
+	/** Handle confirm button click */
+	handleConfirm: () => void;
+	/** Handle cancel button click */
+	handleCancel: () => void;
+	/** Close dialog without triggering callbacks */
+	close: () => void;
+
+	/** Convenience: Confirm delete action */
+	confirmDelete: (itemName: string, options?: Partial<ConfirmationConfig>) => Promise<boolean>;
+	/** Convenience: Confirm bulk delete action */
+	confirmBulkDelete: (count: number, itemType?: string, options?: Partial<ConfirmationConfig>) => Promise<boolean>;
+	/** Convenience: Confirm destructive action */
+	confirmDestructive: (actionName: string, options?: Partial<ConfirmationConfig>) => Promise<boolean>;
+	/** Convenience: Confirm with custom async action */
+	confirmWithAction: <T>(
+		options: ConfirmationConfig,
+		action: () => Promise<T>
+	) => Promise<{ confirmed: boolean; result?: T; error?: Error }>;
+
+	/** Props for uiModal component */
+	modalProps: ComputedRef<{
+		title: string;
+		open: boolean;
+		modalName: string;
+		actions: Array<{ name: string; value: string }>;
+	}>;
+}
+
+/**
+ * Creates a confirmation dialog composable
+ *
+ * @example
+ * ```typescript
+ * const confirmation = useConfirmation();
+ *
+ * async function handleDelete(item: Item) {
+ *   const confirmed = await confirmation.confirmDelete(item.name);
+ *   if (confirmed) {
+ *     await deleteItem(item.id);
+ *   }
+ * }
+ *
+ * // Or with async action
+ * async function handleDeleteWithAction(item: Item) {
+ *   const { confirmed, error } = await confirmation.confirmWithAction(
+ *     { title: 'Delete Item', message: `Delete "${item.name}"?` },
+ *     () => deleteItem(item.id)
+ *   );
+ *   if (confirmed && !error) {
+ *     showSuccess('Item deleted');
+ *   }
+ * }
+ *
+ * // In template
+ * <Modal
+ *   v-bind="confirmation.modalProps"
+ *   @modal-action="(e) => e.action === 'confirm' ? confirmation.handleConfirm() : confirmation.handleCancel()"
+ * >
+ *   <p>{{ confirmation.config.message }}</p>
+ * </Modal>
+ * ```
+ */
+export function useConfirmation(options: UseConfirmationOptions = {}): UseConfirmationReturn {
+	const {
+		defaultConfirmText = 'Confirm',
+		defaultCancelText = 'Cancel',
+		defaultVariant = 'default',
+	} = options;
+
+	// State
+	const isOpen = ref(false);
+	const isLoading = ref(false);
+	const config = ref<ConfirmationConfig>({
+		title: '',
+		message: '',
+		confirmText: defaultConfirmText,
+		cancelText: defaultCancelText,
+		variant: defaultVariant,
+	});
+
+	// Pending promise resolution
+	let pending: PendingConfirmation | null = null;
+
+	/**
+	 * Open confirmation dialog and wait for user response
+	 */
+	function confirm(confirmConfig: ConfirmationConfig): Promise<boolean> {
+		// Set configuration with defaults
+		config.value = {
+			...confirmConfig,
+			confirmText: confirmConfig.confirmText ?? defaultConfirmText,
+			cancelText: confirmConfig.cancelText ?? defaultCancelText,
+			variant: confirmConfig.variant ?? defaultVariant,
+		};
+
+		isOpen.value = true;
+		isLoading.value = false;
+
+		return new Promise((resolve, reject) => {
+			pending = { resolve, reject };
+		});
+	}
+
+	/**
+	 * Handle confirm button click
+	 */
+	function handleConfirm(): void {
+		if (pending) {
+			pending.resolve(true);
+			pending = null;
+		}
+		isOpen.value = false;
+		isLoading.value = false;
+	}
+
+	/**
+	 * Handle cancel button click
+	 */
+	function handleCancel(): void {
+		if (pending) {
+			pending.resolve(false);
+			pending = null;
+		}
+		isOpen.value = false;
+		isLoading.value = false;
+	}
+
+	/**
+	 * Close dialog without resolving
+	 */
+	function close(): void {
+		if (pending) {
+			pending.resolve(false);
+			pending = null;
+		}
+		isOpen.value = false;
+		isLoading.value = false;
+	}
+
+	/**
+	 * Convenience: Confirm delete action
+	 */
+	function confirmDelete(
+		itemName: string,
+		confirmConfig?: Partial<ConfirmationConfig>
+	): Promise<boolean> {
+		return confirm({
+			title: 'Delete Item',
+			message: `Are you sure you want to delete "${itemName}"? This action cannot be undone.`,
+			confirmText: 'Delete',
+			cancelText: 'Cancel',
+			variant: 'danger',
+			...confirmConfig,
+		});
+	}
+
+	/**
+	 * Convenience: Confirm bulk delete action
+	 */
+	function confirmBulkDelete(
+		count: number,
+		itemType: string = 'items',
+		confirmConfig?: Partial<ConfirmationConfig>
+	): Promise<boolean> {
+		return confirm({
+			title: `Delete ${count} ${itemType}`,
+			message: `Are you sure you want to delete ${count} ${itemType}? This action cannot be undone.`,
+			confirmText: 'Delete All',
+			cancelText: 'Cancel',
+			variant: 'danger',
+			...confirmConfig,
+		});
+	}
+
+	/**
+	 * Convenience: Confirm destructive action
+	 */
+	function confirmDestructive(
+		actionName: string,
+		confirmConfig?: Partial<ConfirmationConfig>
+	): Promise<boolean> {
+		return confirm({
+			title: `Confirm ${actionName}`,
+			message: `Are you sure you want to ${actionName.toLowerCase()}? This action cannot be undone.`,
+			confirmText: actionName,
+			cancelText: 'Cancel',
+			variant: 'danger',
+			...confirmConfig,
+		});
+	}
+
+	/**
+	 * Convenience: Confirm with async action execution
+	 */
+	async function confirmWithAction<T>(
+		confirmConfig: ConfirmationConfig,
+		action: () => Promise<T>
+	): Promise<{ confirmed: boolean; result?: T; error?: Error }> {
+		const confirmed = await confirm(confirmConfig);
+
+		if (!confirmed) {
+			return { confirmed: false };
+		}
+
+		// Show loading state
+		isLoading.value = true;
+
+		try {
+			const result = await action();
+			isOpen.value = false;
+			isLoading.value = false;
+			return { confirmed: true, result };
+		} catch (error) {
+			isLoading.value = false;
+			return {
+				confirmed: true,
+				error: error instanceof Error ? error : new Error(String(error)),
+			};
+		}
+	}
+
+	/**
+	 * Props for uiModal component
+	 */
+	const modalProps = computed(() => ({
+		title: config.value.title,
+		open: isOpen.value,
+		modalName: 'confirmation-dialog',
+		actions: [
+			{
+				name: config.value.cancelText ?? defaultCancelText,
+				value: 'cancel',
+			},
+			{
+				name: config.value.confirmText ?? defaultConfirmText,
+				value: 'confirm',
+			},
+		],
+	}));
+
+	return {
+		// State
+		isOpen,
+		config,
+		isLoading,
+
+		// Core methods
+		confirm,
+		handleConfirm,
+		handleCancel,
+		close,
+
+		// Convenience methods
+		confirmDelete,
+		confirmBulkDelete,
+		confirmDestructive,
+		confirmWithAction,
+
+		// Modal props
+		modalProps,
+	};
+}
+
+/**
+ * Global confirmation instance for use across components
+ */
+let globalConfirmation: UseConfirmationReturn | null = null;
+
+/**
+ * Get or create global confirmation instance
+ *
+ * @example
+ * ```typescript
+ * // In any component
+ * const confirmation = useGlobalConfirmation();
+ * await confirmation.confirmDelete('Item Name');
+ * ```
+ */
+export function useGlobalConfirmation(): UseConfirmationReturn {
+	if (!globalConfirmation) {
+		globalConfirmation = useConfirmation();
+	}
+	return globalConfirmation;
+}
+
+/**
+ * Reset global confirmation instance (useful for testing)
+ */
+export function resetGlobalConfirmation(): void {
+	globalConfirmation = null;
+}

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)}%`;
+		},
+	};
+}