calendaryjs-plugin-ics 0.1.1 โ†’ 0.1.2

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.
Files changed (2) hide show
  1. package/README.md +33 -74
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,103 +1,62 @@
1
- # calendaryjs-plugin-ics
2
-
3
- ICS (RFC 5545) export for [calendaryjs](https://www.npmjs.com/package/calendaryjs). Turn generated calendar occurrences into a standard `.ics` `VCALENDAR` that Apple Calendar, Google Calendar, Outlook and anything else can subscribe to.
1
+ <p align="center">
2
+ <img src="https://cdn.jsdelivr.net/npm/calendaryjs/assets/logo.svg" alt="calendaryjs" width="380" />
3
+ </p>
4
4
 
5
- It is an **edge integration**: calendaryjs owns the calendar core; this package only serializes its plain output. It adds **zero runtime dependency** to the core and works on any plain object shaped like a `CalendarEvent`.
5
+ # calendaryjs-plugin-ics
6
6
 
7
- ## Features
7
+ > **New to calendaryjs?** Start with the [core README](https://www.npmjs.com/package/calendaryjs) โ€” this plugin serializes its output.
8
8
 
9
- - **๐Ÿ“ค One VEVENT per occurrence** โ€” events come in already expanded, so no `RRULE` is emitted. Lunar / hijri / formula dates and per-occurrence `exceptions` & `overrideDates` (already applied by the core) all export correctly.
10
- - **โฐ Reminders โ†’ `VALARM`** โ€” each lead-time reminder becomes a relative-trigger alarm (`DISPLAY` or `EMAIL`).
11
- - **๐Ÿ”ข Priority โ†’ `PRIORITY`** โ€” calendaryjs `priority` (CSS `z-index`: higher = on top) is inverted into ICS `PRIORITY` (1 = highest), with a pluggable mapper.
12
- - **๐ŸŽจ Display fields** โ€” `DESCRIPTION`, `LOCATION`, `URL`, `CATEGORIES`, `STATUS`, plus RFC 7986 `COLOR` / `IMAGE`.
13
- - **โœ… Spec-correct output** โ€” CRLF line endings, octet-aware line folding (75-octet, no multi-byte splits), RFC 5545 text escaping.
14
- - **๐Ÿงช Deterministic** โ€” pass a fixed `dtstamp` for byte-stable, diff-friendly files.
9
+ Turn generated calendar occurrences into a standard `.ics` `VCALENDAR` that Apple
10
+ Calendar, Google Calendar, Outlook and anything else can subscribe to. An **edge
11
+ integration** โ€” calendaryjs owns the calendar core; this only serializes its plain
12
+ output, with **zero runtime dependency**.
15
13
 
16
- ## Installation
14
+ ## Install
17
15
 
18
16
  ```bash
19
- pnpm add calendaryjs calendaryjs-plugin-ics
17
+ npm i calendaryjs calendaryjs-plugin-ics
20
18
  ```
21
19
 
22
- ## Requirements
23
-
24
- - `calendaryjs` >= 0.1.0
20
+ ## Use it
25
21
 
26
- ## Quick Start
22
+ Generate occurrences with calendaryjs, then pass them to `toICS()`:
27
23
 
28
- ```typescript
24
+ ```ts
29
25
  import { calendary } from "calendaryjs";
26
+ import { every, date } from "calendaryjs/builder";
30
27
  import { toICS } from "calendaryjs-plugin-ics";
31
28
 
32
29
  const cal = calendary();
33
30
  cal.addGroup({
34
31
  id: "holidays",
35
- name: "Holidays",
36
- events: [
37
- { type: "const", id: "newyear", month: 1, day: 1, title: "New Year" },
38
- { type: "const", id: "christmas", month: 12, day: 25, title: "Christmas" },
39
- ],
32
+ events: [every("year").on(date(12, 25)).title("Christmas")],
40
33
  });
41
34
 
42
- const events = cal.getEventsInRange("2025-01-01", "2025-12-31");
35
+ const events = cal.getEventsInRange("2026-01-01", "2026-12-31");
43
36
  const ics = toICS(events, { calendarName: "Holidays" });
44
-
45
- // โ†’ write `ics` to a .ics file, or serve it from an endpoint
37
+ // โ†’ a VCALENDAR string: write to a .ics file or serve it from an endpoint
46
38
  ```
47
39
 
48
- ## API
49
-
50
- ### `toICS(events, options?) โ†’ string`
40
+ One `VEVENT` per occurrence (events come pre-expanded, so no `RRULE`) โ€” lunar / hijri /
41
+ formula dates and per-occurrence `exceptions` & `overrideDates` all export correctly.
42
+ Reminders โ†’ `VALARM`, `priority` โ†’ `PRIORITY`, plus `DESCRIPTION` / `LOCATION` / `URL` /
43
+ `CATEGORIES` / `COLOR`.
51
44
 
52
- Serialize an array of occurrences into a full `VCALENDAR` document.
45
+ ## Reference
53
46
 
54
- ```typescript
55
- interface ICSOptions {
56
- prodId?: string; // PRODID. Default "-//calendaryjs//calendaryjs-plugin-ics//EN"
57
- calendarName?: string; // X-WR-CALNAME โ€” the calendar's display name
58
- method?: string; // METHOD, e.g. "PUBLISH"
59
- dtstamp?: Date; // DTSTAMP for every event. Default: now (pass a fixed Date for stable output)
60
- priorityMap?: (priority: number) => number; // override priority โ†’ ICS PRIORITY (return 0 to omit)
61
- }
47
+ ```ts
48
+ toICS(events, options?) โ†’ string; // a full VCALENDAR document
62
49
  ```
63
50
 
64
- ### `eventToVEvent(event, options?) โ†’ string`
65
-
66
- Serialize a single occurrence to one folded `VEVENT` block (no `VCALENDAR` wrapper).
67
-
68
- Also exported: `veventLines` (unfolded lines), `defaultPriorityMap`, and the low-level `escapeText` / `foldLine` helpers.
69
-
70
- ## Field mapping
71
-
72
- | calendaryjs | ICS |
73
- | ---------------------------------- | ----------------------------------------- |
74
- | `date` + `startTime`/`endTime` | `DTSTART` / `DTEND` (floating local time) |
75
- | `date` (all-day / no time) | `DTSTART;VALUE=DATE` + exclusive `DTEND` |
76
- | `duration` (minutes) | `DURATION` (when `endTime` is absent) |
77
- | `title` | `SUMMARY` |
78
- | `description` / `location` / `url` | `DESCRIPTION` / `LOCATION` / `URL` |
79
- | `categories` / `status` | `CATEGORIES` / `STATUS` |
80
- | `priority` (z-index) | `PRIORITY` (inverted, 1 = highest) |
81
- | `color` / `icon` | `COLOR` / `IMAGE` (RFC 7986) |
82
- | `reminders[]` (minutes before) | `VALARM` with `TRIGGER:-PTnM` |
83
- | `source` / `groupId` / id + `date` | a stable, unique `UID` |
84
-
85
- ### Notes
86
-
87
- - **Timezones.** Timed events export as **floating local time** (no `Z`, no `TZID`) โ€” the core stays timezone-neutral, so occurrences render in the viewer's local zone.
88
- - **Reminder & duration units** are **minutes**.
89
- - **`exceptions` / `overrideDates`** are resolved by the core before export (skipped occurrences are already gone, overrides already applied), so no `EXDATE` / `RECURRENCE-ID` is needed for the per-occurrence form.
90
-
91
- ## Roadmap
92
-
93
- - `RRULE` compaction for Gregorian-expressible recurrences (with `EXDATE` / `RECURRENCE-ID` for exceptions).
94
- - ICS **import** (`.ics` โ†’ event configs).
95
-
96
- ## Related Packages
51
+ | Option | Notes |
52
+ | -------------- | ----------------------------------------------------- |
53
+ | `prodId` | `PRODID` |
54
+ | `calendarName` | `X-WR-CALNAME` โ€” the calendar's display name |
55
+ | `method` | `METHOD`, e.g. `"PUBLISH"` |
56
+ | `dtstamp` | fixed `Date` โ†’ byte-stable, diff-friendly output |
57
+ | `priorityMap` | override priority โ†’ ICS `PRIORITY` (return 0 to omit) |
97
58
 
98
- - [calendaryjs](https://www.npmjs.com/package/calendaryjs) โ€” core engine
99
- - [calendaryjs-plugin-lunar](https://www.npmjs.com/package/calendaryjs-plugin-lunar) โ€” lunar calendar
100
- - [calendaryjs-plugin-liturgical](https://www.npmjs.com/package/calendaryjs-plugin-liturgical) โ€” liturgical calendar
59
+ Also exported: `eventToVEvent(event, options?)` โ€” a single `VEVENT` block (no wrapper).
101
60
 
102
61
  ## License
103
62
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "calendaryjs-plugin-ics",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "ICS (RFC 5545) export for calendaryjs โ€” serialize generated calendar occurrences to a standard .ics VCALENDAR (VEVENT, VALARM reminders, PRIORITY, CATEGORIES, COLOR/IMAGE). The edge integration: calendaryjs owns the core, ICS rides at the boundary.",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -39,7 +39,7 @@
39
39
  "devDependencies": {
40
40
  "typescript": "^5.3.2",
41
41
  "vitest": "^4.0.18",
42
- "calendaryjs": "0.2.1"
42
+ "calendaryjs": "0.2.2"
43
43
  },
44
44
  "files": [
45
45
  "dist"