A React-based country explorer built around the REST Countries API.
The application allows users to explore countries, search by name, filter by region, inspect detailed country information, navigate between neighboring countries, and switch between light and dark themes.
The project has been rebuilt around a feature-oriented architecture with reusable hooks, explicit UI behavior, accessibility-focused interactions, and automated tests.
- Browse countries in a responsive grid
- Search countries by name
- Filter countries by region
- Combine search and region filters
- Open a dedicated country details view
- Navigate between border countries
- Restore focus to the previously selected country
- Keyboard-friendly country selection
- Keyboard navigation for the custom region selector
- Accessible names and state attributes for interactive controls
- Light and dark theme switching
- Responsive layout
- Empty-state handling when no countries match the current filters
The project uses a feature-oriented structure rather than organizing the application as a collection of unrelated UI files.
src/
├── app/
│ ├── App.jsx
│ ├── App.test.jsx
│ └── styles/
│
├── data/
│ └── data.json
│
├── features/
│ └── countries/
│ ├── api/
│ │ └── CountriesApi.js
│ │
│ ├── hooks/
│ │ ├── useCountryFocusRestore.js
│ │ ├── useCountryFocusRestore.test.jsx
│ │ └── useFocusOnMount.js
│ │
│ ├── model/
│ │ ├── useCountries.js
│ │ └── useCountries.test.js
│ │
│ └── ui/
│ ├── Controls.jsx
│ ├── Controls.test.jsx
│ ├── CountryDetail.jsx
│ ├── CountryDetail.test.jsx
│ ├── CountryGrid.jsx
│ └── CountryGrid.test.jsx
│
├── hooks/
│ ├── useClickOutside.js
│ ├── useClickOutside.test.jsx
│ ├── useFocusOnKey.js
│ ├── useFocusOnKey.test.jsx
│ ├── useFocusOutside.js
│ └── useFocusOutside.test.jsx
│
└── shared/
└── lib/
├── format.js
├── format.test.js
└── strings.jsx
The current structure separates the main responsibilities of the application:
- App — application composition and high-level state flow
- API — country data access
- Model — country filtering and selection logic
- UI — user-facing country controls, grid, and detail views
- Hooks — reusable interaction and focus behavior
- Shared — small reusable formatting and string utilities
- Tests — colocated with the behavior they protect
The architecture was intentionally rebuilt to make responsibilities easier to understand, test, and evolve.
Accessibility is treated as part of the application's behavior rather than as a collection of ARIA attributes.
The application includes:
- Semantic buttons and lists
- Accessible names for country selection controls
- Keyboard activation using native button behavior
- Keyboard navigation for the custom region selector
aria-expandedstate for the region selectoraria-selectedstate for region options- Focus management when entering country details
- Focus restoration when returning to the country grid
- A heading-based focus target that communicates the newly displayed page context
The country grid intentionally keeps native browser navigation rather than implementing a custom roving grid-navigation model. Users can scan the visual collection naturally and move between country buttons with standard keyboard navigation.
The project uses:
The test suite contains 65 automated tests across 10 test files.
The tests focus on observable application behavior rather than implementation details.
- Country filtering
- Region filtering
- Combined filters
- Country selection
- Country detail rendering
- Border-country navigation
- Empty states
- Search interaction
- Custom region-selector keyboard behavior
- Focus management
- Focus restoration
- Outside-click behavior
- Outside-focus behavior
- Keyboard shortcuts
- Formatting utilities
- Theme switching
- Application-level navigation
The testing process was based on identifying public behavior first, then protecting the behaviors that matter to users.
- React
- JavaScript (ES6+)
- CSS
- Vitest
- React Testing Library
- JSDOM
- Vite/Vitest configuration
- Create React App toolchain
Make sure you have:
- Node.js
- npm
- Git
Clone the repository:
git clone https://github.com/a-sayed123/Rest_Countries_API.gitMove into the project directory:
cd Rest_Countries_APIInstall dependencies:
npm installnpm startThe application will be available through the local development server.
Run the test suite:
npm testFor a single non-watch run:
npm test -- --runCreate an optimized production build:
npm run buildThe generated production files are placed in the build/ directory.
| Command | Description |
|---|---|
npm start |
Starts the development server |
npm test |
Runs Vitest in watch mode |
npm test -- --run |
Runs the complete test suite once |
npm run build |
Creates an optimized production build |
npm run eject |
Ejects the Create React App configuration |
The project has completed a major architecture refactor and currently has a stable tested baseline.
The current baseline includes:
- Feature-oriented project structure
- Extracted reusable hooks
- Component and hook tests
- Application-level tests
- Keyboard and focus behavior
- Accessibility-focused interaction testing
- Production build verification
- Clean Git history for the architecture release
Further development can build on this baseline without treating the current architecture as the final form of the application.
This project was originally built around the Frontend Mentor REST Countries challenge and was subsequently developed into a more structured React application with an emphasis on architecture, testing, accessibility, and maintainability.
No license has been declared for this repository yet.