@rokoyfa/calendar 0.1.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/CHANGELOG.md +21 -1
  2. package/README.md +107 -142
  3. package/api/openapi.yaml +10 -2
  4. package/dist-lib/cdn/calendar-widget.js +7 -7
  5. package/dist-lib/cdn/calendar-widget.js.map +1 -1
  6. package/dist-lib/cdn/de-BPZBZXaZ.js +2 -0
  7. package/dist-lib/cdn/de-BPZBZXaZ.js.map +1 -0
  8. package/dist-lib/cdn/es-DsIckdik.js +2 -0
  9. package/dist-lib/cdn/es-DsIckdik.js.map +1 -0
  10. package/dist-lib/cdn/fr-DWAs3O6J.js +2 -0
  11. package/dist-lib/cdn/fr-DWAs3O6J.js.map +1 -0
  12. package/dist-lib/cdn/it-CbhjxqIb.js +2 -0
  13. package/dist-lib/cdn/it-CbhjxqIb.js.map +1 -0
  14. package/dist-lib/cdn/nl-mjTHznX5.js +2 -0
  15. package/dist-lib/cdn/nl-mjTHznX5.js.map +1 -0
  16. package/dist-lib/cdn/pl-CXT0jb2D.js +2 -0
  17. package/dist-lib/cdn/pl-CXT0jb2D.js.map +1 -0
  18. package/dist-lib/cdn/pt-D0oXlVdU.js +2 -0
  19. package/dist-lib/cdn/pt-D0oXlVdU.js.map +1 -0
  20. package/dist-lib/npm/de-CCzGjeTd.js +573 -0
  21. package/dist-lib/npm/de-CCzGjeTd.js.map +1 -0
  22. package/dist-lib/npm/es-Ciaf66rH.js +559 -0
  23. package/dist-lib/npm/es-Ciaf66rH.js.map +1 -0
  24. package/dist-lib/npm/fr-CAqNm10Z.js +559 -0
  25. package/dist-lib/npm/fr-CAqNm10Z.js.map +1 -0
  26. package/dist-lib/npm/index.js +1159 -911
  27. package/dist-lib/npm/index.js.map +1 -1
  28. package/dist-lib/npm/it-Cqqdu2ua.js +565 -0
  29. package/dist-lib/npm/it-Cqqdu2ua.js.map +1 -0
  30. package/dist-lib/npm/nl-CkchSA8q.js +559 -0
  31. package/dist-lib/npm/nl-CkchSA8q.js.map +1 -0
  32. package/dist-lib/npm/pl-CCBDUr8k.js +565 -0
  33. package/dist-lib/npm/pl-CCBDUr8k.js.map +1 -0
  34. package/dist-lib/npm/pt-DucaCaoY.js +566 -0
  35. package/dist-lib/npm/pt-DucaCaoY.js.map +1 -0
  36. package/dist-lib/npm/types/components/DateTimeField.d.ts +2 -1
  37. package/dist-lib/npm/types/components/PageSection.d.ts +2 -1
  38. package/dist-lib/npm/types/config/routes.d.ts +1 -0
  39. package/dist-lib/npm/types/context/HostContext.d.ts +2 -0
  40. package/dist-lib/npm/types/features/calendar/components/DayColumn.d.ts +4 -1
  41. package/dist-lib/npm/types/features/calendar/components/EventChip.d.ts +3 -1
  42. package/dist-lib/npm/types/features/calendar/components/TimeGridView.d.ts +1 -1
  43. package/dist-lib/npm/types/features/calendar/context/DragContext.d.ts +2 -0
  44. package/dist-lib/npm/types/features/calendar/hooks/useEventDrag.d.ts +15 -0
  45. package/dist-lib/npm/types/features/calendar/types/view.d.ts +1 -0
  46. package/dist-lib/npm/types/features/calendar/utils/allDay.d.ts +12 -0
  47. package/dist-lib/npm/types/features/calendar/utils/eventDrag.d.ts +12 -0
  48. package/dist-lib/npm/types/features/calendar/utils/eventLabels.d.ts +1 -0
  49. package/dist-lib/npm/types/features/calendars/components/InvitationList.d.ts +1 -1
  50. package/dist-lib/npm/types/features/calendars/components/settings/RoleOverview.d.ts +1 -0
  51. package/dist-lib/npm/types/features/calendars/index.d.ts +1 -0
  52. package/dist-lib/npm/types/features/events/components/TimeZoneField.d.ts +6 -0
  53. package/dist-lib/npm/types/features/events/index.d.ts +2 -0
  54. package/dist-lib/npm/types/i18n/I18nContext.d.ts +1 -0
  55. package/dist-lib/npm/types/i18n/I18nProvider.d.ts +3 -1
  56. package/dist-lib/npm/types/i18n/index.d.ts +2 -2
  57. package/dist-lib/npm/types/i18n/locale.d.ts +13 -6
  58. package/dist-lib/npm/types/i18n/messages/en/calendars.d.ts +2 -0
  59. package/dist-lib/npm/types/i18n/messages/en/events.d.ts +4 -0
  60. package/dist-lib/npm/types/i18n/messages/en/index.d.ts +8 -6
  61. package/dist-lib/npm/types/i18n/messages/en/settings.d.ts +2 -6
  62. package/dist-lib/npm/types/i18n/messages/es/index.d.ts +2 -0
  63. package/dist-lib/npm/types/i18n/messages/fr/index.d.ts +2 -0
  64. package/dist-lib/npm/types/i18n/messages/index.d.ts +473 -4
  65. package/dist-lib/npm/types/i18n/messages/it/index.d.ts +2 -0
  66. package/dist-lib/npm/types/i18n/messages/nl/index.d.ts +2 -0
  67. package/dist-lib/npm/types/i18n/messages/pl/index.d.ts +2 -0
  68. package/dist-lib/npm/types/i18n/messages/pt/index.d.ts +2 -0
  69. package/dist-lib/npm/types/i18n/messages/types.d.ts +5 -0
  70. package/dist-lib/npm/types/lib/CalendarWidget.d.ts +1 -1
  71. package/dist-lib/npm/types/lib/config.d.ts +3 -0
  72. package/dist-lib/npm/types/lib/element.d.ts +4 -1
  73. package/dist-lib/npm/types/lib/index.d.ts +1 -0
  74. package/dist-lib/npm/types/utils/event.d.ts +19 -7
  75. package/dist-lib/npm/types/utils/preferences.d.ts +1 -2
  76. package/dist-lib/npm/types/utils/timeZone.d.ts +11 -0
  77. package/package.json +11 -5
