react-native-agenda-kit 0.1.0

package/src/timeline/TimelineDay.tsx

@@ -0,0 +1,112 @@
+/**
+ * The day view: ONE vertical ScrollView holding the time gutter and the day pager, so every day
+ * shares the vertical offset by construction. The start offset is a mount-time `contentOffset`;
+ * the caller mounts this conditionally, so every open recomputes it.
+ *
+ * The width is seeded from the window so the FIRST commit already holds the day columns (waiting
+ * for `onLayout` painted an empty grid first); `onLayout` corrects it when not full-width.
+ *
+ * `timelineProps.availableHours` replaces the library's inverted `unavailableHours` and also takes
+ * a per-date map, so a neighbouring day's bands are right mid-swipe.
+ */
+
+import { useKitTheme } from '../theme';
+import { useKitStyles, type KitStyleArgs } from '../theme';
+import { useCallback, useState } from 'react';
+import { Dimensions, ScrollView, StyleSheet, View, type LayoutChangeEvent } from 'react-native';
+import { useCalendarContext } from '../core/CalendarContext';
+import { dayIndexOf } from '../core/dateKey';
+import type { DateString, TimelineEvent, TimelineListProps } from '../types';
+import { DayPager } from './DayPager';
+import { HourGrid } from './HourGrid';
+import { CONTENT_BOTTOM_PAD, GUTTER, HOUR_HEIGHT, gridHeight } from './timelineGeometry';
+import { initialScrollY, minutesOf } from './timelineMath';
+
+export const TimelineList = <E extends TimelineEvent>({
+  events,
+  timelineProps = {},
+  showNowIndicator = false,
+  scrollToNow,
+  scrollToFirst,
+  initialTime,
+}: TimelineListProps<E>) => {
+  const { colors } = useKitTheme();
+  const styles = useKitStyles(makeStyles);
+  const {
+    renderEvent,
+    onEventPress,
+    format24h = true,
+    overlapEventsSpacing = 0,
+    rightEdgeSpacing = 0,
+    availableHours,
+    availableHoursColor = colors.accentSubtle,
+    hourHeight = HOUR_HEIGHT,
+  } = timelineProps;
+
+  const { range, dateRef } = useCalendarContext();
+  const [width, setWidth] = useState(() => Dimensions.get('window').width);
+
+  const [contentOffset] = useState(() => {
+    const ymd = dateRef.current;
+    const dayEvents = events[ymd];
+    let firstEventTop: number | undefined;
+    if (dayEvents?.length) {
+      let earliest = Infinity;
+      for (const e of dayEvents) earliest = Math.min(earliest, minutesOf(e.start));
+      firstEventTop = (earliest / 60) * hourHeight;
+    }
+    const y = initialScrollY({
+      isToday: dayIndexOf(range, ymd) === range.todayIndex,
+      scrollToNow,
+      scrollToFirst,
+      initialTime,
+      firstEventTop,
+      hourHeight,
+    });
+    return { x: 0, y };
+  });
+
+  const availableHoursFor = useCallback(
+    (ymd: DateString) => (Array.isArray(availableHours) ? availableHours : availableHours?.[ymd]),
+    [availableHours],
+  );
+
+  const onLayout = useCallback((e: LayoutChangeEvent) => {
+    const w = e.nativeEvent.layout.width;
+    setWidth((prev) => (Math.abs(prev - w) < 0.5 ? prev : w));
+  }, []);
+
+  const colW = Math.max(0, width - GUTTER);
+  const dayHeight = gridHeight(hourHeight);
+
+  return (
+    <View style={styles.root} onLayout={onLayout}>
+      <ScrollView contentOffset={contentOffset} showsVerticalScrollIndicator={false} nestedScrollEnabled>
+        <View style={{ height: dayHeight + CONTENT_BOTTOM_PAD }}>
+          <HourGrid hourHeight={hourHeight} format24h={format24h} />
+          {colW > 0 ? (
+            <DayPager
+              left={GUTTER}
+              width={colW}
+              height={dayHeight}
+              events={events}
+              availableHoursFor={availableHoursFor}
+              bandColor={availableHoursColor}
+              hourHeight={hourHeight}
+              overlapEventsSpacing={overlapEventsSpacing}
+              rightEdgeSpacing={rightEdgeSpacing}
+              renderEvent={renderEvent}
+              onEventPress={onEventPress}
+              showNowIndicator={showNowIndicator}
+            />
+          ) : null}
+        </View>
+      </ScrollView>
+    </View>
+  );
+};
+
+const makeStyles = ({ colors }: KitStyleArgs) =>
+  StyleSheet.create({
+    root: { flex: 1, backgroundColor: colors.surface },
+  });

