Skip to main content

Tax Compliance Components

This section covers all tax compliance-related components in the WorkPayCore Frontend, including PAYE calculations, NSSF contributions, NHIF deductions, P9 forms, tax calculations, and statutory reporting functionality.

Components Overview​

Core Tax Components​

  • PAYECalculator - PAYE tax calculation engine
  • NSSFCalculator - NSSF contribution calculations
  • NHIFCalculator - NHIF deduction calculations
  • P9FormGenerator - P9 form generation and management
  • TaxCalculationSummary - Tax calculation summary display
  • StatutoryReportGenerator - Statutory reporting tools

Supporting Components​

  • TaxBracketDisplay - Tax bracket visualization
  • TaxRateSelector - Tax rate selection interface
  • ComplianceStatusIndicator - Compliance status display
  • TaxPeriodSelector - Tax period selection
  • StatutoryDeductionCard - Statutory deduction display
  • TaxReportViewer - Tax report viewing interface

PAYECalculator Component​

Basic Usage​

import { PAYECalculator } from '@/components/tax-compliance/PAYECalculator';

// Basic PAYE calculation
const BasicPAYECalculator = () => {
  const [calculation, setCalculation] = useState<PAYECalculation | null>(null);

  const handleCalculate = (grossSalary: number, taxYear: number) => {
    // PAYE calculation logic
    const result = calculatePAYE(grossSalary, taxYear);
    setCalculation(result);
  };

  return (
    <PAYECalculator
      grossSalary={50000}
      taxYear={2024}
      onCalculate={handleCalculate}
      showBreakdown={true}
      currency='KES'
    />
  );
};

Props Interface​

interface PAYECalculatorProps {
  grossSalary: number;
  taxYear: number;
  onCalculate: (calculation: PAYECalculation) => void;
  showBreakdown?: boolean;
  currency?: string;
  taxBrackets?: TaxBracket[];
  personalRelief?: number;
  className?: string;
  loading?: boolean;
  disabled?: boolean;
}

interface PAYECalculation {
  grossSalary: number;
  taxableIncome: number;
  payeTax: number;
  personalRelief: number;
  netSalary: number;
  taxBrackets: TaxBracketCalculation[];
  effectiveRate: number;
  marginalRate: number;
}

interface TaxBracket {
  min: number;
  max: number | null;
  rate: number;
  description: string;
}

Advanced Usage​

// PAYE calculator with custom tax brackets
const AdvancedPAYECalculator = () => {
  const customTaxBrackets: TaxBracket[] = [
    { min: 0, max: 24000, rate: 0.1, description: '10% on first 24,000' },
    { min: 24001, max: 32333, rate: 0.25, description: '25% on next 8,333' },
    { min: 32334, max: null, rate: 0.3, description: '30% on excess' },
  ];

  return (
    <PAYECalculator
      grossSalary={100000}
      taxYear={2024}
      taxBrackets={customTaxBrackets}
      personalRelief={2400}
      onCalculate={calc => console.log(calc)}
      showBreakdown={true}
      currency='KES'
      className='custom-paye-calculator'
    />
  );
};

NSSFCalculator Component​

Basic Usage​

import { NSSFCalculator } from '@/components/tax-compliance/NSSFCalculator';

// Basic NSSF calculation
const BasicNSSFCalculator = () => {
  const [contribution, setContribution] = useState<NSSFContribution | null>(
    null,
  );

  return (
    <NSSFCalculator
      grossSalary={50000}
      contributionRate={0.06}
      onCalculate={setContribution}
      showEmployerContribution={true}
      currency='KES'
    />
  );
};

Props Interface​

interface NSSFCalculatorProps {
  grossSalary: number;
  contributionRate: number;
  onCalculate: (contribution: NSSFContribution) => void;
  showEmployerContribution?: boolean;
  currency?: string;
  minimumContribution?: number;
  maximumContribution?: number;
  className?: string;
  loading?: boolean;
  disabled?: boolean;
}

interface NSSFContribution {
  grossSalary: number;
  employeeContribution: number;
  employerContribution: number;
  totalContribution: number;
  contributionRate: number;
  pensionablePay: number;
}

Advanced Usage​

// NSSF calculator with custom rates and limits
const AdvancedNSSFCalculator = () => {
  const handleNSSFCalculation = (contribution: NSSFContribution) => {
    // Custom handling logic
    console.log('NSSF Contribution:', contribution);
  };

  return (
    <NSSFCalculator
      grossSalary={150000}
      contributionRate={0.06}
      minimumContribution={200}
      maximumContribution={1080}
      onCalculate={handleNSSFCalculation}
      showEmployerContribution={true}
      currency='KES'
      className='advanced-nssf-calculator'
    />
  );
};

