react-native-agenda-kit 0.1.0

package/src/core/CalendarProvider.tsx

@@ -0,0 +1,165 @@
+/**
+ * The date owner. Compat with `react-native-calendars`' `CalendarProvider`.
+ *
+ * Two cadences: `setDate` is synchronous (day tap, Today, page settle, the `date`
+ * prop) and writes `dayIndex`; `commitDate` is the scroll path, called from a
+ * worklet at settle and per month crossing, and leaves `dayIndex` to the
+ * scroller that already owns it. Both bump `move` so the OTHER surfaces follow.
+ *
+ * The prop echo: a controlled caller mirrors every `onDateChanged` back into
+ * `date`, and a `runOnJS` commit can land between a render's commit and its
+ * effects, so "prop equals current date" is not enough (M5: a fast fling was
+ * thrown back a month as `propUpdate`). The provider queues what it emitted; a
+ * prop matching a pending emission is an echo and consumes the queue up to it.
+ */
+
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { monthOrdinalOfYmd } from './civil';
+import { CalendarContext, CalendarDateContext, type CalendarContextValue } from './CalendarContext';
+import { useCreateCalendarStore } from './CalendarStore';
+import { clampIndex, dayIndexOf, ymdAt } from './dateKey';
+import { useReduceMotion } from './motion';
+import { TodayButton } from './TodayButton';
+import { AgendaKitThemeProvider } from '../theme';
+import type { AgendaKitTheme, PartialAgendaKitTheme } from '../theme';
+import type { CalendarRange, DateString, MoveOrigin, UpdateSource } from '../types';
+
+export type CalendarProviderProps = {
+  range: CalendarRange;
+  date: DateString;
+  onDateChanged?: (date: DateString, source: UpdateSource) => void;
+  onMonthChange?: (date: DateString, source: UpdateSource) => void;
+  showTodayButton?: boolean;
+  todayBottomMargin?: number;
+  /** Required for the Today button to render: the kit ships no strings. */
+  todayLabel?: string;
+  /**
+   * Colours and font families. A partial theme layers over `base`
+   * (`lightTheme` unless given), so `{ colors: { accent: '#0F766E' } }` is a
+   * complete override. Omit it entirely for the built-in light theme.
+   *
+   * Pass a STABLE object — a fresh literal every render rebuilds every
+   * stylesheet in the tree. Hoist it to module scope or memoise it.
+   */
+  theme?: AgendaKitTheme | PartialAgendaKitTheme;
+  /** Which built-in a partial `theme` layers over. Pass `darkTheme` for dark mode. */
+  themeBase?: AgendaKitTheme;
+  children: ReactNode;
+};
+
+/** Emissions a caller may leave unechoed before the oldest is forgotten. */
+const MAX_PENDING_ECHOES = 8;
+
+export const CalendarProvider = ({
+  range,
+  date,
+  onDateChanged,
+  onMonthChange,
+  showTodayButton = false,
+  todayBottomMargin = 0,
+  todayLabel,
+  theme,
+  themeBase,
+  children,
+}: CalendarProviderProps) => {
+  const [initialIndex] = useState(() => dayIndexOf(range, date));
+  const store = useCreateCalendarStore(range, initialIndex);
+  const dateRef = useRef(date);
+  const pendingEchoesRef = useRef<DateString[]>([]);
+  const reduceMotion = useReduceMotion();
+  const [committed, setCommitted] = useState(date);
+
+  // Read through a ref so a caller passing inline arrows, or the setting
+  // changing, cannot churn `setDate`'s identity — every scroller holds it.
+  const live = useRef({ onDateChanged, onMonthChange, reduceMotion });
+  live.current.onDateChanged = onDateChanged;
+  live.current.onMonthChange = onMonthChange;
+  live.current.reduceMotion = reduceMotion;
+
+  useEffect(() => {
+    if (__DEV__ && showTodayButton && !todayLabel) {
+      console.warn('[agenda-kit] showTodayButton needs todayLabel; the button is not rendered.');
+    }
+  }, [showTodayButton, todayLabel]);
+
+  const commitCore = useCallback(
+    (idx: number, source: UpdateSource, writeDayIndex: boolean, origin: MoveOrigin, animated: boolean) => {
+      const ymd = ymdAt(range, idx);
+      const prev = dateRef.current;
+      dateRef.current = ymd;
+
+      const pending = pendingEchoesRef.current;
+      pending.push(ymd);
+      if (pending.length > MAX_PENDING_ECHOES) pending.shift();
+
+      setCommitted(ymd);
+      live.current.onDateChanged?.(ymd, source);
+      if (monthOrdinalOfYmd(prev) !== monthOrdinalOfYmd(ymd)) live.current.onMonthChange?.(ymd, source);
+
+      if (writeDayIndex) store.dayIndex.value = idx;
+      store.move.value = {
+        seq: store.move.value.seq + 1,
+        idx,
+        origin,
+        animated: animated && !live.current.reduceMotion,
+      };
+    },
+    [range, store],
+  );
+
+  const setDate = useCallback(
+    (ymd: DateString, source: UpdateSource, origin: MoveOrigin = 'external', animated = true) => {
+      if (ymd === dateRef.current) return;
+      const idx = dayIndexOf(range, ymd);
+      if (Number.isNaN(idx)) return;
+      commitCore(clampIndex(range, idx), source, true, origin, animated);
+    },
+    [commitCore, range],
+  );
+
+  const commitDate = useCallback(
+    (idx: number, source: UpdateSource, origin: MoveOrigin) => {
+      const clamped = clampIndex(range, idx);
+      if (ymdAt(range, clamped) === dateRef.current) return;
+      commitCore(clamped, source, false, origin, false);
+    },
+    [commitCore, range],
+  );
+
+  // A layout effect runs inside the commit, which narrows the race; the queue is
+  // what makes it correct. `indexOf` consumes the EARLIEST matching emission.
+  useLayoutEffect(() => {
+    const pending = pendingEchoesRef.current;
+    const at = pending.indexOf(date);
+    if (at >= 0) {
+      pending.splice(0, at + 1);
+      return;
+    }
+    setDate(date, 'propUpdate');
+  }, [date, setDate]);
+
+  const value = useMemo<CalendarContextValue>(
+    () => ({ range, store, dateRef, setDate, commitDate, reduceMotion }),
+    [range, store, setDate, commitDate, reduceMotion],
+  );
+
+  return (
+    <AgendaKitThemeProvider theme={theme} base={themeBase}>
+      <CalendarContext.Provider value={value}>
+        <CalendarDateContext.Provider value={committed}>
+          <View style={styles.wrapper}>
+            {children}
+            {showTodayButton && todayLabel ? (
+              <TodayButton label={todayLabel} bottomMargin={todayBottomMargin} />
+            ) : null}
+          </View>
+        </CalendarDateContext.Provider>
+      </CalendarContext.Provider>
+    </AgendaKitThemeProvider>
+  );
+};
+
+const styles = StyleSheet.create({
+  wrapper: { flex: 1 },
+});

