@super-calendar/native 2.12.0 → 2.13.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.
@@ -18,12 +18,16 @@ import {
18
18
  import {
19
19
  createContext,
20
20
  type Dispatch,
21
+ type ForwardedRef,
22
+ forwardRef,
21
23
  memo,
22
24
  type ReactElement,
25
+ type RefAttributes,
23
26
  type SetStateAction,
24
27
  useCallback,
25
28
  useContext,
26
29
  useEffect,
30
+ useImperativeHandle,
27
31
  useMemo,
28
32
  useRef,
29
33
  useState,
@@ -34,6 +38,7 @@ import {
34
38
  type LayoutChangeEvent,
35
39
  type NativeScrollEvent,
36
40
  type NativeSyntheticEvent,
41
+ PixelRatio,
37
42
  Platform,
38
43
  Pressable,
39
44
  StyleSheet,
@@ -89,7 +94,11 @@ import {
89
94
  snapDeltaMinutes,
90
95
  } from "@super-calendar/core";
91
96
  import { formatHour, layoutDayEvents, type PositionedEvent } from "@super-calendar/core";
92
- import type { CalendarLabels, EventAccessibilityLabeler } from "@super-calendar/core";
97
+ import type {
98
+ CalendarHandle,
99
+ CalendarLabels,
100
+ EventAccessibilityLabeler,
101
+ } from "@super-calendar/core";
93
102
  import { resolveCalendarLabels } from "@super-calendar/core";
94
103
  import { type WeekdayFormat, weekdayFormatToken } from "@super-calendar/core";
95
104
  import {
@@ -127,6 +136,13 @@ const PAGE_WINDOW = 180;
127
136
  // A page must be ~fully on screen before it becomes the committed date.
128
137
  const PAGE_VIEWABILITY = { itemVisiblePercentThreshold: 90 };
129
138
 
139
+ // How long the Android pager must go without a scroll event before an off-page
140
+ // rest is snapped back onto a page.
141
+ const PAGER_IDLE_MS = 150;
142
+ // The same wait after a drag that never reported its end, which may still be
143
+ // held by a finger.
144
+ const PAGER_HELD_DRAG_MS = 1000;
145
+
130
146
  // Matches the dom renderer's default so both grids start at the same density.
131
147
  /** Default height in pixels of one hour row on the time grid. */
132
148
  export const DEFAULT_HOUR_HEIGHT = 48;
@@ -2338,73 +2354,76 @@ export type TimeGridProps<T> = SlotStyleProps<TimeGridSlot> & {
2338
2354
  renderHeader?: (days: Date[]) => React.ReactNode;
2339
2355
  };
2340
2356
 
2341
- function TimeGridInner<T>({
2342
- mode,
2343
- numberOfDays = 1,
2344
- weekEndsOn,
2345
- date,
2346
- events,
2347
- cellHeight,
2348
- hourHeight = DEFAULT_HOUR_HEIGHT,
2349
- weekStartsOn,
2350
- weekdayFormat = "short",
2351
- labels: labelsProp,
2352
- renderEvent,
2353
- eventAccessibilityLabel,
2354
- keyExtractor,
2355
- scrollOffsetMinutes = 0,
2356
- hourColumnWidth: hourColumnWidthProp = DEFAULT_HOUR_COLUMN_WIDTH,
2357
- hideHours = false,
2358
- timeslots = 1,
2359
- showAllDayEventCell = true,
2360
- showAllDayLabel = false,
2361
- refreshControl,
2362
- highlightWeekends = true,
2363
- calendarCellStyle,
2364
- businessHours,
2365
- renderBusinessHours,
2366
- renderBackgroundEvent,
2367
- showWeekNumber = false,
2368
- headerComponent,
2369
- minHour = 0,
2370
- maxHour = HOURS_PER_DAY,
2371
- ampm = false,
2372
- isRTL = false,
2373
- minHourHeight = DEFAULT_MIN_HOUR_HEIGHT,
2374
- maxHourHeight = DEFAULT_MAX_HOUR_HEIGHT,
2375
- minEventHeight = DEFAULT_MIN_EVENT_HEIGHT,
2376
- eventGap = DEFAULT_EVENT_GAP,
2377
- showNowIndicator = true,
2378
- locale,
2379
- freeSwipe = false,
2380
- swipeEnabled = true,
2381
- showVerticalScrollIndicator = true,
2382
- verticalScrollEnabled = true,
2383
- weekNumberPrefix = "W",
2384
- hiddenDays,
2385
- now,
2386
- timeZone,
2387
- hourComponent,
2388
- activeDate,
2389
- resetPageOnPressCell = false,
2390
- dragStepMinutes = DEFAULT_DRAG_STEP_MINUTES,
2391
- showDragHandle = true,
2392
- eventStartEditable = true,
2393
- eventDurationEditable = true,
2394
- eventOverlap = true,
2395
- onPressEvent,
2396
- onLongPressEvent,
2397
- onDragEvent: onDragEventProp,
2398
- onDragStart,
2399
- onPressCell,
2400
- onLongPressCell,
2401
- onCreateEvent,
2402
- onPressDateHeader,
2403
- onChangeDate,
2404
- renderHeader,
2405
- classNames,
2406
- styles: styleOverrides,
2407
- }: TimeGridProps<T>): ReactElement {
2357
+ function TimeGridInner<T>(
2358
+ {
2359
+ mode,
2360
+ numberOfDays = 1,
2361
+ weekEndsOn,
2362
+ date,
2363
+ events,
2364
+ cellHeight,
2365
+ hourHeight = DEFAULT_HOUR_HEIGHT,
2366
+ weekStartsOn,
2367
+ weekdayFormat = "short",
2368
+ labels: labelsProp,
2369
+ renderEvent,
2370
+ eventAccessibilityLabel,
2371
+ keyExtractor,
2372
+ scrollOffsetMinutes = 0,
2373
+ hourColumnWidth: hourColumnWidthProp = DEFAULT_HOUR_COLUMN_WIDTH,
2374
+ hideHours = false,
2375
+ timeslots = 1,
2376
+ showAllDayEventCell = true,
2377
+ showAllDayLabel = false,
2378
+ refreshControl,
2379
+ highlightWeekends = true,
2380
+ calendarCellStyle,
2381
+ businessHours,
2382
+ renderBusinessHours,
2383
+ renderBackgroundEvent,
2384
+ showWeekNumber = false,
2385
+ headerComponent,
2386
+ minHour = 0,
2387
+ maxHour = HOURS_PER_DAY,
2388
+ ampm = false,
2389
+ isRTL = false,
2390
+ minHourHeight = DEFAULT_MIN_HOUR_HEIGHT,
2391
+ maxHourHeight = DEFAULT_MAX_HOUR_HEIGHT,
2392
+ minEventHeight = DEFAULT_MIN_EVENT_HEIGHT,
2393
+ eventGap = DEFAULT_EVENT_GAP,
2394
+ showNowIndicator = true,
2395
+ locale,
2396
+ freeSwipe = false,
2397
+ swipeEnabled = true,
2398
+ showVerticalScrollIndicator = true,
2399
+ verticalScrollEnabled = true,
2400
+ weekNumberPrefix = "W",
2401
+ hiddenDays,
2402
+ now,
2403
+ timeZone,
2404
+ hourComponent,
2405
+ activeDate,
2406
+ resetPageOnPressCell = false,
2407
+ dragStepMinutes = DEFAULT_DRAG_STEP_MINUTES,
2408
+ showDragHandle = true,
2409
+ eventStartEditable = true,
2410
+ eventDurationEditable = true,
2411
+ eventOverlap = true,
2412
+ onPressEvent,
2413
+ onLongPressEvent,
2414
+ onDragEvent: onDragEventProp,
2415
+ onDragStart,
2416
+ onPressCell,
2417
+ onLongPressCell,
2418
+ onCreateEvent,
2419
+ onPressDateHeader,
2420
+ onChangeDate,
2421
+ renderHeader,
2422
+ classNames,
2423
+ styles: styleOverrides,
2424
+ }: TimeGridProps<T>,
2425
+ ref: ForwardedRef<CalendarHandle>,
2426
+ ): ReactElement {
2408
2427
  // Guard against an inverted/out-of-range window so the grid never collapses.
2409
2428
  const clampedMinHour = Math.max(0, Math.min(minHour, HOURS_PER_DAY - 1));
2410
2429
  const clampedMaxHour = Math.max(clampedMinHour + 1, Math.min(maxHour, HOURS_PER_DAY));
@@ -2487,6 +2506,9 @@ function TimeGridInner<T>({
2487
2506
  scrollY.value = event.contentOffset.y;
2488
2507
  },
2489
2508
  });
2509
+ // The scroll view's `contentOffset` holds the mount offset; a later
2510
+ // `scrollOffsetMinutes` is scrolled to by the effect further down.
2511
+ const [mountOffsetY] = useState(seedDefaultY);
2490
2512
  // react-native-web ignores `contentOffset`; apply the initial offset once the
2491
2513
  // viewport and the content have laid out instead.
2492
2514
  const webSeededRef = useRef(!isWeb);
@@ -2895,6 +2917,26 @@ function TimeGridInner<T>({
2895
2917
  return () => cancelAnimationFrame(frame);
2896
2918
  }, [seedWebScroll]);
2897
2919
 
2920
+ // Scroll so `minutes` sits at the top of the hours, at the live zoom.
2921
+ const scrollToMinutes = useCallback(
2922
+ (minutes: number, animated: boolean) => {
2923
+ webSeededRef.current = true;
2924
+ const y = Math.max(0, minutes / MINUTES_PER_HOUR - clampedMinHour) * cellHeight.value;
2925
+ scrollRef.current?.scrollTo({ y, animated });
2926
+ },
2927
+ [clampedMinHour, cellHeight, scrollRef],
2928
+ );
2929
+
2930
+ // Scroll to a changed `scrollOffsetMinutes` (or hour window). The mount offset
2931
+ // comes from `contentOffset` and the web seed above.
2932
+ const appliedOffsetRef = useRef({ minutes: scrollOffsetMinutes, minHour: clampedMinHour });
2933
+ useEffect(() => {
2934
+ const applied = appliedOffsetRef.current;
2935
+ if (applied.minutes === scrollOffsetMinutes && applied.minHour === clampedMinHour) return;
2936
+ appliedOffsetRef.current = { minutes: scrollOffsetMinutes, minHour: clampedMinHour };
2937
+ scrollToMinutes(scrollOffsetMinutes, false);
2938
+ }, [scrollOffsetMinutes, clampedMinHour, scrollToMinutes]);
2939
+
2898
2940
  // Web: LegendList's horizontal scroll container is `overflow-x: auto`, so a
2899
2941
  // trackpad swipe or horizontal wheel would scroll between pages. Paging should be
2900
2942
  // arrow-keys/toolbar only, so disable user horizontal scrolling on it (programmatic
@@ -2925,6 +2967,15 @@ function TimeGridInner<T>({
2925
2967
  // jumps when it's on.
2926
2968
  const reduceMotion = useReducedMotion();
2927
2969
 
2970
+ useImperativeHandle(
2971
+ ref,
2972
+ () => ({
2973
+ scrollToTime: (minutes, { animated = true } = {}) =>
2974
+ scrollToMinutes(minutes, animated && !reduceMotion),
2975
+ }),
2976
+ [scrollToMinutes, reduceMotion],
2977
+ );
2978
+
2928
2979
  // Page by `delta` (edge drags, web arrow keys): move the list at once and
2929
2980
  // report the date, rather than waiting for the reported date to come back
2930
2981
  // through props. The realign effect then finds the list already there.
@@ -2944,6 +2995,23 @@ function TimeGridInner<T>({
2944
2995
  );
2945
2996
  useWebPagerKeys(swipeEnabled, goToPage);
2946
2997
 
2998
+ // Commit the page nearest `offsetX` and return its index. Viewability only
2999
+ // reports a page that is nearly all on screen, so a pager that rests between
3000
+ // pages would otherwise move the grid without moving the date behind the header.
3001
+ const commitNearestPage = useCallback(
3002
+ (offsetX: number) => {
3003
+ const raw = Math.round(offsetX / columnsWidth);
3004
+ const index = Math.min(Math.max(raw, 0), pageDates.length - 1);
3005
+ if (index !== viewedIndexRef.current) {
3006
+ viewedIndexRef.current = index;
3007
+ const target = pageDates[index];
3008
+ if (target) onChangeDate(target);
3009
+ }
3010
+ return index;
3011
+ },
3012
+ [columnsWidth, pageDates, onChangeDate],
3013
+ );
3014
+
2947
3015
  // A fast fling can outrun the list's on-demand mounting and leave the pager
2948
3016
  // blank until something nudges it. When momentum ends, re-anchor the list on
2949
3017
  // the page the offset landed on: `scrollToIndex` forces it to recompute its
@@ -2957,24 +3025,72 @@ function TimeGridInner<T>({
2957
3025
  // (goToPage, realign) sets `pendingScrollIndexRef` and repaints itself, so
2958
3026
  // skip those to avoid a redundant re-anchor during held edge paging.
2959
3027
  if (pendingScrollIndexRef.current != null) return;
2960
- const raw = Math.round(event.nativeEvent.contentOffset.x / columnsWidth);
2961
- const index = Math.min(Math.max(raw, 0), pageDates.length - 1);
2962
- // Commit the page the pager snaps to. Viewability only reports a page that
2963
- // is nearly all on screen, so a fling that rests between pages would
2964
- // otherwise move the grid without moving the date behind the header.
2965
- if (index !== viewedIndexRef.current) {
2966
- viewedIndexRef.current = index;
2967
- const target = pageDates[index];
2968
- if (target) onChangeDate(target);
2969
- }
3028
+ const index = commitNearestPage(event.nativeEvent.contentOffset.x);
2970
3029
  // eslint-disable-next-line react-hooks/immutability -- Reanimated shared value: assigning .value is the intended mutation API
2971
3030
  pagerOffset.value = index * columnsWidth;
2972
3031
  requestAnimationFrame(() => {
2973
3032
  void listRef.current?.scrollToIndex({ index, animated: false });
2974
3033
  });
2975
3034
  },
2976
- [columnsWidth, pageDates, onChangeDate, pagerOffset],
3035
+ [columnsWidth, commitNearestPage, pagerOffset],
3036
+ );
3037
+
3038
+ // Android: once the pager has gone a moment without a scroll event, snap an
3039
+ // offset left between pages back onto the nearest page (or onto the target of
3040
+ // an interrupted programmatic scroll). A drag that began and has not reported
3041
+ // its end waits longer, in case a finger is still holding it.
3042
+ const pagerDraggingRef = useRef(false);
3043
+ const lastPagerScrollRef = useRef({ offsetX: 0, at: 0 });
3044
+ const pagerIdleTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
3045
+ useEffect(
3046
+ () => () => {
3047
+ if (pagerIdleTimerRef.current) clearTimeout(pagerIdleTimerRef.current);
3048
+ },
3049
+ [],
3050
+ );
3051
+ const realignRestingPager = useCallback(
3052
+ (offsetX: number) => {
3053
+ pagerDraggingRef.current = false;
3054
+ if (columnsWidth <= 0) return;
3055
+ const pages = offsetX / columnsWidth;
3056
+ const offPagePx = Math.abs(pages - Math.round(pages)) * columnsWidth * PixelRatio.get();
3057
+ if (offPagePx < 0.5) return;
3058
+ const index = pendingScrollIndexRef.current ?? commitNearestPage(offsetX);
3059
+ // eslint-disable-next-line react-hooks/immutability -- Reanimated shared value: assigning .value is the intended mutation API
3060
+ pagerOffset.value = index * columnsWidth;
3061
+ void listRef.current?.scrollToIndex({ index, animated: !reduceMotion });
3062
+ },
3063
+ [columnsWidth, commitNearestPage, pagerOffset, reduceMotion],
2977
3064
  );
3065
+ const realignRestingPagerRef = useRef(realignRestingPager);
3066
+ realignRestingPagerRef.current = realignRestingPager;
3067
+ // One timer per burst of scroll events: when it fires early it re-arms for
3068
+ // the rest of the wait measured from the latest event.
3069
+ const armPagerIdleTimer = useCallback((delay: number) => {
3070
+ pagerIdleTimerRef.current = setTimeout(() => {
3071
+ const wait = pagerDraggingRef.current ? PAGER_HELD_DRAG_MS : PAGER_IDLE_MS;
3072
+ const remaining = lastPagerScrollRef.current.at + wait - Date.now();
3073
+ if (remaining > 0) {
3074
+ armPagerIdleTimer(remaining);
3075
+ return;
3076
+ }
3077
+ pagerIdleTimerRef.current = null;
3078
+ realignRestingPagerRef.current(lastPagerScrollRef.current.offsetX);
3079
+ }, delay);
3080
+ }, []);
3081
+ const handlePagerScroll = useCallback(
3082
+ (event: NativeSyntheticEvent<NativeScrollEvent>) => {
3083
+ lastPagerScrollRef.current = { offsetX: event.nativeEvent.contentOffset.x, at: Date.now() };
3084
+ if (!pagerIdleTimerRef.current) armPagerIdleTimer(PAGER_IDLE_MS);
3085
+ },
3086
+ [armPagerIdleTimer],
3087
+ );
3088
+ const handlePagerDragStart = useCallback(() => {
3089
+ pagerDraggingRef.current = true;
3090
+ }, []);
3091
+ const handlePagerDragEnd = useCallback(() => {
3092
+ pagerDraggingRef.current = false;
3093
+ }, []);
2978
3094
 
2979
3095
  // Optionally snap the pager back to the active page after an empty-cell press
2980
3096
  // (so tapping a far-swiped page returns to the committed date).
@@ -3144,7 +3260,7 @@ function TimeGridInner<T>({
3144
3260
  onScroll={scrollHandler}
3145
3261
  scrollEventThrottle={16}
3146
3262
  refreshControl={verticalScrollEnabled ? refreshControl : undefined}
3147
- contentOffset={{ x: 0, y: seedDefaultY }}
3263
+ contentOffset={{ x: 0, y: mountOffsetY }}
3148
3264
  >
3149
3265
  <Animated.View testID="time-grid-hours" style={[styles.gridRow, gridHeightStyle]}>
3150
3266
  {hourColumnWidth > 0 ? (
@@ -3226,6 +3342,13 @@ function TimeGridInner<T>({
3226
3342
  disableIntervalMomentum: !freeSwipe,
3227
3343
  scrollEventThrottle: 16,
3228
3344
  onMomentumScrollEnd: handlePagerSettled,
3345
+ ...(Platform.OS === "android"
3346
+ ? {
3347
+ onScroll: handlePagerScroll,
3348
+ onScrollBeginDrag: handlePagerDragStart,
3349
+ onScrollEndDrag: handlePagerDragEnd,
3350
+ }
3351
+ : null),
3229
3352
  })}
3230
3353
  initialScrollIndex={activeIndex}
3231
3354
  showsHorizontalScrollIndicator={false}
@@ -3278,7 +3401,9 @@ function TimeGridInner<T>({
3278
3401
  * />
3279
3402
  * ```
3280
3403
  */
3281
- export const TimeGrid = memo(TimeGridInner) as typeof TimeGridInner;
3404
+ export const TimeGrid = memo(forwardRef(TimeGridInner)) as <T>(
3405
+ props: TimeGridProps<T> & RefAttributes<CalendarHandle>,
3406
+ ) => ReactElement;
3282
3407
 
3283
3408
  type DayHeaderRowProps = {
3284
3409
  days: Date[];
package/src/index.tsx CHANGED
@@ -57,6 +57,7 @@ export type {
57
57
  BusinessHours,
58
58
  BusinessHoursBand,
59
59
  CalendarEvent,
60
+ CalendarHandle,
60
61
  CalendarMode,
61
62
  EventAccessibilityLabelContext,
62
63
  EventAccessibilityLabeler,
@@ -66,6 +67,7 @@ export type {
66
67
  RecurrenceRule,
67
68
  RenderEvent,
68
69
  RenderEventArgs,
70
+ ScrollToTimeOptions,
69
71
  TimeGridMode,
70
72
  WeekdayFormat,
71
73
  WeekStartsOn,
package/src/types.ts CHANGED
@@ -14,6 +14,7 @@ export type {
14
14
  BusinessHours,
15
15
  BusinessHoursBand,
16
16
  CalendarEvent,
17
+ CalendarHandle,
17
18
  CalendarMode,
18
19
  EventAccessibilityLabelContext,
19
20
  EventAccessibilityLabeler,
@@ -21,6 +22,7 @@ export type {
21
22
  ICalendarEvent,
22
23
  RecurrenceFrequency,
23
24
  RecurrenceRule,
25
+ ScrollToTimeOptions,
24
26
  TimeGridMode,
25
27
  WeekdayFormat,
26
28
  WeekStartsOn,