From cf60ae0ab7cbbad5e986e3f03ae53ccf9af9905a Mon Sep 17 00:00:00 2001 From: Loic Coenen Date: Thu, 25 Jun 2026 11:33:48 +0200 Subject: [PATCH] docs: update README with Berlin Clock project documentation --- README.md | 145 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 86 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index db579d2..e86060b 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,100 @@ -# React + TypeScript + Vite +# Berlin Clock (Mengenlehreuhr) -This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. +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. -Currently, two official plugins are available: +## Features -- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs) -- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) +- 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. -## React Compiler +## Technologies -The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation). +- [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) -## Expanding the ESLint configuration +## Getting Started -If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules: +### Prerequisites -```js -export default defineConfig([ - globalIgnores(["dist"]), - { - files: ["**/*.{ts,tsx}"], - extends: [ - // Other configs... +- [Node.js](https://nodejs.org) (version 18 or later recommended) +- npm, yarn, or pnpm - // Remove tseslint.configs.recommended and replace with this - tseslint.configs.recommendedTypeChecked, - // Alternatively, use this for stricter rules - tseslint.configs.strictTypeChecked, - // Optionally, add this for stylistic rules - tseslint.configs.stylisticTypeChecked, +### Installation - // Other configs... - ], - languageOptions: { - parserOptions: { - project: ["./tsconfig.node.json", "./tsconfig.app.json"], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]); +```bash +# Clone the repository +git clone +cd + +# Install dependencies +npm install ``` -You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules: +### Running the Development Server -```js -// eslint.config.js -import reactX from "eslint-plugin-react-x"; -import reactDom from "eslint-plugin-react-dom"; - -export default defineConfig([ - globalIgnores(["dist"]), - { - files: ["**/*.{ts,tsx}"], - extends: [ - // Other configs... - // Enable lint rules for React - reactX.configs["recommended-typescript"], - // Enable lint rules for React DOM - reactDom.configs.recommended, - ], - languageOptions: { - parserOptions: { - project: ["./tsconfig.node.json", "./tsconfig.app.json"], - tsconfigRootDir: import.meta.dirname, - }, - // other options... - }, - }, -]); +```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 +``` +