@super-calendar/solid 2.17.0 → 2.19.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
@@ -4,16 +4,25 @@ Calendar views and date pickers for Solid 2. The renderer uses Solid signals and
4
4
  the React-free `@super-calendar/core/vanilla` entry. It does not require React,
5
5
  React DOM, React Native, or Legend List.
6
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.
7
+ This package targets Solid 2: `solid-js@^2.0.0` and `@solidjs/web@^2.0.0`.
8
+ Solid 1 is not supported.
9
9
  Its version follows the other calendar packages, and releases use the `latest`
10
10
  npm tag.
11
11
 
12
+ ## All-day spans
13
+
14
+ In the time grid, an all-day event renders once as a bar across the visible
15
+ dates it covers. Overlapping events stack on separate rows. The end is
16
+ exclusive, and hidden days take no width. `renderEvent` and press callbacks
17
+ receive the original event; `continuesBefore` and `continuesAfter` indicate
18
+ clipping at the visible range edges. The `allDayColumn` slot styles one
19
+ spanning cell. Timed events that cross midnight keep their per-day segments.
20
+
12
21
  ## Install
13
22
 
14
23
  ```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
24
+ pnpm add @super-calendar/solid solid-js@^2 @solidjs/web@^2 date-fns
25
+ pnpm add -D @solidjs/vite-plugin@^3 vite@^8
17
26
  ```
18
27
 
19
28
  Configure the Solid 2 Vite plugin:
@@ -93,11 +102,33 @@ to keep editing across full data refreshes. Return a stable, unique string or
93
102
  number per event or recurring occurrence. Missing, invalid, or duplicate IDs
94
103
  close the dialog. Without this prop, full refreshes close it. See
