@wtfalch/calendar 0.1.0

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 (42) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +15 -0
  3. package/dist/calendar/calendar-client.d.ts +7 -0
  4. package/dist/calendar/calendar-client.js +242 -0
  5. package/dist/calendar/calendar.css +953 -0
  6. package/dist/calendar/client.d.ts +87 -0
  7. package/dist/calendar/client.js +233 -0
  8. package/dist/calendar/errors.d.ts +28 -0
  9. package/dist/calendar/errors.js +61 -0
  10. package/dist/calendar/fake/index.d.ts +36 -0
  11. package/dist/calendar/fake/index.js +79 -0
  12. package/dist/calendar/fake/sample.d.ts +66 -0
  13. package/dist/calendar/fake/sample.js +116 -0
  14. package/dist/calendar/fake/store.d.ts +79 -0
  15. package/dist/calendar/fake/store.js +906 -0
  16. package/dist/calendar/index.d.ts +12 -0
  17. package/dist/calendar/index.js +11 -0
  18. package/dist/calendar/push.d.ts +38 -0
  19. package/dist/calendar/push.js +129 -0
  20. package/dist/calendar/react/AvailabilityRibbon.d.ts +40 -0
  21. package/dist/calendar/react/AvailabilityRibbon.js +108 -0
  22. package/dist/calendar/react/Calendar.d.ts +28 -0
  23. package/dist/calendar/react/Calendar.js +431 -0
  24. package/dist/calendar/react/EventDetail.d.ts +22 -0
  25. package/dist/calendar/react/EventDetail.js +91 -0
  26. package/dist/calendar/react/EventEditor.d.ts +52 -0
  27. package/dist/calendar/react/EventEditor.js +188 -0
  28. package/dist/calendar/react/ShareDialog.d.ts +25 -0
  29. package/dist/calendar/react/ShareDialog.js +125 -0
  30. package/dist/calendar/react/Toolbar.d.ts +29 -0
  31. package/dist/calendar/react/Toolbar.js +58 -0
  32. package/dist/calendar/react/index.d.ts +9 -0
  33. package/dist/calendar/react/index.js +8 -0
  34. package/dist/calendar/react/participants.d.ts +34 -0
  35. package/dist/calendar/react/participants.js +40 -0
  36. package/dist/calendar/types.d.ts +384 -0
  37. package/dist/calendar/types.js +40 -0
  38. package/dist/calendar/uri.d.ts +13 -0
  39. package/dist/calendar/uri.js +22 -0
  40. package/dist/calendar/wire.d.ts +177 -0
  41. package/dist/calendar/wire.js +349 -0
  42. package/package.json +82 -0
