@rokoyfa/calendar 0.0.0-stage → 0.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 (218) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/LICENSE +21 -0
  3. package/README.md +194 -3
  4. package/api/openapi.yaml +911 -0
  5. package/dist-lib/cdn/calendar-widget.js +14 -0
  6. package/dist-lib/cdn/calendar-widget.js.map +1 -0
  7. package/dist-lib/npm/index.d.ts +1 -0
  8. package/dist-lib/npm/index.js +13055 -0
  9. package/dist-lib/npm/index.js.map +1 -0
  10. package/dist-lib/npm/types/components/Button.d.ts +17 -0
  11. package/dist-lib/npm/types/components/ChoiceChip.d.ts +13 -0
  12. package/dist-lib/npm/types/components/ConfirmModal.d.ts +11 -0
  13. package/dist-lib/npm/types/components/DateTimeField.d.ts +14 -0
  14. package/dist-lib/npm/types/components/Form.d.ts +8 -0
  15. package/dist-lib/npm/types/components/FormField.d.ts +10 -0
  16. package/dist-lib/npm/types/components/IconButton.d.ts +11 -0
  17. package/dist-lib/npm/types/components/Icons.d.ts +10 -0
  18. package/dist-lib/npm/types/components/Modal.d.ts +10 -0
  19. package/dist-lib/npm/types/components/NumberField.d.ts +12 -0
  20. package/dist-lib/npm/types/components/PageLayout.d.ts +13 -0
  21. package/dist-lib/npm/types/components/PageSection.d.ts +9 -0
  22. package/dist-lib/npm/types/components/PasswordField.d.ts +4 -0
  23. package/dist-lib/npm/types/components/SegmentedControl.d.ts +11 -0
  24. package/dist-lib/npm/types/components/SegmentedField.d.ts +11 -0
  25. package/dist-lib/npm/types/components/SelectField.d.ts +13 -0
  26. package/dist-lib/npm/types/components/StatusMessage.d.ts +13 -0
  27. package/dist-lib/npm/types/components/Stepper.d.ts +9 -0
  28. package/dist-lib/npm/types/components/Switch.d.ts +8 -0
  29. package/dist-lib/npm/types/components/Tabs.d.ts +14 -0
  30. package/dist-lib/npm/types/components/TeamsGate.d.ts +4 -0
  31. package/dist-lib/npm/types/components/TextField.d.ts +9 -0
  32. package/dist-lib/npm/types/config/calendars.d.ts +1 -0
  33. package/dist-lib/npm/types/config/routes.d.ts +17 -0
  34. package/dist-lib/npm/types/context/HostContext.d.ts +9 -0
  35. package/dist-lib/npm/types/context/RootElementContext.d.ts +2 -0
  36. package/dist-lib/npm/types/data/index.d.ts +4 -0
  37. package/dist-lib/npm/types/data/localDataSource.d.ts +3 -0
  38. package/dist-lib/npm/types/data/restDataSource.d.ts +11 -0
  39. package/dist-lib/npm/types/data/tenantDataSource.d.ts +10 -0
  40. package/dist-lib/npm/types/data/types.d.ts +21 -0
  41. package/dist-lib/npm/types/features/authorization/components/AccountMenu.d.ts +6 -0
  42. package/dist-lib/npm/types/features/authorization/components/AuthFields.d.ts +26 -0
  43. package/dist-lib/npm/types/features/authorization/components/AuthGate.d.ts +7 -0
  44. package/dist-lib/npm/types/features/authorization/components/ContinueLink.d.ts +1 -0
  45. package/dist-lib/npm/types/features/authorization/components/EmailVerificationBanner.d.ts +1 -0
  46. package/dist-lib/npm/types/features/authorization/components/ForgotPasswordPage.d.ts +1 -0
  47. package/dist-lib/npm/types/features/authorization/components/LoginPage.d.ts +1 -0
  48. package/dist-lib/npm/types/features/authorization/components/RegisterPage.d.ts +1 -0
  49. package/dist-lib/npm/types/features/authorization/components/ResendVerificationButton.d.ts +4 -0
  50. package/dist-lib/npm/types/features/authorization/components/ResetPasswordPage.d.ts +1 -0
  51. package/dist-lib/npm/types/features/authorization/components/VerifyEmailPage.d.ts +1 -0
  52. package/dist-lib/npm/types/features/authorization/components/account/AccountSettings.d.ts +1 -0
  53. package/dist-lib/npm/types/features/authorization/components/account/DeleteAccountSection.d.ts +1 -0
  54. package/dist-lib/npm/types/features/authorization/components/account/EmailSection.d.ts +4 -0
  55. package/dist-lib/npm/types/features/authorization/components/account/PasswordSection.d.ts +1 -0
  56. package/dist-lib/npm/types/features/authorization/components/account/ProfileSection.d.ts +4 -0
  57. package/dist-lib/npm/types/features/authorization/context/AuthContext.d.ts +2 -0
  58. package/dist-lib/npm/types/features/authorization/context/AuthProvider.d.ts +8 -0
  59. package/dist-lib/npm/types/features/authorization/hooks/useAuth.d.ts +18 -0
  60. package/dist-lib/npm/types/features/authorization/index.d.ts +14 -0
  61. package/dist-lib/npm/types/features/authorization/repositories/HostTokenAuthRepository.d.ts +18 -0
  62. package/dist-lib/npm/types/features/authorization/repositories/RemoteAuthRepository.d.ts +18 -0
  63. package/dist-lib/npm/types/features/authorization/types/auth.d.ts +52 -0
  64. package/dist-lib/npm/types/features/authorization/utils/validation.d.ts +22 -0
  65. package/dist-lib/npm/types/features/calendar/components/Calendar.d.ts +14 -0
  66. package/dist-lib/npm/types/features/calendar/components/CalendarHeader.d.ts +16 -0
  67. package/dist-lib/npm/types/features/calendar/components/DayColumn.d.ts +18 -0
  68. package/dist-lib/npm/types/features/calendar/components/EventBlock.d.ts +10 -0
  69. package/dist-lib/npm/types/features/calendar/components/EventChip.d.ts +8 -0
  70. package/dist-lib/npm/types/features/calendar/components/EventTitle.d.ts +8 -0
  71. package/dist-lib/npm/types/features/calendar/components/MiniMonth.d.ts +9 -0
  72. package/dist-lib/npm/types/features/calendar/components/MonthGrid.d.ts +8 -0
  73. package/dist-lib/npm/types/features/calendar/components/MonthView.d.ts +2 -0
  74. package/dist-lib/npm/types/features/calendar/components/NowIndicator.d.ts +6 -0
  75. package/dist-lib/npm/types/features/calendar/components/TimeColumn.d.ts +1 -0
  76. package/dist-lib/npm/types/features/calendar/components/TimeGridView.d.ts +2 -0
  77. package/dist-lib/npm/types/features/calendar/components/YearView.d.ts +2 -0
  78. package/dist-lib/npm/types/features/calendar/constants/grid.d.ts +4 -0
  79. package/dist-lib/npm/types/features/calendar/constants/views.d.ts +7 -0
  80. package/dist-lib/npm/types/features/calendar/context/EventSourcesContext.d.ts +3 -0
  81. package/dist-lib/npm/types/features/calendar/hooks/useCalendarView.d.ts +19 -0
  82. package/dist-lib/npm/types/features/calendar/hooks/useEventSource.d.ts +2 -0
  83. package/dist-lib/npm/types/features/calendar/hooks/useNow.d.ts +1 -0
  84. package/dist-lib/npm/types/features/calendar/hooks/useSlotSelection.d.ts +6 -0
  85. package/dist-lib/npm/types/features/calendar/index.d.ts +4 -0
  86. package/dist-lib/npm/types/features/calendar/types/editor.d.ts +5 -0
  87. package/dist-lib/npm/types/features/calendar/types/eventLayout.d.ts +14 -0
  88. package/dist-lib/npm/types/features/calendar/types/eventSource.d.ts +6 -0
  89. package/dist-lib/npm/types/features/calendar/types/view.d.ts +26 -0
  90. package/dist-lib/npm/types/features/calendar/utils/eventGeometry.d.ts +3 -0
  91. package/dist-lib/npm/types/features/calendar/utils/eventLabels.d.ts +15 -0
  92. package/dist-lib/npm/types/features/calendar/utils/layoutEvents.d.ts +3 -0
  93. package/dist-lib/npm/types/features/calendar/utils/segmentEvents.d.ts +5 -0
  94. package/dist-lib/npm/types/features/calendar/utils/slotSelection.d.ts +17 -0
  95. package/dist-lib/npm/types/features/calendars/components/ActiveCalendarIndicator.d.ts +1 -0
  96. package/dist-lib/npm/types/features/calendars/components/CalendarPreview.d.ts +4 -0
  97. package/dist-lib/npm/types/features/calendars/components/CalendarSettings.d.ts +1 -0
  98. package/dist-lib/npm/types/features/calendars/components/CalendarSwitcher.d.ts +1 -0
  99. package/dist-lib/npm/types/features/calendars/components/InvitationList.d.ts +1 -0
  100. package/dist-lib/npm/types/features/calendars/components/create/ColorStep.d.ts +7 -0
  101. package/dist-lib/npm/types/features/calendars/components/create/CreateCalendarPage.d.ts +1 -0
  102. package/dist-lib/npm/types/features/calendars/components/create/DetailsStep.d.ts +12 -0
  103. package/dist-lib/npm/types/features/calendars/components/create/MembersStep.d.ts +8 -0
  104. package/dist-lib/npm/types/features/calendars/components/create/ReviewStep.d.ts +4 -0
  105. package/dist-lib/npm/types/features/calendars/components/settings/CalendarSettingsPage.d.ts +1 -0
  106. package/dist-lib/npm/types/features/calendars/components/settings/DangerSection.d.ts +9 -0
  107. package/dist-lib/npm/types/features/calendars/components/settings/GeneralSection.d.ts +4 -0
  108. package/dist-lib/npm/types/features/calendars/components/settings/MembersSection.d.ts +11 -0
  109. package/dist-lib/npm/types/features/calendars/components/settings/TeamInvitationsSection.d.ts +12 -0
  110. package/dist-lib/npm/types/features/calendars/components/settings/TransferOwnershipModal.d.ts +8 -0
  111. package/dist-lib/npm/types/features/calendars/constants/calendars.d.ts +9 -0
  112. package/dist-lib/npm/types/features/calendars/context/CalendarsContext.d.ts +2 -0
  113. package/dist-lib/npm/types/features/calendars/context/CalendarsProvider.d.ts +8 -0
  114. package/dist-lib/npm/types/features/calendars/hooks/useCalendars.d.ts +1 -0
  115. package/dist-lib/npm/types/features/calendars/hooks/useTeam.d.ts +12 -0
  116. package/dist-lib/npm/types/features/calendars/index.d.ts +11 -0
  117. package/dist-lib/npm/types/features/calendars/repositories/LocalCalendarRepository.d.ts +20 -0
  118. package/dist-lib/npm/types/features/calendars/repositories/RemoteCalendarRepository.d.ts +23 -0
  119. package/dist-lib/npm/types/features/calendars/types/calendar.d.ts +91 -0
  120. package/dist-lib/npm/types/features/calendars/utils/draft.d.ts +7 -0
  121. package/dist-lib/npm/types/features/calendars/utils/permissions.d.ts +13 -0
  122. package/dist-lib/npm/types/features/events/components/ColorPicker.d.ts +7 -0
  123. package/dist-lib/npm/types/features/events/components/CustomColorSettings.d.ts +1 -0
  124. package/dist-lib/npm/types/features/events/components/DeleteEventModal.d.ts +8 -0
  125. package/dist-lib/npm/types/features/events/components/EventModal.d.ts +11 -0
  126. package/dist-lib/npm/types/features/events/components/RecurrenceFields.d.ts +9 -0
  127. package/dist-lib/npm/types/features/events/components/RecurrenceScopeModal.d.ts +8 -0
  128. package/dist-lib/npm/types/features/events/components/ScopeButtons.d.ts +10 -0
  129. package/dist-lib/npm/types/features/events/constants/colors.d.ts +3 -0
  130. package/dist-lib/npm/types/features/events/hooks/useCustomColors.d.ts +8 -0
  131. package/dist-lib/npm/types/features/events/hooks/useEvents.d.ts +15 -0
  132. package/dist-lib/npm/types/features/events/index.d.ts +5 -0
  133. package/dist-lib/npm/types/features/events/types/eventModal.d.ts +1 -0
  134. package/dist-lib/npm/types/features/events/utils/scopeOptions.d.ts +3 -0
  135. package/dist-lib/npm/types/features/events/utils/seriesActions.d.ts +4 -0
  136. package/dist-lib/npm/types/features/preferences/components/PreferencesSettings.d.ts +1 -0
  137. package/dist-lib/npm/types/features/preferences/context/PreferencesContext.d.ts +6 -0
  138. package/dist-lib/npm/types/features/preferences/context/PreferencesProvider.d.ts +4 -0
  139. package/dist-lib/npm/types/features/preferences/hooks/usePreferences.d.ts +1 -0
  140. package/dist-lib/npm/types/features/preferences/index.d.ts +3 -0
  141. package/dist-lib/npm/types/features/storage/components/LocalImportPrompt.d.ts +5 -0
  142. package/dist-lib/npm/types/features/storage/context/StorageContext.d.ts +2 -0
  143. package/dist-lib/npm/types/features/storage/context/StorageProvider.d.ts +8 -0
  144. package/dist-lib/npm/types/features/storage/hooks/useStorage.d.ts +7 -0
  145. package/dist-lib/npm/types/features/storage/index.d.ts +10 -0
  146. package/dist-lib/npm/types/features/storage/repositories/LocalColorRepository.d.ts +9 -0
  147. package/dist-lib/npm/types/features/storage/repositories/LocalEventRepository.d.ts +13 -0
  148. package/dist-lib/npm/types/features/storage/repositories/LocalPreferencesRepository.d.ts +8 -0
  149. package/dist-lib/npm/types/features/storage/repositories/RemoteColorRepository.d.ts +10 -0
  150. package/dist-lib/npm/types/features/storage/repositories/RemoteEventRepository.d.ts +12 -0
  151. package/dist-lib/npm/types/features/storage/repositories/RemotePreferencesRepository.d.ts +9 -0
  152. package/dist-lib/npm/types/features/storage/types/storage.d.ts +35 -0
  153. package/dist-lib/npm/types/features/storage/utils/copyEvents.d.ts +3 -0
  154. package/dist-lib/npm/types/features/storage/utils/localStorageList.d.ts +5 -0
  155. package/dist-lib/npm/types/features/storage/utils/localStorageValue.d.ts +9 -0
  156. package/dist-lib/npm/types/hooks/useArrowKeyNavigation.d.ts +6 -0
  157. package/dist-lib/npm/types/hooks/useAsyncAction.d.ts +6 -0
  158. package/dist-lib/npm/types/hooks/useAsyncResource.d.ts +9 -0
  159. package/dist-lib/npm/types/hooks/useForm.d.ts +21 -0
  160. package/dist-lib/npm/types/hooks/useFormState.d.ts +8 -0
  161. package/dist-lib/npm/types/hooks/useRequiredContext.d.ts +2 -0
  162. package/dist-lib/npm/types/hooks/useTabParam.d.ts +3 -0
  163. package/dist-lib/npm/types/i18n/I18nContext.d.ts +15 -0
  164. package/dist-lib/npm/types/i18n/I18nProvider.d.ts +7 -0
  165. package/dist-lib/npm/types/i18n/errorMessage.d.ts +2 -0
  166. package/dist-lib/npm/types/i18n/format.d.ts +28 -0
  167. package/dist-lib/npm/types/i18n/index.d.ts +8 -0
  168. package/dist-lib/npm/types/i18n/locale.d.ts +14 -0
  169. package/dist-lib/npm/types/i18n/messages/de/auth.d.ts +2 -0
  170. package/dist-lib/npm/types/i18n/messages/de/calendar.d.ts +3 -0
  171. package/dist-lib/npm/types/i18n/messages/de/calendars.d.ts +2 -0
  172. package/dist-lib/npm/types/i18n/messages/de/core.d.ts +7 -0
  173. package/dist-lib/npm/types/i18n/messages/de/events.d.ts +2 -0
  174. package/dist-lib/npm/types/i18n/messages/de/index.d.ts +2 -0
  175. package/dist-lib/npm/types/i18n/messages/de/settings.d.ts +2 -0
  176. package/dist-lib/npm/types/i18n/messages/de/storage.d.ts +2 -0
  177. package/dist-lib/npm/types/i18n/messages/en/auth.d.ts +97 -0
  178. package/dist-lib/npm/types/i18n/messages/en/calendar.d.ts +34 -0
  179. package/dist-lib/npm/types/i18n/messages/en/calendars.d.ts +177 -0
  180. package/dist-lib/npm/types/i18n/messages/en/core.d.ts +86 -0
  181. package/dist-lib/npm/types/i18n/messages/en/events.d.ts +42 -0
  182. package/dist-lib/npm/types/i18n/messages/en/index.d.ts +466 -0
  183. package/dist-lib/npm/types/i18n/messages/en/settings.d.ts +23 -0
  184. package/dist-lib/npm/types/i18n/messages/en/storage.d.ts +7 -0
  185. package/dist-lib/npm/types/i18n/messages/index.d.ts +4 -0
  186. package/dist-lib/npm/types/i18n/messages/types.d.ts +2 -0
  187. package/dist-lib/npm/types/i18n/useI18n.d.ts +3 -0
  188. package/dist-lib/npm/types/i18n/useLocaleGetter.d.ts +1 -0
  189. package/dist-lib/npm/types/i18n/weekInfo.d.ts +5 -0
  190. package/dist-lib/npm/types/lib/CalendarApp.d.ts +14 -0
  191. package/dist-lib/npm/types/lib/CalendarWidget.d.ts +2 -0
  192. package/dist-lib/npm/types/lib/IsolatedRoot.d.ts +9 -0
  193. package/dist-lib/npm/types/lib/config.d.ts +28 -0
  194. package/dist-lib/npm/types/lib/defaults.d.ts +13 -0
  195. package/dist-lib/npm/types/lib/element.d.ts +16 -0
  196. package/dist-lib/npm/types/lib/eventCallbacks.d.ts +11 -0
  197. package/dist-lib/npm/types/lib/index.d.ts +16 -0
  198. package/dist-lib/npm/types/lib/linkParam.d.ts +2 -0
  199. package/dist-lib/npm/types/lib/version.d.ts +1 -0
  200. package/dist-lib/npm/types/pages/CalendarPage.d.ts +1 -0
  201. package/dist-lib/npm/types/pages/SettingsPage.d.ts +1 -0
  202. package/dist-lib/npm/types/router.d.ts +7 -0
  203. package/dist-lib/npm/types/utils/api.d.ts +32 -0
  204. package/dist-lib/npm/types/utils/apiError.d.ts +26 -0
  205. package/dist-lib/npm/types/utils/appError.d.ts +10 -0
  206. package/dist-lib/npm/types/utils/calendarView.d.ts +3 -0
  207. package/dist-lib/npm/types/utils/classNames.d.ts +2 -0
  208. package/dist-lib/npm/types/utils/color.d.ts +5 -0
  209. package/dist-lib/npm/types/utils/date.d.ts +44 -0
  210. package/dist-lib/npm/types/utils/dom.d.ts +3 -0
  211. package/dist-lib/npm/types/utils/event.d.ts +74 -0
  212. package/dist-lib/npm/types/utils/number.d.ts +1 -0
  213. package/dist-lib/npm/types/utils/object.d.ts +3 -0
  214. package/dist-lib/npm/types/utils/preferences.d.ts +15 -0
  215. package/dist-lib/npm/types/utils/recurrence.d.ts +33 -0
  216. package/dist-lib/npm/types/utils/series.d.ts +9 -0
  217. package/dist-lib/npm/types/utils/validation.d.ts +6 -0
  218. package/package.json +82 -6
