@super-calendar/solid 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +311 -2
- package/dist/client/index.d.ts +1119 -0
- package/dist/client/index.js +7051 -0
- package/dist/server/index.d.ts +1119 -0
- package/dist/server/index.js +8527 -0
- package/package.json +59 -3
- package/src/Agenda.tsx +296 -0
- package/src/Calendar.tsx +645 -0
- package/src/DateRangePicker.tsx +405 -0
- package/src/EventActions.tsx +497 -0
- package/src/MonthList.tsx +233 -0
- package/src/MonthView.tsx +1936 -0
- package/src/MultiWeekView.tsx +49 -0
- package/src/ResourceTimeline.tsx +1748 -0
- package/src/TimeGrid.tsx +2833 -0
- package/src/VirtualList.tsx +119 -0
- package/src/YearView.tsx +652 -0
- package/src/createEventSource.ts +76 -0
- package/src/index.ts +113 -0
- package/src/props.ts +24 -0
- package/src/slots.ts +91 -0
- package/src/state.ts +62 -0
- package/src/styles.ts +68 -0
- package/src/theme.ts +44 -0
- package/src/touch.ts +131 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Afonso Jorge Ramos
|
|
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,312 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @super-calendar/solid
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Calendar views and date pickers for Solid 2. The renderer uses Solid signals and
|
|
4
|
+
the React-free `@super-calendar/core/vanilla` entry. It does not require React,
|
|
5
|
+
React DOM, React Native, or Legend List.
|
|
6
|
+
|
|
7
|
+
This package targets `solid-js@2.0.0-rc.20` and
|
|
8
|
+
`@solidjs/web@2.0.0-rc.20`. Install both exact versions. Solid 1 is not supported.
|
|
9
|
+
Its version follows the other calendar packages, and releases use the `latest`
|
|
10
|
+
npm tag.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
pnpm add @super-calendar/solid solid-js@2.0.0-rc.20 @solidjs/web@2.0.0-rc.20 date-fns
|
|
16
|
+
pnpm add -D @solidjs/vite-plugin@3.0.0-next.55 vite@^8
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Configure the Solid 2 Vite plugin:
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import { defineConfig } from "vite";
|
|
23
|
+
import solid from "@solidjs/vite-plugin";
|
|
24
|
+
|
|
25
|
+
export default defineConfig({ plugins: [solid({ ssr: true })] });
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
In `tsconfig.json`, set `jsx` to `preserve` and `jsxImportSource` to `@solidjs/web`.
|
|
29
|
+
Use `date-fns` 3 or 4. The package is ESM.
|
|
30
|
+
|
|
31
|
+
## Render a calendar
|
|
32
|
+
|
|
33
|
+
```tsx
|
|
34
|
+
import { createSignal } from "solid-js";
|
|
35
|
+
import { Calendar, type CalendarEvent } from "@super-calendar/solid";
|
|
36
|
+
|
|
37
|
+
export function Schedule() {
|
|
38
|
+
const [date, setDate] = createSignal(new Date(2026, 10, 2));
|
|
39
|
+
const [events, setEvents] = createSignal<CalendarEvent[]>([
|
|
40
|
+
{ title: "Planning", start: new Date(2026, 10, 2, 9), end: new Date(2026, 10, 2, 10) },
|
|
41
|
+
]);
|
|
42
|
+
|
|
43
|
+
return (
|
|
44
|
+
<Calendar
|
|
45
|
+
date={date()}
|
|
46
|
+
mode="week"
|
|
47
|
+
events={events()}
|
|
48
|
+
height={600}
|
|
49
|
+
onChangeDate={setDate}
|
|
50
|
+
onDragEvent={(event, start, end) => {
|
|
51
|
+
setEvents((current) =>
|
|
52
|
+
current.map((item) => (item === event ? { ...item, start, end } : item)),
|
|
53
|
+
);
|
|
54
|
+
}}
|
|
55
|
+
/>
|
|
56
|
+
);
|
|
57
|
+
}
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`Calendar` supports `month`, `multiweek`, `week`, `day`, `3days`, `custom`, `schedule`, and
|
|
61
|
+
`year`. It expands recurring events and applies `timeZone`. Direct views accept
|
|
62
|
+
already expanded events, matching the React DOM renderer.
|
|
63
|
+
|
|
64
|
+
The exported components are `Calendar`, `TimeGrid`, `MonthView`, `MultiWeekView`, `MonthList`,
|
|
65
|
+
`YearView`, `Agenda`, `ResourceTimeline`, `DatePicker`, and `DateRangePicker`.
|
|
66
|
+
`MonthList` and `Agenda` measure and virtualize their rows. `ResourceTimeline`
|
|
67
|
+
supports horizontal and vertical layouts.
|
|
68
|
+
|
|
69
|
+
`MonthList` applies callback, date-constraint, theme, and slot updates to mounted
|
|
70
|
+
months, including when `date` and `events` keep the same references.
|
|
71
|
+
|
|
72
|
+
The web renderers share prop names, pointer gestures, keyboard navigation, and
|
|
73
|
+
the `classNames`/`styles` slot contract. Solid render callbacks return
|
|
74
|
+
`JSX.Element` from `@solidjs/web`. Read callback props inside JSX so updates remain
|
|
75
|
+
reactive. `ref` on `Calendar` or `TimeGrid` receives a `CalendarHandle` with
|
|
76
|
+
`scrollToTime(minutes, options?)`.
|
|
77
|
+
|
|
78
|
+
Only the pointer that starts a drag can move, finish, or cancel it. An additional
|
|
79
|
+
contact cancels a touch hold that has not started dragging yet.
|
|
80
|
+
Cancellation discards pending moves and event creation. `onSelectDrag` reports
|
|
81
|
+
selection live, so it does not roll back selection updates on cancellation.
|
|
82
|
+
|
|
83
|
+
`ResourceTimeline` keeps the grabbed event when other events are inserted or
|
|
84
|
+
reordered. Removing or replacing that event cancels its drag. Locked events
|
|
85
|
+
(`draggable: false`) remain clickable and keyboard accessible in both orientations.
|
|
86
|
+
In `TimeGrid` and `ResourceTimeline`, choose **Edit events**, then an event,
|
|
87
|
+
to open move and resize actions, committed through `onDragEvent`
|
|
88
|
+
like a drop. Rejected edits show a polite status message, customizable with
|
|
89
|
+
`labels.eventChangeRejected`. Long choosers scroll without shrinking their
|
|
90
|
+
choices. Titles without spaces wrap. The centered dialog and chooser include
|
|
91
|
+
both dates for multi-day events. Pass `getEventId` to `Calendar`, `TimeGrid`, or `ResourceTimeline`
|
|
92
|
+
to keep editing across full data refreshes. Return a stable, unique string or
|
|
93
|
+
number per event or recurring occurrence. Missing, invalid, or duplicate IDs
|
|
94
|
+
close the dialog. Without this prop, full refreshes close it. See
|
|
95
|
+
[Move and resize actions](https://super-calendar.afonsojramos.me/guides/accessibility#move-and-resize-actions-web).
|
|
96
|
+
Removing a resource cancels creation in its lane. Losing pointer capture cancels
|
|
97
|
+
the active interaction.
|
|
98
|
+
|
|
99
|
+
In `TimeGrid`, the drag-to-create preview stays within the visible hours of the
|
|
100
|
+
pressed column, with its border inside the column.
|
|
101
|
+
|
|
102
|
+
Pass `renderCreateGhost` to `TimeGrid`, `Calendar`, or `ResourceTimeline` to draw
|
|
103
|
+
a draft inside that preview. Read the props inside JSX so the text follows the
|
|
104
|
+
sweep:
|
|
105
|
+
|
|
106
|
+
```tsx
|
|
107
|
+
import { createSignal } from "solid-js";
|
|
108
|
+
import { TimeGrid, type CalendarEvent, type CreateGhostArgs } from "@super-calendar/solid";
|
|
109
|
+
import { format } from "date-fns";
|
|
110
|
+
|
|
111
|
+
function DraftPreview(props: CreateGhostArgs) {
|
|
112
|
+
return (
|
|
113
|
+
<strong>{`New event ${format(props.start, "HH:mm")} - ${format(props.end, "HH:mm")}`}</strong>
|
|
114
|
+
);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
export function Planner() {
|
|
118
|
+
const [events, setEvents] = createSignal<CalendarEvent[]>([]);
|
|
119
|
+
return (
|
|
120
|
+
<TimeGrid
|
|
121
|
+
date={new Date(2026, 10, 2)}
|
|
122
|
+
mode="week"
|
|
123
|
+
events={events()}
|
|
124
|
+
onCreateEvent={(start, end) => setEvents((current) => [...current, { start, end }])}
|
|
125
|
+
renderCreateGhost={DraftPreview}
|
|
126
|
+
/>
|
|
127
|
+
);
|
|
128
|
+
}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
`start` and `end` are the range `onCreateEvent` would receive on release, which
|
|
132
|
+
can extend past a narrowed `minHour`/`maxHour` window. `ResourceTimeline` also
|
|
133
|
+
passes the lane's `resource`. The content is clipped to the preview,
|
|
134
|
+
non-interactive, and hidden from assistive tech.
|
|
135
|
+
The range follows scrolling and zooming during a held sweep, even without another pointer move.
|
|
136
|
+
|
|
137
|
+
## Multi-week grids
|
|
138
|
+
|
|
139
|
+
Use `mode="multiweek"` with `numberOfWeeks` (default `2`) for consecutive full
|
|
140
|
+
week rows without hourly slots. The first week contains `date` and aligns to
|
|
141
|
+
`weekStartsOn`. Navigation moves by the full number of weeks. `hiddenDays` only
|
|
142
|
+
shortens rows; `custom` views remain hourly even above seven columns.
|
|
143
|
+
|
|
144
|
+
```tsx
|
|
145
|
+
import { createSignal } from "solid-js";
|
|
146
|
+
import { Calendar } from "@super-calendar/solid";
|
|
147
|
+
|
|
148
|
+
export function MultiWeekCalendar() {
|
|
149
|
+
const [date, setDate] = createSignal(new Date(2026, 11, 28));
|
|
150
|
+
return (
|
|
151
|
+
<Calendar
|
|
152
|
+
mode="multiweek"
|
|
153
|
+
numberOfWeeks={3}
|
|
154
|
+
weekStartsOn={1}
|
|
155
|
+
date={date()}
|
|
156
|
+
onChangeDate={setDate}
|
|
157
|
+
events={[]}
|
|
158
|
+
height={480}
|
|
159
|
+
/>
|
|
160
|
+
);
|
|
161
|
+
}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
`MultiWeekView` exposes a standalone window with the month grid's event bars,
|
|
165
|
+
overflow, selection, drag interactions, and styling. Pass expanded events to it;
|
|
166
|
+
`Calendar` handles recurrence and time zones. Custom event renderers receive
|
|
167
|
+
`mode: "multiweek"`. Rows scroll vertically when the container is too short.
|
|
168
|
+
Event chips and overflow buttons default to 24 pixels high; use `chipHeight` to customize them.
|
|
169
|
+
Counts must be positive safe integers whose date span is representable; invalid
|
|
170
|
+
counts or dates throw `RangeError`. Rows are materialized, so larger counts need
|
|
171
|
+
more space. `MonthView` retains its month-only behavior.
|
|
172
|
+
|
|
173
|
+
In the multi-week web grid, a quick touch swipe scrolls. Hold a day or event for
|
|
174
|
+
400 ms, then drag to create or move. Mouse input starts immediately. Cancelling
|
|
175
|
+
the pointer or changing the displayed window cancels the hold or drag.
|
|
176
|
+
|
|
177
|
+
Keep `events` stable during unrelated UI updates. With recurrence or `timeZone`,
|
|
178
|
+
replacing the array rebuilds displayed events and cancels a held move. See
|
|
179
|
+
[keep event data stable](https://super-calendar.afonsojramos.me/guides/events#keep-event-data-stable).
|
|
180
|
+
|
|
181
|
+
## Select dates
|
|
182
|
+
|
|
183
|
+
```tsx
|
|
184
|
+
import { createSignal } from "solid-js";
|
|
185
|
+
import { MonthView, createDateRange } from "@super-calendar/solid";
|
|
186
|
+
|
|
187
|
+
export function Dates() {
|
|
188
|
+
const [month] = createSignal(new Date(2026, 10, 1));
|
|
189
|
+
const selection = createDateRange(() => ({ minDate: month() }));
|
|
190
|
+
return (
|
|
191
|
+
<MonthView
|
|
192
|
+
date={month()}
|
|
193
|
+
minDate={month()}
|
|
194
|
+
selectedRange={selection.range() ?? undefined}
|
|
195
|
+
onPressDay={selection.onPressDate}
|
|
196
|
+
onSelectDrag={selection.selectRange}
|
|
197
|
+
/>
|
|
198
|
+
);
|
|
199
|
+
}
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
`createDateRange(options?)` returns `range`, `setRange`, `onPressDate`,
|
|
203
|
+
`selectRange`, and `reset`. `range` is an accessor. Pass an options accessor for
|
|
204
|
+
reactive `minDate`, `maxDate`, or `isDateDisabled` constraints. `initialRange` is
|
|
205
|
+
read once.
|
|
206
|
+
|
|
207
|
+
`createMonthGrid(month, options?)` accepts accessors and returns an accessor for
|
|
208
|
+
the pure month-grid data. `createNow(options?)` returns a clock accessor and
|
|
209
|
+
cleans up its timer on disposal. Create these inside a Solid component or root.
|
|
210
|
+
|
|
211
|
+
`DatePicker` and `DateRangePicker` apply `theme` to both the popover chrome and
|
|
212
|
+
the calendar inside it. Theme updates apply while open, and per-slot styles take
|
|
213
|
+
precedence. Setting `disabled` closes an open popover; re-enabling the field
|
|
214
|
+
leaves it closed until you open it again. Opening a picker moves focus to the
|
|
215
|
+
selected day, and `Escape` returns it to the field.
|
|
216
|
+
|
|
217
|
+
## Load events
|
|
218
|
+
|
|
219
|
+
```tsx
|
|
220
|
+
import { Calendar, createEventSource } from "@super-calendar/solid";
|
|
221
|
+
|
|
222
|
+
export function Feed(props: { url: string; date: Date }) {
|
|
223
|
+
const feed = createEventSource(
|
|
224
|
+
() => props.url,
|
|
225
|
+
() => ({ refetchIntervalMs: 60_000 }),
|
|
226
|
+
);
|
|
227
|
+
return (
|
|
228
|
+
<>
|
|
229
|
+
<button disabled={feed.loading()} onClick={() => void feed.refetch()}>
|
|
230
|
+
Refresh
|
|
231
|
+
</button>
|
|
232
|
+
<p role="status">{feed.error()?.message}</p>
|
|
233
|
+
<Calendar date={props.date} events={feed.events()} />
|
|
234
|
+
</>
|
|
235
|
+
);
|
|
236
|
+
}
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
`createEventSource(source, options?)` takes accessors. The source is a JSON/ICS
|
|
240
|
+
URL or an async function returning events. Options are `format`, `map`, and
|
|
241
|
+
`refetchIntervalMs`. Finite intervals greater than zero and no larger than
|
|
242
|
+
`2147483647` ms enable polling; other values disable it.
|
|
243
|
+
JSON feeds require an array with valid `start`/`end` date strings.
|
|
244
|
+
Recurrence `until`, `exdates`, and `rdates` are revived too. A custom `map` owns
|
|
245
|
+
validation and conversion of its event fields.
|
|
246
|
+
|
|
247
|
+
Source and options changes reload the feed. Previous events stay available during
|
|
248
|
+
loading or errors. Disposal aborts pending URL requests and stops polling; stale
|
|
249
|
+
custom-function results are ignored, and retained `refetch` calls do nothing.
|
|
250
|
+
Server rendering does not fetch. Use `loadEventSource({ source, format?, map?, signal? })`
|
|
251
|
+
to load one batch yourself, including on a server.
|
|
252
|
+
|
|
253
|
+
## Style the views
|
|
254
|
+
|
|
255
|
+
Use `theme` with `defaultSolidTheme`, `darkSolidTheme`, or
|
|
256
|
+
`mergeSolidTheme(overrides)`. `className` and `style` target the root element.
|
|
257
|
+
`classNames` and `styles` target named slots. A slot class replaces its themed
|
|
258
|
+
styles while retaining structural layout. Inline slot overrides apply last.
|
|
259
|
+
Numeric CSS lengths use pixels; unitless properties and CSS variables stay
|
|
260
|
+
unitless. No stylesheet import is required.
|
|
261
|
+
|
|
262
|
+
## Server rendering
|
|
263
|
+
|
|
264
|
+
The `solid` export condition exposes JSX source for your app's Solid compiler.
|
|
265
|
+
The Vite plugin compiles that source for the client or server. Enable `ssr: true`
|
|
266
|
+
when hydrating server HTML. The package also includes precompiled hydratable
|
|
267
|
+
browser and server entries for tools that use the `browser` or default condition.
|
|
268
|
+
|
|
269
|
+
Use matching initial dates, events, locale, and time zone on both sides. Pass a
|
|
270
|
+
fixed `now` when the clock must match during hydration. The server does not start
|
|
271
|
+
timers or access the DOM.
|
|
272
|
+
|
|
273
|
+
## Integration examples and troubleshooting
|
|
274
|
+
|
|
275
|
+
The [Solid guide](https://super-calendar.afonsojramos.me/guides/solid) includes
|
|
276
|
+
complete examples for controlled date pickers, resource bookings, and custom
|
|
277
|
+
events. `Calendar` uses `renderTimeEvent`, `renderMonthEvent`, and
|
|
278
|
+
`renderScheduleEvent`; direct views use `renderEvent`.
|
|
279
|
+
|
|
280
|
+
If updates stop, read accessors in JSX and update event arrays with signal
|
|
281
|
+
setters. Keep custom renderer props reactive by reading `props.event` in JSX.
|
|
282
|
+
For compilation errors, check the exact peer versions and compiler setup above.
|
|
283
|
+
For hydration mismatches, use `hydrate` with matching initial data and include
|
|
284
|
+
`generateHydrationScript()` before the client entry. See
|
|
285
|
+
[troubleshooting](https://super-calendar.afonsojramos.me/guides/solid#troubleshoot-an-integration).
|
|
286
|
+
|
|
287
|
+
## Run the example
|
|
288
|
+
|
|
289
|
+
From the repository root:
|
|
290
|
+
|
|
291
|
+
```sh
|
|
292
|
+
pnpm build
|
|
293
|
+
pnpm --filter @super-calendar/example-solid dev
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
Open `/` for client rendering or `/ssr` for server rendering and hydration.
|
|
297
|
+
Use `?view=month`, `?view=months`, or another view name to start in that view.
|
|
298
|
+
`pnpm test:solid:browser` starts its own server and isolated headless Chrome to
|
|
299
|
+
check both routes, gestures, pickers, and virtual scrolling.
|
|
300
|
+
`pnpm test:solid:browser:dist` repeats those checks against the built client and
|
|
301
|
+
server entries, plus the built React DOM resource timeline.
|
|
302
|
+
The **feed** view loads a local JSON feed and supports manual refresh.
|
|
303
|
+
`pnpm test:parity` runs all five Vitest projects. Shared web behavior tests live in
|
|
304
|
+
[`tests/web/contracts`](../../tests/web/README.md) and execute against both React
|
|
305
|
+
DOM and Solid through framework adapters. CI requires both runs to pass with the
|
|
306
|
+
same cases. Framework-specific checks remain separate, including React commit
|
|
307
|
+
counts, Solid renderer lifetimes, and SSR.
|
|
308
|
+
|
|
309
|
+
After `pnpm build`, run `pnpm test:browser` for shared React DOM/Solid browser
|
|
310
|
+
contracts. Vitest runs each case against both source and built packages, using
|
|
311
|
+
Playwright to drive Chrome. These checks cover live props, disabled pickers,
|
|
312
|
+
virtual scrolling, pointer capture, touch scrolling, and drag cancellation.
|