HR Payroll Metrics

Data formatting and visualization utilities for HR analytics and payroll metrics in the WorkPayCore frontend application.

Overview

The HR payroll metrics helpers provide functions for formatting complex HR data into chart-ready formats, calculating payroll summaries, and processing employee analytics data.

Employee Demographics Functions

formatTotalEmployees(data)

Formats employee gender distribution data for chart visualization.

Parameters:

data (array): Array of employee gender data objects

Returns:

array: Chart-ready format with headers and gender counts

Example:

import { formatTotalEmployees } from '@/utils/helpers/hr-payrol-metrics';

const genderData = [
  { label: 'MALE', count: 45 },
  { label: 'FEMALE', count: 38 },
  { label: 'UNKNOWN', count: 2 },
  { label: 'Not Set', count: 1 },
];

const chartData = formatTotalEmployees(genderData);
console.log(chartData);
// Returns: [
//   ['Gender', 'Count'],
//   ['Male', 45],
//   ['Female', 38],
//   ['Unknown', 2],
//   ['Not Set', 1]
// ]

Use Cases:

Gender distribution charts
Employee demographics visualization
Diversity reporting
HR analytics dashboards

formatAgeSummary(data)

Formats employee age group data with color coding for visualization.

Parameters:

data (array): Array of age group objects with count data

Returns:

array: Chart-ready format with age groups, counts, and colors

Example:

import { formatAgeSummary } from '@/utils/helpers/hr-payrol-metrics';

const ageData = [
  { 'Gen Z [10-25 Yrs]': '15' },
  { 'Millenials [26-41 Yrs]': '35' },
  { 'Gen X [42-57 Yrs]': '25' },
  { 'Boomers II [58-67 Yrs]': '8' },
  { Unkown: '2' },
];

const chartData = formatAgeSummary(ageData);
console.log(chartData);
// Returns: [
//   ['', 'Count', { role: 'style' }],
//   ['Gen Z 10-25 Yrs', 15, '#f9dba1'],
//   ['Millenials 26-41 Yrs', 35, '#DEEBFF'],
//   ['GenX 42-57 Yrs', 25, '#a0c68f'],
//   ['Boomers II 58-67 Yrs', 8, '#62a446'],
//   ['Unkown', 2, '#fee6e9']
// ]

Use Cases:

Age distribution visualization
Generational analytics
Workforce planning
Retirement planning analysis

formatAgeGroupAnalysis(data)

Formats age group turnover analysis data for charts.

Parameters:

data (array): Array of age group turnover data

Returns:

array: Chart-ready format with turnover data and styling

Example:

import { formatAgeGroupAnalysis } from '@/utils/helpers/hr-payrol-metrics';

const turnoverData = [
  { label: 'Gen Z [10-25 Yrs]', turnover: '12' },
  { label: 'Millenials [26-41 Yrs]', turnover: '8' },
  { label: 'Gen X [42-57 Yrs]', turnover: '5' },
];

const chartData = formatAgeGroupAnalysis(turnoverData);
console.log(chartData);
// Returns chart data with turnover rates and color coding

Use Cases:

Turnover analysis by age group
Retention metrics
HR strategy planning
Workforce stability analysis

Movement and Trend Functions

formatEmployeeMovement(data, departments)

Formats employee movement data across departments and time periods.

Parameters:

data (array): Employee movement data by department
departments (array): List of department names

Returns:

array: Matrix format for time series visualization

Example:

import { formatEmployeeMovement } from '@/utils/helpers/hr-payrol-metrics';

const movementData = [
  {
    items: [
      { label: 'January', count: 5 },
      { label: 'February', count: 3 },
    ],
  },
];

const departments = ['Engineering', 'Marketing', 'Sales'];
const chartData = formatEmployeeMovement(movementData, departments);
console.log(chartData);
// Returns time series data formatted for charts

Use Cases:

Employee hiring trends
Department growth tracking
Workforce planning
Seasonal hiring analysis

formatEmployeeMovement2(data, departments)

Alternative employee movement formatting with month-based organization.

