@craftguild/jscalendar 0.1.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2026 Progressive Works, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,295 @@
+# RFC 8984 (JSCalendar) TypeScript Library
+
+This library provides a thin, practical TypeScript API for working with
+RFC 8984 (JSCalendar) objects. It focuses on creation, mutation, search,
+and export. It does **not** implement a calendar application or server.
+The goal is to keep the data model easy to use in web apps and CLIs while
+preserving access to the full RFC object structure when you need it.
+
+Primary object types are **Event**, **Task**, and **Group**. A **Group**
+acts as a container when you want to bundle multiple objects. The API is
+intentionally small: you create objects, mutate them with safe helpers,
+query them with search utilities, and export them to iCalendar as needed.
+
+## Installation
+
+```bash
+pnpm add @craftguild/jscalendar
+```
+
+## Quick Start
+
+```ts
+import { JsCal } from "@craftguild/jscalendar";
+
+const event = new JsCal.Event({
+  title: "Kickoff",
+  start: "2026-02-03T09:00:00",
+  timeZone: "America/New_York",
+  duration: "PT1H",
+});
+
+const items = [event.eject()];
+```
+
+## Object Creation
+
+Objects are created with `new JsCal.Event`, `new JsCal.Task`, and
+`new JsCal.Group`. Each constructor accepts a plain JSCalendar-like
+object and normalizes required fields (e.g., `uid`, `updated`).
+
+### Event
+
+```ts
+const event = new JsCal.Event({
+  title: "Team Sync",
+  start: "2026-02-10T10:00:00",
+  timeZone: "America/New_York",
+  duration: "PT30M",
+});
+```
+
+### Task
+
+```ts
+const task = new JsCal.Task({
+  title: "Write report",
+  start: "2026-02-11T09:00:00",
+  due: "2026-02-11T17:00:00",
+  percentComplete: 10,
+});
+```
+
+### Group
+
+```ts
+const group = new JsCal.Group({
+  title: "Project A",
+  entries: [event.eject(), task.eject()],
+});
+```
+
+## Updates and Mutations
+
+Mutation helpers update the underlying data and keep metadata such as
+`updated` and `sequence` consistent. Use `update` for shallow updates
+and `patch` for RFC 8984 PatchObject semantics.
+
+```ts
+event.update({ title: "Updated title" });
+event.patch({ title: "Patched title" });
+
+event.addLocation({ name: "Room A" });
+event.addVirtualLocation({ name: "Zoom", uri: "https://example.com" });
+event.addParticipant({ roles: { attendee: true }, email: "a@example.com" });
+event.addAlert({
+  trigger: { "@type": "AbsoluteTrigger", when: "2026-02-10T09:00:00Z" },
+});
+```
+
+## Date Inputs and Time Zones
+
+Date fields accept either RFC 8984 strings or JavaScript `Date`. When a
+`Date` is given, `start`/`due` are converted to LocalDateTime strings and
+`updated`/`created` are converted to UTCDateTime (`Z` suffix). If a
+`timeZone` is set, it is normalized through the bundled time zone list.
+
+`start`, `due`, `updated`, and `created` accept `string` or `Date`.
+
+```ts
+const eventFromDate = new JsCal.Event({
+  title: "Kickoff",
+  start: new Date(),
+});
+
+const eventWithSeconds = new JsCal.Event({
+  title: "Kickoff",
+  start: new Date(),
+  duration: 90 * 60, // seconds
+});
+
+const eventWithZone = new JsCal.Event({
+  title: "Kickoff",
+  start: new Date(),
+  timeZone: JsCal.timeZone("asia/tokyo"), // => Asia/Tokyo
+});
+```
+
+## Utility Methods
+
+All utilities are available on `JsCal`.
+
+The search helpers operate on JSCalendar objects or `JsCal` instances.
+They are intended for lightweight filtering and text matching in
+application code. For more complex queries, use your datastore’s
+query engine or build a custom index.
+
+```ts
+const results = JsCal.filterByDateRange(items, {
+  start: "2026-02-01T00:00:00Z",
+  end: "2026-02-28T23:59:59Z",
+});
+
+const found = JsCal.findByUid(items, "uid-123");
+const byType = JsCal.filterByType(items, "Event");
+const grouped = JsCal.groupByType(items);
+const textHits = JsCal.filterByText(items, "meeting");
+
+const uid = JsCal.createUid();
+const id = JsCal.createId();
+
+const d1 = JsCal.duration.minutes(90); // PT1H30M
+const d2 = JsCal.duration.from({ hours: 1, minutes: 15 }); // PT1H15M
+
+const tz = JsCal.timeZone("asia/tokyo"); // => Asia/Tokyo
+const tzList = JsCal.timeZones;
+```
+
+## Recurrence Expansion
+
+The recurrence expansion API is a generator.
+
+Expansion follows RFC 8984 semantics for recurrence rules, including
+overrides and exclusions. The output instances contain `recurrenceId`
+and preserve the base object’s data unless a patch modifies fields.
+
+```ts
+for (const occ of JsCal.expandRecurrence(
+  [event],
+  { from: new Date("2026-02-01"), to: new Date("2026-03-01") }
+)) {
+  console.log(occ);
+}
+```
+
+### Paged Expansion (for infinite scroll)
+
+`expandRecurrencePaged` wraps the generator and provides a cursor-based
+paging interface. This is convenient when rendering a list with virtual
+scrolling or an infinite feed.
+
+```ts
+const page1 = JsCal.expandRecurrencePaged(
+  [event],
+  { from: new Date("2026-02-01"), to: new Date("2026-03-01") },
+  { limit: 50 }
+);
+
+const page2 = JsCal.expandRecurrencePaged(
+  [event],
+  { from: new Date("2026-02-01"), to: new Date("2026-03-01") },
+  { limit: 50, cursor: page1.nextCursor }
+);
+```
+
+## Time Zone Aware Filtering (Date range)
+
+If `timeZone` is set, `Date` inputs are converted to that time zone
+via `date-fns-tz` before comparison.
+
+This ensures that “wall-clock time” comparisons respect the event’s
+time zone, including DST transitions, as long as the event defines
+`timeZone`. Floating LocalDateTime values without `timeZone` are
+compared as simple strings.
+
+```ts
+const event = new JsCal.Event({
+  start: "2026-02-01T10:00:00",
+  timeZone: "Asia/Tokyo",
+});
+
+// 2026-02-01T01:00:00Z is 10:00 in Asia/Tokyo
+const results = JsCal.filterByDateRange(
+  [event],
+  { start: new Date("2026-02-01T01:00:00Z"), end: new Date("2026-02-01T01:00:00Z") }
+);
+console.log(results.length); // 1
+```
+
+## iCalendar Export
+
+Export uses a minimal mapping from JSCalendar to iCalendar. Any fields
+that cannot be represented are preserved in `X-JSCALENDAR` to avoid data
+loss. This keeps exports reversible while staying compatible with most
+consumers.
+
+```ts
+// includeXJSCalendar defaults to true.
+const ical = JsCal.toICal([event]);
+const icalNoX = JsCal.toICal([event], { includeXJSCalendar: false });
+console.log(ical);
+
+const icalMany = JsCal.toICal([event, task], { includeXJSCalendar: true });
+console.log(icalMany);
+```
+
+## Practical Example
+
+**Weekly engineering sync (every Wednesday 10:30, 1 hour)**
+
+```ts
+const weekly = new JsCal.Event({
+  title: "Engineering Sync",
+  start: "2026-02-04T10:30:00",
+  timeZone: "Asia/Tokyo",
+  duration: JsCal.duration.hours(1),
+  recurrenceRules: [
+    {
+      "@type": "RecurrenceRule",
+      frequency: "weekly",
+      byDay: [{ "@type": "NDay", day: "we" }],
+    },
+  ],
+});
+```
+
+## Compliance and Deviations
+
+### RFC 8984 Conformance (Implemented)
+
+These points are implemented directly as specified in RFC 8984 and are
+covered by tests.
+
+- Core JSCalendar object model (Event / Task / Group) as TypeScript types.
+- Recurrence rules and overrides (RRULE/EXRULE semantics in RFC 8984).
+- Default values for fields defined by RFC 8984 (e.g., `sequence`, `priority`, `freeBusyStatus`, etc.).
+- LocalDateTime and UTCDateTime handling with explicit types.
+- iCalendar export with `X-JSCALENDAR` for data preservation.
+
+### Deviations / Partial Implementations
+
+This library is designed to be practical and lightweight, not a full RFC engine.
+
+The items below are the known deltas between a strict RFC implementation
+and this library’s behavior.
+
+- **rscale**: only `gregorian` is supported; any other value throws.
+- **Validation**: strict type/format validation is enforced by default (RFC-style date/time and duration rules),
+  but can be disabled with `{ validate: false }` in create/update/patch.
+- **Time zone and DST**:
+  - Range filtering and recurrence comparisons use `date-fns-tz`.
+  - Recurrence generation still operates on LocalDateTime arithmetic and does not fully normalize
+    DST gaps/overlaps into canonical UTC instants for all cases.
+- **iCalendar export**: minimal mapping + `X-JSCALENDAR`; no VTIMEZONE generation.
+
+If you require strict, formal compliance, please treat this as a foundation
+and extend the validation/export behavior in your own application.
+
+## Reference Materials
+
+- RFC 8984: JSCalendar specification.
+- RFC 7529: Non-Gregorian recurrence rules used by JSCalendar (rscale).
+- Time zone identifiers: IANA Time Zone Database (tzdata), using Area/Location IDs
+  (e.g., America/New_York, Asia/Tokyo).
+
+## Code of Conduct
+
+See `CODE_OF_CONDUCT.md`.
+
+## Contributing
+
+See `CONTRIBUTING.md`.
+
+## License
+
+See `LICENSE.md`.

