卡路里幫手 — Calorie Helper

Personalised diet and calorie tracking app built for Hong Kong users. Tracks meals from local supermarkets (Wellcome, ParknShop) and cha chaan teng (茶餐廳) menus.

Live: https://roxoctoclaw.github.io/calorie-web-react/

---

Features

• BMR / TDEE Calculator — based on age, height, weight, gender, activity level
• Food Search — 34 supermarket items with HK$ prices and calories
• Calorie Calculator — build custom meals with cooking methods and sauces
• Meal Plan Generator — personalised daily plans (lose / maintain / gain)
• Cha Chaan Teng Menu — 20 dishes + 15 drinks with calorie counts
• Bilingual — English and 繁體中文 (Cantonese)
• Dark Mode — toggle via header button
• Persistent State — all preferences saved to localStorage

---

Tech Stack

• React 19 + Vite 8
• styled-components — CSS-in-JS, no Tailwind
• Custom theme system — central design tokens
• localStorage — client-side persistence

---

Project Structure

src/
  components/
    common/          # Reusable UI components (Button, Card, Input, etc.)
    Calculator.jsx   # Meal builder with food/cooking/sauce selection
    FoodSearch.jsx   # Searchable food list with category filters
    Header.jsx       # Gradient header with lang/dark toggles
    Home.jsx         # Landing page with hero, features, how-to
    MealGenerator.jsx # Personalised meal plan generator
    Profile.jsx      # BMR/TDEE form with BMI display
    TabNav.jsx       # Tab navigation
    TeaRestaurant.jsx # Cha chaan teng dish/drink selector
  data/              # Static data (foods, cooking methods, sauces)
  hooks/             # Custom React hooks (useLocalStorage, useBMR, etc.)
  locales/           # i18n — separate files for zh and en
  styles/            # Theme tokens (colors, spacing, radius)
  utils/             # Pure utility functions (calcPrice, etc.)
  App.jsx            # Root component, global state
  main.jsx           # Entry point

---

Scripts

npm install        # Install dependencies
npm run dev        # Start dev server at localhost:5173
npm run build      # Production build to dist/
npm run preview    # Preview production build locally
npm run lint       # ESLint check

---

Adding New Foods

Edit src/data/foodDatabase.js. Each item follows this shape:

{
  name: "雞胸肉 (美國無激素)",
  nameEn: "Chicken Breast (US Hormone-Free)",
  price: 33.9,
  weight: "450g",
  source: "惠康",        // "惠康" or "百佳"
  category: "肉類",      // 肉類, 魚類, 海鮮, 蔬菜, 水果, 主食, 蛋類, 豆類, 奶類, 芝士
  categoryEn: "Meat",
  calories: 165         // per 100g
}

---

Adding Translations

Every visible string lives in src/locales/:

• zh.js — all 繁體中文 strings
• en.js — all English strings

Both files are kept in sync. To add a new string, add it to both files under the same key.

---

Deployment

The app deploys automatically to GitHub Pages on push to main. The gh-pages branch holds the production build.

Manual deploy:

npm run build
npx gh-pages -d dist -b gh-pages

The vite.config.js is set to base: '/calorie-web-react/' for GitHub Pages subpath hosting.

---

Data Sources

• Calorie data: USDA FoodData Central
• Supermarket prices: Wellcome & ParknShop Hong Kong 2024