@umituz/web-dashboard 2.1.0 → 2.2.0

package/src/domains/analytics/hooks/useAnalytics.ts

@@ -0,0 +1,178 @@
+/**
+ * useAnalytics Hook
+ *
+ * Core analytics hook for fetching and managing analytics data
+ */
+
+import { useState, useCallback, useEffect } from "react";
+import type {
+  KPIs,
+  TimeSeriesData,
+  ChartConfig,
+  DateRangeValue,
+  AnalyticsExportOptions,
+} from "../types/analytics";
+import { createKPI } from "../utils/analytics";
+
+interface UseAnalyticsOptions {
+  /** Analytics API base URL */
+  apiUrl?: string;
+  /** Initial date range */
+  initialDateRange?: DateRangeValue;
+  /** Auto-refresh interval in ms (0 to disable) */
+  refreshInterval?: number;
+}
+
+interface AnalyticsData {
+  /** KPI metrics */
+  kpis: KPIs;
+  /** Time series data */
+  timeSeries: TimeSeriesData[];
+  /** Loading state */
+  isLoading: boolean;
+  /** Error state */
+  error: string | null;
+}
+
+/**
+ * useAnalytics hook
+ *
+ * Manages analytics data fetching and state
+ *
+ * @param options - Hook options
+ * @returns Analytics data and actions
+ */
+export function useAnalytics(options: UseAnalyticsOptions = {}) {
+  const { apiUrl = "/api/analytics", initialDateRange, refreshInterval = 0 } = options;
+
+  // State
+  const [dateRange, setDateRange] = useState<DateRangeValue>(
+    initialDateRange || {
+      from: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().split("T")[0],
+      to: new Date().toISOString().split("T")[0],
+      preset: "Last 30 Days",
+    }
+  );
+  const [data, setData] = useState<AnalyticsData>({
+    kpis: {
+      downloads: { current: 0, previous: 0, growth: 0 },
+      engagement: { current: 0, previous: 0, growth: 0 },
+      users: { current: 0, previous: 0, growth: 0 },
+      revenue: { current: 0, previous: 0, growth: 0 },
+      retention: { current: 0, previous: 0, growth: 0 },
+    },
+    timeSeries: [],
+    isLoading: false,
+    error: null,
+  });
+
+  // Fetch analytics data
+  const fetchAnalytics = useCallback(async () => {
+    setData((prev) => ({ ...prev, isLoading: true, error: null }));
+
+    try {
+      // In production, call your analytics API
+      // const response = await fetch(`${apiUrl}?from=${dateRange.from}&to=${dateRange.to}`);
+      // const result = await response.json();
+
+      // Mock data for demo
+      const mockKPIs: KPIs = {
+        downloads: { current: 1250, previous: 1100, growth: 13.6 },
+        engagement: { current: 68.5, previous: 65.2, growth: 5.1 },
+        users: { current: 4500, previous: 4200, growth: 7.1 },
+        revenue: { current: 8950, previous: 7800, growth: 14.7 },
+        retention: { current: 72.3, previous: 69.8, growth: 3.6 },
+      };
+
+      const mockTimeSeries: TimeSeriesData[] = Array.from({ length: 30 }, (_, i) => {
+        const date = new Date();
+        date.setDate(date.getDate() - (29 - i));
+        return {
+          date: date.toISOString().split("T")[0],
+          downloads: Math.floor(1000 + Math.random() * 500),
+          engagement: 60 + Math.random() * 20,
+          revenue: Math.floor(7000 + Math.random() * 3000),
+          users: Math.floor(4000 + Math.random() * 1000),
+          retention: 65 + Math.random() * 15,
+        };
+      });
+
+      setData({
+        kpis: mockKPIs,
+        timeSeries: mockTimeSeries,
+        isLoading: false,
+        error: null,
+      });
+    } catch (err) {
+      const errorMessage = err instanceof Error ? err.message : "Failed to fetch analytics";
+      setData((prev) => ({
+        ...prev,
+        isLoading: false,
+        error: errorMessage,
+      }));
+    }
+  }, [apiUrl, dateRange]);
+
+  // Update date range
+  const updateDateRange = useCallback((newDateRange: DateRangeValue) => {
+    setDateRange(newDateRange);
+  }, []);
+
+  // Export analytics data
+  const exportData = useCallback(async (options: AnalyticsExportOptions) => {
+    try {
+      // In production, implement export API call
+      const exportData = {
+        dateRange,
+        kpis: data.kpis,
+        timeSeries: data.timeSeries,
+        format: options.format,
+      };
+
+      console.log("Exporting analytics:", exportData);
+
+      // Mock export
+      const blob = new Blob([JSON.stringify(exportData, null, 2)], {
+        type: options.format === "json" ? "application/json" : "text/plain",
+      });
+
+      const url = URL.createObjectURL(blob);
+      const link = document.createElement("a");
+      link.href = url;
+      link.download = options.filename || `analytics-${dateRange.from}-${dateRange.to}.${options.format}`;
+      document.body.appendChild(link);
+      link.click();
+      document.body.removeChild(link);
+      URL.revokeObjectURL(url);
+    } catch (err) {
+      console.error("Export failed:", err);
+      throw err;
+    }
+  }, [dateRange, data]);
+
+  // Refresh data
+  const refresh = useCallback(() => {
+    fetchAnalytics();
+  }, [fetchAnalytics]);
+
+  // Fetch on mount and date range change
+  useEffect(() => {
+    fetchAnalytics();
+  }, [fetchAnalytics]);
+
+  // Auto-refresh
+  useEffect(() => {
+    if (refreshInterval > 0) {
+      const interval = setInterval(fetchAnalytics, refreshInterval);
+      return () => clearInterval(interval);
+    }
+  }, [fetchAnalytics, refreshInterval]);
+
+  return {
+    ...data,
+    dateRange,
+    updateDateRange,
+    refresh,
+    exportData,
+  };
+}

