Shopping list and food preferences

Two small features sit next to nutrition. The shopping list is a checklist of foods the coach recommends. Food preferences let the trainee say which foods and food categories they do not eat, which reshapes the menu the server returns. Both are opened from the profile screen (src/features/profile/presentation/ProfileScreen.tsx) through router.push('/shopping-list') and router.push('/food-preferences').

Shopping list

Files

File	Role
`src/app/(app)/shopping-list.tsx`	Route. Renders `ShoppingListScreen`
`src/features/shopping/presentation/ShoppingListScreen.tsx`	The checklist
`src/features/shopping/data/shoppingApi.ts`	HTTP calls
`src/features/shopping/data/types.ts`	`ShoppingCategory`, `ShoppingFood`, `ShoppingListItem`
`src/features/shopping/hooks/useShopping.ts`	Query and mutation hooks, `shoppingKeys`
`src/features/shopping/hooks/useShoppingSection.ts`	Everything the content tab’s shopping section needs in one hook
`src/features/shopping/lib/shopping.ts`	Category label and icon lookup
`src/features/shopping/components/`	`ShoppingListRow`, `ShoppingFoodRow`, `ShoppingRecommendationsList`

Two surfaces

The feature has two screens that share one list. Recommendations, inside the content tab. ContentScreen (src/features/content/presentation/ContentScreen.tsx) has a shopping section, keyed by SHOPPING_KEY = 'shopping' from src/features/content/lib/content.ts. When that section is active it renders ShoppingRecommendationsList: the foods the trainee can add, a search field, a category filter and a button to the list. The section can be opened directly with the section route param. The list, at /shopping-list. ShoppingListScreen shows the items already added, each with a checkbox and a remove button. Its “add items” button navigates back to the recommendations with router.navigate({ pathname: '/content', params: { section: 'shopping' } }).

Data shapes

type ShoppingCategory = { value: string; count: number };

type ShoppingFood = {
  id: string;
  name: string;
  brand: string | null;
  category: string | null;
  categories: string[];
};

type ShoppingListItem = {
  id: string;
  foodId: string;
  name: string;
  brand: string | null;
  checked: boolean;
  createdAt: string;
};

Endpoints

List responses are wrapped as { items: T[] }. The API functions unwrap them and return an empty array when the body is missing.

Function	Method and path	Body or query
`getShoppingCategories`	`GET /v1/trainee/shopping/categories`
`getShoppingFoods`	`GET /v1/trainee/shopping/foods`	Optional `category`, optional `q`
`getShoppingList`	`GET /v1/trainee/shopping/list`
`addShoppingItem`	`POST /v1/trainee/shopping/list`	`{ foodId }`
`setShoppingItemChecked`	`PATCH /v1/trainee/shopping/list/<id>`	`{ checked }`
`removeShoppingItem`	`DELETE /v1/trainee/shopping/list/<id>`

Hooks and cache

export const shoppingKeys = {
  categories: ['shopping', 'categories'] as const,
  foods: (category: string, q: string) => ['shopping', 'foods', category, q] as const,
  list: ['shopping', 'list'] as const,
};

Hook	Notes
`useShoppingCategories(enabled)`	Stale time 60 s
`useShoppingFoods(category, search, enabled)`	Trims both inputs. Stale time 60 s. `placeholderData: keepPreviousData`, so the previous results stay on screen while a new filter loads
`useShoppingList(enabled)`	Stale time 30 s
`useAddShoppingItem()`	Invalidates the list on success
`useSetShoppingItemChecked()`	Optimistic. See below
`useRemoveShoppingItem()`	Invalidates the list on success

Ticking an item is optimistic. onMutate cancels in-flight list queries, saves the previous list and flips checked in the cache. onError restores the saved list. onSettled invalidates the list either way. Adding and removing are not optimistic. They wait for the server and then refetch.

useShoppingSection

useShoppingSection(active, category, search) is what ContentScreen calls. The three queries only run while active is true, so nothing is fetched until the trainee opens the shopping section. It returns:

categories and foods for the list and the filter.
addedIds, a Set of the foodId values already on the list. ShoppingFoodRow uses it to show a check mark and disable the add button.
add(foodId), which runs the add mutation and shows a toast on success.
refetch(), which refetches all three queries.
isLoading and isRefetching flags.

The search text is debounced in ContentScreen with useDebouncedValue before it reaches the hook.

List screen behaviour

ShoppingListScreen supports pull to refresh, shows three skeleton rows while loading, and an empty state with a hint when the list has no items. Removing an item shows a toast on success. A checked row is drawn struck through and dimmed. ShoppingRecommendationsList is a FlatList (initialNumToRender 10, windowSize 7, removeClippedSubviews). Its empty component is five skeleton rows while loading, then a badge whose text depends on whether the trainee is searching or filtering.

