react-native-agenda-kit 0.1.0

package/src/timeline/DayPager.tsx

@@ -0,0 +1,295 @@
+/**
+ * Day columns, paged horizontally across the SELECTABLE days (the range is padded to whole weeks;
+ * a swipe must not land on padding). Column `i` sits at `(i − minIndex) · width`; only the centre
+ * and its neighbours are mounted. Content stacking is the library's: bands → lines → events.
+ *
+ * The doctor's swipe commits at MOMENTUM END as `origin: 'timeline'`, which this pager ignores.
+ * Any other move animates to a mounted neighbour, or mounts the destination first (keeping the
+ * current columns), jumps once it exists, and releases the old columns on the first scroll there.
+ *
+ * `contentOffset` is read once: the native ScrollView re-applies it whenever its value changes, so
+ * a width-derived offset per render would throw the pager back to the day it opened on.
+ */
+
+import {
+  memo,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+} from 'react';
+import { StyleSheet, View } from 'react-native';
+import Animated, {
+  scrollTo,
+  useAnimatedReaction,
+  useAnimatedRef,
+  useAnimatedScrollHandler,
+  useSharedValue,
+} from 'react-native-reanimated';
+import { runOnJS, scheduleOnUI } from 'react-native-worklets';
+import { useCalendarContext } from '../core/CalendarContext';
+import { clampIndex, dayIndexOf, ymdAt } from '../core/dateKey';
+import type { AvailableHours, DateString, PackedTimelineEvent, TimelineEvent } from '../types';
+import { DayBands, DayEvents } from './DayColumn';
+import { ColumnLines } from './GridLines';
+import { NowKnob, useNowMinutesSV } from './NowIndicator';
+
+const offsetOfIndex = (idx: number, minIndex: number, width: number): number => {
+  'worklet';
+  return (idx - minIndex) * width;
+};
+
+const indexAtOffset = (x: number, minIndex: number, width: number): number => {
+  'worklet';
+  return minIndex + Math.round(x / width);
+};
+
+type Props<E extends TimelineEvent> = {
+  left: number;
+  width: number;
+  height: number;
+  events: Record<DateString, E[]>;
+  availableHoursFor: (ymd: DateString) => AvailableHours | undefined;
+  bandColor: string;
+  hourHeight: number;
+  overlapEventsSpacing: number;
+  rightEdgeSpacing: number;
+  renderEvent?: (event: PackedTimelineEvent<E>) => ReactElement | null;
+  onEventPress?: (event: PackedTimelineEvent<E>) => void;
+  showNowIndicator: boolean;
+};
+
+const DayPagerInner = <E extends TimelineEvent>({
+  left,
+  width,
+  height,
+  events,
+  availableHoursFor,
+  bandColor,
+  hourHeight,
+  overlapEventsSpacing,
+  rightEdgeSpacing,
+  renderEvent,
+  onEventPress,
+  showNowIndicator,
+}: Props<E>) => {
+  const { range, store, dateRef, commitDate } = useCalendarContext();
+  const listRef = useAnimatedRef<Animated.ScrollView>();
+
+  // Plain numbers for the worklets: a captured `range` would be frozen in dev.
+  const { minIndex, maxIndex, todayIndex } = range;
+  const pageCount = maxIndex - minIndex + 1;
+  const todayPage = todayIndex >= minIndex && todayIndex <= maxIndex ? todayIndex - minIndex : -1;
+  const showNow = showNowIndicator && todayPage >= 0;
+  const nowMinutes = useNowMinutesSV(showNow);
+
+  const [initialCenter] = useState(() => clampIndex(range, dayIndexOf(range, dateRef.current)));
+  const [initialOffset] = useState(() => ({ x: offsetOfIndex(initialCenter, minIndex, width), y: 0 }));
+  const [center, setCenter] = useState(initialCenter);
+  const [jumpFrom, setJumpFrom] = useState<number | null>(null);
+  const pendingX = useRef<number | null>(null);
+
+  const centerSV = useSharedValue(initialCenter);
+  const widthSV = useSharedValue(width);
+  const scrollX = useSharedValue(initialOffset.x);
+  const userDriven = useSharedValue(0);
+  const ready = useSharedValue(0);
+  const releaseAtX = useSharedValue(-1);
+
+  // Every column just moved: land back on the day that was showing.
+  useEffect(() => {
+    scheduleOnUI(() => {
+      'worklet';
+      if (widthSV.value === width) return;
+      widthSV.value = width;
+      const x = offsetOfIndex(centerSV.value, minIndex, width);
+      scrollX.value = x;
+      scrollTo(listRef, x, 0, false);
+    });
+  }, [centerSV, listRef, minIndex, scrollX, width, widthSV]);
+
+  /** The doctor's swipe settled on a new day. */
+  const onSwipeSettled = useCallback(
+    (idx: number) => {
+      setCenter(idx);
+      commitDate(idx, 'listDrag', 'timeline');
+    },
+    [commitDate],
+  );
+
+  const prepareJump = useCallback(
+    (idx: number, x: number) => {
+      pendingX.current = x;
+      setJumpFrom(centerSV.value);
+      setCenter(idx);
+    },
+    [centerSV],
+  );
+
+  const releaseJump = useCallback(() => setJumpFrom(null), []);
+
+  // The destination columns are committed: land on them.
+  useLayoutEffect(() => {
+    const x = pendingX.current;
+    if (x === null) return;
+    pendingX.current = null;
+    centerSV.value = center;
+    scheduleOnUI(() => {
+      'worklet';
+      releaseAtX.value = x;
+      userDriven.value = 0;
+      scrollX.value = x;
+      scrollTo(listRef, x, 0, false);
+    });
+  }, [center, centerSV, listRef, releaseAtX, scrollX, userDriven]);
+
+  useAnimatedReaction(
+    () => store.move.value,
+    (m, prev) => {
+      if (!prev || m.seq === prev.seq || m.origin === 'timeline') return;
+      if (ready.value === 0) return;
+      const idx = m.idx < minIndex ? minIndex : m.idx > maxIndex ? maxIndex : m.idx;
+      const x = offsetOfIndex(idx, minIndex, widthSV.value);
+      userDriven.value = 0;
+      if (Math.abs(idx - centerSV.value) <= 1) {
+        scrollTo(listRef, x, 0, m.animated);
+        if (idx !== centerSV.value) {
+          centerSV.value = idx;
+          runOnJS(setCenter)(idx);
+        }
+        return;
+      }
+      runOnJS(prepareJump)(idx, x);
+    },
+  );
+
+  const onScroll = useAnimatedScrollHandler({
+    onScroll: (e) => {
+      scrollX.value = e.contentOffset.x;
+      if (releaseAtX.value >= 0 && Math.abs(e.contentOffset.x - releaseAtX.value) < 1) {
+        releaseAtX.value = -1;
+        runOnJS(releaseJump)();
+      }
+    },
+    onBeginDrag: () => {
+      userDriven.value = 1;
+    },
+    onMomentumEnd: (e) => {
+      const idx = indexAtOffset(e.contentOffset.x, minIndex, widthSV.value);
+      const wasUser = userDriven.value === 1;
+      userDriven.value = 0;
+      if (!wasUser || idx === centerSV.value) return;
+      // This pager owns the position while the doctor swipes it, so it writes
+      // the UI-thread date itself; `commitDate` deliberately does not.
+      store.dayIndex.value = idx;
+      centerSV.value = idx;
+      runOnJS(onSwipeSettled)(idx);
+    },
+  });
+
+  const onLayout = useCallback(() => {
+    ready.value = 1;
+  }, [ready]);
+
+  const layers = useMemo(() => {
+    const bands: ReactElement[] = [];
+    const dayEvents: ReactElement[] = [];
+    const lo = jumpFrom === null || center <= jumpFrom ? center : jumpFrom;
+    const hi = jumpFrom === null || center >= jumpFrom ? center : jumpFrom;
+    let last = minIndex - 1;
+    // Two ascending 3-day windows; starting past `last` skips the days they share.
+    for (let pass = 0; pass < 2; pass += 1) {
+      const c = pass === 0 ? lo : hi;
+      for (let i = Math.max(c - 1, last + 1); i <= c + 1 && i <= maxIndex; i += 1) {
+        last = i;
+        const ymd = ymdAt(range, i);
+        const colLeft = offsetOfIndex(i, minIndex, width);
+        bands.push(
+          <DayBands
+            key={ymd}
+            left={colLeft}
+            width={width}
+            availableHours={availableHoursFor(ymd)}
+            color={bandColor}
+            hourHeight={hourHeight}
+          />,
+        );
+        dayEvents.push(
+          <DayEvents
+            key={ymd}
+            left={colLeft}
+            width={width}
+            events={events[ymd]}
+            hourHeight={hourHeight}
+            overlapEventsSpacing={overlapEventsSpacing}
+            rightEdgeSpacing={rightEdgeSpacing}
+            renderEvent={renderEvent}
+            onEventPress={onEventPress}
+            nowMinutes={showNow && i === todayIndex ? nowMinutes : undefined}
+          />,
+        );
+      }
+    }
+    return { bands, dayEvents };
+  }, [
+    availableHoursFor,
+    bandColor,
+    center,
+    events,
+    hourHeight,
+    jumpFrom,
+    maxIndex,
+    minIndex,
+    nowMinutes,
+    onEventPress,
+    overlapEventsSpacing,
+    range,
+    renderEvent,
+    rightEdgeSpacing,
+    showNow,
+    todayIndex,
+    width,
+  ]);
+
+  return (
+    <>
+      <Animated.ScrollView
+        ref={listRef}
+        horizontal
+        pagingEnabled
+        nestedScrollEnabled
+        showsHorizontalScrollIndicator={false}
+        onScroll={onScroll}
+        scrollEventThrottle={16}
+        contentOffset={initialOffset}
+        onLayout={onLayout}
+        style={[styles.pager, { left, width, height }]}
+      >
+        <View style={{ width: pageCount * width, height }}>
+          {layers.bands}
+          <ColumnLines hourHeight={hourHeight} />
+          {layers.dayEvents}
+        </View>
+      </Animated.ScrollView>
+      {showNow ? (
+        <NowKnob
+          left={left}
+          hourHeight={hourHeight}
+          minutes={nowMinutes}
+          page={todayPage}
+          pageWidth={widthSV}
+          scrollX={scrollX}
+        />
+      ) : null}
+    </>
+  );
+};
+
+export const DayPager = memo(DayPagerInner) as typeof DayPagerInner;
+
+const styles = StyleSheet.create({
+  pager: { position: 'absolute', top: 0 },
+});

