Musterroll Constants

Payroll musterroll display configuration constants that define which columns should be hidden or shown in the payroll processing interface of the WorkPayCore frontend application.

Overview

The musterroll constants control the visibility of various payroll calculation columns in the musterroll (payroll register) display, allowing for customized views and simplified interfaces based on business requirements and user roles.

Column Visibility Constants

columnsToHide

Array of column names that should be hidden by default in the musterroll display to reduce complexity and focus on essential payroll information.

export const columnsToHide = [
  'week_day_overtime_hours',
  'non_week_day_overtime_hours',
  'week_day_overtime_pay',
  'non_week_day_overtime_pay',
  'paid_leave_amount',
  'deduction_before',
  'low_interest_benefit',
  'fringe_tax',
  'pension',
  'employer_pension',
  'insurance_relief',
  'mortgage_interest_relief',
  'salary_advance',
  'loan_repayment',
  'helb',
  'voluntary_provident',
];

Hidden Column Categories:

Overtime Calculations

• week_day_overtime_hours: Overtime hours worked on weekdays
• non_week_day_overtime_hours: Overtime hours worked on weekends/holidays
• week_day_overtime_pay: Overtime payment for weekday work
• non_week_day_overtime_pay: Overtime payment for weekend/holiday work

Leave and Benefits

• paid_leave_amount: Paid leave compensation amounts
• low_interest_benefit: Low interest loan benefits
• fringe_tax: Fringe benefit taxation

Deductions and Contributions

• deduction_before: Pre-tax deductions
• pension: Employee pension contributions
• employer_pension: Employer pension contributions
• insurance_relief: Insurance-related tax relief
• mortgage_interest_relief: Mortgage interest tax deductions

Loans and Advances

• salary_advance: Salary advance deductions
• loan_repayment: Loan repayment amounts
• helb: Higher Education Loans Board repayments
• voluntary_provident: Voluntary provident fund contributions

---

Usage Examples

Musterroll Column Management

import { columnsToHide } from '@/utils/constants/musterroll';

const MusterrollDisplayManager = {
  getVisibleColumns: (allColumns, userRole = 'standard') => {
    if (userRole === 'admin' || userRole === 'hr_manager') {
      // Admins and HR managers can see all columns
      return allColumns;
    }

    // Standard users see only essential columns
    return allColumns.filter(column => !columnsToHide.includes(column.key));
  },

  getHiddenColumns: () => {
    return columnsToHide.map(columnKey => ({
      key: columnKey,
      label: columnKey
        .replace(/_/g, ' ')
        .replace(/\b\w/g, l => l.toUpperCase()),
      category: MusterrollDisplayManager.getColumnCategory(columnKey),
    }));
  },

  getColumnCategory: columnKey => {
    const categoryMap = {
      overtime: [
        'week_day_overtime_hours',
        'non_week_day_overtime_hours',
        'week_day_overtime_pay',
        'non_week_day_overtime_pay',
      ],
      benefits: ['paid_leave_amount', 'low_interest_benefit', 'fringe_tax'],
      deductions: [
        'deduction_before',
        'pension',
        'employer_pension',
        'insurance_relief',
        'mortgage_interest_relief',
      ],
      loans: [
        'salary_advance',
        'loan_repayment',
        'helb',
        'voluntary_provident',
      ],
    };

    for (const [category, columns] of Object.entries(categoryMap)) {
      if (columns.includes(columnKey)) {
        return category;
      }
    }

    return 'other';
  },
};

Dynamic Column Visibility

import { columnsToHide } from '@/utils/constants/musterroll';

const useMusterrollColumns = (baseColumns, userPreferences, userRole) => {
  const [visibleColumns, setVisibleColumns] = useState([]);
  const [hiddenColumns, setHiddenColumns] = useState([]);

  useEffect(() => {
    let columnsToShow = baseColumns;

    // Apply role-based hiding
    if (userRole !== 'admin') {
      columnsToShow = columnsToShow.filter(
        col => !columnsToHide.includes(col.key),
      );
    }

    // Apply user preferences
    if (userPreferences?.hiddenColumns) {
      columnsToShow = columnsToShow.filter(
        col => !userPreferences.hiddenColumns.includes(col.key),
      );
    }

    setVisibleColumns(columnsToShow);
    setHiddenColumns(baseColumns.filter(col => !columnsToShow.includes(col)));
  }, [baseColumns, userPreferences, userRole]);

  const toggleColumn = columnKey => {
    const isCurrentlyVisible = visibleColumns.some(
      col => col.key === columnKey,
    );

    if (isCurrentlyVisible) {
      // Hide column
      setVisibleColumns(prev => prev.filter(col => col.key !== columnKey));
      setHiddenColumns(prev => [
        ...prev,
        baseColumns.find(col => col.key === columnKey),
      ]);
    } else {
      // Show column
      const columnToShow = baseColumns.find(col => col.key === columnKey);
      setVisibleColumns(prev => [...prev, columnToShow]);
      setHiddenColumns(prev => prev.filter(col => col.key !== columnKey));
    }
  };

  return {
    visibleColumns,
    hiddenColumns,
    toggleColumn,
    defaultHiddenColumns: columnsToHide,
  };
};