Parameters:

data (array): Department-based movement data
departments (array): Department names array

Returns:

array: Month-organized movement data

Example:

import { formatEmployeeMovement2 } from '@/utils/helpers/hr-payrol-metrics';

const departmentData = [
  {
    /* Engineering data */
  },
  {
    /* Marketing data */
  },
  {
    /* Sales data */
  },
];

const departments = ['Engineering', 'Marketing', 'Sales'];
const chartData = formatEmployeeMovement2(departmentData, departments);
// Returns monthly movement data across departments

Use Cases:

Monthly hiring reports
Cross-department analysis
Recruitment effectiveness
Workforce trends

Financial and Payroll Functions

formatPayrollSummary(data)

Formats payroll summary data for financial reporting.

Parameters:

data (array): Payroll summary data

Returns:

array: Chart-ready payroll summary

Example:

import { formatPayrollSummary } from '@/utils/helpers/hr-payrol-metrics';

const payrollData = [
  { month: 'January', gross: 125000, net: 95000, deductions: 30000 },
  { month: 'February', gross: 130000, net: 98000, deductions: 32000 },
];

const chartData = formatPayrollSummary(payrollData);
// Returns formatted payroll metrics for visualization

Use Cases:

Monthly payroll reports
Financial planning
Budget analysis
Compensation trends

formatPayrollAllowancesDeductions(data, defaultArray)

Formats allowances and deductions data for payroll analysis.

Parameters:

data (array): Allowances and deductions data
defaultArray (array): Default structure for missing data

Returns:

array: Formatted allowances/deductions data

Example:

import { formatPayrollAllowancesDeductions } from '@/utils/helpers/hr-payrol-metrics';

const allowanceData = [
  { type: 'Housing', amount: 15000 },
  { type: 'Transport', amount: 8000 },
  { type: 'Medical', amount: 5000 },
];

const defaultStructure = ['Housing', 'Transport', 'Medical', 'Bonus'];
const chartData = formatPayrollAllowancesDeductions(
  allowanceData,
  defaultStructure,
);
// Returns formatted allowances/deductions breakdown

Use Cases:

Compensation analysis
Benefit cost tracking
Payroll component breakdown
Financial reporting

Utility Functions

formatAmount(amount)

Formats monetary amounts for display with proper locale formatting.

Parameters:

amount (number): Monetary amount to format

Returns:

string: Formatted amount string

Example:

import { formatAmount } from '@/utils/helpers/hr-payrol-metrics';

formatAmount(1234567.89); // Returns: "1,234,567.89"
formatAmount(1000); // Returns: "1,000.00"
formatAmount(0); // Returns: "0.00"

Use Cases:

Salary display
Financial reporting
Currency formatting
Report generation

progressBlendColors(name)

Generates color schemes for progress indicators and charts.

Parameters:

name (string): Color scheme name

Returns:

string: Generated color value

Example:

import { progressBlendColors } from '@/utils/helpers/hr-payrol-metrics';

const chartColor = progressBlendColors('primary');
const accentColor = progressBlendColors('secondary');

// Use in chart configurations
const chartConfig = {
  backgroundColor: chartColor,
  borderColor: accentColor,
};

Use Cases:

Dynamic chart coloring
Theme-based visualization
Progress indicators
Dashboard styling

Leave Management

canSubmittedLeaveBeApproved(options)

Determines if a submitted leave request can be approved based on workflow and permissions.

Parameters:

options (object): Leave approval configuration object
- hasApprovalWorkflowStages (boolean): Workflow stages present
- settings (object): Company leave settings
- original (object): Original leave request
- role (string): User role
- is_employee_supervisor (boolean): Supervisor status
- permissions (array): User permissions

Returns:

boolean: Whether leave can be approved

Example:

import { canSubmittedLeaveBeApproved } from '@/utils/helpers/hr-payrol-metrics';

const canApprove = canSubmittedLeaveBeApproved({
  hasApprovalWorkflowStages: true,
  settings: { requireSupervisorApproval: true },
  original: { employeeId: 123, days: 5 },
  role: 'manager',
  is_employee_supervisor: true,
  permissions: ['approve_leave', 'manage_employees'],
});

