From 004f2e9964c36e62b4da8d272cfd76c56dc81f1d Mon Sep 17 00:00:00 2001 From: Ahmed Date: Sun, 14 Jun 2026 16:24:32 +0300 Subject: init: coffee cups contributions tracker --- README.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..5ade843 --- /dev/null +++ b/README.md @@ -0,0 +1,119 @@ +# ccc + +Coffee Cups Contributions. A single-file, dependency-free coffee intake tracker with a GitHub-style heatmap. No build step, no framework, plain HTML, CSS, and JavaScript. + +Live at [coffee.gumx.cc](https://coffee.gumx.cc). Source at [git.gumx.cc/ccc](https://git.gumx.cc/ccc). + +--- + +## Features + +- **Contributions heatmap** — 53 × 7 grid (Sunday-aligned) covering the past 52 weeks, rendered in SVG. Month labels along the top, Mon/Wed/Fri labels on the left. Today's cell has a visible outline. +- **5-level greyscale scale** — cup counts are bucketed proportionally to `MAX_CUPS` using `Math.round`. A legend is shown below the heatmap. +- **Hover tooltips** — hovering any cell shows the date and cup count in a fixed-position tooltip. +- **Two modes** — local mode (full editing, localStorage) or static site mode (read-only, fetches from a remote URL). +- **Stats** — today's cups, current streak, total cups, and daily average. +- **Light and dark mode** — full `prefers-color-scheme` support via CSS custom properties. The heatmap re-renders if the OS theme changes mid-session. + +--- + +## Files + +| File | Description | +|---|---| +| `ccc.html` | The entire application — one self-contained HTML file | +| `data.json` | Example data file for static site mode | +| `README.md` | This document | +| `LICENSE` | MIT licence | + +--- + +## Local Mode + +Local mode is active when `DATA_URL` is set to `""` (the default). All data is persisted to `localStorage` under the key `ccc_v1`. + +### Logging Coffee + +A **− / count / +** adjuster lets you set how many cups to log (1–10). The **+** button disables when `logCount` would exceed the remaining cups for today. The **log coffee** button disables when today has already reached `MAX_CUPS`. Both controls re-evaluate after every action. + +Clicking **log coffee** adds the selected count to today's total, hard-capped at `MAX_CUPS`. + +### Editing Past Days + +Click any heatmap cell to open an inline popover for that day. The popover shows: + +- The date +- **− / number input / +** to adjust the count (0–`MAX_CUPS`) +- **set** and **cancel** buttons + +Keyboard shortcuts work inside the popover: **Enter** confirms, **Escape** cancels. Clicking anywhere outside the popover also cancels. Setting a day's count to 0 removes the entry entirely. + +A hint below the log controls reads: *"click any cell to edit that day's count"*. + +### Import and Export + +- **Export JSON** — downloads your current data as `ccc-data.json`. +- **Import JSON** — opens a file picker; selecting a valid JSON file replaces the current data. Invalid files show an alert. + +The data format is described below. + +--- + +## Static Site Mode + +Static site mode is active when `DATA_URL` is set to a non-empty URL string. On load, the app fetches `data.json` (or whatever file is at that URL) and renders the heatmap from it. + +In static site mode: + +- All editing controls are hidden. +- Import and export are unavailable. +- A **"static site mode — read-only"** notice appears below the title. +- Data is never written to `localStorage`. + +To use static site mode, host `ccc.html` and `data.json` on any static hosting service (GitHub Pages, Netlify, etc.), then set `DATA_URL` to the full URL of `data.json`. + +--- + +## Configuration + +The `CONFIG` block is at the top of the `