@rokoyfa/calendar 1.1.0 → 1.2.1

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 (191) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/DEVELOPER_GUIDE.md +743 -0
  3. package/README.md +39 -108
  4. package/api/openapi.yaml +359 -3
  5. package/demo/calendar.config.jsonc +149 -0
  6. package/demo/calendar.config.yaml +146 -0
  7. package/dist-lib/cdn/browser-BSbYkIQu.js +130 -0
  8. package/dist-lib/cdn/browser-BSbYkIQu.js.map +1 -0
  9. package/dist-lib/cdn/calendar-widget.js +12 -7
  10. package/dist-lib/cdn/calendar-widget.js.map +1 -1
  11. package/dist-lib/cdn/de-CjkGEfiE.js +2 -0
  12. package/dist-lib/cdn/de-CjkGEfiE.js.map +1 -0
  13. package/dist-lib/cdn/es-BrMRh6bn.js +2 -0
  14. package/dist-lib/cdn/es-BrMRh6bn.js.map +1 -0
  15. package/dist-lib/cdn/fr-Ckr8Uxxd.js +2 -0
  16. package/dist-lib/cdn/fr-Ckr8Uxxd.js.map +1 -0
  17. package/dist-lib/cdn/it-_2BGklYa.js +2 -0
  18. package/dist-lib/cdn/it-_2BGklYa.js.map +1 -0
  19. package/dist-lib/cdn/nl-BykoYBK7.js +2 -0
  20. package/dist-lib/cdn/nl-BykoYBK7.js.map +1 -0
  21. package/dist-lib/cdn/pl-as7f_-F8.js +2 -0
  22. package/dist-lib/cdn/pl-as7f_-F8.js.map +1 -0
  23. package/dist-lib/cdn/pt-BWJIdrI6.js +2 -0
  24. package/dist-lib/cdn/pt-BWJIdrI6.js.map +1 -0
  25. package/dist-lib/cdn/rolldown-runtime-CrjiCqGf.js +1 -0
  26. package/dist-lib/cdn/src-l8Q4aJRr.js +12 -0
  27. package/dist-lib/cdn/src-l8Q4aJRr.js.map +1 -0
  28. package/dist-lib/npm/{de-CCzGjeTd.js → de-lDO0Tv9y.js} +135 -8
  29. package/dist-lib/npm/de-lDO0Tv9y.js.map +1 -0
  30. package/dist-lib/npm/{es-Ciaf66rH.js → es-Cy3Mmj9C.js} +135 -8
  31. package/dist-lib/npm/es-Cy3Mmj9C.js.map +1 -0
  32. package/dist-lib/npm/{fr-CAqNm10Z.js → fr-Ci0ZM0nG.js} +135 -8
  33. package/dist-lib/npm/fr-Ci0ZM0nG.js.map +1 -0
  34. package/dist-lib/npm/index.js +6012 -2564
  35. package/dist-lib/npm/index.js.map +1 -1
  36. package/dist-lib/npm/{it-Cqqdu2ua.js → it-BiTHjgzI.js} +135 -8
  37. package/dist-lib/npm/it-BiTHjgzI.js.map +1 -0
  38. package/dist-lib/npm/{nl-CkchSA8q.js → nl-DZTwpAwV.js} +135 -8
  39. package/dist-lib/npm/nl-DZTwpAwV.js.map +1 -0
  40. package/dist-lib/npm/{pl-CCBDUr8k.js → pl-DeWLtyMR.js} +135 -8
  41. package/dist-lib/npm/pl-DeWLtyMR.js.map +1 -0
  42. package/dist-lib/npm/{pt-DucaCaoY.js → pt-CaqSW5TJ.js} +135 -8
  43. package/dist-lib/npm/pt-CaqSW5TJ.js.map +1 -0
  44. package/dist-lib/npm/types/components/Button.d.ts +1 -1
  45. package/dist-lib/npm/types/components/Icons.d.ts +5 -0
  46. package/dist-lib/npm/types/components/SegmentedControl.d.ts +2 -2
  47. package/dist-lib/npm/types/components/SegmentedField.d.ts +2 -11
  48. package/dist-lib/npm/types/components/StatusMessage.d.ts +0 -1
  49. package/dist-lib/npm/types/components/Tabs.d.ts +3 -1
  50. package/dist-lib/npm/types/config/routes.d.ts +1 -1
  51. package/dist-lib/npm/types/context/HostContext.d.ts +26 -3
  52. package/dist-lib/npm/types/context/TimeZoneContext.d.ts +3 -0
  53. package/dist-lib/npm/types/data/restDataSource.d.ts +5 -1
  54. package/dist-lib/npm/types/data/tenantDataSource.d.ts +4 -1
  55. package/dist-lib/npm/types/data/types.d.ts +3 -1
  56. package/dist-lib/npm/types/features/authorization/hooks/useAuth.d.ts +2 -1
  57. package/dist-lib/npm/types/features/authorization/hooks/useRedirectTarget.d.ts +4 -0
  58. package/dist-lib/npm/types/features/authorization/index.d.ts +1 -1
  59. package/dist-lib/npm/types/features/authorization/repositories/HostTokenAuthRepository.d.ts +2 -0
  60. package/dist-lib/npm/types/features/authorization/repositories/RemoteAuthRepository.d.ts +2 -0
  61. package/dist-lib/npm/types/features/authorization/types/auth.d.ts +3 -0
  62. package/dist-lib/npm/types/features/calendar/components/Calendar.d.ts +14 -1
  63. package/dist-lib/npm/types/features/calendar/components/CalendarHeader.d.ts +2 -1
  64. package/dist-lib/npm/types/features/calendar/components/DayColumn.d.ts +2 -1
  65. package/dist-lib/npm/types/features/calendar/components/EventLinks.d.ts +7 -0
  66. package/dist-lib/npm/types/features/calendar/components/EventLocation.d.ts +3 -0
  67. package/dist-lib/npm/types/features/calendar/components/EventSearchModal.d.ts +9 -0
  68. package/dist-lib/npm/types/features/calendar/components/EventTitle.d.ts +2 -1
  69. package/dist-lib/npm/types/features/calendar/components/MiniMonth.d.ts +2 -1
  70. package/dist-lib/npm/types/features/calendar/components/UndoNotice.d.ts +7 -0
  71. package/dist-lib/npm/types/features/calendar/constants/views.d.ts +4 -1
  72. package/dist-lib/npm/types/features/calendar/context/CurrentUserContext.d.ts +3 -0
  73. package/dist-lib/npm/types/features/calendar/context/HolidaysContext.d.ts +4 -0
  74. package/dist-lib/npm/types/features/calendar/hooks/useAttendeeCandidates.d.ts +3 -0
  75. package/dist-lib/npm/types/features/calendar/hooks/useEventDrag.d.ts +1 -1
  76. package/dist-lib/npm/types/features/calendar/hooks/useEventSearch.d.ts +7 -0
  77. package/dist-lib/npm/types/features/calendar/hooks/useEventSource.d.ts +2 -1
  78. package/dist-lib/npm/types/features/calendar/hooks/usePressDrag.d.ts +23 -0
  79. package/dist-lib/npm/types/features/calendar/hooks/useSegmentAttributes.d.ts +15 -0
  80. package/dist-lib/npm/types/features/calendar/hooks/useSlotSelection.d.ts +1 -4
  81. package/dist-lib/npm/types/features/calendar/index.d.ts +1 -2
  82. package/dist-lib/npm/types/features/calendar/types/editor.d.ts +3 -0
  83. package/dist-lib/npm/types/features/calendar/types/view.d.ts +1 -1
  84. package/dist-lib/npm/types/features/calendar/utils/eventDrag.d.ts +0 -1
  85. package/dist-lib/npm/types/features/calendar/utils/eventLabels.d.ts +0 -3
  86. package/dist-lib/npm/types/features/calendar/utils/search.d.ts +11 -0
  87. package/dist-lib/npm/types/features/calendars/components/ShowInPersonalSwitch.d.ts +4 -0
  88. package/dist-lib/npm/types/features/calendars/components/settings/ExchangeSection.d.ts +4 -0
  89. package/dist-lib/npm/types/features/calendars/components/settings/SubscribeSection.d.ts +4 -0
  90. package/dist-lib/npm/types/features/calendars/context/CalendarsProvider.d.ts +2 -1
  91. package/dist-lib/npm/types/features/calendars/index.d.ts +2 -2
  92. package/dist-lib/npm/types/features/calendars/repositories/LocalCalendarRepository.d.ts +12 -1
  93. package/dist-lib/npm/types/features/calendars/repositories/RemoteCalendarRepository.d.ts +3 -0
  94. package/dist-lib/npm/types/features/calendars/types/calendar.d.ts +5 -1
  95. package/dist-lib/npm/types/features/calendars/utils/activeCalendarStorage.d.ts +2 -0
  96. package/dist-lib/npm/types/features/calendars/utils/permissions.d.ts +1 -2
  97. package/dist-lib/npm/types/features/chat/components/ChatPanel.d.ts +8 -0
  98. package/dist-lib/npm/types/features/chat/components/ChatProvider.d.ts +13 -0
  99. package/dist-lib/npm/types/features/chat/components/UnreadBadge.d.ts +4 -0
  100. package/dist-lib/npm/types/features/chat/context/ChatContext.d.ts +14 -0
  101. package/dist-lib/npm/types/features/chat/hooks/useChatMessages.d.ts +13 -0
  102. package/dist-lib/npm/types/features/chat/hooks/useChatUnread.d.ts +7 -0
  103. package/dist-lib/npm/types/features/chat/index.d.ts +4 -0
  104. package/dist-lib/npm/types/features/chat/utils/time.d.ts +2 -0
  105. package/dist-lib/npm/types/features/events/components/AttendeesField.d.ts +15 -0
  106. package/dist-lib/npm/types/features/events/components/EventModal.d.ts +19 -3
  107. package/dist-lib/npm/types/features/events/components/LinksField.d.ts +8 -0
  108. package/dist-lib/npm/types/features/events/components/ReminderField.d.ts +6 -0
  109. package/dist-lib/npm/types/features/events/hooks/useEvents.d.ts +6 -3
  110. package/dist-lib/npm/types/features/events/index.d.ts +3 -1
  111. package/dist-lib/npm/types/features/events/utils/icalExchange.d.ts +11 -0
  112. package/dist-lib/npm/types/features/events/utils/undo.d.ts +7 -0
  113. package/dist-lib/npm/types/features/holidays/components/HolidaySettings.d.ts +1 -0
  114. package/dist-lib/npm/types/features/holidays/hooks/useHolidays.d.ts +3 -0
  115. package/dist-lib/npm/types/features/holidays/index.d.ts +2 -0
  116. package/dist-lib/npm/types/features/holidays/utils/holidayLibrary.d.ts +8 -0
  117. package/dist-lib/npm/types/features/preferences/components/NotificationSettings.d.ts +3 -0
  118. package/dist-lib/npm/types/features/preferences/index.d.ts +1 -0
  119. package/dist-lib/npm/types/features/reminders/ReminderNotices.d.ts +1 -0
  120. package/dist-lib/npm/types/features/reminders/useReminders.d.ts +2 -0
  121. package/dist-lib/npm/types/features/storage/hooks/useStorage.d.ts +1 -2
  122. package/dist-lib/npm/types/features/storage/index.d.ts +4 -2
  123. package/dist-lib/npm/types/features/storage/repositories/LocalEventRepository.d.ts +2 -1
  124. package/dist-lib/npm/types/features/storage/repositories/RemoteChatRepository.d.ts +18 -0
  125. package/dist-lib/npm/types/features/storage/repositories/RemoteEventRepository.d.ts +5 -2
  126. package/dist-lib/npm/types/features/storage/repositories/RemoteHolidayRepository.d.ts +7 -0
  127. package/dist-lib/npm/types/features/storage/types/storage.d.ts +30 -2
  128. package/dist-lib/npm/types/hooks/useDebouncedValue.d.ts +1 -0
  129. package/dist-lib/npm/types/hooks/useForm.d.ts +5 -0
  130. package/dist-lib/npm/types/hooks/useFormState.d.ts +5 -0
  131. package/dist-lib/npm/types/hooks/useKeyboardShortcuts.d.ts +3 -0
  132. package/dist-lib/npm/types/hooks/useLocationUrl.d.ts +1 -0
  133. package/dist-lib/npm/types/i18n/format.d.ts +1 -0
  134. package/dist-lib/npm/types/i18n/index.d.ts +0 -1
  135. package/dist-lib/npm/types/i18n/locale.d.ts +0 -2
  136. package/dist-lib/npm/types/i18n/messages/en/calendar.d.ts +17 -0
  137. package/dist-lib/npm/types/i18n/messages/en/calendars.d.ts +25 -0
  138. package/dist-lib/npm/types/i18n/messages/en/core.d.ts +3 -0
  139. package/dist-lib/npm/types/i18n/messages/en/events.d.ts +64 -3
  140. package/dist-lib/npm/types/i18n/messages/en/index.d.ts +130 -3
  141. package/dist-lib/npm/types/i18n/messages/en/settings.d.ts +21 -0
  142. package/dist-lib/npm/types/i18n/messages/index.d.ts +130 -3
  143. package/dist-lib/npm/types/lib/CalendarWidget.d.ts +1 -1
  144. package/dist-lib/npm/types/lib/config.d.ts +9 -22
  145. package/dist-lib/npm/types/lib/configFile.d.ts +6 -0
  146. package/dist-lib/npm/types/lib/defaults.d.ts +25 -1
  147. package/dist-lib/npm/types/lib/element.d.ts +5 -1
  148. package/dist-lib/npm/types/lib/index.d.ts +6 -3
  149. package/dist-lib/npm/types/lib/options.d.ts +35 -0
  150. package/dist-lib/npm/types/lib/useCalendarOptions.d.ts +11 -0
  151. package/dist-lib/npm/types/pages/RespondPage.d.ts +1 -0
  152. package/dist-lib/npm/types/utils/api.d.ts +4 -5
  153. package/dist-lib/npm/types/utils/apiError.d.ts +0 -2
  154. package/dist-lib/npm/types/utils/appError.d.ts +2 -1
  155. package/dist-lib/npm/types/utils/calendarView.d.ts +1 -0
  156. package/dist-lib/npm/types/utils/chat.d.ts +44 -0
  157. package/dist-lib/npm/types/utils/color.d.ts +0 -1
  158. package/dist-lib/npm/types/utils/date.d.ts +0 -6
  159. package/dist-lib/npm/types/utils/event.d.ts +41 -5
  160. package/dist-lib/npm/types/utils/holidays.d.ts +18 -0
  161. package/dist-lib/npm/types/utils/ical.d.ts +11 -0
  162. package/dist-lib/npm/types/utils/location.d.ts +4 -0
  163. package/dist-lib/npm/types/utils/notifications.d.ts +3 -0
  164. package/dist-lib/npm/types/utils/preferences.d.ts +7 -1
  165. package/dist-lib/npm/types/utils/recurrence.d.ts +3 -4
  166. package/dist-lib/npm/types/utils/reminders.d.ts +13 -0
  167. package/dist-lib/npm/types/utils/timeZone.d.ts +1 -1
  168. package/package.json +10 -1
  169. package/schema/calendar-config.schema.json +232 -0
  170. package/dist-lib/cdn/de-BPZBZXaZ.js +0 -2
  171. package/dist-lib/cdn/de-BPZBZXaZ.js.map +0 -1
  172. package/dist-lib/cdn/es-DsIckdik.js +0 -2
  173. package/dist-lib/cdn/es-DsIckdik.js.map +0 -1
  174. package/dist-lib/cdn/fr-DWAs3O6J.js +0 -2
  175. package/dist-lib/cdn/fr-DWAs3O6J.js.map +0 -1
  176. package/dist-lib/cdn/it-CbhjxqIb.js +0 -2
  177. package/dist-lib/cdn/it-CbhjxqIb.js.map +0 -1
  178. package/dist-lib/cdn/nl-mjTHznX5.js +0 -2
  179. package/dist-lib/cdn/nl-mjTHznX5.js.map +0 -1
  180. package/dist-lib/cdn/pl-CXT0jb2D.js +0 -2
  181. package/dist-lib/cdn/pl-CXT0jb2D.js.map +0 -1
  182. package/dist-lib/cdn/pt-D0oXlVdU.js +0 -2
  183. package/dist-lib/cdn/pt-D0oXlVdU.js.map +0 -1
  184. package/dist-lib/npm/de-CCzGjeTd.js.map +0 -1
  185. package/dist-lib/npm/es-Ciaf66rH.js.map +0 -1
  186. package/dist-lib/npm/fr-CAqNm10Z.js.map +0 -1
  187. package/dist-lib/npm/it-Cqqdu2ua.js.map +0 -1
  188. package/dist-lib/npm/nl-CkchSA8q.js.map +0 -1
  189. package/dist-lib/npm/pl-CCBDUr8k.js.map +0 -1
  190. package/dist-lib/npm/pt-DucaCaoY.js.map +0 -1
  191. package/dist-lib/npm/types/hooks/useArrowKeyNavigation.d.ts +0 -6
