101 lines
3.4 KiB
Markdown
101 lines
3.4 KiB
Markdown
# 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](https://react.dev)
|
||
- [TypeScript](https://www.typescriptlang.org)
|
||
- [Vite](https://vitejs.dev)
|
||
- [Cypress](https://www.cypress.io) (end‑to‑end tests)
|
||
- [Vitest](https://vitest.dev) (unit tests, via the community)
|
||
|
||
## Getting Started
|
||
|
||
### Prerequisites
|
||
|
||
- [Node.js](https://nodejs.org) (version 18 or later recommended)
|
||
- npm, yarn, or pnpm
|
||
|
||
### Installation
|
||
|
||
```bash
|
||
# Clone the repository
|
||
git clone <repository-url>
|
||
cd <repository-folder>
|
||
|
||
# Install dependencies
|
||
npm install
|
||
```
|
||
|
||
### Running the Development Server
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
Open [http://localhost:5173](http://localhost:5173) in your browser to see the application.
|
||
|
||
### Building for Production
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
The output will be placed in the `dist` directory.
|
||
|
||
### Running Tests
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|