NHIFCalculator Component​

Basic Usage​

import { NHIFCalculator } from '@/components/tax-compliance/NHIFCalculator';

// Basic NHIF calculation
const BasicNHIFCalculator = () => {
  const [deduction, setDeduction] = useState<NHIFDeduction | null>(null);

  return (
    <NHIFCalculator
      grossSalary={50000}
      onCalculate={setDeduction}
      showBenefits={true}
      currency='KES'
    />
  );
};

Props Interface​

interface NHIFCalculatorProps {
  grossSalary: number;
  onCalculate: (deduction: NHIFDeduction) => void;
  showBenefits?: boolean;
  currency?: string;
  nhifRates?: NHIFRate[];
  className?: string;
  loading?: boolean;
  disabled?: boolean;
}

interface NHIFDeduction {
  grossSalary: number;
  nhifDeduction: number;
  salaryBracket: string;
  benefits: string[];
  coverageLevel: string;
}

interface NHIFRate {
  minSalary: number;
  maxSalary: number;
  deduction: number;
  bracket: string;
}

Advanced Usage​

// NHIF calculator with custom rates
const AdvancedNHIFCalculator = () => {
  const customNHIFRates: NHIFRate[] = [
    { minSalary: 0, maxSalary: 5999, deduction: 150, bracket: 'Band 1' },
    { minSalary: 6000, maxSalary: 7999, deduction: 300, bracket: 'Band 2' },
    { minSalary: 8000, maxSalary: 11999, deduction: 400, bracket: 'Band 3' },
    // ... more bands
  ];

  return (
    <NHIFCalculator
      grossSalary={45000}
      nhifRates={customNHIFRates}
      onCalculate={deduction => console.log(deduction)}
      showBenefits={true}
      currency='KES'
      className='custom-nhif-calculator'
    />
  );
};

P9FormGenerator Component​

Basic Usage​

import { P9FormGenerator } from '@/components/tax-compliance/P9FormGenerator';

// Basic P9 form generation
const BasicP9Form = () => {
  const [p9Data, setP9Data] = useState<P9FormData | null>(null);

  return (
    <P9FormGenerator
      employeeId='EMP001'
      taxYear={2024}
      onGenerate={setP9Data}
      showPreview={true}
      autoCalculate={true}
    />
  );
};

Props Interface​

interface P9FormGeneratorProps {
  employeeId: string;
  taxYear: number;
  onGenerate: (formData: P9FormData) => void;
  showPreview?: boolean;
  autoCalculate?: boolean;
  employeeData?: EmployeeData;
  className?: string;
  loading?: boolean;
  disabled?: boolean;
}

interface P9FormData {
  employeeDetails: EmployeeDetails;
  salaryDetails: SalaryDetails;
  taxCalculations: TaxCalculations;
  statutoryDeductions: StatutoryDeductions;
  monthlyBreakdown: MonthlyBreakdown[];
  annualSummary: AnnualSummary;
  formattedP9: string;
}

interface EmployeeDetails {
  name: string;
  pinNumber: string;
  employeeNumber: string;
  department: string;
  designation: string;
}

Advanced Usage​

// P9 form with custom employee data
const AdvancedP9Form = () => {
  const employeeData: EmployeeData = {
    name: 'John Doe',
    pinNumber: 'A123456789Z',
    employeeNumber: 'EMP001',
    department: 'Finance',
    designation: 'Accountant',
    joinDate: '2024-01-01',
    salaryStructure: 'Monthly',
  };

  const handleP9Generation = (formData: P9FormData) => {
    // Custom P9 handling logic
    console.log('Generated P9:', formData);
    // Could trigger PDF generation, email sending, etc.
  };

  return (
    <P9FormGenerator
      employeeId='EMP001'
      taxYear={2024}
      employeeData={employeeData}
      onGenerate={handleP9Generation}
      showPreview={true}
      autoCalculate={true}
      className='advanced-p9-generator'
    />
  );
};

TaxCalculationSummary Component​

Basic Usage​

import { TaxCalculationSummary } from '@/components/tax-compliance/TaxCalculationSummary';

// Basic tax calculation summary
const BasicTaxSummary = () => {
  const taxData: TaxSummaryData = {
    grossSalary: 100000,
    payeTax: 15000,
    nhifDeduction: 1700,
    nssfContribution: 1080,
    netSalary: 81220,
    effectiveRate: 0.188,
  };

  return (
    <TaxCalculationSummary
      data={taxData}
      showBreakdown={true}
      currency='KES'
      period='monthly'
    />
  );
};

Props Interface​