package/src/timeline/EventBlock.tsx

@@ -0,0 +1,76 @@
+/**
+ * One packed event: the library's `EventBlock` container (absolute, `minHeight: 25`, padding 4/5,
+ * 0.9 opacity when pressed) around the caller's `renderEvent`. The fill is the event's own colour,
+ * else the soft accent token; the hairline ring gives a pastel block an edge on the dark palette
+ *.
+ */
+
+import { useKitStyles, type KitStyleArgs } from '../theme';
+import { FONT_SIZE, RADIUS } from '../theme/tokens';
+import { memo, useCallback, useMemo, type ReactElement } from 'react';
+import { Pressable, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { KitText } from '../core/KitText';
+import type { PackedTimelineEvent, TimelineEvent } from '../types';
+import { EVENT_MIN_HEIGHT } from './timelineGeometry';
+
+type Props<E extends TimelineEvent> = {
+  event: PackedTimelineEvent<E>;
+  renderEvent?: (event: PackedTimelineEvent<E>) => ReactElement | null;
+  onPress?: (event: PackedTimelineEvent<E>) => void;
+};
+
+const EventBlockInner = <E extends TimelineEvent>({ event, renderEvent, onPress }: Props<E>) => {
+  const styles = useKitStyles(makeStyles);
+  const handlePress = useCallback(() => onPress?.(event), [event, onPress]);
+
+  const { color, left, top, width, height } = event;
+  const blockStyle = useMemo(() => {
+    const rest: StyleProp<ViewStyle> = [
+      styles.block,
+      color ? { backgroundColor: color } : styles.blockDefault,
+      { left, top, width, height },
+    ];
+    const pressed: StyleProp<ViewStyle> = [rest, styles.pressed];
+    return { rest, pressed };
+  }, [color, height, left, styles, top, width]);
+
+  return (
+    <Pressable
+      onPress={handlePress}
+      style={({ pressed }) => (pressed ? blockStyle.pressed : blockStyle.rest)}
+    >
+      {renderEvent ? (
+        renderEvent(event)
+      ) : (
+        <KitText style={styles.title} numberOfLines={1}>
+          {event.title}
+        </KitText>
+      )}
+    </Pressable>
+  );
+};
+
+export const EventBlock = memo(EventBlockInner) as typeof EventBlockInner;
+
+const makeStyles = ({ colors, fonts }: KitStyleArgs) =>
+  StyleSheet.create({
+    block: {
+      position: 'absolute',
+      minHeight: EVENT_MIN_HEIGHT,
+      paddingLeft: 4,
+      paddingTop: 5,
+      flexDirection: 'column',
+      alignItems: 'flex-start',
+      overflow: 'hidden',
+      borderRadius: RADIUS.inner,
+      borderWidth: StyleSheet.hairlineWidth,
+      borderColor: colors.border,
+    },
+    blockDefault: { backgroundColor: colors.accentSoft },
+    pressed: { opacity: 0.9 },
+    title: {
+      fontFamily: fonts.semiBold,
+      fontSize: FONT_SIZE.xs,
+      color: colors.text,
+    },
+  });

package/src/timeline/GridLines.tsx

@@ -0,0 +1,36 @@
+/** The half-hour and hour lines: ONE layer across the pager's whole content, between bands and events. */
+
+import { useKitStyles, type KitStyleArgs } from '../theme';
+import { memo, useMemo, type ReactElement } from 'react';
+import { StyleSheet, View } from 'react-native';
+
+const ColumnLinesInner = ({ hourHeight }: { hourHeight: number }) => {
+  const styles = useKitStyles(makeStyles);
+  const lines = useMemo(() => {
+    const out: ReactElement[] = [];
+    for (let half = 1; half <= 48; half += 1) {
+      out.push(<View key={half} style={[styles.line, { top: (hourHeight * half) / 2 }]} />);
+    }
+    return out;
+  }, [hourHeight, styles.line]);
+
+  return (
+    <View pointerEvents="none" style={StyleSheet.absoluteFill}>
+      {lines}
+    </View>
+  );
+};
+
+export const ColumnLines = memo(ColumnLinesInner);
+ColumnLines.displayName = 'ColumnLines';
+
+const makeStyles = ({ colors }: KitStyleArgs) =>
+  StyleSheet.create({
+    line: {
+      position: 'absolute',
+      left: 0,
+      right: 0,
+      height: 1,
+      backgroundColor: colors.border,
+    },
+  });

package/src/timeline/HourGrid.tsx

@@ -0,0 +1,90 @@
+/**
+ * The time gutter: hour labels, the gutter's edge, and each line's 16 px stub into the gutter
+ * (`TimelineHours.js` starts lines at `timelineLeftInset − 16`). The stubs stay here because the
+ * pager starts at `GUTTER` and clips, so its shared line layer cannot reach into the gutter.
+ */
+
+import { useKitStyles, type KitStyleArgs } from '../theme';
+import { Fragment, memo, useMemo, type ReactElement } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { KitText } from '../core/KitText';
+import {
+  CONTENT_BOTTOM_PAD,
+  GUTTER,
+  LABEL_OFFSET_Y,
+  LABEL_PADDING_LEFT,
+  LINE_GUTTER_OVERHANG,
+  gridHeight,
+} from './timelineGeometry';
+
+/** `TimelineHours.js`: no label at 0, "23:59" at 24, no zero padding. */
+const hourLabel = (i: number, format24h: boolean): string => {
+  if (i < 12) return format24h ? `${i}:00` : `${i} AM`;
+  if (i === 12) return format24h ? `${i}:00` : `${i} PM`;
+  if (i === 24) return format24h ? '23:59' : '12 AM';
+  return format24h ? `${i}:00` : `${i - 12} PM`;
+};
+
+type Props = { hourHeight: number; format24h: boolean };
+
+const HourGridInner = ({ hourHeight, format24h }: Props) => {
+  const styles = useKitStyles(makeStyles);
+
+  const nodes = useMemo(() => {
+    const out: ReactElement[] = [];
+    for (let i = 0; i < 24; i += 1) {
+      const hourTop = hourHeight * (i + 1);
+      out.push(
+        <Fragment key={i}>
+          <View style={[styles.stub, { top: hourHeight * (i + 0.5) }]} />
+          <View style={[styles.stub, { top: hourTop }]} />
+          <KitText style={[styles.label, { top: hourTop + LABEL_OFFSET_Y }]}>
+            {hourLabel(i + 1, format24h)}
+          </KitText>
+        </Fragment>,
+      );
+    }
+    out.push(
+      <View key="edge" style={[styles.edge, { height: gridHeight(hourHeight) + CONTENT_BOTTOM_PAD }]} />,
+    );
+    return out;
+  }, [format24h, hourHeight, styles.edge, styles.label, styles.stub]);
+
+  return (
+    <View pointerEvents="none" style={StyleSheet.absoluteFill}>
+      {nodes}
+    </View>
+  );
+};
+
+export const HourGrid = memo(HourGridInner);
+HourGrid.displayName = 'HourGrid';
+
+const makeStyles = ({ colors, fonts }: KitStyleArgs) =>
+  StyleSheet.create({
+    label: {
+      position: 'absolute',
+      left: 0,
+      width: GUTTER - LINE_GUTTER_OVERHANG,
+      paddingLeft: LABEL_PADDING_LEFT,
+      textAlign: 'center',
+      fontFamily: fonts.medium,
+      fontSize: 10,
+      color: colors.textMuted,
+    },
+    stub: {
+      position: 'absolute',
+      left: GUTTER - LINE_GUTTER_OVERHANG,
+      width: LINE_GUTTER_OVERHANG,
+      height: 1,
+      backgroundColor: colors.border,
+    },
+    // The last gutter pixel (`TimelineHours.js`: `right: width`); at `GUTTER` the bands painted over it.
+    edge: {
+      position: 'absolute',
+      top: 0,
+      left: GUTTER - 1,
+      width: 1,
+      backgroundColor: colors.border,
+    },
+  });

package/src/timeline/NowIndicator.tsx

@@ -0,0 +1,123 @@
+/**
+ * The now-line. The minute lives in a SharedValue re-read just past each minute boundary (a bare
+ * 60 s interval started mid-minute runs late for the life of the screen) and on foreground; the
+ * line and knob move through animated styles, so a tick is zero React commits. No spring: a line
+ * that overshoots claims a time that is not now. The pager clips at the gutter, so `NowKnob` draws
+ * the whole dot above it at rest and hides mid-swipe — a worklet-driven knob trails by a frame.
+ */
+
+import { useKitStyles, type KitStyleArgs } from '../theme';
+import { RADIUS } from '../theme/tokens';
+import { memo, useEffect } from 'react';
+import { AppState, StyleSheet, View } from 'react-native';
+import Animated, {
+  useAnimatedStyle,
+  useSharedValue,
+  type SharedValue,
+} from 'react-native-reanimated';
+import { NOW_KNOB } from './timelineGeometry';
+
+const KNOB_HANG = Math.floor(NOW_KNOB / 2);
+const SHOWN = { opacity: 1 };
+const HIDDEN = { opacity: 0 };
+
+const minutesAt = (d: Date) => d.getHours() * 60 + d.getMinutes();
+
+/** Minutes since local midnight, shared by the line and the knob. Disabled means no timer. */
+export const useNowMinutesSV = (enabled: boolean): SharedValue<number> => {
+  const minutes = useSharedValue(minutesAt(new Date()));
+
+  useEffect(() => {
+    if (!enabled) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const tick = () => {
+      const now = new Date();
+      minutes.value = minutesAt(now);
+      // 50 ms past the boundary so the re-read lands in the new minute.
+      timer = setTimeout(tick, (60 - now.getSeconds()) * 1000 - now.getMilliseconds() + 50);
+    };
+    tick();
+    const sub = AppState.addEventListener('change', (state) => {
+      if (state !== 'active') return;
+      clearTimeout(timer);
+      tick();
+    });
+    return () => {
+      clearTimeout(timer);
+      sub.remove();
+    };
+  }, [enabled, minutes]);
+
+  return minutes;
+};
+
+type Props = { hourHeight: number; minutes: SharedValue<number> };
+
+const NowIndicatorInner = ({ hourHeight, minutes }: Props) => {
+  const styles = useKitStyles(makeStyles);
+  const position = useAnimatedStyle(() => ({ top: (minutes.value / 60) * hourHeight }));
+  return (
+    <Animated.View pointerEvents="none" style={[styles.root, position]}>
+      <View style={styles.line} />
+      <View style={styles.knob} />
+    </Animated.View>
+  );
+};
+
+export const NowIndicator = memo(NowIndicatorInner);
+NowIndicator.displayName = 'NowIndicator';
+
+type KnobProps = {
+  /** The pager's left edge in the timeline content — where today's column starts at rest. */
+  left: number;
+  hourHeight: number;
+  minutes: SharedValue<number>;
+  /** Today's page, and the live pager position it is compared against. */
+  page: number;
+  pageWidth: SharedValue<number>;
+  scrollX: SharedValue<number>;
+};
+
+const NowKnobInner = ({ left, hourHeight, minutes, page, pageWidth, scrollX }: KnobProps) => {
+  const styles = useKitStyles(makeStyles);
+  const position = useAnimatedStyle(() => ({
+    top: (minutes.value / 60) * hourHeight - KNOB_HANG,
+  }));
+  // Runs every scroll frame: return the constants by reference, never a fresh object.
+  const atRest = useAnimatedStyle(() => {
+    const dx = page * pageWidth.value - scrollX.value;
+    return dx > -1 && dx < 1 ? SHOWN : HIDDEN;
+  });
+  return (
+    <Animated.View
+      pointerEvents="none"
+      style={[styles.knob, { left: left - KNOB_HANG }, position, atRest]}
+    />
+  );
+};
+
+export const NowKnob = memo(NowKnobInner);
+NowKnob.displayName = 'NowKnob';
+
+const makeStyles = ({ colors }: KitStyleArgs) =>
+  StyleSheet.create({
+    root: { position: 'absolute', left: 0, right: 0, height: 0 },
+    // The now-line carries information (this minute), so a status colour may appear.
+    line: {
+      position: 'absolute',
+      left: 0,
+      right: 0,
+      top: 0,
+      height: 1,
+      backgroundColor: colors.nowIndicator,
+    },
+    knob: {
+      position: 'absolute',
+      left: -KNOB_HANG,
+      top: -KNOB_HANG,
+      width: NOW_KNOB,
+      height: NOW_KNOB,
+      borderRadius: RADIUS.full,
+      backgroundColor: colors.nowIndicator,
+    },
+  });