package/src/domains/analytics/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Analytics Domain
+ *
+ * Main entry point for analytics domain
+ */
+
+// Components
+export {
+  MetricCard,
+  AnalyticsChart,
+  AnalyticsCard,
+  AnalyticsLayout,
+} from "./components";
+
+// Hooks
+export {
+  useAnalytics,
+} from "./hooks";
+
+// Utils
+export {
+  formatNumber,
+  formatPercentage,
+  formatCurrency,
+  calculateGrowth,
+  getTrend,
+  createKPI,
+  createMetric,
+  formatMetricValue,
+  calculateConversionRate,
+  calculateDropOffRate,
+  createDateRangePreset,
+  getDateRangePresets,
+  aggregateByPeriod,
+  calculateMovingAverage,
+  detectOutliers,
+  roundTo,
+  generateColor,
+  generateChartColors,
+} from "./utils";
+
+// Types
+export type {
+  Metric,
+  TimeSeriesData,
+  ChartData,
+  FunnelStep,
+  FunnelData,
+  CohortAnalysis,
+  UserSegment,
+  KPIData,
+  KPIs,
+  ChartType,
+  ChartConfig,
+  MetricCardProps,
+  AnalyticsCardProps,
+  AnalyticsLayoutProps,
+  DateRangePreset,
+  DateRangeValue,
+  ExportFormat,
+  AnalyticsExportOptions,
+} from "./types";

package/src/domains/analytics/types/analytics.ts