package/README.md CHANGED
@@ -1,8 +1,17 @@
1
1
  # @rokoyfa/calendar
2
2
 
3
- An embeddable calendar for React apps and any other website. Day, week, month and year views, recurring events, team calendars with roles and invitations. English, German, French, Spanish, Italian, Dutch, Polish and Portuguese built in, more through your own texts. Runs without a backend (data stays in the browser) or against your own REST backend. Styles are isolated in a Shadow DOM, so the host page and the calendar never affect each other.
3
+ An embeddable calendar for React apps and any other website. It runs without a backend, with data kept in the browser, or against your own REST backend.
4
4
 
5
- ## Setup
5
+ - Day, week, month and year views with drag and drop
6
+ - Recurring and all-day events, time zones, reminders, locations and links
7
+ - Team calendars with roles, invitations, attendees and a chat per event
8
+ - Public holidays for over 200 countries, search, undo, keyboard shortcuts
9
+ - iCalendar import, export and subscription links for other calendar apps
10
+ - English, German, French, Spanish, Italian, Dutch, Polish and Portuguese built in, more through your own texts
11
+ - Styles isolated in a Shadow DOM, so your page and the calendar never affect each other
12
+ - Every optional feature can be switched off
13
+
14
+ ## Quick start
6
15
 
7
16
  **Any website**, React is bundled:
8
17
 
@@ -12,7 +21,7 @@ An embeddable calendar for React apps and any other website. Day, week, month an
12
21
  <calendar-widget style="height: 700px"></calendar-widget>
13
22
  ```
14
23
 
15
- **React 19**:
24
+ **React 19:**
16
25
 
17
26
  ```bash
18
27
  npm install @rokoyfa/calendar
@@ -26,133 +35,55 @@ import { Calendar } from '@rokoyfa/calendar'
26
35
 
27
36
  Give the calendar a height, it fills its box. No CSS import is needed.
28
37
 
29
- ## Examples
38
+ ## Configuring
39
+
40
+ Options are attributes on the web component and props on the React component:
30
41
 
31
42
  ```html
32
- <!-- German, dark, month view -->
33
43
  <calendar-widget locale="de-DE" theme="dark" initial-view="month" style="height: 600px"></calendar-widget>
34
44
 
35
- <!-- Your backend with sign-in -->
36
- <calendar-widget storage-mode="remote" auth api-base-url="https://api.example.com" style="height: 700px"></calendar-widget>
45
+ <calendar-widget storage-mode="remote" feature-auth feature-chat="false" api-base-url="https://api.example.com"></calendar-widget>
37
46
  ```
38
47
 
39
48
  ```tsx
40
49
  <Calendar
41
50
  storageMode="remote"
42
51
  apiBaseUrl="https://api.example.com"
43
- features={{ auth: true, teams: false }}
52
+ features={{ auth: true, chat: false }}
53
+ views={['week', 'month']}
44
54
  onEventCreate={(event) => console.log('created', event)}
45
55
  />
46
56
  ```
