@umituz/web-dashboard 3.2.4 → 4.0.0

package/src/domains/analytics/services/PerformanceService.ts

@@ -37,70 +37,93 @@ export interface RealtimeMetrics {
   revenue: number;
 }
 
+/**
+ * Chrome-specific `performance.memory` shape (not in standard lib types).
+ */
+interface PerformanceMemoryLike {
+  usedJSHeapSize: number;
+}
+
+/**
+ * Layout-shift and first-input entry shapes (not in standard lib types
+ * for all TS versions). Structurally typed — no `any`.
+ */
+interface LayoutShiftEntry extends PerformanceEntry {
+  value: number;
+}
+
+interface FirstInputEntry extends PerformanceEntry {
+  processingStart: number;
+}
+
+const isLayoutShiftEntry = (entry: PerformanceEntry): entry is LayoutShiftEntry =>
+  typeof (entry as LayoutShiftEntry).value === 'number';
+
+const isFirstInputEntry = (entry: PerformanceEntry): entry is FirstInputEntry =>
+  typeof (entry as FirstInputEntry).processingStart === 'number';
+
 /**
  * Performance Service
  *
- * Monitors dashboard performance and provides real-time metrics
+ * Monitors dashboard performance and provides real-time metrics.
+ * Web-vitals observation is opt-in via `startMonitoring()` so that
+ * importing the module never registers browser observers as a side effect.
  */
 export class PerformanceService {
   private metrics: Map<string, PerformanceMetric[]> = new Map();
   private observers: PerformanceObserver[] = [];
 
-  constructor() {
-    if (typeof window !== 'undefined') {
-      this.initializeObservers();
-    }
-  }
-
   /**
-   * Initialize performance observers
+   * Register web-vitals observers (CLS / LCP / FID).
+   * Idempotent — calling it twice will not duplicate observers.
    */
-  private initializeObservers(): void {
-    if ('PerformanceObserver' in window) {
-      // Observe layout shifts
-      try {
-        const observer = new PerformanceObserver((list) => {
-          for (const entry of list.getEntries()) {
-            if (entry.entryType === 'layout-shift') {
-              this.recordMetric('CLS', (entry as any).value, 'score', 0.1);
-            }
+  public startMonitoring(): void {
+    if (typeof window === 'undefined' || !('PerformanceObserver' in window)) return;
+    if (this.observers.length > 0) return;
+
+    // Observe layout shifts
+    try {
+      const observer = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          if (entry.entryType === 'layout-shift' && isLayoutShiftEntry(entry)) {
+            this.recordMetric('CLS', entry.value, 'score', 0.1);
           }
-        });
-        observer.observe({ entryTypes: ['layout-shift'] });
-        this.observers.push(observer);
-      } catch (e) {
-        // Layout Shift API not supported
-      }
+        }
+      });
+      observer.observe({ entryTypes: ['layout-shift'] });
+      this.observers.push(observer);
+    } catch {
+      // Layout Shift API not supported
+    }
 
-      // Observe largest contentful paint
-      try {
-        const observer = new PerformanceObserver((list) => {
-          for (const entry of list.getEntries()) {
-            if (entry.entryType === 'largest-contentful-paint') {
-              this.recordMetric('LCP', entry.startTime, 'ms', 2500);
-            }
+    // Observe largest contentful paint
+    try {
+      const observer = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          if (entry.entryType === 'largest-contentful-paint') {
+            this.recordMetric('LCP', entry.startTime, 'ms', 2500);
           }
-        });
-        observer.observe({ entryTypes: ['largest-contentful-paint'] });
-        this.observers.push(observer);
-      } catch (e) {
-        // LCP API not supported
-      }
+        }
+      });
+      observer.observe({ entryTypes: ['largest-contentful-paint'] });
+      this.observers.push(observer);
+    } catch {
+      // LCP API not supported
+    }
 
-      // Observe first input delay
-      try {
-        const observer = new PerformanceObserver((list) => {
-          for (const entry of list.getEntries()) {
-            if (entry.entryType === 'first-input') {
-              this.recordMetric('FID', (entry as any).processingStart - entry.startTime, 'ms', 100);
-            }
+    // Observe first input delay
+    try {
+      const observer = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          if (entry.entryType === 'first-input' && isFirstInputEntry(entry)) {
+            this.recordMetric('FID', entry.processingStart - entry.startTime, 'ms', 100);
           }
-        });
-        observer.observe({ entryTypes: ['first-input'] });
-        this.observers.push(observer);
-      } catch (e) {
-        // FID API not supported
-      }
+        }
+      });
+      observer.observe({ entryTypes: ['first-input'] });
+      this.observers.push(observer);
+    } catch {
+      // FID API not supported
     }
   }
 
