docs: add wireframes and component structure

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.