package/src/timeline/packEvents.ts

@@ -0,0 +1,118 @@
+/**
+ * Overlap packing for one day column — `react-native-calendars`' `Packer.js`, in minutes, so
+ * blocks land where react-native-calendars put them. Sort by start then end; a new overlap group starts
+ * at or after the latest end seen; first-fit into columns; each event gets `1/n` of the width,
+ * widened across later columns it does not collide with.
+ *
+ * Deliberate edge differences: a missing `end` is start + 60; an `end` at or before `start` is
+ * start + 15 (the library drew a negative height); collisions use an end of at least start + 15,
+ * so two zero-length events at one minute get their own columns.
+ *
+ * Invariant the span pass relies on: a column's events are sorted and pairwise disjoint, so the
+ * last event placed in a column is the only one that can still overlap a later-starting event.
+ * `lib/overlap-detection.ts` cannot execute (gap-6) — do not swap it in.
+ */
+
+import type { PackedTimelineEvent, TimelineEvent } from '../types';
+import { DAY_MINUTES, minutesOf } from './timelineMath';
+
+const SHORT_EVENT_MINUTES = 15;
+
+type Item<E> = {
+  ev: E;
+  index: number;
+  start: number;
+  end: number;
+  /** End used for collision tests: never less than start + 15. */
+  collEnd: number;
+  /** Columns this event may cover, capped at `n − column` when its group flushes. */
+  span: number;
+};
+
+type PackOptions = {
+  /** Width of the day column, px. */
+  colW: number;
+  hourHeight: number;
+  overlapEventsSpacing?: number;
+  rightEdgeSpacing?: number;
+};
+
+export const packEvents = <E extends TimelineEvent>(
+  events: E[] | undefined,
+  { colW, hourHeight, overlapEventsSpacing = 0, rightEdgeSpacing = 0 }: PackOptions,
+): PackedTimelineEvent<E>[] => {
+  if (!events?.length || colW <= 0) return [];
+
+  const items: Item<E>[] = events.map((ev, index) => {
+    const start = Math.min(Math.max(minutesOf(ev.start), 0), DAY_MINUTES);
+    let end = ev.end ? minutesOf(ev.end) : start + 60;
+    if (end <= start) end = start + SHORT_EVENT_MINUTES;
+    end = Math.min(end, DAY_MINUTES);
+    const collEnd = Math.max(end, start + SHORT_EVENT_MINUTES);
+    return { ev, index, start, end, collEnd, span: Infinity };
+  });
+
+  items.sort((a, b) => a.start - b.start || a.end - b.end || a.index - b.index);
+
+  const packed: PackedTimelineEvent<E>[] = [];
+  const totalW = colW - rightEdgeSpacing;
+
+  let columns: Item<E>[][] = [];
+  /** `collEnd` of each column's last event: the whole collision test against that column. */
+  const lastEnd: number[] = [];
+  let groupEnd = -1;
+
+  const flush = () => {
+    const n = columns.length;
+    for (let c = 0; c < n; c += 1) {
+      for (const item of columns[c]) {
+        const span = Math.min(item.span, n - c);
+        let width = (totalW * span) / n;
+        if (c + span <= n - 1) width -= overlapEventsSpacing;
+        packed.push({
+          ...item.ev,
+          index: item.index,
+          left: (c / n) * totalW,
+          width,
+          top: (item.start / 60) * hourHeight,
+          height: ((item.end - item.start) / 60) * hourHeight,
+        });
+      }
+    }
+    columns = [];
+    lastEnd.length = 0;
+  };
+
+  for (const item of items) {
+    if (columns.length && item.start >= groupEnd) {
+      flush();
+      groupEnd = -1;
+    }
+
+    const cols = lastEnd.length;
+    let col = 0;
+    while (col < cols && lastEnd[col] > item.start) col += 1;
+
+    // Every column left of `col` ends after this item starts: its last event stops spanning here.
+    for (let i = 0; i < col; i += 1) {
+      const last = columns[i][columns[i].length - 1];
+      if (last.span > col - i) last.span = col - i;
+    }
+    // The nearest column to the right still busy at this item's start caps its own span.
+    for (let k = col + 1; k < cols; k += 1) {
+      if (lastEnd[k] > item.start) {
+        item.span = k - col;
+        break;
+      }
+    }
+
+    if (col === cols) columns.push([item]);
+    else columns[col].push(item);
+    lastEnd[col] = item.collEnd;
+    if (columns.length === 1 && columns[0].length === 1) groupEnd = item.collEnd;
+    else if (item.collEnd > groupEnd) groupEnd = item.collEnd;
+  }
+  if (columns.length) flush();
+
+  return packed;
+};