@@ -186,19 +209,12 @@ export class PerformanceService {
    * @returns Dashboard performance data
    */
   public getDashboardMetrics(): DashboardMetrics {
-    const timing = typeof window !== 'undefined' ? window.performance?.timing : null;
-    const navigation = typeof window !== 'undefined' ? window.performance?.navigation : null;
-
-    const loadTime = timing
-      ? timing.loadEventEnd - timing.navigationStart
-      : this.getLatestMetric('loadTime')?.value || 0;
+    const loadTime =
+      this.getNavigationLoadTime() ?? this.getLatestMetric('loadTime')?.value ?? 0;
 
     const renderTime = this.getLatestMetric('renderTime')?.value || 0;
     const apiResponseTime = this.getLatestMetric('apiResponseTime')?.value || 0;
-    const memoryUsage =
-      typeof (performance as any).memory !== 'undefined'
-        ? (performance as any).memory.usedJSHeapSize / 1048576
-        : 0;
+    const memoryUsage = this.getMemoryUsageMb();
 
     const errorRate = this.calculateErrorRate();
 
@@ -212,6 +228,31 @@ export class PerformanceService {
     };
   }
 
+  /**
+   * Page load time from the modern Navigation Timing API.
+   * Returns null when the API or the entry is unavailable.
+   */
+  private getNavigationLoadTime(): number | null {
+    if (typeof performance === 'undefined' || typeof performance.getEntriesByType !== 'function') {
+      return null;
+    }
+
+    // getEntriesByType is typed as PerformanceEntry[]; navigation entries
+    // are the only ones with loadEventEnd, hence the narrowing cast.
+    const [navigation] = performance.getEntriesByType('navigation') as PerformanceNavigationTiming[];
+    if (!navigation || navigation.loadEventEnd <= 0) return null;
+    return navigation.loadEventEnd - navigation.startTime;
+  }
+
+  /**
+   * JS heap usage in MB via the Chrome-only `performance.memory`.
+   * Returns 0 where unavailable (all other browsers, Node).
+   */
+  private getMemoryUsageMb(): number {
+    const memory = (performance as Performance & { memory?: PerformanceMemoryLike }).memory;
+    return typeof memory !== 'undefined' ? memory.usedJSHeapSize / 1048576 : 0;
+  }
+
   /**
    * Calculate error rate from metrics
    *
@@ -280,20 +321,27 @@ export class PerformanceService {
   }
 
   /**
-   * Measure page load time
+   * Measure page load time.
+   * Records immediately if the page already loaded; otherwise listens once.
    */
   public measurePageLoad(): void {
-    if (typeof window === 'undefined' || !window.performance) return;
+    if (typeof window === 'undefined' || typeof window.performance === 'undefined') return;
+
+    const record = () => {
+      const loadTime = this.getNavigationLoadTime();
+      if (loadTime !== null) {
+        this.recordMetric('loadTime', loadTime, 'ms', 3000);
+      }
+    };
+
+    if (document.readyState === 'complete') {
+      record();
+      return;
+    }
 
     window.addEventListener('load', () => {
-      setTimeout(() => {
-        const timing = window.performance?.timing;
-        if (timing) {
-          const loadTime = timing.loadEventEnd - timing.navigationStart;
-          this.recordMetric('loadTime', loadTime, 'ms', 3000);
-        }
-      }, 0);
-    });
+      setTimeout(record, 0);
+    }, { once: true });
   }
 
   /**

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

@@ -4,7 +4,7 @@
  * Type definitions for analytics system
  */
 
