@super-calendar/core 2.15.0 → 2.17.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/README.md CHANGED
@@ -14,7 +14,19 @@ npm install @super-calendar/core
14
14
 
15
15
  Also on [JSR](https://jsr.io/@super-calendar/core): `deno add jsr:@super-calendar/core`.
16
16
 
17
- Peer dependencies: `date-fns` (>=3) and `react` (>=19).
17
+ Peer dependencies: `date-fns` (>=3) and optional `react` (>=18).
18
+ The root entry includes React hooks and requires React at runtime. Use
19
+ `@super-calendar/core/vanilla` for pure logic without React:
20
+
21
+ ```ts
22
+ import { buildMonthGrid, layoutDayEvents, nextDateRange } from "@super-calendar/core/vanilla";
23
+ ```
24
+
25
+ The vanilla entry exports the pure types, date calculations, selection, layout,
26
+ recurrence, time-zone, iCalendar, presentation, and theme-token utilities. It
27
+ also exports the framework-independent `loadEventSource` loader. It excludes
28
+ React hooks and providers. Existing root imports remain supported.
29
+ `@super-calendar/solid` uses this entry for its Solid 2 renderer.
18
30
 
19
31
  ## Usage
20
32
 
@@ -40,7 +52,7 @@ Manage single, multiple, or range selection with `useDateRange`:
40
52
  ```ts
41
53
  import { useDateRange } from "@super-calendar/core";
42
54
 
43
- const range = useDateRange({ mode: "range" });
55
+ const range = useDateRange({ minDate: new Date() });
44
56
  ```
45
57
 
46
58
  For a custom time-grid drag, `clampMoveStartMinutes` keeps the moved event's
@@ -67,6 +79,58 @@ saving changes. For a resize, pass zero for the edge you want to keep fixed.
67
79
  renderer's time-grid and resource-timeline resize grips. When omitted, those
68
80
  grips use `theme.colors.eventText`. Core preserves the field without interpreting it.
69
81
 
82
+ `CalendarLabels` supplies shared accessibility and editing text. The optional
83
+ `editEvents` and `eventActions(title)` fields name the web event chooser and its
84
+ move and resize dialog. `eventChangeRejected` supplies the web dialog's rejection
85
+ message (default "This change is not allowed."). `resolveCalendarLabels` fills omitted labels with English
86
+ defaults from `defaultCalendarLabels`.
87
+
88
+ ## Multi-week grids
89
+
90
+ `buildMultiWeekGrid` is available from both core entries. It builds consecutive
91
+ full weeks without month padding or hourly slots.
92
+
93
+ ```ts
94
+ import { buildMultiWeekGrid } from "@super-calendar/core/vanilla";
95
+
96
+ const grid = buildMultiWeekGrid(new Date(2026, 11, 28), {
97
+ numberOfWeeks: 3,
98
+ weekStartsOn: 1,
99
+ hiddenDays: [0, 6],
100
+ });
101
+ console.log(grid.weeks, grid.period, grid.visibleRange);
102
+ ```
103
+
104
+ `numberOfWeeks` defaults to `2` and must be a positive safe integer. Invalid
105
+ dates, invalid counts, and spans outside JavaScript's date range throw
106
+ `RangeError` before allocating rows. The builder materializes O(7 × N) days.
107
+ `period` covers full weeks; `visibleRange` gives the chronological visible
108
+ endpoints after hidden weekdays. Both use `{ start, endExclusive }`. RTL reverses
109
+ row display only. `MultiWeekGridDay` has the month builder's day state without
110
+ `isCurrentMonth`; `MultiWeekGridWeek.id` uses the unfiltered week start.
111
+ `getViewDays` and `viewDayCount` reject `multiweek`, so use this builder for it.
112
+
113
+ ## Recurrence limits
114
+
115
+ Recurring-event expansion stops at JavaScript's date limits and omits occurrences
116
+ whose end would overflow.
117
+
118
+ ## Event sources
119
+
120
+ `loadEventSource({ source, format?, map?, signal? })` loads one JSON or iCalendar
121
+ batch without React. Import it from `@super-calendar/core/vanilla` or the root
122
+ entry. `source` accepts a URL or an async function returning events. URL requests
123
+ accept an `AbortSignal`. The loader rejects HTTP errors and malformed JSON events;
124
+ the default mapper revives `start`, `end`, and recurrence dates. Custom mappers
125
+ receive an unknown array and own their validation and date conversion.
126
+
127
+ The React `useEventSource(source, options?)` hook adds `events`, `loading`,
128
+ `error`, and `refetch`. A failed refresh keeps the last successful batch.
129
+ `refetchIntervalMs` enables polling for finite values greater than zero and no
130
+ larger than `2147483647` ms. Other values disable it. Unmounting aborts
131
+ pending URL requests, stops polling, and disables retained `refetch` callbacks.
132
+ Solid consumers use `createEventSource` from `@super-calendar/solid`.
133
+
70
134
  ## Documentation
71
135
 
72
136
  See the [full documentation](https://super-calendar.afonsojramos.me) and the [API reference](https://super-calendar.afonsojramos.me/reference/api).