@pagamio/frontend-commons-lib 0.8.212 → 0.8.214

package/lib/dashboard-visuals-v2/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Dashboard Visuals V2 - Main exports
+ * ApexCharts-based visualization components
+ */
+export * from './types';
+export { BaseChart, BarChart, LineChart, AreaChart, DonutChart, PieChart, HeatmapChart, RadialChart, MixedChart, } from './charts';
+export { StatCard, MetricCard, InfoCard, CardGrid, StatCardGrid, MetricCardGrid, TransactionListCard, TopItemsCard, } from './cards';
+export { default as visualRegistryV2, VisualType, getVisualComponent, isRegisteredVisual, getRegisteredVisualTypes, registerVisual, } from './visualRegistry';
+export { DashboardWrapperV2, type DashboardWrapperV2Props } from './DashboardWrapperV2';
+export { useChartData, useChartQueryData } from './hooks';

package/lib/dashboard-visuals-v2/index.js

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Dashboard Visuals V2 - Main exports
+ * ApexCharts-based visualization components
+ */
+// Types
+export * from './types';
+// Charts
+export { BaseChart, BarChart, LineChart, AreaChart, DonutChart, PieChart, HeatmapChart, RadialChart, MixedChart, } from './charts';
+// Cards
+export { StatCard, MetricCard, InfoCard, CardGrid, StatCardGrid, MetricCardGrid, TransactionListCard, TopItemsCard, } from './cards';
+// Visual Registry
+export { default as visualRegistryV2, VisualType, getVisualComponent, isRegisteredVisual, getRegisteredVisualTypes, registerVisual, } from './visualRegistry';
+// Dashboard Wrapper
+export { DashboardWrapperV2 } from './DashboardWrapperV2';
+// Hooks
+export { useChartData, useChartQueryData } from './hooks';

package/lib/dashboard-visuals-v2/types/card.types.d.ts

@@ -0,0 +1,237 @@
+/**
+ * @fileoverview Card type definitions for Dashboard Visuals V2
+ */
+import type { ReactNode } from 'react';
+/**
+ * Trend direction for metric comparisons
+ */
+export type TrendDirection = 'up' | 'down' | 'neutral';
+/**
+ * Card variant styles
+ */
+export type CardVariant = 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'gradient' | 'primary-solid' | 'success-solid' | 'warning-solid' | 'danger-solid' | 'purple-solid' | 'orange-solid';
+/**
+ * Card size
+ */
+export type CardSize = 'sm' | 'md' | 'lg';
+/**
+ * Card color presets
+ */
+export type CardColor = 'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info' | 'orange' | 'teal' | 'blue' | 'purple';
+/**
+ * Card action configuration
+ */
+export interface CardAction {
+    /** Action label */
+    label: string;
+    /** Click handler */
+    onClick?: () => void;
+    /** Link href (alternative to onClick) */
+    href?: string;
+    /** Icon element */
+    icon?: ReactNode;
+}
+/**
+ * Base card props shared by all card types
+ */
+export interface BaseCardProps {
+    /** Card title/label */
+    title: string;
+    /** Custom class name */
+    className?: string;
+    /** Class names for sub-components */
+    classNames?: {
+        container?: string;
+        header?: string;
+        title?: string;
+        value?: string;
+        icon?: string;
+        trend?: string;
+        footer?: string;
+        list?: string;
+        item?: string;
+    };
+    /** Loading state */
+    loading?: boolean;
+    /** Error state */
+    error?: Error | string | null;
+    /** Icon element */
+    icon?: ReactNode;
+    /** Click handler for the entire card */
+    onClick?: () => void;
+}
+/**
+ * Value format options
+ */
+export type ValueFormat = 'number' | 'currency' | 'percentage' | 'compact' | 'decimal';
+/**
+ * Stat card props - Main metric display card
+ */
+export interface StatCardProps extends BaseCardProps {
+    /** Numeric value to display */
+    value: number | string;
+    /** Value format type */
+    format?: ValueFormat;
+    /** Currency code (for currency format) */
+    currency?: string;
+    /** Decimal places */
+    decimals?: number;
+    /** Custom value formatter */
+    valueFormatter?: (value: number | string) => string;
+    /** Trend direction */
+    trend?: TrendDirection;
+    /** Trend value (e.g., "+12%") */
+    trendValue?: string;
+    /** Trend label (e.g., "vs last month") */
+    trendLabel?: string;
+    /** Description text */
+    description?: string;
+    /** Card variant */
+    variant?: CardVariant;
+    /** Card size */
+    size?: CardSize;
+    /** Card color (for filled/gradient variants) */
+    color?: CardColor | string;
+    /** Subtitle text */
+    subtitle?: string;
+    /** Footer action */
+    action?: CardAction;
+}
+/**
+ * Metric card props - With comparison and detailed info
+ */
+export interface MetricCardProps extends BaseCardProps {
+    /** Primary value */
+    value: number | string;
+    /** Value format type */
+    format?: ValueFormat;
+    /** Currency code */
+    currency?: string;
+    /** Trend direction */
+    trend?: TrendDirection;
+    /** Trend value */
+    trendValue?: string;
+    /** Trend label */
+    trendLabel?: string;
+    /** Sparkline data */
+    sparklineData?: number[];
+    /** Sparkline color */
+    sparklineColor?: string;
+    /** Subtitle */
+    subtitle?: string;
+    /** Footer action */
+    action?: ReactNode;
+    /** Secondary metrics */
+    secondaryMetrics?: Array<{
+        label: string;
+        value: number | string;
+        format?: ValueFormat;
+    }>;
+}
+/**
+ * Info card props - Simple icon + value display
+ */
+export interface InfoCardProps extends BaseCardProps {
+    /** Value to display */
+    value?: number | string;
+    /** Value format type */
+    format?: ValueFormat;
+    /** Description text */
+    description?: string;
+    /** Card color */
+    color?: CardColor | string;
+    /** Icon background style */
+    iconBackground?: 'filled' | 'light' | 'none';
+    /** Badge text */
+    badge?: string;
+    /** Badge variant */
+    badgeVariant?: 'default' | 'primary' | 'success' | 'warning' | 'danger';
+    /** Footer content */
+    footer?: ReactNode;
+    /** Children content */
+    children?: ReactNode;
+}
+/**
+ * Card grid props - Layout helper for cards
+ */
+export interface CardGridProps {
+    /** Children cards */
+    children: ReactNode;
+    /** Number of columns (responsive) */
+    columns?: {
+        default?: number;
+        sm?: number;
+        md?: number;
+        lg?: number;
+        xl?: number;
+    };
+    /** Gap between cards */
+    gap?: 'sm' | 'md' | 'lg' | number;
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Transaction list item for TransactionCard
+ */
+export interface TransactionItem {
+    id: string | number;
+    date: string | Date;
+    customer: {
+        name: string;
+        id?: string;
+        avatar?: string;
+    };
+    status: 'completed' | 'pending' | 'draft' | 'failed' | string;
+    amount: number;
+    currency?: string;
+}
+/**
+ * Transaction list card props
+ */
+export interface TransactionListCardProps<TItem = Record<string, unknown>> extends Omit<BaseCardProps, 'value'> {
+    /** Items to display */
+    items: TItem[];
+    /** Render function for each item */
+    renderItem: (item: TItem, index: number) => ReactNode;
+    /** Key extractor */
+    keyExtractor?: (item: TItem, index: number) => string;
+    /** Max items to show */
+    maxItems?: number;
+    /** Empty message */
+    emptyMessage?: string;
+    /** View all label */
+    viewAllLabel?: string;
+    /** View all action */
+    onViewAll?: () => void;
+}
+/**
+ * Top items card props (e.g., Top Customers, Top Products)
+ */
+export interface TopItemsCardProps<TItem = Record<string, unknown>> extends Omit<BaseCardProps, 'value'> {
+    /** Items to display */
+    items: TItem[];
+    /** Key for label field */
+    labelKey: keyof TItem;
+    /** Key for value field */
+    valueKey: keyof TItem;
+    /** Custom label renderer */
+    renderLabel?: (item: TItem, index: number) => ReactNode;
+    /** Custom value renderer */
+    renderValue?: (item: TItem, index: number) => ReactNode;
+    /** Show rank numbers */
+    showRank?: boolean;
+    /** Show progress bar */
+    showProgress?: boolean;
+    /** Progress bar color */
+    progressColor?: string;
+    /** Max items to show */
+    maxItems?: number;
+}
+/**
+ * Default card colors mapping
+ */
+export declare const CARD_COLOR_MAP: Record<CardColor, string>;
+/**
+ * Default gradient colors for filled variant
+ */
+export declare const CARD_GRADIENT_MAP: Record<CardColor, string>;

package/lib/dashboard-visuals-v2/types/card.types.js

@@ -0,0 +1,30 @@
+/**
+ * Default card colors mapping
+ */
+export const CARD_COLOR_MAP = {
+    primary: '#3B82F6',
+    secondary: '#6B7280',
+    success: '#10B981',
+    warning: '#F59E0B',
+    danger: '#EF4444',
+    info: '#06B6D4',
+    orange: '#FF6B35',
+    teal: '#00C49A',
+    blue: '#1E88E5',
+    purple: '#8B5CF6',
+};
+/**
+ * Default gradient colors for filled variant
+ */
+export const CARD_GRADIENT_MAP = {
+    primary: 'from-blue-500 to-blue-600',
+    secondary: 'from-gray-500 to-gray-600',
+    success: 'from-emerald-500 to-emerald-600',
+    warning: 'from-amber-500 to-amber-600',
+    danger: 'from-red-500 to-red-600',
+    info: 'from-cyan-500 to-cyan-600',
+    orange: 'from-orange-500 to-orange-600',
+    teal: 'from-teal-500 to-teal-600',
+    blue: 'from-blue-600 to-blue-700',
+    purple: 'from-purple-500 to-purple-600',
+};

package/lib/dashboard-visuals-v2/types/chart.types.d.ts

@@ -0,0 +1,308 @@
+/**
+ * @fileoverview Chart type definitions for Dashboard Visuals V2
+ */
+import type { ApexOptions } from 'apexcharts';
+import type { ReactNode } from 'react';
+/**
+ * Base data point structure for charts
+ */
+export interface ChartDataPoint {
+    [key: string]: string | number | boolean | null | undefined;
+}
+/**
+ * Series data for multi-series charts
+ */
+export interface ChartSeries {
+    name: string;
+    data: number[];
+    type?: 'bar' | 'line' | 'area' | 'scatter';
+    color?: string;
+}
+/**
+ * Common chart styling options
+ */
+export interface ChartStyleOptions {
+    /** Chart height in pixels or percentage */
+    height?: number | string;
+    /** Chart width in pixels or percentage */
+    width?: number | string;
+    /** Color palette for the chart */
+    colors?: string[];
+    /** Show/hide chart toolbar */
+    showToolbar?: boolean;
+    /** Show/hide legend */
+    showLegend?: boolean;
+    /** Legend position */
+    legendPosition?: 'top' | 'right' | 'bottom' | 'left';
+    /** Show/hide data labels */
+    showDataLabels?: boolean;
+    /** Animation duration in ms */
+    animationDuration?: number;
+    /** Disable animations */
+    disableAnimations?: boolean;
+}
+/**
+ * Chart tooltip configuration
+ */
+export interface ChartTooltipConfig {
+    /** Enable/disable tooltip */
+    enabled?: boolean;
+    /** Shared tooltip for multi-series */
+    shared?: boolean;
+    /** Tooltip title */
+    title?: string;
+    /** Value formatter function */
+    valueFormatter?: (value: number) => string;
+    /** Custom tooltip renderer */
+    customTooltip?: (options: {
+        series: number[];
+        dataPointIndex: number;
+        w: unknown;
+    }) => string;
+}
+/**
+ * Chart axis configuration
+ */
+export interface ChartAxisConfig {
+    /** Axis title */
+    title?: string;
+    /** Show/hide axis */
+    show?: boolean;
+    /** Axis label formatter */
+    formatter?: (value: string | number) => string;
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Tick amount */
+    tickAmount?: number;
+    /** Axis type */
+    type?: 'category' | 'datetime' | 'numeric';
+}
+/**
+ * Base props for all chart components
+ */
+export interface BaseChartProps<TData = ChartDataPoint> {
+    /** Chart data array */
+    data?: TData[];
+    /** Series data for multi-series charts */
+    series?: ChartSeries[];
+    /** Categories/labels for x-axis */
+    categories?: string[];
+    /** Chart title */
+    title?: string;
+    /** Chart subtitle */
+    subtitle?: string;
+    /** Loading state */
+    loading?: boolean;
+    /** Error message */
+    error?: string | null;
+    /** Empty state message */
+    emptyMessage?: string;
+    /** Styling options */
+    style?: ChartStyleOptions;
+    /** Tooltip configuration */
+    tooltip?: ChartTooltipConfig;
+    /** X-axis configuration */
+    xAxis?: ChartAxisConfig;
+    /** Y-axis configuration */
+    yAxis?: ChartAxisConfig;
+    /** Custom ApexCharts options (for full control) */
+    apexOptions?: ApexOptions;
+    /** Custom class name */
+    className?: string;
+    /** Class names for sub-components */
+    classNames?: {
+        container?: string;
+        header?: string;
+        title?: string;
+        subtitle?: string;
+        chart?: string;
+        loading?: string;
+        error?: string;
+        empty?: string;
+    };
+    /** Header action element (e.g., dropdown, button) */
+    headerAction?: ReactNode;
+    /** Click handler for data points */
+    onDataPointClick?: (dataPointIndex: number, seriesIndex: number, data: TData | undefined) => void;
+}
+/**
+ * Bar chart specific props
+ */
+export interface BarChartProps<TData = ChartDataPoint> extends BaseChartProps<TData> {
+    /** Data key for x-axis values */
+    xKey?: keyof TData;
+    /** Data key for y-axis values (single series) */
+    yKey?: keyof TData;
+    /** Data keys for multiple series */
+    yKeys?: (keyof TData)[];
+    /** Series names for legend */
+    seriesNames?: string[];
+    /** Horizontal bar chart */
+    horizontal?: boolean;
+    /** Stacked bar chart */
+    stacked?: boolean;
+    /** Bar border radius */
+    borderRadius?: number;
+    /** Column width percentage */
+    columnWidth?: string;
+}
+/**
+ * Line chart specific props
+ */
+export interface LineChartProps<TData = ChartDataPoint> extends BaseChartProps<TData> {
+    /** Data key for x-axis values */
+    xKey?: keyof TData;
+    /** Data key for y-axis values (single series) */
+    yKey?: keyof TData;
+    /** Data keys for multiple series */
+    yKeys?: (keyof TData)[];
+    /** Series names for legend */
+    seriesNames?: string[];
+    /** Curve type */
+    curve?: 'smooth' | 'straight' | 'stepline';
+    /** Line stroke width */
+    strokeWidth?: number;
+    /** Show markers on data points */
+    showMarkers?: boolean;
+    /** Marker size */
+    markerSize?: number;
+}
+/**
+ * Area chart specific props
+ */
+export interface AreaChartProps<TData = ChartDataPoint> extends LineChartProps<TData> {
+    /** Fill opacity */
+    fillOpacity?: number;
+    /** Gradient fill */
+    gradient?: boolean;
+}
+/**
+ * Donut/Pie chart specific props
+ */
+export interface DonutChartProps<TData = ChartDataPoint> extends BaseChartProps<TData> {
+    /** Data key for label */
+    labelKey?: keyof TData;
+    /** Data key for value */
+    valueKey?: keyof TData;
+    /** Labels array (alternative to labelKey) */
+    labels?: string[];
+    /** Values array (alternative to data + valueKey) */
+    values?: number[];
+    /** Donut hole size (0 for pie chart) */
+    donutSize?: string;
+    /** Show total in center (donut only) */
+    showTotal?: boolean;
+    /** Total label */
+    totalLabel?: string;
+    /** Total value formatter */
+    totalFormatter?: (total: number) => string;
+}
+/**
+ * Pie chart props (alias for DonutChartProps with donutSize: '0%')
+ */
+export type PieChartProps<TData = ChartDataPoint> = DonutChartProps<TData>;
+/**
+ * Heatmap chart specific props
+ */
+export interface HeatmapChartProps<TData = ChartDataPoint> extends BaseChartProps<TData> {
+    /** Data key for x-axis */
+    xKey?: keyof TData;
+    /** Data key for y-axis */
+    yKey?: keyof TData;
+    /** Data key for value */
+    valueKey?: keyof TData;
+    /** Color scale range [min, max] */
+    colorScale?: {
+        ranges: Array<{
+            from: number;
+            to: number;
+            color: string;
+            name?: string;
+        }>;
+    };
+    /** Show value in cell */
+    showValue?: boolean;
+}
+/**
+ * Radial/Gauge chart specific props
+ */
+export interface RadialChartProps extends Omit<BaseChartProps, 'data' | 'series'> {
+    /** Values (0-100) */
+    values: number[];
+    /** Labels for each value */
+    labels: string[];
+    /** Show value inside */
+    showValue?: boolean;
+    /** Value formatter */
+    valueFormatter?: (value: number) => string;
+    /** Track background color */
+    trackBackground?: string;
+    /** Hollow size percentage */
+    hollowSize?: string;
+    /** Start angle */
+    startAngle?: number;
+    /** End angle */
+    endAngle?: number;
+}
+/**
+ * Mixed chart specific props
+ */
+export interface MixedChartProps<TData = ChartDataPoint> extends BaseChartProps<TData> {
+    /** Data key for x-axis values */
+    xKey?: keyof TData;
+    /** Series configuration with type for each */
+    seriesConfig: Array<{
+        name: string;
+        dataKey: keyof TData;
+        type: 'bar' | 'line' | 'area';
+        color?: string;
+    }>;
+}
+/**
+ * Chart query props for data fetching integration with TanStack Query
+ */
+export interface ChartQueryProps {
+    /** API endpoint URL */
+    url?: string;
+    /** HTTP method */
+    method?: 'GET' | 'POST';
+    /** Request body for POST */
+    body?: Record<string, unknown>;
+    /** Query parameters */
+    params?: Record<string, string>;
+    /** Transform response data */
+    transform?: (data: unknown) => unknown[];
+    /** Enable query */
+    enabled?: boolean;
+    /** Query key for TanStack Query cache management */
+    queryKey?: unknown[];
+    /** Stale time in ms (how long data is considered fresh) */
+    staleTime?: number;
+    /** Garbage collection time in ms */
+    gcTime?: number;
+    /** Refetch interval in ms (0 = disabled) */
+    refetchInterval?: number;
+    /** Refetch on window focus */
+    refetchOnWindowFocus?: boolean;
+}
+/**
+ * Chart with data fetching props
+ */
+export interface ChartWithQueryProps<TData = ChartDataPoint, TChartProps = BaseChartProps<TData>> extends ChartQueryProps {
+    /** Chart component props (excluding data) */
+    chartProps: Omit<TChartProps, 'data' | 'loading' | 'error'>;
+}
+/**
+ * Visual registry component type
+ */
+export type ChartComponentType = 'BarChart' | 'LineChart' | 'AreaChart' | 'DonutChart' | 'PieChart' | 'HeatmapChart' | 'RadialChart' | 'MixedChart';
+/**
+ * Default chart colors palette
+ */
+export declare const DEFAULT_CHART_COLORS: string[];
+/**
+ * Default chart style options
+ */
+export declare const DEFAULT_CHART_STYLE: ChartStyleOptions;

package/lib/dashboard-visuals-v2/types/chart.types.js

@@ -0,0 +1,25 @@
+/**
+ * Default chart colors palette
+ */
+export const DEFAULT_CHART_COLORS = [
+    '#FF6B35', // Orange
+    '#00C49A', // Teal
+    '#3B82F6', // Blue
+    '#F59E0B', // Amber
+    '#8B5CF6', // Purple
+    '#EC4899', // Pink
+    '#10B981', // Emerald
+    '#6366F1', // Indigo
+];
+/**
+ * Default chart style options
+ */
+export const DEFAULT_CHART_STYLE = {
+    height: 350,
+    showToolbar: false,
+    showLegend: true,
+    legendPosition: 'top',
+    showDataLabels: false,
+    animationDuration: 800,
+    disableAnimations: false,
+};

package/lib/dashboard-visuals-v2/types/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Type definitions for Dashboard Visuals V2
+ * ApexCharts-based visualization components
+ */
+export * from './chart.types';
+export * from './card.types';

package/lib/dashboard-visuals-v2/types/index.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Type definitions for Dashboard Visuals V2
+ * ApexCharts-based visualization components
+ */
+export * from './chart.types';
+export * from './card.types';

package/lib/dashboard-visuals-v2/utils/index.js

@@ -0,0 +1 @@
+"use strict";

package/lib/dashboard-visuals-v2/utils/propsTransformer.js

@@ -0,0 +1 @@
+"use strict";