Update readmes
This commit is contained in:
220
docs/2025-11-26_MIGRATION_HISTORY.md
Normal file
220
docs/2025-11-26_MIGRATION_HISTORY.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# Migration History
|
||||
|
||||
## November 26, 2025 - TypeScript & shadcn/ui Migration
|
||||
|
||||
### Overview
|
||||
Complete migration from JavaScript to TypeScript with shadcn/ui component library integration.
|
||||
|
||||
### What Was Changed
|
||||
|
||||
#### 1. TypeScript Migration
|
||||
**Files Migrated**: All 34 source files converted from `.js` to `.ts`/`.tsx`
|
||||
- ✅ `src/utils/*` → TypeScript with proper type definitions
|
||||
- ✅ `src/hooks/*` → TypeScript with generic types
|
||||
- ✅ `src/components/*` → React components to `.tsx`
|
||||
- ✅ `src/locales/*` → i18n files to TypeScript
|
||||
- ✅ `src/constants/defaults.js` → `defaults.ts` with exported types
|
||||
|
||||
**Type Definitions Added**:
|
||||
```typescript
|
||||
interface AppState {
|
||||
pkParams: PkParams;
|
||||
doses: Dose[];
|
||||
steadyStateConfig: SteadyStateConfig;
|
||||
therapeuticRange: TherapeuticRange;
|
||||
doseIncrement: string;
|
||||
uiSettings: UiSettings;
|
||||
}
|
||||
|
||||
interface Dose {
|
||||
time: string;
|
||||
dose: string;
|
||||
label: string;
|
||||
}
|
||||
|
||||
interface Deviation extends Dose {
|
||||
dayOffset?: number;
|
||||
isAdditional: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
**Import Changes**:
|
||||
- All `.js` extensions removed from imports
|
||||
- TypeScript resolves modules without extensions
|
||||
- Path aliases maintained: `@/*` → `./src/*`
|
||||
|
||||
#### 2. shadcn/ui Component Library
|
||||
|
||||
**Installed Components**:
|
||||
- `button`, `card`, `input`, `label`
|
||||
- `popover`, `select`, `separator`
|
||||
- `slider`, `switch`, `tooltip`
|
||||
|
||||
**Custom Form Components Created**:
|
||||
|
||||
**`FormTimeInput`**:
|
||||
- Time picker with hour/minute grid selection
|
||||
- Real-time validation with error tooltips
|
||||
- Focus-based error display
|
||||
- HH:MM format enforcement
|
||||
- Empty value propagation for validation
|
||||
|
||||
**`FormNumericInput`**:
|
||||
- Increment/decrement buttons
|
||||
- Min/max value enforcement
|
||||
- Unit display support
|
||||
- Decimal place formatting
|
||||
- Empty value validation
|
||||
- Clear button option
|
||||
|
||||
**Migration from Custom Components**:
|
||||
```
|
||||
Old: TimeInput.js → New: ui/form-time-input.tsx
|
||||
Old: NumericInput.js → New: ui/form-numeric-input.tsx
|
||||
```
|
||||
|
||||
#### 3. Validation System Overhaul
|
||||
|
||||
**Before**:
|
||||
- Basic client-side validation
|
||||
- Inconsistent error display
|
||||
- No visual feedback consistency
|
||||
|
||||
**After**:
|
||||
- Real-time field validation
|
||||
- Red borders on invalid fields
|
||||
- Error tooltips (shown only on focus to avoid clutter)
|
||||
- Empty value filtering in calculations
|
||||
- Consistent validation across all forms
|
||||
|
||||
**Validation Logic**:
|
||||
```typescript
|
||||
const isInvalid = required && (!value || value.trim() === '');
|
||||
const hasError = error || isInvalid;
|
||||
const showError = hasError && isFocused; // Only show when focused
|
||||
```
|
||||
|
||||
#### 4. Styling Migration
|
||||
|
||||
**From**: Custom CSS with some Tailwind
|
||||
**To**: Full Tailwind CSS + shadcn/ui theme
|
||||
|
||||
**Color System**:
|
||||
- Migrated from OKLCH to HSL format
|
||||
- CSS variables for theme colors
|
||||
- Dark mode ready (infrastructure in place)
|
||||
|
||||
**Global Styles**:
|
||||
- `src/index.css` removed
|
||||
- `src/styles/global.css` created with Tailwind directives
|
||||
- shadcn/ui theme variables added
|
||||
|
||||
#### 5. Dependency Updates
|
||||
|
||||
**Added**:
|
||||
- `@radix-ui/*` packages (8 primitives)
|
||||
- `lucide-react` for icons
|
||||
- `class-variance-authority` for component variants
|
||||
- `tailwind-merge` for class merging
|
||||
- `tailwindcss-animate` for animations
|
||||
|
||||
**Installed but Not Yet Used**:
|
||||
- `react-hook-form` (7.66.1)
|
||||
- `zod` (4.1.13)
|
||||
- `@hookform/resolvers` (5.2.2)
|
||||
|
||||
**Note**: React Hook Form and Zod were installed for potential future use but are not currently integrated. The app uses manual validation.
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
**None for End Users**: The application functionality remains identical.
|
||||
|
||||
**For Developers**:
|
||||
- Must use `.ts`/`.tsx` file extensions
|
||||
- Import paths no longer include `.js` extension
|
||||
- Components expect typed props (currently using `any` for quick migration)
|
||||
- New component API for form inputs
|
||||
|
||||
### File Changes Summary
|
||||
|
||||
**Deleted**:
|
||||
- All `.js` files in `src/` (replaced with `.ts`/`.tsx`)
|
||||
- `src/index.css` (replaced with `src/styles/global.css`)
|
||||
- `src/reportWebVitals.js` (removed, not needed)
|
||||
|
||||
**Created**:
|
||||
- `src/components/ui/` directory (10 shadcn/ui components)
|
||||
- `src/styles/global.css` (Tailwind + theme)
|
||||
- `src/lib/utils.ts` (cn helper function)
|
||||
- All TypeScript versions of previous JS files
|
||||
|
||||
**Modified**:
|
||||
- `tsconfig.json` - Updated for strict TypeScript
|
||||
- `tailwind.config.js` - Added shadcn/ui configuration
|
||||
- `package.json` - Updated dependencies
|
||||
|
||||
### Known Issues & Future Work
|
||||
|
||||
**Type Safety**:
|
||||
- Many components use `: any` for props (quick migration)
|
||||
- Could be improved with proper prop type interfaces
|
||||
- Consider using `React.FC<Props>` pattern
|
||||
|
||||
**Validation**:
|
||||
- Currently manual validation in components
|
||||
- Could integrate React Hook Form + Zod for better DX
|
||||
- Would provide centralized validation logic
|
||||
|
||||
**Testing**:
|
||||
- Test file uses `@ts-ignore` for jest globals
|
||||
- Should install `@types/jest` for proper types
|
||||
|
||||
**Recommendations**:
|
||||
1. Add proper prop types to all components
|
||||
2. Consider React Hook Form integration if forms become more complex
|
||||
3. Add proper jest types for test files
|
||||
4. Add more comprehensive TypeScript types (reduce `any` usage)
|
||||
|
||||
### Migration Commands Reference
|
||||
|
||||
```bash
|
||||
# TypeScript migration
|
||||
find src -name "*.js" -o -name "*.jsx" | while read f; do
|
||||
mv "$f" "${f%.js*}.tsx"
|
||||
done
|
||||
|
||||
# Remove .js extensions from imports
|
||||
find src -name "*.ts" -o -name "*.tsx" | xargs sed -i "s/from '\(.*\)\.js'/from '\1'/g"
|
||||
|
||||
# Add shadcn/ui components
|
||||
npx shadcn@latest add button card input label popover select separator slider switch tooltip
|
||||
```
|
||||
|
||||
### Verification Checklist
|
||||
|
||||
- ✅ All files migrated to TypeScript
|
||||
- ✅ No `.js` files remain in `src/`
|
||||
- ✅ App compiles without errors
|
||||
- ✅ All features working as before
|
||||
- ✅ Validation working correctly
|
||||
- ✅ LocalStorage persistence working
|
||||
- ✅ Charts rendering correctly
|
||||
- ✅ i18n working (EN/DE)
|
||||
- ✅ Responsive layout maintained
|
||||
- ✅ Production build successful
|
||||
|
||||
---
|
||||
|
||||
## October 18, 2025 - Initial Modularization
|
||||
|
||||
### Overview
|
||||
Original monolithic `App.js` split into modular structure with separate components, hooks, and utilities.
|
||||
|
||||
### Changes
|
||||
- Created component directory structure
|
||||
- Extracted custom hooks (useAppState, useSimulation)
|
||||
- Separated utility functions (timeUtils, pharmacokinetics, calculations, suggestions)
|
||||
- Established constants file for defaults
|
||||
|
||||
### Result
|
||||
Codebase organized into ~20 small, focused modules instead of one large file.
|
||||
Reference in New Issue
Block a user