@@ -0,0 +1,349 @@
1
+ /**
2
+ * The wire <-> public-type mapping. Nothing in `types.ts` (the fixed
3
+ * contract) is JSON-shaped exactly like the JMAP wire, so every method in
4
+ * `calendar-client.ts` goes through here rather than passing server JSON
5
+ * straight through.
6
+ *
7
+ * **What is live-confirmed** (#137, #145; MSG-053 acceptance criteria):
8
+ * `recurrenceRule` is singular (one object, not RFC 8984's plural
9
+ * `recurrenceRules`); a participant's address property is `calendarAddress`,
10
+ * not RFC 8984's `email`; `shareWith`/`myRights` are objects keyed by
11
+ * `CalendarRight` name with boolean values (`shareWith:{"d":{mayReadItems:
12
+ * true,...}}}`, #145 check 4); `busyStatus` on a `Principal/getAvailability`
13
+ * result is a lowercase string (`"confirmed"`, #145 check 5); `participants`
14
+ * is a map keyed by an arbitrary id, not an array (`CalendarEvent/set update
15
+ * {"participants/bob/participationStatus":...}`, #145 check 3); an expanded
16
+ * occurrence carries a `baseEventId` back-reference (#145 check 2).
17
+ *
18
+ * **The rest is now live-confirmed too** (MSG-055, Stalwart v0.16.20). Every
19
+ * name this file had guessed from RFC 8984 came back verbatim off a real
20
+ * `CalendarEvent/get`: `title`, `start`, `timeZone`, `duration`, `status`,
21
+ * `uid`, the all-day flag as `showWithoutTime` (not `isAllDay`), `locations`
22
+ * as a map of `Location` objects (`{"main":{"name":"...","@type":"Location"}}`),
23
+ * `roles` as a map of booleans (`{"owner":true,"chair":true}`), and
24
+ * `recurrenceId` on an expanded occurrence alongside `baseEventId`. The
25
+ * response `availability.test.ts` pins is the transcript this paragraph
26
+ * describes.
27
+ *
28
+ * **Two things the live run changed.** `Principal/getAvailability` does not
29
+ * use any of the names guessed for it -- see `WireBusyPeriod` below. And
30
+ * `recurrenceId`/`baseEventId` are returned only when named explicitly in
31
+ * `properties`; a `get` with no filter omits both. `EVENT_GET_PROPERTIES`
32
+ * already names them, so the client is unaffected, but a caller who asks for
33
+ * "everything" gets less than a caller who asks for a list.
34
+ *
35
+ * **Still open: `sequence`.** The server accepts the name -- asking for it is
36
+ * not an `invalidProperties` error -- but no response in the run ever carried
37
+ * a value, not even `0`, including after an update. `eventFromWire` defaults
38
+ * it to `0`, which is the safe reading either way.
39
+ *
40
+ * **Returned by Stalwart and deliberately unmapped**, because no public type
41
+ * needs them yet: `organizerCalendarAddress`, `recurrenceIdTimeZone`,
42
+ * `updated`, `isDraft`, `isOrigin`.
43
+ */
44
+ // ---------------------------------------------------------------------------
45
+ // Rights: array (public) <-> boolean-keyed object (wire)
46
+ // ---------------------------------------------------------------------------
47
+ const ALL_RIGHTS = [
48
+ 'mayReadFreeBusy',
49
+ 'mayReadItems',
50
+ 'mayWriteAll',
51
+ 'mayWriteOwn',
52
+ 'mayUpdatePrivate',
53
+ 'mayRSVP',
54
+ 'mayShare',
55
+ 'mayDelete',
56
+ ];
57
+ export function rightsFromWire(wire) {
58
+ if (!wire)
59
+ return [];
60
+ return ALL_RIGHTS.filter((right) => wire[right] === true);
61
+ }
62
+ export function rightsToWire(rights) {
63
+ const wire = {};
64
+ for (const right of rights)
65
+ wire[right] = true;
66
+ return wire;
67
+ }
68
+ function shareWithFromWire(wire) {
69
+ if (!wire)
70
+ return [];
71
+ return Object.entries(wire).map(([accountId, rights]) => ({
72
+ accountId,
73
+ rights: rightsFromWire(rights),
74
+ }));
75
+ }
76
+ export function calendarFromWire(wire) {
77
+ return {
78
+ id: wire.id,
79
+ name: wire.name,
80
+ description: wire.description ?? undefined,
81
+ color: wire.color ?? undefined,
82
+ isVisible: wire.isVisible ?? true,
83
+ myRights: rightsFromWire(wire.myRights),
84
+ shareWith: shareWithFromWire(wire.shareWith),
85
+ // Cast rather than validated: an unrecognized value from a future server
86
+ // revision should not crash the list, and `types.ts` fixes the union.
87
+ includeInAvailability: (wire.includeInAvailability ??
88
+ 'none'),
89
+ };
90
+ }
91
+ export const CALENDAR_GET_PROPERTIES = [
92
+ 'id',
93
+ 'name',
94
+ 'description',
95
+ 'color',
96
+ 'isVisible',
97
+ 'myRights',
98
+ 'shareWith',
99
+ 'includeInAvailability',
100
+ ];
101
+ /** `description` carries the friendly display name ("Bob"); the wire's own
102
+ * `name` field carries the address again, so `description` is preferred and
103
+ * `name` is only the fallback. */
104
+ export function principalFromWire(wire) {
105
+ return {
106
+ accountId: wire.id,
107
+ email: wire.email ?? '',
108
+ name: wire.description ?? wire.name ?? undefined,
109
+ };
110
+ }
111
+ function participantFromWire(wire) {
112
+ const roleKeys = wire.roles
113
+ ? Object.keys(wire.roles).filter((role) => wire.roles?.[role] === true)
114
+ : [];
115
+ const roles = roleKeys.length > 0 ? roleKeys : undefined;
116
+ return {
117
+ calendarAddress: wire.calendarAddress,
118
+ name: wire.name ?? undefined,
119
+ roles,
120
+ participationStatus: wire.participationStatus
121
+ ? wire.participationStatus
122
+ : undefined,
123
+ };
124
+ }
125
+ function participantToWire(participant) {
126
+ const roles = participant.roles?.length
127
+ ? Object.fromEntries(participant.roles.map((role) => [role, true]))
128
+ : undefined;
129
+ return {
130
+ '@type': 'Participant',
131
+ calendarAddress: participant.calendarAddress,
132
+ ...(participant.name === undefined ? {} : { name: participant.name }),
133
+ ...(roles === undefined ? {} : { roles }),
134
+ ...(participant.participationStatus === undefined
135
+ ? {}
136
+ : { participationStatus: participant.participationStatus }),
137
+ };
138
+ }
139
+ function participantsFromWire(wire) {
140
+ if (!wire)
141
+ return undefined;
142
+ const list = Object.values(wire).map(participantFromWire);
143
+ return list.length > 0 ? list : undefined;
144
+ }
145
+ /** Wire participant ids are arbitrary and never read back (the contract has
146
+ * no participant-id field): a stable per-call index is all a create/update
147
+ * needs. */
148
+ function participantsToWire(participants) {
149
+ if (!participants)
150
+ return undefined;
151
+ return Object.fromEntries(participants.map((p, i) => [`p${i}`, participantToWire(p)]));
152
+ }
153
+ function locationFromWire(wire) {
154
+ if (!wire)
155
+ return undefined;
156
+ const first = Object.values(wire)[0];
157
+ return first?.name ?? undefined;
158
+ }
159
+ function locationToWire(location) {
160
+ if (location === undefined)
161
+ return undefined;
162
+ return { main: { '@type': 'Location', name: location } };
163
+ }
164
+ function recurrenceRuleFromWire(wire) {
165
+ if (!wire)
166
+ return undefined;
167
+ return {
168
+ // `types.ts` fixes the frequency union; a value outside it is a server
169
+ // extension this contract has no room for, not something to crash on.
170
+ frequency: wire.frequency,
171
+ interval: wire.interval ?? undefined,
172
+ count: wire.count ?? undefined,
173
+ until: wire.until ?? undefined,
174
+ };
175
+ }
176
+ function recurrenceRuleToWire(rule) {
177
+ if (!rule)
178
+ return undefined;
179
+ return {
180
+ '@type': 'RecurrenceRule',
181
+ frequency: rule.frequency,
182
+ ...(rule.interval === undefined ? {} : { interval: rule.interval }),
183
+ ...(rule.count === undefined ? {} : { count: rule.count }),
184
+ ...(rule.until === undefined ? {} : { until: rule.until }),
185
+ };
186
+ }
187
+ /** The event properties this package asks the server for. Naming them
188
+ * explicitly, rather than omitting `properties` for "everything", keeps a
189
+ * server-side addition from silently changing what `wireEventFromWire`
190
+ * has to cope with. */
191
+ export const EVENT_GET_PROPERTIES = [
192
+ 'id',
193
+ 'calendarIds',
194
+ 'uid',
195
+ 'title',
196
+ 'description',
197
+ 'start',
198
+ 'timeZone',
199
+ 'duration',
200
+ 'showWithoutTime',
201
+ 'locations',
202
+ 'recurrenceRule',
203
+ 'participants',
204
+ 'status',
205
+ 'sequence',
206
+ 'baseEventId',
207
+ 'recurrenceId',
208
+ ];
209
+ /** `calendarId` is a fallback for a freshly created event whose response
210
+ * echoes only server-assigned properties; the caller already knows which
211
+ * calendar it asked for. */
212
+ export function eventFromWire(wire, calendarIdFallback) {
213
+ const calendarIds = wire.calendarIds ? Object.keys(wire.calendarIds) : [];
214
+ const calendarId = calendarIds[0] ?? calendarIdFallback;
215
+ if (calendarId === undefined) {
216
+ throw new Error(`event ${wire.id} carries no calendarIds and no fallback was given`);
217
+ }
218
+ return {
219
+ id: wire.id,
220
+ calendarId,
221
+ uid: wire.uid,
222
+ title: wire.title,
223
+ description: wire.description ?? undefined,
224
+ start: wire.start,
225
+ timeZone: wire.timeZone ?? null,
226
+ duration: wire.duration,
227
+ isAllDay: wire.showWithoutTime ?? false,
228
+ location: locationFromWire(wire.locations),
229
+ recurrenceRule: recurrenceRuleFromWire(wire.recurrenceRule),
230
+ participants: participantsFromWire(wire.participants),
231
+ status: (wire.status ?? 'confirmed'),
232
+ sequence: wire.sequence ?? 0,
233
+ recurrenceId: wire.recurrenceId ?? undefined,
234
+ baseEventId: wire.baseEventId ?? undefined,
235
+ };
236
+ }
237
+ /** The properties a create sends: everything `CalendarEventDraft` carries,
238
+ * translated to their wire names. */
239
+ export function draftToWire(calendarId, draft) {
240
+ return {
241
+ '@type': 'Event',
242
+ calendarIds: { [calendarId]: true },
243
+ uid: draft.uid,
244
+ title: draft.title,
245
+ ...(draft.description === undefined ? {} : { description: draft.description }),
246
+ start: draft.start,
247
+ timeZone: draft.timeZone,
248
+ duration: draft.duration,
249
+ showWithoutTime: draft.isAllDay,
250
+ ...(locationToWire(draft.location) ? { locations: locationToWire(draft.location) } : {}),
251
+ ...(recurrenceRuleToWire(draft.recurrenceRule)
252
+ ? { recurrenceRule: recurrenceRuleToWire(draft.recurrenceRule) }
253
+ : {}),
254
+ ...(participantsToWire(draft.participants)
255
+ ? { participants: participantsToWire(draft.participants) }
256
+ : {}),
257
+ status: draft.status,
258
+ };
259
+ }
260
+ /** Only the properties `patch` actually carries -- `CalendarEvent/set`'s
261
+ * `update` is a genuine patch, and a field the caller did not mention must
262
+ * not be overwritten with `undefined`. */
263
+ export function patchToWire(patch) {
264
+ const wire = {};
265
+ if (patch.calendarId !== undefined)
266
+ wire.calendarIds = { [patch.calendarId]: true };
267
+ if (patch.uid !== undefined)
268
+ wire.uid = patch.uid;
269
+ if (patch.title !== undefined)
270
+ wire.title = patch.title;
271
+ if (patch.description !== undefined)
272
+ wire.description = patch.description;
273
+ if (patch.start !== undefined)
274
+ wire.start = patch.start;
275
+ if (patch.timeZone !== undefined)
276
+ wire.timeZone = patch.timeZone;
277
+ if (patch.duration !== undefined)
278
+ wire.duration = patch.duration;
279
+ if (patch.isAllDay !== undefined)
280
+ wire.showWithoutTime = patch.isAllDay;
281
+ if (patch.location !== undefined)
282
+ wire.locations = locationToWire(patch.location);
283
+ if (patch.recurrenceRule !== undefined) {
284
+ wire.recurrenceRule = recurrenceRuleToWire(patch.recurrenceRule);
285
+ }
286
+ if (patch.participants !== undefined)
287
+ wire.participants = participantsToWire(patch.participants);
288
+ if (patch.status !== undefined)
289
+ wire.status = patch.status;
290
+ return wire;
291
+ }
292
+ // ---------------------------------------------------------------------------
293
+ // Availability
294
+ // ---------------------------------------------------------------------------
295
+ /**
296
+ * A minimal ISO 8601 / RFC 5545 duration parser: `P`, an optional week or
297
+ * day count, an optional `T` time part with hours/minutes/seconds. Years and
298
+ * months are deliberately not handled -- a busy period is never months
299
+ * long, and a calendar-aware year/month addition needs a timezone this
300
+ * function does not have. Returns `null` rather than throwing: one
301
+ * unparseable duration should not take down a whole availability read.
302
+ *
303
+ * Exported for `./react`'s own use turning an event's `duration` into a grid
304
+ * end time (`Calendar.tsx`) -- the same parser, not a second one that could
305
+ * drift from this one's idea of what a duration string means.
306
+ */
307
+ export function parseDurationMs(duration) {
308
+ const match = /^P(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/.exec(duration);
309
+ if (!match)
310
+ return null;
311
+ const [, weeks, days, hours, minutes, seconds] = match;
312
+ if (!weeks && !days && !hours && !minutes && !seconds)
313
+ return null;
314
+ const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
315
+ const DAY_MS = 24 * 60 * 60 * 1000;
316
+ const HOUR_MS = 60 * 60 * 1000;
317
+ const MINUTE_MS = 60 * 1000;
318
+ return (Number(weeks ?? 0) * WEEK_MS +
319
+ Number(days ?? 0) * DAY_MS +
320
+ Number(hours ?? 0) * HOUR_MS +
321
+ Number(minutes ?? 0) * MINUTE_MS +
322
+ Number(seconds ?? 0) * 1000);
323
+ }
324
+ /**
325
+ * `Principal/getAvailability` returns a busy period as `utcStart`/`utcEnd`,
326
+ * both always present, both already UTC -- confirmed live against Stalwart
327
+ * v0.16.20 for MSG-055:
328
+ *
329
+ * ```json
330
+ * {"utcStart":"2026-10-05T13:00:00Z","utcEnd":"2026-10-05T14:00:00Z",
331
+ * "busyStatus":"confirmed","event":null}
332
+ * ```
333
+ *
334
+ * This is neither of the two shapes the earlier guess handled: there is no
335
+ * `start`, no `end` and no `duration` on the wire at all. Reading the old
336
+ * names produced an undefined start and an end derived from it, so every
337
+ * real busy period arrived as garbage.
338
+ *
339
+ * `event` rides along and was `null` for every period in the transcript.
340
+ * Nothing reads it yet; it is typed so a later reader does not have to widen
341
+ * the type to find out it exists.
342
+ */
343
+ export function availabilityFromWire(list) {
344
+ return list.map((period) => ({
345
+ start: period.utcStart,
346
+ end: period.utcEnd,
347
+ busyStatus: (period.busyStatus ?? 'confirmed'),
348
+ }));
349
+ }
package/package.json ADDED
@@ -0,0 +1,82 @@
1
+ {
2
+ "name": "@wtfalch/calendar",
3
+ "version": "0.1.0",
4
+ "description": "A JMAP calendar client for Agora, the wtfalch communications app: events, invites, sharing and free/busy over Stalwart, and the React UI on react-big-calendar.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/wtfalch/calendar.git",
10
+ "directory": "packages/calendar"
11
+ },
12
+ "exports": {
13
+ "./calendar": {
14
+ "types": "./dist/calendar/index.d.ts",
15
+ "default": "./dist/calendar/index.js"
16
+ },
17
+ "./calendar/react": {
18
+ "types": "./dist/calendar/react/index.d.ts",
19
+ "default": "./dist/calendar/react/index.js"
20
+ },
21
+ "./calendar/fake": {
22
+ "types": "./dist/calendar/fake/index.d.ts",
23
+ "default": "./dist/calendar/fake/index.js"
24
+ },
25
+ "./calendar/calendar.css": "./dist/calendar/calendar.css",
26
+ "./package.json": "./package.json"
27
+ },
28
+ "files": ["dist", "LICENSE", "README.md"],
29
+ "dependencies": {
30
+ "dayjs": "^1.11.13"
31
+ },
32
+ "scripts": {
33
+ "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/calendar/react/calendar.css dist/calendar/calendar.css && cp ../../LICENSE ../../README.md .",
34
+ "prepack": "pnpm build",
35
+ "typecheck": "tsc --noEmit",
36
+ "test": "vitest run",
37
+ "dev": "vite --config dev/vite.config.ts"
38
+ },
39
+ "peerDependencies": {
40
+ "@wtfalch/design": "0.21.0",
41
+ "react": "^19.0.0",
42
+ "react-big-calendar": "^1.20.0",
43
+ "react-dom": "^19.0.0"
44
+ },
45
+ "peerDependenciesMeta": {
46
+ "@wtfalch/design": {
47
+ "optional": true
48
+ },
49
+ "react": {
50
+ "optional": true
51
+ },
52
+ "react-dom": {
53
+ "optional": true
54
+ },
55
+ "react-big-calendar": {
56
+ "optional": true
57
+ }
58
+ },
59
+ "devDependencies": {
60
+ "@types/node": "^22",
61
+ "@types/react": "^19",
62
+ "@types/react-big-calendar": "^1.16.3",
63
+ "@types/react-dom": "^19",
64
+ "@vitejs/plugin-react": "^6.1.1",
65
+ "@wtfalch/design": "0.21.0",
66
+ "jsdom": "^30.0.1",
67
+ "react": "^19",
68
+ "react-big-calendar": "^1.20.0",
69
+ "react-dom": "^19",
70
+ "typescript": "^5.9.0",
71
+ "vite": "^8.3.0",
72
+ "vitest": "^4.1.6"
73
+ },
74
+ "sideEffects": ["**/*.css"],
75
+ "publishConfig": {
76
+ "access": "public"
77
+ },
78
+ "engines": {
79
+ "node": ">=22.0.0"
80
+ },
81
+ "keywords": ["jmap", "calendar", "stalwart", "jscalendar"]
82
+ }