47
57
 
48
- ```js
49
- document.querySelector('calendar-widget').addEventListener('event-create', (e) => console.log(e.detail))
50
- ```
58
+ Or keep them in a JSON or YAML file:
51
59
 
52
- | Prop | Attribute | Default | |
53
- | --- | --- | --- | --- |
54
- | `locale` | `locale` | browser | `en-US`, `de-DE`, `fr-FR`, `pt-BR`, … Formats follow the region |
55
- | `messages` | property | – | Own texts per language, see below |
56
- | `theme` | `theme` | system | `light`, `dark` |
57
- | `initialView` | `initial-view` | user setting | `day`, `week`, `month`, `year` |
58
- | `timeZone` | `time-zone` | browser | IANA zone the calendar is shown in, e.g. `Europe/Berlin` |
59
- | `storageMode` | `storage-mode` | `local` | `local` or `remote` |
60
- | `apiBaseUrl` | `api-base-url` | `/api` | Base URL of your backend |
61
- | `features` | `auth`, `teams` | auth off, teams on | `teams="false"` turns team features off |
62
- | `tenant`, `getUserToken` | `tenant`, property | – | Multi-tenant backend, sign-in through your own page |
63
- | `dataSource` | property | – | Custom data adapter instead of REST |
64
- | `onEventCreate` / `Update` / `Delete` | `event-create` / `-update` / `-delete` | – | After every stored change |
65
-
66
- **Own texts and languages.** Override single texts or add a language. Missing texts fall back to the built-in language, or to English for a new one. The full list of keys is the `Messages` type.
67
-
68
- ```js
69
- document.querySelector('calendar-widget').messages = {
70
- de: { calendar: { newEvent: 'Neuer Eintrag' } },
71
- sv: { calendar: { today: 'Idag', newEvent: 'Ny händelse' }, views: { weekNumber: (week) => `V. ${week}` } },
72
- }
60
+ ```html
61
+ <calendar-widget config="/calendar.config.yaml" style="height: 700px"></calendar-widget>
73
62
  ```
74
63
 
75
- The CDN build loads languages other than English on demand from files next to `calendar-widget.js`. When hosting it yourself, copy the whole `dist-lib/cdn` folder.
76
-
77
- **Demo:** [`demo/cdn.html`](demo/cdn.html) shows local mode with an event log, a dark German month view and a compact widget. Download it and open it in a browser, it loads the published package from jsDelivr.
78
-
79
- ## Building your own backend
80
-
81
- The full contract is [`api/openapi.yaml`](api/openapi.yaml) (OpenAPI 3.1, also shipped as `@rokoyfa/calendar/openapi.yaml`). The essentials:
82
-
83
- ### Data types
84
-
85
- ```ts
86
- type CalendarEvent = EventInput & {
87
- id: string
88
- calendarId: string
89
- createdAt: string // ISO date-time
90
- updatedAt: string
91
- }
92
-
93
- type EventInput = {
94
- title: string // 1–100 chars
95
- startDate: string // 'YYYY-MM-DD'
96
- start: string // 'HH:mm' in timeZone
97
- endDate: string // inclusive for all-day events
98
- end: string
99
- allDay: boolean // start and end are '00:00'
100
- timeZone: string | null // IANA zone, null = same local time everywhere (always null for all-day)
101
- description: string // max 2000 chars
102
- color: 'blue' | 'red' | 'green' | 'yellow' | `#${string}`
103
- recurrence: Recurrence | null
104
- excludedDates: string[] // occurrences removed from a series
105
- seriesId: string | null // set on an occurrence detached from a series
106
- originalDate: string | null // its original date in that series
107
- }
108
-
109
- type Recurrence = {
110
- frequency: 'daily' | 'weekly' | 'monthly' | 'yearly'
111
- interval: number // 1–99
112
- weekdays: number[] // 0 = Monday … 6 = Sunday
113
- monthlyMode: 'dayOfMonth' | 'weekdayOfMonth' | 'lastWeekdayOfMonth'
114
- until: string | null // either until or count, or neither
115
- count: number | null
116
- }
117
-
118
- type CalendarSummary = {
119
- id: string; teamId: string; name: string; color: string
120
- kind: 'personal' | 'team'; teamName: string | null; description: string
121
- role: 'owner' | 'admin' | 'manager' | 'editor' | 'member' | 'contributor' | 'viewer'
122
- showInPersonal: boolean; permissions: string[]
123
- }
124
-
125
- type User = { id: string; email: string; name: string; emailVerified: boolean }
126
- type Preferences = { theme: 'system' | 'light' | 'dark'; defaultView: View; mobileDefaultView: View; locale: string }
127
- type Problem = { code: string; message: string } // every error response
64
+ ```yaml
65
+ storageMode: remote
66
+ apiBaseUrl: https://api.example.com
67
+ locale: de-DE
68
+ views: [week, month]
69
+ features:
70
+ auth: true
71
+ chat: false
128
72
  ```
