@rokoyfa/calendar 1.2.1 → 1.3.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 (137) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/DEVELOPER_GUIDE.md +312 -10
  3. package/README.md +2 -0
  4. package/api/openapi.yaml +395 -4
  5. package/demo/calendar.config.jsonc +35 -1
  6. package/demo/calendar.config.yaml +34 -0
  7. package/dist-lib/cdn/calendar-widget.js +14 -12
  8. package/dist-lib/cdn/calendar-widget.js.map +1 -1
  9. package/dist-lib/cdn/de-Dqga3QZG.js +2 -0
  10. package/dist-lib/cdn/de-Dqga3QZG.js.map +1 -0
  11. package/dist-lib/cdn/es-BWSfTMjh.js +2 -0
  12. package/dist-lib/cdn/es-BWSfTMjh.js.map +1 -0
  13. package/dist-lib/cdn/fr-N9gwLjVq.js +2 -0
  14. package/dist-lib/cdn/fr-N9gwLjVq.js.map +1 -0
  15. package/dist-lib/cdn/it-B5Ib2xLn.js +2 -0
  16. package/dist-lib/cdn/it-B5Ib2xLn.js.map +1 -0
  17. package/dist-lib/cdn/nl-CjI7Uc8l.js +2 -0
  18. package/dist-lib/cdn/nl-CjI7Uc8l.js.map +1 -0
  19. package/dist-lib/cdn/pl-FRu3yQhc.js +2 -0
  20. package/dist-lib/cdn/pl-FRu3yQhc.js.map +1 -0
  21. package/dist-lib/cdn/pt-DBKJ-3Is.js +2 -0
  22. package/dist-lib/cdn/pt-DBKJ-3Is.js.map +1 -0
  23. package/dist-lib/npm/{de-lDO0Tv9y.js → de-DhWrY8Ae.js} +109 -3
  24. package/dist-lib/npm/de-DhWrY8Ae.js.map +1 -0
  25. package/dist-lib/npm/{es-Cy3Mmj9C.js → es-Bj8leuD5.js} +109 -3
  26. package/dist-lib/npm/es-Bj8leuD5.js.map +1 -0
  27. package/dist-lib/npm/{fr-Ci0ZM0nG.js → fr-DzAFZ0jh.js} +109 -3
  28. package/dist-lib/npm/fr-DzAFZ0jh.js.map +1 -0
  29. package/dist-lib/npm/index.js +3309 -1148
  30. package/dist-lib/npm/index.js.map +1 -1
  31. package/dist-lib/npm/{it-BiTHjgzI.js → it-lEmGP5yo.js} +109 -3
  32. package/dist-lib/npm/it-lEmGP5yo.js.map +1 -0
  33. package/dist-lib/npm/{nl-DZTwpAwV.js → nl-d1h63dvm.js} +109 -3
  34. package/dist-lib/npm/nl-d1h63dvm.js.map +1 -0
  35. package/dist-lib/npm/{pl-DeWLtyMR.js → pl-DynFKadb.js} +109 -3
  36. package/dist-lib/npm/pl-DynFKadb.js.map +1 -0
  37. package/dist-lib/npm/{pt-CaqSW5TJ.js → pt-foL7jDsE.js} +109 -3
  38. package/dist-lib/npm/pt-foL7jDsE.js.map +1 -0
  39. package/dist-lib/npm/types/components/Icons.d.ts +2 -0
  40. package/dist-lib/npm/types/config/routes.d.ts +1 -0
  41. package/dist-lib/npm/types/context/HostBridge.d.ts +38 -0
  42. package/dist-lib/npm/types/context/HostContext.d.ts +15 -0
  43. package/dist-lib/npm/types/data/restDataSource.d.ts +2 -1
  44. package/dist-lib/npm/types/data/tenantDataSource.d.ts +2 -1
  45. package/dist-lib/npm/types/data/types.d.ts +4 -1
  46. package/dist-lib/npm/types/features/attachments/components/AttachmentsField.d.ts +8 -0
  47. package/dist-lib/npm/types/features/attachments/hooks/useAttachments.d.ts +11 -0
  48. package/dist-lib/npm/types/features/attachments/index.d.ts +2 -0
  49. package/dist-lib/npm/types/features/authorization/components/account/DataExportSection.d.ts +1 -0
  50. package/dist-lib/npm/types/features/authorization/hooks/useAuth.d.ts +1 -0
  51. package/dist-lib/npm/types/features/authorization/index.d.ts +1 -0
  52. package/dist-lib/npm/types/features/authorization/repositories/HostTokenAuthRepository.d.ts +1 -0
  53. package/dist-lib/npm/types/features/authorization/repositories/RemoteAuthRepository.d.ts +1 -0
  54. package/dist-lib/npm/types/features/authorization/types/auth.d.ts +2 -0
  55. package/dist-lib/npm/types/features/calendar/components/Calendar.d.ts +7 -1
  56. package/dist-lib/npm/types/features/calendar/components/CalendarHeader.d.ts +3 -1
  57. package/dist-lib/npm/types/features/calendar/hooks/useEventNavigation.d.ts +4 -0
  58. package/dist-lib/npm/types/features/calendar/hooks/useHostController.d.ts +2 -0
  59. package/dist-lib/npm/types/features/calendar/hooks/useLiveEvents.d.ts +11 -0
  60. package/dist-lib/npm/types/features/calendar/hooks/useSegmentAttributes.d.ts +2 -0
  61. package/dist-lib/npm/types/features/calendar/utils/eventLabels.d.ts +4 -0
  62. package/dist-lib/npm/types/features/calendars/components/settings/ShareSection.d.ts +4 -0
  63. package/dist-lib/npm/types/features/calendars/components/settings/TrashSection.d.ts +4 -0
  64. package/dist-lib/npm/types/features/calendars/index.d.ts +1 -1
  65. package/dist-lib/npm/types/features/calendars/repositories/RemoteCalendarRepository.d.ts +3 -0
  66. package/dist-lib/npm/types/features/calendars/types/calendar.d.ts +3 -0
  67. package/dist-lib/npm/types/features/calendars/utils/permissions.d.ts +4 -0
  68. package/dist-lib/npm/types/features/categories/components/CategoriesSection.d.ts +6 -0
  69. package/dist-lib/npm/types/features/categories/components/CategoryField.d.ts +9 -0
  70. package/dist-lib/npm/types/features/categories/components/CategoryFilterModal.d.ts +10 -0
  71. package/dist-lib/npm/types/features/categories/hooks/useCategories.d.ts +9 -0
  72. package/dist-lib/npm/types/features/categories/index.d.ts +4 -0
  73. package/dist-lib/npm/types/features/events/components/DeleteEventModal.d.ts +2 -1
  74. package/dist-lib/npm/types/features/events/components/EventModal.d.ts +11 -3
  75. package/dist-lib/npm/types/features/events/hooks/useEvents.d.ts +4 -1
  76. package/dist-lib/npm/types/features/events/index.d.ts +2 -2
  77. package/dist-lib/npm/types/features/events/utils/icalExchange.d.ts +4 -1
  78. package/dist-lib/npm/types/features/storage/index.d.ts +6 -1
  79. package/dist-lib/npm/types/features/storage/repositories/LocalCategoryRepository.d.ts +14 -0
  80. package/dist-lib/npm/types/features/storage/repositories/LocalEventRepository.d.ts +8 -2
  81. package/dist-lib/npm/types/features/storage/repositories/RemoteAttachmentRepository.d.ts +11 -0
  82. package/dist-lib/npm/types/features/storage/repositories/RemoteCategoryRepository.d.ts +10 -0
  83. package/dist-lib/npm/types/features/storage/repositories/RemoteChatRepository.d.ts +2 -1
  84. package/dist-lib/npm/types/features/storage/repositories/RemoteEventRepository.d.ts +9 -3
  85. package/dist-lib/npm/types/features/storage/repositories/RemoteSharedCalendarRepository.d.ts +9 -0
  86. package/dist-lib/npm/types/features/storage/types/storage.d.ts +30 -2
  87. package/dist-lib/npm/types/features/storage/utils/liveSocket.d.ts +10 -0
  88. package/dist-lib/npm/types/i18n/messages/en/calendar.d.ts +9 -0
  89. package/dist-lib/npm/types/i18n/messages/en/calendars.d.ts +44 -0
  90. package/dist-lib/npm/types/i18n/messages/en/events.d.ts +36 -0
  91. package/dist-lib/npm/types/i18n/messages/en/index.d.ts +97 -1
  92. package/dist-lib/npm/types/i18n/messages/en/settings.d.ts +7 -0
  93. package/dist-lib/npm/types/i18n/messages/index.d.ts +97 -1
  94. package/dist-lib/npm/types/lib/CalendarWidget.d.ts +1 -1
  95. package/dist-lib/npm/types/lib/IsolatedRoot.d.ts +3 -1
  96. package/dist-lib/npm/types/lib/appearance.d.ts +3 -0
  97. package/dist-lib/npm/types/lib/config.d.ts +9 -3
  98. package/dist-lib/npm/types/lib/defaults.d.ts +6 -0
  99. package/dist-lib/npm/types/lib/element.d.ts +11 -1
  100. package/dist-lib/npm/types/lib/handle.d.ts +15 -0
  101. package/dist-lib/npm/types/lib/index.d.ts +4 -2
  102. package/dist-lib/npm/types/lib/options.d.ts +12 -0
  103. package/dist-lib/npm/types/pages/SharedCalendarPage.d.ts +1 -0
  104. package/dist-lib/npm/types/utils/api.d.ts +1 -0
  105. package/dist-lib/npm/types/utils/appError.d.ts +1 -1
  106. package/dist-lib/npm/types/utils/attachment.d.ts +31 -0
  107. package/dist-lib/npm/types/utils/category.d.ts +18 -0
  108. package/dist-lib/npm/types/utils/conflict.d.ts +1 -0
  109. package/dist-lib/npm/types/utils/dataExport.d.ts +13 -0
  110. package/dist-lib/npm/types/utils/event.d.ts +6 -1
  111. package/dist-lib/npm/types/utils/eventChange.d.ts +13 -0
  112. package/dist-lib/npm/types/utils/ical.d.ts +6 -1
  113. package/dist-lib/npm/types/utils/sharedCalendar.d.ts +13 -0
  114. package/dist-lib/npm/types/utils/trash.d.ts +14 -0
  115. package/package.json +1 -1
  116. package/schema/calendar-config.schema.json +65 -0
  117. package/dist-lib/cdn/de-CjkGEfiE.js +0 -2
  118. package/dist-lib/cdn/de-CjkGEfiE.js.map +0 -1
  119. package/dist-lib/cdn/es-BrMRh6bn.js +0 -2
  120. package/dist-lib/cdn/es-BrMRh6bn.js.map +0 -1
  121. package/dist-lib/cdn/fr-Ckr8Uxxd.js +0 -2
  122. package/dist-lib/cdn/fr-Ckr8Uxxd.js.map +0 -1
  123. package/dist-lib/cdn/it-_2BGklYa.js +0 -2
  124. package/dist-lib/cdn/it-_2BGklYa.js.map +0 -1
  125. package/dist-lib/cdn/nl-BykoYBK7.js +0 -2
  126. package/dist-lib/cdn/nl-BykoYBK7.js.map +0 -1
  127. package/dist-lib/cdn/pl-as7f_-F8.js +0 -2
  128. package/dist-lib/cdn/pl-as7f_-F8.js.map +0 -1
  129. package/dist-lib/cdn/pt-BWJIdrI6.js +0 -2
  130. package/dist-lib/cdn/pt-BWJIdrI6.js.map +0 -1
  131. package/dist-lib/npm/de-lDO0Tv9y.js.map +0 -1
  132. package/dist-lib/npm/es-Cy3Mmj9C.js.map +0 -1
  133. package/dist-lib/npm/fr-Ci0ZM0nG.js.map +0 -1
  134. package/dist-lib/npm/it-BiTHjgzI.js.map +0 -1
  135. package/dist-lib/npm/nl-DZTwpAwV.js.map +0 -1
  136. package/dist-lib/npm/pl-DeWLtyMR.js.map +0 -1
  137. package/dist-lib/npm/pt-CaqSW5TJ.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -4,6 +4,20 @@ All notable changes to `@rokoyfa/calendar`. Versions follow [Semantic Versioning
4
4
 
5
5
  ## Unreleased
6
6
 
7
+ - Accessibility: arrow keys, `Home` and `End` move between events, days and month cells are labelled groups, events are announced with time, place, calendar, own response and attachments, and the period title is announced when it changes. Contrast now meets WCAG AA in both themes: darker muted text, no faded days outside the month, and dark text on event colors and the accent in dark mode (`--calendar-on-accent` defaults to dark there)
8
+ - Data export (GDPR Art. 20): a "Data" tab in the settings downloads the user's own data as JSON, from `GET /auth/me/export` when signed in or from the browser storage in local mode. New feature switch `dataExport` and optional `AuthRepository.exportData()`
9
+ - Trash: deleted events stay in the trash of their calendar for 30 days and can be restored in the calendar settings, or deleted for good. Undo after deleting now restores the event with the same id, so attachments and chat are kept. `DELETE /events/:id` moves to the trash, new endpoints `GET /calendars/:id/trash`, `POST /events/:id/restore` and `DELETE /trash/:id`, the trash is its own tab also for the personal calendar (whose settings now have tabs), with 20 entries at a time and a search from 8 entries on, new feature switch `trash` and optional `events.listTrash`, `restore` and `purge` for custom adapters
10
+ - Live updates: changes by other people, or in other tabs, show up at once. The backend sends `event.changed` over the existing WebSocket, and an open dialog says when its event was changed or deleted in the meantime. New feature switch `liveUpdates`, new `restDataSource` option `liveUpdates` and optional `events.subscribe` for custom adapters
11
+ - Protection against editing at the same time: events carry a `version`, saving and deleting send it as `If-Match`, and the backend answers `412` with `eventChanged` when someone else changed the event in the meantime. The dialog then offers to save anyway or to load the current version, and undo no longer overwrites other people's changes. Custom adapters receive the version in `events.update` and `events.remove`
12
+ - Attachments: files can be uploaded to events in the event dialog (also while creating one and by drag and drop), downloaded by everyone who can see the event and deleted by those who may edit it. Events with attachments show a paperclip. New feature switch `attachments`, new endpoints in `api/openapi.yaml`, and events carry `attachmentCount` and `createdBy`
13
+ - Categories per calendar: managed in the calendar settings, assigned in the event dialog, with a filter in the header. Events carry `categoryIds`. New feature switch `categories`
14
+ - Public read-only links: a calendar can be shared with anyone without sign-in, opened at `/shared/:token`. New feature switch `publicLinks`
15
+ - Read-only mode: `readOnly` / `read-only` shows events without letting anyone change them
16
+ - Control from the host page: `goToDate()`, `setView()`, `next()`, `previous()`, `today()`, `openEvent()`, `createEvent()`, `refresh()` and `getState()` on the element and through `ref`, plus `view-change` / `onViewChange`
17
+ - Look and feel: accent color, font, corner radius and more through `--calendar-*` CSS properties or the `appearance` option, and a compact density
18
+ - New REST endpoints for categories and sharing in `api/openapi.yaml`
19
+ - The event dialog has an Appearance tab for color and categories; categories can be created right there. The dialog is 620 px wide on larger screens
20
+ - Categories are exported to `.ics` files as `CATEGORIES` and matched by name on import, creating missing ones when allowed
7
21
  - Every optional feature can be switched off through `features` or `feature-*` attributes: chat, attendees, recurrence, reminders, links, map links, holidays, search, undo, duplicate, shortcuts, subscriptions, import and export, e-mail settings, time zones and custom colors. A feature that is off makes no backend calls, so no WebSocket is opened without chat
8
22
  - `views` limits the views a user can switch between
9
23
  - Configuration file: `config` takes the URL of a JSON or YAML file, or an object, with all serializable options. Props and attributes win over the file. A JSON Schema is included as `@rokoyfa/calendar/config.schema.json`
@@ -16,6 +16,15 @@ Everything you need to put `@rokoyfa/calendar` on your page: embedding, all opti
16
16
  10. [Backend](#10-backend)
17
17
  11. [Event chat](#11-event-chat)
18
18
  12. [Calendar subscriptions](#12-calendar-subscriptions)
19
+ 13. [Categories](#13-categories)
20
+ 14. [Read-only mode and public links](#14-read-only-mode-and-public-links)
21
+ 15. [Controlling the calendar from your page](#15-controlling-the-calendar-from-your-page)
22
+ 16. [Look and feel](#16-look-and-feel)
23
+ 17. [Attachments](#17-attachments)
24
+ 18. [Live updates](#18-live-updates)
25
+ 19. [Trash](#19-trash)
26
+ 20. [Data export](#20-data-export)
27
+ 21. [Accessibility](#21-accessibility)
19
28
 
20
29
  ## 1. Embedding
21
30
 
@@ -94,6 +103,7 @@ Every option can be given in three ways: as a React prop, as an attribute of the
94
103
  | `features` | `feature-*` | see [Features](#3-features) | Switches for every optional feature |
95
104
  | `views` | `views` | all four | Views the user can switch between: `day`, `week`, `month`, `year`. Attribute: separated by spaces or commas, `views="week month"`. With one view the switch disappears |
96
105
  | `initialView` | `initial-view` | user's start view | View shown first. Wins over the user's setting |
106
+ | `readOnly` | `read-only` | `false` | Shows events without letting anyone create, change, move, delete or import them, see [Read-only mode](#14-read-only-mode-and-public-links) |
97
107
 
98
108
  ### Appearance
99
109
 
@@ -106,6 +116,7 @@ Every option can be given in three ways: as a React prop, as an attribute of the
106
116
  | `holidays` | `holidays` | from `locale` | Region for public holidays: `DE`, `DE-NW`, `AT`, `US-CA`, or `off`. Users can override it in the settings |
107
117
  | `holidaySource` | `holiday-source` | `library` | `library` computes holidays in the browser, `backend` asks your backend (`GET /holidays`) and falls back to the library |
108
118
  | `mapUrl` | `map-url` | Google Maps | Map service for locations, with `{query}` for the place: `https://www.openstreetmap.org/search?query={query}`, `https://maps.apple.com/?q={query}` |
119
+ | `appearance` | `accent-color`, `font-family`, `radius`, `density` | – | Accent color, font, corner radius and density, see [Look and feel](#16-look-and-feel) |
109
120
  | `className`, `style` | `class`, `style` | – | Size and place on your page |
110
121
 
111
122
  ### Navigation
@@ -123,6 +134,8 @@ Every option can be given in three ways: as a React prop, as an attribute of the
123
134
  | --- | --- | --- | --- |
124
135
  | `config` | `config`, property `config` | – | URL of a JSON or YAML file, or an object with options. See [Configuration file](#4-configuration-file) |
125
136
  | `onEventCreate`, `onEventUpdate`, `onEventDelete` | events `event-create`, `event-update`, `event-delete` | – | After every stored change, see [Reacting to changes](#6-reacting-to-changes) |
137
+ | `onViewChange` | event `view-change` | – | When the view or the shown dates change, see [Controlling the calendar](#15-controlling-the-calendar-from-your-page) |
138
+ | `ref` | methods on the element | – | Methods such as `goToDate()`, see [Controlling the calendar](#15-controlling-the-calendar-from-your-page) |
126
139
 
127
140
  ### Which setting wins
128
141
 
@@ -166,6 +179,12 @@ Everything beyond the core calendar (views, creating, editing, moving and deleti
166
179
  | `emailNotifications` | `feature-email-notifications` | on | E-mail settings of a signed-in user | Sending the e-mails |
167
180
  | `timeZones` | `feature-time-zones` | on | Time zone per event and in the settings | – |
168
181
  | `customColors` | `feature-custom-colors` | on | Own event colors | `/colors` |
182
+ | `categories` | `feature-categories` | on | Categories per calendar and the filter, see [Categories](#13-categories) | `/categories`, `/calendars/:id/categories` |
183
+ | `attachments` | `feature-attachments` | on | Files on events, see [Attachments](#17-attachments). Not in local mode | `/events/:id/attachments`, `/attachments/:id` |
184
+ | `liveUpdates` | `feature-live-updates` | on | Changes by others, or in other tabs, show up at once, see [Live updates](#18-live-updates) | WebSocket `/chat/socket` with `event.changed` messages |
185
+ | `trash` | `feature-trash` | on | Trash in the calendar settings, see [Trash](#19-trash) | `/calendars/:id/trash`, `/events/:id/restore`, `/trash/:id` |
186
+ | `dataExport` | `feature-data-export` | on | "Data" tab in the settings to download one's own data, see [Data export](#20-data-export) | `GET /auth/me/export` |
187
+ | `publicLinks` | `feature-public-links` | on | Public read-only links and the page they open, see [Public links](#14-read-only-mode-and-public-links) | `/calendars/:id/share`, `/shared/:token` |
169
188
 
170
189
  Good to know:
171
190
 
@@ -244,6 +263,8 @@ All options from [Options](#2-options) under their prop names, except those that
244
263
  | `holidays` | text (region or `"off"`) | from `locale` |
245
264
  | `holidaySource` | `"library"` or `"backend"` | `"library"` |
246
265
  | `mapUrl` | text with `{query}` | Google Maps |
266
+ | `readOnly` | `true` or `false` | `false` |
267
+ | `appearance` | object with `accentColor`, `fontFamily`, `radius`, `density` | – |
247
268
  | `routing` | `"memory"` or `"browser"` | `"memory"` |
248
269
  | `basename` | text | – |
249
270
  | `initialPath` | text | `/` |
@@ -387,8 +408,9 @@ import { Calendar, localDataSource, restDataSource, tenantDataSource } from '@ro
387
408
  | `getAccessToken` | – | Returns a bearer token for the `Authorization` header |
388
409
  | `getUserToken` | – | Sign-in through your page, see above |
389
410
  | `holidaySource` | `library` | `backend` asks `GET /holidays` |
390
- | `chat` | `true` | `false` creates no chat connection |
391
- | `chatSocketUrl` | from `baseUrl` | Address of the chat WebSocket |
411
+ | `chat` | `true` | `false` turns the chat off |
412
+ | `liveUpdates` | `true` | `false` turns live updates of events off. Without chat and live updates no WebSocket is opened |
413
+ | `chatSocketUrl` | from `baseUrl` | Address of the WebSocket, used by the chat and live updates |
392
414
 
393
415
  Note that `restDataSource` defaults to `auth: true`, while the `auth` feature of the component defaults to off.
394
416
 
@@ -409,17 +431,20 @@ const myDataSource: CalendarDataSource = {
409
431
  preferences: myPreferences,
410
432
  holidays: myHolidays,
411
433
  chat: myChat,
434
+ categories: myCategories,
435
+ shared: mySharedCalendars,
412
436
  }),
413
437
  }
414
438
  ```
415
439
 
416
440
  - `connect` returns the repositories for the current state. It is called again on sign-in and sign-out.
417
441
  - `createAuthRepository` is optional. Without it there is no sign-in in the widget.
418
- - `holidays` and `chat` are optional. Without `chat` there is no chat, without `holidays` they are computed in the browser.
442
+ - `holidays`, `chat`, `categories` and `shared` are optional. Without `chat` there is no chat, without `categories` no categories, without `shared` public links cannot be opened, and without `holidays` they are computed in the browser.
419
443
  - `mode: 'remote'` makes the calendar offer to move local events into the account after sign-in.
420
- - Optional methods switch their feature on: `events.search`, `events.respond`, `events.setReminders`, `calendars.getFeed` / `createFeed` / `deleteFeed`. Without `search` the calendar searches the last and next year itself.
444
+ - Optional methods switch their feature on: `events.search`, `events.respond`, `events.setReminders`, `events.subscribe` (live updates), `events.listTrash` / `restore` / `purge` (trash), `calendars.getFeed` / `createFeed` / `deleteFeed`, `calendars.getShare` / `createShare` / `deleteShare`. Without `search` the calendar searches the last and next year itself.
421
445
  - Call `onUnauthorized` when a session has run out. `getLanguage` returns the current language for your requests.
422
446
  - Errors with a known `code` are shown translated, others with their `message`.
447
+ - `events.update(id, input, version)` and `events.remove(id, version)` get the `version` the user saw. Throw an error with code `eventChanged` if the stored event is newer; without `version`, save without checking.
423
448
 
424
449
  A simple start is to take most repositories from `localDataSource()` and replace only `events`:
425
450
 
@@ -451,6 +476,8 @@ Everything below is exported from `@rokoyfa/calendar`.
451
476
  | `CalendarView` | type | `'day' | 'week' | 'month' | 'year'` |
452
477
  | `CalendarRouting`, `StorageMode`, `HolidaySource`, `HostTheme` | types | The values of `routing`, `storageMode`, `holidaySource`, `theme` |
453
478
  | `EventCallbacks`, `DeletedEvent` | types | The three callbacks, and `{ id }` |
479
+ | `CalendarHandle`, `CalendarState`, `NewEventDraft` | types | The methods of `ref` and of the element, the state they report, and the argument of `createEvent()` |
480
+ | `CalendarAppearance` | type | The value of `appearance` |
454
481
  | `Messages`, `PartialMessages`, `MessageOverrides`, `DeepPartial` | types | All texts, a part of them, and the type of `messages` |
455
482
 
456
483
  ```ts
@@ -473,11 +500,22 @@ type CalendarOptions = {
473
500
  holidays?: string
474
501
  holidaySource?: 'library' | 'backend'
475
502
  mapUrl?: string
503
+ readOnly?: boolean
504
+ appearance?: CalendarAppearance
505
+ }
506
+
507
+ type CalendarAppearance = {
508
+ accentColor?: string
509
+ fontFamily?: string
510
+ radius?: number
511
+ density?: 'comfortable' | 'compact'
476
512
  }
477
513
 
478
514
  type CalendarProps = CalendarOptions &
479
515
  EventCallbacks & {
480
516
  config?: string | CalendarOptions
517
+ ref?: Ref<CalendarHandle>
518
+ onViewChange?: (state: CalendarState) => void
481
519
  dataSource?: CalendarDataSource
482
520
  getUserToken?: UserTokenProvider
483
521
  className?: string
@@ -503,6 +541,9 @@ type CalendarFeatures = {
503
541
  emailNotifications: boolean
504
542
  timeZones: boolean
505
543
  customColors: boolean
544
+ categories: boolean
545
+ publicLinks: boolean
546
+ attachments: boolean
506
547
  }
507
548
  ```
508
549
 
@@ -515,6 +556,9 @@ type CalendarFeatures = {
515
556
  | `User`, `AuthMethod`, `UserTokenProvider` | The signed-in user, `'password' | 'hostToken'`, and the type of `getUserToken` |
516
557
  | `Preferences` | A user's settings |
517
558
  | `PublicHoliday` | `{ date, name }` |
559
+ | `Category` | `{ id, calendarId, name }` |
560
+ | `Attachment` | `{ id, eventId, name, type, size, createdAt, uploadedBy }` |
561
+ | `SharedCalendar` | `{ id, name, color, categories }`, what a public link shows of a calendar |
518
562
  | `ChatMessage`, `ChatKey`, `ChatPage`, `ChatUnread`, `ChatEvent` | Chat, see [Event chat](#11-event-chat) |
519
563
 
520
564
  ### Data adapters
@@ -530,6 +574,9 @@ type CalendarFeatures = {
530
574
  | `ColorRepository`, `PreferencesRepository` | Own colors, settings |
531
575
  | `HolidayRepository`, `HolidayQuery` | Public holidays |
532
576
  | `ChatRepository` | Chat |
577
+ | `CategoryRepository` | Categories |
578
+ | `SharedCalendarRepository` | Reading a calendar through a public link |
579
+ | `AttachmentRepository` | Files on events |
533
580
 
534
581
  ```ts
535
582
  interface CalendarDataSource {
@@ -547,19 +594,59 @@ type DataRepositories = {
547
594
  preferences: PreferencesRepository
548
595
  holidays?: HolidayRepository
549
596
  chat?: ChatRepository
597
+ categories?: CategoryRepository
598
+ shared?: SharedCalendarRepository
599
+ attachments?: AttachmentRepository
600
+ }
601
+
602
+ interface AttachmentRepository {
603
+ list(eventId: string): Promise<Attachment[]>
604
+ upload(eventId: string, file: File): Promise<Attachment>
605
+ download(attachment: Attachment): Promise<Blob>
606
+ remove(id: string): Promise<void>
607
+ }
608
+
609
+ interface CategoryRepository {
610
+ list(calendarIds: readonly string[]): Promise<Category[]>
611
+ create(calendarId: string, name: string): Promise<Category>
612
+ rename(id: string, name: string): Promise<Category>
613
+ remove(id: string): Promise<void>
614
+ }
615
+
616
+ interface SharedCalendarRepository {
617
+ get(token: string): Promise<SharedCalendar>
618
+ listEvents(token: string, range: { from: string; to: string }): Promise<CalendarEvent[]>
550
619
  }
551
620
 
552
621
  interface EventRepository {
553
622
  list(query: { from: string; to: string; calendarIds: readonly string[] }): Promise<CalendarEvent[]>
554
623
  listSeries(seriesId: string): Promise<CalendarEvent[]>
555
624
  create(calendarId: string, input: EventInput): Promise<CalendarEvent>
556
- update(id: string, input: EventInput): Promise<CalendarEvent>
557
- remove(id: string): Promise<void>
625
+ update(id: string, input: EventInput, version?: number): Promise<CalendarEvent>
626
+ remove(id: string, version?: number): Promise<void>
558
627
  search?(query: { text: string; calendarIds: readonly string[] }): Promise<CalendarEvent[]>
559
628
  respond?(id: string, status: AttendeeStatus): Promise<CalendarEvent>
560
629
  setReminders?(id: string, reminders: number[]): Promise<CalendarEvent>
630
+ subscribe?(listener: (change: EventChange) => void): () => void
631
+ listTrash?(calendarId: string): Promise<TrashedEvent[]>
632
+ restore?(id: string): Promise<CalendarEvent>
633
+ purge?(id: string): Promise<void>
561
634
  }
562
635
 
636
+ type TrashedEvent = {
637
+ event: CalendarEvent
638
+ deletedAt: string
639
+ deletedBy: string | null
640
+ deletedByName: string | null
641
+ expiresAt: string
642
+ detachedCount: number
643
+ }
644
+
645
+ type EventChange =
646
+ | { type: 'connected' }
647
+ | { type: 'disconnected' }
648
+ | { type: 'event.changed'; calendarId: string | null; eventId: string | null; version: number | null; changedBy: string | null }
649
+
563
650
  interface ChatRepository {
564
651
  list(key: ChatKey, options?: { before?: string }): Promise<ChatPage>
565
652
  send(key: ChatKey, text: string): Promise<ChatMessage>
@@ -583,7 +670,7 @@ type ChatPage = { messages: ChatMessage[]; hasMore: boolean }
583
670
  type ChatUnread = ChatKey & { count: number }
584
671
  ```
585
672
 
586
- The other interfaces (`CalendarRepository`, `AuthRepository`, `ColorRepository`, `PreferencesRepository`, `HolidayRepository`) are best read in your editor from the package's type definitions.
673
+ `AuthRepository` has an optional `exportData(): Promise<Blob>` for the data export. The other interfaces (`CalendarRepository`, `AuthRepository`, `ColorRepository`, `PreferencesRepository`, `HolidayRepository`) are best read in your editor from the package's type definitions.
587
674
 
588
675
  ## 10. Backend
589
676
 
@@ -597,6 +684,7 @@ type CalendarEvent = EventInput & {
597
684
  calendarId: string
598
685
  createdAt: string // ISO date-time
599
686
  updatedAt: string
687
+ version: number // starts at 1, goes up on every change, read-only
600
688
  }
601
689
 
602
690
  type EventInput = {
@@ -604,6 +692,7 @@ type EventInput = {
604
692
  title: string // 1–100 chars
605
693
  location: string // max 200 chars, '' if none
606
694
  links: EventLink[] // up to 10 http(s) links
695
+ categoryIds: string[] // up to 5 categories of the event's calendar
607
696
  startDate: string // 'YYYY-MM-DD'
608
697
  start: string // 'HH:mm' in timeZone
609
698
  endDate: string // inclusive for all-day events
@@ -670,7 +759,13 @@ The backend stores series as one event. The component expands occurrences itself
670
759
  | Answer as attendee | `POST /events/:id/response` with `{ status }` |
671
760
  | Change only own reminders | `PUT /events/:id/reminders` with `{ reminders }` (also for members without edit rights) |
672
761
  | Answer from an email link | `POST /events/respond` with `{ token, status }`, no session needed |
762
+ | Data export | `GET /auth/me/export` from the "Data" tab in the settings, answered with a JSON file |
763
+ | Trash | `GET /calendars/:id/trash` in the calendar settings, `POST /events/:id/restore`, `DELETE /trash/:id`. Undo after deleting also calls `POST /events/:id/restore` |
764
+ | Live updates | WebSocket `/chat/socket`, opened while the calendar is shown. After an `event.changed` message for a shown calendar, the component reloads the events of the visible range |
673
765
  | Event chat | `GET`/`POST /events/:id/chat?date=…`, `POST /events/:id/chat/read`, `PATCH`/`DELETE /chat/messages/:id`, `GET /chat/unread?calendarId=…`, WebSocket `/chat/socket` |
766
+ | Categories | `GET /categories?calendarId=…` with the calendars shown, `POST /calendars/:id/categories`, `PATCH` and `DELETE /categories/:id`. Events carry `categoryIds` |
767
+ | Attachments | `GET` and `POST /events/:id/attachments` (multipart, field `file`), `GET /attachments/:id/content`, `DELETE /attachments/:id`. Events carry a read-only `attachmentCount` |
768
+ | Public link | `GET`, `POST` (new link), `DELETE /calendars/:id/share`. The page behind the link calls `GET /shared/:token` and `GET /shared/:token/events?from=…&to=…` without a session |
674
769
  | Subscription link | `GET`, `POST` (new link), `DELETE /calendars/:id/feed`. The link points at your `GET /feeds/:token.ics` |
675
770
  | Reminders | `GET /events` for the next four weeks of all calendars, every five minutes while the widget is open |
676
771
  | Import .ics | `GET /events` for the whole calendar, then `PUT` for known `uid`s and `POST` for new ones |
@@ -682,11 +777,18 @@ Before editing "following" or "all" of a series, the component loads its detache
682
777
 
683
778
  ### Rules for the backend
684
779
 
685
- - **Sessions:** requests use `credentials: 'include'`. Set an `HttpOnly` cookie on sign-in. If the widget runs on another domain: CORS for that origin with `Access-Control-Allow-Credentials: true`, allowed headers `Content-Type`, `Accept`, `Accept-Language`, `Authorization`, `X-Calendar-Tenant`, and the cookie as `SameSite=None; Secure`. Answer `401` when the session is gone.
780
+ - **Sessions:** requests use `credentials: 'include'`. Set an `HttpOnly` cookie on sign-in. If the widget runs on another domain: CORS for that origin with `Access-Control-Allow-Credentials: true`, allowed headers `Content-Type`, `Accept`, `Accept-Language`, `Authorization`, `If-Match`, `X-Calendar-Tenant`, and the cookie as `SameSite=None; Secure`. Answer `401` when the session is gone.
686
781
  - **Errors:** always `{ code, message }`. Known codes such as `invalidCredentials`, `emailTaken`, `forbidden`, `lastOwner` are shown translated, others with `message`.
687
782
  - **Language:** every request carries `Accept-Language`. Use it, or the stored `locale`, for emails.
688
783
  - **Emails about events** (your backend sends them, the component only stores the user's choice): an invitation with yes / maybe / no links to `/respond?status=accepted&token=…` when someone is added as attendee (`emailInvites`), a notice when title, time, place or repetition change or the event is cancelled (`emailChanges`), and reminders at the user's own reminder times even while the calendar is closed (`emailReminders`, off by default). Only to verified addresses, never to the person who made the change.
689
- - **Subscriptions:** `GET /feeds/:token.ics` answers without a session with the calendar as iCalendar (RFC 5545) and the subscriber's own reminders. Keep one secret token per user and calendar, a new one replaces the old. Stop serving it when the user leaves the calendar.
784
+ - **Subscriptions:** `GET /feeds/:token.ics` answers without a session with the calendar as iCalendar (RFC 5545), the subscriber's own reminders and the category names as `CATEGORIES` (comma-separated, with `,` and `;` inside a name escaped as `\,` and `\;`). Keep one secret token per user and calendar, a new one replaces the old. Stop serving it when the user leaves the calendar.
785
+ - **Editing at the same time:** every event has a `version` that starts at 1. Raise it on every `PUT`, attendee response and removed category, but not when someone only changes their own reminders. `PUT` and `DELETE /events/:id` send `If-Match: "<version>"` with the version the user saw. If the event has a newer version, answer `412` with `eventChanged` and change nothing. The dialog then offers to save anyway (sent without `If-Match`) or to load the current version. Without `If-Match`, or with `*`, skip the check.
786
+ - **Categories:** belong to one calendar, names are unique per calendar without regard to case. Reject an event whose `categoryIds` are not from its calendar, and remove a deleted category from all events.
787
+ - **Attachments:** at most 10 MB per file and 20 per event. Store the files outside the database, keep only the file name, and serve them with `Content-Disposition: attachment`, `X-Content-Type-Options: nosniff` and a sandboxing `Content-Security-Policy`, because uploaded files are untrusted. Delete them together with their event, calendar or team. Never hand them out through public links or subscription feeds.
788
+ - **Public links:** one unguessable token per calendar. `GET /shared/:token/events` must leave out everything personal: empty `attendees` and `reminders`, no `createdBy`, and never chat messages. A new link, or stopping the share, must make the old token fail at once.
789
+ - **Data export:** `GET /auth/me/export` returns everything stored about the signed-in user as JSON (see `AccountExport` in the OpenAPI file). Leave out password hashes, sessions, tokens and secret links, and never include other people's events or messages.
790
+ - **Trash:** `DELETE /events/:id` moves the event to the trash instead of deleting it, together with the detached events of a series. Keep attachments, chat and email response links. Deleted events must no longer appear anywhere else: lists, search, feeds, public links, reminders. Restoring keeps the id and raises `version`; refuse a detached event whose series is still in the trash with `409 seriesDeleted`. After 30 days delete the event for good with its attachments and chat, and do the same at once when its calendar or team is deleted.
791
+ - **Live updates:** after every change to an event (create, `PUT`, `DELETE`, attendee response, attachment added or removed, category removed) send `{ "type": "event.changed", "calendarId", "eventId", "version", "changedBy" }` over the WebSocket to every connected member of the calendar's team. `version` is the new version, `null` when the event was deleted. `changedBy` is the user id, or `null` for changes without a session such as answers from an email link. Send one message per event, also for detached events deleted with their series.
690
792
  - **Email links:** point them at the host page with the screen as parameter, e.g. `https://host.example/calendar?calendarPath=%2Freset-password%3Ftoken%3D…`.
691
793
 
692
794
  ## 11. Event chat
@@ -703,7 +805,7 @@ Messages go over REST (see the OpenAPI file, tag *Chat*). New, edited and delete
703
805
 
704
806
  Emails link to the host page with `?calendar=…&event=…&date=…&tab=chat`, which opens the event with the chat.
705
807
 
706
- Without a WebSocket on your backend, turn the feature off: `features: { chat: false }`. The calendar then opens no connection and shows no chat.
808
+ Without a WebSocket on your backend, turn the feature off: `features: { chat: false }`. The calendar then shows no chat. The same WebSocket also carries [live updates](#18-live-updates); with both off, no connection is opened.
707
809
 
708
810
  ## 12. Calendar subscriptions
709
811
 
@@ -741,3 +843,203 @@ A subscription is not live: the app downloads the whole calendar again at interv
741
843
  The feed asks clients to reload every hour (`REFRESH-INTERVAL` and `X-PUBLISHED-TTL`), but most apps follow their own settings. For changes that must show up immediately, users should open this calendar directly. Two-way sync with near-instant updates would need a CalDAV server, which this component does not cover.
742
844
 
743
845
  Without the feed endpoints, turn the feature off: `features: { subscriptions: false }`.
846
+
847
+ ## 13. Categories
848
+
849
+ Every calendar can have its own categories, for example "Training" and "Match". Events get up to five of them, and a filter in the header shows only the chosen ones.
850
+
851
+ - **Managing.** Categories are created, renamed and deleted in the calendar's settings, by members with `manage_calendars` and by the owner of a personal calendar. A calendar holds up to 30.
852
+ - **Assigning.** The event dialog shows the categories of the event's calendar as chips. Anyone who may edit the event may assign them. Whoever may manage the categories can also create a new one right there with "+ New category"; it is selected at once.
853
+ - **Filtering.** The filter button appears as soon as one of the shown calendars has categories. It also offers "Without category". The choice lasts until the page is reloaded.
854
+ - **Deleting.** A deleted category disappears from its events.
855
+ - **Local mode.** Categories work without a backend, stored in the browser.
856
+ - **Export and subscriptions.** Exported `.ics` files carry the category names as `CATEGORIES`, which Google Calendar, Outlook and Apple Calendar understand. Your subscription feed should do the same.
857
+ - **Import.** Categories in an imported file are matched to the calendar's categories by name, without regard to case. Missing ones are created if the importing member may manage the calendar and the limit of 30 is not reached, otherwise they are left out. When a known event is imported again from a file without categories, it keeps its own.
858
+
859
+ Turn the feature off with `features: { categories: false }`.
860
+
861
+ ## 14. Read-only mode and public links
862
+
863
+ ### Read-only mode
864
+
865
+ `readOnly` turns the calendar into a display. Events can be opened and read, but not created, changed, moved, deleted or imported. Views, search, the category filter and the user's own settings keep working.
866
+
867
+ ```html
868
+ <calendar-widget read-only storage-mode="remote" api-base-url="https://api.example.com"></calendar-widget>
869
+ ```
870
+
871
+ ```tsx
872
+ <Calendar readOnly />
873
+ ```
874
+
875
+ This is a display option, not a protection. Your backend still has to reject changes it does not allow.
876
+
877
+ ### Public links
878
+
879
+ A member with `manage_calendars` can create a public link in the calendar's settings. Anyone with the link sees the calendar read-only, without an account.
880
+
881
+ - **What visitors see.** Title, time, location, description, links and categories of all events. Never attendees, reminders or chat.
882
+ - **One link per calendar.** Creating a new one, or stopping the share, turns the old link off at once.
883
+ - **Where the link points.** With `routing: memory` it is your own page with the link parameter, for example `https://example.com/team?calendarPath=%2Fshared%2F<token>`. With `routing: browser` it is `/shared/<token>` under your `basename`. If `linkParam` is `false`, the settings show the path instead, for use with `initialPath`.
884
+
885
+ To show a shared calendar permanently on a page, for example a club's public event list, open the widget on that path. Visitors do not sign in. Use the same data options as on your other pages, so the widget knows your backend (with accounts that is `feature-auth`, otherwise `storage-mode="remote"`):
886
+
887
+ ```html
888
+ <calendar-widget feature-auth api-base-url="https://api.example.com" initial-path="/shared/<token>" style="height: 600px"></calendar-widget>
889
+ ```
890
+
891
+ In local mode there is no backend to ask, so public links are not available.
892
+
893
+ Turn the feature off with `features: { publicLinks: false }`. Existing links then show a "not shared" message.
894
+
895
+ ## 15. Controlling the calendar from your page
896
+
897
+ Your page can move the calendar and react to where it is.
898
+
899
+ ```js
900
+ const calendar = document.querySelector('calendar-widget')
901
+
902
+ calendar.goToDate('2027-03-05')
903
+ calendar.setView('month')
904
+ calendar.addEventListener('view-change', (e) => console.log(e.detail))
905
+ ```
906
+
907
+ ```tsx
908
+ import { useRef } from 'react'
909
+ import { Calendar, type CalendarHandle } from '@rokoyfa/calendar'
910
+
911
+ function Page() {
912
+ const calendar = useRef<CalendarHandle>(null)
913
+ return (
914
+ <>
915
+ <button onClick={() => calendar.current?.today()}>Today</button>
916
+ <Calendar ref={calendar} onViewChange={(state) => console.log(state)} />
917
+ </>
918
+ )
919
+ }
920
+ ```
921
+
922
+ | Method | |
923
+ | --- | --- |
924
+ | `getState()` | `{ view, date, from, to }`: the view, the date it is centred on and the first and last day shown. `null` while the calendar itself is not on screen |
925
+ | `goToDate(date)` | Shows the date. Takes `'YYYY-MM-DD'` or a `Date` |
926
+ | `setView(view)` | Switches to `day`, `week`, `month` or `year` |
927
+ | `next()`, `previous()`, `today()` | The same as the buttons in the header |
928
+ | `openEvent(eventId, date)` | Goes to the date and opens the event. For a recurring event the date picks the occurrence |
929
+ | `createEvent(draft?)` | Opens the dialog for a new event, optionally filled in: `{ title, startDate, start, end, endDate, allDay, location, description }`. Nothing is stored until the user saves |
930
+ | `refresh()` | Loads the events again, for example after your page changed data on the backend |
931
+
932
+ - Every method except `getState()` returns `true` when it was carried out and `false` otherwise.
933
+ - A method answers `false` while the calendar itself is not on screen (settings, sign-in, or the configuration still loading), when an argument is invalid, when `setView` asks for a view that is not in `views`, and `createEvent` when the user may not create events.
934
+ - `view-change` / `onViewChange` fires once at the start and then whenever the view or the dates change, with the same value as `getState()`.
935
+
936
+ ## 16. Look and feel
937
+
938
+ The calendar follows light and dark mode by itself. On top of that you can match it to your page in two ways. Both set the same things, so use whichever is handier.
939
+
940
+ **From your CSS.** Custom properties set on the element reach into the calendar:
941
+
942
+ ```css
943
+ calendar-widget {
944
+ --calendar-accent: #e63946;
945
+ --calendar-on-accent: #ffffff;
946
+ --calendar-font: 'Inter', sans-serif;
947
+ --calendar-radius: 6px;
948
+ }
949
+ ```
950
+
951
+ With the React component, set them on the element you give a `className` or `style`.
952
+
953
+ | Property | Default | |
954
+ | --- | --- | --- |
955
+ | `--calendar-accent` | blue | Buttons, links, the active view, today, selection and focus ring |
956
+ | `--calendar-on-accent` | white, dark in dark mode | Text on the accent color. Set it when your accent is light (or dark in dark mode) |
957
+ | `--calendar-font` | Segoe UI, sans-serif | Font family. Your page has to load the font |
958
+ | `--calendar-radius` | `10px` | Corner radius of dialogs, buttons and fields. `0px` gives square corners |
959
+ | `--calendar-bg` | white / near black | Background |
960
+ | `--calendar-surface` | white / dark grey | Dialogs and cards |
961
+ | `--calendar-text` | near black / light grey | Text |
962
+ | `--calendar-heading` | grey | Headings |
963
+ | `--calendar-muted` | grey | Secondary text |
964
+ | `--calendar-border` | light grey / dark grey | Grid lines and borders |
965
+
966
+ Colors you set apply in light and dark mode alike. To give each its own value, use `light-dark()` or a media query in your CSS, or fix the mode with `theme`.
967
+
968
+ **As an option**, which also works in a configuration file:
969
+
970
+ ```html
971
+ <calendar-widget accent-color="#e63946" font-family="Inter, sans-serif" radius="6" density="compact"></calendar-widget>
972
+ ```
973
+
974
+ ```tsx
975
+ <Calendar appearance={{ accentColor: '#e63946', fontFamily: 'Inter, sans-serif', radius: 6, density: 'compact' }} />
976
+ ```
977
+
978
+ | Field | Attribute | |
979
+ | --- | --- | --- |
980
+ | `accentColor` | `accent-color` | A CSS color. For a hex color the text color on it is picked for you |
981
+ | `fontFamily` | `font-family` | A CSS font family |
982
+ | `radius` | `radius` | Corner radius in pixels, 0 to 24 |
983
+ | `density` | `density` | `comfortable` (default) or `compact` with smaller text, rows and spacing |
984
+
985
+ The option wins over the CSS properties. The colors of events are not affected by the accent color, they keep the color the user gave them.
986
+
987
+ ## 17. Attachments
988
+
989
+ Files can be attached to events, for example an agenda or a flyer.
990
+
991
+ - **Where.** In the event dialog under "Details", with a button or by dragging files onto the section. Events with attachments show a paperclip.
992
+ - **New events.** Files chosen while creating an event are uploaded right after it is saved. If one fails, the event is kept and a message names the files that are missing.
993
+ - **Limits.** Up to 20 files per event, each at most 10 MB. Empty and larger files are refused before anything is sent.
994
+ - **Who may do what.** Everyone who can see the event can download its files. Uploading and deleting needs the right to edit the event. In read-only mode files can only be downloaded.
995
+ - **Series.** A recurring event has one set of attachments for all its occurrences. An occurrence changed on its own gets its own set.
996
+ - **Not included.** Attachments are not copied when duplicating an event, and they are not part of `.ics` exports, subscription feeds or public links.
997
+ - **Local mode.** Without a backend there are no attachments, because browser storage is too small for files.
998
+
999
+ Turn the feature off with `features: { attachments: false }`.
1000
+
1001
+ ## 18. Live updates
1002
+
1003
+ When someone changes an event in a calendar that is shown, everyone else sees it at once, without reloading.
1004
+
1005
+ - **How.** The backend sends an `event.changed` message over the WebSocket that the chat uses too (see [Event chat](#11-event-chat) for address, sign-in and pings, and [Rules for the backend](#rules-for-the-backend) for the message). The component then reloads the events of the visible range, several messages in a row only once.
1006
+ - **Open dialog.** If another person changes or deletes the event that is open in the dialog, the dialog says so and offers to reload it. Saving anyway is still protected by `If-Match` (see [Rules for the backend](#rules-for-the-backend)).
1007
+ - **Connection lost.** The component reconnects with growing pauses and reloads the events once it is back, so nothing is missed.
1008
+ - **Local mode.** Without a backend, changes made in another tab of the same browser show up at once.
1009
+ - **Own adapter.** Implement `events.subscribe(listener)` and call the listener with an `EventChange`. Return a function that ends the subscription. Without `subscribe` there are no live updates.
1010
+
1011
+ Without a WebSocket on your backend, turn chat and live updates off: `features: { chat: false, liveUpdates: false }`. The calendar then opens no connection.
1012
+
1013
+ ## 19. Trash
1014
+
1015
+ Deleted events are not gone at once. They stay in the trash of their calendar for 30 days.
1016
+
1017
+ - **Where.** In the calendar settings, in the **Trash** tab (team and personal calendars). Each entry shows when and by whom it was deleted and when it will be gone for good. The list shows 20 entries at a time with **Show more**, and from 8 entries on a search by title, place or who deleted it.
1018
+ - **Restore.** Brings the event back with the same id, so attachments, chat and email links work again. A series comes back with the detached events deleted together with it. A detached event can only come back while its series exists.
1019
+ - **Delete for good.** Removes the event with attachments and chat at once, after a confirmation.
1020
+ - **Undo.** The undo notice after deleting uses the trash too, so nothing is lost on the way back.
1021
+ - **Who.** Everyone who may delete an event may restore it or delete it for good: with `delete_any_entry` every event, with `delete_own_entry` their own.
1022
+ - **Local mode.** Without a backend the trash lives in the browser (`localStorage`) and works the same way.
1023
+ - **Own adapter.** Implement `events.listTrash`, `events.restore` and `events.purge`. Without them there is no trash and undo creates a copy of the deleted event.
1024
+
1025
+ Turn the trash off with `features: { trash: false }`. Undo still restores from the trash when the backend has one.
1026
+
1027
+ ## 20. Data export
1028
+
1029
+ Users can download their own data in the settings, in the **Data** tab, as required by Art. 20 GDPR (right to data portability).
1030
+
1031
+ - **Signed in.** The file comes from `GET /auth/me/export` on your backend. What belongs into it is listed in [Rules for the backend](#rules-for-the-backend). With your own `AuthRepository`, implement `exportData()`; without it the tab is not shown to signed-in users.
1032
+ - **Local mode.** The file contains everything the calendar stores in this browser (`localStorage` keys starting with `calendar.`), with the format `calendar-browser-export`.
1033
+ - **File.** JSON, named `calendar-export-YYYY-MM-DD.json`.
1034
+
1035
+ Turn it off with `features: { dataExport: false }`, for example when your page already offers its own export.
1036
+
1037
+ ## 21. Accessibility
1038
+
1039
+ The calendar aims at WCAG 2.2 AA and is checked with axe-core in light and dark mode.
1040
+
1041
+ - **Keyboard.** Every event is a button and can be reached with `Tab`. On an event, `↑` and `↓` move to the previous or next event of the same day, `←` and `→` to the nearest event on the previous or next day with events, `Home` and `End` to the first and last event in view, `Enter` opens it. The other shortcuts are listed in the tooltips of the header buttons.
1042
+ - **Screen readers.** Each day column and month cell is a group named after its date, with "today" and public holidays. Events are announced with title, time, place, repetition, calendar, the user's own response and the number of attachments. The period title in the header is a live region, so moving to the next week is announced. Dialogs are labelled by their title and move the focus into the dialog.
1043
+ - **Contrast.** Text and event colors meet 4.5:1 in both themes. In dark mode, text on the built-in event colors and the accent is dark. If you change colors with `--calendar-*` properties, check the contrast of your own colors.
1044
+ - **Creating events.** Clicking a time slot needs a mouse; with the keyboard, use the **+** button or `N`.
1045
+
package/README.md CHANGED
@@ -9,6 +9,8 @@ An embeddable calendar for React apps and any other website. It runs without a b
9
9
  - iCalendar import, export and subscription links for other calendar apps
10
10
  - English, German, French, Spanish, Italian, Dutch, Polish and Portuguese built in, more through your own texts
11
11
  - Styles isolated in a Shadow DOM, so your page and the calendar never affect each other
12
+ - Categories with a filter, a read-only mode and public read-only links
13
+ - Your page can steer it (`goToDate()`, `setView()`, `openEvent()`) and match it to your design with CSS variables
12
14
  - Every optional feature can be switched off
13
15
 
14
16
  ## Quick start