51 write a complete readme

README.md

@@ -1,10 +1,71 @@
-# T23-Project-1
+# T23-Project-1 — Country Explorer
 
-Repository for team IT2810-H26-T23 in IT2810-H26.
+**[Open the web app on the group VM](http://it2810-23.idi.ntnu.no/project1/)**
 
-## Use of AI tools
+Country Explorer lets you browse European countries, filter by subregion, sort by
+name or population, and save favorites. Built with React, TypeScript and Vite by
+team IT2810-H26-T23.
 
-See [AI usage documentation](docs/ai-usage.md).
+## Requirements
+
+- Git and access to this repository.
+- Node.js **22.20.0** and npm **10.9.3** (the versions used for local verification).
+- Internet access to install dependencies and load country data and flags.
+
+No API key or environment file is needed. Check your installed versions with
+`node --version` and `npm --version`.
+
+## Run locally
+
+1. Clone the repository and enter the application folder:
+
+   ```bash
+   git clone https://git.ntnu.no/IT2810-H26/T23-Project-1.git
+   cd T23-Project-1/country-explorer
+   ```
+
+2. Install the locked dependencies:
+
+   ```bash
+   npm install
+   npm ci
+   ```
+
+3. Start the development server:
+
+   ```bash
+   npm run dev
+   ```
+
+4. Open [the local app](http://localhost:5173/project1/). If Vite reports a
+   different port, use that port instead. Stop the server with `Ctrl+C`.
+
+## Test and build
+
+Run these commands from `country-explorer/`:
+
+```bash
+npm test              # Run automated tests
+npm run lint          # Check code with ESLint
+npm run format:check  # Check formatting
+npm run build         # Type-check and generate dist/
+npm run preview       # Preview the production build locally
+```
+
+The preview normally runs at `http://localhost:4173/project1/`.
+See the deployment document below for serving the build on the VM.
+
+## Documentation
+
+- [Component structure](docs/component-structure.md): components, props, state ownership and initial wireframes.
+- [API performance](docs/api-performance.md): observed network requests and TanStack Query caching.
+- [Testing](docs/testing.md): automated checks, PC/iPhone testing and coverage limitations.
+- [Deployment](docs/deployment.md): production build, VM setup and deployment verification.
+- [Usability evaluation](docs/usability-evaluation.md): the group's assessment and possible mobile improvements.
+- [AI usage](docs/ai-usage.md): tools used, their role and the group's review of suggestions.
+- [Git workflow](docs/git-workflow.md): branch and commit templates, pull requests and review rules.
+- [Sprint process](docs/sprint-process.md): weekly meetings, issue allocation and progress discussions.
+- [REST API details](country-explorer/src/api/README.md): data source, country fields and error handling.
 
 ## Working in this repository
 

docs/api-performance.md

@@ -20,7 +20,7 @@ We checked requests to the REST API (`countries.dev`) at each stage:
 
 ## Findings
 
-The application makes exactly **one** request to the REST API per session:
+During the recorded test sequence, we observed **one** request to the REST API:
 
 ```
 GET https://countries.dev/region/europe
@@ -47,3 +47,6 @@ already supports this:
 Since there is only one query in the app (`useCountries`, keyed by region) and
 the UI never changes the region it's called with, there is only ever one
 active query, and it is never invalidated during normal use.
+
+This observation is not a one-request-per-session guarantee. Reloading the page,
+retrying a failure, or remounting/reconnecting with stale data can fetch again.

docs/component-structure.md

@@ -3,6 +3,18 @@
 This document describes the planned user interface, component hierarchy,
 component responsibilities, props, and state for Country Explorer.
 
+## Current implementation
+
+`App` coordinates query results and UI state. `RegionFilter`, `SortSelector`, and
+`CountrySelector` reuse `Dropdown`. `CountryCard` contains `FavoriteButton`;
+`NavigationControls` and `FavoritesList` receive data and callbacks from `App`.
+`Loading` and `ErrorMessage` handle request states. Header, footer, and the controls
+section are markup inside `App`, not separate components. `useFavorites` owns
+favorite state, while `useCountries` wraps TanStack Query.
+
+The wireframes and planned hierarchy below describe the initial design; the
+current implementation above is the reference for actual component boundaries.
+
 ## Wireframes
 
 ### Desktop
@@ -164,12 +176,12 @@ Displays brief information about the REST API used by the application.
 
 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 |
+| 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.
@@ -191,4 +203,4 @@ The user can change the displayed country by:
 
 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.
+available country will be selected.

docs/git-workflow.md

@@ -0,0 +1,32 @@
+# Git workflow
+
+Work on an issue branch and open a pull request into protected `dev`.
+Use the branch template `<issue-number>-<short-description>`. Replace all
+placeholders below before running the commands.
+
+```bash
+git switch dev
+git pull --ff-only
+git switch -c "<issue-number>-<short-description>"
+# Make changes, run relevant checks, and stage the intended files.
+git commit -m "<type>: <short description>" -m "<summary of changes>" -m "Closes #<issue-number>"
+git push -u origin "<issue-number>-<short-description>"
+```
+
+Commit template: `<type>: <short description>`. Use `feat`, `fix`, `style`, `test`,
+`docs`, or `refactor` as appropriate. Add `Closes #<issue>` only when the change
+completes that issue.
+
+## Pull requests
+
+Keep the description short:
+
+```text
+Summary: What changed.
+Verification: Commands run, results, and any manual checks or limitations.
+Closes #<issue>
+```
+
+A different member of IT2810-H26-T23 must approve the PR; approvals from staff do
+not count. Resolve every review conversation before merging. New commits dismiss
+previous approval, so request another review after making changes.

docs/sprint-process.md

@@ -0,0 +1,8 @@
+# Weekly meetings and sprint planning
+
+We held one main meeting each week. We split the work into issues, agreed on who
+would take each task, and discussed progress and problems we were struggling with.
+The meetings helped us clarify tasks and decide what to focus on next.
+
+Issues described the work and acceptance criteria. Changes were submitted through
+pull requests so another group member could review them before merging.

docs/testing.md

@@ -0,0 +1,32 @@
+# Testing
+
+From `country-explorer/`, run `npm test`, `npm run lint`, and `npm run build`.
+Use `npm run format:check` to check formatting. Tests use fixed country fixtures
+and mock API calls; storage is cleared between tests.
+
+The tests cover country rendering, loading/error states, filtering, sorting,
+navigation, dropdown selection, and storage/restoration, including invalid data.
+The current checkout has no committed snapshot test or `.snap` file; snapshot
+coverage is therefore not claimed here.
+
+## Browser and device coverage
+
+The group's [usability evaluation](usability-evaluation.md) reports that the app
+worked as expected and identifies scrolling on mobile as an improvement area.
+The [deployment report](deployment.md) also records functional browser checks.
+The group confirms testing on a PC and an iPhone. Browser names/versions, the
+PC operating system, and the iPhone model/iOS version were not recorded.
+Portrait and landscape coverage was not specified. jsdom tests do not establish
+cross-browser coverage.
+
+| Device | Reported result                                            |
+| ------ | ---------------------------------------------------------- |
+| PC     | Functionality worked as expected in the group's evaluation |
+| iPhone | Functionality worked; navigation required some scrolling   |
+
+For future checks, record browser/version, device/OS, orientation, and results.
+
+Check filtering, sorting, favorites after reload, navigation, keyboard focus and
+selection, and layout without horizontal scrolling. Test both portrait and
+landscape on small screens. This is a checklist for future records, not a claim
+that every combination has already been verified.