-import type { ComponentType, ReactElement } from "react";
+import type { ComponentType } from "react";
 
 /**
  * Metric card data
@@ -153,6 +153,8 @@ export type ChartType =
  * Chart configuration
  */
 export interface ChartConfig {
+  /** Stable identifier — used as React key, also for telemetry */
+  id: string;
   /** Chart type */
   type: ChartType;
   /** Chart title */
@@ -165,7 +167,7 @@ export interface ChartConfig {
   xAxisKey?: string;
   /** Y-axis keys */
   yAxisKeys?: string[];
-  /** Color scheme */
+  /** Color scheme (CSS variable names, e.g. "hsl(var(--primary))") */
   colors?: string[];
   /** Show legend */
   showLegend?: boolean;
@@ -179,6 +181,12 @@ export interface ChartConfig {
   aspectRatio?: string;
 }
 
+/**
+ * Supported analytics period tokens.
+ * Typed union to prevent stringly-typed comparison elsewhere.
+ */
+export type AnalyticsPeriod = '7d' | '30d' | '90d' | '1y' | (string & {});
+
 /**
  * Metric card props
  */
@@ -236,19 +244,21 @@ export interface AnalyticsLayoutProps {
   /** Loading state */
   loading?: boolean;
   /** Current period */
-  period?: string;
+  period?: AnalyticsPeriod;
   /** Period change handler */
-  onPeriodChange?: (period: string) => void;
+  onPeriodChange?: (period: AnalyticsPeriod) => void;
   /** Date range selector */
   showDateRange?: boolean;
   /** Refresh button */
   showRefresh?: boolean;
   /** Export button */
   showExport?: boolean;
-  /** KPI cards */
-  kpis?: KPIs;
   /** Charts configuration */
   charts?: ChartConfig[];
+  /** Refresh handler — required when showRefresh is true */
+  onRefresh?: () => void;
+  /** Export handler — required when showExport is true */
+  onExport?: () => void;
   /** Custom header content */
   headerContent?: React.ReactNode;
   /** Children content */
@@ -265,6 +275,10 @@ export interface DateRangePreset {
   value: string;
   /** Number of days */
   days: number;
+  /** Range start (ISO yyyy-mm-dd), resolved at creation time */
+  from?: string;
+  /** Range end (ISO yyyy-mm-dd), resolved at creation time */
+  to?: string;
 }
 
 /**

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

@@ -19,6 +19,9 @@ export type {
   MetricCardProps,
   AnalyticsCardProps,
   AnalyticsLayoutProps,
+  AnalyticsPeriod,
+  AnalyticsConfig,
+  MetricConfig,
   DateRangePreset,
   DateRangeValue,
   ExportFormat,

package/src/domains/analytics/utils/analytics.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Tests for pure analytics utility functions.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  formatNumber,
+  formatPercentage,
+  formatCurrency,
+  calculateGrowth,
+  getTrend,
+  calculateConversionRate,
+  calculateDropOffRate,
+  calculateMovingAverage,
+  detectOutliers,
+  aggregateByPeriod,
+  roundTo,
+  createDateRangePreset,
+} from "./analytics";
+
+describe("formatNumber", () => {
+  it("keeps whole numbers below 1K whole", () => {
+    expect(formatNumber(999)).toBe("999");
+    expect(formatNumber(42)).toBe("42");
+  });
+
+  it("abbreviates at the K/M/B thresholds", () => {
+    expect(formatNumber(1000)).toBe("1.0K");
+    expect(formatNumber(1500)).toBe("1.5K");
+    expect(formatNumber(2_500_000)).toBe("2.5M");
+    expect(formatNumber(3_000_000_000)).toBe("3.0B");
+  });
+
+  it("respects the decimals argument", () => {
+    expect(formatNumber(1234, 2)).toBe("1.23K");
+  });
+});
+
+describe("formatPercentage", () => {
+  it("appends % to a rounded value", () => {
+    expect(formatPercentage(12.345)).toBe("12.3%");
+  });
+
+  it("passes through negatives and values above 100 (generic formatter)", () => {
+    expect(formatPercentage(-5)).toBe("-5.0%");
+    expect(formatPercentage(120)).toBe("120.0%");
+  });
+});
+
+describe("formatCurrency", () => {
+  it("formats USD by default", () => {
+    expect(formatCurrency(10)).toBe("$10");
+  });
+
+  it("honors the locale parameter", () => {
+    // Signature is (value, currency, decimals, locale); the assertions
+    // expect 2 decimal places, which "en-US"/"de-DE" format as ,50 / ,50.
+    expect(formatCurrency(1234.5, "USD", 2, "en-US")).toBe("$1,234.50");
+    expect(formatCurrency(1234.5, "EUR", 2, "de-DE")).toContain("1.234,50");
+  });
+});
+
+describe("calculateGrowth", () => {
+  it("treats growth from zero as 100% (or 0 when nothing grew)", () => {
+    expect(calculateGrowth(50, 0)).toBe(100);
+    expect(calculateGrowth(0, 0)).toBe(0);
+  });
+
+  it("computes positive growth as a percentage", () => {
+    expect(calculateGrowth(150, 100)).toBe(50);
+  });
+
+  it("computes negative growth", () => {
+    expect(calculateGrowth(50, 100)).toBe(-50);
+  });
+});
+
+describe("getTrend", () => {
+  it("treats ±0.1 as stable", () => {
+    expect(getTrend(0)).toBe("stable");
+    expect(getTrend(0.1)).toBe("stable");
+    expect(getTrend(-0.1)).toBe("stable");
+  });
+
+  it("detects up and down beyond the threshold", () => {
+    expect(getTrend(0.2)).toBe("up");
+    expect(getTrend(-0.2)).toBe("down");
+  });
+});
+
+describe("calculateConversionRate", () => {
+  it("returns 0 for an empty total", () => {
+    expect(calculateConversionRate(5, 0)).toBe(0);
+  });
+
+  it("computes the percentage", () => {
+    expect(calculateConversionRate(25, 100)).toBe(25);
+  });
+});
+
+describe("calculateDropOffRate", () => {
+  it("returns 0 when the previous step is 0", () => {
+    expect(calculateDropOffRate(10, 0)).toBe(0);
+  });
+
+  it("computes drop-off between steps", () => {
+    expect(calculateDropOffRate(25, 100)).toBe(75);
+  });
+});
+
+describe("calculateMovingAverage", () => {
+  it("throws for a non-positive window", () => {
+    expect(() => calculateMovingAverage([1, 2], 0)).toThrow(RangeError);
+  });
+
+  it("returns an empty array for empty input", () => {
+    expect(calculateMovingAverage([], 3)).toEqual([]);
+  });
+
+  it("emits a trailing average per point (partial windows at the start)", () => {
+    expect(calculateMovingAverage([1, 2, 3], 2)).toEqual([1, 1.5, 2.5]);
+  });
+});
+
+describe("detectOutliers", () => {
+  it("returns [] for an empty series", () => {
+    expect(detectOutliers([])).toEqual([]);
+  });
+
+  it("returns indices of values beyond 2 standard deviations", () => {
+    // mean ≈ 16.7, population stdev ≈ 14.9 → only 50 exceeds 2σ.
+    expect(detectOutliers([10, 10, 10, 10, 10, 50])).toEqual([5]);
+  });
+
+  it("returns no indices for a uniform series", () => {
+    expect(detectOutliers([7, 7, 7, 7])).toEqual([]);
+  });
+});
+
+describe("aggregateByPeriod", () => {
+  it("sums numeric fields per day bucket", () => {
+    const result = aggregateByPeriod(
+      [
+        { date: "2026-01-01", value: 10 },
+        { date: "2026-01-01", value: 5 },
+        { date: "2026-01-02", value: 7 },
+      ],
+      "day",
+    );
+    expect(result).toEqual([
+      { date: "2026-01-01", value: 15 },
+      { date: "2026-01-02", value: 7 },
+    ]);
+  });
+
+  it("groups by month key when period is month", () => {
+    const result = aggregateByPeriod(
+      [
+        { date: "2026-01-05", value: 1 },
+        { date: "2026-01-25", value: 2 },
+      ],
+      "month",
+    );
+    expect(result).toEqual([{ date: "2026-01", value: 3 }]);
+  });
+});
+
+describe("roundTo", () => {
+  it("rounds to the given decimals", () => {
+    expect(roundTo(3.14159, 2)).toBe(3.14);
+  });
+});
+
+describe("createDateRangePreset", () => {
+  it("resolves from/to dates around today", () => {
+    const preset = createDateRangePreset("Last 7 Days", 7);
+    const today = new Date().toISOString().split("T")[0];
+    expect(preset.value).toBe("last-7-days");
+    expect(preset.to).toBe(today);
+    expect(preset.from).toBeDefined();
+    expect(preset.from).not.toBe(preset.to);
+  });
+});

package/src/domains/analytics/utils/analytics.ts

@@ -4,6 +4,8 @@
  * Helper functions for analytics operations
  */
 
+import type { TimeSeriesData } from "../types/analytics";
+
 import type { Metric, KPIData, DateRangePreset } from "../types/analytics";
 
 /**
@@ -23,7 +25,8 @@ export function formatNumber(num: number, decimals: number = 1): string {
   if (num >= 1_000) {
     return (num / 1_000).toFixed(decimals) + "K";
   }
-  return num.toFixed(decimals);
+  // Whole numbers stay whole ("999", not "999.0")
+  return Number.isInteger(num) ? num.toString() : num.toFixed(decimals);
 }
 
 /**
@@ -43,14 +46,16 @@ export function formatPercentage(value: number, decimals: number = 1): string {
  * @param value - Value to format
  * @param currency - Currency code (default: USD)
  * @param decimals - Number of decimal places (default: 0)
+ * @param locale - BCP 47 locale (default: en-US)
  * @returns Formatted currency string
  */
 export function formatCurrency(
   value: number,
   currency: string = "USD",
-  decimals: number = 0
+  decimals: number = 0,
+  locale: string = "en-US"
 ): string {
-  return new Intl.NumberFormat("en-US", {
+  return new Intl.NumberFormat(locale, {
     style: "currency",
     currency,
     minimumFractionDigits: decimals,
@@ -180,7 +185,7 @@ export function calculateDropOffRate(current: number, previous: number): number
  *
  * @param label - Preset label
  * @param days - Number of days
- * @returns Date range preset
+ * @returns Date range preset with resolved `from`/`to` ISO dates
  */
 export function createDateRangePreset(label: string, days: number): DateRangePreset {
   const to = new Date();
@@ -191,6 +196,8 @@ export function createDateRangePreset(label: string, days: number): DateRangePre
     label,
     value: label.toLowerCase().replace(/\s+/g, "-"),
     days,
+    from: from.toISOString().split("T")[0],
+    to: to.toISOString().split("T")[0],
   };
 }
 
@@ -240,17 +247,21 @@ export function aggregateByPeriod(
     if (!grouped.has(key)) {
       grouped.set(key, []);
     }
-    grouped.get(key)!.push(item);
+    const bucket = grouped.get(key);
+    if (bucket) {
+      bucket.push(item);
+    }
   });
 
   return Array.from(grouped.entries()).map(([date, items]) => {
-    const aggregated: any = { date };
+    const aggregated: TimeSeriesData = { date };
 
-    // Sum all numeric fields
     items.forEach((item) => {
       Object.entries(item).forEach(([key, value]) => {
-        if (key !== "date" && typeof value === "number") {
-          aggregated[key] = (aggregated[key] || 0) + value;
+        if (key === "date") return;
+        if (typeof value === "number") {
+          const current = (aggregated[key] as number | undefined) ?? 0;
+          aggregated[key] = current + value;
         }
       });
     });
@@ -267,6 +278,10 @@ export function aggregateByPeriod(
  * @returns Array of moving averages
  */
 export function calculateMovingAverage(data: number[], window: number): number[] {
+  if (window < 1) {
+    throw new RangeError(`calculateMovingAverage: window must be >= 1, received ${window}`);
+  }
+
   const result: number[] = [];
 
   for (let i = 0; i < data.length; i++) {
@@ -287,6 +302,8 @@ export function calculateMovingAverage(data: number[], window: number): number[]
  * @returns Array of outlier indices
  */
 export function detectOutliers(data: number[], threshold: number = 2): number[] {
+  if (data.length === 0) return [];
+
   const mean = data.reduce((sum, val) => sum + val, 0) / data.length;
   const variance = data.reduce((sum, val) => sum + Math.pow(val - mean, 2), 0) / data.length;
   const stdDev = Math.sqrt(variance);

package/src/domains/analytics/utils/i18nKeys.ts

@@ -0,0 +1,40 @@
+/**
+ * Analytics Domain i18n Keys
+ */
+
+export const ANALYTICS_KEYS = {
+  // Common
+  common: {
+    export: 'analytics.common.export',
+    refresh: 'analytics.common.refresh',
+    periodSelector: 'analytics.common.periodSelector',
+    lastPeriod: 'analytics.common.lastPeriod',
+    last7Days: 'analytics.common.last7Days',
+    last30Days: 'analytics.common.last30Days',
+    last90Days: 'analytics.common.last90Days',
+    lastYear: 'analytics.common.lastYear',
+    loading: 'analytics.common.loading',
+  },
+
+  // Metric card
+  metric: {
+    noData: 'analytics.metric.noData',
+    change: 'analytics.metric.change',
+  },
+
+  // Analytics card
+  card: {
+    title: 'analytics.card.title',
+  },
+
+  // Chart
+  chart: {
+    noData: 'analytics.chart.noData',
+  },
+
+  // Layout
+  layout: {
+    title: 'analytics.layout.title',
+    export: 'analytics.layout.export',
+  },
+} as const;

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

@@ -24,3 +24,5 @@ export {
   generateColor,
   generateChartColors,
 } from "./analytics";
+
+export { ANALYTICS_KEYS } from "./i18nKeys";