interface TaxCalculationSummaryProps {
  data: TaxSummaryData;
  showBreakdown?: boolean;
  currency?: string;
  period?: 'monthly' | 'annual';
  onExport?: (format: 'pdf' | 'excel') => void;
  className?: string;
  loading?: boolean;
}

interface TaxSummaryData {
  grossSalary: number;
  payeTax: number;
  nhifDeduction: number;
  nssfContribution: number;
  netSalary: number;
  effectiveRate: number;
  taxBrackets?: TaxBracketSummary[];
  otherDeductions?: OtherDeduction[];
}

Advanced Usage​

// Tax summary with export functionality
const AdvancedTaxSummary = () => {
  const comprehensiveTaxData: TaxSummaryData = {
    grossSalary: 120000,
    payeTax: 18000,
    nhifDeduction: 1700,
    nssfContribution: 1080,
    netSalary: 99220,
    effectiveRate: 0.173,
    taxBrackets: [
      { bracket: '0 - 24,000', rate: 0.1, tax: 2400 },
      { bracket: '24,001 - 32,333', rate: 0.25, tax: 2083 },
      { bracket: '32,334 - 120,000', rate: 0.3, tax: 13517 },
    ],
    otherDeductions: [
      { name: 'Housing Levy', amount: 1200 },
      { name: 'Insurance Relief', amount: -5000 },
    ],
  };

  const handleExport = (format: 'pdf' | 'excel') => {
    // Export logic
    console.log(`Exporting as ${format}`);
  };

  return (
    <TaxCalculationSummary
      data={comprehensiveTaxData}
      showBreakdown={true}
      currency='KES'
      period='monthly'
      onExport={handleExport}
      className='comprehensive-tax-summary'
    />
  );
};

StatutoryReportGenerator Component​

Basic Usage​

import { StatutoryReportGenerator } from '@/components/tax-compliance/StatutoryReportGenerator';

// Basic statutory report generation
const BasicStatutoryReport = () => {
  const [reportData, setReportData] = useState<StatutoryReportData | null>(
    null,
  );

  return (
    <StatutoryReportGenerator
      reportType='paye'
      period={{ from: '2024-01-01', to: '2024-12-31' }}
      onGenerate={setReportData}
      showPreview={true}
    />
  );
};

Props Interface​

interface StatutoryReportGeneratorProps {
  reportType: 'paye' | 'nssf' | 'nhif' | 'p9' | 'comprehensive';
  period: ReportPeriod;
  onGenerate: (data: StatutoryReportData) => void;
  showPreview?: boolean;
  filters?: ReportFilters;
  className?: string;
  loading?: boolean;
  disabled?: boolean;
}

interface ReportPeriod {
  from: string;
  to: string;
}

interface StatutoryReportData {
  reportType: string;
  period: ReportPeriod;
  summary: ReportSummary;
  details: ReportDetail[];
  totals: ReportTotals;
  generatedAt: string;
}

Advanced Usage​

// Comprehensive statutory report with filters
const AdvancedStatutoryReport = () => {
  const reportFilters: ReportFilters = {
    departments: ['Finance', 'HR', 'IT'],
    employeeTypes: ['Permanent', 'Contract'],
    salaryRange: { min: 20000, max: 200000 },
  };

  const handleReportGeneration = (data: StatutoryReportData) => {
    // Custom report handling
    console.log('Generated Report:', data);
  };

  return (
    <StatutoryReportGenerator
      reportType='comprehensive'
      period={{ from: '2024-01-01', to: '2024-12-31' }}
      filters={reportFilters}
      onGenerate={handleReportGeneration}
      showPreview={true}
      className='advanced-statutory-report'
    />
  );
};

TaxBracketDisplay Component​

Basic Usage​

import { TaxBracketDisplay } from '@/components/tax-compliance/TaxBracketDisplay';

// Basic tax bracket display
const BasicTaxBrackets = () => {
  const taxBrackets: TaxBracket[] = [
    { min: 0, max: 24000, rate: 0.1, description: '10% on first 24,000' },
    { min: 24001, max: 32333, rate: 0.25, description: '25% on next 8,333' },
    { min: 32334, max: null, rate: 0.3, description: '30% on excess' },
  ];

  return (
    <TaxBracketDisplay
      brackets={taxBrackets}
      highlightSalary={50000}
      currency='KES'
      showCalculations={true}
    />
  );
};

Props Interface​

interface TaxBracketDisplayProps {
  brackets: TaxBracket[];
  highlightSalary?: number;
  currency?: string;
  showCalculations?: boolean;
  interactive?: boolean;
  className?: string;
}

interface TaxBracket {
  min: number;
  max: number | null;
  rate: number;
  description: string;
  color?: string;
}