129
73
 
130
- The backend stores series as one event. The component expands occurrences itself.
74
+ Commented example files with every option: [`demo/calendar.config.yaml`](demo/calendar.config.yaml) and [`demo/calendar.config.jsonc`](demo/calendar.config.jsonc).
131
75
 
132
- ### When the component calls your backend
76
+ ## Documentation
133
77
 
134
- | Moment | Requests |
78
+ | | |
135
79
  | --- | --- |
136
- | Widget loads | `GET /auth/me` (only with `auth`), then `GET /preferences`, `GET /colors`, `GET /calendars`, `GET /invitations` |
137
- | Visible range changes | `GET /events?from=…&to=…&calendarId=…` with the calendars shown. The range is one day wider than the view to cover time zone shifts. Return every event in the range **and** every series that can occur in it. |
138
- | Create event | `POST /events` with `EventInput` + `calendarId` |
139
- | Edit event / whole series | `PUT /events/:id` with the full `EventInput` |
140
- | Edit only this occurrence | `PUT` the series with the date added to `excludedDates`, then `POST` a detached event with `seriesId` and `originalDate` |
141
- | Edit this and following | `PUT` the series with `until` set to the day before (and `count: null`), `POST` a new series, `PUT` later detached events to relink them |
142
- | Delete | single: `PUT` with `excludedDates` · following: `PUT` with `until`, `DELETE` its later detached events · all: `DELETE` detached events, then the series · plain: `DELETE /events/:id` |
143
- | Settings, colors | `PATCH /preferences`, `POST /colors`, `DELETE /colors/:rrggbb` |
144
- | Sign-in, teams, invitations | `/auth/*`, `/calendars`, `/teams/*`, `/invitations/*`, see the OpenAPI file |
145
-
146
- Before editing "following" or "all" of a series, the component loads its detached events with `GET /events?seriesId=…`.
147
-
148
- ### Rules for the backend
149
-
150
- - **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.
151
- - **Errors:** always `{ code, message }`. Known codes such as `invalidCredentials`, `emailTaken`, `forbidden`, `lastOwner` are shown translated, others with `message`.
152
- - **Language:** every request carries `Accept-Language`. Use it, or the stored `locale`, for emails.
153
- - **Email links:** point them at the host page with the screen as parameter, e.g. `https://host.example/calendar?calendarPath=%2Freset-password%3Ftoken%3D…`.
154
-
155
- Building, the test backend and all internals are described in German in [DEVELOPMENT.md](DEVELOPMENT.md).
80
+ | [Developer Guide](DEVELOPER_GUIDE.md) | Embedding, all options and features, the configuration file, languages, sign-in, data adapters, exported types, and what your backend has to provide |
81
+ | [`api/openapi.yaml`](api/openapi.yaml) | The REST contract for your own backend (OpenAPI 3.1), also shipped as `@rokoyfa/calendar/openapi.yaml` |
82
+ | [`schema/calendar-config.schema.json`](schema/calendar-config.schema.json) | JSON Schema for configuration files, also shipped as `@rokoyfa/calendar/config.schema.json` |
83
+ | [CHANGELOG.md](CHANGELOG.md) | Changes per version |
84
+ | [DEVELOPMENT.md](DEVELOPMENT.md) | Working on the calendar itself: building, the test backend and internals (in German) |
85
+
86
+ **Demo:** [`demo/cdn.html`](demo/cdn.html) shows local mode with an event log, a dark German month view and a compact widget. Download it and open it in a browser, it loads the published package from jsDelivr.
156
87
 
157
88
  ## License
158
89
 
package/api/openapi.yaml CHANGED
@@ -34,6 +34,11 @@ tags:
34
34
  - name: Teams
35
35
  - name: Invitations
36
36
  - name: Preferences
37
+ - name: Chat
38
+ description: |
39
+ One chat per event in team calendars, for recurring events one per occurrence (`date` = original date of the occurrence).
40
+ Live updates come over a WebSocket at `{base}/chat/socket`, see the README section “Event chat”.
41
+ - name: Holidays
37
42
  paths:
38
43
  /auth/me:
39
44
  get:
@@ -73,7 +78,7 @@ paths:
73
78
  properties:
74
79
  password: { type: string }
75
80
  responses:
76
- '204': { description: Deleted, session cookie cleared }
81
+ '204': { description: 'Deleted, session cookie cleared' }
77
82
  '403': { $ref: '#/components/responses/Problem' }
78
83
  '409': { $ref: '#/components/responses/Problem' }
79
84
  /auth/me/password:
@@ -167,7 +172,7 @@ paths:
167
172
  summary: Sign out
168
173
  security: []
169
174
  responses:
170
- '204': { description: Session ended, cookie cleared }
175
+ '204': { description: 'Session ended, cookie cleared' }
171
176
  /auth/password-reset:
172
177
  post:
173
178
  tags: [Auth]
@@ -274,6 +279,93 @@ paths:
274
279
  '400': { $ref: '#/components/responses/Problem' }
275
280
  '403': { $ref: '#/components/responses/Problem' }
276
281
  '404': { $ref: '#/components/responses/Problem' }