@@ -0,0 +1,291 @@
+/**
+ * Analytics Types
+ *
+ * Type definitions for analytics system
+ */
+
+import type { ComponentType, ReactElement } from "react";
+
+/**
+ * Metric card data
+ */
+export interface Metric {
+  /** Unique identifier */
+  id: string;
+  /** Metric name */
+  name: string;
+  /** Current value */
+  value: number;
+  /** Previous period value */
+  previousValue?: number;
+  /** Unit (%, $, etc.) */
+  unit?: string;
+  /** Trend direction */
+  trend?: "up" | "down" | "stable";
+  /** Icon component */
+  icon?: ComponentType<{ className?: string }>;
+}
+
+/**
+ * Time series data point
+ */
+export interface TimeSeriesData {
+  /** Date/label */
+  date: string;
+  /** Metric values */
+  [key: string]: string | number;
+}
+
+/**
+ * Chart data point
+ */
+export interface ChartData {
+  /** X-axis label */
+  label: string;
+  /** Y-axis value */
+  value: number;
+  /** Additional data */
+  [key: string]: string | number | boolean;
+}
+
+/**
+ * Funnel step
+ */
+export interface FunnelStep {
+  /** Step name */
+  name: string;
+  /** User count at this step */
+  count: number;
+  /** Conversion rate to this step */
+  conversionRate: number;
+  /** Drop-off rate from previous step */
+  dropOffRate: number;
+  /** Average time spent at step */
+  averageTime?: number;
+}
+
+/**
+ * Funnel data
+ */
+export interface FunnelData {
+  /** Funnel title */
+  title: string;
+  /** Funnel steps */
+  steps: FunnelStep[];
+  /** Total starting users */
+  totalUsers: number;
+  /** Final conversion rate */
+  finalConversion: number;
+}
+
+/**
+ * Cohort analysis data
+ */
+export interface CohortAnalysis {
+  /** Cohort identifier */
+  cohort: string;
+  /** Cohort size */
+  size: number;
+  /** Retention rates over time */
+  retention: number[];
+  /** Average retention rate */
+  averageRetention: number;
+}
+
+/**
+ * User segment
+ */
+export interface UserSegment {
+  /** Segment name */
+  name: string;
+  /** User count */
+  count: number;
+  /** Percentage of total users */
+  percentage: number;
+  /** Segment characteristics */
+  characteristics: string[];
+  /** Behavioral metrics */
+  behavior: {
+    avgSessionDuration: number;
+    pagesPerSession: number;
+    bounceRate: number;
+  };
+}
+
+/**
+ * KPI data with comparison
+ */
+export interface KPIData {
+  /** Current period value */
+  current: number;
+  /** Previous period value */
+  previous: number;
+  /** Growth rate percentage */
+  growth: number;
+}
+
+/**
+ * KPIs container
+ */
+export interface KPIs {
+  downloads: KPIData;
+  engagement: KPIData;
+  users: KPIData;
+  revenue: KPIData;
+  retention: KPIData;
+}
+
+/**
+ * Chart types
+ */
+export type ChartType =
+  | "line"
+  | "bar"
+  | "area"
+  | "pie"
+  | "donut"
+  | "funnel"
+  | "heatmap"
+  | "metric"
+  | "table";
+
+/**
+ * Chart configuration
+ */
+export interface ChartConfig {
+  /** Chart type */
+  type: ChartType;
+  /** Chart title */
+  title?: string;
+  /** Chart description */
+  description?: string;
+  /** Data */
+  data: TimeSeriesData[] | ChartData[] | Metric[];
+  /** X-axis key */
+  xAxisKey?: string;
+  /** Y-axis keys */
+  yAxisKeys?: string[];
+  /** Color scheme */
+  colors?: string[];
+  /** Show legend */
+  showLegend?: boolean;
+  /** Show grid */
+  showGrid?: boolean;
+  /** Show tooltip */
+  showTooltip?: boolean;
+  /** Chart height */
+  height?: number | string;
+  /** Chart aspect ratio */
+  aspectRatio?: string;
+}
+
+/**
+ * Metric card props
+ */
+export interface MetricCardProps {
+  /** Metric data */
+  metric: Metric;
+  /** Card size variant */
+  size?: "sm" | "md" | "lg";
+  /** Show trend indicator */
+  showTrend?: boolean;
+  /** Show icon */
+  showIcon?: boolean;
+  /** Custom class name */
+  className?: string;
+  /** On click handler */
+  onClick?: () => void;
+}
+
+/**
+ * Analytics card props
+ */
+export interface AnalyticsCardProps {
+  /** Card title */
+  title?: string;
+  /** Card description */
+  description?: string;
+  /** Chart configuration */
+  chart?: ChartConfig;
+  /** Metrics to display */
+  metrics?: Metric[];
+  /** Card size */
+  size?: "sm" | "md" | "lg" | "full";
+  /** Loading state */
+  loading?: boolean;
+  /** Error message */
+  error?: string;
+  /** Custom class name */
+  className?: string;
+  /** Children content */
+  children?: React.ReactNode;
+}
+
+/**
+ * Analytics layout props
+ */
+export interface AnalyticsLayoutProps {
+  /** Page title */
+  title?: string;
+  /** Page description */
+  description?: string;
+  /** Date range selector */
+  showDateRange?: boolean;
+  /** Refresh button */
+  showRefresh?: boolean;
+  /** Export button */
+  showExport?: boolean;
+  /** KPI cards */
+  kpis?: KPIs;
+  /** Charts configuration */
+  charts?: ChartConfig[];
+  /** Custom header content */
+  headerContent?: React.ReactNode;
+  /** Children content */
+  children?: React.ReactNode;
+}
+
+/**
+ * Date range preset
+ */
+export interface DateRangePreset {
+  /** Preset label */
+  label: string;
+  /** Preset value */
+  value: string;
+  /** Number of days */
+  days: number;
+}
+
+/**
+ * Date range value
+ */
+export interface DateRangeValue {
+  /** Start date */
+  from: string;
+  /** End date */
+  to: string;
+  /** Preset label */
+  preset?: string;
+}
+
+/**
+ * Export format
+ */
+export type ExportFormat = "csv" | "json" | "xlsx" | "pdf";
+
+/**
+ * Analytics export options
+ */
+export interface AnalyticsExportOptions {
+  /** Export format */
+  format: ExportFormat;
+  /** Include charts */
+  includeCharts?: boolean;
+  /** Include metrics */
+  includeMetrics?: boolean;
+  /** Date range */
+  dateRange?: DateRangeValue;
+  /** Filename */
+  filename?: string;
+}

package/src/domains/analytics/types/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Analytics Types
+ *
+ * Export all analytics-related types
+ */
+
+export type {
+  Metric,
+  TimeSeriesData,
+  ChartData,
+  FunnelStep,
+  FunnelData,
+  CohortAnalysis,
+  UserSegment,
+  KPIData,
+  KPIs,
+  ChartType,
+  ChartConfig,
+  MetricCardProps,
+  AnalyticsCardProps,
+  AnalyticsLayoutProps,
+  DateRangePreset,
+  DateRangeValue,
+  ExportFormat,
+  AnalyticsExportOptions,
+} from "./analytics";