package/dist/__tests__/calendar-extra.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar-extra.test.js

@@ -0,0 +1,185 @@
+import { describe, expect, it } from "vitest";
+import { JsCal, createId, isEvent, isGroup, isTask } from "../jscal.js";
+const fixedNow = () => "2026-02-01T00:00:00Z";
+function makeEvent() {
+    return new JsCal.Event({
+        title: "Kickoff",
+        start: "2026-02-02T10:00:00",
+    }, { now: fixedNow });
+}
+describe("JsCal helpers", () => {
+    it("creates group and adds entry", () => {
+        const group = new JsCal.Group({ entries: [] }, { now: fixedNow });
+        const event = makeEvent();
+        group.addEntry(event.data);
+        expect(group.data.entries.length).toBe(1);
+    });
+    it("does not expose addEntry on non-group", () => {
+        const event = makeEvent();
+        expect("addEntry" in event).toBe(false);
+    });
+    it("adds locations and virtual locations", () => {
+        const event = makeEvent();
+        const locId = event.addLocation({ name: "Room A" });
+        const vlocId = event.addVirtualLocation({ name: "Zoom", uri: "https://example.com" });
+        const locations = event.data.locations;
+        const virtualLocations = event.data.virtualLocations;
+        expect(locations).toBeDefined();
+        expect(virtualLocations).toBeDefined();
+        if (!locations || !virtualLocations)
+            throw new Error("Missing locations");
+        expect(locations[locId]?.name).toBe("Room A");
+        expect(virtualLocations[vlocId]?.uri).toBe("https://example.com");
+    });
+    it("adds participants and alerts", () => {
+        const event = makeEvent();
+        const participantId = event.addParticipant({ roles: { attendee: true }, email: "a@example.com" });
+        const alertId = event.addAlert({ trigger: { "@type": "AbsoluteTrigger", when: "2026-02-01T01:00:00Z" } });
+        const participants = event.data.participants;
+        const alerts = event.data.alerts;
+        expect(participants).toBeDefined();
+        expect(alerts).toBeDefined();
+        if (!participants || !alerts)
+            throw new Error("Missing participants/alerts");
+        expect(participants[participantId]?.email).toBe("a@example.com");
+        expect(alerts[alertId]?.trigger).toBeTruthy();
+        expect(participants[participantId]?.participationStatus).toBe("needs-action");
+        expect(participants[participantId]?.expectReply).toBe(false);
+        expect(participants[participantId]?.scheduleAgent).toBe("server");
+        expect(participants[participantId]?.scheduleForceSend).toBe(false);
+        expect(participants[participantId]?.scheduleSequence).toBe(0);
+        expect(alerts[alertId]?.action).toBe("display");
+    });
+    it("defaults relativeTo for offset triggers", () => {
+        const event = makeEvent();
+        const alertId = event.addAlert({ trigger: { "@type": "OffsetTrigger", offset: "PT15M" } });
+        const alerts = event.data.alerts;
+        expect(alerts).toBeDefined();
+        if (!alerts)
+            throw new Error("Missing alerts");
+        const trigger = alerts[alertId]?.trigger;
+        if (!trigger || trigger["@type"] !== "OffsetTrigger")
+            throw new Error("Missing trigger");
+        expect(trigger.relativeTo).toBe("start");
+    });
+    it("updates sequence for alerts but not for participants", () => {
+        const event = makeEvent();
+        const initialSequence = event.data.sequence ?? 0;
+        event.addParticipant({ roles: { attendee: true }, email: "a@example.com" });
+        expect(event.data.sequence ?? 0).toBe(initialSequence);
+        event.addAlert({ trigger: { "@type": "AbsoluteTrigger", when: "2026-02-01T01:00:00Z" } });
+        expect(event.data.sequence ?? 0).toBe(initialSequence + 1);
+    });
+    it("clones and eject return deep copies", () => {
+        const event = makeEvent();
+        const clone = event.clone();
+        clone.data.title = "Changed";
+        expect(event.data.title).toBe("Kickoff");
+        const json = event.eject();
+        json.title = "Changed";
+        expect(event.data.title).toBe("Kickoff");
+    });
+    it("createId returns base64url without padding", () => {
+        const id = createId();
+        expect(id).toMatch(/^[A-Za-z0-9_-]+$/);
+        expect(id).not.toContain("=");
+    });
+    it("supports task creation", () => {
+        const task = new JsCal.Task({
+            title: "Do work",
+            start: "2026-02-02T10:00:00",
+        }, { now: fixedNow });
+        expect(task.data["@type"]).toBe("Task");
+        expect(task.data.created).toBe("2026-02-01T00:00:00Z");
+    });
+    it("supports group creation", () => {
+        const group = new JsCal.Group({ entries: [] }, { now: fixedNow });
+        expect(group.data["@type"]).toBe("Group");
+        expect(group.data.created).toBe("2026-02-01T00:00:00Z");
+    });
+    it("accepts Date inputs and null time zones", () => {
+        const start = new Date("2026-02-02T10:00:00");
+        const event = new JsCal.Event({ title: "Date input", start, timeZone: null }, { now: fixedNow });
+        expect(event.data.start).toMatch(/^2026-02-02T/);
+        expect(event.data.timeZone).toBeNull();
+        const task = new JsCal.Task({ title: "No TZ", start, timeZone: null }, { now: fixedNow });
+        expect(task.data.timeZone).toBeNull();
+    });
+    it("accepts Date inputs for updated/created", () => {
+        const updated = new Date("2026-02-02T10:00:00Z");
+        const created = new Date("2026-02-01T09:00:00Z");
+        const event = new JsCal.Event({
+            title: "Dates",
+            start: "2026-02-02T10:00:00",
+            updated,
+            created,
+        });
+        expect(event.data.updated).toBe("2026-02-02T10:00:00Z");
+        expect(event.data.created).toBe("2026-02-01T09:00:00Z");
+    });
+    it("rejects invalid event start", () => {
+        expect(() => new JsCal.Event({ title: "Bad", start: "" })).toThrow();
+    });
+    it("resolves task time zones", () => {
+        const task = new JsCal.Task({ title: "TZ", start: "2026-02-02T10:00:00", timeZone: "asia/tokyo" }, { now: fixedNow });
+        expect(task.data.timeZone).toBe("Asia/Tokyo");
+    });
+    it("derives task progress from participant statuses", () => {
+        const completed = new JsCal.Task({
+            title: "Completed",
+            participants: {
+                p1: { "@type": "Participant", roles: { attendee: true }, progress: "completed" },
+            },
+        }, { now: fixedNow });
+        expect(completed.data.progress).toBe("completed");
+        const failed = new JsCal.Task({
+            title: "Failed",
+            participants: {
+                p1: { "@type": "Participant", roles: { attendee: true }, progress: "failed" },
+            },
+        }, { now: fixedNow });
+        expect(failed.data.progress).toBe("failed");
+        const inProcess = new JsCal.Task({
+            title: "In process",
+            participants: {
+                p1: { "@type": "Participant", roles: { attendee: true }, progress: "in-process" },
+            },
+        }, { now: fixedNow });
+        expect(inProcess.data.progress).toBe("in-process");
+        const fallback = new JsCal.Task({
+            title: "Fallback",
+            participants: {
+                p1: { "@type": "Participant", roles: { attendee: true }, progress: "delegated" },
+            },
+        }, { now: fixedNow });
+        expect(fallback.data.progress).toBe("needs-action");
+    });
+    it("clones task and group objects", () => {
+        const task = new JsCal.Task({ title: "Task", start: "2026-02-02T10:00:00" }, { now: fixedNow });
+        const taskClone = task.clone();
+        taskClone.data.title = "Changed";
+        expect(task.data.title).toBe("Task");
+        const group = new JsCal.Group({ entries: [] }, { now: fixedNow });
+        const groupClone = group.clone();
+        groupClone.data.title = "Changed";
+        expect(group.data.title).toBe("");
+    });
+    it("requires entries for group creation", () => {
+        // @ts-expect-error entries are required
+        expect(() => new JsCal.Group({})).toThrow();
+    });
+    it("supports get/set helpers", () => {
+        const event = makeEvent();
+        expect(event.get("title")).toBe("Kickoff");
+        event.set("title", "Updated");
+        expect(event.get("title")).toBe("Updated");
+    });
+    it("exposes type guards", () => {
+        const event = makeEvent().eject();
+        const task = new JsCal.Task({ title: "Task", start: "2026-02-02T10:00:00" }).eject();
+        const group = new JsCal.Group({ entries: [] }).eject();
+        expect(isEvent(event)).toBe(true);
+        expect(isTask(task)).toBe(true);
+        expect(isGroup(group)).toBe(true);
+    });
+});