package/CHANGELOG.md CHANGED
@@ -1,6 +1,26 @@
1
1
  # Changelog
2
2
 
3
- All notable changes to `@rokoyfa/calendar`. Versions follow [Semantic Versioning](https://semver.org/). Until 1.0, minor versions may contain breaking changes.
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.1.0 – 2026-11-11
6
+
7
+ - Arrow keys switch to the previous or next day, week, month or year also right after loading and after closing a dialog, not only after clicking into the calendar. With several calendars on a page, the last used one reacts
8
+
9
+ ## 1.0.0 – 2026-11-11
10
+
11
+ First stable release. The public API is now frozen in the sense of SemVer.
12
+
13
+ **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.
14
+
15
+
16
+ - All-day events: `allDay` in the event format, switch in the event dialog, all-day row above the day and week grid
17
+ - 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
18
+ - 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
19
+ - Events without `allDay`/`timeZone` keep working as floating timed events
20
+ - The visible range sent to the backend is one day wider on each side
21
+ - French, Spanish, Italian, Dutch, Polish and Portuguese, loaded on demand. Language names in the settings appear in their own language
22
+ - `messages` prop and property to override texts or add languages
23
+ - Automated tests with Vitest (`npm test`), run before every publish
4
24
 
5
25
  ## 0.1.0 – 2026-11-10
6
26
 
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
- - Day, week, month and year views, drag to select a time range (long-press on touch devices)
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
- Two ways to use it, both from the same package:
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@0.1/dist-lib/cdn/calendar-widget.js"></script>
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
- That's it. Without further attributes the calendar stores everything in the visitor's browser (localStorage).
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
- export function Page() {
42
- return <Calendar style={{ height: 700 }} />
43
- }
24
+ <Calendar style={{ height: 700 }} />
44
25
  ```
45
26
 
46
- `react` and `react-dom` (19.x) are peer dependencies. No CSS import is needed, styles ship inside the component.
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
- ## Options
29
+ ## Examples
51
30
 
52
- Every option exists as a React prop. Most also exist as an attribute of `<calendar-widget>`.
53
-
54
- | Prop | Attribute | Default | Description |
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
- ```js
83
- document.querySelector('calendar-widget').addEventListener('event-create', (e) => console.log(e.detail))
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
- import { Calendar, localDataSource, restDataSource } from '@rokoyfa/calendar'
94
-
95
- <Calendar dataSource={localDataSource()} />
96
- <Calendar dataSource={restDataSource({ baseUrl: 'https://api.example.com' })} />
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').dataSource = myDataSource
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
- If your site already has its own users, let the widget sign them in with a short-lived token signed by your server:
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').getUserToken = async () => (await fetch('/calendar-token')).text()
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
- ```tsx
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
- The widget exchanges the token at `POST /auth/token` for a session and repeats this when the session expires. Sign-in, registration, password screens and the sign-out button are hidden in this mode. Return `null` when nobody is signed in on your page; the widget then works as a guest in the browser.
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
- ## Languages and regions
79
+ ## Building your own backend
160
80
 
161
- English is the default, German is included. The language comes from, in this order: the user's own setting in the widget, the `locale` option, the browser, `en-US`.
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
- Formats follow the region: `en-US` starts weeks on Sunday with 12-hour time and US week numbers, `en-GB` and `de-DE` start on Monday with 24-hour time and ISO week numbers. Abbreviations are translated too (`Wk 45` / `KW 45`).
83
+ ### Data types
164
84
 
165
- ## Isolation and sizing
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
- - The calendar renders into a Shadow DOM. Your page's styles cannot break it and its styles cannot change your page.
168
- - Breakpoints use container queries, so a narrow widget on a wide screen gets the compact layout.
169
- - Several widgets on one page are independent. Widgets in `local` mode on the same page share the browser storage.
170
- - With `routing="memory"` (default) the calendar never changes your page's URL.
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
- ## Version
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
- ```ts
175
- import { VERSION } from '@rokoyfa/calendar'
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
- ```js
179
- customElements.get('calendar-widget').version
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
- Pin a version on the CDN with the full number (`@rokoyfa/calendar@0.1.0`) or follow patch releases with `@0.1`. See [CHANGELOG.md](CHANGELOG.md).
130
+ The backend stores series as one event. The component expands occurrences itself.
183
131
 
184
- ## Browser support
132
+ ### When the component calls your backend
185
133
 
186
- Current Chrome, Edge, Firefox and Safari (ES2022, Shadow DOM, constructable stylesheets, container queries).
187
-
188
- ## Development
189
-
190
- Building, the test backend, the database schema and all internals are described (in German) in [DEVELOPMENT.md](DEVELOPMENT.md).
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, `database/` the reference schema.
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 (`external_id` = `sub`) and starts a session.
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' }] }