Payroll Report Customization

import { columnsToHide } from '@/utils/constants/musterroll';

const PayrollReportGenerator = {
  generateReport: (employees, reportType = 'summary', options = {}) => {
    const allColumns = [
      'employee_name',
      'employee_id',
      'basic_salary',
      'allowances',
      'gross_pay',
      'deductions',
      'net_pay',
      ...columnsToHide, // All detailed columns
    ];

    let columnsToInclude;

    switch (reportType) {
      case 'detailed':
        columnsToInclude = allColumns;
        break;
      case 'summary':
        columnsToInclude = allColumns.filter(
          col => !columnsToHide.includes(col),
        );
        break;
      case 'custom':
        columnsToInclude = options.customColumns || allColumns;
        break;
      default:
        columnsToInclude = allColumns.filter(
          col => !columnsToHide.includes(col),
        );
    }

    return {
      columns: columnsToInclude,
      data: employees.map(employee =>
        PayrollReportGenerator.formatEmployeeData(employee, columnsToInclude),
      ),
      hiddenColumns: allColumns.filter(col => !columnsToInclude.includes(col)),
    };
  },

  formatEmployeeData: (employee, columns) => {
    const data = {};
    columns.forEach(column => {
      data[column] = employee[column] || 0;
    });
    return data;
  },

  getColumnDisplayName: columnKey => {
    const displayNames = {
      week_day_overtime_hours: 'Weekday OT Hours',
      non_week_day_overtime_hours: 'Weekend OT Hours',
      week_day_overtime_pay: 'Weekday OT Pay',
      non_week_day_overtime_pay: 'Weekend OT Pay',
      paid_leave_amount: 'Paid Leave Amount',
      deduction_before: 'Pre-tax Deductions',
      low_interest_benefit: 'Low Interest Benefit',
      fringe_tax: 'Fringe Tax',
      pension: 'Pension Contribution',
      employer_pension: 'Employer Pension',
      insurance_relief: 'Insurance Relief',
      mortgage_interest_relief: 'Mortgage Interest Relief',
      salary_advance: 'Salary Advance',
      loan_repayment: 'Loan Repayment',
      helb: 'HELB Repayment',
      voluntary_provident: 'Voluntary Provident Fund',
    };

    return (
      displayNames[columnKey] || columnKey.replace(/_/g, ' ').toUpperCase()
    );
  },
};

Musterroll Table Component

import React, { useState } from 'react';
import { columnsToHide } from '@/utils/constants/musterroll';

const MusterrollTable = ({ employees, userRole }) => {
  const [showHiddenColumns, setShowHiddenColumns] = useState(false);

  const allColumns = [
    { key: 'employee_name', label: 'Employee Name', essential: true },
    { key: 'basic_salary', label: 'Basic Salary', essential: true },
    { key: 'gross_pay', label: 'Gross Pay', essential: true },
    { key: 'net_pay', label: 'Net Pay', essential: true },
    // Add all other columns including hidden ones
    ...columnsToHide.map(key => ({
      key,
      label: PayrollReportGenerator.getColumnDisplayName(key),
      essential: false,
    })),
  ];

  const getVisibleColumns = () => {
    if (userRole === 'admin' || showHiddenColumns) {
      return allColumns;
    }

    return allColumns.filter(
      col => col.essential || !columnsToHide.includes(col.key),
    );
  };

  const visibleColumns = getVisibleColumns();

  return (
    <div>
      <div className='table-controls'>
        <button
          onClick={() => setShowHiddenColumns(!showHiddenColumns)}
          disabled={userRole !== 'admin'}
        >
          {showHiddenColumns ? 'Hide' : 'Show'} Detailed Columns
        </button>

        <span className='column-count'>
          Showing {visibleColumns.length} of {allColumns.length} columns
        </span>
      </div>

      <table className='musterroll-table'>
        <thead>
          <tr>
            {visibleColumns.map(column => (
              <th key={column.key}>
                {column.label}
                {!column.essential && (
                  <span className='optional-indicator'>*</span>
                )}
              </th>
            ))}
          </tr>
        </thead>
        <tbody>
          {employees.map(employee => (
            <tr key={employee.id}>
              {visibleColumns.map(column => (
                <td key={column.key}>
                  {formatCellValue(employee[column.key], column.key)}
                </td>
              ))}
            </tr>
          ))}
        </tbody>
      </table>

      {!showHiddenColumns && columnsToHide.length > 0 && (
        <div className='hidden-columns-info'>
          {columnsToHide.length} detailed columns are hidden.
          {userRole === 'admin' && (
            <button onClick={() => setShowHiddenColumns(true)}>Show All</button>
          )}
        </div>
      )}
    </div>
  );
};

