diff --git a/docs/component-structure.md b/docs/component-structure.md new file mode 100644 index 0000000..76b3d28 --- /dev/null +++ b/docs/component-structure.md @@ -0,0 +1,194 @@ +# Wireframes and Component Structure + +This document describes the planned user interface, component hierarchy, +component responsibilities, props, and state for Country Explorer. + +## Wireframes + +### Desktop + +![Desktop wireframe](wireframes/desktop-wireframe.png) + +The desktop layout displays the country card and the favorites list next to +each other. Filters and selection controls are displayed above the main +content. + +### Mobile + +![Mobile wireframe](wireframes/mobile-wireframe.png) + +The mobile layout displays all sections in one column. The filters appear +first, followed by the country card, navigation controls, and favorites list. + +These wireframes are initial design sketches. The final appearance may change +during implementation. + +## Country card content + +The application displays one country at a time. The country card will contain: + +- Country name +- Flag +- Capital +- Region +- Population +- Area +- Currency +- Languages +- Favorite status +- Previous and next navigation buttons +- Current position in the country selection + +## Component hierarchy + +- `App` + - `Header` + - `FilterControls` + - `RegionFilter` + - `SortSelector` + - `CountrySelector` + - `CountryCard` + - `FavoriteButton` + - `NavigationControls` + - `FavoritesList` + - `Footer` + +## Component responsibilities + +### App + +The root component of the application. It coordinates the main application +state and passes data and callback functions to child components. + +Responsibilities: + +- Retrieve country data through the country query hook +- Store the currently selected country +- Store the selected region and sorting option +- Store the user's favorite countries +- Produce the filtered and sorted country selection +- Display loading and error states +- Pass data and callbacks to child components + +### Header + +Displays the application title and a short introduction. + +### FilterControls + +Groups the controls used to filter and sort countries. + +Props: + +- Current region +- Current sorting option +- Callback for changing region +- Callback for changing sorting option + +### RegionFilter + +Allows the user to filter countries by region. + +Props: + +- Available regions +- Selected region +- Callback for changing the selected region + +### SortSelector + +Allows the user to change the order of the countries. + +Props: + +- Selected sorting option +- Callback for changing the sorting option + +### CountrySelector + +Allows the user to jump directly to a specific country. + +Props: + +- Filtered and sorted countries +- Currently selected country +- Callback for selecting a country + +### CountryCard + +Displays information about one country at a time. + +Props: + +- Selected country +- Whether the country is a favorite +- Callback for toggling favorite status + +### FavoriteButton + +Allows the user to add or remove the displayed country from favorites. + +Props: + +- Favorite status +- Callback for toggling favorite status +- Country name for an accessible button label + +### NavigationControls + +Allows the user to move to the previous or next country. + +Props: + +- Current country position +- Number of available countries +- Callback for showing the previous country +- Callback for showing the next country +- Information about whether navigation buttons should be disabled + +### FavoritesList + +Displays the countries saved as favorites. Selecting a favorite displays that +country in the main country card. + +Props: + +- Favorite countries +- Callback for selecting a favorite country + +### Footer + +Displays brief information about the REST API used by the application. + +## State ownership + +The main application state will initially be stored in `App`. + +| State | Purpose | Storage | +|---|---|---| +| Selected country | Determines which single country is displayed | React state | +| Selected region | Determines which countries are included | React state and sessionStorage | +| Sorting option | Determines the order of countries | React state and sessionStorage | +| Favorite countries | Stores the user's favorite selections | React state and localStorage | + +The country data itself will be fetched from the REST API with TanStack Query. +API data will not be stored in localStorage or sessionStorage. + +Child components receive the data they need through props. Callback functions +are also passed through props when a child component needs to update state +owned by `App`. + +## Displaying one country at a time + +Only one country will be displayed in `CountryCard` at any given time. + +The user can change the displayed country by: + +- Selecting the previous country +- Selecting the next country +- Choosing a country from `CountrySelector` +- Selecting a country from `FavoritesList` + +Filtering or sorting may change the available countries and their order. If +the selected country is no longer included after filtering, the first +available country will be selected. \ No newline at end of file diff --git a/docs/wireframes/desktop-wireframe.png b/docs/wireframes/desktop-wireframe.png new file mode 100644 index 0000000..4355ba0 Binary files /dev/null and b/docs/wireframes/desktop-wireframe.png differ diff --git a/docs/wireframes/mobile-wireframe.png b/docs/wireframes/mobile-wireframe.png new file mode 100644 index 0000000..f18e260 Binary files /dev/null and b/docs/wireframes/mobile-wireframe.png differ