282
+ /events/search:
283
+ get:
284
+ tags: [Events]
285
+ summary: Search events
286
+ description: |
287
+ Events and series whose title, location, description or links contain `q` (case-insensitive), in the given calendars.
288
+ Optional for custom backends: without it the component searches the events of the last and next year itself.
289
+ parameters:
290
+ - { name: q, in: query, required: true, schema: { type: string, minLength: 2 } }
291
+ - name: calendarId
292
+ in: query
293
+ required: true
294
+ schema: { type: array, items: { type: string } }
295
+ style: form
296
+ explode: true
297
+ responses:
298
+ '200':
299
+ description: Matching events, at most 50
300
+ content:
301
+ application/json:
302
+ schema: { type: array, items: { $ref: '#/components/schemas/CalendarEvent' } }
303
+ '400': { $ref: '#/components/responses/Problem' }
304
+ /events/{id}/response:
305
+ parameters:
306
+ - { name: id, in: path, required: true, schema: { type: string } }
307
+ post:
308
+ tags: [Events]
309
+ summary: Answer an event invitation
310
+ description: Sets the status of the attendee whose email is the signed-in user's. Allowed for every attendee with read access. `403` if the user is not an attendee.
311
+ requestBody:
312
+ required: true
313
+ content:
314
+ application/json:
315
+ schema:
316
+ type: object
317
+ required: [status]
318
+ properties:
319
+ status: { $ref: '#/components/schemas/AttendeeStatus' }
320
+ responses:
321
+ '200': { $ref: '#/components/responses/Event' }
322
+ '400': { $ref: '#/components/responses/Problem' }
323
+ '403': { $ref: '#/components/responses/Problem' }
324
+ '404': { $ref: '#/components/responses/Problem' }
325
+ /events/{id}/reminders:
326
+ parameters:
327
+ - { name: id, in: path, required: true, schema: { type: string } }
328
+ put:
329
+ tags: [Events]
330
+ summary: Set the own reminders of an event
331
+ description: Changes only the reminders of the signed-in user. Allowed with read access, so members without edit rights can be reminded too.
332
+ requestBody:
333
+ required: true
334
+ content:
335
+ application/json:
336
+ schema:
337
+ type: object
338
+ required: [reminders]
339
+ properties:
340
+ reminders: { type: array, maxItems: 5, items: { type: integer, minimum: 0, maximum: 40320 } }
341
+ responses:
342
+ '200': { $ref: '#/components/responses/Event' }
343
+ '400': { $ref: '#/components/responses/Problem' }
344
+ '404': { $ref: '#/components/responses/Problem' }
345
+ /events/respond:
346
+ post:
347
+ tags: [Events]
348
+ summary: Answer an invitation from an email link
349
+ description: No session needed. The token comes from the invitation email (`/respond?status=…&token=…` on the host page) and stands for one attendee of one event.
350
+ security: []
351
+ requestBody:
352
+ required: true
353
+ content:
354
+ application/json:
355
+ schema:
356
+ type: object
357
+ required: [token, status]
358
+ properties:
359
+ token: { type: string }
360
+ status: { type: string, enum: [accepted, tentative, declined] }
361
+ responses:
362
+ '200':
363
+ description: Saved
364
+ content:
365
+ application/json:
366
+ schema: { $ref: '#/components/schemas/EventResponse' }
367
+ '400': { $ref: '#/components/responses/Problem' }
368
+ '410': { $ref: '#/components/responses/Problem' }
277
369
  /events/{id}:
278
370
  parameters:
279
371
  - { name: id, in: path, required: true, schema: { type: string } }
@@ -331,6 +423,140 @@ paths:
331
423
  responses:
332
424
  '201': { $ref: '#/components/responses/CalendarSummary' }
333
425
  '400': { $ref: '#/components/responses/Problem' }
