neon-activity-graph 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Elliot Négrel-Jerzy
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,139 @@
1
- # Temporary Holding Version
1
+ # Neon-activity-graph
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A 3D activity graph in three.js: one glass block a day, two layers stacked in a column (say GitHub contributions on top of coding time), lit like a neon sign. In the dark theme the blocks' rods flicker on like gas tubes, with a synthesised hum; in the light theme the sun shines through the glass and casts coloured shadows and caustics. The camera never moves, so the picture is rendered progressively (soft shadows and anti-aliasing accumulated over a few dozen frames) and then the GPU goes idle.
4
+
5
+ It draws the graph only: no panel, no figures, no legend. Hover and keyboard events are handed to you as data (`onHover`) so the card is yours.
6
+
7
+ <p>
8
+ <img alt="Dark theme" src="docs/dark.jpg" width="49%" />
9
+ <img alt="Light theme" src="docs/light.jpg" width="49%" />
10
+ </p>
11
+
12
+ - Framework-agnostic core (`createActivityGraph`) and a React wrapper (`neon-activity-graph/react`)
13
+ - Generic data: two layers of `{ date, value }`; adapters for GitHub's contribution calendar and WakaTime's summaries
14
+ - Light and dark themes (following `prefers-color-scheme` by default), phone layout (4 strips), reduced motion, a `lite` mode
15
+ - No assets to bundle: the baked light of the dark theme is embedded (41 KB PNG, loaded only for the dark theme)
16
+ - `three` is a peer dependency, and is loaded on demand (`import("three")`), so the entry is small
17
+
18
+ ## Install
19
+
20
+ ```sh
21
+ npm install neon-activity-graph three
22
+ ```
23
+
24
+ ## Quick start
25
+
26
+ Vanilla:
27
+
28
+ ```ts
29
+ import { createActivityGraph, fromGitHubCalendar } from "neon-activity-graph";
30
+
31
+ const graph = createActivityGraph(document.getElementById("graph")!, {
32
+ data: {
33
+ top: fromGitHubCalendar(calendar), // GitHub's contributionCalendar, or any { date, value }[] layer
34
+ bottom: { label: "Coding", unit: "h", days: [{ date: "2026-11-19", value: 3.5 } /* ... */] },
35
+ },
36
+ onHover: (day) => { /* day: { date, top, bottom, x, y, outline } | null: show your card */ },
37
+ });
38
+
39
+ graph.update(newData); // rebuilds the graph
40
+ graph.setTheme("dark"); // "light" | "dark" | "auto"
41
+ graph.destroy(); // frees the GPU resources and the listeners
42
+ ```
43
+
44
+ Give the container a size: the picture fills it (about 4:1 for one strip; with `strips: 4`, about 4:5). It needs WebGL 2.
45
+
46
+ React:
47
+
48
+ ```tsx
49
+ import { ActivityGraphView } from "neon-activity-graph/react";
50
+
51
+ <ActivityGraphView data={data} theme="auto" className="aspect-[4/1] w-full" onHover={setDay} />
52
+ ```
53
+
54
+ `data` should be memoised (a new object rebuilds the graph); callbacks can be new closures at every render.
55
+
56
+ ## Data
57
+
58
+ ```ts
59
+ interface GraphData { top: GraphLayer; bottom: GraphLayer }
60
+ interface GraphLayer { label?: string; unit?: string; days: { date: string /* "2026-11-19", UTC */; value: number }[] }
61
+ ```
62
+
63
+ The graph shows the last `weeks` weeks (53 by default) ending at the latest day of either layer; missing days are 0 (a flat tile). A block's height and colour follow `sqrt(value / max)` of its layer. Adapters (all pure, no network): `fromGitHubCalendar`, `fromWakaTimeSummaries`, `fromRecords(rows, date, value)`; `fakeLayer({ seed })` makes repeatable fake data for demos and tests.
64
+
65
+ ## Options
66
+
67
+ | Option | Default | |
68
+ | --- | --- | --- |
69
+ | `data` | required | The two layers, or `null` while they are being fetched (only the place-holder shows; `update(data)` builds the graph). |
70
+ | `weeks` | `53` | How many weeks are drawn. |
71
+ | `strips` | `1` | `1` is one long strip; `4` staggers four strips for a narrow, tall box (aspect about 0.8). |
72
+ | `theme` | `"auto"` | `"light"`, `"dark"` or `"auto"` (follows `prefers-color-scheme`). Change it with `setTheme`. |
73
+ | `colors` | green on top, blue below | `{ top?: { light?: [low, high], dark?: [low, high] }, bottom?: ... }`, colours as `#rrggbb` or `0xrrggbb`: the glass of a quiet day and of the busiest one. |
74
+ | `background` | nearest opaque ancestor background | A CSS colour, or `(theme) => css`. The ground takes it, so the picture has no seam with the page. Call `setTheme` again after it changed. |
75
+ | `rodColor` | `undefined` | `({ layer, index, date, t }) => [r, g, b] \| null`: the dark theme's rod colour (linear RGB, around 0..1; `t` is how busy the day was). Giving it turns on the "string of lights" look: clear glass, no grey veil, softer bloom; `null` keeps the default colour for that day. |
76
+ | `sound` | `true` | The synthesised hum and dings of the start-up. They play only once the browser lets the page make sound (after the visitor interacted with it) and only while the graph is on screen. |
77
+ | `reducedMotion` | `"auto"` | `"auto"` follows `prefers-reduced-motion`; when reduced there is no start-up and no flicker. |
78
+ | `lite` | `"auto"` | The light version: a third of the frames, lower resolution, simpler blocks. `"auto"` turns it on for coarse pointers and for machines with 4 cores or fewer or under 4 GB. |
79
+ | `grain` | `0.012` | Camera grain strength; `0` is off. |
80
+ | `templatesUrl` | embedded | URL of `caustic-templates.png` (see below) instead of the embedded data URI. |
81
+ | `label` | "Activity graph, ..." | The accessible name. The arrow keys walk the days (focus the graph by clicking it), Escape lets go. |
82
+ | `placeholder` | `true` | Shows the flat days (the same slab, seen by the same camera, strips on a narrow box) at once, pulsing, and fades it out when the first picture is on screen. The React view renders it itself, so it is in server-rendered pages. |
83
+ | `overlay` | off | `true` or `{ outline?, card?, locale? }`: the day's outline (an SVG path round its blocks) and a day card, drawn over the graph. `card` can be `false` or a function `(info) => string \| Node`. Styled with CSS variables on the container or above: `--nag-outline`, `--nag-outline-fill`, `--nag-card-bg`, `--nag-card-fg`, `--nag-card-muted`, `--nag-top`, `--nag-bottom`, `--nag-card-radius`. |
84
+ | `maxPixelRatio` | `2` | The highest pixel ratio the picture is rendered at (`lite` is always 1). |
85
+ | `maxPixels` | `8_000_000` | The most pixels rendered; a larger container is rendered at a lower ratio (also capped by the card's texture size). |
86
+ | `onLayout` | | `(bounds) => void`: where the blocks are on the screen, `{ left, right, top, bottom }` in CSS pixels of the container (the first layout, and every resize). The same numbers are on the container as the CSS variables `--nag-content-left`, `--nag-content-right`, `--nag-content-top` and `--nag-content-bottom`, and in `graph.bounds`: use them to line a caption up with the picture and not with its box (the demo hangs its title in the empty ground at the bottom left, `left: var(--nag-content-left)`). |
87
+ | `onHover` | | `(info \| null) => void`: `{ index, date, top, bottom, outline, x, y, behind }`. `outline` is the SVG `points` of the day's silhouette, `x, y` a point on its top in CSS pixels of the container. Clicking days that are behind one another cycles through them (`behind`). |
88
+ | `onReady` / `onLit` | | The first picture is on screen (fade your place-holder); the picture is lit (`false` while the start-up runs). |
89
+ | `startup` | | `({ inView }) => { start?, stop? } \| void`: called each time a start-up is prepared, to hook your own sound or greeting to it. |
90
+ | `debug` | | `{ metrics?, wireframe?, neonHold? }`: development helpers (`data-*` timings on the container, the glass as a cage, the picture held half on). |
91
+
92
+ `createHoverOverlay(container, options, labels)` is the overlay on its own, for a graph you drive yourself. In React, `<ActivityGraphView aspect={4} overlay />` takes the same options (`aspect` is the box's, so the server-rendered place-holder has the right shape).
93
+
94
+ A flat place-holder that shares the scene's camera (so the scene replaces it in place) can be drawn without loading three.js: `import { placeholderTiles } from "neon-activity-graph/layout"` gives an SVG `viewBox` and one path of all the squares.
95
+
96
+ ## Performance
97
+
98
+ - Nothing moves, so the picture is drawn once, a frame at a time (96 jittered samples; 32 in `lite`), then the render loop stops. Hover only re-lights the blocks (a few frames, then stops again).
99
+ - The start-up and the idle flickers update the light of the blocks, not their geometry: a light update costs about 0.05 ms of CPU and a frame about 0.5 ms on an Apple M4; on an emulated Pixel 7 (CPU slowed 6x) 0.7-0.8 ms and 4-5 ms.
100
+ - The one-time build (geometry, ground light) stalls the main thread for a few hundred ms, up to 1.3 s on a slowed phone. Dark theme: the baked light is decoded once.
101
+ - The idle flickers run only while the graph is in view and the tab visible; `prefers-reduced-motion` skips the start-up altogether.
102
+ - The picture is rendered at the container's size times the pixel ratio (up to 2), so it grows with the screen; above 8 million pixels the ratio drops. Measured (Chrome on an Apple M4, dark and light): a 2352 px wide graph on a 2560 px screen at ratio 2 renders 4704 x 1184 px (5.6 MP), the first picture is on screen after about 1 s, rAF stays at 16.7 ms (p95 16.8 ms) with a one-time build hitch of 250-330 ms, JS heap about 100 MB. GPU memory is not measured: expect a few hundred MB of half-float targets at that size, which `maxPixels` bounds.
103
+ - three.js is imported on demand: until the graph is created nothing of it is loaded.
104
+
105
+ ## Browser support
106
+
107
+ Anything with WebGL 2 and half-float render targets (current Chrome, Edge, Firefox, Safari 15+, iOS Safari). Without WebGL 2 the call fails (logged); check first and draw a fallback if you care (`document.createElement("canvas").getContext("webgl2")`).
108
+
109
+ ## How the optics work
110
+
111
+ - **Light theme.** The sun's light through the glass is traced on the GPU (`ground-light.ts`, a vertex shader that splats rays onto the ground): refraction, Fresnel, total internal reflection, the glass's colour absorption, rounded edges. The ground's brightness is a signed difference to what it would have got with no glass, so shadows are coloured and soft and the caustics are the surplus. `glass-caustics.ts` is the readable CPU version of the same optics, with the tests.
112
+ - **Dark theme.** There is no sun; the light is each block's rod. What one block casts on the ground is *baked*: `assets/caustic-templates.png` holds path-traced templates (Mitsuba 3) of a glass block with a rod in it, for 3 heights x 4 heights above the ground, averaged over the square's symmetries. The graph lays the right template under every block, in the rod's colour. Tracing this live does not work: with the rays a page can afford the result is noise.
113
+ - **Start-up.** The blocks are split into 8 oval areas, each with its own stutter, then a warm-up; a block whose rod is off is dim and lit by its lit neighbours. The sound is Web Audio (a 100 Hz ballast hum and bell-like dings), no file. Afterwards, rarely and less and less, a batch of tubes flickers like a sign's.
114
+ - **Grain.** A soft, luminance-dependent noise added in the last pass, like a camera's.
115
+
116
+ ### Regenerating the caustic templates
117
+
118
+ Only needed if the blocks' shape or the rod changes. See `scripts/caustic-templates/README.md` (Mitsuba 3, about 15 minutes), then `pnpm embed:templates` rewrites the embedded data URI (`pnpm build` does it too).
119
+
120
+ ## Demo and playground
121
+
122
+ The [demo](https://bsodium.github.io/Neon-activity-graph/) draws the author's current activity (GitHub contributions over WakaTime coding time) and falls back to generated data when the activity file is not there. `demo/` is the page, `demo/scripts/fetch-activity.mjs` fetches public data without a token (a scheduled workflow writes `activity.json` to the `data` branch every 6 hours; set the repository variables `GITHUB_LOGIN` and `WAKATIME_USER` to draw somebody else).
123
+
124
+ ```sh
125
+ pnpm demo # the demo page
126
+ pnpm dev # the playground: fake data and every option
127
+ ```
128
+
129
+ ## Releasing (maintainers)
130
+
131
+ Releases go through npm Trusted Publishing (OIDC): no npm token is created or stored.
132
+
133
+ 1. **First version, once, by hand** (a trusted publisher can only be attached to a package that exists): in this folder, `pnpm install && pnpm run build`, then `npm login` (with your 2FA) and `npm publish --access public`. (`npm pack --dry-run` lists what goes in: `dist`, `README.md`, `LICENSE`, and a `package.json` whose `exports` point at `dist`.)
134
+ 2. On npmjs.com, open the package > Settings > Trusted Publisher > GitHub Actions: user `BSoDium`, repository `Neon-activity-graph`, workflow file `release.yml`, environment empty.
135
+ 3. From then on: bump `version` in `package.json`, commit, then `git tag vX.Y.Z && git push origin vX.Y.Z`. The `release` workflow tests, builds and publishes with provenance (the tag must match the version).
136
+
137
+ ## License
138
+
139
+ MIT