if (canApprove) {
  // Show approval buttons
  showApprovalInterface();
}

Use Cases:

Leave approval workflows
Permission checking
Role-based access control
HR process automation

Advanced Usage Examples

Dashboard Metrics Component

import {
  formatTotalEmployees,
  formatAgeSummary,
  formatPayrollSummary,
  formatAmount,
} from '@/utils/helpers/hr-payrol-metrics';

const HRDashboard = ({ employeeData, payrollData, ageData }) => {
  const genderChartData = useMemo(
    () => formatTotalEmployees(employeeData?.gender || []),
    [employeeData],
  );

  const ageChartData = useMemo(
    () => formatAgeSummary(ageData || []),
    [ageData],
  );

  const payrollChartData = useMemo(
    () => formatPayrollSummary(payrollData || []),
    [payrollData],
  );

  const totalPayroll = useMemo(() => {
    const total = payrollData?.reduce((sum, item) => sum + item.gross, 0) || 0;
    return formatAmount(total);
  }, [payrollData]);

  return (
    <div className='hr-dashboard'>
      <div className='metrics-row'>
        <MetricCard title='Total Payroll' value={totalPayroll} />
      </div>

      <div className='charts-row'>
        <Chart type='pie' data={genderChartData} title='Gender Distribution' />

        <Chart type='column' data={ageChartData} title='Age Groups' />

        <Chart type='line' data={payrollChartData} title='Payroll Trends' />
      </div>
    </div>
  );
};

Employee Analytics Hook

import {
  formatTotalEmployees,
  formatAgeGroupAnalysis,
  formatEmployeeMovement,
} from '@/utils/helpers/hr-payrol-metrics';

const useEmployeeAnalytics = filters => {
  const [analytics, setAnalytics] = useState({
    loading: true,
    demographics: null,
    movement: null,
    turnover: null,
  });

  useEffect(() => {
    const loadAnalytics = async () => {
      setAnalytics(prev => ({ ...prev, loading: true }));

      try {
        const [demographicsData, movementData, turnoverData] =
          await Promise.all([
            fetchDemographics(filters),
            fetchMovement(filters),
            fetchTurnover(filters),
          ]);

        setAnalytics({
          loading: false,
          demographics: {
            gender: formatTotalEmployees(demographicsData.gender),
            age: formatAgeGroupAnalysis(demographicsData.age),
          },
          movement: formatEmployeeMovement(movementData, filters.departments),
          turnover: formatAgeGroupAnalysis(turnoverData),
        });
      } catch (error) {
        console.error('Failed to load analytics:', error);
        setAnalytics(prev => ({ ...prev, loading: false }));
      }
    };

    loadAnalytics();
  }, [filters]);

  return analytics;
};

Leave Approval Component

import { canSubmittedLeaveBeApproved } from '@/utils/helpers/hr-payrol-metrics';

const LeaveRequestCard = ({ leaveRequest, currentUser, companySettings }) => {
  const canApprove = useMemo(
    () =>
      canSubmittedLeaveBeApproved({
        hasApprovalWorkflowStages: companySettings.hasWorkflow,
        settings: companySettings.leave,
        original: leaveRequest,
        role: currentUser.role,
        is_employee_supervisor: currentUser.isSupervisor,
        permissions: currentUser.permissions,
      }),
    [leaveRequest, currentUser, companySettings],
  );

  const handleApprove = async () => {
    if (!canApprove) return;

    try {
      await approveLeaveRequest(leaveRequest.id);
      // Handle success
    } catch (error) {
      // Handle error
    }
  };

  return (
    <div className='leave-request-card'>
      <div className='request-details'>
        <h3>{leaveRequest.employeeName}</h3>
        <p>
          Dates: {leaveRequest.startDate} - {leaveRequest.endDate}
        </p>
        <p>Days: {leaveRequest.days}</p>
      </div>

      {canApprove && (
        <div className='approval-actions'>
          <button onClick={handleApprove} className='approve-btn'>
            Approve
          </button>
          <button onClick={handleReject} className='reject-btn'>
            Reject
          </button>
        </div>
      )}
    </div>
  );
};

