From b262eab508e8d714e297d2a80766d74adcf3edca Mon Sep 17 00:00:00 2001 From: Andreas Weyer Date: Wed, 26 Nov 2025 20:20:32 +0000 Subject: [PATCH] Update readmes --- README.md | 40 ++++- docs/2025-10-18_MODULAR_STRUCTURE.md | 157 ++++++++++++++----- docs/2025-11-26_MIGRATION_HISTORY.md | 220 +++++++++++++++++++++++++++ docs/README.dev-notes.md | 71 ++++++--- 4 files changed, 429 insertions(+), 59 deletions(-) create mode 100644 docs/2025-11-26_MIGRATION_HISTORY.md diff --git a/README.md b/README.md index a2aacd5..85756e8 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,44 @@ # Medication Plan Assistant -## Basic Setup +A pharmacokinetic simulation tool for Lisdexamfetamine (LDX) and d-Amphetamine medication planning with real-time visualization and dose adjustment suggestions. + +## 🚀 Quick Start ```sh # Install dependencies -npm install -D recharts tailwindcss postcss autoprefixer nodemon - -# Initialize tailwind CSS (creates config files) -npx tailwindcss init -p +npm install # Run the development server npm start + +# Build for production +npm run build ``` + +The app will be available at `http://localhost:3000` (or `http://0.0.0.0:3000` in dev containers). + +## 🛠️ Tech Stack + +- **React 19.1** with TypeScript +- **shadcn/ui** component library (Radix UI primitives) +- **Tailwind CSS** for styling +- **Recharts** for concentration-time charts +- **Create React App** as build tool + +## 📋 Features + +- Interactive dose schedule planning with 5 daily time slots +- Real-time pharmacokinetic simulation +- Deviation tracking from planned doses +- Automatic correction suggestions +- Dual chart view (LDX, d-Amphetamine, or both) +- Advanced PK parameter configuration +- Multi-language support (English/German) +- Local storage persistence + +## 📚 Documentation + +See the [docs/](./docs) folder for detailed documentation: +- [Development Notes](./docs/README.dev-notes.md) - Setup and troubleshooting +- [Modular Structure](./docs/2025-10-18_MODULAR_STRUCTURE.md) - Architecture overview +- [Dev Container Setup](./docs/README.devcontainer.md) - WSL2/Podman configuration diff --git a/docs/2025-10-18_MODULAR_STRUCTURE.md b/docs/2025-10-18_MODULAR_STRUCTURE.md index 810fc57..513214c 100644 --- a/docs/2025-10-18_MODULAR_STRUCTURE.md +++ b/docs/2025-10-18_MODULAR_STRUCTURE.md @@ -1,32 +1,78 @@ # Medication Plan Assistant - Modular Structure -This application has been successfully modularized to simplify maintenance and further development. +This application has been successfully modularized and migrated to TypeScript with shadcn/ui components. -## 📁 New Project Structure +## 📁 Current Project Structure (2025-11-26) ```text src/ -├── App.js # Main component (greatly simplified) -├── components/ # UI components -│ ├── DoseSchedule.js # Dosage schedule input -│ ├── DeviationList.js # Deviations from the schedule -│ ├── SuggestionPanel.js # Correction suggestions -│ ├── SimulationChart.js # Chart component -│ ├── Settings.js # Settings panel -│ ├── TimeInput.js # Time input with picker -│ └── NumericInput.js # Numeric input with +/- buttons -├── hooks/ # Custom React hooks -│ ├── useAppState.js # State management & local storage -│ └── useSimulation.js # Simulation logic & calculations -├── utils/ # Utility functions -│ ├── timeUtils.js # Time utility functions -│ ├── pharmacokinetics.js # PK calculations -│ ├── calculations.js # Concentration calculations -│ └── suggestions.js # Correction suggestion algorithm -└── constants/ - └── defaults.js # Constants & default values +├── App.tsx # Main component (TypeScript) +├── index.tsx # Entry point +├── components/ # UI components (TypeScript) +│ ├── dose-schedule.tsx # Dosage schedule input +│ ├── deviation-list.tsx # Deviations from the schedule +│ ├── suggestion-panel.tsx # Correction suggestions +│ ├── simulation-chart.tsx # Chart component (Recharts) +│ ├── settings.tsx # Settings panel +│ ├── language-selector.tsx # Language switcher +│ └── ui/ # shadcn/ui components +│ ├── form-time-input.tsx # Custom time input with picker +│ ├── form-numeric-input.tsx # Custom numeric input with +/- buttons +│ ├── button.tsx +│ ├── card.tsx +│ ├── input.tsx +│ ├── label.tsx +│ ├── popover.tsx +│ ├── select.tsx +│ ├── separator.tsx +│ ├── slider.tsx +│ ├── switch.tsx +│ └── tooltip.tsx +├── hooks/ # Custom React hooks (TypeScript) +│ ├── useAppState.ts # State management & local storage +│ ├── useSimulation.ts # Simulation logic & calculations +│ └── useLanguage.ts # i18n language management +├── utils/ # Utility functions (TypeScript) +│ ├── timeUtils.ts # Time utility functions +│ ├── pharmacokinetics.ts # PK calculations +│ ├── calculations.ts # Concentration calculations +│ └── suggestions.ts # Correction suggestion algorithm +├── constants/ +│ └── defaults.ts # Constants, types & default values +├── locales/ # Internationalization +│ ├── en.ts # English translations +│ ├── de.ts # German translations +│ └── index.ts # i18n setup +├── styles/ +│ └── global.css # Tailwind CSS + shadcn/ui theme +└── lib/ + └── utils.ts # Utility functions (cn helper) ``` +## 🔄 Recent Migrations (November 2025) + +### ✅ JavaScript → TypeScript +- All `.js` files migrated to `.ts`/`.tsx` +- Type definitions in `constants/defaults.ts` +- Proper TypeScript configuration with strict mode + +### ✅ Custom Components → shadcn/ui +- Replaced custom inputs with shadcn/ui components +- Built custom form components: `FormTimeInput`, `FormNumericInput` +- Integrated Radix UI primitives for accessibility +- Tailwind CSS for consistent styling + +### ✅ Validation Enhancement +- Real-time validation with visual feedback +- Error tooltips (shown on focus only) +- Red borders for invalid fields +- Empty value filtering in calculations + +### ✅ Internationalization +- Multi-language support (EN/DE) +- Browser language detection +- LocalStorage persistence + ## 🎯 Advantages of the new structure ### ✅ Better maintainability @@ -53,30 +99,67 @@ src/ - **Code splitting**: Possible for better performance - **Refactoring**: Changes are limited locally -## 🔧 Technical details +## 🔧 Technical Details -### State management +### State Management -- **useAppState**: Manages global app state and LocalStorage -- **useSimulation**: Manages all simulation-related calculations +- **useAppState**: Manages global app state with LocalStorage persistence +- **useSimulation**: Handles all simulation-related calculations and deviations +- **useLanguage**: Manages i18n state and language switching -### Component architecture +### Component Architecture -- **Dumb components**: UI components receive props and call callbacks -- **Smart Components**: Hooks manage state and business logic -- **Separation of Concerns**: UI, state, and business logic are separated +- **Presentational components**: UI components receive typed props and call callbacks +- **Custom hooks**: Manage state and business logic +- **shadcn/ui base**: Radix UI primitives with Tailwind styling +- **Form components**: Reusable `FormTimeInput` and `FormNumericInput` with validation + +### TypeScript Integration + +- **Type-safe state**: All state objects have proper TypeScript interfaces +- **Type inference**: Leverages TS for better IDE support and compile-time checks +- **Strict mode**: Configured for maximum type safety +- **Exported types**: `Dose`, `Deviation`, `AppState`, `PkParams`, etc. ### Utils & Calculations -- **Pure functions**: All calculations are side-effect-free +- **Pure functions**: All calculations are side-effect-free and deterministic - **Modular exports**: Functions can be imported individually -- **Typed interfaces**: Clear input/output definitions +- **Type-safe interfaces**: Clear input/output types with TypeScript +- **Empty value handling**: Filters out invalid entries before calculations -## 🚀 Migration complete +## 🎯 Key Features -The application works identically to the original version, but now: +### Validation System +- Real-time field validation +- Visual feedback (red borders, error tooltips) +- Focus-based error display (tooltips only show on focus) +- Required field enforcement -- Split into **350+ lines** across **several small modules** -- **Easier to understand** and modify -- **Ready for further features** and improvements -- **More test-friendly** for unit and integration tests +### UI/UX Enhancements +- Time picker with hour/minute grid selection +- Numeric inputs with increment/decrement buttons +- Responsive layout with Tailwind CSS +- Dark mode ready (HSL color variables) + +### Data Persistence +- LocalStorage for all settings +- Automatic save on state changes +- Version-based storage key +- Graceful fallback to defaults + +## 🚀 Evolution Summary + +The application has evolved significantly: + +- **2025-10**: Initial modularization (JS) +- **2025-11**: TypeScript migration (34 TS/TSX files) +- **2025-11**: shadcn/ui component library integration +- **2025-11**: Enhanced validation and UX improvements + +**Current state**: +- **Full TypeScript** with type safety throughout +- **Modern component library** (shadcn/ui + Radix UI) +- **Professional UI/UX** with validation and error handling +- **Maintainable architecture** with clear separation of concerns +- **Production-ready** with optimized builds diff --git a/docs/2025-11-26_MIGRATION_HISTORY.md b/docs/2025-11-26_MIGRATION_HISTORY.md new file mode 100644 index 0000000..8893afc --- /dev/null +++ b/docs/2025-11-26_MIGRATION_HISTORY.md @@ -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` 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. diff --git a/docs/README.dev-notes.md b/docs/README.dev-notes.md index 4711965..2d22804 100644 --- a/docs/README.dev-notes.md +++ b/docs/README.dev-notes.md @@ -1,44 +1,81 @@ # Development Notes -## Initial Setup for Tailwind CSS and Recharts +## Current Tech Stack (2025-11-26) + +- **React 19.1.1** with TypeScript 5.9.3 +- **shadcn/ui** component library (Radix UI + Tailwind) +- **Tailwind CSS 3.4.18** for styling +- **Recharts 3.3.0** for data visualization +- **Create React App 5.0.1** as build tool + +## Initial Setup (Fresh Clone) ```sh -# Hard reset in case of version conflicts / existing installs -npm uninstall tailwindcss postcss autoprefixer recharts nodemon -npm install -D tailwindcss@^3.0.0 postcss@^8.0.0 autoprefixer@^10.0.0 - -npm install --save recharts -rm -rf node_modules package-lock.json - -# Fresh install +# Install all dependencies npm install -# Initialize tailwind CSS (creates config files) -# Note: This may overwrite existing project files -npx tailwindcss init -p +# Run development server +npm start + +# Build for production +npm run build ``` -Content of ./tailwind.config.js: +## shadcn/ui Setup (Already Done) + +The project was set up with shadcn/ui components. If you need to add more components: + +```sh +# Add new shadcn/ui components +npx shadcn@latest add [component-name] + +# Example: +npx shadcn@latest add dialog +``` + +## TypeScript Configuration + +TypeScript is configured with: +- Strict mode enabled +- Path aliases: `@/*` → `./src/*` +- Target: ES5 +- Module: ESNext +- JSX: react-jsx + +## Tailwind CSS Configuration + +Content paths in `tailwind.config.js`: ```javascript -/** @type {import('tailwindcss').Config} */ module.exports = { content: [ "./src/**/*.{js,jsx,ts,tsx}", ], theme: { - extend: {}, + extend: { + colors: { + // HSL-based color system for shadcn/ui + }, + }, }, - plugins: [], + plugins: [require("tailwindcss-animate")], } ``` -Content of ./src/index.css: +Global styles in `./src/styles/global.css`: ```css @tailwind base; @tailwind components; @tailwind utilities; + +@layer base { + :root { + --background: 0 0% 98%; + --foreground: 222 47% 11%; + /* ... more CSS variables for shadcn/ui theme */ + } +} ``` ## WSL Networking Issues