426
+ /events/{id}/chat:
427
+ parameters:
428
+ - { name: id, in: path, required: true, description: 'Event id, for detached occurrences the id of their series', schema: { type: string } }
429
+ - { name: date, in: query, required: false, description: 'Required for recurring events: the original date of the occurrence. Not allowed for single events.', schema: { $ref: '#/components/schemas/ISODate' } }
430
+ get:
431
+ tags: [Chat]
432
+ summary: Messages of an event chat
433
+ description: Oldest first. Without `before` the newest page. Every member of the team calendar may read. `400` with `personalTeam` in personal calendars.
434
+ parameters:
435
+ - { name: before, in: query, required: false, description: 'Message id, returns messages older than this one', schema: { type: string } }
436
+ - { name: limit, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 100, default: 50 } }
437
+ responses:
438
+ '200':
439
+ description: Page of messages
440
+ content:
441
+ application/json:
442
+ schema: { $ref: '#/components/schemas/ChatPage' }
443
+ '400': { $ref: '#/components/responses/Problem' }
444
+ '404': { $ref: '#/components/responses/Problem' }
445
+ post:
446
+ tags: [Chat]
447
+ summary: Write a message
448
+ description: Every member of the team calendar may write. Marks the chat as read for the author, sends `message.created` over the socket to all members and an email to attendees who want it.
449
+ requestBody:
450
+ required: true
451
+ content:
452
+ application/json:
453
+ schema: { type: object, required: [text], properties: { text: { type: string, minLength: 1, maxLength: 2000 } } }
454
+ responses:
455
+ '201':
456
+ description: Created
457
+ content:
458
+ application/json:
459
+ schema: { $ref: '#/components/schemas/ChatMessage' }
460
+ '400': { $ref: '#/components/responses/Problem' }
461
+ '404': { $ref: '#/components/responses/Problem' }
462
+ /events/{id}/chat/read:
463
+ parameters:
464
+ - { name: id, in: path, required: true, schema: { type: string } }
465
+ - { name: date, in: query, required: false, schema: { $ref: '#/components/schemas/ISODate' } }
466
+ post:
467
+ tags: [Chat]
468
+ summary: Mark the chat as read
469
+ responses:
470
+ '204': { description: Marked }
471
+ /chat/messages/{messageId}:
472
+ parameters:
473
+ - { name: messageId, in: path, required: true, schema: { type: string } }
474
+ patch:
475
+ tags: [Chat]
476
+ summary: Edit an own message
477
+ requestBody:
478
+ required: true
479
+ content:
480
+ application/json:
481
+ schema: { type: object, required: [text], properties: { text: { type: string, minLength: 1, maxLength: 2000 } } }
482
+ responses:
483
+ '200':
484
+ description: Edited, `editedAt` is set. Sends `message.updated` over the socket.
485
+ content:
486
+ application/json:
487
+ schema: { $ref: '#/components/schemas/ChatMessage' }
488
+ '403': { $ref: '#/components/responses/Problem' }
489
+ '404': { $ref: '#/components/responses/Problem' }
490
+ delete:
491
+ tags: [Chat]
492
+ summary: Delete a message
493
+ description: Own messages, or any message with `manage_calendars` (owner, admin, manager). Sends `message.deleted` over the socket.
494
+ responses:
495
+ '204': { description: Deleted }
496
+ '403': { $ref: '#/components/responses/Problem' }
497
+ '404': { $ref: '#/components/responses/Problem' }
498
+ /chat/unread:
499
+ get:
500
+ tags: [Chat]
501
+ summary: Unread messages per chat
502
+ description: Messages of others newer than the user's last read time, only chats with at least one.
503
+ parameters:
504
+ - name: calendarId
505
+ in: query
506
+ required: true
507
+ style: form
508
+ explode: true
509
+ schema: { type: array, items: { type: string } }
510
+ responses:
511
+ '200':
512
+ description: Counts
513
+ content:
514
+ application/json:
515
+ schema: { type: array, items: { $ref: '#/components/schemas/ChatUnread' } }
516
+ /calendars/{calendarId}/feed:
517
+ parameters:
518
+ - { $ref: '#/components/parameters/CalendarId' }
519
+ get:
520
+ tags: [Calendars]
521
+ summary: Own subscription link
522
+ responses:
523
+ '200':
524
+ description: Link or null
525
+ content:
526
+ application/json:
527
+ schema: { type: object, required: [url], properties: { url: { oneOf: [{ type: string, format: uri }, { type: 'null' }] } } }
528
+ '404': { $ref: '#/components/responses/Problem' }
529
+ post:
530
+ tags: [Calendars]
531
+ summary: Create a new subscription link
532
+ description: Replaces an existing link of this user for this calendar.
533
+ responses:
534
+ '201':
535
+ description: New link
536
+ content:
537
+ application/json:
538
+ schema: { type: object, required: [url], properties: { url: { type: string, format: uri } } }
539
+ '404': { $ref: '#/components/responses/Problem' }
540
+ delete:
541
+ tags: [Calendars]
542
+ summary: End the subscription
543
+ responses:
544
+ '204': { description: Ended }
545
+ /feeds/{token}.ics:
546
+ parameters:
547
+ - { name: token, in: path, required: true, schema: { type: string } }
548
+ get:
549
+ tags: [Calendars]
550
+ summary: Calendar subscription
551
+ description: No session needed. The calendar as iCalendar with the subscriber's own reminders as alarms. `404` when the token is unknown or the user is no longer a member.
552
+ security: []
553
+ responses:
554
+ '200':
555
+ description: iCalendar
556
+ content:
557
+ text/calendar:
558
+ schema: { type: string }
559
+ '404': { description: Unknown link }
334
560
  /calendars/{calendarId}:
335
561
  parameters:
336
562
  - { $ref: '#/components/parameters/CalendarId' }
@@ -597,6 +823,28 @@ paths:
597
823
  responses:
598
824
  '204': { description: Declined }
599
825
  '404': { $ref: '#/components/responses/Problem' }
826
+ /holidays:
827
+ get:
828
+ tags: [Holidays]
829
+ summary: Public holidays of a region
830
+ description: |
831
+ Optional. Only called with `holiday-source="backend"`. Without it, or when this request fails, the component computes holidays itself.
832
+ Return the public holidays (days off) between `from` and `to` inclusive, with names in `lang`.
833
+ parameters:
834
+ - { name: from, in: query, required: true, schema: { $ref: '#/components/schemas/ISODate' } }
835
+ - { name: to, in: query, required: true, schema: { $ref: '#/components/schemas/ISODate' } }
836
+ - name: region
837
+ in: query
838
+ required: true
839
+ description: Country, optionally with a subdivision, e.g. `DE`, `DE-NW`, `US-CA`
840
+ schema: { type: string, pattern: '^[A-Z]{2}(-[A-Z0-9]{1,6})?$' }
841
+ - { name: lang, in: query, required: true, schema: { type: string, examples: [de] } }
842
+ responses:
843
+ '200':
844
+ description: Holidays
845
+ content:
846
+ application/json:
847
+ schema: { type: array, items: { $ref: '#/components/schemas/PublicHoliday' } }
600
848
  /preferences:
601
849
  get:
602
850
  tags: [Preferences]
@@ -618,6 +866,12 @@ paths:
618
866
  defaultView: { $ref: '#/components/schemas/CalendarView' }
619
867
  mobileDefaultView: { $ref: '#/components/schemas/CalendarView' }
620
868
  locale: { $ref: '#/components/schemas/Locale' }
869
+ timeZone: { $ref: '#/components/schemas/PreferredTimeZone' }
870
+ holidays: { $ref: '#/components/schemas/HolidaySetting' }
871
+ emailInvites: { type: boolean }
872
+ emailChanges: { type: boolean }
873
+ emailReminders: { type: boolean }
874
+ emailChat: { type: boolean }
621
875
  responses:
622
876
  '200': { $ref: '#/components/responses/Preferences' }
623
877
  '400': { $ref: '#/components/responses/Problem' }
@@ -787,7 +1041,18 @@ components:
787
1041
  type: object
788
1042
  required: [title, startDate, start, endDate, end, description, color, recurrence, excludedDates, seriesId, originalDate]
789
1043
  properties:
1044
+ uid:
1045
+ type: string
1046
+ maxLength: 255
1047
+ description: Stable id for iCalendar exchange. Kept when importing again; the backend creates one if missing. Detached occurrences share the uid of their series.
790
1048
  title: { type: string, minLength: 1, maxLength: 100 }
1049
+ location: { type: string, maxLength: 200, default: '' }
1050
+ links:
1051
+ type: array
1052
+ maxItems: 10
1053
+ default: []
1054
+ items: { $ref: '#/components/schemas/EventLink' }
1055
+ description: Website and other links. Only http and https addresses are accepted.
791
1056
  startDate: { $ref: '#/components/schemas/ISODate' }
792
1057
  start: { $ref: '#/components/schemas/Time' }
