Technical Documentation
AstroCal
An astronomical calendar with lunar phases, solar and lunar eclipses, hemisphere awareness, timezone support, and Zmanim — built from scratch in vanilla JavaScript
Origin
This calendar started out as a table in Microsoft Word — initially created as a more aesthetically pleasing option than the printable calendars available online. Moon phase symbols came next. Having to retype the calendar every month, the decision was made to turn it into a dynamic website. What followed was a years-long process of layering in precision: date navigation, hemispheres, eclipses, timezones, Zmanim. Each feature integrated into the existing architecture rather than bolted on.
The calendar renders moon phases, lunar and solar eclipses, hemisphere-aware iconography, full timezone support with UTC conversion, Dawn and Midnight Zmanim via the Hebcal library, and an interactive legend. All phase and eclipse data is calculated using Don Cross's Astronomy Engine, chosen specifically for the accuracy of its mathematics.
The moon has been pulling human attention for hundreds of thousands of years. Every culture has tracked it, named it, built calendars and rituals around it. What draws me to it isn't religion or photography — it's that same instinct I have with everything: when something is complex and beautiful, I want to bring it close enough to touch. The technology now exists to know exactly what the moon is doing at any moment. This calendar is a way of making that relationship tangible — turning something vast and ancient into something you can check over your morning coffee.
Features
Lunar phases
- All eight principal moon phases rendered per day across the month
- Phase calculations performed using Don Cross's Astronomy Engine — chosen specifically for mathematical accuracy
- All symbols are Unicode icons converted to SVGs, hand-aligned to the pixel
- Hemisphere toggle adjusts icon orientation accordingly — northern and southern hemisphere rendering differ
Eclipses
- Both lunar and solar eclipses detected and displayed for the current month
- Eclipse data computed via Astronomy Engine alongside phase data — same calculation pass, no separate lookup
- Eclipse indicators rendered inline within the calendar grid
Timezone support
- Full timezone selection with precise UTC offset conversion
- All astronomical times — phase transitions, eclipse moments, Zmanim — displayed in the selected timezone
- Timezone state persists across navigation
Zmanim — Dawn and Midnight
- Halachic dawn and astronomical midnight calculated via the Hebcal Zmanim library
- Times displayed per day when Zmanim mode is active
- Geolocation-aware: calculations use the observer's coordinates
Interactive legend
- Fully interactive legend explaining all symbols used in the calendar
- Toggle controls for showing and hiding individual data layers
Date navigation
- Forward and backward month navigation with full recalculation on each view
- Jumps to any month and year
- Current day highlighted automatically
Technical Approach
The calendar is built entirely in vanilla JavaScript — no framework, no build step, no bundler. The decision to avoid dependencies was deliberate: the Astronomy Engine and Hebcal libraries are the two exceptions, both chosen for domain-specific accuracy rather than convenience.
Astronomical calculations are performed client-side on each render. Phase and eclipse data for the visible month is computed in a single pass using the Astronomy Engine, which provides the mathematical precision required for reliable eclipse detection. Zmanim calculations are layered on top via Hebcal, using the observer's geolocation when available.
The SVG icon system was built by hand: each moon phase symbol started as a Unicode character, was traced and refined into a clean SVG path, and then tuned for visual consistency across the full phase cycle. Hemisphere-awareness required a separate set of orientations for southern-hemisphere rendering, where the crescent and gibbous phases appear mirrored.
Tech Stack
| Language | Vanilla JavaScript — no framework, no build step |
| Astronomical calculations | Astronomy Engine by Don Cross |
| Zmanim calculations | Hebcal Core (Zmanim class) |
| Icons | Unicode characters converted to hand-authored SVGs |
| Styling | Hand-authored CSS using the Musical Interval Typography System |
| Hosting | Static site, served via PHP host |
Design Notes
The calendar was conceived as something beautiful before it was conceived as something functional. The original Word table prioritized aesthetics — readable type, clean grid, considered spacing — and that priority carried through every subsequent version. The SVG icons were aligned to the pixel not because it was required but because misalignment was noticeable and unacceptable.
The same Musical Interval Typography System that governs bachtogauss.com governs the calendar's layout — the same ratio, the same note variables, the same two media queries. The calendar is not a separate design artifact; it is part of the same document.
A native app version of the calendar extends this work to mobile, preserving the same calculation engine and visual language in an application context.
Credits
- Astronomy Engine by Don Cross — astronomical calculations including lunar phases and eclipse detection
- Hebcal Core / Zmanim — halachic and astronomical time calculations
- Ian Venskus — pixel-level design alignment and consultation