ComplianceStatusIndicator Component​

Basic Usage​

import { ComplianceStatusIndicator } from '@/components/tax-compliance/ComplianceStatusIndicator';

// Basic compliance status
const BasicComplianceStatus = () => {
  const complianceData: ComplianceStatus = {
    paye: { status: 'compliant', lastUpdated: '2024-01-15' },
    nssf: { status: 'pending', lastUpdated: '2024-01-10' },
    nhif: { status: 'compliant', lastUpdated: '2024-01-15' },
    returns: { status: 'overdue', lastUpdated: '2023-12-31' },
  };

  return (
    <ComplianceStatusIndicator
      data={complianceData}
      showDetails={true}
      alertOnIssues={true}
    />
  );
};

Props Interface​

interface ComplianceStatusIndicatorProps {
  data: ComplianceStatus;
  showDetails?: boolean;
  alertOnIssues?: boolean;
  className?: string;
}

interface ComplianceStatus {
  paye: ComplianceItem;
  nssf: ComplianceItem;
  nhif: ComplianceItem;
  returns: ComplianceItem;
  [key: string]: ComplianceItem;
}

interface ComplianceItem {
  status: 'compliant' | 'pending' | 'overdue' | 'error';
  lastUpdated: string;
  details?: string;
  dueDate?: string;
}

Styling and Customization​

CSS Classes​

/* PAYE Calculator */
.paye-calculator {
  @apply bg-white rounded-lg shadow-md p-6;
}

.paye-calculator__input {
  @apply w-full p-3 border border-gray-300 rounded-md focus:ring-2 focus:ring-blue-500;
}

.paye-calculator__result {
  @apply mt-4 p-4 bg-gray-50 rounded-md;
}

.paye-calculator__breakdown {
  @apply mt-2 space-y-2;
}

/* NSSF Calculator */
.nssf-calculator {
  @apply bg-white rounded-lg shadow-md p-6;
}

.nssf-calculator__contribution {
  @apply flex justify-between items-center p-3 bg-green-50 rounded-md;
}

/* NHIF Calculator */
.nhif-calculator {
  @apply bg-white rounded-lg shadow-md p-6;
}

.nhif-calculator__deduction {
  @apply flex justify-between items-center p-3 bg-blue-50 rounded-md;
}

/* P9 Form Generator */
.p9-generator {
  @apply bg-white rounded-lg shadow-md p-6;
}

.p9-generator__preview {
  @apply mt-4 p-4 border border-gray-300 rounded-md;
}

/* Tax Calculation Summary */
.tax-summary {
  @apply bg-white rounded-lg shadow-md p-6;
}

.tax-summary__item {
  @apply flex justify-between items-center py-2 border-b border-gray-200;
}

.tax-summary__total {
  @apply font-bold text-lg pt-2 border-t-2 border-gray-400;
}

/* Statutory Report Generator */
.statutory-report {
  @apply bg-white rounded-lg shadow-md p-6;
}

.statutory-report__filters {
  @apply mb-4 p-4 bg-gray-50 rounded-md;
}

/* Tax Bracket Display */
.tax-brackets {
  @apply bg-white rounded-lg shadow-md p-6;
}

.tax-bracket__item {
  @apply flex justify-between items-center p-3 border-l-4 border-blue-500 bg-blue-50 mb-2;
}

.tax-bracket__highlighted {
  @apply border-l-4 border-orange-500 bg-orange-50;
}

/* Compliance Status Indicator */
.compliance-status {
  @apply bg-white rounded-lg shadow-md p-6;
}

.compliance-status__item {
  @apply flex items-center justify-between p-3 rounded-md mb-2;
}

.compliance-status__compliant {
  @apply bg-green-50 text-green-800;
}

.compliance-status__pending {
  @apply bg-yellow-50 text-yellow-800;
}

.compliance-status__overdue {
  @apply bg-red-50 text-red-800;
}

Theme Customization​

// Custom theme for tax compliance components
const taxComplianceTheme = {
  colors: {
    paye: {
      primary: '#3B82F6',
      secondary: '#EFF6FF',
      accent: '#1E40AF',
    },
    nssf: {
      primary: '#10B981',
      secondary: '#ECFDF5',
      accent: '#047857',
    },
    nhif: {
      primary: '#8B5CF6',
      secondary: '#F3E8FF',
      accent: '#6D28D9',
    },
    compliance: {
      compliant: '#10B981',
      pending: '#F59E0B',
      overdue: '#EF4444',
      error: '#DC2626',
    },
  },
  spacing: {
    component: '1.5rem',
    section: '1rem',
    element: '0.5rem',
  },
  typography: {
    heading: 'text-lg font-semibold',
    subheading: 'text-md font-medium',
    body: 'text-sm',
    caption: 'text-xs text-gray-600',
  },
};

