Files
vcr-calendar/README.md
2026-11-02 21:02:57 -05:00

90 lines
4.5 KiB
Markdown

> [!IMPORTANT]
> AI Disclaimer: This project was built with the assistance of [Claude](https://claude.com/product/overview) (using [Cursor](https://cursor.com)).
# VCR Calendar
A zero-JavaScript, server-rendered weekly calendar for [voidzero Community Radio](https://voidzero.stream) (VCR) and [Small Group](https://smallgroupscoop.com) podcast schedules. Built on Cloudflare Workers.
> **Note:** This schedule is unofficial and subject to change. Show times are maintained on a best-effort basis and may not reflect last-minute changes.
## Features
- **Week grid view** — CSS Grid calendar with half-hour time slots, colored show blocks, and live-now indicators
- **Agenda view** — day-by-day breakdown below the grid
- **Show detail pages** — description, hosts, website/feed links, and schedule badges
- **Timezone conversion** — Eastern, Central, Pacific, UTC, and Amsterdam with cookie-persisted preference
- **Light / Dark / System themes** — cookie-persisted, zero-JS theme switching via server-rendered links
- **Overnight show support** — shows crossing midnight render correctly across day boundaries and timezones
- **Fully server-rendered** — no client-side JavaScript; all interactivity through links and `Set-Cookie` headers
- **Week navigation** — browse past and future weeks via date picker
## Tech Stack
- **Runtime:** [Cloudflare Workers](https://workers.cloudflare.com)
- **Language:** TypeScript
- **Rendering:** Server-side HTML string templates
- **Styling:** Inline CSS (single `<style>` block, no external files)
- **Testing:** [Vitest](https://vitest.dev) with [`@cloudflare/vitest-pool-workers`](https://developers.cloudflare.com/workers/testing/vitest-integration/)
- **Deploy:** [Wrangler](https://developers.cloudflare.com/workers/wrangler/)
## Getting Started
```bash
npm install
npm run dev # local dev server on http://localhost:8787
npm test # run test suite
npm run deploy # deploy to Cloudflare Workers
```
Requires a [Cloudflare account](https://dash.cloudflare.com/sign-up) and [`wrangler` authentication](https://developers.cloudflare.com/workers/wrangler/commands/#login) for deployment.
## Project Structure
```
src/
├── index.ts # Worker entry point and router
├── schedule.json # Show roster (times in America/New_York)
├── preferences.ts # Cookie/query param preference resolution
├── types.ts # TypeScript type definitions
├── time/
│ ├── zones.ts # Timezone config and conversion (Intl.DateTimeFormat)
│ └── week.ts # Week boundary calculations
├── render/
│ ├── page.ts # HTML shell, controls bar, header/footer
│ ├── week-grid.ts # CSS Grid week view renderer
│ ├── week-page.ts # Week page composition (grid + agenda)
│ ├── agenda.ts # Day-by-day agenda renderer
│ ├── show-detail.ts # Individual show detail page
│ ├── not-found.ts # 404 page
│ └── utils.ts # Shared render helpers
└── style/
└── css.ts # Complete CSS as template literal
```
## Adding / Editing Shows
All show data lives in [`src/schedule.json`](src/schedule.json). Each show entry includes:
- Schedule (day, start/end time, timezone, recurrence)
- Metadata (name, slug, description, hosts, accent color)
- Links (website URL, RSS feed URL)
- Flags (`isVcr`, `isSmallGroup`, `isActive`)
Times are in 24-hour format. Overnight shows use a `+1` suffix on `endTime` (e.g., `"01:00+1"` means 1:00 AM the next day).
## URL Parameters
All parameters are optional. Values set via query params are persisted in cookies for future visits.
| Param | Values | Default | Notes |
|---------|-----------------------------------------------------|-----------|-------|
| `tz` | `eastern`, `central`, `pacific`, `utc`, `amsterdam` | `eastern` | Sets timezone for all displayed times |
| `theme` | `system`, `light`, `dark` | `system` | `system` follows OS preference |
| `mode` | `vcr`, `all` | `vcr` | `vcr` shows VCR-only schedule; `all` includes Small Group and non-VCR shows |
| `week` | `YYYY-MM-DD` (any date in the target week) | current week | Week always starts on Sunday |
| `reset` | `1` | — | Clears all cookie preferences and returns to defaults |
## License
[MIT](LICENSE)