170 lines
7.5 KiB
Markdown
170 lines
7.5 KiB
Markdown
# Refactor Strategy
|
|
|
|
This document outlines a pragmatic, step-by-step refactor plan to improve structure, readability, and maintainability. Each step includes a clear outcome and a checkbox to track progress.
|
|
|
|
Last updated: 2025-10-18
|
|
|
|
## Goals
|
|
|
|
- Separate concerns (routing, HTTP/API, mapping/normalization, UI logic)
|
|
- Improve readability and testability
|
|
- Establish light-weight standards (naming, lint/format) without blocking development
|
|
- Keep changes incremental and safe
|
|
|
|
## Phases and Steps
|
|
|
|
### 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.
|
|
|
|
Last updated: 2025-10-18
|
|
|
|
## Goals
|
|
|
|
- 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.
|
|
|
|
## Current status
|
|
|
|
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`
|
|
|
|
Remaining to migrate (Options API or mixed):
|
|
|
|
- Core
|
|
- `App.vue`
|
|
- `components/AlertToast.vue`
|
|
- `components/LoginPage.vue`
|
|
|
|
- Recipes
|
|
- `components/recipes/EditRecipePage.vue` (most complex)
|
|
|
|
- Meals
|
|
- `components/meals/DatePicker.vue`
|
|
- `components/meals/PersonList.vue` (mixed Options+setup, unify under `<script setup>`)
|
|
|
|
- Ingredients
|
|
- `components/ingredients/EditableIngredientsPanel.vue`
|
|
|
|
- Shopping
|
|
- `components/shopping/ShoppingListItem.vue`
|
|
|
|
## Migration order (batches)
|
|
|
|
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
|
|
|
|
- [ ] Core: `App.vue`
|
|
- [ ] Core: `components/AlertToast.vue`
|
|
- [x] Core: `components/ActionItem.vue`
|
|
- [ ] Core: `components/LoginPage.vue`
|
|
|
|
- [x] Recipes: `components/recipes/RecipesPage.vue`
|
|
- [x] Recipes: `components/recipes/RecipeSearchBox.vue`
|
|
- [x] Recipes: `components/recipes/RecipeCard.vue`
|
|
- [ ] 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`
|
|
|
|
## 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.
|