Integration Patterns​

Tax Calculation Pipeline​

// Complete tax calculation pipeline
const TaxCalculationPipeline = () => {
  const [employee, setEmployee] = useState<Employee | null>(null);
  const [calculations, setCalculations] = useState<TaxCalculations | null>(
    null,
  );

  const calculateTaxes = async (employeeData: Employee) => {
    try {
      // Step 1: Calculate PAYE
      const payeResult = await calculatePAYE(employeeData.grossSalary, 2024);

      // Step 2: Calculate NSSF
      const nssfResult = await calculateNSSF(employeeData.grossSalary);

      // Step 3: Calculate NHIF
      const nhifResult = await calculateNHIF(employeeData.grossSalary);

      // Step 4: Combine results
      const totalCalculations: TaxCalculations = {
        paye: payeResult,
        nssf: nssfResult,
        nhif: nhifResult,
        netSalary:
          employeeData.grossSalary -
          payeResult.payeTax -
          nssfResult.employeeContribution -
          nhifResult.nhifDeduction,
      };

      setCalculations(totalCalculations);
    } catch (error) {
      console.error('Tax calculation error:', error);
    }
  };

  return (
    <div className='tax-calculation-pipeline'>
      <EmployeeSelector onSelect={setEmployee} />

      {employee && (
        <>
          <PAYECalculator
            grossSalary={employee.grossSalary}
            taxYear={2024}
            onCalculate={result => calculateTaxes(employee)}
          />

          <NSSFCalculator
            grossSalary={employee.grossSalary}
            contributionRate={0.06}
            onCalculate={result => console.log('NSSF:', result)}
          />

          <NHIFCalculator
            grossSalary={employee.grossSalary}
            onCalculate={result => console.log('NHIF:', result)}
          />

          {calculations && (
            <TaxCalculationSummary
              data={calculations}
              showBreakdown={true}
              currency='KES'
            />
          )}
        </>
      )}
    </div>
  );
};

Compliance Dashboard Integration​

// Compliance dashboard with all components
const ComplianceDashboard = () => {
  const [complianceData, setComplianceData] = useState<ComplianceData | null>(
    null,
  );

  useEffect(() => {
    fetchComplianceData();
  }, []);

  const fetchComplianceData = async () => {
    try {
      const data = await api.getComplianceData();
      setComplianceData(data);
    } catch (error) {
      console.error('Failed to fetch compliance data:', error);
    }
  };

  return (
    <div className='compliance-dashboard'>
      <div className='dashboard-header'>
        <h1>Tax Compliance Dashboard</h1>
        <ComplianceStatusIndicator
          data={complianceData?.status}
          showDetails={true}
          alertOnIssues={true}
        />
      </div>

      <div className='dashboard-grid'>
        <div className='col-span-2'>
          <TaxCalculationSummary
            data={complianceData?.summary}
            showBreakdown={true}
            currency='KES'
          />
        </div>

        <div className='col-span-1'>
          <TaxBracketDisplay
            brackets={complianceData?.taxBrackets}
            highlightSalary={complianceData?.averageSalary}
            currency='KES'
            showCalculations={true}
          />
        </div>

        <div className='col-span-3'>
          <StatutoryReportGenerator
            reportType='comprehensive'
            period={{ from: '2024-01-01', to: '2024-12-31' }}
            onGenerate={data => console.log('Report generated:', data)}
            showPreview={true}
          />
        </div>
      </div>
    </div>
  );
};

Accessibility Features​

Keyboard Navigation​

// Keyboard navigation support
const AccessibleTaxCalculator = () => {
  const [focusedElement, setFocusedElement] = useState<string | null>(null);

  const handleKeyDown = (event: KeyboardEvent) => {
    switch (event.key) {
      case 'Tab':
        // Handle tab navigation
        break;
      case 'Enter':
        // Handle enter key actions
        break;
      case 'Escape':
        // Handle escape key actions
        break;
    }
  };

  return (
    <div
      className='accessible-tax-calculator'
      onKeyDown={handleKeyDown}
      role='application'
      aria-label='Tax Calculator'
    >
      <PAYECalculator
        grossSalary={50000}
        taxYear={2024}
        onCalculate={result => console.log(result)}
        aria-describedby='paye-description'
      />

      <div id='paye-description' className='sr-only'>
        Calculate PAYE tax based on gross salary and tax year
      </div>
    </div>
  );
};

Screen Reader Support​

