You are an expert AI assistant specialized in full-stack development and UI/UX design, tasked with generating a Single Page Application (SPA) for a developer tool. This application aims to simplify and enhance date and time manipulation in JavaScript, addressing the complexities and inconsistencies often encountered with native JavaScript Date objects and even the Temporal API's current limitations. The target user is a professional JavaScript developer. The entire application should be built as a functional SPA using React, Tailwind CSS, and appropriate state management.
## PROJECT OVERVIEW
**Application Name:** Zaman Ustası (Time Master)
**Concept:** A SaaS tool for JavaScript developers to overcome the inherent complexities and inconsistencies of date and time handling. It provides an intuitive, reliable, and efficient API and UI for creating, manipulating, formatting, and parsing date and time values across different time zones and calendar systems. It acts as a superior alternative or complement to native JS Date and the Temporal API, offering a more streamlined developer experience.
**Problem Solved:** Native JavaScript `Date` objects are notoriously difficult to work with due to their quirks, mutability, and inconsistent behavior across environments. While the Temporal API is a significant improvement, it's still evolving and might not cover all edge cases or provide the most user-friendly experience for certain complex scenarios (e.g., intricate calendar systems, advanced time zone calculations). This tool aims to bridge that gap.
**Value Proposition:** Empower JavaScript developers with a robust, easy-to-use, and highly reliable solution for all date and time operations, reducing bugs, saving development time, and improving application accuracy, especially in global contexts.
## TECH STACK
* **Frontend Framework:** React (using functional components and Hooks)
* **Styling:** Tailwind CSS (for rapid, utility-first styling)
* **State Management:** Zustand (lightweight, simple, and performant for this scale)
* **Routing:** React Router DOM (for potential future expansion to multiple pages, though MVP is single-page focused)
* **Utility Libraries:** None initially, rely on custom logic and standard JS/Temporal API if available, or build abstractions.
* **Build Tool:** Vite (for fast development server and optimized builds)
## CORE FEATURES (MVP)
1. **Intuitive Date/Time Creation:**
* **User Flow:** The user selects options from dropdowns or inputs fields to define year, month, day, hour, minute, second, millisecond. They can also choose a calendar system (default Gregorian) and a time zone (e.g., 'UTC', 'America/New_York', 'Asia/Tokyo'). A "Create" button generates the date object, displayed clearly below.
* **Functionality:** Handles input validation (e.g., valid month ranges, day ranges based on month/leap year). Abstracts away the complexity of `new Date()` or Temporal `ZonedDateTime.from()` calls.
2. **Seamless Manipulation:**
* **User Flow:** An existing date/time object is displayed. User selects an operation (e.g., 'Add', 'Subtract'). They then choose the unit (e.g., 'Days', 'Months', 'Hours', 'Minutes') and the quantity. An "Apply" button executes the operation, updating the displayed date/time.
* **Functionality:** Implements safe addition/subtraction logic that correctly handles month/year rollovers, leap years, and time zone transitions. For example, adding 30 days to March 1st should correctly land in April.
3. **Flexible Formatting & Parsing:**
* **User Flow:** A date/time value is displayed. The user enters a desired output format string (e.g., 'YYYY-MM-DD HH:mm:ss', 'ddd, MMM D, YYYY', 'ISO'). A "Format" button generates the formatted string. Conversely, a user can paste or type a date string in a specific format into an input field and select the corresponding format from a dropdown, then click "Parse" to see the resulting structured date/time object.
* **Functionality:** Supports common format tokens (YYYY, MM, DD, HH, mm, ss, etc.) and robust parsing that can handle various input string structures with defined formats.
4. **Time Zone & Calendar Awareness:**
* **User Flow:** When creating or displaying a date, the current time zone and calendar system are clearly indicated. Users can change the displayed time zone or calendar system, and the application should intelligently convert the displayed value while preserving the underlying absolute point in time (where applicable).
* **Functionality:** Leverages established time zone databases (like IANA) and handles conversions accurately, including daylight saving time (DST) considerations. Offers a selection of common calendar systems.
## UI/UX DESIGN
* **Layout:** Single-page application. A main content area displays the primary tool (Creation, Manipulation, Formatting sections). A sidebar or top navigation could potentially switch between these modes, but for MVP, tabs or distinct sections within the main area are preferred. Clean, minimalist design.
* **Color Palette:** Primary: Dark Blue (`#1E3A8A`), Secondary: Light Gray (`#F3F4F6`), Accent: Teal (`#14B8A6`), Text: White (`#FFFFFF`) / Dark Gray (`#1F2937`). Focus on high contrast for readability.
* **Typography:** Sans-serif font (e.g., Inter, Roboto). Clear hierarchy using font weights and sizes. Headings (`h1`, `h2`, `h3`), body text, labels, input text.
* **Component Hierarchy:** `App` -> `MainLayout` -> `FeatureTabs` (or `SectionSwitcher`) -> `CreationForm`, `ManipulationTool`, `FormattingParser`. Each tool section contains relevant inputs, buttons, and display areas.
* **Responsive Design:** Mobile-first approach. Use Tailwind's responsive prefixes (`sm:`, `md:`, `lg:`) to ensure usability across devices. On small screens, elements stack vertically. On larger screens, they might arrange in columns or side-by-side.
* **Interactivity:** Clear visual feedback on input changes, button clicks. Loading indicators for potentially slow operations (though ideally fast).
## COMPONENT BREAKDOWN
* **`App.jsx`:** Root component. Initializes Zustand store, sets up routing (if any), renders `MainLayout`.
* **`MainLayout.jsx`:** Contains the overall page structure, header/footer (if any), and the main content area. Manages the active feature tab/section.
* **`FeatureTabs.jsx` / `SectionSwitcher.jsx`:** Manages the UI for switching between Create, Manipulate, Format/Parse features.
* **`CreationForm.jsx`:**
* **Props:** `onCreate` (callback function).
* **State:** `year`, `month`, `day`, `hour`, `minute`, `second`, `timeZone`, `calendarSystem` (controlled inputs).
* **Responsibility:** Renders input fields for date/time components, time zone selector, calendar selector. Handles input changes and triggers `onCreate` on submission.
* **`ManipulationTool.jsx`:**
* **Props:** `initialDateTime` (object), `onManipulate` (callback function).
* **State:** `currentDateTime` (object, managed potentially by Zustand), `operationType` ('add'/'subtract'), `unit` ('days', 'months', etc.), `quantity`.
* **Responsibility:** Displays the current date/time. Provides inputs for selecting manipulation parameters. Triggers `onManipulate`.
* **`FormattingParser.jsx`:**
* **Props:** `initialDateTime` (object), `onFormat` (callback), `onParse` (callback).
* **State:** `currentDateTime` (object), `outputFormatString`, `inputString`, `inputFormatString`.
* **Responsibility:** Displays date/time. Input for format string and parsing. Buttons for 'Format' and 'Parse'. Triggers callbacks.
* **`DateTimePickerInput.jsx`:** Reusable component for individual date/time input fields (year, month, etc.).
* **Props:** `label`, `value`, `onChange`, `min`, `max`.
* **`TimeZoneSelector.jsx`:** Dropdown/select for choosing time zones.
* **Props:** `value`, `onChange`.
* **`CalendarSelector.jsx`:** Dropdown/select for choosing calendar systems.
* **Props:** `value`, `onChange`.
* **`DisplayDateTime.jsx`:** Component to render the formatted date/time value.
* **Props:** `dateTimeObject`.
* **`Button.jsx`:** Reusable button component with styling.
* **`Input.jsx`:** Reusable text input component.
* **`Select.jsx`:** Reusable select/dropdown component.
## DATA MODEL
* **State Structure (Zustand Store):**
```javascript
{
currentDateTime: { // Represents the primary date/time object being worked on
year: number,
month: number, // 1-12
day: number,
hour: number,
minute: number,
second: number,
millisecond: number,
timeZone: string, // e.g., 'UTC', 'America/New_York'
calendar: string // e.g., 'Gregorian', 'Julian'
} | null,
creationForm: { // State for the creation form inputs
year: string,
month: string,
day: string,
hour: string,
minute: string,
second: string,
timeZone: string,
calendar: string
},
manipulationForm: {
operationType: 'add' | 'subtract',
unit: 'years' | 'months' | 'weeks' | 'days' | 'hours' | 'minutes' | 'seconds' | 'milliseconds',
quantity: string
},
formattingParserForm: {
outputFormat: string,
inputString: string,
inputFormat: string
},
errors: Record<string, string> // For validation and operation errors
}
```
* **Mock Data Format:** Dates should be represented as objects following the `currentDateTime` structure above. For example:
```json
{
"year": 2023,
"month": 10, // November
"day": 26,
"hour": 14,
"minute": 30,
"second": 0,
"millisecond": 0,
"timeZone": "America/New_York",
"calendar": "Gregorian"
}
```
```json
{
"year": 2024,
"month": 1,
"day": 1,
"hour": 0,
"minute": 0,
"second": 0,
"millisecond": 0,
"timeZone": "UTC",
"calendar": "Gregorian"
}
```
## ANIMATIONS & INTERACTIONS
* **Hover Effects:** Subtle background color changes or slight scaling on buttons and interactive elements.
* **Transitions:** Smooth transitions for showing/hiding elements (e.g., error messages), tab switching, and potentially for updating the displayed date/time value (e.g., a slight fade). Use Tailwind's transition utilities.
* **Loading States:** If any operation were to take noticeable time (unlikely for most client-side logic, but possible for complex time zone lookups), display a subtle spinner or progress indicator.
* **Micro-interactions:** Visual confirmation (e.g., a checkmark briefly appearing) upon successful formatting or parsing. Input field focus states.
## EDGE CASES
* **Empty State:** When no date is created yet, display clear instructions or placeholder text prompting the user to create a date.
* **Error Handling:**
* **Validation:** Display clear error messages next to invalid input fields (e.g., "Invalid day for this month", "Quantity must be a number").
* **Operation Errors:** If a manipulation or parsing fails due to invalid input or logical impossibility, display a user-friendly error message in a designated error area.
* **Time Zone Data:** Gracefully handle cases where time zone data might be missing or outdated (though this is rare with robust libraries).
* **Input Validation:** Ensure all numerical inputs are within reasonable ranges (e.g., month 1-12, day 1-31, hour 0-23). Use `parseInt` carefully and check for `NaN`.
* **Accessibility (a11y):** Use semantic HTML elements. Ensure proper ARIA attributes where necessary (e.g., for dynamically updated content). All interactive elements should be focusable and operable via keyboard. Sufficient color contrast.
* **Leap Years:** Ensure all calculations correctly account for leap years (e.g., February 29th).
* **DST Transitions:** Handle the complexities of Daylight Saving Time shifts, where clocks may jump forward or backward, or a specific time might not exist on a given day.
## SAMPLE DATA
1. **Initial Creation State:**
```json
{
"year": "2023", "month": "10", "day": "26", "hour": "10", "minute": "00", "second": "00",
"timeZone": "UTC", "calendar": "Gregorian"
}
```
2. **Created DateTime Object:**
```json
{
"year": 2023, "month": 10, "day": 26, "hour": 10, "minute": 0, "second": 0,
"millisecond": 0, "timeZone": "UTC", "calendar": "Gregorian"
}
```
3. **After Adding 3 Days:**
```json
{
"year": 2023, "month": 10, "day": 29, "hour": 10, "minute": 0, "second": 0,
"millisecond": 0, "timeZone": "UTC", "calendar": "Gregorian"
}
```
4. **After Adding 1 Month (from Oct 26 to Nov 26):**
```json
{
"year": 2023, "month": 11, "day": 26, "hour": 10, "minute": 0, "second": 0,
"millisecond": 0, "timeZone": "UTC", "calendar": "Gregorian"
}
```
5. **After Subtracting 1 Year (from 2024-02-29):**
```json
{
"year": 2023, "month": 2, "day": 28, "hour": 10, "minute": 0, "second": 0,
"millisecond": 0, "timeZone": "UTC", "calendar": "Gregorian"
}
```
6. **Formatted Output (Input: Oct 26, 2023 10:00 UTC, Format: 'YYYY-MM-DD HH:mm'):**
`"2023-10-26 10:00"`
7. **Formatted Output (Input: Nov 15, 2023 14:30 NY time, Format: 'ddd, MMM D, YYYY'):**
`"Thu, Nov 15, 2023"`
8. **Parsed Input (String: "2023-11-15T14:30:00-05:00", Format: ISO String):**
(Results in a date object representing Nov 15, 2023, 2:30 PM EST)
9. **Parsed Input (String: "15/11/2023", Format: 'DD/MM/YYYY'):**
(Results in a date object representing Nov 15, 2023, 00:00:00)
10. **Time Zone Conversion Example (Input: Oct 26, 2023 10:00 UTC, Target TZ: 'Asia/Tokyo'):**
The displayed time should be Oct 26, 2023, 19:00 (UTC+9).
## DEPLOYMENT NOTES
* **Build Command:** `npm run build` or `yarn build`.
* **Environment Variables:** Use `.env` files for configuration. Potentially `NODE_ENV` for production/development builds. If external APIs were used (e.g., for time zone data updates), their keys would go here.
* **Performance Optimizations:** Code splitting (though less critical for MVP SPA). Memoization using `React.memo` or `useMemo`/`useCallback` for expensive computations or frequently re-rendering components. Optimize image assets (if any).
* **Static Assets:** Configure Vite to handle static assets correctly.
* **Hosting:** Deployable to static hosting platforms like Vercel, Netlify, GitHub Pages.