package/src/core/CalendarStore.ts

@@ -0,0 +1,64 @@
+/**
+ * The UI-thread half of the calendar: four shared values, created once.
+ *
+ * The scroll offset owns position and `dayIndex` is derived from it on the UI
+ * thread, so the week strip, the Today button and the sticky header track a
+ * fling frame-locked. `move` carries a programmatic move with its `origin`;
+ * each scroller ignores its own origin, so a `scrollTo` never echoes back.
+ */
+
+import { useEffect, useState } from 'react';
+import { AppState } from 'react-native';
+import { useSharedValue, type SharedValue } from 'react-native-reanimated';
+import { todayIndexOf } from './dateKey';
+import type { CalendarMove, CalendarRange } from '../types';
+
+/**
+ * SHARED VALUES ONLY. Worklets that read `store.x.value` capture `store`, and
+ * react-native-worklets freezes captured objects in `__DEV__`: a plain ref in
+ * here silently ignores every write (M2: the echo guard compared against a date
+ * frozen at mount). Anything else lives on the provider and the context.
+ */
+export type CalendarStore = {
+  /** UI-thread truth. Written by whichever scroller owns the position. */
+  dayIndex: SharedValue<number>;
+  /** The last programmatic move. `seq` makes repeats distinct. */
+  move: SharedValue<CalendarMove>;
+  /** Index of today, refreshed across midnight and on app foreground. */
+  todayIndex: SharedValue<number>;
+  /** Bumped when a list starts a drag; only the CHANGE means anything. */
+  listDragSeq: SharedValue<number>;
+};
+
+const NO_MOVE: CalendarMove = { seq: 0, idx: 0, origin: 'external', animated: false };
+
+export const useCreateCalendarStore = (range: CalendarRange, initialIndex: number): CalendarStore => {
+  const dayIndex = useSharedValue(initialIndex);
+  const move = useSharedValue<CalendarMove>(NO_MOVE);
+  const todayIndex = useSharedValue(range.todayIndex);
+  const listDragSeq = useSharedValue(0);
+
+  const { startEpochDay, days } = range;
+  useEffect(() => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    // One timer for the next local midnight, re-armed on foreground: a 24 h
+    // interval drifts and fires at the wrong instant after a suspend.
+    const refreshAndArm = () => {
+      todayIndex.value = todayIndexOf(startEpochDay, days);
+      if (timer) clearTimeout(timer);
+      const now = new Date();
+      const next = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1, 0, 0, 5);
+      timer = setTimeout(refreshAndArm, Math.max(1000, next.getTime() - now.getTime()));
+    };
+    refreshAndArm();
+    const sub = AppState.addEventListener('change', (state) => {
+      if (state === 'active') refreshAndArm();
+    });
+    return () => {
+      if (timer) clearTimeout(timer);
+      sub.remove();
+    };
+  }, [days, startEpochDay, todayIndex]);
+
+  return useState(() => ({ dayIndex, move, todayIndex, listDragSeq }))[0];
+};

