sundog-calculator/README.md

# 🐕 Sundog Dog Food Calorie Calculator

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)
- **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, optimized layouts for all devices
- **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)
```html
<!-- Basic usage -->
<script src="https://yourdomain.com/sundog-dog-food-calculator.js"></script>
<div id="dog-calorie-calculator"></div>

<!-- With theme and scale options -->
<div id="dog-calorie-calculator" data-theme="dark" data-scale="0.8"></div>
```

### Option 2: iframe Embed
```html
<!-- Basic iframe -->
<iframe 
    src="https://yourdomain.com/iframe.html"
    width="100%" 
    height="600"
    frameborder="0"
    title="Dog Calorie Calculator">
</iframe>

<!-- With theme and scale parameters -->
<iframe 
    src="https://yourdomain.com/iframe.html?theme=dark&scale=1.2"
    width="100%" 
    height="600"
    frameborder="0"
    title="Dog Calorie Calculator">
</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
Choose from three themes:
- `light` - Light theme
- `dark` - Dark theme  
- `system` - Follows user's OS preference (default)

### Scale Options
Resize the widget from 50% to 200%:
- Range: `0.5` to `2.0`
- Default: `1.0` (100% size)
- Examples: `0.8` (80%), `1.2` (120%), `1.5` (150%)

### Food Energy Units
Support for regional differences:
- `kcal/100g` - European/UK standard (default)
- `kcal/kg` - North American standard
- `kcal/cup` - US/Canada dry food
- `kcal/can` - US/Canada wet food

### Advanced JavaScript Usage
```javascript
new DogCalorieCalculatorWidget(container, {
    theme: 'dark',    // 'light', 'dark', 'system'
    scale: 1.2        // 0.5 to 2.0
});
```

## 🛠️ Development

### Build System
This project uses a single source of truth approach:

- **Master Source**: `iframe.html` - Contains all functionality, styles, and calculations
- **Build Script**: `build.js` - Generates the widget from iframe.html 
- **Generated Output**: `sundog-dog-food-calculator.js` - Embeddable widget

### Development Workflow
1. **Make changes to `iframe.html`** - Edit calculations, design, layout, or functionality
2. **Run the build script**: `node build.js` 
3. **Done!** - Both iframe and widget now have identical functionality

### Why This Approach?
- ✅ **Single Source of Truth** - No need to maintain two separate files
- ✅ **Identical Functionality** - Widget matches iframe exactly
- ✅ **Easy Maintenance** - Edit once, deploy everywhere
- ✅ **No Sync Issues** - Build script ensures consistency

### Build Script Features
- Extracts CSS, HTML, and JavaScript from iframe.html
- Transforms CSS classes for widget namespacing (`dog-calculator-` → `dog-calc-`)
- Preserves all functionality including unit switching and calculations
- Maintains theme and scale support via data attributes

## 📁 Project Structure

```
├── iframe.html                    # 🎯 MASTER SOURCE - Edit this file
├── build.js                      # 🔧 Build script - Run after changes
├── sundog-dog-food-calculator.js  # 📦 Generated widget (don't edit)
├── test-widget.html              # 🧪 Test file for widget
└── README.md                     # 📖 This file
```

## 🎨 Brand Integration

The calculator uses your brand's color system:
- **Primary**: `#f19a5f` (Coral)
- **Secondary**: `#9f5999` (Purple)
- **Text**: `#6f3f6d` (Deep Purple)
- **Backgrounds**: Light purple tints
- **Font**: Montserrat

Colors automatically adapt to light/dark themes via CSS custom properties.

## 📊 Dog Activity Factors

| Dog Type | Factor | Use Case |
|----------|--------|----------|
| Puppy (0-4 months) | 3.0 | Rapid growth phase |
| Puppy (4 months - adult) | 2.0 | Continued growth |
| Adult - inactive/obese | 1.2 | Weight management |
| Adult (neutered/spayed) | 1.6 | Typical house pet |
| Adult (intact) | 1.8 | Unaltered adult |
| Adult - weight loss | 1.0 | Calorie restriction |
| Adult - weight gain | 1.7 | Weight building |
| Working dog - light work | 2.0 | Light activity |
| Working dog - moderate work | 3.0 | Regular work |
| Working dog - heavy work | 5.0 | Intensive work |
| Senior dog | 1.1 | Reduced activity |