package/src/timeline/timelineGeometry.ts

@@ -0,0 +1,23 @@
+// Timeline geometry, numbers only. Transcribed from `react-native-calendars` (`Packer.js`,
+// `TimelineHours.js`, `timeline/style.js`); GUTTER is the provider's `timelineLeftInset` default.
+
+/** px per hour. The live event card's layout branches (<25 / <50 / <70) assume it. */
+export const HOUR_HEIGHT = 100;
+
+export const GUTTER = 72;
+
+/** Hour lines start this far inside the gutter (`timelineLeftInset - 16`). */
+export const LINE_GUTTER_OVERHANG = 16;
+
+/** Labels sit 6 px above their line, centred in the 56 px label box. */
+export const LABEL_OFFSET_Y = -6;
+export const LABEL_PADDING_LEFT = 12;
+
+/** `contentStyle.height: calendarHeight + 10`. */
+export const CONTENT_BOTTOM_PAD = 10;
+
+export const EVENT_MIN_HEIGHT = 25;
+
+export const NOW_KNOB = 7;
+
+export const gridHeight = (hourHeight: number): number => 24 * hourHeight;

package/src/timeline/timelineMath.ts

@@ -0,0 +1,86 @@
+/** Pure time ↔ pixel arithmetic for the timeline, in minutes of the day — never a `Date`. */
+
+import type { AvailableHours } from '../types';
+
+export const DAY_MINUTES = 24 * 60;
+
+const digitAt = (s: string, i: number): number => {
+  const d = s.charCodeAt(i) - 48;
+  return d >= 0 && d <= 9 ? d : -1;
+};
+
+/** Minute of the day from `'YYYY-MM-DD HH:mm:ss'` (HH at 11–12, mm at 14–15); 0 when unreadable. */
+export const minutesOf = (dateTime: string | undefined): number => {
+  if (!dateTime || dateTime.length < 16) return 0;
+  const h1 = digitAt(dateTime, 11);
+  const h2 = digitAt(dateTime, 12);
+  const m1 = digitAt(dateTime, 14);
+  const m2 = digitAt(dateTime, 15);
+  if (h1 < 0 || h2 < 0 || m1 < 0 || m2 < 0) return 0;
+  return (h1 * 10 + h2) * 60 + m1 * 10 + m2;
+};
+
+/** `{ hour, minutes }` or `'H:mm'` → minute of the day. */
+const initialTimeMinutes = (
+  t: { hour: number; minutes: number } | string | undefined,
+): number | undefined => {
+  if (t == null) return undefined;
+  if (typeof t === 'string') {
+    const [h, m] = t.split(':').map(Number);
+    return Number.isFinite(h) ? h * 60 + (Number.isFinite(m) ? m : 0) : undefined;
+  }
+  return t.hour * 60 + (t.minutes || 0);
+};
+
+/**
+ * Library precedence (`timeline-list`): today → `scrollToNow` only; other days → `scrollToFirst`
+ * (when the day has events) over `initialTime`. One hour above the target, as `Timeline.js` does.
+ */
+export const initialScrollY = ({
+  isToday,
+  scrollToNow,
+  scrollToFirst,
+  initialTime,
+  firstEventTop,
+  hourHeight,
+  now = new Date(),
+}: {
+  isToday: boolean;
+  scrollToNow?: boolean;
+  scrollToFirst?: boolean;
+  initialTime?: { hour: number; minutes: number } | string;
+  /** Top of the earliest packed event on the day, or undefined when empty. */
+  firstEventTop?: number;
+  hourHeight: number;
+  now?: Date;
+}): number => {
+  let pos = 0;
+  if (isToday) {
+    if (scrollToNow) pos = ((now.getHours() * 60 + now.getMinutes()) / 60) * hourHeight;
+  } else if (scrollToFirst && firstEventTop !== undefined) {
+    pos = firstEventTop;
+  } else {
+    const m = initialTimeMinutes(initialTime);
+    if (m !== undefined) pos = (m / 60) * hourHeight;
+  }
+  return pos ? Math.max(0, pos - hourHeight) : 0;
+};
+
+export type Band = { top: number; height: number };
+
+/**
+ * Availability windows → pixel bands. Invalid windows are dropped silently: they are backend
+ * data, and the library's `console.error` raised a red box in debug builds.
+ */
+export const buildBands = (windows: AvailableHours | undefined, hourHeight: number): Band[] => {
+  if (!windows?.length) return [];
+  const out: Band[] = [];
+  for (const w of windows) {
+    if (!(w.start >= 0 && w.start < 25 && w.end >= 0 && w.end < 25)) continue;
+    if (w.start >= w.end) continue;
+    const e = Math.min(w.end, 24);
+    if (e <= w.start) continue;
+    out.push({ top: w.start * hourHeight, height: (e - w.start) * hourHeight });
+  }
+  return out;
+};