793
1058
  endDate: { $ref: '#/components/schemas/ISODate' }
@@ -810,6 +1075,35 @@ components:
810
1075
  originalDate:
811
1076
  description: For a detached occurrence, its original date in the series
812
1077
  oneOf: [{ $ref: '#/components/schemas/ISODate' }, { type: 'null' }]
1078
+ reminders:
1079
+ type: array
1080
+ maxItems: 5
1081
+ default: []
1082
+ items: { type: integer, minimum: 0, maximum: 40320 }
1083
+ description: |
1084
+ Minutes before the start (for all-day events before 00:00 of the first day) at which the signed-in user wants to be reminded.
1085
+ Personal: store them per user and return only the caller's own reminders. Changing them never affects other members.
1086
+ attendees:
1087
+ type: array
1088
+ maxItems: 100
1089
+ default: []
1090
+ items: { $ref: '#/components/schemas/Attendee' }
1091
+ EventLink:
1092
+ type: object
1093
+ required: [url]
1094
+ properties:
1095
+ url: { type: string, format: uri, maxLength: 2000, pattern: '^https?://' }
1096
+ label: { type: string, maxLength: 100, default: '' }
1097
+ AttendeeStatus:
1098
+ type: string
1099
+ enum: [needsAction, accepted, tentative, declined]
1100
+ Attendee:
1101
+ type: object
1102
+ required: [email, name, status]
1103
+ properties:
1104
+ email: { type: string, format: email }
1105
+ name: { type: string }
1106
+ status: { $ref: '#/components/schemas/AttendeeStatus' }
813
1107
  CalendarEvent:
814
1108
  allOf:
815
1109
  - $ref: '#/components/schemas/EventInput'
@@ -909,11 +1203,73 @@ components:
909
1203
  description: '`auto` or a BCP 47 language tag such as `en-US`, `en-GB`, `de-DE`'
910
1204
  maxLength: 35
911
1205
  pattern: '^(auto|[a-z]{2,3}(-[A-Za-z0-9]{2,8})*)$'
1206
+ HolidaySetting:
1207
+ type: string
1208
+ default: auto
1209
+ description: '`auto` (region given by the host, otherwise from the language), `off`, or a region such as `DE-NW`.'
1210
+ pattern: '^(auto|off|[A-Z]{2}(-[A-Z0-9]{1,6})?)$'
1211
+ ChatMessage:
1212
+ type: object
1213
+ required: [id, calendarId, eventId, occurrenceDate, author, text, createdAt, editedAt]
1214
+ properties:
1215
+ id: { type: string }
1216
+ calendarId: { type: string }
1217
+ eventId: { type: string }
1218
+ occurrenceDate: { oneOf: [{ $ref: '#/components/schemas/ISODate' }, { type: 'null' }] }
1219
+ author:
1220
+ description: null when the account was deleted
1221
+ oneOf: [{ type: object, required: [id, name], properties: { id: { type: string }, name: { type: string } } }, { type: 'null' }]
1222
+ text: { type: string }
1223
+ createdAt: { type: string, format: date-time }
1224
+ editedAt: { oneOf: [{ type: string, format: date-time }, { type: 'null' }] }
1225
+ ChatPage:
1226
+ type: object
1227
+ required: [messages, hasMore]
1228
+ properties:
1229
+ messages: { type: array, items: { $ref: '#/components/schemas/ChatMessage' } }
1230
+ hasMore: { type: boolean }
1231
+ ChatUnread:
1232
+ type: object
1233
+ required: [eventId, occurrenceDate, count]
1234
+ properties:
1235
+ eventId: { type: string }
1236
+ occurrenceDate: { oneOf: [{ $ref: '#/components/schemas/ISODate' }, { type: 'null' }] }
1237
+ count: { type: integer, minimum: 1 }
1238
+ EventResponse:
1239
+ type: object
1240
+ required: [title, location, startDate, start, endDate, end, allDay, timeZone, recurring, status]
1241
+ properties:
1242
+ title: { type: string }
1243
+ location: { type: string }
1244
+ startDate: { $ref: '#/components/schemas/ISODate' }
1245
+ start: { $ref: '#/components/schemas/Time' }
1246
+ endDate: { $ref: '#/components/schemas/ISODate' }
1247
+ end: { $ref: '#/components/schemas/Time' }
1248
+ allDay: { type: boolean }
1249
+ timeZone: { oneOf: [{ type: string }, { type: 'null' }] }
1250
+ recurring: { type: boolean }
1251
+ status: { $ref: '#/components/schemas/AttendeeStatus' }
1252
+ PublicHoliday:
1253
+ type: object
1254
+ required: [date, name]
1255
+ properties:
1256
+ date: { $ref: '#/components/schemas/ISODate' }
1257
+ name: { type: string }
1258
+ PreferredTimeZone:
1259
+ type: string
1260
+ default: auto
1261
+ description: '`auto` (zone given by the host, otherwise the system zone) or an IANA zone such as `Europe/Berlin`. Events are shown in this zone.'
912
1262
  Preferences:
913
1263
  type: object
914
- required: [theme, defaultView, mobileDefaultView, locale]
1264
+ required: [theme, defaultView, mobileDefaultView, locale, timeZone, holidays, emailInvites, emailChanges, emailReminders, emailChat]
915
1265
  properties:
916
1266
  theme: { $ref: '#/components/schemas/Theme' }
917
1267
  defaultView: { $ref: '#/components/schemas/CalendarView' }
918
1268
  mobileDefaultView: { $ref: '#/components/schemas/CalendarView' }
919
1269
  locale: { $ref: '#/components/schemas/Locale' }
1270
+ timeZone: { $ref: '#/components/schemas/PreferredTimeZone' }
1271
+ holidays: { $ref: '#/components/schemas/HolidaySetting' }
1272
+ emailInvites: { type: boolean, default: true, description: Email when someone invites the user to an event }
1273
+ emailChanges: { type: boolean, default: true, description: Email when an event the user is invited to changes or is cancelled }
1274
+ emailReminders: { type: boolean, default: false, description: Emails at the user's own reminder times }
1275
+ emailChat: { type: boolean, default: true, description: Email about new chat messages of events the user is invited to }