Food preferences

Files

File	Role
`src/app/(app)/food-preferences.tsx`	Route. Renders `FoodPreferencesScreen`
`src/features/food-preferences/presentation/FoodPreferencesScreen.tsx`	The screen
`src/features/food-preferences/data/foodPreferencesApi.ts`	`getFoodPreferences`, `saveFoodPreferences`, `FoodPreferencesPayload`
`src/features/food-preferences/hooks/useFoodPreferences.ts`	`useFoodPreferences`, `useSaveFoodPreferences`

The feature has no UI of its own for the picker. It reuses the intake form field: FoodPreferencesField from src/features/forms/components/fields/, the helpers in src/features/forms/lib/foodPreferences.ts, and the FoodPreferenceAnswer type from src/features/forms/data/types.ts. A trainee sees the same control in an intake form and on this screen.

Data shapes

interface FoodPreferenceAnswer {
  excludedCategoryIds: string[];
  excludedFoodIds: string[];
  includedExceptionIds: string[];
}

interface FoodPreferencesPayload {
  value: FoodPreferenceAnswer;
  source: 'coach' | 'form' | 'none';
  origin: { formId: string; formName: string; submittedAt: string } | null;
  updatedAt: string | null;
  excludedCount: number;
}

The answer stores ids only. source says who last set the list: a saved override or the newest intake form. The screen reads only value. How the three lists combine, from isFoodExcluded in src/features/forms/lib/foodPreferences.ts:

A food is excluded when its id is in excludedFoodIds.
It is also excluded when its category is in excludedCategoryIds, unless its id is in includedExceptionIds.

toggleCategory drops the category’s exceptions when the category is switched either way, and keeps foods that were excluded one by one. readFoodPreferenceAnswer(value) normalises any input into the three arrays, dropping non-strings and duplicates.

Endpoints

Function	Method and path	Body
`getFoodPreferences`	`GET /v1/trainee/food-preferences`
`saveFoodPreferences`	`PUT /v1/trainee/food-preferences`	The `FoodPreferenceAnswer` object itself, not wrapped
`getFoodCatalog` (forms feature)	`GET /v1/trainee/foods/catalog`

The catalog is { categories: { id, name }[], foods: { id, name, categoryId }[] }. It is fetched with useFoodCatalog(true), query key ['forms', 'food-catalog'], stale time 5 minutes.

The screen

FoodPreferencesScreen builds a fake form field definition, PROFILE_FIELD, with type: 'food_preferences' and no config. In a form, a coach can hide categories through config.hiddenCategoryIds. Here nothing is hidden, so the trainee sees the whole catalog. State is a local draft:

Before the first edit, the picker shows the server value.
From the first edit, the draft is the source of truth and stays so until a pull to refresh clears it.

Saving

Edits are saved automatically. There is no save button.

const SAVE_DEBOUNCE_MS = 800;

onChange stores the new answer in draft and in pendingRef, and restarts an 800 ms timer.
flush sends pendingRef through useSaveFoodPreferences. It does nothing when a write is already in flight.
When the write settles, flush runs again if a newer edit arrived meanwhile.

Only one PUT is in flight at a time, so two writes cannot overtake each other on a slow network. The effect cleanup calls flush on unmount, so leaving the screen sends an edit that is still waiting on the timer. A failed save shows a toast. Pull to refresh cancels the timer, clears pendingRef and the draft, and refetches both queries. The pending save is dropped on purpose: writing a discarded draft after the refresh would flip the chips back.

Cache effects

useSaveFoodPreferences is optimistic. onMutate cancels the query and writes the new value into the cached payload with source: 'coach'. onError restores the previous payload. onSettled invalidates three things:

['food-preferences']
['nutrition', 'plan'], because exclusions change the menu the server returns
homeQueryKey (['home', 'today']), because the home macros follow the menu

The exclusions are applied by the server when it builds the plan. The app does not filter plan items itself.

Loading and errors

The screen shows three skeleton rows while either query loads or the answer is not ready. If either query fails it shows a message and a retry button that refetches both.

​Shopping list

​Files

​Two surfaces

​Data shapes

​Endpoints

​Hooks and cache

​useShoppingSection

​Categories

​List screen behaviour

​Food preferences

​Files

​Data shapes

​Endpoints

​The screen

​Saving

​Cache effects

​Loading and errors

​Related

Shopping list

Files

Two surfaces

Data shapes

Endpoints

Hooks and cache

useShoppingSection

Categories

List screen behaviour

Food preferences

Files

Data shapes

Endpoints

The screen

Saving

Cache effects

Loading and errors

Related