95
104
  [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
105
 
99
- In `TimeGrid`, the drag-to-create preview stays within the visible hours of the
100
- pressed column, with its border inside the column.
106
+ In time grids, `getEventId` also preserves all-day focus and renderer state when
107
+ a refresh replaces event objects. Bars without a valid, unique ID use object
108
+ identity and remount when that object changes.
109
+
110
+ Removing a resource cancels creation in its lane. `TimeGrid` completes creation
111
+ on pointer release even if capture is lost just before it. Capture loss without
112
+ a matching release and pointer cancellation cancel its creation sweep. A new
113
+ press discards a stale sweep left by a missed release outside the window.
114
+ Text selection and native browser dragging are disabled only while a mouse or
115
+ pen sweep is active.
116
+
117
+ In `TimeGrid`, the drag-to-create preview snaps to the same range as
118
+ `onCreateEvent`, starting with one slot on press. It stays within the visible
119
+ hours of the pressed column, with its border inside the column.
120
+ `dragStepMinutes` sets the snap interval.
121
+ Short previews use `minEventHeight`, like committed events. Clipping to the
122
+ visible hours takes priority at the column edges.
123
+
124
+ `MonthView`, `MultiWeekView`, and `Calendar` in month and multi-week modes also
125
+ accept `renderCreateGhost`. It receives the full all-day range with an exclusive
126
+ end, once per covered row. Use date labels for this content. The preview follows
127
+ `chipHeight` and `chipGap`, uses the `createGhost` slot, and requires
128
+ `onCreateEvent`. It is clipped, noninteractive, and hidden from assistive
129
+ technology. Empty months use the event-grid layout when both props are set.
130
+ Set `keyboardDayNavigation` to keep arrow-key day navigation in that layout,
131
+ including before the first event exists.
101
132
 
102
133
  Pass `renderCreateGhost` to `TimeGrid`, `Calendar`, or `ResourceTimeline` to draw
103
134
  a draft inside that preview. Read the props inside JSX so the text follows the
@@ -170,6 +201,9 @@ Counts must be positive safe integers whose date span is representable; invalid
170
201
  counts or dates throw `RangeError`. Rows are materialized, so larger counts need
171
202
  more space. `MonthView` retains its month-only behavior.
172
203
 
204
+ In month and multi-week grids, Escape or cancellation of the active pointer
205
+ ends a create or move gesture without committing. Release and cancellation events from other pointers do not end that gesture.
206
+
173
207
  In the multi-week web grid, a quick touch swipe scrolls. Hold a day or event for
174
208
  400 ms, then drag to create or move. Mouse input starts immediately. Cancelling
175
209
  the pointer or changing the displayed window cancels the hold or drag.
@@ -275,7 +309,10 @@ timers or access the DOM.
275
309
  The [Solid guide](https://super-calendar.afonsojramos.me/guides/solid) includes
276
310
  complete examples for controlled date pickers, resource bookings, and custom
277
311
  events. `Calendar` uses `renderTimeEvent`, `renderMonthEvent`, and
278
- `renderScheduleEvent`; direct views use `renderEvent`.
312
+ `renderScheduleEvent`; direct views use `renderEvent`. While a time-grid event
313
+ is moved or resized, its renderer receives a copy whose `start` and `end` are
314
+ the times the drop would report, so compare events by a stable ID. After a drag
315
+ pages the view, the floating preview keeps the stored times until release.
279
316
 
280
317
  If updates stop, read accessors in JSX and update event arrays with signal
281
318
  setters. Keep custom renderer props reactive by reading `props.event` in JSX.
@@ -95,6 +95,13 @@ interface AgendaProps<T = unknown> extends SlotStyleProps<AgendaSlot> {
95
95
  events: CalendarEvent$1<T>[];
96
96
  /** date-fns locale for the day headers and time labels. */
97
97
  locale?: Locale;
98
+ /**
99
+ * The instant whose calendar day is highlighted as today. Defaults to the
100
+ * device clock, and is read in `timeZone` when one is set.
101
+ */
102
+ now?: Date;
103
+ /** Highlight today as it is in this IANA time zone (default: the device's). */
104
+ timeZone?: string;
98
105
  /** Render times in 12-hour AM/PM (default false, 24h). */
99
106
  ampm?: boolean;
100
107
  /** Highlight this date's header instead of the real "today". */
@@ -136,7 +143,7 @@ export declare function Agenda<T = unknown>(incoming: AgendaProps<T>): JSX.Eleme
136
143
  * Styleable parts of {@link MonthView}. Pass a class or inline style per slot via
137
144
  * the `classNames` / `styles` props to restyle just that part.
138
145
  */
139
- type MonthViewSlot = "title" | "weekdays" | "weekday" | "grid" | "week" | "day" | "dayBadge" | "rangeBand" | "events" | "chipButton" | "chip" | "more" | "morePopover";
146
+ type MonthViewSlot = "title" | "weekdays" | "weekday" | "grid" | "week" | "day" | "dayBadge" | "rangeBand" | "events" | "createGhost" | "chipButton" | "chip" | "more" | "morePopover";
140
147
  /** Props passed to a custom month event chip renderer. */
141
148
  interface SolidMonthEventArgs<T = unknown> {
142
149
  /** The event to render. */
@@ -210,6 +217,13 @@ interface MonthViewProps<T = unknown> extends DateSelectionConstraints$1, SlotSt
210
217
  showWeekdays?: boolean;
211
218
  /** date-fns locale for the title and weekday labels. */
212
219
  locale?: Locale;
220
+ /**
221
+ * The instant whose calendar day is highlighted as today. Defaults to the
222
+ * device clock, and is read in `timeZone` when one is set.
223
+ */
224
+ now?: Date;
225
+ /** Highlight today as it is in this IANA time zone (default: the device's). */
226
+ timeZone?: string;
213
227
  /** Theme overrides; falls back to the default light theme. */
214
228
  theme?: Partial<SolidCalendarTheme>;
215
229
  /** Fired when a selectable day is clicked. */
@@ -227,6 +241,12 @@ interface MonthViewProps<T = unknown> extends DateSelectionConstraints$1, SlotSt
227
241
  * carry `data-creating` for styling.
228
242
  */
229
243
  onCreateEvent?: (start: Date, end: Date) => void;
244
+ /**
245
+ * Custom content for a drag-to-create preview, once per covered week row.
246
+ * Receives the full all-day range with an exclusive end. Requires onCreateEvent.
247
+ * Content is clipped, noninteractive, and hidden from assistive technology.
248
+ */
249
+ renderCreateGhost?: Component<CreateGhostArgs$1>;
230
250
  /**
231
251
  * Reports the day span of a create sweep **as it happens**, as the ordered
232
252
  * inclusive `[start, end]` days (both at midnight), so a selection highlight can
@@ -282,7 +302,12 @@ type EventActionsSlot = "eventActionsTrigger" | "eventActionsList" | "eventActio
282
302
  type TimeGridSlot = "header" | "weekNumber" | "columnHeader" | "columnHeaderWeekday" | "columnHeaderDate" | "allDayLane" | "allDayLabel" | "allDayColumn" | "allDayEvent" | "hourGutter" | "hourLabel" | "dayColumn" | "gridLines" | "businessHours" | "backgroundEvent" | "event" | "eventBox" | "nowIndicator" | "createGhost" | EventActionsSlot;
283
303
  /** Props passed to a custom time-grid event renderer. */
284
304
  interface SolidRenderEventArgs<T = unknown> {
285
- /** The event to render. */
305
+ /**
306
+ * The event to render. While it is being moved or resized, a copy whose
307
+ * `start` and `end` are the times `onDragEvent` would report on release.
308
+ * After a drag pages the view, the floating preview keeps the stored times
309
+ * until release.
310
+ */
286
311
  event: CalendarEvent$1<T>;
287
312
  /** The current view mode. */
288
313
  mode: CalendarMode$1;
@@ -290,9 +315,9 @@ interface SolidRenderEventArgs<T = unknown> {
290
315
  isAllDay: boolean;
291
316
  /** Pixel height of the event box (timed events only). */
292
317
  boxHeight?: number;
293
- /** The event started before the visible day and continues into it. */
318
+ /** Starts before the visible day (timed) or visible date range (all-day). */
294
319
  continuesBefore?: boolean;
295
- /** The event continues past the visible day. */
320
+ /** Ends after the visible day (timed) or visible date range (all-day). */
296
321
  continuesAfter?: boolean;
297
322
  /** Show the time range in 12-hour AM/PM. */
298
323
  ampm?: boolean;
@@ -378,9 +403,15 @@ interface TimeGridProps<T = unknown> extends SlotStyleProps<TimeGridSlot> {
378
403
  renderBackgroundEvent?: SolidRenderEvent<T>;
379
404
  /** Show the current-time indicator on today's column (default true). */
380
405
  showNowIndicator?: boolean;
381
- /** Fixed "now" instant for the indicator (doesn't tick). Defaults to the device clock. */
406
+ /**
407
+ * Fixed "now" instant for the indicator (doesn't tick) and for the day
408
+ * highlighted as today. Defaults to the device clock.
409
+ */
382
410
  now?: Date;
383
- /** Shift the now indicator into this IANA zone (pair with `eventsInTimeZone`). */
411
+ /**
412
+ * Shift the now indicator and the day highlighted as today into this IANA zone
413
+ * (pair with `eventsInTimeZone`).
414
+ */
384
415
  timeZone?: string;
385
416
  /** Show the all-day lane above the grid (default true). */
386
417
  showAllDayEventCell?: boolean;
@@ -448,7 +479,7 @@ interface TimeGridProps<T = unknown> extends SlotStyleProps<TimeGridSlot> {
448
479
  * Return `false` to reject the drop (the event snaps back).
449
480
  */
450
481
  onDragEvent?: (event: CalendarEvent$1<T>, start: Date, end: Date) => void | boolean;
451
- /** Stable, unique event identity for the web editing dialog across data refreshes. */
482
+ /** Stable, unique identity for the editing dialog and all-day bars across data refreshes. */
452
483
  getEventId?: (event: CalendarEvent$1<T>) => string | number;
453
484
  /**
454
485
  * Page the grid to a new anchor date. Supplying it alongside `onDragEvent`
@@ -494,6 +525,13 @@ interface YearViewProps<T = unknown> extends DateSelectionConstraints$1, SlotSty
494
525
  /** Weekdays (0=Sunday…6=Saturday) hidden from the grid, e.g. `[0, 6]` for weekends off. */
495
526
  hiddenDays?: number[];
496
527
  locale?: Locale;
528
+ /**
529
+ * The instant whose calendar day is highlighted as today. Defaults to the
530
+ * device clock, and is read in `timeZone` when one is set.
531
+ */
532
+ now?: Date;
533
+ /** Highlight today as it is in this IANA time zone (default: the device's). */
534
+ timeZone?: string;
497
535
  /** Translations for the screen-reader words; omitted keys use English. */
498
536
  labels?: Partial<CalendarLabels$1>;
499
537
  /** Highlight this date instead of the real "today". */
@@ -575,9 +613,10 @@ interface CalendarProps<T = unknown> extends DateSelectionConstraints$1, SlotSty
575
613
  /** Weekdays (0=Sunday…6=Saturday) hidden from the grid, e.g. `[0, 6]` for weekends off. */
576
614
  hiddenDays?: number[];
577
615
  /**
578
- * Fixed "now" instant for the current-time indicator (doesn't tick), e.g. a
579
- * server-synced clock. Defaults to the device clock, shifted into `timeZone`
580
- * when one is set so the line matches the displayed events.
616
+ * Fixed "now" instant for the current-time indicator (doesn't tick) and for
617
+ * the day highlighted as today in every mode, e.g. a server-synced clock.
618
+ * Defaults to the device clock, shifted into `timeZone` when one is set so
619
+ * both match the displayed events.
581
620
  */
582
621
  now?: Date;
583
622
  /** Column count for `mode="custom"`. */
@@ -589,7 +628,9 @@ interface CalendarProps<T = unknown> extends DateSelectionConstraints$1, SlotSty
589
628
  /**
590
629
  * Display events in this IANA time zone (e.g. `"America/New_York"`), DST-correct
591
630
  * and independent of the device zone. Display-only: it shifts the wall-clock the
592
- * grid lays out from, it doesn't change your `Date`s. Uses `eventsInTimeZone`.
631
+ * grid lays out from, it doesn't change your `Date`s, and callbacks report your
632
+ * own events and real instants. All-day events stay on their days. Uses
633
+ * `eventsInTimeZone`.
593
634
  */
594
635
  timeZone?: string;
595
636
  /** Theme overrides; falls back to the default light theme. */
@@ -683,8 +724,9 @@ interface CalendarProps<T = unknown> extends DateSelectionConstraints$1, SlotSty
683
724
  */
684
725
  onCreateEvent?: (start: Date, end: Date) => void;
685
726
  /**
686
- * A component that draws content inside the time-grid drag-to-create preview;
687
- * see `TimeGrid`'s prop of the same name. Applies to the week/day grid only.
727
+ * A component that draws content inside a creation preview in time-grid, month
728
+ * and multi-week modes. Month rows receive the full all-day range with an
729
+ * exclusive end, once per covered row. Requires onCreateEvent.
688
730
  */
689
731
  renderCreateGhost?: Component<CreateGhostArgs$1>;
690
732
  /** Fires when an event drag begins. */
@@ -695,7 +737,7 @@ interface CalendarProps<T = unknown> extends DateSelectionConstraints$1, SlotSty
695
737
  * days dragged so the time of day and duration are kept.
696
738
  */
697
739
  onDragEvent?: (event: CalendarEvent$1<T>, start: Date, end: Date) => void | boolean;
698
- /** Stable, unique event identity for the web editing dialog across data refreshes. */
740
+ /** Stable, unique identity for the editing dialog and time-grid all-day bars across data refreshes. */
699
741
  getEventId?: (event: CalendarEvent$1<T>) => string | number;
700
742
  /** Tap a day's column header. */
701
743
  onPressDateHeader?: (day: Date) => void;