package/CHANGELOG.md ADDED
@@ -0,0 +1,16 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@rokoyfa/calendar`. Versions follow [Semantic Versioning](https://semver.org/). Until 1.0, minor versions may contain breaking changes.
4
+
5
+ ## 0.1.0 – 2026-11-10
6
+
7
+ First public release.
8
+
9
+ - `<Calendar />` React component and `<calendar-widget>` web component from one package, isolated in a Shadow DOM
10
+ - Day, week, month and year views, drag to select a time range, recurring events with "this / following / all" editing
11
+ - Data sources: `localDataSource`, `restDataSource`, `tenantDataSource` and custom adapters
12
+ - Accounts, team calendars with roles, invitations and ownership transfer when a backend is connected
13
+ - Sign-in through the host page with `getUserToken`
14
+ - English and German, region-aware week start, week numbers and time formats
15
+ - Host options `theme`, `initialView`, `features.teams`, `linkParam` and callbacks `onEventCreate`, `onEventUpdate`, `onEventDelete` (DOM events on the web component)
16
+ - REST contract as OpenAPI 3.1 in `api/openapi.yaml`
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Rokoyfa
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,194 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # @rokoyfa/calendar
2
+
3
+ An embeddable calendar for React apps and any other website.
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
12
+
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)
23
+
24
+ ```html
25
+ <script type="module" src="https://cdn.jsdelivr.net/npm/@rokoyfa/calendar@0.1/dist-lib/cdn/calendar-widget.js"></script>
26
+
27
+ <calendar-widget style="height: 700px"></calendar-widget>
28
+ ```
29
+
30
+ That's it. Without further attributes the calendar stores everything in the visitor's browser (localStorage).
31
+
32
+ ### React
33
+
34
+ ```bash
35
+ npm install @rokoyfa/calendar
36
+ ```
37
+
38
+ ```tsx
39
+ import { Calendar } from '@rokoyfa/calendar'
40
+
41
+ export function Page() {
42
+ return <Calendar style={{ height: 700 }} />
43
+ }
44
+ ```
45
+
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.
49
+
50
+ ## Options
51
+
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
+ ```
81
+
82
+ ```js
83
+ document.querySelector('calendar-widget').addEventListener('event-create', (e) => console.log(e.detail))
84
+ ```
85
+
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
+ ```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
+ }
112
+ ```
113
+
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
+ ```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>
145
+ ```
146
+
147
+ If your site already has its own users, let the widget sign them in with a short-lived token signed by your server:
148
+
149
+ ```js
150
+ document.querySelector('calendar-widget').getUserToken = async () => (await fetch('/calendar-token')).text()
151
+ ```
152
+
153
+ ```tsx
154
+ <Calendar tenant="acme" apiBaseUrl="https://api.example.com" getUserToken={() => fetch('/calendar-token').then((r) => r.text())} />
155
+ ```
156
+
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.
158
+
159
+ ## Languages and regions
160
+
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`.
162
+
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`).
164
+
165
+ ## Isolation and sizing
166
+
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.
171
+
172
+ ## Version
173
+
174
+ ```ts
175
+ import { VERSION } from '@rokoyfa/calendar'
176
+ ```
177
+
178
+ ```js
179
+ customElements.get('calendar-widget').version
180
+ ```
181
+
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).
183
+
184
+ ## Browser support
185
+
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).
191
+
192
+ ## License
193
+
194
+ [MIT](LICENSE) © Rokoyfa