jacob/munch-ease-frontend
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Readme updates

Browse source
This commit is contained in:
jableader 2025-10-18 14:06:24 +11:00
parent 68e82f1fa2
commit d1534934c0
2 changed files with 97 additions and 154 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

87
README.md
View file

@ -1,29 +1,92 @@
# doof-front
## Munch Ease — Plan, Cook, Shop, Repeat
## Project setup
Munch Ease is a snappy Vue 3 app that helps you plan meals, manage recipes, and turn plans into stress-free shopping lists. Search and save recipes, build your weekly meal plan, and seamlessly check items off your shopping list—everything stays in sync so you can focus on what’s cooking.
```
Built with modern Vue patterns, a clean API layer, and lightweight tests, the project is easy to extend and fun to work on.
---
## Quick start
1) Install dependencies
```bash
npm install
```
### Compiles and hot-reloads for development
2) Run the dev server
```
```bash
npm run serve
```
### Compiles and minifies for production
3) Run unit tests (Vitest)
```bash
npm run test
```
4) Build for production
```bash
npm run build
```
### Lints and fixes files
Environment
- API base URL: set VUE_APP_API_BASE (e.g. http://localhost:8081)
```
npm run lint
```
---
### Customize configuration
## Architecture and conventions
See [Configuration Reference](https://cli.vuejs.org/config/).
The codebase follows clear boundaries and Vue 3 Composition API throughout.
- Routing and auth
- Centralized in `src/router/index.js` with named routes and an auth guard via route meta `requiresAuth`.
- Components use `useRouter/useRoute` for navigation and route access.
- API layer and mappers
- `src/api/http.js` is a tiny JSON fetch wrapper that honors `VUE_APP_API_BASE`.
- Feature services live in `src/api/*` (meals, recipes, shopping, auth, persons).
- Normalization lives in `src/api/mappers/*` (e.g., date parsing, shape cleanup).
- Composables (UI-facing logic)
- Reusable logic in `src/composables/*` (useAuth, useMeals, useShopping).
- Components stay thin: data via refs/reactive, effects via computed/watch.
- Components
- All Single File Components use `<script setup>`.
- Props via `defineProps`, events via `defineEmits`, routing via `useRouter`.
- Event bus for alerts is in `src/alert.js` with `AlertToast` subscribing; can evolve into a `useAlert` composable.
- Testing
- Vitest configured (`vitest.config.js`) with `@` alias to `src`.
- Targeted unit tests cover units and API mappers under `tests/`.
- Formatting and linting
- Prettier is the source of truth; Husky + lint-staged auto-format on commit.
- ESLint configured for Vue 3 and Composition API macros.
- Recommended: use Volar in your editor for Vue intelligence.
Folder highlights
- `src/api/` — HTTP wrapper, feature services, and data mappers
- `src/composables/` — Reusable app logic (auth, meals, shopping)
- `src/components/` — UI components and pages (all in `<script setup>`)
- `src/router/` — Route definitions and auth guard
---
## Development tips
- Prefer composables for shared logic; keep components presentational where possible.
- Use computed for derived values; avoid mutating props directly.
- When navigating, prefer named routes for stability.
- Keep tests small and fast; add a test when you add a new mapper or unit.
---
## Troubleshooting
- API errors: verify `VUE_APP_API_BASE` is set and reachable.
- Type/IDE help: ensure Volar is enabled and ESLint is not conflicting with Prettier.
- Build issues: this project uses Vue CLI 5. If migrating to Vite, update scripts and configs accordingly.

164
refactor-strategy.md
View file

@ -15,159 +15,39 @@ Last updated: 2025-10-18
### Phase 1 — Routing and Auth (Foundational)
- [x] Extract router into `src/router/index.js` with named routes
- [x] Add route meta `requiresAuth` and a global auth guard
- [x] Remove auth-redirect from `App.vue` (handled by guard instead)
- [x] Convert top-level nav to use route names consistently (optional)
Outcome: Routing logic is centralized and testable; pages redirect consistently based on auth.
### Phase 2 — API Layer Split (Incremental)
- [x] Add `src/api/http.js` wrapper for JSON fetch with error handling and env-based base URL
- [x] Add `src/api/mappers/mealMapper.js` to normalize Meal data (dates)
- [x] Add `src/api/meals.js` and migrate MealPlan API calls (get upcoming, mark consumed, delete)
- [x] Create `src/api/recipes.js` and migrate recipe endpoints
- [x] Create `src/api/shopping.js` and migrate shopping endpoints
- [x] Create `src/api/auth.js` and migrate auth endpoints
Outcome: Feature modules call cohesive services; logic for mapping/normalization is isolated and testable.
### Phase 3 — Composables (UI-Facing Logic)
- [x] Add `src/composables/useAuth.js` (user ref, ensureAuth)
- [x] Add `src/composables/useMeals.js` (fetch and mutate meals)
- [x] Refactor pages to use composables and `<script setup>` where appropriate
- Converted: `MealPlanPage.vue`, `EditMealPage.vue`, `CurrentShoppingListPage.vue`, `MyShoppingPage.vue`, `PurchasedShoppingListPage.vue`
- Added: `src/composables/useShopping.js`; adopted by shopping pages
Outcome: Components get smaller and easier to read; business logic is reusable.
### Phase 4 — Tooling and Standards
- [x] Add Prettier config and .editorconfig; wire Prettier with ESLint
- [ ] Upgrade ESLint (if/when convenient) and align with Vue 3 rules
- [x] Ensure Volar is used (dev environment) for Vue 3 type intelligence
- [x] Add lint-staged + husky for `pre-commit` formatting
- Optional next: enable Vue macros (defineProps/defineOptions) in ESLint or upgrade ESLint/vue plugin
Outcome: Stable formatting and consistent linting across contributors.
### Phase 5 — Tests (Targeted)
# Composition API Migration Plan
This document tracks the migration of remaining components to Vue 3 Composition API using `<script setup>`, with clear ordering and acceptance criteria.
# Refactor Strategy (Outstanding Work)
Last updated: 2025-10-18
## Goals
Only outstanding, actionable steps are listed below. Completed work has been removed for clarity.
- Convert all SFCs to Composition API `<script setup>`.
- Remove Options API patterns (`data`, `methods`, `computed`, `watch`, `this.*`).
- Standardize on composables for cross-cutting concerns (auth, alerts, API calls).
- Keep changes incremental and safe with focused PRs and existing tests.
## 1) Linting and rules modernization
- Evaluate upgrading ESLint and eslint-plugin-vue to latest that fully supports Vue 3 macros and recommended rules.
- Align rules with Composition API best practices; ensure Prettier remains source of truth.
## Current status
Acceptance: ESLint upgrade plan decided (or implemented), rules apply cleanly, lint passes.
Already using `<script setup>`:
- Meals: `MealPlanPage.vue`, `EditMealPage.vue`, `meals/MealCard.vue`
- Shopping: `CurrentShoppingListPage.vue`, `MyShoppingPage.vue`, `PurchasedShoppingListPage.vue`, `shopping/MealSelectionList.vue`, `shopping/ShoppingListItem.vue`
- Core/Leaf: `components/ActionItem.vue`, `recipes/RecipeCard.vue`, `ingredients/CompactParsedIngredient.vue`
- Ingredients: `ingredients/IngredientLine.vue`, `ingredients/EditableIngredientsPanel.vue`
- Recipes: `components/recipes/RecipesPage.vue`, `components/recipes/RecipeSearchBox.vue`
- Recipes: `components/recipes/RecipesPage.vue`, `components/recipes/RecipeSearchBox.vue`, `components/recipes/EditRecipePage.vue`
## 2) Alerts as a composable (nice-to-have)
- Replace the simple event bus in `src/alert.js` with a `useAlert` composable (reactive queue API) and adapt `AlertToast.vue`.
- Provide show({ heading, message, type }) and auto-dismiss with clear-on-click.
Remaining to migrate (Options API or mixed):
Acceptance: AlertToast driven by composable; no global mutable arrays; behavior unchanged.
- Core
-
-
-
## 3) Incremental test coverage
- Add unit tests for new utilities/composables when added (e.g., `useAlert`).
- Consider snapshot tests for components with stable UI fragments (cards, list items).
- Recipes
-
Acceptance: New logic lands with tests; existing tests stay green.
- Meals
- `components/meals/DatePicker.vue`
- `components/meals/PersonList.vue` (mixed Options+setup, unify under `<script setup>`)
## 4) Developer experience
- Document .env usage with `VUE_APP_API_BASE` and add a `.env.example` file.
- Add Volar as a recommended extension in the project docs (README updated).
- Ingredients
- `components/ingredients/EditableIngredientsPanel.vue`
Acceptance: Clear env setup; editor help consistent.
- Shopping
- `components/shopping/ShoppingListItem.vue`
## 5) Optional: Migrate from Vue CLI to Vite
- If desired, migrate build tooling to Vite for faster dev server and simpler config.
- Update scripts, configure vitest (already in place), and resolve aliasing.
## Migration order (batches)
Acceptance: Dev/build parity maintained; cold/hot start noticeably faster.
1) Leaf/presentational components (low risk)
- `ActionItem.vue`, `RecipeCard.vue`, `CompactParsedIngredient.vue`
- Patterns: defineProps, no router; replace `props: ['x']` with `defineProps<{...}>` (or JSDoc). Simple emits with `defineEmits`.
2) Simple interactive components
- `IngredientLine.vue`, `MealCard.vue`, `MealSelectionList.vue`, `DatePicker.vue`
- Patterns: replace `data` with `ref/reactive`, computed with `computed`, methods with local functions. Replace `this.$emit` with `emit`.
3) Components with watchers and DOM refs
- `EditableIngredientsPanel.vue`, `PersonList.vue`, `ShoppingListItem.vue`
- Patterns: use `ref` for elements, `onMounted` for subscriptions/layout, `watch` for reactive sources. Ensure timeouts/listeners are cleaned up.
4) Pages and core scaffolding
- `RecipesPage.vue`, `RecipeSearchBox.vue`, `EditRecipePage.vue`, `LoginPage.vue`, `App.vue`, `AlertToast.vue`
- Patterns: replace `this.$router`/`this.$route` with `useRouter`/`useRoute`. Consider a small `useAlert` composable to replace the event bus pattern used by `AlertToast.vue` and current `alert.js`.
## Conventions and helpers
- Routing: `const router = useRouter(); const route = useRoute();`
- Props/Emits:
- `const props = defineProps({ ... })`
- `const emit = defineEmits(['event-name'])`
- State: `const state = reactive({...})` or `const x = ref(initial)`
- Computed/Watch: `const y = computed(() => ...)`; `watch(source, (val, old) => ...)`
- Lifecycle: `onMounted`, `onBeforeUnmount`
- Assets: import statics via `new URL('@/assets/foo.svg', import.meta.url).href` or leave template `require()` where needed (non-blocking).
- Testing: keep current Vitest setup; prefer unit tests for any functional changes.
## Acceptance criteria per component
- The component uses a single `<script setup>` block.
- No `this.*` usage remains; props accessed via `props` or destructured; emits via `emit`.
- Route navigation uses `useRouter`/`useRoute` where applicable.
- All existing functionality and events preserved.
- Lint/test/build pass.
## Tracking checklist
- [x] Core: `App.vue`
- [x] Core: `components/AlertToast.vue`
- [x] Core: `components/ActionItem.vue`
- [x] Core: `components/LoginPage.vue`
- [x] Recipes: `components/recipes/RecipesPage.vue`
- [x] Recipes: `components/recipes/RecipeSearchBox.vue`
- [x] Recipes: `components/recipes/RecipeCard.vue`
- [x] Recipes: `components/recipes/EditRecipePage.vue`
- [x] Meals: `components/meals/MealCard.vue`
- [x] Meals: `components/meals/DatePicker.vue`
- [x] Meals: `components/meals/PersonList.vue`
- [x] Ingredients: `components/ingredients/CompactParsedIngredient.vue`
- [x] Ingredients: `components/ingredients/IngredientLine.vue`
- [x] Ingredients: `components/ingredients/EditableIngredientsPanel.vue`
- [x] Shopping: `components/shopping/MealSelectionList.vue`
- [x] Shopping: `components/shopping/ShoppingListItem.vue`
All components are now migrated to `<script setup>`.
## Notes and risks
- `PersonList.vue` aligns a dropdown to an input via DOM measurements; ensure the ref-based approach updates positions correctly on focus/resize.
- `RecipeSearchBox.vue` uses timeouts for debouncing; prefer `watch` with a debounced effect and clean up on unmount.
- `AlertToast.vue` uses a simple event-bus (`alert.js`); consider migrating to a `useAlert` composable with a `ref`-based queue to simplify subscriptions.
## Done (context)
- Routing extracted with auth guard; API layer split; composables for auth/meals/shopping; prettier/husky configured; Vitest tests for mappers and units in place.