init: coffee cups contributions tracker

1 files changed, 119 insertions, 0 deletions

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 `<script>` tag in `ccc.html`:
+
+```js
+const CONFIG = {
+  DATA_URL: "",   // "" = local mode | "<url>" = static site mode
+  MAX_CUPS: 6,    // maximum cups allowed per day
+  WEEK_START: 1,  // first day of the week: 0=Sun, 1=Mon, 2=Tue, 3=Wed, 4=Thu, 5=Fri, 6=Sat
+};
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `DATA_URL` | string | `""` | URL to fetch `data.json` from. Empty string activates local mode. |
+| `MAX_CUPS` | integer | `6` | Maximum cups allowed per day. Controls the colour scale and log/edit caps. |
+| `WEEK_START` | integer | `1` | First day of the week. `0` = Sunday, `1` = Monday (ISO default), through `6` = Saturday. Affects the heatmap column alignment and day labels. |
+
+---
+
+## Data Format
+
+Data is stored as a JSON object with a single `entries` key. Each entry is a date string (`YYYY-MM-DD`) mapped to a cup count (integer, 1–`MAX_CUPS`). Days with zero cups are omitted.
+
+```json
+{
+  "entries": {
+    "2026-04-07": 3,
+    "2026-04-08": 2
+  }
+}
+```
+
+- Dates must match the pattern `YYYY-MM-DD`.
+- Values must be positive integers. Zero or negative values are ignored on import.
+- Values exceeding `MAX_CUPS` are clamped on import.
+- Deleting an entry (setting it to 0 via the cell editor) removes the key entirely.
+
+---
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).