You are an expert Senior Full-Stack Developer, Startup Consultant, and Application Architect. Your task is to generate a complete, single-page, functional web application based on the provided concept and requirements. The application aims to solve the user pain point of tedious and error-prone address entry by automatically populating city, state, and country based on a US ZIP code. The target audience includes e-commerce platforms, online form providers, logistics companies, and CRMs seeking to improve user experience and data accuracy. The core technology stack will be React for the frontend, Tailwind CSS for styling, and it will leverage an external API like zippopotam.us for address data. The application should be structured as a Single Page Application (SPA) with a clean, modern, and responsive user interface.
PROJECT OVERVIEW:
The application's primary goal is to streamline the address entry process for users on various digital platforms. By inputting a 5-digit US ZIP code, the system will automatically determine and fill in the corresponding City, State, and Country fields. This significantly reduces user effort, minimizes typographical errors, and improves the quality of data collected by businesses. The core value proposition is enhanced user experience, increased form conversion rates, and cleaner, more accurate address data for businesses.
TECH STACK:
- Frontend Framework: React.js (using functional components and Hooks)
- Styling: Tailwind CSS for rapid UI development and a utility-first approach.
- State Management: React's Context API for managing global state (e.g., API key, user settings if applicable) and local component state (useState, useReducer) where appropriate. For this SPA, Context API is sufficient.
- Routing: Not strictly necessary for a single-page application focused on a single core function, but can be included for future scalability. For this MVP, we'll keep it minimal without explicit routing.
- API Interaction: `fetch` API or `axios` for making requests to the address lookup API (e.g., zippopotam.us).
- Build Tool: Vite (for speed and modern features).
- Language: JavaScript (with JSX).
CORE FEATURES:
1. **ZIP Code Input Field**: A single input field where the user types a 5-digit US ZIP code.
* User Flow: The user focuses on the ZIP code input. As they type, real-time validation should check if the input is a valid 5-digit number. Upon losing focus (onBlur) or after typing the 5th digit, an API call is triggered.
2. **Automated Address Fields**: Upon successful ZIP code lookup, the City, State, and Country fields are automatically populated.
* User Flow: After the API call returns data, the application updates the state, and the corresponding `<span>` or `<p>` elements displaying 'City', 'State', and 'Country' are updated with the fetched information. These fields should be read-only or visually distinct to indicate they are auto-filled.
3. **Address Lookup API Integration**: Connects to a service like zippopotam.us to fetch address details based on the ZIP code.
* User Flow: When a valid ZIP code is submitted, the application constructs the API request URL (e.g., `https://api.zippopotam.us/us/${zipCode}`). It sends a GET request and handles the response. Success populates the fields; errors display a user-friendly message.
4. **Error Handling & Feedback**: Provides clear messages for invalid ZIP codes, network errors, or API issues.
* User Flow: If the API returns an error (e.g., 404 for an invalid ZIP, network down), an error message is displayed below the input field. If the ZIP code format is incorrect (e.g., not 5 digits), immediate visual feedback (like a red border) and a helper text can be shown.
5. **Manual Input Fallback (Optional for MVP, but good to consider for robustness)**: If the API fails or the ZIP code is not found, allow the user to manually enter the City, State, and Country.
* User Flow: If an error occurs during lookup, the City, State, and Country fields become editable input fields, and a message prompts the user to fill them manually if desired.
UI/UX DESIGN:
- **Layout**: A clean, centered, single-column layout optimized for focus on the address form. The SPA will occupy the full viewport.
- **Color Palette**: Primary: A calming blue (#4A90E2). Secondary: A neutral gray for text and borders (#6B7280). Accent: A subtle green for success states or highlights (#34D399). Background: White (#FFFFFF) or a very light gray (#F9FAFB).
- **Typography**: Use a clean, readable sans-serif font like Inter or Roboto. Headings: 24px bold. Body text: 16px regular. Input labels: 14px semibold.
- **Components**: Clearly defined input fields, labels, buttons (if any for submission), and feedback/error messages.
- **Responsive Design**: The layout must adapt seamlessly to various screen sizes (mobile, tablet, desktop). Use Tailwind's responsive modifiers (sm:, md:, lg:). For a single-column layout, this primarily means adjusting padding and font sizes.
- **Focus States**: Inputs should have a clear focus indicator (e.g., a blue border using Tailwind's focus ring utilities).
COMPONENT BREAKDOWN:
1. `App.js` (Main Container)
* Responsibilities: Holds the overall structure, Context Provider (if needed), and the main form component. Manages the global theme or layout settings.
* Props: None (or theme-related props if extended).
2. `AddressForm.js`
* Responsibilities: Renders the ZIP code input, the auto-filled address display, and handles the core logic for input changes, API calls, and state updates.
* Props:
* `apiKey` (string, optional): For potential future API key management.
3. `ZipCodeInput.js`
* Responsibilities: Renders the input field for the ZIP code, manages its local state (value), handles input changes, and triggers validation/lookup.
* Props:
* `value` (string): The current value of the input.
* `onChange` (function): Callback function to update the parent state.
* `onBlur` (function): Callback function to trigger the lookup logic.
* `error` (string | null): Error message to display.
* `isValid` (boolean): Flag for valid format.
4. `AddressDisplay.js`
* Responsibilities: Renders the read-only fields for City, State, and Country, displaying fetched data or placeholders.
* Props:
* `city` (string | null): The city name.
* `state` (string | null): The state name.
* `country` (string | null): The country name.
* `isLoading` (boolean): To show loading state.
* `error` (string | null): Error message.
5. `FeedbackMessage.js`
* Responsibilities: Displays success, error, or informational messages to the user.
* Props:
* `message` (string | null): The message content.
* `type` (enum: 'error' | 'success' | 'info'): The type of message, affecting styling.
DATA MODEL:
- State Management:
* `zipCode` (string): Current value in the ZIP code input.
* `city` (string | null): Fetched city name.
* `state` (string | null): Fetched state name.
* `country` (string | null): Fetched country name.
* `isLoading` (boolean): Tracks if an API request is in progress.
* `error` (string | null): Stores any error message.
* `isZipValidFormat` (boolean): Tracks if the entered ZIP code has the correct 5-digit format.
- Mock Data Format (Example for zippopotam.us):
```json
{
"post code": "90210",
"country": "United States",
"places": [
{
"place name": "Beverly Hills",
"state": "California",
"state abbreviation": "CA",
"latitude": "34.0901",
"longitude": "-118.4064"
}
]
}
```
ANIMATIONS & INTERACTIONS:
- **Input Focus**: Subtle border highlight on input focus using Tailwind's `focus-within:` or `focus:` utilities.
- **Loading State**: When fetching data, display a subtle loading indicator (e.g., a spinner icon or a pulsating animation on the display area). Use Tailwind's animation utilities.
- **Transitions**: Smooth transitions for showing/hiding error messages or when fields are populated. Use Tailwind's `transition` and `duration-` classes.
- **Micro-interactions**: Possible subtle animation on successful data population.
EDGE CASES:
- **Empty Input**: When the ZIP code input is empty, clear the address fields and reset error states.
- **Invalid Format**: Input should ideally restrict to numbers and enforce a 5-digit length. Provide immediate feedback if the format is wrong before even triggering the API.
- **API Errors**: Handle 4xx/5xx errors gracefully. Display a user-friendly message (e.g., "Could not retrieve address information. Please check the ZIP code or try again later."). Offer a manual entry fallback.
- **Network Errors**: Use `try...catch` blocks around `fetch` to handle network connectivity issues.
- **No Places Found**: The API might return a valid structure but with an empty `places` array. Handle this case by showing an appropriate message.
- **Accessibility (a11y)**: Ensure proper ARIA attributes for inputs, labels, and error messages. Use semantic HTML elements. Ensure sufficient color contrast.
SAMPLE DATA (for testing and demonstration):
1. Valid ZIP: `90210` -> City: `Beverly Hills`, State: `California`, Country: `United States`
2. Valid ZIP: `10001` -> City: `New York`, State: `New York`, Country: `United States`
3. Valid ZIP: `75001` -> City: `Addison`, State: `Texas`, Country: `United States`
4. Invalid Format: `1234` -> Error: "Invalid ZIP code format. Please enter 5 digits."
5. Invalid Format: `ABCDE` -> Error: "Invalid ZIP code format. Please enter 5 digits."
6. Non-existent ZIP (example): `00000` -> Error: "ZIP code not found. Please verify the code."
7. (Consider edge case of API outage or service error) -> Error: "Service unavailable. Please try again later."
DEPLOYMENT NOTES:
- Use Vite for building the React application (`npm run build`).
- The output will be a set of static files (HTML, CSS, JS) ready for deployment on any static hosting service (Netlify, Vercel, GitHub Pages, etc.).
- Environment Variables: If an API key were required for a different service, it would be managed via `.env` files and accessed in the code using `import.meta.env.VITE_API_KEY` (or similar, depending on the build tool).
- Performance Optimizations: Code splitting (handled by Vite by default), image optimization (if any images were used), efficient state management, and minimizing re-renders. Ensure the API call is debounced or triggered on blur to avoid excessive requests.
- HTTPS: Ensure the application is served over HTTPS, especially if handling any sensitive data (though this MVP does not).
- CORS: Be mindful of Cross-Origin Resource Sharing if the frontend and backend (or API) are on different domains. The zippopotam.us API appears to handle CORS correctly for public access.