// Screen reader optimized components
const ScreenReaderOptimizedTaxSummary = () => {
  const announceCalculation = (calculation: TaxCalculations) => {
    const announcement = `Tax calculation complete. 
      Gross salary: ${calculation.grossSalary} shillings. 
      PAYE tax: ${calculation.paye.payeTax} shillings. 
      Net salary: ${calculation.netSalary} shillings.`;

    // Announce to screen readers
    const announcer = document.createElement('div');
    announcer.setAttribute('aria-live', 'polite');
    announcer.setAttribute('aria-atomic', 'true');
    announcer.className = 'sr-only';
    announcer.textContent = announcement;
    document.body.appendChild(announcer);

    setTimeout(() => document.body.removeChild(announcer), 1000);
  };

  return (
    <TaxCalculationSummary
      data={taxData}
      showBreakdown={true}
      currency='KES'
      onCalculationComplete={announceCalculation}
      aria-label='Tax Calculation Summary'
    />
  );
};

Performance Optimization​

Memoization​

// Memoized tax calculations
const MemoizedTaxCalculator = React.memo(
  ({ grossSalary, taxYear }: TaxCalculatorProps) => {
    const calculationResult = useMemo(() => {
      return calculatePAYE(grossSalary, taxYear);
    }, [grossSalary, taxYear]);

    const memoizedTaxBrackets = useMemo(() => {
      return getTaxBrackets(taxYear);
    }, [taxYear]);

    return (
      <PAYECalculator
        grossSalary={grossSalary}
        taxYear={taxYear}
        calculationResult={calculationResult}
        taxBrackets={memoizedTaxBrackets}
      />
    );
  },
);

Lazy Loading​

// Lazy loaded tax components
const LazyTaxComponents = () => {
  const PAYECalculator = lazy(
    () => import('@/components/tax-compliance/PAYECalculator'),
  );
  const NSSFCalculator = lazy(
    () => import('@/components/tax-compliance/NSSFCalculator'),
  );
  const P9FormGenerator = lazy(
    () => import('@/components/tax-compliance/P9FormGenerator'),
  );

  return (
    <div className='lazy-tax-components'>
      <Suspense fallback={<div>Loading PAYE Calculator...</div>}>
        <PAYECalculator grossSalary={50000} taxYear={2024} />
      </Suspense>

      <Suspense fallback={<div>Loading NSSF Calculator...</div>}>
        <NSSFCalculator grossSalary={50000} contributionRate={0.06} />
      </Suspense>

      <Suspense fallback={<div>Loading P9 Form Generator...</div>}>
        <P9FormGenerator employeeId='EMP001' taxYear={2024} />
      </Suspense>
    </div>
  );
};

Testing Strategies​

Unit Tests​

// Tax calculation unit tests
describe('PAYECalculator', () => {
  it('should calculate PAYE correctly for basic salary', () => {
    const result = calculatePAYE(50000, 2024);
    expect(result.payeTax).toBe(7500);
    expect(result.netSalary).toBe(42500);
  });

  it('should apply personal relief correctly', () => {
    const result = calculatePAYE(30000, 2024);
    expect(result.personalRelief).toBe(2400);
  });

  it('should handle tax brackets correctly', () => {
    const result = calculatePAYE(100000, 2024);
    expect(result.taxBrackets).toHaveLength(3);
    expect(result.effectiveRate).toBeCloseTo(0.15, 2);
  });
});

describe('NSSFCalculator', () => {
  it('should calculate NSSF contribution correctly', () => {
    const result = calculateNSSF(50000);
    expect(result.employeeContribution).toBe(1080);
    expect(result.employerContribution).toBe(1080);
  });

  it('should apply contribution limits', () => {
    const result = calculateNSSF(200000);
    expect(result.employeeContribution).toBe(1080); // Maximum
  });
});

Integration Tests​

// Tax compliance integration tests
describe('Tax Compliance Integration', () => {
  it('should calculate complete tax package', async () => {
    render(<TaxCalculationPipeline />);

    // Select employee
    const employeeSelect = screen.getByLabelText('Select Employee');
    fireEvent.change(employeeSelect, { target: { value: 'EMP001' } });

    // Wait for calculations
    await waitFor(() => {
      expect(screen.getByText('Tax Calculation Complete')).toBeInTheDocument();
    });

    // Verify all components are rendered
    expect(screen.getByText('PAYE Tax:')).toBeInTheDocument();
    expect(screen.getByText('NSSF Contribution:')).toBeInTheDocument();
    expect(screen.getByText('NHIF Deduction:')).toBeInTheDocument();
    expect(screen.getByText('Net Salary:')).toBeInTheDocument();
  });

  it('should generate P9 form correctly', async () => {
    render(<P9FormGenerator employeeId='EMP001' taxYear={2024} />);

    const generateButton = screen.getByText('Generate P9 Form');
    fireEvent.click(generateButton);

    await waitFor(() => {
      expect(screen.getByText('P9 Form Generated')).toBeInTheDocument();
    });
  });
});