package/dist/__tests__/calendar.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar.test.js

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import { JsCal, createUid } from "../jscal.js";
+const fixedNow = () => "2026-02-01T00:00:00Z";
+function makeEvent() {
+    return new JsCal.Event({
+        title: "Kickoff",
+        start: "2026-02-02T10:00:00",
+    }, { now: fixedNow });
+}
+describe("JsCal.Event", () => {
+    it("fills uid and updated", () => {
+        const event = makeEvent();
+        expect(event.data.uid).toBeTruthy();
+        expect(event.data.updated).toBe("2026-02-01T00:00:00Z");
+        expect(event.data["@type"]).toBe("Event");
+        expect(event.data.sequence).toBe(0);
+        expect(event.data.duration).toBe("PT0S");
+        expect(event.data.status).toBe("confirmed");
+        expect(event.data.created).toBe("2026-02-01T00:00:00Z");
+        expect(event.data.descriptionContentType).toBe("text/plain");
+        expect(event.data.showWithoutTime).toBe(false);
+        expect(event.data.freeBusyStatus).toBe("busy");
+        expect(event.data.privacy).toBe("public");
+        expect(event.data.useDefaultAlerts).toBe(false);
+        expect(event.data.excluded).toBe(false);
+        expect(event.data.timeZone).toBeUndefined();
+    });
+    it("throws when required fields are missing", () => {
+        expect(() => {
+            // @ts-expect-error start is required
+            new JsCal.Event({ title: "Missing start" }, { now: fixedNow });
+        }).toThrow(/Event.start/);
+    });
+    it("accepts explicit @type", () => {
+        const event = new JsCal.Event({ start: "2026-02-02T10:00:00" }, { now: fixedNow });
+        expect(event.data["@type"]).toBe("Event");
+    });
+    it("accepts Date for start", () => {
+        const event = new JsCal.Event({ start: new Date("2026-02-02T10:00:00") }, { now: fixedNow });
+        expect(event.data.start).toBe("2026-02-02T10:00:00");
+    });
+    it("does not set timeZone when missing", () => {
+        const event = new JsCal.Event({ start: new Date("2026-02-02T10:00:00") }, { now: fixedNow });
+        expect(event.data.timeZone).toBeUndefined();
+    });
+    it("accepts duration in seconds", () => {
+        const event = new JsCal.Event({ start: new Date("2026-02-02T10:00:00"), duration: 3600 }, { now: fixedNow });
+        expect(event.data.duration).toBe("PT1H");
+    });
+    it("handles duration boundaries", () => {
+        const zero = new JsCal.Event({ start: new Date("2026-02-02T10:00:00"), duration: 0 }, { now: fixedNow });
+        expect(zero.data.duration).toBe("PT0S");
+        const seconds = new JsCal.Event({ start: new Date("2026-02-02T10:00:00"), duration: 59 }, { now: fixedNow });
+        expect(seconds.data.duration).toBe("PT59S");
+        const negative = new JsCal.Event({ start: new Date("2026-02-02T10:00:00"), duration: -1 }, { now: fixedNow });
+        expect(negative.data.duration).toBe("PT0S");
+    });
+});
+describe("Event.update", () => {
+    it("increments sequence on non-participant updates", () => {
+        const event = makeEvent();
+        event.update({ title: "Updated" }, { now: fixedNow });
+        expect(event.data.sequence).toBe(1);
+    });
+    it("does not increment sequence when only participants change", () => {
+        const event = makeEvent();
+        const initialSequence = event.data.sequence ?? 0;
+        event.addParticipant({ roles: { attendee: true }, email: "a@example.com" });
+        expect(event.data.sequence ?? 0).toBe(initialSequence);
+    });
+    it("respects touch=false", () => {
+        const event = makeEvent();
+        const before = event.data.updated;
+        event.update({ title: "No touch" }, { touch: false, now: () => "2026-02-02T00:00:00Z" });
+        expect(event.data.updated).toBe(before);
+    });
+});
+describe("Event.patch", () => {
+    it("applies patch and updates metadata", () => {
+        const event = makeEvent();
+        event.patch({ title: "Patched" }, { now: fixedNow });
+        expect(event.data.title).toBe("Patched");
+        expect(event.data.updated).toBe("2026-02-01T00:00:00Z");
+        expect(event.data.sequence).toBe(1);
+    });
+    it("does not increment sequence for participants-only patch", () => {
+        const event = makeEvent();
+        event.patch({
+            participants: {
+                p1: {
+                    "@type": "Participant",
+                    roles: { attendee: true },
+                },
+            },
+        }, { now: fixedNow });
+        expect(event.data.sequence ?? 0).toBe(0);
+    });
+});
+describe("createUid", () => {
+    it("generates unique-ish id format", () => {
+        const uid = createUid();
+        expect(uid).toMatch(/^[0-9a-f-]{36}$/);
+    });
+});