const formatCellValue = (value, columnKey) => {
  if (value === null || value === undefined) return '-';

  // Format monetary values
  if (
    columnKey.includes('pay') ||
    columnKey.includes('amount') ||
    columnKey.includes('salary') ||
    columnKey.includes('deduction')
  ) {
    return new Intl.NumberFormat('en-US', {
      style: 'currency',
      currency: 'KES',
    }).format(value);
  }

  // Format hours
  if (columnKey.includes('hours')) {
    return `${value} hrs`;
  }

  return value;
};

Export Configuration

import { columnsToHide } from '@/utils/constants/musterroll';

const MusterrollExportManager = {
  getExportColumns: (exportType, userRole) => {
    const essentialColumns = [
      'employee_name',
      'employee_id',
      'basic_salary',
      'gross_pay',
      'net_pay',
    ];

    switch (exportType) {
      case 'summary':
        return essentialColumns;

      case 'detailed':
        if (userRole === 'admin') {
          return [...essentialColumns, ...columnsToHide];
        }
        // Non-admin users get filtered detailed view
        return essentialColumns;

      case 'custom':
        return essentialColumns; // Base columns for custom selection

      default:
        return essentialColumns;
    }
  },

  generateExportData: (employees, columns) => {
    return employees.map(employee => {
      const exportRow = {};
      columns.forEach(column => {
        exportRow[PayrollReportGenerator.getColumnDisplayName(column)] =
          employee[column] || 0;
      });
      return exportRow;
    });
  },

  getHiddenColumnsSummary: () => {
    const categories = {
      overtime: [],
      benefits: [],
      deductions: [],
      loans: [],
    };

    columnsToHide.forEach(column => {
      const category = MusterrollDisplayManager.getColumnCategory(column);
      if (categories[category]) {
        categories[category].push(column);
      }
    });

    return categories;
  },
};

---

Column Categories and Business Logic

Overtime Calculations

Hidden to simplify payroll view while detailed overtime data remains accessible through dedicated overtime reports.

Employee Benefits

Complex benefit calculations are hidden from standard view to focus on net impact rather than individual components.

Tax and Relief Calculations

Detailed tax relief and deduction components are hidden to present clean payroll summary while maintaining calculation accuracy.

Loan and Advance Management

Individual loan components are hidden from payroll view as they're better managed through dedicated loan management interfaces.

---

Best Practices

1. Role-Based Visibility

// Always consider user role when determining column visibility
const getColumns = userRole => {
  if (userRole === 'admin' || userRole === 'payroll_manager') {
    return allColumns; // Show everything
  }

  return allColumns.filter(col => !columnsToHide.includes(col.key));
};

2. Progressive Disclosure

// Allow users to progressively reveal more detail
const enableDetailedView = userHasPermission => {
  if (userHasPermission) {
    setShowDetailedColumns(true);
  }
};

3. Export Considerations

// Different export formats may need different column sets
const getExportColumns = (format, userRole) => {
  if (format === 'summary') {
    return essentialColumns;
  }

  if (format === 'audit' && userRole === 'admin') {
    return allColumns; // Include everything for audit purposes
  }

  return standardColumns;
};

---

Related Utilities

• Settings - For payroll configuration settings
• Status Codes - For employee status filtering
• Options - For payroll frequency and type options

---

TypeScript Definitions

export const columnsToHide: readonly string[];

interface MusterrollColumn {
  key: string;
  label: string;
  category: 'overtime' | 'benefits' | 'deductions' | 'loans' | 'other';
  essential: boolean;
  dataType: 'currency' | 'hours' | 'percentage' | 'text';
}

interface MusterrollDisplayOptions {
  showHiddenColumns: boolean;
  userRole: 'admin' | 'hr_manager' | 'payroll_manager' | 'standard';
  customHiddenColumns?: string[];
}

interface ExportConfiguration {
  type: 'summary' | 'detailed' | 'custom' | 'audit';
  columns: string[];
  includeHiddenColumns: boolean;
}

---

Configuration Management

Environment-Based Hiding

// Different environments might need different default hidden columns
const getEnvironmentColumns = environment => {
  const baseHidden = columnsToHide;

  if (environment === 'development') {
    // Show more columns in development for testing
    return baseHidden.filter(
      col => !['pension', 'loan_repayment'].includes(col),
    );
  }

  if (environment === 'demo') {
    // Hide sensitive columns in demo environment
    return [...baseHidden, 'salary_advance', 'loan_repayment'];
  }

  return baseHidden;
};

Regional Customization

// Different regions might need different column visibility
const getRegionalColumns = country => {
  const baseHidden = columnsToHide;

  if (country === 'Nigeria') {
    // Nigeria doesn't use HELB
    return baseHidden.filter(col => col !== 'helb');
  }

  if (country === 'Kenya') {
    // Kenya includes all standard columns
    return baseHidden;
  }

  return baseHidden;
};

---

These musterroll constants provide flexible payroll display management, ensuring that users see appropriate levels of detail while maintaining access to comprehensive payroll data when needed for reporting and auditing purposes.