Public: anyone can read this; the crew can change it.

An .ics calendar file opens as its events in the browser #13615

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

mason/forge:mason/13591-an-ics-calendar-file-opens-as-its-events → main 3 commits fork

  • Merged. mason/13591-an-ics-calendar-file-opens-as-its-events was merged into main as c555d6d.

Review

Sign in to review this change.
3 files changed +17 −27
docs/features/ics.md +3 −3
@@ -1,12 +1,12 @@
11 # Calendar files (.ics) as a list of events
22
3 Open a `.ics` file in a repository, such as a calendar export, and read its events as a table: start, end, summary, location, sorted by start.
3 Open a `.ics` file in a repository, such as a calendar export, and read its events as a table: start, end, summary, location, in the file's own order.
44
55 - **Web:** the blob page draws the table on the server (`src/web/render/ics.ts`, `parseIcs`). `?view=source`, Raw and Download work as for any file.
66 - **Terminal:** the workspace opens a `.ics` as the same table (`src/tui/screens/workspace.ts`, sharing `parseIcs` and `EVENT_CAP`); `s` flips to the source. The status line reads `N events`, and `· N events could not be read, not shown` when some were skipped.
77 - Folded lines are unfolded and `\,` `\;` `\n` escapes are undone. UTC times show as `UTC`, `TZID` times keep their zone name, all-day events show dates and the last day (the file's end is exclusive).
8 - Events are sorted by start as written (text order); time zones are not applied, so events in different zones can be out of order, and the web says so in one line when a file holds more than one zone.
8 - Events appear in the order the file lists them; times are shown as written, with their zone name, and no zone is applied.
99 - An event with no readable `DTSTART` is skipped, and both doors count them in one line (the web's, under the table; the terminal's, in the status line).
10 - The first 200 events (`EVENT_CAP`) are shown; the rest are counted.
10 - The first 500 events (`EVENT_CAP`) are shown; the rest are counted.
1111 - A file with no `BEGIN:VCALENDAR` is not a calendar, and a calendar where no event could be read, or with none: it shows as source, with a one-line reason on the web.
1212 - All text is escaped on output; the parser is pure and never throws.
src/web/render/ics.ts +3 −11
@@ -1,6 +1,6 @@
11 /**
22 * A calendar file (iCalendar `.ics`, RFC 5545) as a list of its events: start,
3 * end (or "all day"), summary and location, sorted by start. Lines are unfolded
3 * end (or "all day"), summary and location, in the file's own order. Lines are unfolded
44 * (§3.1), VEVENT blocks read, DTSTART/DTEND taken with or without TZID, and
55 * TEXT escapes (`\,` `\;` `\\` `\n`) undone. Every value is escaped on output.
66 * A file that is not a calendar falls back to its source; an event that cannot
@@ -12,7 +12,7 @@ import { fileSize } from "../ui.ts";
1212 import type { Rendered, RenderInput } from "./renderers.ts";
1313
1414 /** Events drawn, whatever the file holds. */
15 export const EVENT_CAP = 200;
15 export const EVENT_CAP = 500;
1616
1717 export interface IcsEvent {
1818 /** `2026-03-01 09:00`, `2026-03-01`, with a zone note when the file gave one. */
@@ -133,8 +133,6 @@ export function parseIcs(source: string): Calendar {
133133 }
134134 }
135135 if (props !== undefined) skipped++;
136 // Stable: events that start together keep file order. Dates sort as text; a zone is not applied.
137 events.sort((a, b) => (a.start < b.start ? -1 : a.start > b.start ? 1 : 0));
138136 return { events, skipped };
139137 }
140138
@@ -179,12 +177,6 @@ export function ics(input: RenderInput): Rendered {
179177 cal.skipped > 0
180178 ? `<p class="muted small">${cal.skipped.toLocaleString()} ${cal.skipped === 1 ? "event" : "events"} could not be read and ${cal.skipped === 1 ? "is" : "are"} not shown.</p>`
181179 : "";
182 // Start times sort as written, so two zones can be out of order against each other: say so.
183 const zones = new Set(cal.events.filter((e) => !e.allDay).map((e) => e.start.slice(17)));
184 const zoned =
185 zones.size > 1
186 ? `<p class="muted small">Events are sorted by the start as written; time zones are not applied, so events in different zones may be out of order.</p>`
187 : "";
188180 const more =
189181 cal.events.length > EVENT_CAP
190182 ? `<p class="muted small">Showing ${EVENT_CAP.toLocaleString()} of ${cal.events.length.toLocaleString()} events, ${(cal.events.length - EVENT_CAP).toLocaleString()} more. The rest is in the raw file.</p>`
@@ -193,7 +185,7 @@ export function ics(input: RenderInput): Rendered {
193185 const content = html`<table class="table" data-dense aria-label="${name} events">
194186 <thead><tr><th scope="col">Start</th><th scope="col">End</th><th scope="col">Summary</th><th scope="col">Location</th></tr></thead>
195187 <tbody>${raw(rows)}</tbody>
196 </table>${raw(more)}${raw(bad)}${raw(zoned)}`;
188 </table>${raw(more)}${raw(bad)}`;
197189 const n = cal.events.length;
198190 return { content, lines: 0, summary: `${n.toLocaleString()} ${n === 1 ? "event" : "events"} · ${fileSize(input.size)}` };
199191 }
test/render-ics.test.ts +11 −13
@@ -15,7 +15,7 @@ describe("calendar files", () => {
1515 expect(RENDERERS.calendar).toBe(ics);
1616 });
1717
18 test("folded lines, escapes, UTC and TZID times, sorted by start", () => {
18 test("folded lines, escapes, UTC and TZID times", () => {
1919 const cal = parseIcs(
2020 wrap(
2121 "DTSTART:20260301T090000Z\r\nDTEND:20260301T100000Z\r\nSUMMARY:Plan\\, build\\nand a very long\r\n title folded\r\nLOCATION:Room 1\\; East",
@@ -40,8 +40,8 @@ describe("calendar files", () => {
4040 );
4141 if ("error" in cal) throw new Error(cal.error);
4242 expect(cal.events.map((e) => [e.allDay, e.start, e.end])).toEqual([
43 [true, "2026-02-28", "2026-03-02"],
4443 [true, "2026-03-01", ""],
44 [true, "2026-02-28", "2026-03-02"],
4545 ]);
4646 const out = String(draw(wrap("DTSTART;VALUE=DATE:20260301\r\nSUMMARY:X")).content);
4747 expect(out).toContain("all day");
@@ -62,14 +62,14 @@ describe("calendar files", () => {
6262 expect(r.summary).toContain("1 event");
6363 });
6464
65 test("events are sorted by start, not file order; non-VEVENT parts are ignored", () => {
65 test("events keep the file's own order; non-VEVENT parts are ignored", () => {
6666 const cal = parseIcs(
6767 "BEGIN:VCALENDAR\r\nBEGIN:VTODO\r\nDTSTART:20250101T000000Z\r\nSUMMARY:todo\r\nEND:VTODO\r\n" +
6868 "BEGIN:VEVENT\r\nDTSTART:20260305T090000Z\r\nSUMMARY:late\r\nEND:VEVENT\r\n" +
6969 "BEGIN:VEVENT\r\nDTSTART;VALUE=DATE:20260301\r\nSUMMARY:early\r\nEND:VEVENT\r\nEND:VCALENDAR\r\n",
7070 );
7171 if ("error" in cal) throw new Error(cal.error);
72 expect(cal.events.map((e) => e.summary)).toEqual(["early", "late"]);
72 expect(cal.events.map((e) => e.summary)).toEqual(["late", "early"]);
7373 });
7474
7575 test("a malformed file shows the rows it could read and one line about the rest", () => {
@@ -85,14 +85,12 @@ describe("calendar files", () => {
8585 expect(String(open.content)).toContain("1 event could not be read");
8686 });
8787
88 test("two zones in one file get one note after the table; one zone gets none", () => {
89 const mixed = String(
88 test("events in different zones stay in file order, with no note", () => {
89 const out = String(
9090 draw(wrap("DTSTART:20260301T090000Z\r\nSUMMARY:a", "DTSTART;TZID=Europe/Paris:20260301T080000\r\nSUMMARY:b")).content,
9191 );
92 expect(mixed.match(/time zones are not applied/g)?.length).toBe(1);
93 expect(mixed.indexOf("time zones are not applied")).toBeGreaterThan(mixed.indexOf("</table>"));
94 const one = String(draw(wrap("DTSTART:20260301T090000Z\r\nSUMMARY:a", "DTSTART:20260302T090000Z\r\nSUMMARY:b")).content);
95 expect(one).not.toContain("time zones");
92 expect(out).not.toContain("time zones");
93 expect(out.indexOf(">a<")).toBeLessThan(out.indexOf(">b<"));
9694 });
9795
9896 test("malformed files fall back to text", () => {
@@ -103,11 +101,11 @@ describe("calendar files", () => {
103101 expect(draw("BEGIN:VCALENDAR\r\nEND:VCALENDAR\r\n").fallback).toContain("no events");
104102 });
105103
106 test("capped at 200 events, saying how many more", () => {
104 test("capped at 500 events, saying how many more", () => {
107105 const many = Array.from({ length: EVENT_CAP + 7 }, (_, i) => `DTSTART:20260301T090000Z\r\nSUMMARY:e${i}`);
108106 const out = String(draw(wrap(...many)).content);
109 expect(out).toContain("e199<");
110 expect(out).not.toContain("e200<");
107 expect(out).toContain("e499<");
108 expect(out).not.toContain("e500<");
111109 expect(out).toContain("7 more");
112110 });
113111 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs