@rokoyfa/calendar 1.2.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.
- package/CHANGELOG.md +8 -0
- package/DEVELOPER_GUIDE.md +743 -0
- package/README.md +39 -190
- package/demo/calendar.config.jsonc +149 -0
- package/demo/calendar.config.yaml +146 -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 +12 -11
- package/dist-lib/cdn/calendar-widget.js.map +1 -1
- package/dist-lib/cdn/de-CjkGEfiE.js +2 -0
- package/dist-lib/cdn/de-CjkGEfiE.js.map +1 -0
- package/dist-lib/cdn/es-BrMRh6bn.js +2 -0
- package/dist-lib/cdn/es-BrMRh6bn.js.map +1 -0
- package/dist-lib/cdn/fr-Ckr8Uxxd.js +2 -0
- package/dist-lib/cdn/fr-Ckr8Uxxd.js.map +1 -0
- package/dist-lib/cdn/it-_2BGklYa.js +2 -0
- package/dist-lib/cdn/it-_2BGklYa.js.map +1 -0
- package/dist-lib/cdn/nl-BykoYBK7.js +2 -0
- package/dist-lib/cdn/nl-BykoYBK7.js.map +1 -0
- package/dist-lib/cdn/pl-as7f_-F8.js +2 -0
- package/dist-lib/cdn/pl-as7f_-F8.js.map +1 -0
- package/dist-lib/cdn/pt-BWJIdrI6.js +2 -0
- package/dist-lib/cdn/pt-BWJIdrI6.js.map +1 -0
- package/dist-lib/npm/{de-Cuz-uz3s.js → de-lDO0Tv9y.js} +3 -1
- package/dist-lib/npm/de-lDO0Tv9y.js.map +1 -0
- package/dist-lib/npm/{es-BnRzdU90.js → es-Cy3Mmj9C.js} +3 -1
- package/dist-lib/npm/es-Cy3Mmj9C.js.map +1 -0
- package/dist-lib/npm/{fr-B-nmvStg.js → fr-Ci0ZM0nG.js} +3 -1
- package/dist-lib/npm/fr-Ci0ZM0nG.js.map +1 -0
- package/dist-lib/npm/index.js +475 -160
- package/dist-lib/npm/index.js.map +1 -1
- package/dist-lib/npm/{it-DMTpE4GO.js → it-BiTHjgzI.js} +3 -1
- package/dist-lib/npm/it-BiTHjgzI.js.map +1 -0
- package/dist-lib/npm/{nl-DQkyEt9Z.js → nl-DZTwpAwV.js} +3 -1
- package/dist-lib/npm/nl-DZTwpAwV.js.map +1 -0
- package/dist-lib/npm/{pl-CcjU41yx.js → pl-DeWLtyMR.js} +3 -1
- package/dist-lib/npm/pl-DeWLtyMR.js.map +1 -0
- package/dist-lib/npm/{pt-Dulais2f.js → pt-CaqSW5TJ.js} +3 -1
- package/dist-lib/npm/pt-CaqSW5TJ.js.map +1 -0
- package/dist-lib/npm/types/context/HostContext.d.ts +24 -2
- package/dist-lib/npm/types/data/restDataSource.d.ts +2 -1
- package/dist-lib/npm/types/data/tenantDataSource.d.ts +2 -1
- package/dist-lib/npm/types/features/calendar/constants/views.d.ts +2 -2
- package/dist-lib/npm/types/i18n/messages/en/core.d.ts +1 -0
- package/dist-lib/npm/types/i18n/messages/en/events.d.ts +1 -0
- package/dist-lib/npm/types/i18n/messages/en/index.d.ts +2 -0
- package/dist-lib/npm/types/i18n/messages/index.d.ts +2 -0
- package/dist-lib/npm/types/lib/CalendarWidget.d.ts +1 -1
- package/dist-lib/npm/types/lib/config.d.ts +9 -26
- package/dist-lib/npm/types/lib/configFile.d.ts +6 -0
- package/dist-lib/npm/types/lib/defaults.d.ts +23 -1
- package/dist-lib/npm/types/lib/element.d.ts +5 -1
- package/dist-lib/npm/types/lib/index.d.ts +4 -2
- package/dist-lib/npm/types/lib/options.d.ts +35 -0
- package/dist-lib/npm/types/lib/useCalendarOptions.d.ts +11 -0
- package/dist-lib/npm/types/utils/calendarView.d.ts +1 -0
- package/package.json +8 -2
- package/schema/calendar-config.schema.json +232 -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
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.
|
|
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
|
-
|
|
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,216 +35,56 @@ 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
|
-
##
|
|
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
|
-
|
|
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,
|
|
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
|
-
|
|
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
|
-
|
|
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`. New events start in it. A zone the user picks in the settings takes precedence |
|
|
59
|
-
| `holidays` | `holidays` | from `locale` | Public holidays to show: country or region code such as `DE`, `DE-NW`, `AT`, `US-CA`, or `off`. Users can override it in the settings |
|
|
60
|
-
| `mapUrl` | `map-url` | Google Maps | Map service for locations, with `{query}` for the place, e.g. `https://www.openstreetmap.org/search?query={query}` or `https://maps.apple.com/?q={query}` |
|
|
61
|
-
| `holidaySource` | `holiday-source` | `library` | `library` computes holidays in the browser, `backend` asks your backend (`GET /holidays`) and falls back to the library |
|
|
62
|
-
| `storageMode` | `storage-mode` | `local` | `local` or `remote` |
|
|
63
|
-
| `apiBaseUrl` | `api-base-url` | `/api` | Base URL of your backend |
|
|
64
|
-
| `features` | `auth`, `teams` | auth off, teams on | `teams="false"` turns team features off |
|
|
65
|
-
| `tenant`, `getUserToken` | `tenant`, property | – | Multi-tenant backend, sign-in through your own page |
|
|
66
|
-
| `dataSource` | property | – | Custom data adapter instead of REST |
|
|
67
|
-
| `onEventCreate` / `Update` / `Delete` | `event-create` / `-update` / `-delete` | – | After every stored change |
|
|
68
|
-
|
|
69
|
-
**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.
|
|
70
|
-
|
|
71
|
-
```js
|
|
72
|
-
document.querySelector('calendar-widget').messages = {
|
|
73
|
-
de: { calendar: { newEvent: 'Neuer Eintrag' } },
|
|
74
|
-
sv: { calendar: { today: 'Idag', newEvent: 'Ny händelse' }, views: { weekNumber: (week) => `V. ${week}` } },
|
|
75
|
-
}
|
|
60
|
+
```html
|
|
61
|
+
<calendar-widget config="/calendar.config.yaml" style="height: 700px"></calendar-widget>
|
|
76
62
|
```
|
|
77
63
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
- The subscription is **read-only**. Changes made in the other app do not come back.
|
|
87
|
-
- 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.
|
|
88
|
-
- It stops working when the user leaves the calendar.
|
|
89
|
-
|
|
90
|
-
### Adding the link in calendar apps
|
|
91
|
-
|
|
92
|
-
| App | Steps |
|
|
93
|
-
| --- | --- |
|
|
94
|
-
| **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. |
|
|
95
|
-
| **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**. |
|
|
96
|
-
| **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. |
|
|
97
|
-
| **Outlook.com / Outlook on the web / new Outlook** | *Calendar → Add calendar → Subscribe from web*, paste the link, give it a name, **Import**. |
|
|
98
|
-
| **Classic Outlook for Windows** | *Home → Add Calendar → From Internet…* (in some versions *Open Calendar → From Internet*), paste the link, **OK**, confirm with **Yes**. |
|
|
99
|
-
| **Thunderbird** | *New Calendar → On the Network*, paste the link, choose the iCalendar (ICS) format. |
|
|
100
|
-
|
|
101
|
-
Menu names change between app versions. If a path does not match, look for “subscribe”, “from URL” or “from internet”.
|
|
102
|
-
|
|
103
|
-
### How quickly changes show up
|
|
104
|
-
|
|
105
|
-
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:
|
|
106
|
-
|
|
107
|
-
| App | Refresh |
|
|
108
|
-
| --- | --- |
|
|
109
|
-
| 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. |
|
|
110
|
-
| 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. |
|
|
111
|
-
| Google Calendar | Google's own schedule, usually several hours, sometimes up to a day. Cannot be changed. |
|
|
112
|
-
| Outlook.com / web / new Outlook | Microsoft's own schedule, roughly every 3 hours, sometimes more than 24 hours. Cannot be changed. |
|
|
113
|
-
| Classic Outlook for Windows | Follows the update limit in the feed (one hour here) and Outlook's send/receive settings. |
|
|
114
|
-
|
|
115
|
-
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.
|
|
116
|
-
|
|
117
|
-
## Event chat
|
|
118
|
-
|
|
119
|
-
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).
|
|
120
|
-
|
|
121
|
-
Messages go over REST (see the OpenAPI file, tag *Chat*). New, edited and deleted messages arrive live over a WebSocket:
|
|
122
|
-
|
|
123
|
-
- **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. Custom data sources can pass `chatSocketUrl` to `restDataSource`.
|
|
124
|
-
- **Sign-in:** the session cookie is sent with the handshake. Check the `Origin` header against the allowed origins and answer `401` without a session.
|
|
125
|
-
- **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.
|
|
126
|
-
- **Client → server:** only `{ "type": "ping" }` every 25 seconds, answer with `{ "type": "pong" }` or ignore it.
|
|
127
|
-
- 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.
|
|
128
|
-
|
|
129
|
-
Emails link to the host page with `?calendar=…&event=…&date=…&tab=chat`, which opens the event with the chat.
|
|
130
|
-
|
|
131
|
-
## Building your own backend
|
|
132
|
-
|
|
133
|
-
The full contract is [`api/openapi.yaml`](api/openapi.yaml) (OpenAPI 3.1, also shipped as `@rokoyfa/calendar/openapi.yaml`). The essentials:
|
|
134
|
-
|
|
135
|
-
### Data types
|
|
136
|
-
|
|
137
|
-
```ts
|
|
138
|
-
type CalendarEvent = EventInput & {
|
|
139
|
-
id: string
|
|
140
|
-
calendarId: string
|
|
141
|
-
createdAt: string // ISO date-time
|
|
142
|
-
updatedAt: string
|
|
143
|
-
}
|
|
144
|
-
|
|
145
|
-
type EventInput = {
|
|
146
|
-
uid: string // stable id for iCalendar, shared by a series and its detached events
|
|
147
|
-
title: string // 1–100 chars
|
|
148
|
-
location: string // max 200 chars, '' if none
|
|
149
|
-
links: EventLink[] // up to 10 http(s) links
|
|
150
|
-
startDate: string // 'YYYY-MM-DD'
|
|
151
|
-
start: string // 'HH:mm' in timeZone
|
|
152
|
-
endDate: string // inclusive for all-day events
|
|
153
|
-
end: string
|
|
154
|
-
allDay: boolean // start and end are '00:00'
|
|
155
|
-
timeZone: string | null // IANA zone, null = same local time everywhere (always null for all-day)
|
|
156
|
-
description: string // max 2000 chars
|
|
157
|
-
color: 'blue' | 'red' | 'green' | 'yellow' | `#${string}`
|
|
158
|
-
recurrence: Recurrence | null
|
|
159
|
-
excludedDates: string[] // occurrences removed from a series
|
|
160
|
-
seriesId: string | null // set on an occurrence detached from a series
|
|
161
|
-
originalDate: string | null // its original date in that series
|
|
162
|
-
reminders: number[] // minutes before the start, per user (see below)
|
|
163
|
-
attendees: Attendee[]
|
|
164
|
-
}
|
|
165
|
-
|
|
166
|
-
type Attendee = { email: string; name: string; status: 'needsAction' | 'accepted' | 'tentative' | 'declined' }
|
|
167
|
-
|
|
168
|
-
type EventLink = { url: string; label: string } // url max 2000 chars, label max 100 chars, '' if none
|
|
169
|
-
|
|
170
|
-
type Recurrence = {
|
|
171
|
-
frequency: 'daily' | 'weekly' | 'monthly' | 'yearly'
|
|
172
|
-
interval: number // 1–99
|
|
173
|
-
weekdays: number[] // 0 = Monday … 6 = Sunday
|
|
174
|
-
monthlyMode: 'dayOfMonth' | 'weekdayOfMonth' | 'lastWeekdayOfMonth'
|
|
175
|
-
until: string | null // either until or count, or neither
|
|
176
|
-
count: number | null
|
|
177
|
-
}
|
|
178
|
-
|
|
179
|
-
type CalendarSummary = {
|
|
180
|
-
id: string; teamId: string; name: string; color: string
|
|
181
|
-
kind: 'personal' | 'team'; teamName: string | null; description: string
|
|
182
|
-
role: 'owner' | 'admin' | 'manager' | 'editor' | 'member' | 'contributor' | 'viewer'
|
|
183
|
-
showInPersonal: boolean; permissions: string[]
|
|
184
|
-
}
|
|
185
|
-
|
|
186
|
-
type User = { id: string; email: string; name: string; emailVerified: boolean }
|
|
187
|
-
type Preferences = {
|
|
188
|
-
theme: 'system' | 'light' | 'dark'; defaultView: View; mobileDefaultView: View; locale: string
|
|
189
|
-
timeZone: string // 'auto' or IANA zone
|
|
190
|
-
holidays: string // 'auto', 'off' or a region such as 'DE-NW'
|
|
191
|
-
}
|
|
192
|
-
type PublicHoliday = { date: string; name: string } // GET /holidays, only with holiday-source="backend"
|
|
193
|
-
// Preferences also carry emailInvites, emailChanges, emailReminders, emailChat: booleans for the emails below
|
|
194
|
-
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
|
|
195
72
|
```
|
|
196
73
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
**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.
|
|
74
|
+
Commented example files with every option: [`demo/calendar.config.yaml`](demo/calendar.config.yaml) and [`demo/calendar.config.jsonc`](demo/calendar.config.jsonc).
|
|
200
75
|
|
|
201
|
-
|
|
76
|
+
## Documentation
|
|
202
77
|
|
|
203
|
-
|
|
|
78
|
+
| | |
|
|
204
79
|
| --- | --- |
|
|
205
|
-
|
|
|
206
|
-
|
|
|
207
|
-
|
|
|
208
|
-
|
|
|
209
|
-
|
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
| Search | `GET /events/search?q=…&calendarId=…` (optional: without it the component searches the last and next year via `GET /events`) |
|
|
213
|
-
| Answer as attendee | `POST /events/:id/response` with `{ status }` |
|
|
214
|
-
| Change only own reminders | `PUT /events/:id/reminders` with `{ reminders }` (also for members without edit rights) |
|
|
215
|
-
| Answer from an email link | `POST /events/respond` with `{ token, status }`, no session needed |
|
|
216
|
-
| 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` |
|
|
217
|
-
| Subscription link | `GET`, `POST` (new link), `DELETE /calendars/:id/feed`. The link points at your `GET /feeds/:token.ics` |
|
|
218
|
-
| Reminders | `GET /events` for the next four weeks of all calendars, every five minutes while the widget is open |
|
|
219
|
-
| Import .ics | `GET /events` for the whole calendar, then `PUT` for known `uid`s and `POST` for new ones |
|
|
220
|
-
| Settings, colors | `PATCH /preferences`, `POST /colors`, `DELETE /colors/:rrggbb` |
|
|
221
|
-
| Holidays (only with `holiday-source="backend"`) | `GET /holidays?from=…&to=…®ion=DE-NW&lang=de`, answer `PublicHoliday[]` |
|
|
222
|
-
| Sign-in, teams, invitations | `/auth/*`, `/calendars`, `/teams/*`, `/invitations/*`, see the OpenAPI file |
|
|
223
|
-
|
|
224
|
-
Before editing "following" or "all" of a series, the component loads its detached events with `GET /events?seriesId=…`.
|
|
225
|
-
|
|
226
|
-
### Rules for the backend
|
|
227
|
-
|
|
228
|
-
- **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.
|
|
229
|
-
- **Errors:** always `{ code, message }`. Known codes such as `invalidCredentials`, `emailTaken`, `forbidden`, `lastOwner` are shown translated, others with `message`.
|
|
230
|
-
- **Language:** every request carries `Accept-Language`. Use it, or the stored `locale`, for emails.
|
|
231
|
-
- **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.
|
|
232
|
-
- **Subscriptions:** `GET /feeds/:token.ics` answers without a session with the calendar as iCalendar (RFC 5545) and the subscriber's own reminders. Keep one secret token per user and calendar, a new one replaces the old. Stop serving it when the user leaves the calendar.
|
|
233
|
-
- **Email links:** point them at the host page with the screen as parameter, e.g. `https://host.example/calendar?calendarPath=%2Freset-password%3Ftoken%3D…`.
|
|
234
|
-
|
|
235
|
-
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.
|
|
236
87
|
|
|
237
88
|
## License
|
|
238
89
|
|
|
239
90
|
[MIT](LICENSE) © Rokoyfa
|
|
240
|
-
|
|
241
|
-
Public holiday data comes from [date-holidays](https://github.com/commenthol/date-holidays) (code ISC, data [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)). It is loaded only when holidays are shown.
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://unpkg.com/@rokoyfa/calendar/schema/calendar-config.schema.json",
|
|
3
|
+
|
|
4
|
+
// Example configuration for @rokoyfa/calendar.
|
|
5
|
+
//
|
|
6
|
+
// <calendar-widget config="/calendar.config.jsonc"></calendar-widget>
|
|
7
|
+
// <Calendar config="/calendar.config.jsonc" />
|
|
8
|
+
//
|
|
9
|
+
// Every entry is optional. Leave out what you do not need, the value shown here is
|
|
10
|
+
// the default unless a comment says otherwise. Props and attributes on the page win
|
|
11
|
+
// over this file. The file is public like everything a browser loads: no secrets.
|
|
12
|
+
//
|
|
13
|
+
// Comments are allowed in .json and .jsonc files. The last entry of an object must
|
|
14
|
+
// not end with a comma.
|
|
15
|
+
|
|
16
|
+
// ── Data ──────────────────────────────────────────────────────────────────────
|
|
17
|
+
|
|
18
|
+
// Where events are stored.
|
|
19
|
+
// local in the visitor's browser, no backend needed
|
|
20
|
+
// remote in your backend (see the Developer Guide, "Backend")
|
|
21
|
+
// With features.auth the sign-in decides: signed-in users use the backend, guests the browser.
|
|
22
|
+
"storageMode": "local",
|
|
23
|
+
|
|
24
|
+
// Base URL of your backend. Relative ("/api") or absolute ("https://api.example.com").
|
|
25
|
+
// Only used with storageMode "remote" or features.auth.
|
|
26
|
+
"apiBaseUrl": "/api",
|
|
27
|
+
|
|
28
|
+
// How long a request to the backend may take, in milliseconds.
|
|
29
|
+
"apiTimeoutMs": 10000,
|
|
30
|
+
|
|
31
|
+
// Multi-tenant backends: sent with every request as the X-Calendar-Tenant header.
|
|
32
|
+
// Setting it turns sign-in on. Default: not set.
|
|
33
|
+
// "tenant": "acme",
|
|
34
|
+
|
|
35
|
+
// ── Features ──────────────────────────────────────────────────────────────────
|
|
36
|
+
// Everything beyond the core calendar can be switched off. A feature that is off
|
|
37
|
+
// disappears from the interface and makes no requests to the backend.
|
|
38
|
+
|
|
39
|
+
"features": {
|
|
40
|
+
// Sign-in, registration and account pages. Needs the /auth endpoints.
|
|
41
|
+
"auth": false,
|
|
42
|
+
|
|
43
|
+
// Team calendars with members, roles and invitations. Needs sign-in.
|
|
44
|
+
"teams": true,
|
|
45
|
+
|
|
46
|
+
// Chat per event in team calendars. Needs teams, the chat endpoints and the WebSocket.
|
|
47
|
+
"chat": true,
|
|
48
|
+
|
|
49
|
+
// Inviting team members to events and answering with yes, maybe or no. Needs teams.
|
|
50
|
+
"attendees": true,
|
|
51
|
+
|
|
52
|
+
// Creating and editing recurring events. Existing series are still shown when off.
|
|
53
|
+
"recurrence": true,
|
|
54
|
+
|
|
55
|
+
// Reminders on events, shown as browser notifications or notices in the calendar.
|
|
56
|
+
"reminders": true,
|
|
57
|
+
|
|
58
|
+
// Website and other links on events.
|
|
59
|
+
"links": true,
|
|
60
|
+
|
|
61
|
+
// Opening an event's location in a map service (see mapUrl).
|
|
62
|
+
"mapLinks": true,
|
|
63
|
+
|
|
64
|
+
// Public holidays in the views, and their setting.
|
|
65
|
+
"holidays": true,
|
|
66
|
+
|
|
67
|
+
// Event search.
|
|
68
|
+
"search": true,
|
|
69
|
+
|
|
70
|
+
// Undo after moving or deleting an event. When off, deleting asks for confirmation.
|
|
71
|
+
"undo": true,
|
|
72
|
+
|
|
73
|
+
// "Duplicate" in the event dialog.
|
|
74
|
+
"duplicate": true,
|
|
75
|
+
|
|
76
|
+
// Keyboard shortcuts (T today, N new event, / search, D W M Y views, arrow keys).
|
|
77
|
+
"shortcuts": true,
|
|
78
|
+
|
|
79
|
+
// Subscription links for other calendar apps. Needs the feed endpoints.
|
|
80
|
+
"subscriptions": true,
|
|
81
|
+
|
|
82
|
+
// Import and export of .ics files in the calendar settings.
|
|
83
|
+
"importExport": true,
|
|
84
|
+
|
|
85
|
+
// The "Notifications" tab where signed-in users choose which e-mails they get.
|
|
86
|
+
// Your backend sends the e-mails.
|
|
87
|
+
"emailNotifications": true,
|
|
88
|
+
|
|
89
|
+
// Time zone per event and in the settings. When off, the automatic zone is always used.
|
|
90
|
+
"timeZones": true,
|
|
91
|
+
|
|
92
|
+
// Letting users add their own event colors.
|
|
93
|
+
"customColors": true
|
|
94
|
+
},
|
|
95
|
+
|
|
96
|
+
// ── Appearance ────────────────────────────────────────────────────────────────
|
|
97
|
+
|
|
98
|
+
// Views the user can switch between, any of: day, week, month, year.
|
|
99
|
+
// With a single view the switch disappears.
|
|
100
|
+
"views": ["day", "week", "month", "year"],
|
|
101
|
+
|
|
102
|
+
// View shown first. Default: the user's own start view (week on desktop, day on phones).
|
|
103
|
+
// "initialView": "month",
|
|
104
|
+
|
|
105
|
+
// Language and region, e.g. en-US, de-DE, fr-FR, pt-BR. Default: the browser's language.
|
|
106
|
+
// Users can change it in the settings.
|
|
107
|
+
// "locale": "de-DE",
|
|
108
|
+
|
|
109
|
+
// Theme while the user has chosen "system": light or dark. Default: follows the device.
|
|
110
|
+
// "theme": "dark",
|
|
111
|
+
|
|
112
|
+
// IANA time zone the calendar is shown in while the user has chosen "automatic".
|
|
113
|
+
// Default: the browser's zone.
|
|
114
|
+
// "timeZone": "Europe/Berlin",
|
|
115
|
+
|
|
116
|
+
// Region for public holidays: a country (DE, AT, US) or a region (DE-NW, US-CA), or "off".
|
|
117
|
+
// Default: derived from the language. Users can override it in the settings.
|
|
118
|
+
// "holidays": "DE-NW",
|
|
119
|
+
|
|
120
|
+
// Where public holidays come from.
|
|
121
|
+
// library computed in the browser
|
|
122
|
+
// backend asked from your backend (GET /holidays), falling back to the library
|
|
123
|
+
"holidaySource": "library",
|
|
124
|
+
|
|
125
|
+
// Map service for locations. {query} is replaced by the place. Default: Google Maps.
|
|
126
|
+
// "mapUrl": "https://www.openstreetmap.org/search?query={query}",
|
|
127
|
+
|
|
128
|
+
// Own texts per language. Only plain texts can be set here. Texts that are functions
|
|
129
|
+
// (for example with a count) need the "messages" prop or property instead.
|
|
130
|
+
// "messages": { "de": { "calendar": { "newEvent": "Neuer Eintrag" } } },
|
|
131
|
+
|
|
132
|
+
// ── Navigation ────────────────────────────────────────────────────────────────
|
|
133
|
+
|
|
134
|
+
// How the calendar's own pages (settings, sign-in, …) are addressed.
|
|
135
|
+
// memory inside the widget, the address bar stays untouched (right for embedding)
|
|
136
|
+
// browser in the address bar, when the calendar is the whole page
|
|
137
|
+
"routing": "memory",
|
|
138
|
+
|
|
139
|
+
// Path prefix for routing "browser", when the calendar does not live at "/". Default: none.
|
|
140
|
+
// "basename": "/calendar",
|
|
141
|
+
|
|
142
|
+
// Page the widget opens on. Default: the calendar itself.
|
|
143
|
+
// "initialPath": "/settings",
|
|
144
|
+
|
|
145
|
+
// Query parameter of your page that links from e-mails use to open a page of the widget,
|
|
146
|
+
// e.g. https://example.com/team?calendarPath=%2Freset-password%3Ftoken%3D…
|
|
147
|
+
// Set to false to turn it off. Only used with routing "memory".
|
|
148
|
+
"linkParam": "calendarPath"
|
|
149
|
+
}
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# yaml-language-server: $schema=https://unpkg.com/@rokoyfa/calendar/schema/calendar-config.schema.json
|
|
2
|
+
#
|
|
3
|
+
# Example configuration for @rokoyfa/calendar.
|
|
4
|
+
#
|
|
5
|
+
# <calendar-widget config="/calendar.config.yaml"></calendar-widget>
|
|
6
|
+
# <Calendar config="/calendar.config.yaml" />
|
|
7
|
+
#
|
|
8
|
+
# Every entry is optional. Leave out what you do not need, the value shown here is
|
|
9
|
+
# the default unless a comment says otherwise. Props and attributes on the page win
|
|
10
|
+
# over this file. The file is public like everything a browser loads: no secrets.
|
|
11
|
+
|
|
12
|
+
# ── Data ────────────────────────────────────────────────────────────────────────
|
|
13
|
+
|
|
14
|
+
# Where events are stored.
|
|
15
|
+
# local in the visitor's browser, no backend needed
|
|
16
|
+
# remote in your backend (see the Developer Guide, "Backend")
|
|
17
|
+
# With features.auth the sign-in decides: signed-in users use the backend, guests the browser.
|
|
18
|
+
storageMode: local
|
|
19
|
+
|
|
20
|
+
# Base URL of your backend. Relative ("/api") or absolute ("https://api.example.com").
|
|
21
|
+
# Only used with storageMode "remote" or features.auth.
|
|
22
|
+
apiBaseUrl: /api
|
|
23
|
+
|
|
24
|
+
# How long a request to the backend may take, in milliseconds.
|
|
25
|
+
apiTimeoutMs: 10000
|
|
26
|
+
|
|
27
|
+
# Multi-tenant backends: sent with every request as the X-Calendar-Tenant header.
|
|
28
|
+
# Setting it turns sign-in on. Default: not set.
|
|
29
|
+
# tenant: acme
|
|
30
|
+
|
|
31
|
+
# ── Features ────────────────────────────────────────────────────────────────────
|
|
32
|
+
# Everything beyond the core calendar can be switched off. A feature that is off
|
|
33
|
+
# disappears from the interface and makes no requests to the backend.
|
|
34
|
+
|
|
35
|
+
features:
|
|
36
|
+
# Sign-in, registration and account pages. Needs the /auth endpoints.
|
|
37
|
+
auth: false
|
|
38
|
+
|
|
39
|
+
# Team calendars with members, roles and invitations. Needs sign-in.
|
|
40
|
+
teams: true
|
|
41
|
+
|
|
42
|
+
# Chat per event in team calendars. Needs teams, the chat endpoints and the WebSocket.
|
|
43
|
+
chat: true
|
|
44
|
+
|
|
45
|
+
# Inviting team members to events and answering with yes, maybe or no. Needs teams.
|
|
46
|
+
attendees: true
|
|
47
|
+
|
|
48
|
+
# Creating and editing recurring events. Existing series are still shown when off.
|
|
49
|
+
recurrence: true
|
|
50
|
+
|
|
51
|
+
# Reminders on events, shown as browser notifications or notices in the calendar.
|
|
52
|
+
reminders: true
|
|
53
|
+
|
|
54
|
+
# Website and other links on events.
|
|
55
|
+
links: true
|
|
56
|
+
|
|
57
|
+
# Opening an event's location in a map service (see mapUrl).
|
|
58
|
+
mapLinks: true
|
|
59
|
+
|
|
60
|
+
# Public holidays in the views, and their setting.
|
|
61
|
+
holidays: true
|
|
62
|
+
|
|
63
|
+
# Event search.
|
|
64
|
+
search: true
|
|
65
|
+
|
|
66
|
+
# Undo after moving or deleting an event. When off, deleting asks for confirmation.
|
|
67
|
+
undo: true
|
|
68
|
+
|
|
69
|
+
# "Duplicate" in the event dialog.
|
|
70
|
+
duplicate: true
|
|
71
|
+
|
|
72
|
+
# Keyboard shortcuts (T today, N new event, / search, D W M Y views, arrow keys).
|
|
73
|
+
shortcuts: true
|
|
74
|
+
|
|
75
|
+
# Subscription links for other calendar apps. Needs the feed endpoints.
|
|
76
|
+
subscriptions: true
|
|
77
|
+
|
|
78
|
+
# Import and export of .ics files in the calendar settings.
|
|
79
|
+
importExport: true
|
|
80
|
+
|
|
81
|
+
# The "Notifications" tab where signed-in users choose which e-mails they get.
|
|
82
|
+
# Your backend sends the e-mails.
|
|
83
|
+
emailNotifications: true
|
|
84
|
+
|
|
85
|
+
# Time zone per event and in the settings. When off, the automatic zone is always used.
|
|
86
|
+
timeZones: true
|
|
87
|
+
|
|
88
|
+
# Letting users add their own event colors.
|
|
89
|
+
customColors: true
|
|
90
|
+
|
|
91
|
+
# ── Appearance ──────────────────────────────────────────────────────────────────
|
|
92
|
+
|
|
93
|
+
# Views the user can switch between, any of: day, week, month, year.
|
|
94
|
+
# With a single view the switch disappears.
|
|
95
|
+
views: [day, week, month, year]
|
|
96
|
+
|
|
97
|
+
# View shown first. Default: the user's own start view (week on desktop, day on phones).
|
|
98
|
+
# initialView: month
|
|
99
|
+
|
|
100
|
+
# Language and region, e.g. en-US, de-DE, fr-FR, pt-BR. Default: the browser's language.
|
|
101
|
+
# Users can change it in the settings.
|
|
102
|
+
# locale: de-DE
|
|
103
|
+
|
|
104
|
+
# Theme while the user has chosen "system": light or dark. Default: follows the device.
|
|
105
|
+
# theme: dark
|
|
106
|
+
|
|
107
|
+
# IANA time zone the calendar is shown in while the user has chosen "automatic".
|
|
108
|
+
# Default: the browser's zone.
|
|
109
|
+
# timeZone: Europe/Berlin
|
|
110
|
+
|
|
111
|
+
# Region for public holidays: a country (DE, AT, US) or a region (DE-NW, US-CA), or "off".
|
|
112
|
+
# Default: derived from the language. Users can override it in the settings.
|
|
113
|
+
# holidays: DE-NW
|
|
114
|
+
|
|
115
|
+
# Where public holidays come from.
|
|
116
|
+
# library computed in the browser
|
|
117
|
+
# backend asked from your backend (GET /holidays), falling back to the library
|
|
118
|
+
holidaySource: library
|
|
119
|
+
|
|
120
|
+
# Map service for locations. {query} is replaced by the place. Default: Google Maps.
|
|
121
|
+
# mapUrl: https://www.openstreetmap.org/search?query={query}
|
|
122
|
+
|
|
123
|
+
# Own texts per language. Only plain texts can be set here. Texts that are functions
|
|
124
|
+
# (for example with a count) need the "messages" prop or property instead.
|
|
125
|
+
# messages:
|
|
126
|
+
# de:
|
|
127
|
+
# calendar:
|
|
128
|
+
# newEvent: Neuer Eintrag
|
|
129
|
+
|
|
130
|
+
# ── Navigation ──────────────────────────────────────────────────────────────────
|
|
131
|
+
|
|
132
|
+
# How the calendar's own pages (settings, sign-in, …) are addressed.
|
|
133
|
+
# memory inside the widget, the address bar stays untouched (right for embedding)
|
|
134
|
+
# browser in the address bar, when the calendar is the whole page
|
|
135
|
+
routing: memory
|
|
136
|
+
|
|
137
|
+
# Path prefix for routing "browser", when the calendar does not live at "/". Default: none.
|
|
138
|
+
# basename: /calendar
|
|
139
|
+
|
|
140
|
+
# Page the widget opens on. Default: the calendar itself.
|
|
141
|
+
# initialPath: /settings
|
|
142
|
+
|
|
143
|
+
# Query parameter of your page that links from e-mails use to open a page of the widget,
|
|
144
|
+
# e.g. https://example.com/team?calendarPath=%2Freset-password%3Ftoken%3D…
|
|
145
|
+
# Set to false to turn it off. Only used with routing "memory".
|
|
146
|
+
linkParam: calendarPath
|