package/dist/__tests__/ical-extra.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/ical-extra.test.js

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { JsCal } from "../jscal.js";
+const task = {
+    "@type": "Task",
+    uid: "t1",
+    updated: "2026-02-01T00:00:00Z",
+    title: "Write notes",
+    description: "Prepare summary",
+    sequence: 1,
+    start: "2026-02-02T09:00:00",
+    due: "2026-02-02T17:00:00",
+    timeZone: "America/Los_Angeles",
+    percentComplete: 50,
+    progress: "in-process",
+};
+const group = {
+    "@type": "Group",
+    uid: "g1",
+    updated: "2026-02-01T00:00:00Z",
+    title: "Group",
+    entries: [task],
+};
+const event = {
+    "@type": "Event",
+    uid: "e2",
+    updated: "2026-02-01T00:00:00Z",
+    title: "Planning",
+    start: "2026-02-03T09:00:00",
+};
+const taskWithMethod = {
+    "@type": "Task",
+    uid: "t2",
+    updated: "2026-02-01T00:00:00Z",
+    title: "Method test",
+    method: "request",
+};
+const taskWithoutTimeZone = {
+    "@type": "Task",
+    uid: "t3",
+    updated: "2026-02-01T00:00:00Z",
+    title: "No TZ",
+    start: "2026-02-05T09:00:00",
+    due: "2026-02-05T17:00:00",
+};
+describe("toICal extras", () => {
+    it("exports VTODO with key fields", () => {
+        const ical = JsCal.toICal([task], { includeXJSCalendar: false });
+        expect(ical).toContain("BEGIN:VTODO");
+        expect(ical).toContain("UID:t1");
+        expect(ical).toContain("DTSTART;TZID=America/Los_Angeles:20260202T090000");
+        expect(ical).toContain("DUE;TZID=America/Los_Angeles:20260202T170000");
+        expect(ical).toContain("PERCENT-COMPLETE:50");
+        expect(ical).toContain("STATUS:IN-PROCESS");
+    });
+    it("exports group as VCALENDAR with entries", () => {
+        const ical = JsCal.toICal([group], { includeXJSCalendar: true });
+        expect(ical).toContain("BEGIN:VCALENDAR");
+        expect(ical).toContain("X-JSCALENDAR-GROUP:");
+        expect(ical).toContain("BEGIN:VTODO");
+    });
+    it("exports mixed arrays (group + event + task)", () => {
+        const ical = JsCal.toICal([group, event, task]);
+        expect(ical).toContain("BEGIN:VEVENT");
+        expect(ical).toContain("BEGIN:VTODO");
+    });
+    it("uses method from first object that defines it", () => {
+        const ical = JsCal.toICal([event, taskWithMethod]);
+        expect(ical).toContain("METHOD:REQUEST");
+    });
+    it("exports VTODO without time zone parameters", () => {
+        const ical = JsCal.toICal([taskWithoutTimeZone], { includeXJSCalendar: false });
+        expect(ical).toContain("DTSTART:20260205T090000");
+        expect(ical).toContain("DUE:20260205T170000");
+    });
+    it("ignores unknown object types", () => {
+        const unknownObject = {
+            "@type": "Unknown",
+            uid: "x1",
+            updated: "2026-02-01T00:00:00Z",
+        };
+        // @ts-expect-error unknown object type
+        const ical = JsCal.toICal([unknownObject], { includeXJSCalendar: false });
+        expect(ical).toContain("BEGIN:VCALENDAR");
+        expect(ical).not.toContain("BEGIN:VEVENT");
+        expect(ical).not.toContain("BEGIN:VTODO");
+    });
+});