berlin/README.md

Berlin Clock (Mengenlehreuhr)

A React + TypeScript application that implements the Berlin Clock (also known as the Mengenlehreuhr), a system invented in Berlin in 1975 to represent the time using coloured lamps.

Features

• Real-time clock that automatically advances every second using the system time.
• Converter mode – uncheck the "Use system time" checkbox to switch to manual time input. The digital time display becomes editable, letting you set any time and immediately see its Berlin‑Clock representation.
• Full Berlin Clock layout:
  • Seconds lamp (top, round) – blinks yellow every second.
  • Five‑hour row – four red lamps, each representing 5 hours.
  • One‑hour row – four red lamps, each representing 1 hour.
  • Five‑minute row – eleven lamps, each representing 5 minutes. Every third lamp is red to mark quarter hours; the remaining lamps are yellow.
  • One‑minute row – four yellow lamps, each representing 1 minute.

Technologies

• React
• TypeScript
• Vite
• Cypress (end‑to‑end tests)
• Vitest (unit tests, via the community)

Getting Started

Prerequisites

• Node.js (version 18 or later recommended)
• npm, yarn, or pnpm

Installation

# Clone the repository
git clone <repository-url>
cd <repository-folder>

# Install dependencies
npm install

Running the Development Server

npm run dev

Open http://localhost:5173 in your browser to see the application.

Building for Production

npm run build

The output will be placed in the dist directory.

Running Tests

# Unit tests (Vitest)
npm test

# End‑to‑end tests (Cypress)
npx cypress run

# Open Cypress test runner
npx cypress open

Usage

When the application starts, the Berlin Clock shows the current system time (the "Use system time" checkbox is checked).

• System clock mode – the digital display shows the current time and is read‑only. The Berlin clock updates every second.
• Manual converter mode – uncheck "Use system time". The digital time input becomes editable. Type a new time (hh:mm:ss) or use the browser’s native date/time picker (if available). As you change the value, the Berlin Clock immediately reflects the entered time.

The Berlin Clock layout is read‑only; it always shows the time represented by the digital input.

Project Structure

src/
├── App.tsx              – Main application component
├── components/
│   ├── Lamp.tsx         – Single lamp with state and border radius logic
│   └── LampLine.tsx     – Row of lamps (used for five‑hour, one‑hour, etc.)
├── containers/
│   ├── BerlinClock.tsx  – Visual representation of the Berlin clock
│   ├── DigitalClock.tsx – Input field for digital time
│   └── TimeConverter.tsx– Orchestrates clock switching and time sync
├── hooks/
│   └── useCurrentTime.ts– Hook to manage current time state
├── types/
│   └── index.ts         – Type definitions (`LampState`, `BerlinClock`)
├── utils/
│   └── index.ts         – Conversion functions between Date and Berlin Clock
└── __tests__/           – Unit tests corresponding to the source files