Best Practices​

1. Tax Calculation Accuracy​

// Ensure precision in tax calculations
const preciseTaxCalculation = (amount: number): number => {
  // Use precise decimal arithmetic
  return Math.round(amount * 100) / 100;
};

// Validate tax brackets
const validateTaxBrackets = (brackets: TaxBracket[]): boolean => {
  // Check for gaps or overlaps
  for (let i = 0; i < brackets.length - 1; i++) {
    if (brackets[i].max !== brackets[i + 1].min - 1) {
      return false;
    }
  }
  return true;
};

2. Compliance Data Management​

// Centralized compliance data management
const useComplianceData = () => {
  const [data, setData] = useState<ComplianceData | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  const fetchComplianceData = useCallback(async () => {
    try {
      setLoading(true);
      const response = await api.getComplianceData();
      setData(response);
      setError(null);
    } catch (err) {
      setError('Failed to fetch compliance data');
      console.error('Compliance data fetch error:', err);
    } finally {
      setLoading(false);
    }
  }, []);

  useEffect(() => {
    fetchComplianceData();
  }, [fetchComplianceData]);

  return { data, loading, error, refetch: fetchComplianceData };
};

3. Error Handling​

// Comprehensive error handling for tax calculations
const TaxCalculatorWithErrorHandling = () => {
  const [error, setError] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);

  const handleTaxCalculation = async (salary: number, year: number) => {
    try {
      setLoading(true);
      setError(null);

      // Validate inputs
      if (salary <= 0) {
        throw new Error('Salary must be greater than zero');
      }

      if (year < 2000 || year > new Date().getFullYear()) {
        throw new Error('Invalid tax year');
      }

      // Perform calculation
      const result = await calculatePAYE(salary, year);
      return result;
    } catch (err) {
      const errorMessage =
        err instanceof Error ? err.message : 'Calculation failed';
      setError(errorMessage);
      throw err;
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className='tax-calculator-with-error-handling'>
      {error && (
        <div className='error-alert' role='alert'>
          <p>Error: {error}</p>
          <button onClick={() => setError(null)}>Dismiss</button>
        </div>
      )}

      {loading && (
        <div className='loading-indicator'>
          <p>Calculating taxes...</p>
        </div>
      )}

      <PAYECalculator onCalculate={handleTaxCalculation} disabled={loading} />
    </div>
  );
};

4. Data Security​

// Secure handling of sensitive tax data
const SecureTaxDataHandler = () => {
  const encryptSensitiveData = (data: any): string => {
    // Implement encryption for sensitive data
    return btoa(JSON.stringify(data)); // Basic example
  };

  const decryptSensitiveData = (encryptedData: string): any => {
    // Implement decryption
    return JSON.parse(atob(encryptedData)); // Basic example
  };

  const handleTaxDataSave = (taxData: TaxData) => {
    // Encrypt sensitive fields
    const secureData = {
      ...taxData,
      employeePin: encryptSensitiveData(taxData.employeePin),
      salaryDetails: encryptSensitiveData(taxData.salaryDetails),
    };

    // Save to secure storage
    saveTaxData(secureData);
  };

  return {
    handleTaxDataSave,
    encryptSensitiveData,
    decryptSensitiveData,
  };
};

Migration Guide​

From Legacy Tax System​

// Migration helper for legacy tax calculations
const migrateLegacyTaxData = (legacyData: LegacyTaxData): ModernTaxData => {
  return {
    employeeId: legacyData.emp_id,
    grossSalary: legacyData.gross_pay,
    taxYear: legacyData.tax_year,
    payeCalculation: {
      taxableIncome: legacyData.taxable_income,
      payeTax: legacyData.paye_tax,
      personalRelief: legacyData.personal_relief || 2400,
      netSalary: legacyData.net_pay,
    },
    statutoryDeductions: {
      nssf: legacyData.nssf_contribution,
      nhif: legacyData.nhif_deduction,
    },
  };
};

Component Updates​

// Update existing components to use new tax compliance components
const UpdatedEmployeePayroll = () => {
  // Replace legacy tax calculation with new components
  return (
    <div className='employee-payroll'>
      {/* Old: <LegacyTaxCalculator /> */}
      <TaxCalculationSummary
        data={taxData}
        showBreakdown={true}
        currency='KES'
      />

      {/* Old: <LegacyP9Generator /> */}
      <P9FormGenerator
        employeeId={employee.id}
        taxYear={2024}
        onGenerate={handleP9Generation}
      />

      {/* Old: <LegacyComplianceStatus /> */}
      <ComplianceStatusIndicator
        data={complianceStatus}
        showDetails={true}
        alertOnIssues={true}
      />
    </div>
  );
};