## 🔧 Technical Implementation

### JavaScript Widget Features
- **Auto-initialization**: Detects `#dog-calorie-calculator` containers
- **CSS Namespacing**: All classes prefixed with `dog-calc-`
- **Shadow DOM Ready**: Prepared for better style isolation
- **Real-time Validation**: Input validation with error messages
- **Mobile Optimized**: Responsive breakpoints and touch-friendly

### iframe Features
- **Auto-resize**: Communicates height changes to parent
- **Style Isolation**: Complete protection from host site CSS
- **Loading Animation**: Smooth fade-in when ready
- **Cross-origin Ready**: PostMessage communication for integration

## 🚀 Deployment Guide

### 1. Host the Files
Upload these files to your web server:
- `sundog-dog-food-calculator.js` (for widget embedding)
- `iframe.html` (for iframe embedding)

### 2. Update URLs
Replace `https://yourdomain.com` in:
- `test-widget.html` examples
- `sundog-dog-food-calculator.js` comments
- This README

### 3. CDN Distribution (Optional)
For better performance, serve the widget script via CDN:
- Use CloudFlare, AWS CloudFront, or similar
- Enable CORS headers for cross-origin requests
- Set appropriate cache headers (1 day for updates)

### 4. Analytics Integration
Add tracking to understand usage:

```javascript
// Track widget interactions
document.addEventListener('DOMContentLoaded', function() {
    // Track when calculator is used
    document.addEventListener('change', function(e) {
        if (e.target.closest('.dog-calc-widget')) {
            gtag('event', 'calculator_interaction', {
                'event_category': 'dog_calculator',
                'event_label': e.target.id
            });
        }
    });
});
```

## 🔒 Brand Protection

### JavaScript Widget Risks
Users can override your styling with:
```css
.dog-calc-footer { display: none !important; }
```

### iframe Protection
Your branding is completely protected in iframe mode. Users cannot:
- Remove your footer link
- Modify your styling
- Access your content with JavaScript

## 📱 Mobile Optimization

- **Responsive breakpoints**: 576px (mobile), 850px (tablet)
- **Touch-friendly**: Larger tap targets on mobile
- **Input optimization**: Numeric keyboards for number inputs
- **Collapsible sections**: Better mobile space utilization

## 🧪 Testing

### Manual Testing Checklist

#### Core Functionality
- [ ] All dog type selections work
- [ ] Weight validation (minimum 0.1kg)
- [ ] RER/MER calculations accurate
- [ ] Unit conversions (g/kg/oz/lb) correct
- [ ] Theme switching (light/dark/system)
- [ ] Scale options (0.5x to 2.0x) work properly

#### 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+
- ✅ Firefox 88+
- ✅ Safari 14+
- ✅ Edge 90+
- ✅ Mobile Safari (iOS 14+)
- ✅ Chrome Mobile (Android 10+)

## 🤝 Contributing

This tool is maintained by Canine Nutrition and Wellness. For suggestions or issues:

1. Test the issue on the demo page
2. Provide specific browser/device information
3. Include steps to reproduce
4. Suggest improvements based on veterinary nutrition standards

## 📄 License

© 2024 Canine Nutrition and Wellness. All rights reserved.

This calculator is provided for educational and professional use. The formulas are based on established veterinary nutrition standards. Always consult with a veterinary nutritionist for specific dietary recommendations.

## 🔗 Links

- **Website**: [caninenutritionandwellness.com](https://caninenutritionandwellness.com)
- **Widget Demo**: Open `test-widget.html` in your browser
- **Standalone**: Open `iframe.html` in your browser

---

**Built with ❤️ for canine nutrition professionals**