Update README.md

README.md

@@ -1,22 +1,44 @@
 # 🐕 Sundog Dog Food Calorie Calculator
 
-A professional veterinary nutrition tool for calculating dogs' daily calorie requirements and food amounts. Built for embedding on websites with complete brand protection options.
+A professional veterinary nutrition tool for calculating dogs' daily calorie requirements and food amounts. Features advanced multi-food source management, percentage locking, and detailed food amount breakdowns. Built for embedding on websites with complete brand protection options.
 
 **By [Canine Nutrition and Wellness](https://caninenutritionandwellness.com)**
 
 ## ✨ Features
 
+### Core Calculation Features
 - **Accurate Calculations**: Uses veterinary-standard RER formula: `70 × (weight in kg)^0.75`
 - **Multiple Activity Levels**: 11 different dog types and activity factors
 - **Multi-Region Support**: kcal/100g (EU/UK), kcal/kg, kcal/cup, kcal/can (US/Canada)
-- **Food Amount Calculator**: Converts calories to grams/kg/oz/lb of food
+- **Unit Conversion**: Automatic conversion to grams/kg/oz/lb for food amounts
+- **Smart Unit Selection**: Auto-selects grams for metric and ounces for imperial systems
+- **Unit Selection Buttons**: Intuitive button interface for choosing display units (g/kg/oz/lb)
+
+### Multi-Food Source Management
+- **Multiple Food Sources**: Add up to 5 different food sources per diet plan
+- **Percentage System**: Distribute diet percentages across multiple foods with real-time validation
+- **Percentage Locking**: Lock specific food source percentages to maintain fixed ratios
+- **Smart Redistribution**: Automatic percentage rebalancing when sources are added/removed
+- **Editable Food Names**: Click-to-edit food source names (e.g., "Morning Kibble", "Evening Wet Food")
+
+### Food Amount Breakdown
+- **Individual Food Amounts**: See exact amounts needed for each food source
+- **Per-Food Calculations**: Calculate specific quantities for different food types
+- **Total Summary**: Combined totals with clear breakdown by food source
+- **Lock Indicators**: Visual indicators showing which percentages are locked
+
+### User Experience
 - **Scalable Widget**: Easily resize from 50% to 200% with data attributes
 - **Theme Support**: Light, dark, and system themes
-- **Responsive Design**: Mobile-first, works on all devices
+- **Responsive Design**: Mobile-first, optimized layouts for all devices
-- **Brand Integration**: Uses Canine Nutrition and Wellness color scheme
 - **Two Embedding Options**: JavaScript widget and iframe
 - **Accessibility**: Full keyboard navigation and screen reader support
 
+### Brand & Integration
+- **Brand Integration**: Uses Canine Nutrition and Wellness color scheme
+- **Professional Design**: Clean, veterinary-grade interface
+- **Brand Protection**: Complete iframe isolation option
+
 ## 🚀 Quick Start
 
 ### Option 1: JavaScript Widget (Recommended)
@@ -50,6 +72,59 @@ A professional veterinary nutrition tool for calculating dogs' daily calorie req
 </iframe>
 ```
 
+## 🍽️ Multi-Food Source Usage
+
+The calculator supports complex feeding plans with multiple food sources, perfect for mixed diets combining dry food, wet food, treats, and supplements.
+
+### Basic Multi-Food Workflow
+
+1. **Start with one food source** - Calculator begins with a single "Food Source 1"
+2. **Add more sources** - Click "Add another food source" (up to 5 total)
+3. **Customize names** - Click any food source name to edit (e.g., "Morning Kibble", "Evening Wet Food")
+4. **Set energy content** - Enter kcal values and select appropriate units for each food
+5. **Adjust percentages** - Use sliders or input fields to distribute diet percentages
+6. **Lock percentages** - Click 🔒 to lock specific food source percentages
+7. **Get individual amounts** - See exact quantities needed for each food source
+
+### Percentage System Features
+
+- **Real-time Validation**: Percentages always total exactly 100%
+- **Smart Redistribution**: When you change one percentage, others adjust automatically
+- **Percentage Locking**: Lock specific sources to maintain fixed ratios
+- **Visual Feedback**: Lock indicators show which percentages are fixed
+- **Bulletproof Logic**: Prevents impossible states (negative percentages, >100% totals)
+
+### Example Usage Scenarios
+
+**Mixed Diet Example:**
+```
+Royal Canin Dry Food    → 70% (locked)
+Blue Buffalo Wet Food   → 25%
+Training Treats         → 5%
+```
+
+**Meal-Based Planning:**
+```
+Morning Kibble          → 50%
+Evening Wet Food        → 30%
+Midday Snacks          → 20%
+```
+
+**Transition Diet:**
+```
+Old Food (reducing)     → 25%
+New Food (increasing)   → 75% (locked)
+```
+
+### Food Amount Breakdown
+
+The calculator provides detailed breakdowns showing:
+- **Individual amounts** for each food source
+- **Percentage distribution** with visual indicators
+- **Lock status** for each food source
+- **Total combined amount** for the specified number of days
+- **Unit conversion** (grams, kg, oz, lb) for all amounts
+
 ## ⚙️ Configuration Options
 
 ### Theme Options
@@ -218,18 +293,39 @@ Your branding is completely protected in iframe mode. Users cannot:
 ## 🧪 Testing
 
 ### Manual Testing Checklist
+
+#### Core Functionality
 - [ ] All dog type selections work
 - [ ] Weight validation (minimum 0.1kg)
 - [ ] RER/MER calculations accurate
-- [ ] Food energy unit selector (kcal/100g, kcal/kg, kcal/cup, kcal/can)
-- [ ] Food energy validation (minimum values per unit)
 - [ ] Unit conversions (g/kg/oz/lb) correct
 - [ ] Theme switching (light/dark/system)
 - [ ] Scale options (0.5x to 2.0x) work properly
-- [ ] Collapsible section toggles
+
+#### Multi-Food Source Features
+- [ ] Add food sources (up to 5 maximum)
+- [ ] Remove food sources (minimum 1 maintained)
+- [ ] Edit food source names (click-to-edit functionality)
+- [ ] Food energy content validation per source
+- [ ] Food energy unit selector per source (kcal/100g, kcal/kg, kcal/cup, kcal/can)
+- [ ] Percentage slider adjustments work correctly
+- [ ] Percentage input field validation
+- [ ] Percentage locking/unlocking (🔒 icon)
+- [ ] Smart percentage redistribution when sources change
+- [ ] Total percentages always equal 100%
+- [ ] Individual food amount calculations
+- [ ] Food amount breakdown display
+- [ ] Add button states ("Add another food source" vs "Maximum 5 sources reached")
+
+#### User Interface
 - [ ] Mobile responsive layout
+- [ ] Collapsible section toggles
+- [ ] Visual lock indicators display correctly
+- [ ] Percentage badges and styling
 - [ ] Branded footer link works
 - [ ] Box shadows consistent across all sections
+- [ ] Food source name alignment on mobile
+- [ ] Proper input field sizing on mobile
 
 ### Browser Compatibility
 - ✅ Chrome 90+
@@ -257,8 +353,8 @@ This calculator is provided for educational and professional use. The formulas a
 ## 🔗 Links
 
 - **Website**: [caninenutritionandwellness.com](https://caninenutritionandwellness.com)
-- **Demo**: Open `embed-demo.html` in your browser
+- **Widget Demo**: Open `test-widget.html` in your browser
-- **Standalone**: Open `index.html` in your browser
+- **Standalone**: Open `iframe.html` in your browser
 
 ---