Adding a New Calculator
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the step-by-step process for developing and integrating a new medical calculator into the application. Adhering to this guide ensures consistency in architecture, code style, and user experience across the project. The process involves creating data types, building the calculator component, adding internationalization strings, and integrating it into the main application page.
The overall workflow for adding a new calculator is visualized below.
This diagram shows the sequential steps required to add a new calculator, from type definition to final integration.
Sources: CONTRIBUTING.md
1. Project Structure
All new calculators and related files must be placed in the appropriate directories to maintain project organization. The core directories for calculator development are src/calculators, src/types, src/i18n, and src/app.
This diagram illustrates the key directories and files involved in creating and integrating a new calculator.
Sources: CONTRIBUTING.md:100-106, README.md:31-45
2. Defining Data Types
The first step is to define the TypeScript interfaces for the new calculator's inputs and results. These types ensure data integrity and provide autocompletion during development. All new types should be added to src/types/index.ts.
Sources: CONTRIBUTING.md:5-18, src/types/index.ts
Input and Result Interfaces
Create two interfaces: one for the input fields and one for the calculation results.
Generic Example:
// src/types/index.ts
export interface NewCalculatorInputs {
parameter1: number;
parameter2: string;
// ... other input parameters
}
export interface NewCalculatorResult {
result1: number;
result2: string;
// ... other result values
}
Sources: CONTRIBUTING.md:6-17
Concrete Example (PotassiumCorrectionCalculator):
// src/types/index.ts
export interface PotassiumCorrectionInputs {
currentPotassium: number | null;
weight: number | null;
useAsparkam: boolean;
}
export interface PotassiumCorrectionResult {
deficit: number;
asparkamDose: number;
potassiumChlorideDose: number;
infusionRate: number;
duration: number;
}
Sources: src/types/index.ts:1-13
3. Creating the Calculator Component
Create a new React component file inside the src/calculators/ directory (e.g., NewCalculator.tsx). This component will encapsulate the UI, state management, and calculation logic.
Sources: CONTRIBUTING.md:20-65, src/calculators/PotassiumCorrectionCalculator.tsx
Component Structure
The component should follow a standard structure:
- State Management: Use the
useStatehook to manage user inputs and calculation results. - Calculation Logic: A
calculatefunction that performs the medical calculation based on the input state. - Reset Functionality: A
resetfunction to clear inputs and results. - UI (JSX): The component's render method, which includes input fields, action buttons, and a section to display results.
The following diagram shows the internal data flow of a typical calculator component.
This sequence diagram illustrates how user actions trigger state updates and calculations, leading to the display of results.
Sources: src/calculators/PotassiumCorrectionCalculator.tsx:15-52
Reusable UI Components
The project provides a set of reusable components in src/components/ to maintain a consistent look and feel.
| Component | Description |
|---|---|
Card | A container for the calculator with a title and subtitle. |
NumberInput | An input field specifically for numerical values. |
Select | A dropdown menu for selection from a list of options. |
Checkbox | A checkbox for boolean (true/false) options. |
Button | A button for actions like 'Calculate' and 'Reset'. |
Sources: CONTRIBUTING.md:83-89, src/calculators/PotassiumCorrectionCalculator.tsx:4-8
Example Implementation (PotassiumCorrectionCalculator)
// src/calculators/PotassiumCorrectionCalculator.tsx
'use client';
import React, { useState } from 'react';
import { Card } from '@/components/Card';
import { NumberInput } from '@/components/NumberInput';
import { Checkbox } from '@/components/Checkbox';
import { Button } from '@/components/Button';
import { PotassiumCorrectionInputs, PotassiumCorrectionResult } from '@/types';
import { useLanguage } from '@/i18n/LanguageContext';
export const PotassiumCorrectionCalculator: React.FC = () => {
const { t } = useLanguage();
const [inputs, setInputs] = useState<PotassiumCorrectionInputs>({
currentPotassium: 3.0,
weight: 70,
useAsparkam: true,
});
const [result, setResult] = useState<PotassiumCorrectionResult | null>(null);
const calculateCorrection = () => {
// ... calculation logic ...
setResult({
// ... calculated values ...
});
};
const resetCalculator = () => {
// ... reset logic ...
setResult(null);
};
return (
<Card title={t.potassiumCorrection} /* ... */ >
{/* ... JSX for inputs and result display ... */}
</Card>
);
};
Sources: src/calculators/PotassiumCorrectionCalculator.tsx
4. Internationalization (i18n)
All user-facing text must be added to the internationalization file to support multiple languages.
- Add Keys: Add new string keys for your calculator's title, description, labels, and results to the
Translationsinterface insrc/i18n/translations.ts. - Provide Translations: Add the corresponding translations for each supported language (
en,ru,uk) in thetranslationsobject. - Use in Component: Use the
useLanguagehook and thetfunction to display text in your component:t.yourNewKey.
Sources: src/i18n/translations.ts, src/calculators/ElectrolyteCorrectionCalculator.tsx:16
Example:
// src/i18n/translations.ts
export interface Translations {
// ... existing keys
newCalculatorTitle: string;
newCalculatorDescription: string;
}
export const translations: Record<Language, Translations> = {
en: {
// ...
newCalculatorTitle: 'New Calculator',
newCalculatorDescription: 'Description for the new calculator.',
},
ru: {
// ...
newCalculatorTitle: 'Новый калькулятор',
newCalculatorDescription: 'Описание для нового калькулятора.',
},
// ... other languages
};
Sources: src/i18n/translations.ts:1-550
5. Integrating into the Main Page
The final step is to make the new calculator accessible from the main application page (src/app/page.tsx).
Sources: CONTRIBUTING.md:67-91, src/app/page.tsx
Steps for Integration
-
Update
CalculatorType: Add a unique identifier for your new calculator to theCalculatorTypeunion type.// src/app/page.tsx type CalculatorType = 'home' | 'electrolyte' | 'antibiotic' | 'pediatric' | 'bloodGas' | 'infusionTherapy' | 'newCalculator';Sources: src/app/page.tsx:11, CONTRIBUTING.md:71
-
Import the Component: Import your newly created calculator component at the top of
src/app/page.tsx.// src/app/page.tsx import { NewCalculator } from '@/calculators/NewCalculator';Sources: CONTRIBUTING.md:69, src/app/page.tsx:3-8
-
Add Navigation: Add a button or card on the home screen that sets the
activeCalculatorstate to your new calculator's identifier when clicked.// src/app/page.tsx - Example for a navigation button in the header <button onClick={() => setActiveCalculator('newCalculator')} className={`...`} > {t.newCalculatorTitle} </button>Sources: src/app/page.tsx:50-58, CONTRIBUTING.md:74-81
-
Conditionally Render: Add a new block in the main content area to render your calculator component when its
activeCalculatorstate is selected.// src/app/page.tsx {activeCalculator === 'newCalculator' && ( <div> <div className="mb-6 text-center"> <h2 className="text-2xl font-semibold text-foreground mb-2"> {t.newCalculatorTitle} </h2> <p className="text-muted-foreground max-w-2xl mx-auto"> {t.newCalculatorDescription} </p> </div> <NewCalculator /> </div> )}
Conclusion
By following these five steps—defining types, creating the component, adding i18n strings, integrating into the main page, and using the established project structure—developers can efficiently add new, high-quality medical calculators. This standardized process ensures that the application remains maintainable, scalable, and consistent for both developers and end-users.
Sources: CONTRIBUTING.md