@rokoyfa/calendar 0.1.0 → 1.0.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 +17 -1
- package/README.md +107 -142
- package/api/openapi.yaml +10 -2
- package/dist-lib/cdn/calendar-widget.js +7 -7
- package/dist-lib/cdn/calendar-widget.js.map +1 -1
- package/dist-lib/cdn/de-BPZBZXaZ.js +2 -0
- package/dist-lib/cdn/de-BPZBZXaZ.js.map +1 -0
- package/dist-lib/cdn/es-DsIckdik.js +2 -0
- package/dist-lib/cdn/es-DsIckdik.js.map +1 -0
- package/dist-lib/cdn/fr-DWAs3O6J.js +2 -0
- package/dist-lib/cdn/fr-DWAs3O6J.js.map +1 -0
- package/dist-lib/cdn/it-CbhjxqIb.js +2 -0
- package/dist-lib/cdn/it-CbhjxqIb.js.map +1 -0
- package/dist-lib/cdn/nl-mjTHznX5.js +2 -0
- package/dist-lib/cdn/nl-mjTHznX5.js.map +1 -0
- package/dist-lib/cdn/pl-CXT0jb2D.js +2 -0
- package/dist-lib/cdn/pl-CXT0jb2D.js.map +1 -0
- package/dist-lib/cdn/pt-D0oXlVdU.js +2 -0
- package/dist-lib/cdn/pt-D0oXlVdU.js.map +1 -0
- package/dist-lib/npm/de-CCzGjeTd.js +573 -0
- package/dist-lib/npm/de-CCzGjeTd.js.map +1 -0
- package/dist-lib/npm/es-Ciaf66rH.js +559 -0
- package/dist-lib/npm/es-Ciaf66rH.js.map +1 -0
- package/dist-lib/npm/fr-CAqNm10Z.js +559 -0
- package/dist-lib/npm/fr-CAqNm10Z.js.map +1 -0
- package/dist-lib/npm/index.js +1130 -908
- package/dist-lib/npm/index.js.map +1 -1
- package/dist-lib/npm/it-Cqqdu2ua.js +565 -0
- package/dist-lib/npm/it-Cqqdu2ua.js.map +1 -0
- package/dist-lib/npm/nl-CkchSA8q.js +559 -0
- package/dist-lib/npm/nl-CkchSA8q.js.map +1 -0
- package/dist-lib/npm/pl-CCBDUr8k.js +565 -0
- package/dist-lib/npm/pl-CCBDUr8k.js.map +1 -0
- package/dist-lib/npm/pt-DucaCaoY.js +566 -0
- package/dist-lib/npm/pt-DucaCaoY.js.map +1 -0
- package/dist-lib/npm/types/components/DateTimeField.d.ts +2 -1
- package/dist-lib/npm/types/components/PageSection.d.ts +2 -1
- package/dist-lib/npm/types/config/routes.d.ts +1 -0
- package/dist-lib/npm/types/context/HostContext.d.ts +2 -0
- package/dist-lib/npm/types/features/calendar/components/DayColumn.d.ts +4 -1
- package/dist-lib/npm/types/features/calendar/components/EventChip.d.ts +3 -1
- package/dist-lib/npm/types/features/calendar/components/TimeGridView.d.ts +1 -1
- package/dist-lib/npm/types/features/calendar/context/DragContext.d.ts +2 -0
- package/dist-lib/npm/types/features/calendar/hooks/useEventDrag.d.ts +15 -0
- package/dist-lib/npm/types/features/calendar/types/view.d.ts +1 -0
- package/dist-lib/npm/types/features/calendar/utils/allDay.d.ts +12 -0
- package/dist-lib/npm/types/features/calendar/utils/eventDrag.d.ts +12 -0
- package/dist-lib/npm/types/features/calendar/utils/eventLabels.d.ts +1 -0
- package/dist-lib/npm/types/features/calendars/components/InvitationList.d.ts +1 -1
- package/dist-lib/npm/types/features/calendars/components/settings/RoleOverview.d.ts +1 -0
- package/dist-lib/npm/types/features/calendars/index.d.ts +1 -0
- package/dist-lib/npm/types/features/events/components/TimeZoneField.d.ts +6 -0
- package/dist-lib/npm/types/features/events/index.d.ts +2 -0
- package/dist-lib/npm/types/i18n/I18nContext.d.ts +1 -0
- package/dist-lib/npm/types/i18n/I18nProvider.d.ts +3 -1
- package/dist-lib/npm/types/i18n/index.d.ts +2 -2
- package/dist-lib/npm/types/i18n/locale.d.ts +13 -6
- package/dist-lib/npm/types/i18n/messages/en/calendars.d.ts +2 -0
- package/dist-lib/npm/types/i18n/messages/en/events.d.ts +4 -0
- package/dist-lib/npm/types/i18n/messages/en/index.d.ts +8 -6
- package/dist-lib/npm/types/i18n/messages/en/settings.d.ts +2 -6
- package/dist-lib/npm/types/i18n/messages/es/index.d.ts +2 -0
- package/dist-lib/npm/types/i18n/messages/fr/index.d.ts +2 -0
- package/dist-lib/npm/types/i18n/messages/index.d.ts +473 -4
- package/dist-lib/npm/types/i18n/messages/it/index.d.ts +2 -0
- package/dist-lib/npm/types/i18n/messages/nl/index.d.ts +2 -0
- package/dist-lib/npm/types/i18n/messages/pl/index.d.ts +2 -0
- package/dist-lib/npm/types/i18n/messages/pt/index.d.ts +2 -0
- package/dist-lib/npm/types/i18n/messages/types.d.ts +5 -0
- package/dist-lib/npm/types/lib/CalendarWidget.d.ts +1 -1
- package/dist-lib/npm/types/lib/config.d.ts +3 -0
- package/dist-lib/npm/types/lib/element.d.ts +4 -1
- package/dist-lib/npm/types/lib/index.d.ts +1 -0
- package/dist-lib/npm/types/utils/event.d.ts +19 -7
- package/dist-lib/npm/types/utils/preferences.d.ts +1 -2
- package/dist-lib/npm/types/utils/timeZone.d.ts +11 -0
- package/package.json +11 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,22 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
All notable changes to `@rokoyfa/calendar`. Versions follow [Semantic Versioning](https://semver.org/).
|
|
3
|
+
All notable changes to `@rokoyfa/calendar`. Versions follow [Semantic Versioning](https://semver.org/). From 1.0 on, breaking changes to props, attributes, DOM events, exported types, the data adapter and the REST contract only come with a new major version.
|
|
4
|
+
|
|
5
|
+
## 1.0.0 – 2026-11-11
|
|
6
|
+
|
|
7
|
+
First stable release. The public API is now frozen in the sense of SemVer.
|
|
8
|
+
|
|
9
|
+
**Upgrading from 0.1:** No changes are needed on the host page. Your own backend should store the new event fields `allDay` and `timeZone` and return them; events without them are read as before. `GET /events` is now called with a range one day wider on each side.
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
- All-day events: `allDay` in the event format, switch in the event dialog, all-day row above the day and week grid
|
|
13
|
+
- Time zones: events store an IANA `timeZone` (or `null` for the same local time everywhere), the dialog has a zone picker and shows the time in the viewer's zone, new prop `timeZone` / attribute `time-zone` sets the zone the calendar is shown in
|
|
14
|
+
- Move events by pressing and holding them for one second, then dragging (mouse and touch). In the day and week view the lower edge changes the end time. Recurring events ask whether to change this, the following or all events
|
|
15
|
+
- Events without `allDay`/`timeZone` keep working as floating timed events
|
|
16
|
+
- The visible range sent to the backend is one day wider on each side
|
|
17
|
+
- French, Spanish, Italian, Dutch, Polish and Portuguese, loaded on demand. Language names in the settings appear in their own language
|
|
18
|
+
- `messages` prop and property to override texts or add languages
|
|
19
|
+
- Automated tests with Vitest (`npm test`), run before every publish
|
|
4
20
|
|
|
5
21
|
## 0.1.0 – 2026-11-10
|
|
6
22
|
|
package/README.md
CHANGED
|
@@ -1,35 +1,18 @@
|
|
|
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. Day, week, month and year views, recurring events, team calendars with roles and invitations. English, German, French, Spanish, Italian, Dutch, Polish and Portuguese built in, more through your own texts. Runs without a backend (data stays in the browser) or against your own REST backend. Styles are isolated in a Shadow DOM, so the host page and the calendar never affect each other.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
- Recurring events (daily, weekly, monthly, yearly) with "this / following / all" editing
|
|
7
|
-
- Works without a backend (data stays in the browser) or with your own REST backend
|
|
8
|
-
- Accounts, team calendars with roles and email invitations when a backend is connected
|
|
9
|
-
- English and German, with week start, week numbers and 12/24-hour time taken from the user's region
|
|
10
|
-
- Light and dark theme, responsive to the size of the widget instead of the window
|
|
11
|
-
- Fully isolated in a Shadow DOM: the page's CSS does not leak in and the calendar's CSS does not leak out
|
|
5
|
+
## Setup
|
|
12
6
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
| | For | How |
|
|
16
|
-
| --- | --- | --- |
|
|
17
|
-
| React component `<Calendar />` | React 19 apps | `npm install @rokoyfa/calendar` |
|
|
18
|
-
| Web component `<calendar-widget>` | Any page: plain HTML, WordPress, Vue, Angular … | one `<script>` tag, React is bundled |
|
|
19
|
-
|
|
20
|
-
## Quick start
|
|
21
|
-
|
|
22
|
-
### Plain HTML (script tag)
|
|
7
|
+
**Any website**, React is bundled:
|
|
23
8
|
|
|
24
9
|
```html
|
|
25
|
-
<script type="module" src="https://cdn.jsdelivr.net/npm/@rokoyfa/calendar@
|
|
10
|
+
<script type="module" src="https://cdn.jsdelivr.net/npm/@rokoyfa/calendar@1/dist-lib/cdn/calendar-widget.js"></script>
|
|
26
11
|
|
|
27
12
|
<calendar-widget style="height: 700px"></calendar-widget>
|
|
28
13
|
```
|
|
29
14
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
### React
|
|
15
|
+
**React 19**:
|
|
33
16
|
|
|
34
17
|
```bash
|
|
35
18
|
npm install @rokoyfa/calendar
|
|
@@ -38,156 +21,138 @@ npm install @rokoyfa/calendar
|
|
|
38
21
|
```tsx
|
|
39
22
|
import { Calendar } from '@rokoyfa/calendar'
|
|
40
23
|
|
|
41
|
-
|
|
42
|
-
return <Calendar style={{ height: 700 }} />
|
|
43
|
-
}
|
|
24
|
+
<Calendar style={{ height: 700 }} />
|
|
44
25
|
```
|
|
45
26
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
**Give the calendar a height.** It fills its box and scrolls inside it.
|
|
27
|
+
Give the calendar a height, it fills its box. No CSS import is needed.
|
|
49
28
|
|
|
50
|
-
##
|
|
29
|
+
## Examples
|
|
51
30
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
| --- | --- | --- | --- |
|
|
56
|
-
| `locale` | `locale` | browser language | `en-US`, `en-GB`, `de-DE`, … Other languages fall back to English with the user's region. |
|
|
57
|
-
| `theme` | `theme` | system | `light` or `dark`. Applies while the user's own setting is "Automatic". |
|
|
58
|
-
| `initialView` | `initial-view` | user setting | `day`, `week`, `month` or `year` |
|
|
59
|
-
| `storageMode` | `storage-mode` | `local` | `local` (browser) or `remote` (REST backend) |
|
|
60
|
-
| `apiBaseUrl` | `api-base-url` | `/api` | Base URL of the REST backend |
|
|
61
|
-
| `apiTimeoutMs` | `api-timeout-ms` | `10000` | Timeout per request |
|
|
62
|
-
| `features.auth` | `auth` | off | Sign-in and registration inside the widget. Needs a backend. |
|
|
63
|
-
| `features.teams` | `teams` | on | Team calendars, invitations and the calendar switcher. `teams="false"` turns them off. |
|
|
64
|
-
| `tenant` | `tenant` | – | Public tenant id for a multi-tenant backend, see [Tenants](#tenants-and-sign-in-through-the-host-page) |
|
|
65
|
-
| `getUserToken` | property `getUserToken` | – | Sign in with a token from the host page instead of widget accounts |
|
|
66
|
-
| `dataSource` | property `dataSource` | – | Custom data adapter, see [Data sources](#data-sources) |
|
|
67
|
-
| `initialPath` | `initial-path` | `/` | Screen to open, e.g. `/settings` |
|
|
68
|
-
| `linkParam` | `link-param` | `calendarPath` | URL parameter the widget reads its start screen from, so links in emails can open e.g. the password reset. `false` turns it off. |
|
|
69
|
-
| `routing` | – | `memory` | `memory` keeps the page URL untouched. `browser` lets the calendar own the URL (full-page apps only). |
|
|
70
|
-
| `basename` | – | – | Path prefix with `routing="browser"` |
|
|
71
|
-
| `onEventCreate`, `onEventUpdate`, `onEventDelete` | events `event-create`, `event-update`, `event-delete` | – | Called after every stored change with the event (or `{ id }` when deleted) |
|
|
72
|
-
| `className`, `style` | `class`, `style` | – | Size and placement on your page |
|
|
73
|
-
|
|
74
|
-
Boolean attributes are on when present (`auth`) and off with `="false"`.
|
|
75
|
-
|
|
76
|
-
### Reacting to changes
|
|
77
|
-
|
|
78
|
-
```tsx
|
|
79
|
-
<Calendar onEventCreate={(event) => console.log('created', event.title, event.startDate)} />
|
|
80
|
-
```
|
|
31
|
+
```html
|
|
32
|
+
<!-- German, dark, month view -->
|
|
33
|
+
<calendar-widget locale="de-DE" theme="dark" initial-view="month" style="height: 600px"></calendar-widget>
|
|
81
34
|
|
|
82
|
-
|
|
83
|
-
|
|
35
|
+
<!-- Your backend with sign-in -->
|
|
36
|
+
<calendar-widget storage-mode="remote" auth api-base-url="https://api.example.com" style="height: 700px"></calendar-widget>
|
|
84
37
|
```
|
|
85
38
|
|
|
86
|
-
Editing a recurring series can store several changes at once (for example splitting a series), so one user action may fire more than one callback.
|
|
87
|
-
|
|
88
|
-
## Data sources
|
|
89
|
-
|
|
90
|
-
Where data lives is decided by a data source. The component stays the same.
|
|
91
|
-
|
|
92
39
|
```tsx
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
| Data source | Behaviour |
|
|
100
|
-
| --- | --- |
|
|
101
|
-
| `localDataSource()` | Everything in the browser, no sign-in. Default. |
|
|
102
|
-
| `restDataSource({ baseUrl, timeoutMs?, auth?, headers?, getAccessToken?, getUserToken? })` | Talks to a backend that implements [`api/openapi.yaml`](api/openapi.yaml). With `auth: true` (default) users sign in inside the widget; guests keep working in the browser. With `auth: false` every request goes to the backend, e.g. with `getAccessToken` returning your own bearer token. |
|
|
103
|
-
| `tenantDataSource({ tenant, baseUrl, getUserToken? })` | `restDataSource` for a multi-tenant backend, sends `X-Calendar-Tenant` |
|
|
104
|
-
| your own | Implement `CalendarDataSource`. All interfaces (`EventRepository`, `CalendarRepository`, `PreferencesRepository`, `ColorRepository`, `AuthRepository`) and data types are exported. |
|
|
105
|
-
|
|
106
|
-
```ts
|
|
107
|
-
import { localDataSource, type CalendarDataSource } from '@rokoyfa/calendar'
|
|
108
|
-
|
|
109
|
-
const myDataSource: CalendarDataSource = {
|
|
110
|
-
connect: (session, context) => ({ ...localDataSource().connect(session, context), events: myEventRepository }),
|
|
111
|
-
}
|
|
40
|
+
<Calendar
|
|
41
|
+
storageMode="remote"
|
|
42
|
+
apiBaseUrl="https://api.example.com"
|
|
43
|
+
features={{ auth: true, teams: false }}
|
|
44
|
+
onEventCreate={(event) => console.log('created', event)}
|
|
45
|
+
/>
|
|
112
46
|
```
|
|
113
47
|
|
|
114
|
-
`connect` is called again when the user signs in or out. `createAuthRepository` is optional; without it there is no sign-in.
|
|
115
|
-
|
|
116
|
-
With the web component, set the property from JavaScript:
|
|
117
|
-
|
|
118
48
|
```js
|
|
119
|
-
document.querySelector('calendar-widget').
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
## Using your own backend
|
|
123
|
-
|
|
124
|
-
The REST contract is published as **OpenAPI 3.1** in [`api/openapi.yaml`](api/openapi.yaml) (also inside the package as `@rokoyfa/calendar/openapi.yaml`): authentication, events, calendars, teams, invitations, preferences, error codes and permissions.
|
|
125
|
-
|
|
126
|
-
```html
|
|
127
|
-
<calendar-widget storage-mode="remote" auth api-base-url="https://api.example.com" style="height: 700px"></calendar-widget>
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
Things to know when the widget runs on another domain than your backend:
|
|
131
|
-
|
|
132
|
-
- Requests use `credentials: 'include'`. The backend must answer CORS for the host page's origin with `Access-Control-Allow-Credentials: true` and allow the headers `Content-Type`, `Accept`, `Accept-Language`, `Authorization` and `X-Calendar-Tenant`.
|
|
133
|
-
- A session cookie must be `SameSite=None; Secure`. Browsers that block third-party cookies will still drop it, so for cross-site embedding prefer a bearer token (`getAccessToken`) or host sign-in (`getUserToken`).
|
|
134
|
-
- Errors are `{ "code": "…", "message": "…" }`. Known codes are shown translated, others with their message.
|
|
135
|
-
- Every request sends `Accept-Language`, so your emails can match the user's language.
|
|
136
|
-
|
|
137
|
-
**Links in emails** (confirm email, reset password, invitations): point them at the page that hosts the widget and add the screen as a parameter, for example `https://your-site.example/calendar?calendarPath=%2Freset-password%3Ftoken%3D…`. The widget opens that screen.
|
|
138
|
-
|
|
139
|
-
## Tenants and sign-in through the host page
|
|
140
|
-
|
|
141
|
-
For a backend that serves several websites, pass a public tenant id. Every request then carries `X-Calendar-Tenant`.
|
|
142
|
-
|
|
143
|
-
```html
|
|
144
|
-
<calendar-widget tenant="acme" api-base-url="https://api.example.com" style="height: 700px"></calendar-widget>
|
|
49
|
+
document.querySelector('calendar-widget').addEventListener('event-create', (e) => console.log(e.detail))
|
|
145
50
|
```
|
|
146
51
|
|
|
147
|
-
|
|
52
|
+
| Prop | Attribute | Default | |
|
|
53
|
+
| --- | --- | --- | --- |
|
|
54
|
+
| `locale` | `locale` | browser | `en-US`, `de-DE`, `fr-FR`, `pt-BR`, … Formats follow the region |
|
|
55
|
+
| `messages` | property | – | Own texts per language, see below |
|
|
56
|
+
| `theme` | `theme` | system | `light`, `dark` |
|
|
57
|
+
| `initialView` | `initial-view` | user setting | `day`, `week`, `month`, `year` |
|
|
58
|
+
| `timeZone` | `time-zone` | browser | IANA zone the calendar is shown in, e.g. `Europe/Berlin` |
|
|
59
|
+
| `storageMode` | `storage-mode` | `local` | `local` or `remote` |
|
|
60
|
+
| `apiBaseUrl` | `api-base-url` | `/api` | Base URL of your backend |
|
|
61
|
+
| `features` | `auth`, `teams` | auth off, teams on | `teams="false"` turns team features off |
|
|
62
|
+
| `tenant`, `getUserToken` | `tenant`, property | – | Multi-tenant backend, sign-in through your own page |
|
|
63
|
+
| `dataSource` | property | – | Custom data adapter instead of REST |
|
|
64
|
+
| `onEventCreate` / `Update` / `Delete` | `event-create` / `-update` / `-delete` | – | After every stored change |
|
|
65
|
+
|
|
66
|
+
**Own texts and languages.** Override single texts or add a language. Missing texts fall back to the built-in language, or to English for a new one. The full list of keys is the `Messages` type.
|
|
148
67
|
|
|
149
68
|
```js
|
|
150
|
-
document.querySelector('calendar-widget').
|
|
69
|
+
document.querySelector('calendar-widget').messages = {
|
|
70
|
+
de: { calendar: { newEvent: 'Neuer Eintrag' } },
|
|
71
|
+
sv: { calendar: { today: 'Idag', newEvent: 'Ny händelse' }, views: { weekNumber: (week) => `V. ${week}` } },
|
|
72
|
+
}
|
|
151
73
|
```
|
|
152
74
|
|
|
153
|
-
|
|
154
|
-
<Calendar tenant="acme" apiBaseUrl="https://api.example.com" getUserToken={() => fetch('/calendar-token').then((r) => r.text())} />
|
|
155
|
-
```
|
|
75
|
+
The CDN build loads languages other than English on demand from files next to `calendar-widget.js`. When hosting it yourself, copy the whole `dist-lib/cdn` folder.
|
|
156
76
|
|
|
157
|
-
|
|
77
|
+
**Demo:** [`demo/cdn.html`](demo/cdn.html) shows local mode with an event log, a dark German month view and a compact widget. Download it and open it in a browser, it loads the published package from jsDelivr.
|
|
158
78
|
|
|
159
|
-
##
|
|
79
|
+
## Building your own backend
|
|
160
80
|
|
|
161
|
-
|
|
81
|
+
The full contract is [`api/openapi.yaml`](api/openapi.yaml) (OpenAPI 3.1, also shipped as `@rokoyfa/calendar/openapi.yaml`). The essentials:
|
|
162
82
|
|
|
163
|
-
|
|
83
|
+
### Data types
|
|
164
84
|
|
|
165
|
-
|
|
85
|
+
```ts
|
|
86
|
+
type CalendarEvent = EventInput & {
|
|
87
|
+
id: string
|
|
88
|
+
calendarId: string
|
|
89
|
+
createdAt: string // ISO date-time
|
|
90
|
+
updatedAt: string
|
|
91
|
+
}
|
|
166
92
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
93
|
+
type EventInput = {
|
|
94
|
+
title: string // 1–100 chars
|
|
95
|
+
startDate: string // 'YYYY-MM-DD'
|
|
96
|
+
start: string // 'HH:mm' in timeZone
|
|
97
|
+
endDate: string // inclusive for all-day events
|
|
98
|
+
end: string
|
|
99
|
+
allDay: boolean // start and end are '00:00'
|
|
100
|
+
timeZone: string | null // IANA zone, null = same local time everywhere (always null for all-day)
|
|
101
|
+
description: string // max 2000 chars
|
|
102
|
+
color: 'blue' | 'red' | 'green' | 'yellow' | `#${string}`
|
|
103
|
+
recurrence: Recurrence | null
|
|
104
|
+
excludedDates: string[] // occurrences removed from a series
|
|
105
|
+
seriesId: string | null // set on an occurrence detached from a series
|
|
106
|
+
originalDate: string | null // its original date in that series
|
|
107
|
+
}
|
|
171
108
|
|
|
172
|
-
|
|
109
|
+
type Recurrence = {
|
|
110
|
+
frequency: 'daily' | 'weekly' | 'monthly' | 'yearly'
|
|
111
|
+
interval: number // 1–99
|
|
112
|
+
weekdays: number[] // 0 = Monday … 6 = Sunday
|
|
113
|
+
monthlyMode: 'dayOfMonth' | 'weekdayOfMonth' | 'lastWeekdayOfMonth'
|
|
114
|
+
until: string | null // either until or count, or neither
|
|
115
|
+
count: number | null
|
|
116
|
+
}
|
|
173
117
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
118
|
+
type CalendarSummary = {
|
|
119
|
+
id: string; teamId: string; name: string; color: string
|
|
120
|
+
kind: 'personal' | 'team'; teamName: string | null; description: string
|
|
121
|
+
role: 'owner' | 'admin' | 'manager' | 'editor' | 'member' | 'contributor' | 'viewer'
|
|
122
|
+
showInPersonal: boolean; permissions: string[]
|
|
123
|
+
}
|
|
177
124
|
|
|
178
|
-
|
|
179
|
-
|
|
125
|
+
type User = { id: string; email: string; name: string; emailVerified: boolean }
|
|
126
|
+
type Preferences = { theme: 'system' | 'light' | 'dark'; defaultView: View; mobileDefaultView: View; locale: string }
|
|
127
|
+
type Problem = { code: string; message: string } // every error response
|
|
180
128
|
```
|
|
181
129
|
|
|
182
|
-
|
|
130
|
+
The backend stores series as one event. The component expands occurrences itself.
|
|
183
131
|
|
|
184
|
-
|
|
132
|
+
### When the component calls your backend
|
|
185
133
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
134
|
+
| Moment | Requests |
|
|
135
|
+
| --- | --- |
|
|
136
|
+
| Widget loads | `GET /auth/me` (only with `auth`), then `GET /preferences`, `GET /colors`, `GET /calendars`, `GET /invitations` |
|
|
137
|
+
| Visible range changes | `GET /events?from=…&to=…&calendarId=…` with the calendars shown. The range is one day wider than the view to cover time zone shifts. Return every event in the range **and** every series that can occur in it. |
|
|
138
|
+
| Create event | `POST /events` with `EventInput` + `calendarId` |
|
|
139
|
+
| Edit event / whole series | `PUT /events/:id` with the full `EventInput` |
|
|
140
|
+
| Edit only this occurrence | `PUT` the series with the date added to `excludedDates`, then `POST` a detached event with `seriesId` and `originalDate` |
|
|
141
|
+
| Edit this and following | `PUT` the series with `until` set to the day before (and `count: null`), `POST` a new series, `PUT` later detached events to relink them |
|
|
142
|
+
| Delete | single: `PUT` with `excludedDates` · following: `PUT` with `until`, `DELETE` its later detached events · all: `DELETE` detached events, then the series · plain: `DELETE /events/:id` |
|
|
143
|
+
| Settings, colors | `PATCH /preferences`, `POST /colors`, `DELETE /colors/:rrggbb` |
|
|
144
|
+
| Sign-in, teams, invitations | `/auth/*`, `/calendars`, `/teams/*`, `/invitations/*`, see the OpenAPI file |
|
|
145
|
+
|
|
146
|
+
Before editing "following" or "all" of a series, the component loads its detached events with `GET /events?seriesId=…`.
|
|
147
|
+
|
|
148
|
+
### Rules for the backend
|
|
149
|
+
|
|
150
|
+
- **Sessions:** requests use `credentials: 'include'`. Set an `HttpOnly` cookie on sign-in. If the widget runs on another domain: CORS for that origin with `Access-Control-Allow-Credentials: true`, allowed headers `Content-Type`, `Accept`, `Accept-Language`, `Authorization`, `X-Calendar-Tenant`, and the cookie as `SameSite=None; Secure`. Answer `401` when the session is gone.
|
|
151
|
+
- **Errors:** always `{ code, message }`. Known codes such as `invalidCredentials`, `emailTaken`, `forbidden`, `lastOwner` are shown translated, others with `message`.
|
|
152
|
+
- **Language:** every request carries `Accept-Language`. Use it, or the stored `locale`, for emails.
|
|
153
|
+
- **Email links:** point them at the host page with the screen as parameter, e.g. `https://host.example/calendar?calendarPath=%2Freset-password%3Ftoken%3D…`.
|
|
154
|
+
|
|
155
|
+
Building, the test backend and all internals are described in German in [DEVELOPMENT.md](DEVELOPMENT.md).
|
|
191
156
|
|
|
192
157
|
## License
|
|
193
158
|
|
package/api/openapi.yaml
CHANGED
|
@@ -4,7 +4,7 @@ info:
|
|
|
4
4
|
version: 1.0.0
|
|
5
5
|
description: |
|
|
6
6
|
REST contract between the calendar component (`restDataSource`) and a backend.
|
|
7
|
-
The test backend (`TestBE`) is the reference implementation
|
|
7
|
+
The test backend (`TestBE`) is the reference implementation.
|
|
8
8
|
|
|
9
9
|
- Authentication uses an HttpOnly session cookie set by the backend. Alternatively a host can send
|
|
10
10
|
`Authorization: Bearer …` (`restDataSource({ getAccessToken })`).
|
|
@@ -143,7 +143,7 @@ paths:
|
|
|
143
143
|
tags: [Auth]
|
|
144
144
|
summary: Sign in with a token issued by the host page
|
|
145
145
|
description: |
|
|
146
|
-
Verifies signature, expiry and tenant, creates the user on first use (
|
|
146
|
+
Verifies signature, expiry and tenant, creates the user on first use (linked to `sub`) and starts a session.
|
|
147
147
|
`401` with `invalidUserToken`, `403` with `unknownTenant` or when token sign-in is disabled for the tenant.
|
|
148
148
|
security: []
|
|
149
149
|
parameters:
|
|
@@ -792,6 +792,14 @@ components:
|
|
|
792
792
|
start: { $ref: '#/components/schemas/Time' }
|
|
793
793
|
endDate: { $ref: '#/components/schemas/ISODate' }
|
|
794
794
|
end: { $ref: '#/components/schemas/Time' }
|
|
795
|
+
allDay:
|
|
796
|
+
type: boolean
|
|
797
|
+
default: false
|
|
798
|
+
description: All-day events cover startDate to endDate inclusive. start and end are '00:00'.
|
|
799
|
+
timeZone:
|
|
800
|
+
description: IANA zone of start and end, e.g. 'Europe/Berlin'. null keeps the same local time in every zone and is always null for all-day events.
|
|
801
|
+
oneOf: [{ type: string }, { type: 'null' }]
|
|
802
|
+
default: null
|
|
795
803
|
description: { type: string, maxLength: 2000 }
|
|
796
804
|
color: { $ref: '#/components/schemas/EventColor' }
|
|
797
805
|
recurrence: { oneOf: [{ $ref: '#/components/schemas/Recurrence' }, { type: 'null' }] }
|