@umituz/web-dashboard 6.1.0 → 6.2.0

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

@@ -1,132 +1,66 @@
-/**
- * Analytics Types
- *
- * Type definitions for analytics system
- */
-
 import type { ComponentType } 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 }>;
+    id: string;
+    name: string;
+    value: number;
+    previousValue?: number;
+    unit?: string;
+    trend?: "up" | "down" | "stable";
+    icon?: ComponentType<{ className?: string }>;
 }
 
-/**
- * Time series data point
- */
 export interface TimeSeriesData {
-  /** Date/label */
-  date: string;
-  /** Metric values */
-  [key: string]: string | number;
+    date: string;
+    [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;
+    label: string;
+    value: number;
+    [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;
+    name: string;
+    count: number;
+    conversionRate: number;
+    dropOffRate: number;
+    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;
+    title: string;
+    steps: FunnelStep[];
+    totalUsers: number;
+    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;
+    cohort: string;
+    size: number;
+    retention: number[];
+    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: {
+    name: string;
+    count: number;
+    percentage: number;
+    characteristics: string[];
+    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;
+    current: number;
+    previous: number;
+    growth: number;
 }
 
-/**
- * KPIs container
- */
 export interface KPIs {
   downloads: KPIData;
   engagement: KPIData;
@@ -135,9 +69,6 @@ export interface KPIs {
   retention: KPIData;
 }
 
-/**
- * Chart types
- */
 export type ChartType =
   | "line"
   | "bar"
@@ -149,202 +80,101 @@ export type ChartType =
   | "metric"
   | "table";
 
-/**
- * Chart configuration
- */
 export interface ChartConfig {
-  /** Stable identifier — used as React key, also for telemetry */
-  id: string;
-  /** 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 (CSS variable names, e.g. "hsl(var(--primary))") */
-  colors?: string[];
-  /** Show legend */
-  showLegend?: boolean;
-  /** Show grid */
-  showGrid?: boolean;
-  /** Show tooltip */
-  showTooltip?: boolean;
-  /** Chart height */
-  height?: number | string;
-  /** Chart aspect ratio */
-  aspectRatio?: string;
+    id: string;
+    type: ChartType;
+    title?: string;
+    description?: string;
+    data: TimeSeriesData[] | ChartData[] | Metric[];
+    xAxisKey?: string;
+    yAxisKeys?: string[];
+    colors?: string[];
+    showLegend?: boolean;
+    showGrid?: boolean;
+    showTooltip?: boolean;
+    height?: number | string;
+    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
- */
 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;
+    metric: Metric;
+    size?: "sm" | "md" | "lg";
+    showTrend?: boolean;
+    showIcon?: boolean;
+    className?: string;
+    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;
+    title?: string;
+    description?: string;
+    chart?: ChartConfig;
+    metrics?: Metric[];
+    size?: "sm" | "md" | "lg" | "full";
+    loading?: boolean;
+    error?: string;
+    className?: string;
+    children?: React.ReactNode;
 }
 
-/**
- * Analytics layout props
- */
 export interface AnalyticsLayoutProps {
-  /** Analytics configuration */
-  config?: AnalyticsConfig;
-  /** Page title */
-  title?: string;
-  /** Page description */
-  description?: string;
-  /** Metrics data */
-  metrics?: Metric[];
-  /** Loading state */
-  loading?: boolean;
-  /** Current period */
-  period?: AnalyticsPeriod;
-  /** Period change handler */
-  onPeriodChange?: (period: AnalyticsPeriod) => void;
-  /** Date range selector */
-  showDateRange?: boolean;
-  /** Refresh button */
-  showRefresh?: boolean;
-  /** Export button */
-  showExport?: boolean;
-  /** 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 */
-  children?: React.ReactNode;
+    config?: AnalyticsConfig;
+    title?: string;
+    description?: string;
+    metrics?: Metric[];
+    loading?: boolean;
+    period?: AnalyticsPeriod;
+    onPeriodChange?: (period: AnalyticsPeriod) => void;
+    showDateRange?: boolean;
+    showRefresh?: boolean;
+    showExport?: boolean;
+    charts?: ChartConfig[];
+    onRefresh?: () => void;
+    onExport?: () => void;
+    headerContent?: React.ReactNode;
+    children?: React.ReactNode;
 }
 
-/**
- * Date range preset
- */
 export interface DateRangePreset {
-  /** Preset label */
-  label: string;
-  /** Preset value */
-  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;
+    label: string;
+    value: string;
+    days: number;
+    from?: string;
+    to?: string;
 }
 
-/**
- * Date range value
- */
 export interface DateRangeValue {
-  /** Start date */
-  from: string;
-  /** End date */
-  to: string;
-  /** Preset label */
-  preset?: string;
+    from: string;
+    to: string;
+    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;
+    format: ExportFormat;
+    includeCharts?: boolean;
+    includeMetrics?: boolean;
+    dateRange?: DateRangeValue;
+    filename?: string;
 }
 
-/**
- * Analytics configuration
- */
 export interface AnalyticsConfig {
-  /** Brand/application name */
-  brandName: string;
-  /** Default period selection */
-  defaultPeriod?: string;
-  /** Available period options */
-  availablePeriods?: string[];
-  /** Show export button */
-  showExport?: boolean;
-  /** Show refresh button */
-  showRefresh?: boolean;
-  /** Enable real-time updates */
-  enableRealTime?: boolean;
-  /** Metrics configuration */
-  metrics?: MetricConfig[];
+    brandName: string;
+    defaultPeriod?: string;
+    availablePeriods?: string[];
+    showExport?: boolean;
+    showRefresh?: boolean;
+    enableRealTime?: boolean;
+    metrics?: MetricConfig[];
 }
 
-/**
- * Metric configuration
- */
 export interface MetricConfig {
-  /** Metric identifier */
-  id: string;
-  /** Metric name */
-  name: string;
-  /** Unit type */
-  unit?: string;
-  /** Icon identifier */
-  icon?: string;
+    id: string;
+    name: string;
+    unit?: string;
+    icon?: string;
 }
 

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

@@ -1,9 +1,3 @@
-/**
- * Analytics Types
- *
- * Export all analytics-related types
- */
-
 export type {
   Metric,
   TimeSeriesData,

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

@@ -1,7 +1,3 @@
-/**
- * Tests for pure analytics utility functions.
- */
-
 import { describe, it, expect } from "vitest";
 import {
   formatNumber,
@@ -53,9 +49,7 @@ describe("formatCurrency", () => {
   });
 
   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, "USD", 2, "en-US")).toBe("$1,234.50");
     expect(formatCurrency(1234.5, "EUR", 2, "de-DE")).toContain("1.234,50");
   });
 });