package/src/core/KitText.tsx

@@ -0,0 +1,10 @@
+import type { Ref } from 'react';
+import { Text, type TextProps } from 'react-native';
+
+/**
+ * Kit text with OS scaling pinned off: row heights are declared, so scaled text
+ * would clip in its slot. `Text.defaultProps` is a no-op under React 19.
+ */
+export const KitText = ({ ref, ...props }: TextProps & { ref?: Ref<Text> }) => (
+  <Text ref={ref} allowFontScaling={false} maxFontSizeMultiplier={1} {...props} />
+);

package/src/core/TodayButton.tsx

@@ -0,0 +1,121 @@
+/**
+ * The Today pill, visible whenever the calendar is not on today: centred, with an
+ * arrow pointing the way back to today (the owner's Teams reference, 2026-09-11).
+ *
+ * Visibility and the arrow's direction are derived on the UI thread from
+ * `dayIndex` and `todayIndex`, so the pill appears the frame a fling leaves today
+ * and the arrow flips with no React commit. The show/hide animation starts from a
+ * reaction that fires only when the boolean flips — `withTiming` returned from
+ * `useAnimatedStyle` would restart on every frame of a fling. Hidden means
+ * translated off the bottom edge: a transparent pill would still swallow taps.
+ */
+
+import { useKitStyles, useKitTheme, type KitStyleArgs } from '../theme';
+import { ANIMATION, FONT_SIZE, RADIUS, SPACING } from '../theme/tokens';
+import { memo, useCallback, useMemo } from 'react';
+import { Pressable, StyleSheet } from 'react-native';
+import Animated, {
+  useAnimatedReaction,
+  useAnimatedStyle,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+import { ArrowGlyph } from './ArrowGlyph';
+import { useCalendarContext } from './CalendarContext';
+import { dayIndexOf, ymdAt } from './dateKey';
+import { KitText } from './KitText';
+import { KIT_EASING, kitDuration } from './motion';
+
+/** The library's non-tablet `todayButton.height`. */
+const BUTTON_HEIGHT = 28;
+const ARROW_SIZE = 14;
+
+type Props = {
+  label: string;
+  bottomMargin?: number;
+};
+
+const TodayButtonInner = ({ label, bottomMargin = 0 }: Props) => {
+  const styles = useKitStyles(makeStyles);
+  const { colors } = useKitTheme();
+  const { range, store, dateRef, setDate, reduceMotion } = useCalendarContext();
+  const duration = kitDuration(ANIMATION.base, reduceMotion);
+  const hiddenOffset = bottomMargin + BUTTON_HEIGHT + SPACING[5];
+
+  // Mount-time seed from plain values (reading a shared value in render is
+  // unsupported); the reaction owns every change after that.
+  const shown = useSharedValue(
+    range.todayIndex >= 0 && dayIndexOf(range, dateRef.current) !== range.todayIndex ? 1 : 0,
+  );
+
+  useAnimatedReaction(
+    () => {
+      const today = store.todayIndex.value;
+      return today >= 0 && store.dayIndex.value !== today ? 1 : 0;
+    },
+    (next, prev) => {
+      if (next === prev) return;
+      shown.value = withTiming(next, { duration, easing: KIT_EASING });
+    },
+    [duration],
+  );
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    opacity: shown.value,
+    transform: [{ translateY: (1 - shown.value) * hiddenOffset }],
+  }));
+  // Up when today lies above the list's day, down when below.
+  const arrowStyle = useAnimatedStyle(() => ({
+    transform: [{ rotate: store.todayIndex.value < store.dayIndex.value ? '0deg' : '180deg' }],
+  }));
+
+  const onPress = useCallback(() => {
+    const today = store.todayIndex.value;
+    if (today >= 0) setDate(ymdAt(range, today), 'todayPress');
+  }, [range, setDate, store]);
+
+  const containerStyle = useMemo(
+    () => [styles.container, { bottom: bottomMargin }, animatedStyle],
+    [animatedStyle, bottomMargin, styles.container],
+  );
+
+  return (
+    <Animated.View pointerEvents="box-none" style={containerStyle}>
+      <Pressable
+        style={styles.button}
+        onPress={onPress}
+        hitSlop={8}
+        accessibilityRole="button"
+        accessibilityLabel={label}
+      >
+        <Animated.View style={arrowStyle}>
+          <ArrowGlyph size={ARROW_SIZE} color={colors.accent} />
+        </Animated.View>
+        <KitText style={styles.label} numberOfLines={1}>
+          {label}
+        </KitText>
+      </Pressable>
+    </Animated.View>
+  );
+};
+
+export const TodayButton = memo(TodayButtonInner);
+TodayButton.displayName = 'TodayButton';
+
+const makeStyles = ({ colors, fonts }: KitStyleArgs) =>
+  StyleSheet.create({
+    container: { position: 'absolute', left: 0, right: 0, alignItems: 'center' },
+    button: {
+      height: BUTTON_HEIGHT,
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: SPACING[1],
+      paddingHorizontal: SPACING[3],
+      borderRadius: RADIUS.full,
+      borderWidth: 1,
+      borderColor: colors.border,
+      backgroundColor: colors.surface,
+    },
+    // An action's label: accent INK, never a fill.
+    label: { fontFamily: fonts.medium, fontSize: FONT_SIZE.sm, color: colors.accent },
+  });