Chart Integration

Google Charts Integration

import {
  formatAgeSummary,
  progressBlendColors,
} from '@/utils/helpers/hr-payrol-metrics';

const AgeDistributionChart = ({ data }) => {
  const chartData = formatAgeSummary(data);

  const options = {
    title: 'Employee Age Distribution',
    chartArea: { width: '50%' },
    colors: [
      progressBlendColors('gen-z'),
      progressBlendColors('millennial'),
      progressBlendColors('gen-x'),
      progressBlendColors('boomer'),
    ],
    hAxis: {
      title: 'Age Groups',
      minValue: 0,
    },
    vAxis: {
      title: 'Number of Employees',
    },
  };

  return (
    <Chart
      chartType='ColumnChart'
      width='100%'
      height='400px'
      data={chartData}
      options={options}
    />
  );
};

Best Practices

Data Validation: Always validate input data before formatting
Color Consistency: Use progressBlendColors for consistent theming
Performance: Memoize chart data to prevent unnecessary recalculations
Error Handling: Handle missing or malformed data gracefully
Accessibility: Ensure charts have proper labels and descriptions

String Utilities - For text formatting
Number Utilities - For numeric calculations
Date & Time Utilities - For date formatting

TypeScript Definitions

export function formatTotalEmployees(data: any[]): any[];
export function formatAgeSummary(data: any[]): any[];
export function formatAgeGroupAnalysis(data: any[]): any[];
export function formatEmployeeMovement(
  data: any[],
  departments: string[],
): any[];
export function formatEmployeeMovement2(
  data: any[],
  departments: string[],
): any[];
export function formatPayrollSummary(data: any[]): any[];
export function formatPayrollAllowancesDeductions(
  data: any[],
  defaultArray: any[],
): any[];
export function formatAmount(amount: number): string;
export function progressBlendColors(name: string): string;
export function canSubmittedLeaveBeApproved(options: {
  hasApprovalWorkflowStages: boolean;
  settings: any;
  original: any;
  role: string;
  is_employee_supervisor: boolean;
  permissions: string[];
}): boolean;

Dependencies

Chakra UI Theme Tools: For color utilities
Theme Colors: For consistent color schemes
Date/Time Utilities: For date formatting
String Utilities: For text processing

Overview​

Employee Demographics Functions​

formatTotalEmployees(data)​

formatAgeSummary(data)​

formatAgeGroupAnalysis(data)​

Movement and Trend Functions​

formatEmployeeMovement(data, departments)​

formatEmployeeMovement2(data, departments)​

Financial and Payroll Functions​

formatPayrollSummary(data)​

formatPayrollAllowancesDeductions(data, defaultArray)​

Utility Functions​

formatAmount(amount)​

progressBlendColors(name)​

Leave Management​

canSubmittedLeaveBeApproved(options)​

Advanced Usage Examples​

Dashboard Metrics Component​

Employee Analytics Hook​

Leave Approval Component​

Chart Integration​

Google Charts Integration​

Best Practices​

Related Utilities​

TypeScript Definitions​

Dependencies​

Overview

Employee Demographics Functions

formatTotalEmployees(data)

formatAgeSummary(data)

formatAgeGroupAnalysis(data)

Movement and Trend Functions

formatEmployeeMovement(data, departments)

formatEmployeeMovement2(data, departments)

Financial and Payroll Functions

formatPayrollSummary(data)

formatPayrollAllowancesDeductions(data, defaultArray)

Utility Functions

formatAmount(amount)

progressBlendColors(name)

Leave Management

canSubmittedLeaveBeApproved(options)

Advanced Usage Examples

Dashboard Metrics Component

Employee Analytics Hook

Leave Approval Component

Chart Integration

Google Charts Integration

Best Practices

Related Utilities

TypeScript Definitions

Dependencies