@@ -128,8 +122,7 @@ describe("detectOutliers", () => {
   });
 
   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]);
+        expect(detectOutliers([10, 10, 10, 10, 10, 50])).toEqual([5]);
   });
 
   it("returns no indices for a uniform series", () => {

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

@@ -1,20 +1,7 @@
-/**
- * Analytics Utilities
- *
- * Helper functions for analytics operations
- */
-
 import type { TimeSeriesData } from "../types/analytics";
 
 import type { Metric, KPIData, DateRangePreset } from "../types/analytics";
 
-/**
- * Format number with K/M/B suffixes
- *
- * @param num - Number to format
- * @param decimals - Number of decimal places (default: 1)
- * @returns Formatted string
- */
 export function formatNumber(num: number, decimals: number = 1): string {
   if (num >= 1_000_000_000) {
     return (num / 1_000_000_000).toFixed(decimals) + "B";
@@ -25,17 +12,9 @@ export function formatNumber(num: number, decimals: number = 1): string {
   if (num >= 1_000) {
     return (num / 1_000).toFixed(decimals) + "K";
   }
-  // Whole numbers stay whole ("999", not "999.0")
-  return Number.isInteger(num) ? num.toString() : num.toFixed(decimals);
+    return Number.isInteger(num) ? num.toString() : num.toFixed(decimals);
 }
 
-/**
- * Format percentage
- *
- * @param value - Value to format as percentage
- * @param decimals - Number of decimal places (default: 1)
- * @returns Formatted string with % suffix
- */
 export function formatPercentage(value: number, decimals: number = 1): string {
   return `${value.toFixed(decimals)}%`;
 }

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

@@ -1,9 +1,3 @@
-/**
- * Analytics Utilities
- *
- * Export all analytics utilities
- */
-
 export {
   formatNumber,
   formatPercentage,

package/src/domains/calendar/config.ts

@@ -1,12 +1,5 @@
-/**
- * Calendar Configuration
- */
-
 import type { CalendarConfig } from './types/calendar.types';
 
-/**
- * Default calendar configuration
- */
 export const DEFAULT_CALENDAR_CONFIG: CalendarConfig = {
   defaultView: 'month',
   showWeekends: true,

package/src/domains/calendar/hooks/index.ts

@@ -1,5 +1 @@
-/**
- * Calendar Hooks Index
- */
-
 export * from './useCalendar';

package/src/domains/calendar/hooks/useCalendar.ts

@@ -1,12 +1,3 @@
-/**
- * useCalendar
- *
- * React hook for the calendar domain. Delegates persistence
- * to the injected `CalendarService`, guards refreshes with a
- * request id so a stale response can never overwrite a newer one,
- * and returns a clean discriminated CRUD contract.
- */
-
 import { useState, useCallback, useEffect, useMemo, useRef } from 'react';
 import type {
   CalendarConfig,
@@ -20,14 +11,10 @@ import type { ICalendarService } from '../types/calendar.types';
 type CalendarView = 'month' | 'week' | 'day' | 'timeline';
 
 export interface UseCalendarOptions {
-  /** Calendar configuration overrides */
-  config?: Partial<CalendarConfig>;
-  /** User ID (required to fetch items) */
-  userId: string;
-  /** Error callback — receives the original Error */
-  onError?: (error: Error) => void;
-  /** Override the default service (useful for tests) */
-  service?: ICalendarService;
+    config?: Partial<CalendarConfig>;
+    userId: string;
+    onError?: (error: Error) => void;
+    service?: ICalendarService;
 }
 
 export interface UseCalendarReturn {
@@ -77,17 +64,12 @@ export function useCalendar(options: UseCalendarOptions): UseCalendarReturn {
   const [selectedDate, setSelectedDate] = useState(() => new Date());
   const [filter, setFilterState] = useState<CalendarFilter>({});
 
-  // Keep the latest onError in a ref so refresh identity stays stable
-  // when consumers pass a fresh closure each render.
-  const onErrorRef = useRef(onError);
+      const onErrorRef = useRef(onError);
   useEffect(() => {
     onErrorRef.current = onError;
   }, [onError]);
 
-  // Guards against out-of-order responses: only the most recent
-  // refresh may commit state (e.g. user changes the filter while a
-  // previous fetch is still resolving).
-  const requestIdRef = useRef(0);
+        const requestIdRef = useRef(0);
 
   const refresh = useCallback(async () => {
     if (!userId) {
@@ -178,9 +160,7 @@ export function useCalendar(options: UseCalendarOptions): UseCalendarReturn {
     setFilterState((prev) => ({ ...prev, ...updates }));
   }, []);
 
-  // Single source of truth for filtering (shared with the service layer)
-  // so client-side refiltering can never drift from server-side semantics.
-  const filteredItems = useMemo(
+      const filteredItems = useMemo(
     () => applyCalendarFilter(items, filter),
     [items, filter],
   );

package/src/domains/calendar/index.ts

@@ -1,7 +1,3 @@
-/**
- * Calendar Domain Index
- */
-
 export * from './types/calendar.types';
 export * from './config';
 export * from './services';

package/src/domains/calendar/services/CalendarService.ts

@@ -1,13 +1,3 @@
-/**
- * Calendar Service
- *
- * Camp-agnostic calendar service for managing content items.
- * Persistence is injected via the `ICalendarDatabase` seam — the
- * package ships no Firebase (or any other) backend. Use
- * `createInMemoryCalendarDatabase()` for demos and tests, or adapt
- * your own backend to the interface.
- */
-
 import type {
   ContentItem,
   CalendarFilter,
@@ -16,10 +6,6 @@ import type {
   ICalendarService,
 } from '../types/calendar.types';
 
-/**
- * Database interface for calendar operations
- * Implementations can provide different backends
- */
 export interface ICalendarDatabase {
   getItems(userId: string): Promise<ContentItem[]>;
   getItemById(id: string): Promise<ContentItem | null>;
@@ -28,9 +14,6 @@ export interface ICalendarDatabase {
   deleteItem(id: string): Promise<void>;
 }
 
-/**
- * Resolve scheduled_at to ISO string regardless of source type
- */
 const resolveScheduledAt = (value: string | Date | undefined): string => {
   if (value === undefined) {
     throw new Error('scheduled_at is required to create or update a content item');
@@ -39,10 +22,6 @@ const resolveScheduledAt = (value: string | Date | undefined): string => {
   return value.toISOString();
 };
 
-/**
- * In-memory calendar database — zero-dependency default for demos
- * and tests. Data lives per-instance for the lifetime of the page.
- */
 export const createInMemoryCalendarDatabase = (): ICalendarDatabase => {
   const items = new Map<string, ContentItem>();
 

package/src/domains/calendar/services/index.ts

@@ -1,5 +1 @@
-/**
- * Calendar Services Index
- */
-
 export * from './CalendarService';