package/src/core/civil.ts

@@ -0,0 +1,92 @@
+/**
+ * Integer civil-date arithmetic: no `Date`, no string splitting, no timezone.
+ *
+ * An epoch day is the count of days since 1970-01-01 in the proleptic Gregorian
+ * calendar. Calendar days are integers here, so a DST transition cannot make two
+ * days 23 or 25 hours apart — the bug a `(a - b) / 86400000` calendar has twice
+ * a year. Algorithms: H. Hinnant, "chrono-Compatible Low-Level Date Algorithms".
+ */
+
+/** Epoch day of a civil date. `m` is 1–12. */
+export const epochDayOf = (y: number, m: number, d: number): number => {
+  const yy = m <= 2 ? y - 1 : y;
+  const era = Math.floor(yy / 400);
+  const yoe = yy - era * 400;
+  const doy = Math.floor((153 * ((m + 9) % 12) + 2) / 5) + d - 1;
+  const doe = yoe * 365 + Math.floor(yoe / 4) - Math.floor(yoe / 100) + doy;
+  return era * 146097 + doe - 719468;
+};
+
+/** Civil date of an epoch day, packed as YYYYMMDD so nothing is allocated. */
+export const civilOf = (z: number): number => {
+  const zz = z + 719468;
+  const era = Math.floor(zz / 146097);
+  const doe = zz - era * 146097;
+  const yoe = Math.floor(
+    (doe - Math.floor(doe / 1460) + Math.floor(doe / 36524) - Math.floor(doe / 146096)) / 365,
+  );
+  const doy = doe - (365 * yoe + Math.floor(yoe / 4) - Math.floor(yoe / 100));
+  const mp = Math.floor((5 * doy + 2) / 153);
+  const d = doy - Math.floor((153 * mp + 2) / 5) + 1;
+  const m = mp < 10 ? mp + 3 : mp - 9;
+  return (yoe + era * 400 + (m <= 2 ? 1 : 0)) * 10000 + m * 100 + d;
+};
+
+/** 0 = Sunday … 6 = Saturday, as `Date#getDay`. 1970-01-01 was a Thursday. */
+export const weekdayOf = (z: number): number => (((z + 4) % 7) + 7) % 7;
+
+const isLeap = (y: number): boolean => (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0;
+const MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+export const daysInMonth = (y: number, m: number): number =>
+  m === 2 && isLeap(y) ? 29 : MONTH_DAYS[m - 1];
+
+/** '00'…'31', so formatting never calls `padStart` or builds a template per part. */
+const TWO_DIGIT: readonly string[] = Array.from({ length: 32 }, (_, i) => (i < 10 ? `0${i}` : `${i}`));
+
+/** 'YYYY-MM-DD' of an epoch day. */
+export const ymdOfEpochDay = (z: number): string => {
+  const c = civilOf(z);
+  const y = Math.floor(c / 10000);
+  return `${y}-${TWO_DIGIT[Math.floor(c / 100) % 100]}-${TWO_DIGIT[c % 100]}`;
+};
+
+const digit = (s: string, i: number): number => {
+  const c = s.charCodeAt(i) - 48;
+  return c >= 0 && c <= 9 ? c : NaN;
+};
+
+/** Epoch day of 'YYYY-MM-DD' (anything after position 10 is ignored); NaN if malformed. */
+export const epochDayOfYmd = (s: string): number => {
+  if (s.length < 10) return NaN;
+  const y = digit(s, 0) * 1000 + digit(s, 1) * 100 + digit(s, 2) * 10 + digit(s, 3);
+  const m = digit(s, 5) * 10 + digit(s, 6);
+  const d = digit(s, 8) * 10 + digit(s, 9);
+  return epochDayOf(y, m, d);
+};
+
+/** y·12 + (m − 1) of 'YYYY-MM-DD' — a month ordinal that orders and subtracts. */
+export const monthOrdinalOfYmd = (s: string): number =>
+  (digit(s, 0) * 1000 + digit(s, 1) * 100 + digit(s, 2) * 10 + digit(s, 3)) * 12 +
+  digit(s, 5) * 10 +
+  digit(s, 6) -
+  1;
+
+/** Epoch day of a `Date`'s LOCAL calendar day. The one bridge from `Date`. */
+export const epochDayOfDate = (d: Date): number =>
+  epochDayOf(d.getFullYear(), d.getMonth() + 1, d.getDate());
+
+let today = { epochDay: 0, validUntilMs: 0 };
+
+/** Today's epoch day. Cached until local midnight: a hot call is one `Date.now()`, no allocation. */
+export const todayEpochDay = (): number => {
+  const now = Date.now();
+  if (now >= today.validUntilMs) {
+    const d = new Date(now);
+    today = {
+      epochDay: epochDayOfDate(d),
+      validUntilMs: new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime(),
+    };
+  }
+  return today.epochDay;
+};

package/src/core/dateKey.ts

@@ -0,0 +1,52 @@
+/**
+ * The one translation between the kit's integer index space and 'YYYY-MM-DD'.
+ *
+ * Every surface addresses a day as `dayIndex`, an offset from `range.start`.
+ * `buildRange` pays for the strings once; after that both directions are O(1)
+ * and allocation-free: `dayIndexOf` is a subtraction, `ymdAt` an array read.
+ */
+
+import { epochDayOfDate, epochDayOfYmd, todayEpochDay, weekdayOf, ymdOfEpochDay } from './civil';
+import type { CalendarRange, DateString } from '../types';
+
+/** Index of `ymd` within `range`. May fall outside `[0, days)`; NaN if malformed. */
+export const dayIndexOf = (range: CalendarRange, ymd: DateString): number =>
+  epochDayOfYmd(ymd) - range.startEpochDay;
+
+/** 'YYYY-MM-DD' at `idx`. Defined for any integer; callers clamp first. */
+export const ymdAt = (range: CalendarRange, idx: number): DateString =>
+  range.ymdByIndex[idx] ?? ymdOfEpochDay(range.startEpochDay + idx);
+
+/** The single gating predicate: an index is selectable iff clamping leaves it alone. */
+export const clampIndex = (range: CalendarRange, idx: number): number =>
+  idx < range.minIndex ? range.minIndex : idx > range.maxIndex ? range.maxIndex : idx;
+
+export const todayIndexOf = (startEpochDay: number, days: number): number => {
+  const i = todayEpochDay() - startEpochDay;
+  return i >= 0 && i < days ? i : -1;
+};
+
+/**
+ * `start` is pushed back to the `firstDay` week boundary and `days` rounded up
+ * to whole weeks, so `floor(dayIndex / 7)` is always a week page.
+ */
+export const buildRange = (minDate: Date, maxDate: Date, firstDay: number = 1): CalendarRange => {
+  const min = epochDayOfDate(minDate);
+  const max = epochDayOfDate(maxDate);
+  const startEpochDay = min - ((weekdayOf(min) - firstDay + 7) % 7);
+  const days = Math.ceil((max - startEpochDay + 1) / 7) * 7;
+
+  const ymdByIndex = new Array<DateString>(days);
+  for (let i = 0; i < days; i += 1) ymdByIndex[i] = ymdOfEpochDay(startEpochDay + i);
+
+  return {
+    start: ymdByIndex[0],
+    startEpochDay,
+    ymdByIndex,
+    days,
+    minIndex: min - startEpochDay,
+    maxIndex: max - startEpochDay,
+    firstDay,
+    todayIndex: todayIndexOf(startEpochDay, days),
+  };
+};

package/src/core/motion.ts

@@ -0,0 +1,51 @@
+/**
+ * The kit's motion inputs and the two accessibility flags it obeys.
+ *
+ * Durations come from `theme/tokens` (`ANIMATION.fast/base/slow`). They are
+ * module constants, not themeable: `KIT_EASING` is captured by worklets at
+ * module scope and so cannot read a React context.
+ */
+
+import { EASING } from '../theme/tokens';
+import { useEffect, useState } from 'react';
+import { AccessibilityInfo, type AccessibilityChangeEventName } from 'react-native';
+import { Easing } from 'react-native-reanimated';
+
+export const KIT_EASING = Easing.bezier(...EASING.bezier);
+
+/** Reanimated treats `duration: 0` as an immediate set, so a snap stays a snap. */
+export const kitDuration = (ms: number, reduced: boolean): number => (reduced ? 0 : ms);
+
+/** A platform that cannot answer gets the default: full motion, visual calendar. */
+const useA11yFlag = (read: () => Promise<boolean>, event: AccessibilityChangeEventName): boolean => {
+  const [on, setOn] = useState(false);
+  useEffect(() => {
+    let alive = true;
+    read()
+      .then((value) => {
+        if (alive) setOn(value);
+      })
+      .catch(() => undefined);
+    const sub = AccessibilityInfo.addEventListener(event, (value) => {
+      if (alive) setOn(Boolean(value));
+    });
+    return () => {
+      alive = false;
+      sub.remove();
+    };
+  }, [read, event]);
+  return on;
+};
+
+const readReduceMotion = () => AccessibilityInfo.isReduceMotionEnabled();
+const readScreenReader = () => AccessibilityInfo.isScreenReaderEnabled();
+
+/** Subscribe ONCE per tree: the provider reads it and publishes it on the context. */
+export const useReduceMotion = (): boolean => useA11yFlag(readReduceMotion, 'reduceMotionChanged');
+
+/**
+ * TalkBack does not see opacity, so the stacked week strip and month grid would
+ * both be read. `ExpandableCalendar` renders a static grid while this is true.
+ */
+export const useScreenReaderEnabled = (): boolean =>
+  useA11yFlag(readScreenReader, 'screenReaderChanged');

package/src/core/worklets.ts

@@ -0,0 +1,37 @@
+/**
+ * Module-scope `'worklet'` helpers. The babel plugin workletizes a top-level
+ * function with the directive unconditionally; inside a hook call it depends on
+ * configuration (`hooks/useChromeScrub.ts:24-39`).
+ */
+
+/**
+ * Largest `i` with `offsets[i] <= y`, or 0. `offsets` is a strictly increasing
+ * prefix-sum table, so the search is exact and allocation-free.
+ */
+export const bsearchLE = (offsets: readonly number[], y: number): number => {
+  'worklet';
+  let lo = 0;
+  let hi = offsets.length - 1;
+  if (hi < 0 || y <= offsets[0]) return 0;
+  if (y >= offsets[hi]) return hi;
+  while (lo < hi) {
+    // Upper mid, so the loop converges on the LAST index satisfying the predicate.
+    const mid = (lo + hi + 1) >> 1;
+    if (offsets[mid] <= y) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo;
+};
+
+export const clampNum = (v: number, lo: number, hi: number): number => {
+  'worklet';
+  return v < lo ? lo : v > hi ? hi : v;
+};
+
+// Without the worklets babel plugin every scroll handler silently runs on the JS
+// thread; the only symptom would be the jank the kit exists to remove.
+if (__DEV__ && (clampNum as unknown as { __workletHash?: unknown }).__workletHash === undefined) {
+  console.error(
+    '[agenda-kit] worklet helpers are not workletized — the worklets babel plugin did not run over this package. Metro must apply babel to node_modules.',
+  );
+}