package/src/types.ts

@@ -0,0 +1,252 @@
+/**
+ * react-native-agenda-kit — the public type surface.
+ *
+ * The kit is a PURE UI LIBRARY: it fetches nothing, knows no app type, and
+ * reads only design tokens. Everything domain-shaped (an appointment, a
+ * booking status, a locale) arrives as a caller-supplied render prop or a
+ * primitive. That boundary is what makes the three surfaces reusable and what
+ * keeps the CONSUMER's screen the only place that knows what a row *means*.
+ *
+ * Names deliberately match `react-native-calendars`' public API
+ * (`CalendarProvider`, `ExpandableCalendar`, `AgendaList`, `TimelineList`,
+ * `UpdateSources`) so a migrating screen's JSX is a copy, not a rewrite.
+ */
+
+import type { ReactElement, ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+/** 'YYYY-MM-DD', local calendar day. The only date string the kit accepts. */
+export type DateString = string;
+
+/**
+ * Why a date changed. The strings are byte-identical to the library's
+ * `commons.js` UpdateSources so the screen's `handleDateChanged` switch is a
+ * verbatim copy.
+ */
+export const UpdateSources = {
+  CALENDAR_INIT: 'calendarInit',
+  TODAY_PRESS: 'todayPress',
+  LIST_DRAG: 'listDrag',
+  DAY_PRESS: 'dayPress',
+  PAGE_SCROLL: 'pageScroll',
+  WEEK_SCROLL: 'weekScroll',
+  PROP_UPDATE: 'propUpdate',
+} as const;
+
+export type UpdateSource = (typeof UpdateSources)[keyof typeof UpdateSources];
+
+/**
+ * Which surface *produced* a programmatic move. The originating scroller
+ * ignores its own origin, which is the whole echo-proofing story: no latches,
+ * no 500 ms timers, no `changedItems` bookkeeping.
+ */
+export type MoveOrigin = 'agenda' | 'timeline' | 'week' | 'month' | 'external';
+
+/** One programmatic move. `seq` makes every move distinct even when `idx` repeats. */
+export type CalendarMove = {
+  seq: number;
+  idx: number;
+  origin: MoveOrigin;
+  animated: boolean;
+};
+
+/**
+ * The one index space. Every surface addresses a day by its integer offset
+ * from `start`: agenda section index, week page `floor(i/7)`, month page,
+ * timeline column. Worklets never touch strings.
+ *
+ * `start` is a Monday (the skeleton pads to whole weeks) and `days` is a
+ * multiple of 7, so `floor(dayIndex / 7)` is always a whole page.
+ */
+export type CalendarRange = {
+  /** 'YYYY-MM-DD' of index 0 — a padded week start. */
+  start: DateString;
+  /** Epoch day of `start` (see `core/civil.ts`): `dayIndexOf` is one subtraction. */
+  startEpochDay: number;
+  /** 'YYYY-MM-DD' of every index, built once: `ymdAt` is one array read. */
+  ymdByIndex: readonly DateString[];
+  /** Total day count (e.g. 126 or 133 for a 4-month window). */
+  days: number;
+  /** Selectable bounds, inclusive, as indices into the same space. */
+  minIndex: number;
+  maxIndex: number;
+  /** 1 = Monday. Matches the library's `firstDay`. */
+  firstDay: number;
+  /** Index of today, or -1 when today is outside the range. */
+  todayIndex: number;
+};
+
+/* ── Agenda ────────────────────────────────────────────────────────────── */
+
+/**
+ * A day's worth of rows. `title` is the 'YYYY-MM-DD' key — the library's
+ * SectionList convention, kept so `renderSectionHeader` stays a copy.
+ */
+export type AgendaSection<T> = {
+  title: DateString;
+  data: T[];
+};
+
+export type AgendaListRef = {
+  scrollToDate: (date: DateString, animated?: boolean) => void;
+  scrollToSection: (title: DateString, animated?: boolean) => void;
+  scrollToOffset: (params: { offset: number; animated?: boolean }) => void;
+};
+
+export type AgendaListProps<T> = {
+  sections: AgendaSection<T>[];
+  renderItem: (info: { item: T; index: number; section: AgendaSection<T> }) => ReactElement | null;
+  renderSectionHeader: (title: DateString) => ReactElement | null;
+
+  /**
+   * Declared row heights in px, keyed by `getItemType`. Never measured: a wrong
+   * number clips inside its slot instead of shifting the list (DEV warns per type).
+   */
+  itemHeightByType: Record<string, number>;
+  /** Height of a section header slot. Default 32. */
+  sectionHeaderHeight?: number;
+
+  /** Defaults to `item.itemCustomHeightType`, else 'Regular'. */
+  getItemType?: (item: T) => string;
+  /** Defaults to `item.id`. */
+  keyExtractor?: (item: T, index: number) => string;
+
+  /** Real sticky headers (a fixed overlay), unlike the library's. */
+  stickySectionHeadersEnabled?: boolean;
+  /** Real `RefreshControl`. Arms at the top of the window only (platform). */
+  refreshing?: boolean;
+  onRefresh?: () => void;
+
+  /**
+   * Skeleton tiles drawn BEHIND the list, moving with it. With a backdrop, rows
+   * entering the window during a fast fling are deferred and the backdrop shows
+   * through their slots — so a fling that outruns the JS thread never shows bare
+   * ground. Without one, every row renders real.
+   */
+  backdrop?: { tileHeight: number; renderTile: () => ReactElement };
+  /** Painted under every drawn row, so the backdrop shows only where no row is drawn. */
+  rowGroundColor?: string;
+
+  decelerationRate?: number | 'fast' | 'normal';
+  ref?: React.Ref<AgendaListRef>;
+
+  /** Gesture hooks: drag begin and settle. Each costs a UI→JS hop per gesture — pass them only when needed. */
+  onDragBegin?: () => void;
+  onSettle?: () => void;
+
+  /* Accepted and ignored — typed so JSX copied from the react-native-calendars screen compiles. */
+  titleHeight?: number;
+  sectionStyle?: StyleProp<ViewStyle>;
+  dayFormatter?: (date: string) => string;
+  markToday?: boolean;
+  updateCellsBatchingPeriod?: number;
+  onScrollToIndexFailed?: (info: unknown) => void;
+  infiniteListProps?: Record<string, unknown>;
+};
+
+/* ── Expandable calendar ───────────────────────────────────────────────── */
+
+export type MarkedDates = Record<
+  DateString,
+  { marked?: boolean; dotColor?: string; selected?: boolean; disabled?: boolean }
+>;
+
+export type CalendarPosition = 'closed' | 'open';
+
+export type ExpandableCalendarRef = {
+  /** Returns the position it moved TO. `true` = open. */
+  toggleCalendarPosition: () => boolean;
+};
+
+export type ExpandableCalendarProps = ExpandableCalendarCompatProps & {
+  initialPosition?: CalendarPosition;
+  onCalendarToggled?: (isOpen: boolean) => void;
+  style?: StyleProp<ViewStyle>;
+  closeOnDayPress?: boolean;
+  /** Collapse an open calendar when a list under it starts a drag. Default true; ignored under a screen reader. */
+  closeOnListScroll?: boolean;
+  markedDates?: MarkedDates;
+  disablePan?: boolean;
+  openThreshold?: number;
+  closeThreshold?: number;
+  /** Screen-reader label for the drag knob. Caller-supplied: the kit ships no strings. */
+  knobAccessibilityLabel?: string;
+  /** The spoken name of a grid day; called only while a screen reader runs, once per day of the range. */
+  dayAccessibilityLabel?: (date: DateString) => string;
+  /** Twelve short month names, January first, drawn over each 1st in the week strip. None drawn when absent. */
+  monthShortLabels?: readonly string[];
+  /** Rendered inside the body the calendar pushes down — the agenda or the timeline. */
+  children?: ReactNode;
+  ref?: React.Ref<ExpandableCalendarRef>;
+};
+
+/** Accepted and never read — typed so JSX copied from `react-native-calendars` compiles unchanged. */
+export type ExpandableCalendarCompatProps = {
+  firstDay?: number;
+  /** No header band is rendered; the callers pass `() => null`. */
+  renderHeader?: (date?: DateString) => ReactNode;
+  headerStyle?: StyleProp<ViewStyle>;
+  minDate?: DateString;
+  maxDate?: DateString;
+  pastScrollRange?: number;
+  futureScrollRange?: number;
+  hideArrows?: boolean;
+  allowShadow?: boolean;
+  /** No day-names row is rendered; the callers pass `hideDayNames`. */
+  hideDayNames?: boolean;
+  dayNames?: string[];
+  theme?: unknown;
+  onVisibleMonthsChange?: (months: unknown[]) => void;
+};
+
+/* ── Timeline ──────────────────────────────────────────────────────────── */
+
+/** `start` / `end` are 'YYYY-MM-DD HH:mm:ss' — the library's wire format. */
+export type TimelineEvent = {
+  id: string;
+  start: string;
+  end?: string;
+  title?: string;
+  summary?: string;
+  color?: string;
+};
+
+export type PackedTimelineEvent<E extends TimelineEvent = TimelineEvent> = E & {
+  /** Packer output, in px relative to the column. */
+  index: number;
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+};
+
+/** An inclusive window of *available* time. The kit never takes the inverse. */
+export type AvailableHours = { start: number; end: number }[];
+
+export type TimelineInnerProps<E extends TimelineEvent = TimelineEvent> = {
+  renderEvent?: (event: PackedTimelineEvent<E>) => ReactElement | null;
+  /** Receives the PACKED event, as the library's does (`Timeline.js` passes `packedEvents[i][j]`). */
+  onEventPress?: (event: PackedTimelineEvent<E>) => void;
+  format24h?: boolean;
+  overlapEventsSpacing?: number;
+  rightEdgeSpacing?: number;
+  /**
+   * AVAILABLE windows, per date. The library takes `unavailableHours`; the
+   * consumer usually computes availability directly, so the kit takes the
+   * un-inverted form. This is the one deliberate rename.
+   */
+  availableHours?: Record<DateString, AvailableHours> | AvailableHours;
+  availableHoursColor?: string;
+  hourHeight?: number;
+};
+
+export type TimelineListProps<E extends TimelineEvent = TimelineEvent> = {
+  /** Keyed by 'YYYY-MM-DD'. Neighbours must be present or a swipe shows a blank day. */
+  events: Record<DateString, E[]>;
+  timelineProps?: TimelineInnerProps<E>;
+  showNowIndicator?: boolean;
+  scrollToNow?: boolean;
+  scrollToFirst?: boolean;
+  /** 'HH:mm' or `{ hour, minutes }`. Lowest precedence. */
+  initialTime?: { hour: number; minutes: number } | string;
+};