World Clock Website

A beautiful, responsive world clock application built with TypeScript and Vite. View and compare times from cities around the world with real-time updates, add custom cities, and adjust time across all clocks.

Features

✨ View Default Clocks - Displays New York, London, and Tokyo time zones on page load 🌍 Add Custom Cities - Search and add clocks for any city from a database of 54+ cities ⏰ Time Adjustment - Scroll to adjust time forward/backward by 15-minute increments 🔄 Real-time Updates - All clocks update every second automatically 💾 Persistent Storage - Your custom cities are saved in localStorage 📱 Responsive Design - Optimized for mobile, tablet, and desktop ♿ Accessible - Full keyboard navigation and screen reader support

Tech Stack

• TypeScript 5.x - Type-safe JavaScript
• Vite - Fast build tool and dev server
• Vitest - Unit and integration testing
• Playwright - End-to-end testing
• Vanilla CSS - No CSS frameworks, just modern CSS features
• No UI Framework - Pure TypeScript with component-based architecture

Getting Started

Prerequisites

• Node.js 18+ and npm

Installation

1. Clone the repository:

git clone <repository-url>
cd ClockProject

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

The application will open at http://localhost:5173

Development

Available Commands

# Development server with hot reload
npm run dev

# Run unit and integration tests
npm test

# Run E2E tests (requires dev server running)
npm run test:e2e

# Type check
npm run typecheck

# Build for production
npm run build

# Preview production build
npm run preview

Running Tests

The project follows Test-First Development (TDD):

1. Unit & Integration Tests:

npm test

2. E2E Tests (requires dev server):

# Terminal 1: Start dev server
npm run dev

# Terminal 2: Run E2E tests
npm run test:e2e

All tests should pass:

• 45 unit/integration tests
• 33 E2E acceptance tests (across 3 browsers)

Project Structure

ClockProject/
├── src/
│   ├── components/       # UI components (Clock, ClockGrid, CitySelector)
│   ├── services/         # Business logic (timeService, cityService)
│   ├── types/            # TypeScript interfaces
│   ├── utils/            # Utility functions (localStorage)
│   ├── data/             # Static data (cities.json)
│   ├── styles/           # CSS files
│   └── main.ts           # Application entry point
├── tests/
│   ├── unit/             # Unit tests
│   ├── integration/      # Integration tests
│   └── acceptance/       # E2E tests (Playwright)
├── specs/                # Design documents and task lists
└── public/               # Static assets

## Architecture

### Component-Based Design

The application uses a component-based architecture without a UI framework:

- **Clock**: Renders individual analog clock faces
- **ClockGrid**: Manages the layout and updates of multiple clocks
- **CitySelector**: Modal for searching and selecting cities

### Service Layer

Business logic is separated into services:

- **timeService**: Handles timezone calculations, time formatting, and time state management
- **cityService**: Manages city data and search functionality

### State Management

- **Local State**: Each component manages its own state
- **Global State**: Time state and city list managed in main.ts
- **Persistence**: localStorage for user's selected cities

## User Stories

### 1. View Default Clocks (P1)
As a user, I want to see clocks for New York, London, and Tokyo when I open the page, so I can quickly check times in major cities.

### 2. Add Custom Cities (P2)
As a user, I want to add clocks for other cities I care about and have them persist across sessions, so I can track times in locations relevant to me.

### 3. Adjust Time (P3)
As a user, I want to adjust time forward/backward across all clocks to plan future meetings or check past times.

## Browser Support

- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest)
- Mobile browsers (iOS Safari, Chrome Mobile)

## Accessibility

The application is fully accessible with:

- Semantic HTML and ARIA labels
- Keyboard navigation (Tab, Arrow keys, Enter, Escape)
- Screen reader support
- Reduced motion support
- High contrast mode support

## Testing Philosophy

This project follows **Test-First Development**:

1. Write tests first (RED)
2. Implement features (GREEN)
3. Refactor code (REFACTOR)

Every feature has comprehensive test coverage:
- Unit tests for individual functions
- Integration tests for component interactions
- E2E tests for user workflows

## License

MIT

## Contributing

Contributions are welcome! Please ensure all tests pass before submitting a PR.

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Implement your changes
5. Ensure all tests pass
6. Submit a pull request