@rokoyfa/calendar 1.2.0 → 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.
- package/CHANGELOG.md +22 -0
- package/DEVELOPER_GUIDE.md +1045 -0
- package/README.md +41 -190
- package/api/openapi.yaml +395 -4
- package/demo/calendar.config.jsonc +183 -0
- package/demo/calendar.config.yaml +180 -0
- package/dist-lib/cdn/browser-BSbYkIQu.js +130 -0
- package/dist-lib/cdn/browser-BSbYkIQu.js.map +1 -0
- package/dist-lib/cdn/calendar-widget.js +14 -11
- package/dist-lib/cdn/calendar-widget.js.map +1 -1
- package/dist-lib/cdn/de-Dqga3QZG.js +2 -0
- package/dist-lib/cdn/de-Dqga3QZG.js.map +1 -0
- package/dist-lib/cdn/es-BWSfTMjh.js +2 -0
- package/dist-lib/cdn/es-BWSfTMjh.js.map +1 -0
- package/dist-lib/cdn/fr-N9gwLjVq.js +2 -0
- package/dist-lib/cdn/fr-N9gwLjVq.js.map +1 -0
- package/dist-lib/cdn/it-B5Ib2xLn.js +2 -0
- package/dist-lib/cdn/it-B5Ib2xLn.js.map +1 -0
- package/dist-lib/cdn/nl-CjI7Uc8l.js +2 -0
- package/dist-lib/cdn/nl-CjI7Uc8l.js.map +1 -0
- package/dist-lib/cdn/pl-FRu3yQhc.js +2 -0
- package/dist-lib/cdn/pl-FRu3yQhc.js.map +1 -0
- package/dist-lib/cdn/pt-DBKJ-3Is.js +2 -0
- package/dist-lib/cdn/pt-DBKJ-3Is.js.map +1 -0
- package/dist-lib/npm/{de-Cuz-uz3s.js → de-DhWrY8Ae.js} +111 -3
- package/dist-lib/npm/de-DhWrY8Ae.js.map +1 -0
- package/dist-lib/npm/{es-BnRzdU90.js → es-Bj8leuD5.js} +111 -3
- package/dist-lib/npm/es-Bj8leuD5.js.map +1 -0
- package/dist-lib/npm/{fr-B-nmvStg.js → fr-DzAFZ0jh.js} +111 -3
- package/dist-lib/npm/fr-DzAFZ0jh.js.map +1 -0
- package/dist-lib/npm/index.js +3876 -1400
- package/dist-lib/npm/index.js.map +1 -1
- package/dist-lib/npm/{it-DMTpE4GO.js → it-lEmGP5yo.js} +111 -3
- package/dist-lib/npm/it-lEmGP5yo.js.map +1 -0
- package/dist-lib/npm/{nl-DQkyEt9Z.js → nl-d1h63dvm.js} +111 -3
- package/dist-lib/npm/nl-d1h63dvm.js.map +1 -0
- package/dist-lib/npm/{pl-CcjU41yx.js → pl-DynFKadb.js} +111 -3
- package/dist-lib/npm/pl-DynFKadb.js.map +1 -0
- package/dist-lib/npm/{pt-Dulais2f.js → pt-foL7jDsE.js} +111 -3
- package/dist-lib/npm/pt-foL7jDsE.js.map +1 -0
- package/dist-lib/npm/types/components/Icons.d.ts +2 -0
- package/dist-lib/npm/types/config/routes.d.ts +1 -0
- package/dist-lib/npm/types/context/HostBridge.d.ts +38 -0
- package/dist-lib/npm/types/context/HostContext.d.ts +39 -2
- package/dist-lib/npm/types/data/restDataSource.d.ts +3 -1
- package/dist-lib/npm/types/data/tenantDataSource.d.ts +3 -1
- package/dist-lib/npm/types/data/types.d.ts +4 -1
- package/dist-lib/npm/types/features/attachments/components/AttachmentsField.d.ts +8 -0
- package/dist-lib/npm/types/features/attachments/hooks/useAttachments.d.ts +11 -0
- package/dist-lib/npm/types/features/attachments/index.d.ts +2 -0
- package/dist-lib/npm/types/features/authorization/components/account/DataExportSection.d.ts +1 -0
- package/dist-lib/npm/types/features/authorization/hooks/useAuth.d.ts +1 -0
- package/dist-lib/npm/types/features/authorization/index.d.ts +1 -0
- package/dist-lib/npm/types/features/authorization/repositories/HostTokenAuthRepository.d.ts +1 -0
- package/dist-lib/npm/types/features/authorization/repositories/RemoteAuthRepository.d.ts +1 -0
- package/dist-lib/npm/types/features/authorization/types/auth.d.ts +2 -0
- package/dist-lib/npm/types/features/calendar/components/Calendar.d.ts +7 -1
- package/dist-lib/npm/types/features/calendar/components/CalendarHeader.d.ts +3 -1
- package/dist-lib/npm/types/features/calendar/constants/views.d.ts +2 -2
- package/dist-lib/npm/types/features/calendar/hooks/useEventNavigation.d.ts +4 -0
- package/dist-lib/npm/types/features/calendar/hooks/useHostController.d.ts +2 -0
- package/dist-lib/npm/types/features/calendar/hooks/useLiveEvents.d.ts +11 -0
- package/dist-lib/npm/types/features/calendar/hooks/useSegmentAttributes.d.ts +2 -0
- package/dist-lib/npm/types/features/calendar/utils/eventLabels.d.ts +4 -0
- package/dist-lib/npm/types/features/calendars/components/settings/ShareSection.d.ts +4 -0
- package/dist-lib/npm/types/features/calendars/components/settings/TrashSection.d.ts +4 -0
- package/dist-lib/npm/types/features/calendars/index.d.ts +1 -1
- package/dist-lib/npm/types/features/calendars/repositories/RemoteCalendarRepository.d.ts +3 -0
- package/dist-lib/npm/types/features/calendars/types/calendar.d.ts +3 -0
- package/dist-lib/npm/types/features/calendars/utils/permissions.d.ts +4 -0
- package/dist-lib/npm/types/features/categories/components/CategoriesSection.d.ts +6 -0
- package/dist-lib/npm/types/features/categories/components/CategoryField.d.ts +9 -0
- package/dist-lib/npm/types/features/categories/components/CategoryFilterModal.d.ts +10 -0
- package/dist-lib/npm/types/features/categories/hooks/useCategories.d.ts +9 -0
- package/dist-lib/npm/types/features/categories/index.d.ts +4 -0
- package/dist-lib/npm/types/features/events/components/DeleteEventModal.d.ts +2 -1
- package/dist-lib/npm/types/features/events/components/EventModal.d.ts +11 -3
- package/dist-lib/npm/types/features/events/hooks/useEvents.d.ts +4 -1
- package/dist-lib/npm/types/features/events/index.d.ts +2 -2
- package/dist-lib/npm/types/features/events/utils/icalExchange.d.ts +4 -1
- package/dist-lib/npm/types/features/storage/index.d.ts +6 -1
- package/dist-lib/npm/types/features/storage/repositories/LocalCategoryRepository.d.ts +14 -0
- package/dist-lib/npm/types/features/storage/repositories/LocalEventRepository.d.ts +8 -2
- package/dist-lib/npm/types/features/storage/repositories/RemoteAttachmentRepository.d.ts +11 -0
- package/dist-lib/npm/types/features/storage/repositories/RemoteCategoryRepository.d.ts +10 -0
- package/dist-lib/npm/types/features/storage/repositories/RemoteChatRepository.d.ts +2 -1
- package/dist-lib/npm/types/features/storage/repositories/RemoteEventRepository.d.ts +9 -3
- package/dist-lib/npm/types/features/storage/repositories/RemoteSharedCalendarRepository.d.ts +9 -0
- package/dist-lib/npm/types/features/storage/types/storage.d.ts +30 -2
- package/dist-lib/npm/types/features/storage/utils/liveSocket.d.ts +10 -0
- package/dist-lib/npm/types/i18n/messages/en/calendar.d.ts +9 -0
- package/dist-lib/npm/types/i18n/messages/en/calendars.d.ts +44 -0
- package/dist-lib/npm/types/i18n/messages/en/core.d.ts +1 -0
- package/dist-lib/npm/types/i18n/messages/en/events.d.ts +37 -0
- package/dist-lib/npm/types/i18n/messages/en/index.d.ts +99 -1
- package/dist-lib/npm/types/i18n/messages/en/settings.d.ts +7 -0
- package/dist-lib/npm/types/i18n/messages/index.d.ts +99 -1
- package/dist-lib/npm/types/lib/CalendarWidget.d.ts +1 -1
- package/dist-lib/npm/types/lib/IsolatedRoot.d.ts +3 -1
- package/dist-lib/npm/types/lib/appearance.d.ts +3 -0
- package/dist-lib/npm/types/lib/config.d.ts +16 -27
- package/dist-lib/npm/types/lib/configFile.d.ts +6 -0
- package/dist-lib/npm/types/lib/defaults.d.ts +29 -1
- package/dist-lib/npm/types/lib/element.d.ts +15 -1
- package/dist-lib/npm/types/lib/handle.d.ts +15 -0
- package/dist-lib/npm/types/lib/index.d.ts +6 -2
- package/dist-lib/npm/types/lib/options.d.ts +47 -0
- package/dist-lib/npm/types/lib/useCalendarOptions.d.ts +11 -0
- package/dist-lib/npm/types/pages/SharedCalendarPage.d.ts +1 -0
- package/dist-lib/npm/types/utils/api.d.ts +1 -0
- package/dist-lib/npm/types/utils/appError.d.ts +1 -1
- package/dist-lib/npm/types/utils/attachment.d.ts +31 -0
- package/dist-lib/npm/types/utils/calendarView.d.ts +1 -0
- package/dist-lib/npm/types/utils/category.d.ts +18 -0
- package/dist-lib/npm/types/utils/conflict.d.ts +1 -0
- package/dist-lib/npm/types/utils/dataExport.d.ts +13 -0
- package/dist-lib/npm/types/utils/event.d.ts +6 -1
- package/dist-lib/npm/types/utils/eventChange.d.ts +13 -0
- package/dist-lib/npm/types/utils/ical.d.ts +6 -1
- package/dist-lib/npm/types/utils/sharedCalendar.d.ts +13 -0
- package/dist-lib/npm/types/utils/trash.d.ts +14 -0
- package/package.json +8 -2
- package/schema/calendar-config.schema.json +297 -0
- package/dist-lib/cdn/de-BjzK4Pgn.js +0 -2
- package/dist-lib/cdn/de-BjzK4Pgn.js.map +0 -1
- package/dist-lib/cdn/es-TA5DvEsw.js +0 -2
- package/dist-lib/cdn/es-TA5DvEsw.js.map +0 -1
- package/dist-lib/cdn/fr-Dx-nmhQ7.js +0 -2
- package/dist-lib/cdn/fr-Dx-nmhQ7.js.map +0 -1
- package/dist-lib/cdn/it-D_2eA3dT.js +0 -2
- package/dist-lib/cdn/it-D_2eA3dT.js.map +0 -1
- package/dist-lib/cdn/nl-dC1zae2Z.js +0 -2
- package/dist-lib/cdn/nl-dC1zae2Z.js.map +0 -1
- package/dist-lib/cdn/pl-9TYRPoy1.js +0 -2
- package/dist-lib/cdn/pl-9TYRPoy1.js.map +0 -1
- package/dist-lib/cdn/pt-CvBN-qx1.js +0 -2
- package/dist-lib/cdn/pt-CvBN-qx1.js.map +0 -1
- package/dist-lib/npm/de-Cuz-uz3s.js.map +0 -1
- package/dist-lib/npm/es-BnRzdU90.js.map +0 -1
- package/dist-lib/npm/fr-B-nmvStg.js.map +0 -1
- package/dist-lib/npm/it-DMTpE4GO.js.map +0 -1
- package/dist-lib/npm/nl-DQkyEt9Z.js.map +0 -1
- package/dist-lib/npm/pl-CcjU41yx.js.map +0 -1
- package/dist-lib/npm/pt-Dulais2f.js.map +0 -1
|
@@ -0,0 +1,1045 @@
|
|
|
1
|
+
# Developer Guide
|
|
2
|
+
|
|
3
|
+
Everything you need to put `@rokoyfa/calendar` on your page: embedding, all options, the configuration file, the types the package exports, and what a backend has to provide. For a first look see the [README](README.md).
|
|
4
|
+
|
|
5
|
+
**Contents**
|
|
6
|
+
|
|
7
|
+
1. [Embedding](#1-embedding)
|
|
8
|
+
2. [Options](#2-options)
|
|
9
|
+
3. [Features](#3-features)
|
|
10
|
+
4. [Configuration file](#4-configuration-file)
|
|
11
|
+
5. [Languages and texts](#5-languages-and-texts)
|
|
12
|
+
6. [Reacting to changes](#6-reacting-to-changes)
|
|
13
|
+
7. [Sign-in and tenants](#7-sign-in-and-tenants)
|
|
14
|
+
8. [Data adapters](#8-data-adapters)
|
|
15
|
+
9. [Exported types](#9-exported-types)
|
|
16
|
+
10. [Backend](#10-backend)
|
|
17
|
+
11. [Event chat](#11-event-chat)
|
|
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)
|
|
28
|
+
|
|
29
|
+
## 1. Embedding
|
|
30
|
+
|
|
31
|
+
There are two ways to embed the calendar. Both render the same component and take the same options.
|
|
32
|
+
|
|
33
|
+
### Web component, for any website
|
|
34
|
+
|
|
35
|
+
One script, no build step. React is bundled.
|
|
36
|
+
|
|
37
|
+
```html
|
|
38
|
+
<script type="module" src="https://cdn.jsdelivr.net/npm/@rokoyfa/calendar@1/dist-lib/cdn/calendar-widget.js"></script>
|
|
39
|
+
|
|
40
|
+
<calendar-widget style="height: 700px"></calendar-widget>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The script registers `<calendar-widget>`. Options are attributes in kebab-case (`initial-view="month"`). Values that are not text (functions, objects) are set as properties on the element, before or after the script has loaded:
|
|
44
|
+
|
|
45
|
+
```js
|
|
46
|
+
const calendar = document.querySelector('calendar-widget')
|
|
47
|
+
calendar.getUserToken = async () => (await fetch('/calendar-token')).text()
|
|
48
|
+
calendar.config = { features: { chat: false } }
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
When hosting the script yourself, copy the whole `dist-lib/cdn` folder. Languages other than English, the holiday data and the YAML parser are separate files next to `calendar-widget.js` that are loaded on demand.
|
|
52
|
+
|
|
53
|
+
To register the element under another name, or to control when it is registered, use the npm package:
|
|
54
|
+
|
|
55
|
+
```js
|
|
56
|
+
import { defineCalendarElement, CalendarElement } from '@rokoyfa/calendar'
|
|
57
|
+
|
|
58
|
+
defineCalendarElement('team-calendar')
|
|
59
|
+
console.log(CalendarElement.version)
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### React component
|
|
63
|
+
|
|
64
|
+
Needs React 19.
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
npm install @rokoyfa/calendar
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
```tsx
|
|
71
|
+
import { Calendar } from '@rokoyfa/calendar'
|
|
72
|
+
|
|
73
|
+
<Calendar style={{ height: 700 }} />
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### What the host page should know
|
|
77
|
+
|
|
78
|
+
- **Height.** Give the calendar a height, it fills its box and scrolls inside. Without one it grows with its content.
|
|
79
|
+
- **Styles.** The calendar renders into a Shadow DOM. Your CSS does not reach in, its CSS does not leak out, and no stylesheet has to be imported.
|
|
80
|
+
- **Responsive.** The layout follows the width of the calendar, not of the window. A narrow calendar on a wide screen shows the phone layout.
|
|
81
|
+
- **Several calendars** on one page are independent, each with its own view and dialogs. In local mode they share the browser's storage.
|
|
82
|
+
- **Address bar.** By default (`routing: memory`) the calendar never touches the address of your page.
|
|
83
|
+
|
|
84
|
+
## 2. Options
|
|
85
|
+
|
|
86
|
+
Every option can be given in three ways: as a React prop, as an attribute of the web component, or in a [configuration file](#4-configuration-file).
|
|
87
|
+
|
|
88
|
+
### Data
|
|
89
|
+
|
|
90
|
+
| Prop | Attribute | Default | |
|
|
91
|
+
| --- | --- | --- | --- |
|
|
92
|
+
| `storageMode` | `storage-mode` | `local` | `local` keeps events in the visitor's browser, `remote` in your backend. With the `auth` feature the sign-in decides: signed-in users use the backend, guests the browser |
|
|
93
|
+
| `apiBaseUrl` | `api-base-url` | `/api` | Base URL of your backend, relative or absolute |
|
|
94
|
+
| `apiTimeoutMs` | `api-timeout-ms` | `10000` | Time limit per request in milliseconds |
|
|
95
|
+
| `tenant` | `tenant` | – | Tenant of a multi-tenant backend, see [Sign-in and tenants](#7-sign-in-and-tenants) |
|
|
96
|
+
| `getUserToken` | property `getUserToken` | – | Sign-in through your own page, see [Sign-in and tenants](#7-sign-in-and-tenants) |
|
|
97
|
+
| `dataSource` | property `dataSource` | – | Your own data adapter, see [Data adapters](#8-data-adapters). Replaces the five options above |
|
|
98
|
+
|
|
99
|
+
### Features and views
|
|
100
|
+
|
|
101
|
+
| Prop | Attribute | Default | |
|
|
102
|
+
| --- | --- | --- | --- |
|
|
103
|
+
| `features` | `feature-*` | see [Features](#3-features) | Switches for every optional feature |
|
|
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 |
|
|
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) |
|
|
107
|
+
|
|
108
|
+
### Appearance
|
|
109
|
+
|
|
110
|
+
| Prop | Attribute | Default | |
|
|
111
|
+
| --- | --- | --- | --- |
|
|
112
|
+
| `locale` | `locale` | browser | Language and region: `en-US`, `de-DE`, `fr-FR`, `pt-BR`, … See [Languages and texts](#5-languages-and-texts) |
|
|
113
|
+
| `messages` | property `messages` | – | Own texts or languages |
|
|
114
|
+
| `theme` | `theme` | follows the device | `light` or `dark`. Applies while the user has chosen "system" in the settings |
|
|
115
|
+
| `timeZone` | `time-zone` | browser | IANA zone the calendar is shown in, e.g. `Europe/Berlin`. New events start in it. A zone the user picks in the settings wins |
|
|
116
|
+
| `holidays` | `holidays` | from `locale` | Region for public holidays: `DE`, `DE-NW`, `AT`, `US-CA`, or `off`. Users can override it in the settings |
|
|
117
|
+
| `holidaySource` | `holiday-source` | `library` | `library` computes holidays in the browser, `backend` asks your backend (`GET /holidays`) and falls back to the library |
|
|
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) |
|
|
120
|
+
| `className`, `style` | `class`, `style` | – | Size and place on your page |
|
|
121
|
+
|
|
122
|
+
### Navigation
|
|
123
|
+
|
|
124
|
+
| Prop | Attribute | Default | |
|
|
125
|
+
| --- | --- | --- | --- |
|
|
126
|
+
| `routing` | – | `memory` | `memory`: the calendar's pages (settings, sign-in, …) change inside the widget only. `browser`: they get addresses in the address bar, for when the calendar is the whole page. The web component always uses `memory` |
|
|
127
|
+
| `basename` | – | – | Path prefix for `routing="browser"` |
|
|
128
|
+
| `initialPath` | `initial-path` | `/` | Page the widget opens on, e.g. `/settings` |
|
|
129
|
+
| `linkParam` | `link-param` | `calendarPath` | Query parameter of your page that links from e-mails use to open a page of the widget, e.g. `?calendarPath=%2Freset-password%3Ftoken%3D…`. `false` turns it off |
|
|
130
|
+
|
|
131
|
+
### Configuration and callbacks
|
|
132
|
+
|
|
133
|
+
| Prop | Attribute | Default | |
|
|
134
|
+
| --- | --- | --- | --- |
|
|
135
|
+
| `config` | `config`, property `config` | – | URL of a JSON or YAML file, or an object with options. See [Configuration file](#4-configuration-file) |
|
|
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) |
|
|
139
|
+
|
|
140
|
+
### Which setting wins
|
|
141
|
+
|
|
142
|
+
Several places can set the same thing. From strongest to weakest:
|
|
143
|
+
|
|
144
|
+
1. What the user chose in the calendar's settings (language, theme, time zone, holidays, start view). Exception: `initialView` wins over the user's start view.
|
|
145
|
+
2. Props and attributes.
|
|
146
|
+
3. The configuration file.
|
|
147
|
+
4. The browser or device (language, time zone, light or dark).
|
|
148
|
+
5. The defaults in the tables above.
|
|
149
|
+
|
|
150
|
+
## 3. Features
|
|
151
|
+
|
|
152
|
+
Everything beyond the core calendar (views, creating, editing, moving and deleting events, colors, all-day events) can be switched off. A feature that is off disappears from the interface and the component makes no calls for it, so your backend does not have to provide it.
|
|
153
|
+
|
|
154
|
+
```jsx
|
|
155
|
+
<Calendar storageMode="remote" features={{ auth: true, chat: false, subscriptions: false }} views={['week', 'month']} />
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
```html
|
|
159
|
+
<calendar-widget storage-mode="remote" feature-auth feature-chat="false" feature-subscriptions="false" views="week month"></calendar-widget>
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
| Feature | Attribute | Default | What it covers | Your backend needs |
|
|
163
|
+
| --- | --- | --- | --- | --- |
|
|
164
|
+
| `auth` | `feature-auth` | off | Sign-in, registration, accounts | `/auth/*` |
|
|
165
|
+
| `teams` | `feature-teams` | on | Team calendars, members, roles, invitations | `/calendars`, `/teams/*`, `/invitations` |
|
|
166
|
+
| `chat` | `feature-chat` | on | Chat per event in team calendars | Chat endpoints and the WebSocket, see [Event chat](#11-event-chat) |
|
|
167
|
+
| `attendees` | `feature-attendees` | on | Inviting members to events, replies | `POST /events/:id/response` |
|
|
168
|
+
| `recurrence` | `feature-recurrence` | on | Creating and editing recurring events | – |
|
|
169
|
+
| `reminders` | `feature-reminders` | on | Reminders and their notifications | `PUT /events/:id/reminders` for members without edit rights |
|
|
170
|
+
| `links` | `feature-links` | on | Website and other links on events | – |
|
|
171
|
+
| `mapLinks` | `feature-map-links` | on | Opening a location in a map service | – |
|
|
172
|
+
| `holidays` | `feature-holidays` | on | Public holidays and their setting | `GET /holidays` only with `holidaySource="backend"` |
|
|
173
|
+
| `search` | `feature-search` | on | Event search | `GET /events/search` |
|
|
174
|
+
| `undo` | `feature-undo` | on | Undo after moving or deleting | – |
|
|
175
|
+
| `duplicate` | `feature-duplicate` | on | Duplicating events | – |
|
|
176
|
+
| `shortcuts` | `feature-shortcuts` | on | Keyboard shortcuts | – |
|
|
177
|
+
| `subscriptions` | `feature-subscriptions` | on | Subscription links in the calendar settings | `/calendars/:id/feed`, `/feeds/:token.ics` |
|
|
178
|
+
| `importExport` | `feature-import-export` | on | iCalendar import and export | – |
|
|
179
|
+
| `emailNotifications` | `feature-email-notifications` | on | E-mail settings of a signed-in user | Sending the e-mails |
|
|
180
|
+
| `timeZones` | `feature-time-zones` | on | Time zone per event and in the settings | – |
|
|
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` |
|
|
188
|
+
|
|
189
|
+
Good to know:
|
|
190
|
+
|
|
191
|
+
- `chat` and `attendees` need `teams`. Without teams they are off, whatever you set.
|
|
192
|
+
- With `undo` off, deleting an event asks for confirmation first.
|
|
193
|
+
- With `recurrence`, `links` or `reminders` off, existing data is kept when an event is saved. It is only no longer shown or editable.
|
|
194
|
+
- With `timeZones` off, the calendar always uses the automatic zone (your `timeZone`, otherwise the browser's).
|
|
195
|
+
- With a single entry in `views`, the view switch disappears.
|
|
196
|
+
- The attributes `auth` and `teams` still work as short forms of `feature-auth` and `feature-teams`.
|
|
197
|
+
|
|
198
|
+
## 4. Configuration file
|
|
199
|
+
|
|
200
|
+
Instead of props or attributes you can keep the options in a file, or pass them as an object. This keeps the embedding code the same on every page and the settings in one place.
|
|
201
|
+
|
|
202
|
+
```html
|
|
203
|
+
<calendar-widget config="/calendar.config.yaml"></calendar-widget>
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
```tsx
|
|
207
|
+
<Calendar config="/calendar.config.json" />
|
|
208
|
+
<Calendar config={{ storageMode: 'remote', features: { auth: true, chat: false } }} />
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
```js
|
|
212
|
+
document.querySelector('calendar-widget').config = { features: { chat: false } }
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
### Example files
|
|
216
|
+
|
|
217
|
+
Two complete, commented examples list every option with its default. Copy one and delete what you do not need:
|
|
218
|
+
|
|
219
|
+
- [`demo/calendar.config.yaml`](demo/calendar.config.yaml)
|
|
220
|
+
- [`demo/calendar.config.jsonc`](demo/calendar.config.jsonc), the same as JSON
|
|
221
|
+
|
|
222
|
+
A short file is enough, everything left out keeps its default:
|
|
223
|
+
|
|
224
|
+
```yaml
|
|
225
|
+
storageMode: remote
|
|
226
|
+
apiBaseUrl: https://api.example.com
|
|
227
|
+
locale: de-DE
|
|
228
|
+
views: [week, month]
|
|
229
|
+
features:
|
|
230
|
+
auth: true
|
|
231
|
+
chat: false
|
|
232
|
+
subscriptions: false
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
```jsonc
|
|
236
|
+
{
|
|
237
|
+
// comments are allowed
|
|
238
|
+
"storageMode": "remote",
|
|
239
|
+
"apiBaseUrl": "https://api.example.com",
|
|
240
|
+
"locale": "de-DE",
|
|
241
|
+
"views": ["week", "month"],
|
|
242
|
+
"features": { "auth": true, "chat": false, "subscriptions": false }
|
|
243
|
+
}
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
### What can be in the file
|
|
247
|
+
|
|
248
|
+
All options from [Options](#2-options) under their prop names, except those that cannot be written as data: `dataSource`, `getUserToken`, the event callbacks, `className`, `style`, and `config` itself.
|
|
249
|
+
|
|
250
|
+
| Field | Type | Default |
|
|
251
|
+
| --- | --- | --- |
|
|
252
|
+
| `storageMode` | `"local"` or `"remote"` | `"local"` |
|
|
253
|
+
| `apiBaseUrl` | text | `"/api"` |
|
|
254
|
+
| `apiTimeoutMs` | whole number above 0 | `10000` |
|
|
255
|
+
| `tenant` | text | – |
|
|
256
|
+
| `features` | object of feature names and `true` / `false` | see [Features](#3-features) |
|
|
257
|
+
| `views` | list of `day`, `week`, `month`, `year` | all four |
|
|
258
|
+
| `initialView` | `day`, `week`, `month` or `year` | user's start view |
|
|
259
|
+
| `locale` | text | browser |
|
|
260
|
+
| `messages` | object: language → texts | – |
|
|
261
|
+
| `theme` | `"light"` or `"dark"` | follows the device |
|
|
262
|
+
| `timeZone` | text (IANA zone) | browser |
|
|
263
|
+
| `holidays` | text (region or `"off"`) | from `locale` |
|
|
264
|
+
| `holidaySource` | `"library"` or `"backend"` | `"library"` |
|
|
265
|
+
| `mapUrl` | text with `{query}` | Google Maps |
|
|
266
|
+
| `readOnly` | `true` or `false` | `false` |
|
|
267
|
+
| `appearance` | object with `accentColor`, `fontFamily`, `radius`, `density` | – |
|
|
268
|
+
| `routing` | `"memory"` or `"browser"` | `"memory"` |
|
|
269
|
+
| `basename` | text | – |
|
|
270
|
+
| `initialPath` | text | `/` |
|
|
271
|
+
| `linkParam` | text or `false` | `"calendarPath"` |
|
|
272
|
+
|
|
273
|
+
### How the file is read
|
|
274
|
+
|
|
275
|
+
- **Format.** Files ending in `.yaml` or `.yml` are read as YAML, files ending in `.json` or `.jsonc` as JSON. For other addresses the `Content-Type` of the answer decides. JSON files may contain `//` and `/* */` comments.
|
|
276
|
+
- **YAML parser.** It is only loaded when a YAML file is used. With the script tag it is a separate file next to `calendar-widget.js`, with the npm package it comes from the `yaml` dependency.
|
|
277
|
+
- **Precedence.** Props and attributes win over the file, for features one switch at a time. So one shared file can be adjusted per page: `<calendar-widget config="/calendar.config.yaml" feature-search="false">`.
|
|
278
|
+
- **Mistakes in the file.** Unknown or invalid entries are skipped, the rest is used. Every skipped entry is listed as a warning in the browser console, starting with `[calendar]`.
|
|
279
|
+
- **File not reachable or not parseable.** The calendar shows a message and does not start. It never falls back to defaults silently, because that could mean storing events in the wrong place.
|
|
280
|
+
- **Loading.** The file is fetched once when the calendar starts and again when the `config` address changes. Cache it like any other static file.
|
|
281
|
+
- **Texts.** `messages` in a file can override plain texts. Texts that are functions need the `messages` prop or property, see [Languages and texts](#5-languages-and-texts).
|
|
282
|
+
- **Security.** The file is public, like everything a browser loads. Never put secrets in it.
|
|
283
|
+
|
|
284
|
+
### Editor support
|
|
285
|
+
|
|
286
|
+
A JSON Schema ships with the package as `@rokoyfa/calendar/config.schema.json`. With it, editors complete field names and flag wrong values.
|
|
287
|
+
|
|
288
|
+
```json
|
|
289
|
+
{ "$schema": "https://unpkg.com/@rokoyfa/calendar/schema/calendar-config.schema.json" }
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
```yaml
|
|
293
|
+
# yaml-language-server: $schema=https://unpkg.com/@rokoyfa/calendar/schema/calendar-config.schema.json
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
### Checking a configuration yourself
|
|
297
|
+
|
|
298
|
+
`parseCalendarOptions` is the function the calendar uses. It returns the valid options and a list of problems, useful in a build step or an admin page:
|
|
299
|
+
|
|
300
|
+
```ts
|
|
301
|
+
import { parseCalendarOptions } from '@rokoyfa/calendar'
|
|
302
|
+
|
|
303
|
+
const { options, issues } = parseCalendarOptions(JSON.parse(text))
|
|
304
|
+
if (issues.length > 0) console.warn(issues)
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
## 5. Languages and texts
|
|
308
|
+
|
|
309
|
+
English, German, French, Spanish, Italian, Dutch, Polish and Portuguese are built in. Which language is used, in this order:
|
|
310
|
+
|
|
311
|
+
1. The user's choice in the settings.
|
|
312
|
+
2. Your `locale`.
|
|
313
|
+
3. The browser's languages.
|
|
314
|
+
4. `en-US`.
|
|
315
|
+
|
|
316
|
+
Formats follow the region, not the language: `en-US` starts the week on Sunday and shows `1:00 PM`, `en-GB` starts on Monday and shows `13:00`. A language that is not available falls back to English with the user's region.
|
|
317
|
+
|
|
318
|
+
**Own texts and languages.** `messages` overrides single texts or adds 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.
|
|
319
|
+
|
|
320
|
+
```js
|
|
321
|
+
document.querySelector('calendar-widget').messages = {
|
|
322
|
+
de: { calendar: { newEvent: 'Neuer Eintrag' } },
|
|
323
|
+
sv: { calendar: { today: 'Idag', newEvent: 'Ny händelse' }, views: { weekNumber: (week) => `V. ${week}` } },
|
|
324
|
+
}
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
Texts with values in them are functions, like `weekNumber` above. An override of the wrong kind (a text where a function is expected, or the other way round) is ignored.
|
|
328
|
+
|
|
329
|
+
## 6. Reacting to changes
|
|
330
|
+
|
|
331
|
+
After every stored change the calendar tells your page.
|
|
332
|
+
|
|
333
|
+
```tsx
|
|
334
|
+
<Calendar
|
|
335
|
+
onEventCreate={(event) => console.log('created', event)}
|
|
336
|
+
onEventUpdate={(event) => console.log('updated', event)}
|
|
337
|
+
onEventDelete={({ id }) => console.log('deleted', id)}
|
|
338
|
+
/>
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
```js
|
|
342
|
+
const calendar = document.querySelector('calendar-widget')
|
|
343
|
+
calendar.addEventListener('event-create', (e) => console.log(e.detail))
|
|
344
|
+
calendar.addEventListener('event-update', (e) => console.log(e.detail))
|
|
345
|
+
calendar.addEventListener('event-delete', (e) => console.log(e.detail.id))
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
- Create and update carry the stored `CalendarEvent`, delete carries `{ id }`.
|
|
349
|
+
- The DOM events bubble and cross the Shadow DOM, so you can listen on a parent element.
|
|
350
|
+
- One action on a recurring event can cause several calls. Changing "only this occurrence" updates the series and creates a detached event.
|
|
351
|
+
- An undo causes the reverse calls.
|
|
352
|
+
|
|
353
|
+
## 7. Sign-in and tenants
|
|
354
|
+
|
|
355
|
+
There are three ways to handle users.
|
|
356
|
+
|
|
357
|
+
**No sign-in** (default). Everything stays in the visitor's browser. With `storageMode="remote"` all requests go to your backend without the calendar asking anyone to sign in. Who the visitor is, is then up to your backend, for example through a session cookie of your own site or a token from `getAccessToken` (see [Data adapters](#8-data-adapters)).
|
|
358
|
+
|
|
359
|
+
**The calendar's own accounts.** Turn on the `auth` feature. The calendar then has pages for sign-in, registration, password reset and e-mail confirmation. Guests keep working in the browser, and after signing in they are asked whether to move their local events into the account.
|
|
360
|
+
|
|
361
|
+
```html
|
|
362
|
+
<calendar-widget storage-mode="remote" feature-auth api-base-url="https://api.example.com"></calendar-widget>
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
**Sign-in through your page.** If your visitors are already signed in on your site, pass `getUserToken`. It returns a short-lived token signed by your server, or `null` when nobody is signed in.
|
|
366
|
+
|
|
367
|
+
```tsx
|
|
368
|
+
<Calendar
|
|
369
|
+
tenant="acme"
|
|
370
|
+
apiBaseUrl="https://api.example.com"
|
|
371
|
+
getUserToken={() => fetch('/calendar-token').then((r) => r.text())}
|
|
372
|
+
/>
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
- The calendar first asks `GET /auth/me`. On `401` it calls `getUserToken` and exchanges the token at `POST /auth/token` for a session. When the session runs out later, this happens again by itself.
|
|
376
|
+
- In this mode there are no sign-in, registration or password pages, no sign-out button and no account tab. The account belongs to your site.
|
|
377
|
+
- With `null` the calendar works like for guests, in the browser.
|
|
378
|
+
|
|
379
|
+
**Tenants.** `tenant` is for a backend that serves several host pages. Every request then carries the header `X-Calendar-Tenant`, and sign-in is on. What the backend has to check is described in the OpenAPI file.
|
|
380
|
+
|
|
381
|
+
## 8. Data adapters
|
|
382
|
+
|
|
383
|
+
Where the data comes from is decided by a `CalendarDataSource`. Without the `dataSource` option the calendar picks a built-in one from `storageMode`, `apiBaseUrl`, `tenant` and the `auth` feature.
|
|
384
|
+
|
|
385
|
+
```tsx
|
|
386
|
+
import { Calendar, localDataSource, restDataSource, tenantDataSource } from '@rokoyfa/calendar'
|
|
387
|
+
|
|
388
|
+
<Calendar dataSource={localDataSource()} />
|
|
389
|
+
<Calendar dataSource={restDataSource({ baseUrl: 'https://api.example.com' })} />
|
|
390
|
+
<Calendar dataSource={restDataSource({ baseUrl: '/api', auth: false, getAccessToken: () => myToken })} />
|
|
391
|
+
<Calendar dataSource={tenantDataSource({ tenant: 'acme', baseUrl: 'https://api.example.com', getUserToken })} />
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
| Adapter | Behaviour |
|
|
395
|
+
| --- | --- |
|
|
396
|
+
| `localDataSource()` | Everything in the browser (localStorage), no sign-in |
|
|
397
|
+
| `restDataSource(options)` | Talks to the [REST API](api/openapi.yaml) |
|
|
398
|
+
| `tenantDataSource(options)` | `restDataSource` with the tenant header and sign-in |
|
|
399
|
+
|
|
400
|
+
`restDataSource` options:
|
|
401
|
+
|
|
402
|
+
| Option | Default | |
|
|
403
|
+
| --- | --- | --- |
|
|
404
|
+
| `baseUrl` | required | Base URL of the backend |
|
|
405
|
+
| `timeoutMs` | `10000` | Time limit per request |
|
|
406
|
+
| `auth` | `true` | With sign-in in the widget: guests work in the browser, signed-in users on the backend. `false`: always the backend |
|
|
407
|
+
| `headers` | – | Extra headers for every request |
|
|
408
|
+
| `getAccessToken` | – | Returns a bearer token for the `Authorization` header |
|
|
409
|
+
| `getUserToken` | – | Sign-in through your page, see above |
|
|
410
|
+
| `holidaySource` | `library` | `backend` asks `GET /holidays` |
|
|
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 |
|
|
414
|
+
|
|
415
|
+
Note that `restDataSource` defaults to `auth: true`, while the `auth` feature of the component defaults to off.
|
|
416
|
+
|
|
417
|
+
### Your own adapter
|
|
418
|
+
|
|
419
|
+
For any other data source, implement the interfaces yourself. All types are exported.
|
|
420
|
+
|
|
421
|
+
```ts
|
|
422
|
+
import type { CalendarDataSource } from '@rokoyfa/calendar'
|
|
423
|
+
|
|
424
|
+
const myDataSource: CalendarDataSource = {
|
|
425
|
+
createAuthRepository: ({ getLanguage }) => myAuth,
|
|
426
|
+
connect: ({ isAuthenticated }, { getLanguage, onUnauthorized }) => ({
|
|
427
|
+
mode: 'remote',
|
|
428
|
+
events: myEvents,
|
|
429
|
+
calendars: myCalendars,
|
|
430
|
+
colors: myColors,
|
|
431
|
+
preferences: myPreferences,
|
|
432
|
+
holidays: myHolidays,
|
|
433
|
+
chat: myChat,
|
|
434
|
+
categories: myCategories,
|
|
435
|
+
shared: mySharedCalendars,
|
|
436
|
+
}),
|
|
437
|
+
}
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
- `connect` returns the repositories for the current state. It is called again on sign-in and sign-out.
|
|
441
|
+
- `createAuthRepository` is optional. Without it there is no sign-in in the widget.
|
|
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.
|
|
443
|
+
- `mode: 'remote'` makes the calendar offer to move local events into the account after sign-in.
|
|
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.
|
|
445
|
+
- Call `onUnauthorized` when a session has run out. `getLanguage` returns the current language for your requests.
|
|
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.
|
|
448
|
+
|
|
449
|
+
A simple start is to take most repositories from `localDataSource()` and replace only `events`:
|
|
450
|
+
|
|
451
|
+
```ts
|
|
452
|
+
const local = localDataSource()
|
|
453
|
+
|
|
454
|
+
const myDataSource: CalendarDataSource = {
|
|
455
|
+
connect: (session, context) => ({ ...local.connect(session, context), events: myEvents }),
|
|
456
|
+
}
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
## 9. Exported types
|
|
460
|
+
|
|
461
|
+
Everything below is exported from `@rokoyfa/calendar`.
|
|
462
|
+
|
|
463
|
+
### Component and configuration
|
|
464
|
+
|
|
465
|
+
| Export | Kind | |
|
|
466
|
+
| --- | --- | --- |
|
|
467
|
+
| `Calendar` | component | The React component |
|
|
468
|
+
| `CalendarElement`, `defineCalendarElement`, `DEFAULT_ELEMENT_NAME` | class, function, text | The web component, registering it, and its default name `calendar-widget` |
|
|
469
|
+
| `VERSION` | text | Version of the package |
|
|
470
|
+
| `CalendarProps` | type | All props of `Calendar` |
|
|
471
|
+
| `CalendarOptions` | type | The options that can be written as data, the shape of a configuration file |
|
|
472
|
+
| `CalendarConfigSource` | type | `string | CalendarOptions`, the type of `config` |
|
|
473
|
+
| `CalendarFeatures`, `CalendarFeature` | types | All feature switches, and the name of one |
|
|
474
|
+
| `DEFAULT_FEATURES`, `FEATURE_NAMES` | values | Defaults and names of the features |
|
|
475
|
+
| `parseCalendarOptions`, `ParsedOptions` | function, type | Checks a configuration and returns `{ options, issues }` |
|
|
476
|
+
| `CalendarView` | type | `'day' | 'week' | 'month' | 'year'` |
|
|
477
|
+
| `CalendarRouting`, `StorageMode`, `HolidaySource`, `HostTheme` | types | The values of `routing`, `storageMode`, `holidaySource`, `theme` |
|
|
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` |
|
|
481
|
+
| `Messages`, `PartialMessages`, `MessageOverrides`, `DeepPartial` | types | All texts, a part of them, and the type of `messages` |
|
|
482
|
+
|
|
483
|
+
```ts
|
|
484
|
+
type CalendarOptions = {
|
|
485
|
+
tenant?: string
|
|
486
|
+
storageMode?: 'local' | 'remote'
|
|
487
|
+
apiBaseUrl?: string
|
|
488
|
+
apiTimeoutMs?: number
|
|
489
|
+
features?: Partial<CalendarFeatures>
|
|
490
|
+
views?: readonly CalendarView[]
|
|
491
|
+
routing?: 'memory' | 'browser'
|
|
492
|
+
basename?: string
|
|
493
|
+
initialPath?: string
|
|
494
|
+
linkParam?: string | false
|
|
495
|
+
locale?: string
|
|
496
|
+
messages?: MessageOverrides
|
|
497
|
+
theme?: 'light' | 'dark'
|
|
498
|
+
initialView?: CalendarView
|
|
499
|
+
timeZone?: string
|
|
500
|
+
holidays?: string
|
|
501
|
+
holidaySource?: 'library' | 'backend'
|
|
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'
|
|
512
|
+
}
|
|
513
|
+
|
|
514
|
+
type CalendarProps = CalendarOptions &
|
|
515
|
+
EventCallbacks & {
|
|
516
|
+
config?: string | CalendarOptions
|
|
517
|
+
ref?: Ref<CalendarHandle>
|
|
518
|
+
onViewChange?: (state: CalendarState) => void
|
|
519
|
+
dataSource?: CalendarDataSource
|
|
520
|
+
getUserToken?: UserTokenProvider
|
|
521
|
+
className?: string
|
|
522
|
+
style?: CSSProperties
|
|
523
|
+
}
|
|
524
|
+
|
|
525
|
+
type CalendarFeatures = {
|
|
526
|
+
auth: boolean
|
|
527
|
+
teams: boolean
|
|
528
|
+
chat: boolean
|
|
529
|
+
attendees: boolean
|
|
530
|
+
recurrence: boolean
|
|
531
|
+
reminders: boolean
|
|
532
|
+
links: boolean
|
|
533
|
+
mapLinks: boolean
|
|
534
|
+
holidays: boolean
|
|
535
|
+
search: boolean
|
|
536
|
+
undo: boolean
|
|
537
|
+
duplicate: boolean
|
|
538
|
+
shortcuts: boolean
|
|
539
|
+
subscriptions: boolean
|
|
540
|
+
importExport: boolean
|
|
541
|
+
emailNotifications: boolean
|
|
542
|
+
timeZones: boolean
|
|
543
|
+
customColors: boolean
|
|
544
|
+
categories: boolean
|
|
545
|
+
publicLinks: boolean
|
|
546
|
+
attachments: boolean
|
|
547
|
+
}
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
### Data
|
|
551
|
+
|
|
552
|
+
| Export | |
|
|
553
|
+
| --- | --- |
|
|
554
|
+
| `CalendarEvent`, `EventInput`, `EventLink`, `Attendee`, `AttendeeStatus`, `Recurrence`, `HexColor` | Events, see [Data types](#data-types) |
|
|
555
|
+
| `CalendarSummary`, `CalendarDraft`, `CalendarChanges`, `TeamChanges`, `TeamMember`, `TeamRole`, `Invitation`, `PendingInvitation`, `TeamInvitation` | Calendars, teams and invitations |
|
|
556
|
+
| `User`, `AuthMethod`, `UserTokenProvider` | The signed-in user, `'password' | 'hostToken'`, and the type of `getUserToken` |
|
|
557
|
+
| `Preferences` | A user's settings |
|
|
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 |
|
|
562
|
+
| `ChatMessage`, `ChatKey`, `ChatPage`, `ChatUnread`, `ChatEvent` | Chat, see [Event chat](#11-event-chat) |
|
|
563
|
+
|
|
564
|
+
### Data adapters
|
|
565
|
+
|
|
566
|
+
| Export | |
|
|
567
|
+
| --- | --- |
|
|
568
|
+
| `localDataSource`, `restDataSource`, `tenantDataSource`, `TENANT_HEADER` | The built-in adapters and the name of the tenant header |
|
|
569
|
+
| `RestDataSourceOptions`, `TenantDataSourceOptions` | Their options |
|
|
570
|
+
| `CalendarDataSource`, `DataRepositories`, `DataSession`, `DataSourceContext` | The adapter interface |
|
|
571
|
+
| `EventRepository`, `EventQuery`, `EventSearchQuery` | Events |
|
|
572
|
+
| `CalendarRepository` | Calendars, teams, invitations, subscription links |
|
|
573
|
+
| `AuthRepository` | Sign-in and account |
|
|
574
|
+
| `ColorRepository`, `PreferencesRepository` | Own colors, settings |
|
|
575
|
+
| `HolidayRepository`, `HolidayQuery` | Public holidays |
|
|
576
|
+
| `ChatRepository` | Chat |
|
|
577
|
+
| `CategoryRepository` | Categories |
|
|
578
|
+
| `SharedCalendarRepository` | Reading a calendar through a public link |
|
|
579
|
+
| `AttachmentRepository` | Files on events |
|
|
580
|
+
|
|
581
|
+
```ts
|
|
582
|
+
interface CalendarDataSource {
|
|
583
|
+
createAuthRepository?: (context: { getLanguage: () => string | null }) => AuthRepository
|
|
584
|
+
connect: (session: { isAuthenticated: boolean }, context: DataSourceContext) => DataRepositories
|
|
585
|
+
}
|
|
586
|
+
|
|
587
|
+
type DataSourceContext = { getLanguage: () => string | null; onUnauthorized: () => void }
|
|
588
|
+
|
|
589
|
+
type DataRepositories = {
|
|
590
|
+
mode: 'local' | 'remote'
|
|
591
|
+
events: EventRepository
|
|
592
|
+
calendars: CalendarRepository
|
|
593
|
+
colors: ColorRepository
|
|
594
|
+
preferences: PreferencesRepository
|
|
595
|
+
holidays?: HolidayRepository
|
|
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[]>
|
|
619
|
+
}
|
|
620
|
+
|
|
621
|
+
interface EventRepository {
|
|
622
|
+
list(query: { from: string; to: string; calendarIds: readonly string[] }): Promise<CalendarEvent[]>
|
|
623
|
+
listSeries(seriesId: string): Promise<CalendarEvent[]>
|
|
624
|
+
create(calendarId: string, input: EventInput): Promise<CalendarEvent>
|
|
625
|
+
update(id: string, input: EventInput, version?: number): Promise<CalendarEvent>
|
|
626
|
+
remove(id: string, version?: number): Promise<void>
|
|
627
|
+
search?(query: { text: string; calendarIds: readonly string[] }): Promise<CalendarEvent[]>
|
|
628
|
+
respond?(id: string, status: AttendeeStatus): Promise<CalendarEvent>
|
|
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>
|
|
634
|
+
}
|
|
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
|
+
|
|
650
|
+
interface ChatRepository {
|
|
651
|
+
list(key: ChatKey, options?: { before?: string }): Promise<ChatPage>
|
|
652
|
+
send(key: ChatKey, text: string): Promise<ChatMessage>
|
|
653
|
+
edit(id: string, text: string): Promise<ChatMessage>
|
|
654
|
+
remove(id: string): Promise<void>
|
|
655
|
+
markRead(key: ChatKey): Promise<void>
|
|
656
|
+
unread(calendarIds: readonly string[]): Promise<ChatUnread[]>
|
|
657
|
+
subscribe(listener: (event: ChatEvent) => void): () => void
|
|
658
|
+
}
|
|
659
|
+
|
|
660
|
+
type ChatKey = { eventId: string; occurrenceDate: string | null }
|
|
661
|
+
type ChatMessage = ChatKey & {
|
|
662
|
+
id: string
|
|
663
|
+
calendarId: string
|
|
664
|
+
author: { id: string; name: string } | null
|
|
665
|
+
text: string
|
|
666
|
+
createdAt: string
|
|
667
|
+
editedAt: string | null
|
|
668
|
+
}
|
|
669
|
+
type ChatPage = { messages: ChatMessage[]; hasMore: boolean }
|
|
670
|
+
type ChatUnread = ChatKey & { count: number }
|
|
671
|
+
```
|
|
672
|
+
|
|
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.
|
|
674
|
+
|
|
675
|
+
## 10. Backend
|
|
676
|
+
|
|
677
|
+
The full contract is [`api/openapi.yaml`](api/openapi.yaml) (OpenAPI 3.1, also shipped as `@rokoyfa/calendar/openapi.yaml`). The essentials:
|
|
678
|
+
|
|
679
|
+
### Data types
|
|
680
|
+
|
|
681
|
+
```ts
|
|
682
|
+
type CalendarEvent = EventInput & {
|
|
683
|
+
id: string
|
|
684
|
+
calendarId: string
|
|
685
|
+
createdAt: string // ISO date-time
|
|
686
|
+
updatedAt: string
|
|
687
|
+
version: number // starts at 1, goes up on every change, read-only
|
|
688
|
+
}
|
|
689
|
+
|
|
690
|
+
type EventInput = {
|
|
691
|
+
uid: string // stable id for iCalendar, shared by a series and its detached events
|
|
692
|
+
title: string // 1–100 chars
|
|
693
|
+
location: string // max 200 chars, '' if none
|
|
694
|
+
links: EventLink[] // up to 10 http(s) links
|
|
695
|
+
categoryIds: string[] // up to 5 categories of the event's calendar
|
|
696
|
+
startDate: string // 'YYYY-MM-DD'
|
|
697
|
+
start: string // 'HH:mm' in timeZone
|
|
698
|
+
endDate: string // inclusive for all-day events
|
|
699
|
+
end: string
|
|
700
|
+
allDay: boolean // start and end are '00:00'
|
|
701
|
+
timeZone: string | null // IANA zone, null = same local time everywhere (always null for all-day)
|
|
702
|
+
description: string // max 2000 chars
|
|
703
|
+
color: 'blue' | 'red' | 'green' | 'yellow' | `#${string}`
|
|
704
|
+
recurrence: Recurrence | null
|
|
705
|
+
excludedDates: string[] // occurrences removed from a series
|
|
706
|
+
seriesId: string | null // set on an occurrence detached from a series
|
|
707
|
+
originalDate: string | null // its original date in that series
|
|
708
|
+
reminders: number[] // minutes before the start, per user (see below)
|
|
709
|
+
attendees: Attendee[]
|
|
710
|
+
}
|
|
711
|
+
|
|
712
|
+
type Attendee = { email: string; name: string; status: 'needsAction' | 'accepted' | 'tentative' | 'declined' }
|
|
713
|
+
|
|
714
|
+
type EventLink = { url: string; label: string } // url max 2000 chars, label max 100 chars, '' if none
|
|
715
|
+
|
|
716
|
+
type Recurrence = {
|
|
717
|
+
frequency: 'daily' | 'weekly' | 'monthly' | 'yearly'
|
|
718
|
+
interval: number // 1–99
|
|
719
|
+
weekdays: number[] // 0 = Monday … 6 = Sunday
|
|
720
|
+
monthlyMode: 'dayOfMonth' | 'weekdayOfMonth' | 'lastWeekdayOfMonth'
|
|
721
|
+
until: string | null // either until or count, or neither
|
|
722
|
+
count: number | null
|
|
723
|
+
}
|
|
724
|
+
|
|
725
|
+
type CalendarSummary = {
|
|
726
|
+
id: string; teamId: string; name: string; color: string
|
|
727
|
+
kind: 'personal' | 'team'; teamName: string | null; description: string
|
|
728
|
+
role: 'owner' | 'admin' | 'manager' | 'editor' | 'member' | 'contributor' | 'viewer'
|
|
729
|
+
showInPersonal: boolean; permissions: string[]
|
|
730
|
+
}
|
|
731
|
+
|
|
732
|
+
type User = { id: string; email: string; name: string; emailVerified: boolean }
|
|
733
|
+
type Preferences = {
|
|
734
|
+
theme: 'system' | 'light' | 'dark'; defaultView: View; mobileDefaultView: View; locale: string
|
|
735
|
+
timeZone: string // 'auto' or IANA zone
|
|
736
|
+
holidays: string // 'auto', 'off' or a region such as 'DE-NW'
|
|
737
|
+
}
|
|
738
|
+
type PublicHoliday = { date: string; name: string } // GET /holidays, only with holiday-source="backend"
|
|
739
|
+
// Preferences also carry emailInvites, emailChanges, emailReminders, emailChat: booleans for the emails below
|
|
740
|
+
type Problem = { code: string; message: string } // every error response
|
|
741
|
+
```
|
|
742
|
+
|
|
743
|
+
The backend stores series as one event. The component expands occurrences itself.
|
|
744
|
+
|
|
745
|
+
**Reminders are personal.** Store them per user and event, return only the caller's own `reminders`, and keep other members' reminders when someone saves the event. The component shows reminders while it is open (browser notification or a notice in the calendar). Emails or push messages when it is closed are up to your backend.
|
|
746
|
+
|
|
747
|
+
### When the component calls your backend
|
|
748
|
+
|
|
749
|
+
| Moment | Requests |
|
|
750
|
+
| --- | --- |
|
|
751
|
+
| Widget loads | `GET /auth/me` (only with `auth`), then `GET /preferences`, `GET /colors`, `GET /calendars`, `GET /invitations` |
|
|
752
|
+
| Visible range changes | `GET /events?from=…&to=…&calendarId=…` with the calendars shown. The range is two days wider than the view to cover time zone shifts. Return every event in the range **and** every series that can occur in it. |
|
|
753
|
+
| Create event | `POST /events` with `EventInput` + `calendarId` |
|
|
754
|
+
| Edit event / whole series | `PUT /events/:id` with the full `EventInput` |
|
|
755
|
+
| Edit only this occurrence | `PUT` the series with the date added to `excludedDates`, then `POST` a detached event with `seriesId` and `originalDate` |
|
|
756
|
+
| 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 |
|
|
757
|
+
| 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` |
|
|
758
|
+
| Search | `GET /events/search?q=…&calendarId=…` (optional: without it the component searches the last and next year via `GET /events`) |
|
|
759
|
+
| Answer as attendee | `POST /events/:id/response` with `{ status }` |
|
|
760
|
+
| Change only own reminders | `PUT /events/:id/reminders` with `{ reminders }` (also for members without edit rights) |
|
|
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 |
|
|
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 |
|
|
769
|
+
| Subscription link | `GET`, `POST` (new link), `DELETE /calendars/:id/feed`. The link points at your `GET /feeds/:token.ics` |
|
|
770
|
+
| Reminders | `GET /events` for the next four weeks of all calendars, every five minutes while the widget is open |
|
|
771
|
+
| Import .ics | `GET /events` for the whole calendar, then `PUT` for known `uid`s and `POST` for new ones |
|
|
772
|
+
| Settings, colors | `PATCH /preferences`, `POST /colors`, `DELETE /colors/:rrggbb` |
|
|
773
|
+
| Holidays (only with `holiday-source="backend"`) | `GET /holidays?from=…&to=…®ion=DE-NW&lang=de`, answer `PublicHoliday[]` |
|
|
774
|
+
| Sign-in, teams, invitations | `/auth/*`, `/calendars`, `/teams/*`, `/invitations/*`, see the OpenAPI file |
|
|
775
|
+
|
|
776
|
+
Before editing "following" or "all" of a series, the component loads its detached events with `GET /events?seriesId=…`.
|
|
777
|
+
|
|
778
|
+
### Rules for the backend
|
|
779
|
+
|
|
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.
|
|
781
|
+
- **Errors:** always `{ code, message }`. Known codes such as `invalidCredentials`, `emailTaken`, `forbidden`, `lastOwner` are shown translated, others with `message`.
|
|
782
|
+
- **Language:** every request carries `Accept-Language`. Use it, or the stored `locale`, for emails.
|
|
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.
|
|
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.
|
|
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…`.
|
|
793
|
+
|
|
794
|
+
## 11. Event chat
|
|
795
|
+
|
|
796
|
+
Events in team calendars have a **Chat** tab: every member can read and write, edit and delete their own messages, and owners, admins and managers (`manage_calendars`) can delete any message. Recurring events have one chat per occurrence. A detached occurrence keeps the chat of its original date. The calendar shows unread messages as a red badge on the event and in the tab title, and attendees can get an email about new messages (`emailChat`, on by default, at most one email per chat every few minutes).
|
|
797
|
+
|
|
798
|
+
Messages go over REST (see the OpenAPI file, tag *Chat*). New, edited and deleted messages arrive live over a WebSocket:
|
|
799
|
+
|
|
800
|
+
- **Address:** `{apiBaseUrl}/chat/socket` with `ws://` or `wss://`, derived from `apiBaseUrl` (relative addresses use the page's host). With `tenant` the tenant is added as `?tenant=…`, because browsers cannot set headers on WebSockets. `restDataSource` takes another address as `chatSocketUrl`.
|
|
801
|
+
- **Sign-in:** the session cookie is sent with the handshake. Check the `Origin` header against the allowed origins and answer `401` without a session.
|
|
802
|
+
- **Server → client** (JSON text frames): `{ "type": "message.created" | "message.updated", "message": ChatMessage }` and `{ "type": "message.deleted", "id", "calendarId", "eventId", "occurrenceDate" }`, sent to every connected member of the calendar's team.
|
|
803
|
+
- **Client → server:** only `{ "type": "ping" }` every 25 seconds, answer with `{ "type": "pong" }` or ignore it.
|
|
804
|
+
- The component reconnects with growing pauses (1 to 30 seconds) and reloads the open chat and the unread counts after reconnecting, so a lost connection only delays messages.
|
|
805
|
+
|
|
806
|
+
Emails link to the host page with `?calendar=…&event=…&date=…&tab=chat`, which opens the event with the chat.
|
|
807
|
+
|
|
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.
|
|
809
|
+
|
|
810
|
+
## 12. Calendar subscriptions
|
|
811
|
+
|
|
812
|
+
With a backend that serves `/calendars/:id/feed` and `/feeds/:token.ics`, every signed-in user can subscribe to a calendar in another calendar app and see its events there, for example on the phone. Users get the link in the calendar settings: **Import & export** tab for team calendars, on the settings page for the personal calendar → **Subscribe** → **Create subscription link**. They can copy the link or open it in their calendar app.
|
|
813
|
+
|
|
814
|
+
- The subscription is **read-only**. Changes made in the other app do not come back.
|
|
815
|
+
- The link is **personal and secret**: it contains the user's own reminders, and anyone who has it can see all events of the calendar. **Create new link** turns the old one off, **End subscription** removes it.
|
|
816
|
+
- It stops working when the user leaves the calendar.
|
|
817
|
+
|
|
818
|
+
### Adding the link in calendar apps
|
|
819
|
+
|
|
820
|
+
| App | Steps |
|
|
821
|
+
| --- | --- |
|
|
822
|
+
| **Apple Calendar on Mac** | **Open in calendar app** in the settings, or *File → New Calendar Subscription…*, paste the link, **Subscribe**. Set *Auto-refresh* and choose *iCloud* as location so the calendar also appears on iPhone and iPad. |
|
|
823
|
+
| **Apple Calendar on iPhone / iPad** | **Open in calendar app** in the settings, or *Settings → Apps → Calendar → Calendar Accounts → Add Account → Other → Add Subscribed Calendar* (older iOS: *Settings → Calendar → Accounts*), paste the link as server, **Next**, **Save**. |
|
|
824
|
+
| **Google Calendar** | Only in the browser at calendar.google.com: next to *Other calendars* click **+** → **From URL**, paste the link, **Add calendar**. It then also shows in the Google Calendar apps on Android and iPhone. |
|
|
825
|
+
| **Outlook.com / Outlook on the web / new Outlook** | *Calendar → Add calendar → Subscribe from web*, paste the link, give it a name, **Import**. |
|
|
826
|
+
| **Classic Outlook for Windows** | *Home → Add Calendar → From Internet…* (in some versions *Open Calendar → From Internet*), paste the link, **OK**, confirm with **Yes**. |
|
|
827
|
+
| **Thunderbird** | *New Calendar → On the Network*, paste the link, choose the iCalendar (ICS) format. |
|
|
828
|
+
|
|
829
|
+
Menu names change between app versions. If a path does not match, look for “subscribe”, “from URL” or “from internet”.
|
|
830
|
+
|
|
831
|
+
### How quickly changes show up
|
|
832
|
+
|
|
833
|
+
A subscription is not live: the app downloads the whole calendar again at intervals that the app decides. Changes made in this calendar therefore appear with a delay:
|
|
834
|
+
|
|
835
|
+
| App | Refresh |
|
|
836
|
+
| --- | --- |
|
|
837
|
+
| Apple Calendar on Mac | Adjustable per subscription, from every 5 minutes to weekly (right-click the calendar → *Get Info* → *Auto-refresh*). *View → Refresh Calendars* (⌘R) refreshes right away. |
|
|
838
|
+
| Apple Calendar on iPhone / iPad | Follows *Fetch New Data* (*Settings → Apps → Calendar → Calendar Accounts → Fetch New Data*). Choose *Every 15 Minutes* or *Hourly*. Subscriptions have no push. A subscription added on the Mac with location *iCloud* is refreshed by iCloud. |
|
|
839
|
+
| Google Calendar | Google's own schedule, usually several hours, sometimes up to a day. Cannot be changed. |
|
|
840
|
+
| Outlook.com / web / new Outlook | Microsoft's own schedule, roughly every 3 hours, sometimes more than 24 hours. Cannot be changed. |
|
|
841
|
+
| Classic Outlook for Windows | Follows the update limit in the feed (one hour here) and Outlook's send/receive settings. |
|
|
842
|
+
|
|
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.
|
|
844
|
+
|
|
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
|
+
|