@super-calendar/solid 0.0.0-stage → 2.16.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 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,268 @@
1
- # Temporary Holding Version
1
+ # @super-calendar/solid
2
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.
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`, `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`, `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
+ ## Select dates
138
+
139
+ ```tsx
140
+ import { createSignal } from "solid-js";
141
+ import { MonthView, createDateRange } from "@super-calendar/solid";
142
+
143
+ export function Dates() {
144
+ const [month] = createSignal(new Date(2026, 10, 1));
145
+ const selection = createDateRange(() => ({ minDate: month() }));
146
+ return (
147
+ <MonthView
148
+ date={month()}
149
+ minDate={month()}
150
+ selectedRange={selection.range() ?? undefined}
151
+ onPressDay={selection.onPressDate}
152
+ onSelectDrag={selection.selectRange}
153
+ />
154
+ );
155
+ }
156
+ ```
157
+
158
+ `createDateRange(options?)` returns `range`, `setRange`, `onPressDate`,
159
+ `selectRange`, and `reset`. `range` is an accessor. Pass an options accessor for
160
+ reactive `minDate`, `maxDate`, or `isDateDisabled` constraints. `initialRange` is
161
+ read once.
162
+
163
+ `createMonthGrid(month, options?)` accepts accessors and returns an accessor for
164
+ the pure month-grid data. `createNow(options?)` returns a clock accessor and
165
+ cleans up its timer on disposal. Create these inside a Solid component or root.
166
+
167
+ `DatePicker` and `DateRangePicker` apply `theme` to both the popover chrome and
168
+ the calendar inside it. Theme updates apply while open, and per-slot styles take
169
+ precedence. Setting `disabled` closes an open popover; re-enabling the field
170
+ leaves it closed until you open it again. Opening a picker moves focus to the
171
+ selected day, and `Escape` returns it to the field.
172
+
173
+ ## Load events
174
+
175
+ ```tsx
176
+ import { Calendar, createEventSource } from "@super-calendar/solid";
177
+
178
+ export function Feed(props: { url: string; date: Date }) {
179
+ const feed = createEventSource(
180
+ () => props.url,
181
+ () => ({ refetchIntervalMs: 60_000 }),
182
+ );
183
+ return (
184
+ <>
185
+ <button disabled={feed.loading()} onClick={() => void feed.refetch()}>
186
+ Refresh
187
+ </button>
188
+ <p role="status">{feed.error()?.message}</p>
189
+ <Calendar date={props.date} events={feed.events()} />
190
+ </>
191
+ );
192
+ }
193
+ ```
194
+
195
+ `createEventSource(source, options?)` takes accessors. The source is a JSON/ICS
196
+ URL or an async function returning events. Options are `format`, `map`, and
197
+ `refetchIntervalMs`. Finite intervals greater than zero and no larger than
198
+ `2147483647` ms enable polling; other values disable it.
199
+ JSON feeds require an array with valid `start`/`end` date strings.
200
+ Recurrence `until`, `exdates`, and `rdates` are revived too. A custom `map` owns
201
+ validation and conversion of its event fields.
202
+
203
+ Source and options changes reload the feed. Previous events stay available during
204
+ loading or errors. Disposal aborts pending URL requests and stops polling; stale
205
+ custom-function results are ignored, and retained `refetch` calls do nothing.
206
+ Server rendering does not fetch. Use `loadEventSource({ source, format?, map?, signal? })`
207
+ to load one batch yourself, including on a server.
208
+
209
+ ## Style the views
210
+
211
+ Use `theme` with `defaultSolidTheme`, `darkSolidTheme`, or
212
+ `mergeSolidTheme(overrides)`. `className` and `style` target the root element.
213
+ `classNames` and `styles` target named slots. A slot class replaces its themed
214
+ styles while retaining structural layout. Inline slot overrides apply last.
215
+ Numeric CSS lengths use pixels; unitless properties and CSS variables stay
216
+ unitless. No stylesheet import is required.
217
+
218
+ ## Server rendering
219
+
220
+ The `solid` export condition exposes JSX source for your app's Solid compiler.
221
+ The Vite plugin compiles that source for the client or server. Enable `ssr: true`
222
+ when hydrating server HTML. The package also includes precompiled hydratable
223
+ browser and server entries for tools that use the `browser` or default condition.
224
+
225
+ Use matching initial dates, events, locale, and time zone on both sides. Pass a
226
+ fixed `now` when the clock must match during hydration. The server does not start
227
+ timers or access the DOM.
228
+
229
+ ## Integration examples and troubleshooting
230
+
231
+ The [Solid guide](https://super-calendar.afonsojramos.me/guides/solid) includes
232
+ complete examples for controlled date pickers, resource bookings, and custom
233
+ events. `Calendar` uses `renderTimeEvent`, `renderMonthEvent`, and
234
+ `renderScheduleEvent`; direct views use `renderEvent`.
235
+
236
+ If updates stop, read accessors in JSX and update event arrays with signal
237
+ setters. Keep custom renderer props reactive by reading `props.event` in JSX.
238
+ For compilation errors, check the exact peer versions and compiler setup above.
239
+ For hydration mismatches, use `hydrate` with matching initial data and include
240
+ `generateHydrationScript()` before the client entry. See
241
+ [troubleshooting](https://super-calendar.afonsojramos.me/guides/solid#troubleshoot-an-integration).
242
+
243
+ ## Run the example
244
+
245
+ From the repository root:
246
+
247
+ ```sh
248
+ pnpm build
249
+ pnpm --filter @super-calendar/example-solid dev
250
+ ```
251
+
252
+ Open `/` for client rendering or `/ssr` for server rendering and hydration.
253
+ Use `?view=month`, `?view=months`, or another view name to start in that view.
254
+ `pnpm test:solid:browser` starts its own server and isolated headless Chrome to
255
+ check both routes, gestures, pickers, and virtual scrolling.
256
+ `pnpm test:solid:browser:dist` repeats those checks against the built client and
257
+ server entries, plus the built React DOM resource timeline.
258
+ The **feed** view loads a local JSON feed and supports manual refresh.
259
+ `pnpm test:parity` runs all five Vitest projects. Shared web behavior tests live in
260
+ [`tests/web/contracts`](../../tests/web/README.md) and execute against both React
261
+ DOM and Solid through framework adapters. CI requires both runs to pass with the
262
+ same cases. Framework-specific checks remain separate, including React commit
263
+ counts, Solid renderer lifetimes, and SSR.
264
+
265
+ After `pnpm build`, run `pnpm test:browser` for shared React DOM/Solid browser
266
+ contracts. Vitest runs each case against both source and built packages, using
267
+ Playwright to drive Chrome. These checks cover live props, disabled pickers,
268
+ virtual scrolling, pointer capture, touch scrolling, and drag cancellation.