Advanced Usage Examples​

Custom Tax Bracket System​

// Custom tax bracket system with dynamic rates
const CustomTaxBracketSystem = () => {
  const [customBrackets, setCustomBrackets] = useState<TaxBracket[]>([]);
  const [previewSalary, setPreviewSalary] = useState(50000);

  const addTaxBracket = (bracket: TaxBracket) => {
    setCustomBrackets(prev => [...prev, bracket].sort((a, b) => a.min - b.min));
  };

  const removeTaxBracket = (index: number) => {
    setCustomBrackets(prev => prev.filter((_, i) => i !== index));
  };

  return (
    <div className='custom-tax-bracket-system'>
      <div className='bracket-editor'>
        <h3>Tax Bracket Editor</h3>
        <TaxBracketEditor
          brackets={customBrackets}
          onAdd={addTaxBracket}
          onRemove={removeTaxBracket}
        />
      </div>

      <div className='bracket-preview'>
        <h3>Tax Bracket Preview</h3>
        <TaxBracketDisplay
          brackets={customBrackets}
          highlightSalary={previewSalary}
          currency='KES'
          showCalculations={true}
          interactive={true}
        />

        <input
          type='number'
          value={previewSalary}
          onChange={e => setPreviewSalary(Number(e.target.value))}
          placeholder='Enter salary to preview'
        />
      </div>

      <div className='calculation-result'>
        <PAYECalculator
          grossSalary={previewSalary}
          taxYear={2024}
          taxBrackets={customBrackets}
          onCalculate={result => console.log('Custom calculation:', result)}
        />
      </div>
    </div>
  );
};

Multi-Country Tax Compliance​

// Multi-country tax compliance support
const MultiCountryTaxCompliance = () => {
  const [selectedCountry, setSelectedCountry] = useState<string>('Kenya');
  const [taxRules, setTaxRules] = useState<CountryTaxRules | null>(null);

  const countryTaxRules: Record<string, CountryTaxRules> = {
    Kenya: {
      currency: 'KES',
      taxBrackets: [
        { min: 0, max: 24000, rate: 0.10, description: "10% on first 24,000" },
        { min: 24001, max: 32333, rate: 0.25, description: "25% on next 8,333" },
        { min: 32334, max: null, rate: 0.30, description: "30% on excess" }
      ],
      personalRelief: 2400,
      socialSecurity: {
        nssf: { rate: 0.06, max: 1080 },
        nhif: { brackets: [...] }
      }
    },
    Uganda: {
      currency: 'UGX',
      taxBrackets: [
        { min: 0, max: 2820000, rate: 0.00, description: "0% on first 2,820,000" },
        { min: 2820001, max: 4920000, rate: 0.10, description: "10% on next 2,100,000" },
        { min: 4920001, max: null, rate: 0.30, description: "30% on excess" }
      ],
      personalRelief: 0,
      socialSecurity: {
        nssf: { rate: 0.05, max: 15000 }
      }
    }
  };

  useEffect(() => {
    setTaxRules(countryTaxRules[selectedCountry]);
  }, [selectedCountry]);

  return (
    <div className="multi-country-tax-compliance">
      <div className="country-selector">
        <label>Select Country:</label>
        <select
          value={selectedCountry}
          onChange={(e) => setSelectedCountry(e.target.value)}
        >
          <option value="Kenya">Kenya</option>
          <option value="Uganda">Uganda</option>
          <option value="Tanzania">Tanzania</option>
        </select>
      </div>

      {taxRules && (
        <>
          <TaxBracketDisplay
            brackets={taxRules.taxBrackets}
            currency={taxRules.currency}
            showCalculations={true}
          />

          <PAYECalculator
            grossSalary={100000}
            taxYear={2024}
            taxBrackets={taxRules.taxBrackets}
            personalRelief={taxRules.personalRelief}
            currency={taxRules.currency}
            onCalculate={(result) => console.log(`${selectedCountry} tax:`, result)}
          />

          {taxRules.socialSecurity.nssf && (
            <NSSFCalculator
              grossSalary={100000}
              contributionRate={taxRules.socialSecurity.nssf.rate}
              maximumContribution={taxRules.socialSecurity.nssf.max}
              currency={taxRules.currency}
            />
          )}
        </>
      )}
    </div>
  );
};

This comprehensive documentation covers all the tax compliance components in the WorkPayCore Frontend, providing detailed information about each component, their usage patterns, styling options, integration methods, and best practices for implementation.