🕚 TimeSpot - World Clock Application

A modern, responsive world clock application built with React, TypeScript, and Vite. Features real-time updates, day/night indicators, and an intuitive interface for tracking time across multiple cities and time zones.

📸 Screenshots

✨ Features

• 🕐 Real-time Clock Display - Live updates for multiple time zones
• 🌅 Day/Night Indicators - Visual cues based on local sunrise/sunset times
• 🔍 City Search & Selection - Easy-to-use search functionality
• 📱 Responsive Design - Optimized for mobile, tablet, and desktop
• 🎨 Adaptive Typography - Dynamic text sizing based on available space
• ⚡ Fast Performance - Built with Vite for lightning-fast development and builds
• 🧪 TypeScript Support - Full type safety throughout the application
• 🎯 Accessible UI - WCAG compliant interface

🚀 Quick Start

Prerequisites

• Node.js 18.0 or higher
• npm 9.0 or higher (or yarn/pnpm)

Installation

1. Clone the repository

   git clone https://github.com/hugomrvt/mrvt-timespot.git
   cd mrvt-timespot

2. Install dependencies

   npm install

3. Start the development server

   npm run dev

4. Open your browser

   Navigate to http://localhost:3000 (or the port shown in your terminal)

📋 Table of Contents

• Features
• Quick Start
• Scripts
• Project Structure
• Architecture
• Environment Variables
• Deployment
• Contributing
• Tech Stack
• Credits
• License

📜 Scripts

Command	Description
npm run dev	Start development server with hot reload
npm run build	Create production build
npm run preview	Preview production build locally
npm run typecheck	Run TypeScript type checking
npm run lint	Run ESLint with error reporting
npm run format	Format code with Prettier

📁 Project Structure

src/
├── components/          # React components organized by feature
│   ├── layout/         # Layout components
│   │   ├── Header.tsx
│   │   ├── AppHeader.tsx
│   │   ├── ResponsiveAppHeader.tsx
│   │   └── MobileNavigation.tsx
│   ├── time/           # Time-related components
│   │   ├── PrimaryTimeDisplay.tsx
│   │   ├── ResponsivePrimaryTimeDisplay.tsx
│   │   ├── TimeZoneCard.tsx
│   │   ├── ResponsiveTimeZoneGrid.tsx
│   │   └── TimeFormatToggle.tsx
│   ├── city/           # City information components
│   │   ├── CityInfoSection.tsx
│   │   └── ResponsiveCityInfoSection.tsx
│   ├── common/         # Shared/common components
│   │   ├── AdaptiveText.tsx
│   │   ├── ApiDataMonitor.tsx
│   │   ├── Credits.tsx
│   │   ├── StatusNotification.tsx
│   │   └── TimeSpotIcon.tsx
│   └── ui/             # UI library components (shadcn/ui)
├── hooks/              # Custom React hooks
│   ├── useTimeZoneData.ts
│   ├── useSunData.ts
│   ├── useAdaptiveTextSize.ts
│   ├── useBreakpoint.ts
│   ├── useRealTimeUpdates.ts
│   ├── useServerConnection.ts
│   ├── useTouchDevice.ts
│   └── useUserPreferences.ts
├── lib/                # Library code
│   ├── api/            # API services
│   │   ├── localTimeApi.ts
│   │   └── supabaseTimeApi.ts
│   └── utils/          # Utility functions
│       ├── timezoneUtils.ts
│       ├── secureLogger.ts
│       └── validation.ts
├── pages/              # Page components
│   └── Frame6.tsx
├── types/              # TypeScript type definitions
│   └── index.ts
├── constants/          # Application constants
│   └── timezones.ts
├── styles/             # Global styles
│   └── globals.css
├── App.tsx             # Main application component
└── main.tsx            # Application entry point

🏗️ Architecture

TimeSpot follows a modular, hook-based architecture with a local data service:

Core Components

• ResponsivePrimaryTimeDisplay: Main time display with adaptive sizing
• ResponsiveTimeZoneGrid: Grid layout for multiple time zones
• TimeZoneCard: Individual time zone display cards

Custom Hooks

• useTimeZoneData: Manages time zone information and real-time updates
• useSunData: Provides sunrise/sunset data from local cache
• useAdaptiveTextSize: Dynamic font sizing based on container width
• useBreakpoint: Responsive design breakpoint detection

🌐 Environment Variables

No environment variables are required by default. Everything works locally with the bundled JSON data and localStorage.

🚀 Deployment

Static Hosting

1. Build the application

   npm run build

2. Deploy the dist/ folder to your preferred hosting platform:

   • Vercel
   • Netlify
   • GitHub Pages
   • Firebase Hosting

Server Functions

None required.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes
4. Run quality checks

   npm run typecheck && npm run lint && npm run format

5. Commit your changes

   git commit -m 'feat: add amazing feature'

6. Push to your branch

   git push origin feature/amazing-feature

7. Open a Pull Request

Commit Convention

We follow Conventional Commits:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• style: - Code style changes
• refactor: - Code refactoring
• test: - Adding tests
• chore: - Maintenance tasks

🛠️ Tech Stack

Frontend

• React 18 - Modern React with concurrent features
• TypeScript - Type-safe JavaScript
• Vite - Next-generation frontend tooling

Development Tools

• ESLint - Code linting
• Prettier - Code formatting
• Husky - Git hooks (optional)

🎨 Design Credits

• Original Design Inspiration: Nixtio on Dribbble
• Implementation: Hugo Mourlevat

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

⭐ Star this repository if you find it helpful!

Made with Figma Make & Trae by Hugo Mourlevat